Ch6. MCP 서버 연동

v2.1.265~269 연결·권한 수정

legacy HTTP+SSE 전용 서버에 대한 HTTP→SSE fallback, 재개 시 plugin MCP 재연결, 인증 오류에서 환경변수로 해석된 secret 마스킹을 반영합니다. 2.1.268은 symlink의 실제 경로로 접근할 때도 deny/ask가 적용되도록 수정하고, 2.1.269는 tee 대상에도 Edit deny와 쓰기 경계를 적용합니다. gateway 환경의 2.1.265 로그인 회귀는 2.1.266에서, Anthropic 호환 endpoint의 schema HTTP 400은 2.1.268에서 수정됐으므로 오류 원인과 버전을 먼저 대조하세요.

공식 Changelog · 2026-09-12 KST

MCP(Model Context Protocol)는 Claude Code를 외부 도구·데이터베이스·API에 연결하는 표준 프로토콜입니다. GitHub, DB, 사내 도구를 Claude Code에서 그대로 쓸 수 있습니다.

MCP 개념

Claude Code는 MCP 클라이언트로서 여러 MCP 서버에 동시에 연결합니다. 각 서버는 도구(tools), 리소스(resources), 프롬프트(prompts)를 제공합니다.

MCP 서버 추가

claude mcp add는 세 가지 전송 방식(transport)을 지원합니다. 공식 문서는 원격 서버에는 HTTP를 권장하며, SSE 전송은 deprecated되었으니 가능하면 HTTP로 연결하세요.

# HTTP 원격 서버 (권장)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Bearer 토큰 헤더 포함
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

# 로컬 stdio 서버
claude mcp add --transport stdio --env AIRTABLE_API_KEY=KEY airtable \
  -- npx -y airtable-mcp-server

설정 파일 직접 편집과 범위(scope)

MCP 서버는 세 가지 범위(scope)로 저장됩니다. --scope 플래그로 지정합니다.

.mcp.json(project 범위)과 add-json에서 사용하는 JSON 스키마 예시입니다. type은 stdio, http, sse를 받으며, JSON에서는 streamable-http를 http의 별칭으로 인식합니다.

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

project 범위 서버는 보안상 처음 사용할 때 승인 프롬프트가 표시됩니다. 승인 기록을 초기화하려면 claude mcp reset-project-choices를 실행합니다.

환경 변수 확장

.mcp.json에서는 ${VAR}(값 치환)과 ${VAR:-default}(기본값) 구문으로 환경 변수를 확장할 수 있습니다. 확장 가능한 위치는 command, args, env, url, headers이며, 값이 없고 기본값도 없으면 설정 파싱에 실패합니다.

stdio 서버에는 Claude Code가 프로젝트 루트를 CLAUDE_PROJECT_DIR 환경 변수로 주입하므로, 서버 내부에서 프로젝트 상대 경로를 안정적으로 해석할 수 있습니다.

JSON으로 직접 추가 / Claude Desktop 가져오기

# JSON 문자열로 추가
claude mcp add-json weather '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# Claude Desktop 설정 가져오기 (macOS, WSL)
claude mcp add-from-claude-desktop

OAuth 인증

많은 원격 서버가 OAuth 2.0을 요구합니다. 서버가 401 Unauthorized 또는 403 Forbidden을 반환하면 Claude Code가 인증 필요 상태로 표시하고, /mcp에서 브라우저 로그인 흐름을 진행합니다. 토큰은 안전하게 저장되고 자동 갱신됩니다.

최신 CLI는 대화형 /mcp 메뉴 외에도 claude mcp login <server>와 claude mcp logout <server>로 원격 서버 인증을 명시적으로 시작하거나 해제할 수 있습니다. 팀 bootstrap script에는 list/get 검증과 login/logout 안내를 분리해 두면 운영자가 브라우저 인증 단계를 놓치지 않습니다.

고정 콜백 포트와 사전 등록 자격증명 (비DCR 서버)

일부 MCP 서버는 Dynamic Client Registration(DCR)을 지원하지 않습니다("does not support dynamic client registration" 오류). 이럴 때는 사전 등록한 OAuth 자격증명을 넘깁니다. --client-secret 플래그는 값을 인자로 받지 않고 마스킹된 입력 프롬프트를 띄우며, CI에서는 MCP_CLIENT_SECRET 환경 변수로 대신합니다.

# 고정 콜백 포트 + 사전 등록 client-id (secret은 마스킹 입력)
claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

# CI에서 환경 변수로 secret 주입
MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

--callback-port는 사전 등록된 http://localhost:PORT/callback 형식의 리다이렉트 URI에 맞춰 콜백 포트를 고정합니다(DCR과 함께 단독 사용 가능). 이 플래그들은 HTTP/SSE 전송에만 적용되며 stdio 서버에는 영향이 없습니다.

