MCP 통합 시스템

Claude Code가 MCP 서버를 발견, 연결, 프록시, 인증하는 방법을 살펴봅니다. MCP 통합은 여러 아키텍처 레이어로 구성되며, 각 레이어가 명확한 책임을 가집니다.

• services/mcp/ — 연결 생명주기 관리, 설정 로드, OAuth 인증 흐름 처리
• tools/MCPTool/ — 원격 MCP 도구 호출을 프록시하는 래퍼 도구. 도구 메타데이터를 딥 클론하여 각 서버별 도구 인스턴스를 생성
• commands/mcp/ — /mcp 슬래시 커맨드 인터페이스. 서버 추가/제거/상태 확인
• components/mcp/ — React 기반 UI 패널. 서버 연결 상태, 도구 목록, 인증 상태를 시각화

MCP는 8가지 전송 유형을 지원하며, 공개(Public), 내부(Internal), 인프로세스(In-process)로 분류됩니다.

공개 전송 (Public)

• stdio — 서브프로세스 spawn 방식. 자식 프로세스의 stdin/stdout으로 JSON-RPC 통신. stderr는 'pipe'로 캡처하며 64MB 하드 캡 적용
• sse — HTTP Server-Sent Events. OAuth 인증 지원. 장기 연결 유지
• http — Streamable HTTP 전송. 요청/응답 기반 통신
• ws — WebSocket 전송. 양방향 실시간 통신

내부 전송 (Internal)

• sse-ide — IDE 확장 전용 SSE. VS Code, JetBrains 등 IDE에서 MCP 서버와 통신
• ws-ide — IDE 전용 WebSocket 전송
• sdk — SDK 프로세스 브릿지. 외부 SDK 프로세스와 통신

인프로세스 전송 (In-process)

• in-process — Chrome MCP 및 Computer Use 전용. 별도 프로세스 없이 같은 Node.js 이벤트 루프에서 실행. queueMicrotask()로 재귀 호출 시 스택 오버플로를 방지

// in-process 전송 — 스택 오버플로 방지
// 동일 이벤트 루프에서 MCP 서버를 실행할 때
// 재귀적 호출 체인이 스택을 초과할 수 있음
queueMicrotask(() => {
  // 다음 마이크로태스크에서 처리하여 스택 깊이 초기화
  handleMessage(message)
})

MCP 서버 설정은 7단계 우선순위 계층으로 조립됩니다. 상위 범위가 하위 범위보다 우선합니다.

1. enterprise (최고 우선순위) — managed-mcp.json. MDM(모바일 디바이스 관리)으로 배포. 엔터프라이즈 IT 관리자가 제어
2. dynamic — CLI 플래그(--mcp-server 등)로 전달된 서버 설정
3. claudeai — Claude.ai 커넥터 API에서 제공하는 서버 구성
4. project — .mcp.json 파일. CWD 및 상위 디렉토리를 순회하며 탐색
5. local — ~/.claude/projects/<hash>/. 프로젝트별 로컬 오버라이드
6. user — ~/.claude/settings.json. 사용자 전역 설정
7. managed (최저 우선순위) — 플러그인이 제공하는 서버 설정

MCP 서버 연결은 8단계를 거칩니다.

1. 설정 조립 — 7단계 계단식에서 서버 설정을 수집하고 병합
2. 배치 연결 — 동시 연결 제한 적용. stdio: 최대 3개 동시, remote(SSE/HTTP/WS): 최대 20개 동시
3. 전송 구성 — 전송 유형에 따라 적절한 클라이언트 전송 인스턴스 생성
4. client.connect() 타임아웃 — 기본 30초 타임아웃. 응답 없으면 연결 실패로 처리
5. 인증 처리 — 401 응답 수신 시 상태를 needs-auth로 전환. McpAuthTool 의사 도구를 모델의 도구 목록에 주입하여 모델이 OAuth 흐름을 시작할 수 있게 함
6. 기능 협상 — 서버가 지원하는 기능(도구, 리소스, 프롬프트, elicitation 등)을 협상
7. 도구/리소스/프롬프트 가져오기 — 협상된 기능에 따라 사용 가능한 도구, 리소스, 프롬프트 메타데이터를 수집
8. 라이브 알림 — ToolListChanged 등 서버 알림을 구독. 연결 끊김 시 지수적 백오프로 재연결 (1초 ~ 30초)

