Ch6. MCP 서버 연동

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

MCP 개념

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

MCP 서버 추가

CLI 마법사

claude mcp add

설정 파일 직접 편집

프로젝트 범위: .mcp.json
사용자 범위: ~/.claude.json

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

OAuth 비DCR 서버 추가 (v2.1.30)

일부 MCP 서버(예: Slack)는 Dynamic Client Registration(DCR)을 지원하지 않을 수 있습니다. 이 경우 claude mcp add에 OAuth 클라이언트 정보를 명시할 수 있습니다.

claude mcp add slack \
  --transport sse \
  --url <MCP_SERVER_SSE_URL> \
  --client-id "$MCP_CLIENT_ID" \
  --client-secret "$MCP_CLIENT_SECRET"

OAuth 메타데이터 URL 지정 (v2.1.69)

oauth.authServerMetadataUrl 옵션으로 MCP 서버의 OAuth 메타데이터 URL을 직접 지정할 수 있습니다. OAuth step-up auth도 지원되며, 디스커버리 결과가 캐싱됩니다. (v2.1.49)

OAuth 에러 처리 개선 (v2.1.74)

OAuth 콜백 포트 충돌 시 명확한 에러 처리
OAuth refresh 토큰 만료 시 재인증 프롬프트 표시

OAuth CIMD 지원 (v2.1.81)

MCP OAuth가 **Client ID Metadata Document(CIMD / SEP-991)**을 지원합니다. CIMD를 통해 클라이언트 등록 없이도 OAuth 인증 흐름을 시작할 수 있습니다. (v2.1.81)

OAuth RFC 9728 지원 (v2.1.85)

MCP OAuth가 RFC 9728 Protected Resource Metadata 디스커버리를 지원합니다. 리소스 서버가 자신의 보호 방식을 표준화된 방법으로 공개하고, 클라이언트가 이를 자동 검색합니다.

관리 명령어

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

/mcp로 상태 확인

/mcp

VS Code에서는 /mcp 명령으로 네이티브 MCP 관리 다이얼로그를 열 수 있습니다 — 서버 활성화/비활성화/재연결/OAuth 관리를 UI에서 직접 수행합니다. (v2.1.70)

claude.ai MCP 커넥터 (v2.1.63)

claude.ai에서 설정한 MCP 서버를 Claude Code에서도 연동할 수 있습니다. 비활성화하려면 환경 변수 ENABLE_CLAUDEAI_MCP_SERVERS=false를 설정합니다.

MCP Elicitation (v2.1.76)

MCP 서버가 작업 도중 사용자에게 구조화된 입력을 요청할 수 있습니다. 예를 들어, DB 서버가 커넥션 정보를 물어보거나, 배포 서버가 환경 선택을 요구하는 식입니다.

MCP 서버가 elicitation 요청을 보내면 대화형 다이얼로그가 표시됩니다
사용자가 응답하면 ElicitationResult가 서버에 전달됩니다
Elicitation과 ElicitationResult 훅 이벤트로 자동화를 연결할 수 있습니다

운영 팁

elicitation은 MCP 서버가 사용자 앞에 있을 때만 유용합니다. CI/헤드리스 환경에서는 사전 설정(환경변수, config)으로 대체하세요.

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

--channels 플래그를 사용하면 MCP 서버가 세션에 메시지를 직접 푸시할 수 있습니다. 기존에는 Claude가 MCP 도구를 호출해야만 서버와 통신할 수 있었지만, Channels를 통해 서버가 능동적으로 알림이나 업데이트를 보낼 수 있습니다. (v2.1.80)

퍼미션 릴레이

채널 서버가 permission capability를 선언하면, 도구 승인 프롬프트를 폰으로 전달할 수 있습니다. 원격지에서 도구 실행을 승인/거부하는 워크플로우가 가능합니다. (v2.1.81)

실전 활용 시나리오