OAuth 메타데이터 디스커버리 override

oauth.authServerMetadataUrl을 .mcp.json의 oauth 객체에 설정하면 기본 디스커버리 체인을 우회해 특정 인증 서버 메타데이터 URL을 직접 지정할 수 있습니다(v2.1.64 이상). 기본 디스커버리는 먼저 RFC 9728 Protected Resource Metadata(/.well-known/oauth-protected-resource)를 확인한 뒤, RFC 8414 Authorization Server Metadata(/.well-known/oauth-authorization-server)로 폴백합니다.

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

또한 CIMD(Client ID Metadata Document)를 사용하는 서버는 별도 클라이언트 등록 없이도 자동으로 디스커버리됩니다.

OAuth scope 제한

oauth.scopes에 공백으로 구분한 단일 문자열을 지정하면 인증 흐름에서 요청할 scope를 고정합니다. 보안팀이 승인한 범위로 제한할 때 쓰며, 이 값은 authServerMetadataUrl이나 서버가 디스커버리한 scope보다 우선합니다.

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": { "scopes": "channels:read chat:write search:read" }
    }
  }
}

동적 인증 헤더 (headersHelper)

OAuth 외 인증 방식(Kerberos, 단기 토큰, 사내 SSO 등)을 쓰는 서버는 headersHelper로 연결 시점에 헤더를 만듭니다. 명령은 stdout에 JSON 객체(문자열 키-값)를 출력해야 하며, 셸에서 10초 타임아웃으로 실행됩니다. 연결마다 새로 실행하고 캐싱은 없습니다.

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

headersHelper 실행 시 다음 환경 변수를 사용할 수 있습니다:

• CLAUDE_CODE_MCP_SERVER_NAME — 서버 이름
• CLAUDE_CODE_MCP_SERVER_URL — 서버 URL

서버마다 다른 인증 헤더를 헬퍼 스크립트 하나로 동적으로 만들 때 쓰면 좋습니다.

관리 명령어

claude mcp list
claude mcp get github
claude mcp remove github
claude mcp serve

claude mcp list/get은 승인 대기 중인 project 범위 서버를 ⏸ Pending approval, 거부된 서버를 ✗ Rejected로 표시합니다. claude mcp serve는 Claude Code 자체를 stdio MCP 서버로 띄워 다른 애플리케이션(예: Claude Desktop)이 Claude의 도구에 접근하게 합니다.

/mcp로 상태 확인

/mcp

/mcp 패널은 연결된 서버마다 도구 개수를 보여주고, tools capability를 광고하면서도 도구가 0개인 서버를 따로 표시합니다. OAuth 인증이 필요한 원격 서버 인증도 /mcp에서 합니다. 인증 해제는 /mcp 메뉴의 "Clear authentication"으로 합니다.

v2.1.181~v2.1.197 릴리스에서는 MCP 상태가 실제보다 나쁘게 보이는 표시 문제와 repo self-approved .mcp.json 서버 보안 경계가 일부 수정되었습니다. 그래도 장애 대응에서는 /mcp 표시만 보지 말고 claude mcp get <server>, 서버 로그, HTTP 상태, OAuth 토큰 상태를 함께 확인하세요.

자동 재연결과 동적 도구 갱신

HTTP/SSE 서버가 세션 도중 끊기면 지수 백오프로 자동 재연결합니다(최대 5회, 1초에서 시작해 2배씩 증가). 초기 연결도 5xx·연결 거부·타임아웃 같은 일시적 오류에 한해 최대 3회 재시도합니다(v2.1.121). 인증·not-found 오류는 설정 변경이 필요하므로 재시도하지 않습니다. stdio 서버는 로컬 프로세스라 자동 재연결되지 않습니다.

MCP list_changed 알림을 지원하므로, 서버가 도구·프롬프트·리소스 목록을 바꾸면 재연결 없이 자동으로 갱신됩니다.

플러그인 제공 MCP 서버

플러그인은 MCP 서버를 번들로 포함할 수 있습니다. 플러그인 루트의 .mcp.json 또는 plugin.json 인라인으로 정의하며, 플러그인 활성화 시 자동 시작됩니다. ${CLAUDE_PLUGIN_ROOT}(번들 파일), ${CLAUDE_PLUGIN_DATA}(영속 상태), ${CLAUDE_PROJECT_DIR}(프로젝트 루트) 변수를 사용할 수 있습니다.

claude.ai MCP 커넥터

claude.ai 계정으로 로그인한 경우 claude.ai에서 추가한 MCP 서버를 Claude Code에서 자동으로 사용할 수 있습니다. 단, 활성 인증 방식이 claude.ai 구독일 때만 로드되며 ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, apiKeyHelper, Bedrock/Vertex 등이 활성화되면 로드되지 않습니다. 비활성화하려면 환경 변수 ENABLE_CLAUDEAI_MCP_SERVERS=false를 설정합니다.