// 배치 연결 — 전송 유형별 동시성 제한
const STDIO_CONCURRENCY = 3   // 서브프로세스 폭주 방지
const REMOTE_CONCURRENCY = 20  // 네트워크 연결은 더 관대

// 재연결 지수적 백오프
const RECONNECT_BASE = 1000   // 1초
const RECONNECT_MAX  = 30000  // 30초 상한

MCPTool은 모든 MCP 서버 도구의 공통 템플릿입니다. 실제 도구 인스턴스는 fetchToolsForClient()가 서버에서 메타데이터를 가져온 후 딥 클론으로 생성합니다.

이름 정규화

MCP 도구 이름은 mcp__<server>__<tool> 형식으로 정규화됩니다. 이를 통해 여러 MCP 서버에서 동일한 이름의 도구가 존재하더라도 충돌을 방지합니다.

// 도구 이름 정규화 예시
// 서버 "github"의 "create_issue" 도구 →
"mcp__github__create_issue"

// 서버 "slack"의 "send_message" 도구 →
"mcp__slack__send_message"

제한 사항

• 도구 설명: 2048자 하드 캡. 초과 시 잘라냄
• 결과 크기: 100KB 초과 시 잘라내기 적용. 대용량 응답이 컨텍스트 윈도우를 압도하는 것을 방지

MCP는 전체 PKCE(Proof Key for Code Exchange) 흐름과 XAA(교차 앱 액세스) 확장을 지원합니다.

McpAuthTool 흐름

1. 원격 MCP 서버가 401 반환
2. 서버 상태가 needs-auth로 전환
3. McpAuthTool 의사 도구가 모델 도구 목록에 주입
4. 모델이 McpAuthTool을 호출하여 OAuth PKCE 흐름 시작
5. 사용자에게 브라우저 인증 URL 제공
6. 인증 완료 후 토큰 저장, 서버 재연결

XAA (교차 앱 액세스)

XAA는 엔터프라이즈 SSO(Single Sign-On) 확장입니다. 기업 환경에서 중앙 인증 서버를 통해 여러 MCP 서버에 대한 액세스를 일괄 관리할 수 있게 합니다.

Elicitation은 MCP 서버가 작업 도중 사용자에게 구조화된 입력을 요청하는 메커니즘입니다.

두 가지 모드

• form 모드 — JSON Schema 기반. 서버가 JSON Schema를 제공하면 클라이언트가 이에 맞는 입력 폼을 렌더링하여 사용자에게 표시
• url 모드 — 2단계 프로세스. 서버가 URL을 제공하고, 사용자가 해당 URL에서 작업을 완료한 후 결과를 반환

여러 설정 범위에 동일한 MCP 서버가 중복 등록될 수 있습니다. MCP 통합은 콘텐츠 기반(이름 기반이 아님) 중복 제거를 수행합니다.

서명 생성 규칙

• stdio 서버: stdio:["cmd","arg1","arg2"] — 명령어와 인수 배열로 서명 생성
• 원격 서버: url:https://example.com/mcp — URL로 서명 생성

// 중복 제거 서명 예시
// stdio 서버: 명령어 + 인수가 동일하면 같은 서버
'stdio:["npx","@modelcontextprotocol/server-github"]'

// 원격 서버: URL이 동일하면 같은 서버
'url:https://slack.mcp.example.com/sse'

추가 규칙

• CCR 프록시 URL 풀기: CCR(Claude Code Remote) 환경에서 프록시 URL을 원본 URL로 풀어서 서명을 생성. 프록시 경유 여부와 관계없이 동일 서버로 인식
• 수동 우선: 동일 서명의 서버가 수동 설정과 플러그인 제공 양쪽에 존재하면 수동 설정이 우선