시나리오	MCP 서버	동작
CI 결과 알림	GitHub Actions MCP	빌드/테스트 완료 시 세션에 결과 푸시 → Claude가 실패 원인 분석
Slack 메시지 전달	Slack MCP	특정 채널의 메시지를 세션에 전달 → Claude가 요약/응답 초안 작성
파일 변경 감지	파일 감시 MCP	특정 디렉토리의 파일 변경 시 알림 → Claude가 변경 영향 분석
모니터링 알림	Grafana/PagerDuty MCP	임계치 초과 알림 → Claude가 런북 참조하여 대응 제안
폰 승인	Permission 채널	도구 실행 승인을 폰으로 전달 → 외출 중에도 에이전트 관리

# CI 결과를 세션에 푸시하는 예시 (개념적)
claude --channels \
  --mcp-config .mcp.json \
  -p "이 프로젝트의 테스트를 모니터링하고 실패 시 원인을 분석해줘"

연구 프리뷰

Channels는 현재 연구 프리뷰 단계입니다. API와 동작이 변경될 수 있습니다. Team/Enterprise 플랜에서는 기본 비활성화되며, 관리자가 channelsEnabled와 allowedChannelPlugins로 제어합니다.

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

로컬 .mcp.json 설정과 claude.ai 커넥터에 동일한 서버가 등록된 경우, 로컬 설정이 우선됩니다. 같은 서버가 두 번 로드되어 도구가 중복되는 문제가 해결되었습니다.

MCP 도구 설명 제한 (v2.1.84)

MCP 도구 설명(description)과 서버 지시문(instructions)이 2KB로 제한됩니다. 과도하게 긴 설명이 컨텍스트를 낭비하는 것을 방지합니다.

MCP headersHelper 환경변수 (v2.1.85)

MCP headersHelper 스크립트에서 다음 환경변수를 사용할 수 있습니다:

CLAUDE_CODE_MCP_SERVER_NAME — 서버 이름
CLAUDE_CODE_MCP_SERVER_URL — 서버 URL

서버별로 다른 인증 헤더를 동적으로 생성하는 데 유용합니다.

연결 대기 최적화 (v2.1.89)

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

Tool Search (선택적)

서버 도구가 많으면 Tool Search로 도구 설명을 필요 시점에 로드할 수 있습니다. 원격 MCP 서버는 ENABLE_TOOL_SEARCH=1로 활성화합니다.

도구 출력 제한

MCP 도구 출력은 기본적으로 10,000 토큰 경고, 25,000 토큰 제한이 있습니다. 환경 변수 MAX_MCP_OUTPUT_TOKENS로 상한을 조정할 수 있습니다.

도구 결과가 50K자를 초과하면 디스크에 저장됩니다(기존 100K에서 변경). 이를 통해 컨텍스트 사용량이 절감됩니다. (v2.1.51)

결과 보존 크기 override (v2.1.91)

MCP 서버는 결과에 _meta["anthropic/maxResultSizeChars"]를 붙여 결과 보존 한도를 최대 500K자까지 늘릴 수 있습니다. DB 스키마, 대형 API 스펙처럼 잘리면 안 되는 출력을 전달할 때 유용하지만, 필요한 서버에만 제한적으로 적용하는 편이 좋습니다.

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

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

바이너리 콘텐츠 처리 (v2.1.69)

MCP 도구가 반환하는 바이너리 콘텐츠(PDF, Office 문서, 오디오 등)를 자동으로 디코딩하여 디스크에 저장합니다. 이전에는 바이너리 응답이 제대로 처리되지 않았지만, 이제 Claude가 파일 내용을 활용할 수 있습니다.

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\""
          }
        ]
      }
    ]
  }
}

deny 규칙

deny: ["mcp__servername"] 형태의 퍼미션 규칙으로 특정 MCP 서버의 모든 도구를 차단할 수 있습니다. (v2.1.78 수정)

참고 문서

MCP 개요 및 설정 파일: https://docs.claude.com/ko/docs/claude-code/mcp (한국어)
/mcp 명령: https://code.claude.com/docs/ko/slash-commands (한국어)
MCP 도구 출력 제한/Tool Search: https://docs.claude.com/ko/docs/claude-code/mcp (한국어)
Changelog (MCP OAuth client 옵션): https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md (영어)

MCP 개념

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