범위 우선순위와 중복 제거

같은 서버가 여러 곳에 정의되면 Claude Code는 가장 높은 우선순위 정의 하나만 사용하며, 필드는 병합하지 않습니다. 우선순위는 다음과 같습니다.

1. local 범위
2. project 범위
3. user 범위
4. 플러그인 제공 서버
5. claude.ai 커넥터

세 범위는 이름으로, 플러그인·커넥터는 **엔드포인트(URL/command)**로 중복을 판별합니다. 즉 로컬 .mcp.json과 claude.ai 커넥터가 같은 URL을 가리키면 로컬 설정이 우선하고, claude.ai 커넥터는 /mcp에서 hidden으로 표시됩니다.

MCP Elicitation

MCP 서버는 작업 도중 사용자에게 구조화된 입력을 요청할 수 있습니다(elicitation). 별도 설정 없이 서버가 요청하면 대화형 다이얼로그가 자동으로 뜨고, 응답이 서버로 전달됩니다. 모드는 두 가지입니다.

• Form 모드: 서버가 정의한 폼 필드(예: 사용자명·비밀번호)를 채워 제출
• URL 모드: 인증·승인을 위한 브라우저 URL을 열고, 완료 후 CLI에서 확인

다이얼로그 없이 자동 응답하려면 Elicitation 훅을 사용합니다.

MCP Channels (연구 프리뷰, v2.1.80)

채널(Channel)은 세션에 메시지를 직접 푸시하는 MCP 서버입니다. 기존에는 Claude가 도구를 호출해야만 서버와 통신했지만, 채널을 쓰면 CI 결과·모니터링 알림·채팅 메시지 같은 외부 이벤트가 실행 중인 세션으로 들어와 Claude가 즉시 반응합니다.

현재 채널은 플러그인 형태로 설치하고, 시작할 때 --channels 플래그에 플러그인을 명시해 옵트인합니다. 연구 프리뷰에는 Telegram, Discord, iMessage, fakechat(로컬 데모)이 들어 있습니다. 서버는 claude/channel capability를 선언해야 하고, .mcp.json에 두는 것만으로는 부족합니다. 반드시 --channels에 지정해야 푸시할 수 있습니다.

# 플러그인 설치 후 채널을 옵트인하여 시작
claude --channels plugin:fakechat@claude-plugins-official

# 여러 플러그인을 공백으로 구분해 전달 가능
claude --channels plugin:telegram@claude-plugins-official

퍼미션 릴레이

채널 서버가 permission relay capability를 선언하면, 도구 승인 프롬프트를 폰 등 원격으로 전달해 외출 중에도 도구 실행을 승인하거나 거부할 수 있습니다. 채널의 sender allowlist에 등록된 사람만 응답하므로, 그 권한을 믿을 수 있는 발신자만 허용하세요. 무인 실행에는 신뢰하는 환경에서만 --dangerously-skip-permissions를 사용합니다.

실전 활용 시나리오

MCP 서버 중복 제거 (v2.1.84)

로컬 설정과 claude.ai 커넥터에 같은 엔드포인트의 서버가 등록되면 로컬 설정이 우선합니다. 같은 서버가 두 번 로드되어 도구가 중복되던 문제도 이제 해결됐습니다. /mcp는 중복으로 가려진 커넥터를 hidden으로 표시하고 중복 제거 힌트를 보여줍니다.

도구 검색(Tool Search)

서버 도구가 많으면 Tool Search로 도구 정의를 필요한 시점에 로드해 컨텍스트 사용을 줄입니다. 현재는 기본 활성화라서, 세션 시작 때는 도구 이름만 로드하고 Claude가 필요할 때 검색 도구로 관련 도구를 찾습니다. 사용자가 보기엔 기존과 똑같이 동작합니다.

ENABLE_TOOL_SEARCH 환경 변수로 동작을 제어합니다.

Tool Search는 tool_reference 블록을 지원하는 모델(Sonnet 4 / Opus 4 이상)이 필요하며, Haiku는 지원하지 않습니다. Vertex AI에서는 기본 비활성화되며 Sonnet 4.5 / Opus 4.5 이상에서만 지원됩니다. ToolSearch 도구 자체를 끄려면 권한 deny 규칙 "deny": ["ToolSearch"]를 사용합니다.

서버를 지연에서 제외 (alwaysLoad)

