mcp-go (SDK)

Name: mcp-go (SDK) MCP Server
Author: mark3labs

왜 쓰나요

핵심 기능

stdio + SSE + 스트리머블 HTTP 트랜스포트
Go 제네릭을 사용한 타입 안전 도구 등록
리소스 및 프롬프트 기본 지원
내장 기능 협상
최신 MCP 스펙과 호환

라이브 데모

실제 사용 모습

mcp-go-mark3labs.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-go-mark3labs": {
      "command": "go",
      "args": [
        "install",
        "github.com/mark3labs/mcp-go/cmd/example@latest"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mcp-go-mark3labs": {
      "command": "go",
      "args": [
        "install",
        "github.com/mark3labs/mcp-go/cmd/example@latest"
      ],
      "_inferred": true
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mcp-go-mark3labs": {
      "command": "go",
      "args": [
        "install",
        "github.com/mark3labs/mcp-go/cmd/example@latest"
      ],
      "_inferred": true
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mcp-go-mark3labs": {
      "command": "go",
      "args": [
        "install",
        "github.com/mark3labs/mcp-go/cmd/example@latest"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mcp-go-mark3labs",
      "command": "go",
      "args": [
        "install",
        "github.com/mark3labs/mcp-go/cmd/example@latest"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "mcp-go-mark3labs": {
      "command": {
        "path": "go",
        "args": [
          "install",
          "github.com/mark3labs/mcp-go/cmd/example@latest"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add mcp-go-mark3labs -- go install github.com/mark3labs/mcp-go/cmd/example@latest

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: mcp-go (SDK)

100줄 이하로 회사 API를 위한 내부 MCP 서버 구축

👤 Claude에 내부 도구를 노출하고 싶은 회사의 Go 개발자 ⏱ ~45 min intermediate

언제 쓸까: Go 서비스가 있고 OpenAPI 스키마 없이 Claude가 호출하게 하고 싶을 때.

사전 조건

Go 1.21+ — brew 또는 asdf로 설치

흐름

서버 스캐폴딩

Create a new Go project. Add mcp-go and define one tool: search_orders(customer_id) that calls our internal /v1/orders API.✓ 복사됨

→ main.go ~50줄, 깔끔하게 빌드
mcp-inspector로 테스트

Run the server in stdio mode. Open mcp-inspector and verify the tool shows up.✓ 복사됨

→ 인스펙터에서 도구 호출 가능
Claude에 등록

Add the binary to claude_desktop_config.json. Test from Claude with a real customer ID.✓ 복사됨

→ API에서 라이브 응답

결과: 타입 안전 MCP 도구로 Claude에 노출된 내부 Go API.

함정

장시간 호출이 stdio를 블로킹 — 5초 이상 호출에는 SSE 또는 스트리머블 HTTP 트랜스포트 사용

함께 쓰기: mcp-python-sdk

REST 클라이언트를 중단시키지 않고 기존 REST API를 MCP로 포팅

👤 강제 마이그레이션 없이 MCP를 도입하는 백엔드 팀 ⏱ ~60 min intermediate

언제 쓸까: REST와 MCP가 같은 핸들러에서 공존하길 원할 때.

흐름

핸들러 로직 추출

Take the existing /api/v1/search handler. Extract the core function so both gin and mcp-go can call it.✓ 복사됨

→ 핸들러 분리 — HTTP 핸들러가 순수 함수에 위임
MCP 도구로 래핑

Register the pure func as an mcp-go tool. Map URL params to tool inputs.✓ 복사됨

→ 같은 로직, 두 가지 표면
단일 바이너리, 두 가지 트랜스포트

Build one binary that runs gin on :8080 and the MCP server over stdio when invoked with --mcp.✓ 복사됨

→ 멀티 모드 바이너리

결과: 공유 코어로 하나의 Go 바이너리에서 REST와 MCP를 제공.

SSE로 공개 인터넷에 MCP 서버 호스팅

👤 공개 MCP를 퍼블리싱하는 개발자 (예: git-mcp.io) ⏱ ~90 min advanced

언제 쓸까: 사용자가 로컬에 아무것도 설치하지 않고 MCP를 추가하길 원할 때.

사전 조건

도메인과 TLS — Let's Encrypt가 있는 Caddy/nginx

흐름

SSE 트랜스포트로 전환

Convert the stdio server to SSE. Add CORS for the relevant origins.✓ 복사됨

→ 서버가 /sse 연결 수락
사용자별 인증 추가

Validate Bearer token on each connection; reject unknown.✓ 복사됨

→ 잘못된 token은 401, 유효한 token은 정상
배포 및 테스트

Deploy to fly.io. Add the URL to Claude via mcp-remote.✓ 복사됨

→ 원격 URL을 가리키는 Claude에서 도구 호출 가능

결과: 인증이 있는 공개 인터넷 MCP 서버, 사용자 준비 완료.

함정

로드 밸런서 뒤의 SSE가 긴 연결을 끊음 — LB에서 유휴 타임아웃을 5분 이상으로 설정

조합

다른 MCP와 조합해 10배 효율

mcp-go-mark3labs + mcp-python-sdk

같은 프로젝트에서 두 SDK로 다른 표면

Use mcp-go for the perf-critical core; mcp-python-sdk for the data-science adjacency.✓ 복사됨

mcp-go-mark3labs + mcp-registry

구축한 MCP를 공식 레지스트리에 퍼블리시

Once your mcp-go server works, submit it to the modelcontextprotocol/registry.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출
AddTool	name, description, handler	각 도구에 대해 서버 시작 시
AddResource	uri, name, handler	읽기 가능한 리소스 노출
AddPrompt	name, description, handler	재사용 가능한 프롬프트 노출
ServeStdio	()	로컬 stdio 모드 (가장 일반적)
ServeSSE	addr, opts	네트워크/원격 모드

비용 및 제한

운영 비용

API 쿼터: 해당 없음 — 라이브러리
호출당 토큰: 해당 없음
금액: 무료 (MIT)
팁: 특정 마이너 버전에 고정; API는 2025년에 안정화되었지만 마이너 변경이 발생

보안

권한, 시크릿, 파급범위

자격 증명 저장: 도구 핸들러에 필요한 것

데이터 외부 송신: 핸들러로 제어됨

문제 해결

자주 발생하는 오류와 해결

Claude에서 도구가 보이지 않음

기능이 협상되는지 확인; 도구는 ServeStdio 호출 전에 등록되어야 함

확인: Use mcp-inspector to confirm tool listing

stdio 메시지가 잘못됨

핸들러에서 stdout에 출력하지 마세요 — 그것이 JSON-RPC 채널입니다. 로그는 stderr에.

유휴 시 SSE 끊김

주기적 킵얼라이브 추가; 프록시 타임아웃 설정

대안

mcp-go (SDK) 다른 것과 비교

대안	언제 쓰나	단점/장점
mcp-python-sdk (official)	Python으로 개발할 때	다른 언어; 둘 다 일급
TypeScript SDK (official)	Node/Bun 생태계에 적합할 때	JS 우선; Go보다 성능 헤드룸이 낮음

왜 쓰나요

핵심 기능

라이브 데모

실제 사용 모습

설치

클라이언트 선택

사용 사례

실전 활용법: mcp-go (SDK)

사전 조건

흐름

함정

흐름

사전 조건

흐름

함정

조합

다른 MCP와 조합해 10배 효율

도구

이 MCP가 노출하는 것

비용 및 제한

운영 비용

보안

권한, 시크릿, 파급범위

문제 해결

자주 발생하는 오류와 해결

대안

mcp-go (SDK) 다른 것과 비교

더 보기

리소스