MCP 서버 추가

CLI 마법사

claude mcp add

설정 파일 직접 편집

프로젝트 범위: .mcp.json
사용자 범위: ~/.claude.json

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

OAuth 비DCR 서버 추가 (v2.1.30)

일부 MCP 서버(예: Slack)는 Dynamic Client Registration(DCR)을 지원하지 않을 수 있습니다. 이 경우 claude mcp add에 OAuth 클라이언트 정보를 명시할 수 있습니다.

claude mcp add slack \
  --transport sse \
  --url <MCP_SERVER_SSE_URL> \
  --client-id "$MCP_CLIENT_ID" \
  --client-secret "$MCP_CLIENT_SECRET"

OAuth 메타데이터 URL 지정 (v2.1.69)

OAuth 에러 처리 개선 (v2.1.74)

OAuth 콜백 포트 충돌 시 명확한 에러 처리
OAuth refresh 토큰 만료 시 재인증 프롬프트 표시

OAuth CIMD 지원 (v2.1.81)

MCP OAuth가 **Client ID Metadata Document(CIMD / SEP-991)**을 지원합니다. CIMD를 통해 클라이언트 등록 없이도 OAuth 인증 흐름을 시작할 수 있습니다. (v2.1.81)

OAuth RFC 9728 지원 (v2.1.85)

관리 명령어

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

/mcp로 상태 확인

/mcp

claude.ai MCP 커넥터 (v2.1.63)

claude.ai에서 설정한 MCP 서버를 Claude Code에서도 연동할 수 있습니다. 비활성화하려면 환경 변수 ENABLE_CLAUDEAI_MCP_SERVERS=false를 설정합니다.

MCP Elicitation (v2.1.76)

MCP 서버가 elicitation 요청을 보내면 대화형 다이얼로그가 표시됩니다
사용자가 응답하면 ElicitationResult가 서버에 전달됩니다
Elicitation과 ElicitationResult 훅 이벤트로 자동화를 연결할 수 있습니다

운영 팁

elicitation은 MCP 서버가 사용자 앞에 있을 때만 유용합니다. CI/헤드리스 환경에서는 사전 설정(환경변수, config)으로 대체하세요.

시나리오	MCP 서버	동작
CI 결과 알림	GitHub Actions MCP	빌드/테스트 완료 시 세션에 결과 푸시 → Claude가 실패 원인 분석
Slack 메시지 전달	Slack MCP	특정 채널의 메시지를 세션에 전달 → Claude가 요약/응답 초안 작성
파일 변경 감지	파일 감시 MCP	특정 디렉토리의 파일 변경 시 알림 → Claude가 변경 영향 분석
모니터링 알림	Grafana/PagerDuty MCP	임계치 초과 알림 → Claude가 런북 참조하여 대응 제안
폰 승인	Permission 채널	도구 실행 승인을 폰으로 전달 → 외출 중에도 에이전트 관리

# CI 결과를 세션에 푸시하는 예시 (개념적)
claude --channels \
  --mcp-config .mcp.json \
  -p "이 프로젝트의 테스트를 모니터링하고 실패 시 원인을 분석해줘"

연구 프리뷰

CLAUDE_CODE_MCP_SERVER_NAME — 서버 이름
CLAUDE_CODE_MCP_SERVER_URL — 서버 URL

서버별로 다른 인증 헤더를 동적으로 생성하는 데 유용합니다.

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

deny 규칙

deny: ["mcp__servername"] 형태의 퍼미션 규칙으로 특정 MCP 서버의 모든 도구를 차단할 수 있습니다. (v2.1.78 수정)

참고 문서

MCP 개요 및 설정 파일: https://docs.claude.com/ko/docs/claude-code/mcp (한국어)
/mcp 명령: https://code.claude.com/docs/ko/slash-commands (한국어)
MCP 도구 출력 제한/Tool Search: https://docs.claude.com/ko/docs/claude-code/mcp (한국어)
Changelog (MCP OAuth client 옵션): https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md (영어)

Ch6. MCP 서버 연동

목차

Ch6. MCP 서버 연동

목차