특정 서버의 도구가 항상 보여야 한다면 그 서버 설정에 "alwaysLoad": true를 추가합니다. 그러면 해당 서버의 모든 도구가 ENABLE_TOOL_SEARCH 설정과 무관하게 세션 시작 때 컨텍스트에 로드됩니다(v2.1.121 이상). 이때는 서버 연결까지 시작이 블로킹되며 표준 5초 연결 타임아웃이 상한입니다. 개별 도구는 _meta에 "anthropic/alwaysLoad": true로 지정할 수 있습니다.

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

연결 대기 최적화

MCP 시작은 기본적으로 논블로킹이며, 서버는 백그라운드에서 연결됩니다. 다만 어떤 요청이 아직 연결 중인 서버의 도구를 필요로 하면 Claude가 그 서버를 기다립니다(Tool Search 활성 시 ToolSearch 호출 안에서, 비활성 시 WaitForMcpServers 도구로 대기).

헤드리스 -p 실행에서는 MCP_CONNECTION_NONBLOCKING=true로 MCP 연결 대기를 완전히 건너뛸 수 있습니다. --mcp-config로 지정한 서버 연결은 느린 서버 하나 때문에 전체가 묶이지 않도록 서버당 5초로 상한을 둡니다.

타임아웃 관련 환경 변수/필드:

• MCP_TIMEOUT — 서버 시작 타임아웃(예: MCP_TIMEOUT=10000은 10초)
• MCP_TOOL_TIMEOUT / 서버별 .mcp.json의 timeout(ms) — 도구 호출 단위 하드 타임아웃. 서버별 timeout이 환경 변수보다 우선하며, 1000 미만 값은 1초로 올림

도구 출력 제한

MCP 도구 출력에는 기본적으로 10,000 토큰 경고, 25,000 토큰 제한이 걸립니다. 환경 변수 MAX_MCP_OUTPUT_TOKENS로 상한을 조정합니다(예: MAX_MCP_OUTPUT_TOKENS=50000). 이 변수는 자체 한도를 선언하지 않은 도구에만 적용됩니다.

결과 보존 크기 override

MCP 서버는 도구의 tools/list 항목에 _meta["anthropic/maxResultSizeChars"]를 붙여 결과 보존 한도를 최대 500K자까지 늘릴 수 있습니다. DB 스키마나 대형 파일 트리처럼 잘리면 안 되는 출력을 전달할 때 쓰면 좋습니다. 이 값은 텍스트 콘텐츠에 한해 MAX_MCP_OUTPUT_TOKENS와 따로 적용되지만, 이미지 데이터는 여전히 토큰 제한을 받습니다. 어노테이션이 없으면 기본 임계치를 넘는 결과는 디스크에 보존하고 대화에는 파일 참조로 대신합니다.

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": { "anthropic/maxResultSizeChars": 200000 }
}

MCP 도구 호출 표시 개선 (v2.1.81)

MCP read/search 도구 호출이 1줄로 접혀 표시되며, Ctrl+O로 확장할 수 있습니다. 대화 흐름이 깔끔해집니다.

바이너리/이미지 콘텐츠 처리

MCP 도구가 반환하는 바이너리 콘텐츠(PDF, Office 문서, 오디오 등)는 자동으로 디코딩해 디스크에 저장하므로, Claude가 파일 내용을 활용할 수 있습니다. 지원하지 않는 MIME 타입(예: SVG) 이미지도 대화를 깨뜨리지 않고 디스크에 저장한 뒤 결과에서 참조합니다.

MCP 리소스와 프롬프트

리소스 (@ 멘션)

MCP 서버가 노출한 리소스는 파일처럼 @로 참조합니다. 프롬프트에서 @를 입력하면 연결된 서버의 리소스가 자동완성에 나타나며, @server:protocol://resource/path 형식으로 지정합니다.

@github:issue://123 이슈를 분석하고 수정안을 제안해줘
@postgres:schema://users 와 @docs:file://database/user-model 를 비교해줘

프롬프트 (슬래시 명령)

MCP 서버가 노출한 프롬프트는 /mcp__servername__promptname 형식의 슬래시 명령으로 사용합니다. 인자는 명령 뒤에 공백으로 구분해 전달합니다.

/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug in login flow" high

hooks·권한과 MCP 연동

MCP 도구는 mcp__<서버명>__<도구명> 패턴으로 이름이 지정됩니다. hooks의 matcher나 권한 규칙에서 이 패턴을 활용할 수 있습니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "mcp__postgres__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"MCP tool used\" >> \"$CLAUDE_PROJECT_DIR/.claude/mcp-log.txt\""
          }
        ]
      }
    ]
  }
}

참고 문서

• MCP 개요 및 설정 파일: https://code.claude.com/docs/en/mcp
• Channels(이벤트 푸시): https://code.claude.com/docs/en/channels
• 관리형 MCP 설정: https://code.claude.com/docs/en/managed-mcp
• 환경 변수: https://code.claude.com/docs/en/env-vars
• Changelog: https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md