MCP로 Claude Code를 도구에 연결하기

Model Context Protocol(MCP)로 Claude Code를 수백 개의 외부 도구·데이터 소스에 연결하는 방법을 다루는 참조 문서예요. MCP는 AI-도구 통합을 위한 오픈소스 표준이고, MCP 서버가 Claude Code에 도구·데이터베이스·API에 대한 접근을 제공해요. 이슈 트래커나 모니터링 대시보드 같은 다른 도구의 데이터를 채팅에 복사해 붙여넣는 상황에서 서버를 연결하면, Claude가 붙여넣은 내용 대신 그 시스템을 직접 읽고 동작하게 돼요.

출처: 공식문서

본문

MCP로 할 수 있는 일

MCP 서버를 연결하면 Claude Code에 이렇게 시킬 수 있어요.

이슈 트래커에서 기능 구현: "JIRA 이슈 ENG-4521에 설명된 기능을 추가하고 GitHub에 PR을 만들어 줘."
모니터링 데이터 분석: "Sentry와 Statsig를 확인해서 ENG-4521의 사용량을 봐 줘."
데이터베이스 쿼리: "PostgreSQL에서 ENG-4521 기능을 쓴 10명의 랜덤 사용자 이메일을 찾아 줘."
디자인 통합: "Slack에 올라온 새 Figma 디자인에 맞춰 표준 이메일 템플릿을 갱신해 줘."
워크플로 자동화: "이 10명 사용자에게 새 기능에 대한 피드백 세션을 제안하는 Gmail 초안을 만들어 줘."
외부 이벤트에 반응: MCP 서버는 채널로도 동작해 세션에 메시지를 밀어 넣을 수 있어요. 그래서 자리를 비웠을 때 Telegram 메시지, Discord 채팅, 웹훅 이벤트에 Claude가 반응하게 할 수 있어요.

MCP 서버 찾기와 구축

리뷰된 커넥터는 Anthropic Directory에서 찾아볼 수 있어요. 디렉토리 커넥터는 Claude Code와 같은 MCP 인프라를 쓰므로, 거기 있는 어떤 원격 서버든 claude mcp add로 추가할 수 있어요.

경고: 서버를 연결하기 전에 신뢰하는지 확인하세요. 외부 콘텐츠를 가져오는 서버는 프롬프트 인젝션 위험에 노출될 수 있어요.

자체 서버를 구축하려면 프로토콜 기초는 MCP 서버 가이드, 인증·테스트·디렉토리 제출은 Claude 커넥터 구축 문서를 보세요. 공식 mcp-server-dev 플러그인으로 Claude가 서버를 스캐폴드하게 할 수도 있어요.

플러그인 설치

Claude Code 세션에서 실행:

/plugin install mcp-server-dev@claude-plugins-official

설치가 실패하면 보고된 메시지를 맞춰요. Marketplace "claude-plugins-official" not found면 /plugin marketplace add anthropics/claude-plugins-official로 마켓플레이스를 추가 후 재시도. 플러그인 이름을 확인하세요. 설치 요약에 Run /reload-plugins to activate.가 있으면 Claude Code가 그 리로드를 대신 실행해요. 리로드가 다음 메시지에서 대화를 다시 읽겠다고 경고하면 /reload-plugins --force를 실행하세요.

빌드 스킬 실행

/mcp-server-dev:build-mcp-server

Claude가 사용 사례를 묻고 원격 HTTP 또는 로컬 stdio 서버를 스캐폴드해요.

MCP 서버 설치

MCP 서버는 필요에 따라 여러 방식으로 설정할 수 있어요.

옵션 1: 원격 HTTP 서버 추가

HTTP 서버는 원격 MCP 서버 연결에 권장되는 옵션이에요. 클라우드 기반 서비스에서 가장 널리 지원되는 트랜스포트죠.

# 기본 문법
claude mcp add --transport http <name> <url>

# 실제 예: Notion 연결
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Bearer 토큰 예
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer ***"

.mcp.json, ~/.claude.json, claude mcp add-json으로 JSON 설정 시 type 필드는 streamable-http를 http의 별칭으로 받아요. MCP 스펙이 이 트랜스포트를 streamable-http라고 부르므로 서버 문서에서 복사한 설정이 수정 없이 동작해요.

url은 있는데 type이 없는 JSON 항목은 설정 오류예요. Claude Code가 type 없는 항목을 stdio 서버로 읽기 때문이에요. 그 서버는 건너뛰고 MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry라고 보고해요. v2.1.202 이전에는 command: expected string, received undefined로 보고했어요.

--output-format stream-json 실행에서는 건너뛴 --mcp-config 항목을 system/init 이벤트의 mcp_server_errors 필드로도 보고해, 스크립트가 서버가 로드되지 않았음을 감지할 수 있어요. Claude Code v2.1.219 이상 필요.

옵션 2: 원격 SSE 서버 추가

경고: SSE(Server-Sent Events) 트랜스포트는 deprecated예요. 가능하면 HTTP 서버를 쓰세요.

일부 서비스는 아직 SSE 엔드포인트만 노출해요. HTTP 서버처럼 같은 claude mcp add --transport http <name> <url> 명령으로 추가하면 돼요. Claude Code가 먼저 HTTP 트랜스포트를 시도하고, 서버가 받지 않으면 SSE로 전환해요. 자동 전환은 v2.1.265 이상 필요.

이전 버전이거나 SSE로 직접 연결하려면 --transport sse를 주세요.

# 기본 문법
claude mcp add --transport sse <name> <url>

# 실제 예: Asana 연결
claude mcp add --transport sse asana https://mcp.asana.com/sse

# 인증 헤더 예
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: ***"

옵션 3: 로컬 stdio 서버 추가

stdio 서버는 머신에서 로컬 프로세스로 실행돼요. 직접 시스템 접근이나 커스텀 스크립트가 필요한 도구에 이상적이에요.

Claude Code는 생성된 서버 환경의 CLAUDE_PROJECT_DIR을 프로젝트 루트로 설정해, 서버가 작업 디렉토리에 의존하지 않고 프로젝트 상대 경로를 해석하게 해요. 이는 훅이 받는 CLAUDE_PROJECT_DIR 변수와 같은 디렉토리예요. 서버 프로세스 안에서 읽는데, Node는 process.env.CLAUDE_PROJECT_DIR, Python은 os.environ["CLAUDE_PROJECT_DIR"]이에요.

CLAUDE_PROJECT_DIR은 안정적인 프로젝트 루트라 세션 중간에 작업 디렉토리를 추가·제거해도 변하지 않아요. 자신의 파일시스템 접근을 허용 디렉토리 집합으로 제한하는 서버는 MCP roots/list 요청을 구현해야 해요. Claude Code는 roots/list에 세션 실행 디렉토리와 --add-dir, /add-dir, additionalDirectories 설정으로 부여한 모든 추가 작업 디렉토리로 답해요. 그 집합이 바뀌면 notifications/roots/list_changed를 보내요. v2.1.203 이전에는 roots/list가 실행 디렉토리만 반환하고 notifications/roots/list_changed를 보내지 않았어요.

이 변수는 서버 환경에서 설정되지 Claude Code 환경에서 설정되는 게 아니므로, 프로젝트 스코프 .mcp.json 항목이나 ~/.claude.json의 local·user 스코프 서버의 command·args에서 ${VAR}로 참조하려면 ${CLAUDE_PROJECT_DIR:-.} 같은 기본값이 필요해요. 플러그인 제공 MCP 설정은 ${CLAUDE_PROJECT_DIR}을 직접 치환해 기본값이 필요 없어요.

# 기본 문법
claude mcp add [options] <name> -- <command> [args...]

# 실제 예: Airtable 서버 추가
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

중요: 서버 인자와 -- 구분하기 stdio 서버에서 --(더블 대시)는 --transport, --env, --scope 같은 Claude 자체 옵션과 서버를 실행하는 명령·인자를 구분해요. -- 뒤의 모든 것은 서버에 그대로 전달돼요.

claude mcp add --transport stdio myserver -- npx server → npx server 실행

claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080 → KEY=value를 환경에 넣고 python server.py --port 8080 실행 --가 없으면 Claude Code가 위 --port 같은 서버 플래그를 자신의 옵션으로 파싱하려 해요. --env는 여러 KEY=value 쌍을 받아요. 서버 이름이 --env 바로 뒤에 오면 CLI가 이름을 또 하나의 쌍으로 읽고 거부하므로, 위 예시처럼 --env와 서버 이름 사이에 다른 옵션을 하나 이상 두세요.

옵션 4: 원격 WebSocket 서버 추가

WebSocket 서버는 지속 양방향 연결을 유지해, Claude에게 요청 없이 이벤트를 밀어 주는 원격 MCP 서버에 어울려요. 서버가 요청에만 응답한다면 HTTP를 쓰세요. HTTP는 OAuth와 claude mcp add --transport 플래그를 지원하지만 WebSocket은 둘 다 지원하지 않아요.

WebSocket 서버는 .mcp.json이나 claude mcp add-json으로 설정해요.

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

type: "ws" 항목은 http와 같은 url, headers, headersHelper, timeout, alwaysLoad 필드를 받아요. 인증은 헤더 전용이라 정적 토큰을 headers에 넘기거나 연결 시 headersHelper로 생성해요. claude mcp add --transport 플래그는 ws를 받지 않아요.

다른 클라이언트용 설정 지시에서 서버 추가하기

MCP 서버는 Claude Code 전용이 아니므로, 서버 설정 지시가 Claude Desktop, Cursor 같은 다른 MCP 클라이언트용으로 쓰여 claude mcp add 명령이 없을 수 있어요. 그 지시에서 이 셋 중 하나를 찾아보세요: URL(https://mcp.example.com/mcp 형태 → 원격), 실행 명령(npx -y @example/mcp-server 형태 → 로컬 실행), mcpServers JSON 블록(다른 클라이언트 설정 파일용). 각 셋은 여기 네 옵션이 받는 입력 중 하나예요.

URL: --transport http로 추가. wss://면 옵션 4. 인증 헤더는 --header로.
npx·uvx·바이너리 명령: 로컬 stdio 프로세스. 전체 명령을 -- 뒤에 두고(-y 같은 플래그를 Claude Code가 자신의 옵션으로 읽지 않게), 지시가 요구하는 환경변수는 서버 이름 뒤·-- 앞의 --env로 전달:
```
claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server
```
mcpServers JSON 블록: claude mcp add-json에 mcpServers 안쪽 객체를 넘겨요. 두 항목은 먼저 고쳐야 해요. type 없는 url은 "type": "http"·"sse"·"ws" 중 하나를 추가(없으면 stdio로 읽혀 실패), 그리고 문자·숫자·하이픈·언더스코어 밖의 문자를 가진 키는 서버 이름을 그 문자가 없는 것으로 바꾸세요(아니면 그 키가 서버 이름이 돼요).

예를 들어 이 블록:

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

이 명령이 돼요:

claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

팀과 공유하려면 --scope project를 주거나 프로젝트 루트 .mcp.json의 mcpServers 아래 항목을 추가하고 커밋하세요.

각 claude mcp add·add-json 명령은 Added ... 줄을 출력해요. 연결 확인은 claude mcp get <name>, .mcp.json 서버는 승인 단계가 붙어요.

서버 관리

# 모든 설정 서버 나열
claude mcp list

# 특정 서버 상세
claude mcp get notion

# 서버 제거
claude mcp remove notion

# (Claude Code 안에서) 서버 상태 확인
/mcp

원격 서버를 제거하면 Claude Code가 그 서버에 저장한 OAuth 토큰과 클라이언트 등록도 삭제해요.

서버 상태

claude mcp add는 성공을 Added ... 줄로 확인해 주고, 이는 설정이 기록됐다는 뜻이에요. claude mcp list는 각 서버 옆에 ✔ Connected, ! Needs authentication, ✘ Failed to connect 같은 상태를 보여줘요. 실패 상태는 Claude Code가 그 서버에 연결할 수 없다는 뜻이지, 나열 명령이 실패했다는 뜻이 아니에요.

이 목록의 상태는 연결 시도가 아니라 설정 결정을 보고해요. ⏸ Pending approval (run claude to approve)는 아직 승인하지 않은 .mcp.json의 프로젝트 스코프 서버, ✘ Rejected (see disabledMcpjsonServers in settings)는 disabledMcpjsonServers 항목이 거부한 서버, ⊘ Disabled for this project (re-enable via /mcp)는 프로젝트의 disabledMcpServers가 이름을 거는 서버예요. v2.1.238 이전에는 두 명령이 비활성 서버에 연결해 헬스 체크하고 결과를 보고했어요.

WebSocket 서버는 claude mcp list 출력에 안 나타나요. claude mcp get <name>이나 /mcp 패널로 확인하세요.

프로젝트 서버 승인과 워크스페이스 신뢰

v2.1.196부터 claude mcp list와 claude mcp get은 설정 파일이 리포지토리에 커밋되지 않은 경우에만 .mcp.json 승인을 읽어요. 그 저장소에 .claude/settings.json에 커밋된 enableAllProjectMcpServers·enabledMcpjsonServers는 신뢰하지 않는 폴더에서 무시되고, 서버는 연결·헬스 체크 대신 ⏸ Pending approval로 남아요. 신뢰하지 않는 폴더에서도 적용되는 승인 소스: 사용자 ~/.claude/settings.json, 관리 설정, --settings로 전달한 설정. .claude/settings.local.json은 신뢰 폴더에서만 git으로 추적 여부를 확인하고 적용해요.

서버 상태 상세

/mcp와 /plugin 관리자에서 이전에 쓴 원격 HTTP·SSE 서버는 cached 2h ago · connects on first use · 5 tools 같은 cached 상태를 보여줄 수 있어요. Claude Code가 시작 시 연결하는 대신 이전 세션에 저장된 디스커버리 캐시에서 도구 목록을 로드했고, Claude가 그 서버 도구를 처음 호출할 때 연결해요. v2.1.221 이상 필요. 캐시는 기본적으로 꺼져 있고, MCP_DISCOVERY_CACHE=1로 켜거나 0으로 유지돼요(v2.1.238 이전엔 기본 켜짐). 서버 메뉴의 Reconnect는 지금 연결하고 캐시 항목 유지, Clear authentication은 인증 취소와 항목 폐기. 캐시 폐기 후엔 캐시가 아니라 서버에서 도구 목록을 가져와요.

✘ Failed to connect 상태면 claude mcp list가 상태 줄에 실패 상세(HTPP 상태/에러 코드 + 서버가 반환한 에러 텍스트)를 붙이고, claude mcp get <name>은 Issue: 줄에 보여줘요. Claude Code는 이 상세에서 자격 증명 같은 텍스트를 가리고, 확장된 서버 URL(비밀을 담을 수 있음)은 절대 포함하지 않아요. ✘ Connection error 상태에는 상세를 붙이지 않아요(그곳에 출력할 예외 텍스트가 그 URL을 포함할 수 있으므로). v2.1.219 이전에는 상태 코드·서버 에러 텍스트 없이 맨 상태만 보였어요.

/mcp에서 인증을 완료했는데도 HTTP 상태나 트랜스포트 에러 코드로 연결이 실패하면, 시도 후 출력 메시지에 그 코드와 서버 URL의 origin(스킴+호스트, URL이 포트를 제시하면 포트, 예: https://mcp.example.com)을 추가해요. 경로와 쿼리는 그 메시지에 절대 안 나타나요.

설정 url이 빈 원격 서버는 /mcp, claude mcp list, /plugin 관리자에서 not configured로 보이고, Claude Code는 연결을 시도하지 않아요. 플러그인이 나중에 설정할 커넥터용 placeholder 항목을 포함할 수 있어서예요. v2.1.208 이전에는 빈 url을 설정 문제로 보고하고 재연결을 제안했어요.

설정 경고

숨은 공백: MCP 설정 값에 앞/뒤 공백이 있으면(토큰을 개행과 함께 붙여넣는 경우 흔함) 경고해요. command, url, 각 args, env·headers 아래의 값·키 이름을 검사하고, claude mcp list·/mcp에서 값은 반향하지 않고 필드만 짚어요, 예: Leading or trailing whitespace in: headers.Authorization. 공백을 자르지 않고 정확히 쓴 값대로 써요.
둘 이상 스코프의 같은 이름: 같은 서버 이름을 둘 이상 스코프에 다른 엔드포인트로 정의하면 충돌 경고를 보여줘요. OAuth 로그인은 엔드포인트별 저장이라 각 프로젝트에서 따로 로그인해야 해요. 원하는 엔드포인트를 유지하고 claude mcp remove <name> --scope <scope>로 나머지를 지우세요. 경고에서는 API 키 같은 해석된 값을 절대 안 보여줘요.
예약 이름: workspace, claude-in-chrome, computer-use, Claude Preview, Claude Browser를 포함해 빌트인 서버 이름을 예약해요. 설정이 예약 이름을 정의하면 로드 시 건너뛰고 이름 변경 경고를 보여요. claude mcp add는 예약 이름을 오류로 거부해요.
환경변수 누락: 서버 설정의 ${VAR} 참조가 변수가 설정되지 않고 :-default도 없으면 경고하고, ${VAR} 텍스트를 펼치지 않은 채로 서버를 로드해요. 변수를 설정하거나 ${VAR:-default} 폴백을 추가하세요.

도구 가용성

/mcp 패널은 각 연결 서버 옆에 도구 수를 보여주고, tools 능력을 광고하면서 도구를 노출하지 않는 서버를 표시해요. 요청이 아직 백그라운드 연결 중인 서버의 도구를 필요로 하면 Claude는 그 서버를 기다려요. 기본(tool search 포함)이면 대기는 ToolSearch 호출 안에서 일어나요. tool search 없으면 WaitForMcpServers 도구를 써요(커스텀 ANTHROPIC_BASE_URL, ENABLE_TOOL_SEARCH=false, Claude 4.5 세대 이전 모델 등). Azure 호스팅 Microsoft Foundry 배포에서는 서버가 연결을 마치면 그 도구가 Claude의 다음 요청에서 사용 가능해져요.

서버를 제거하지 않고 비활성화

/mcp 패널에서 서버를 꺼서 설정을 잃지 않고 연결을 막아요. Claude Code는 여전히 /mcp에 비활성으로 표시해요. 토글 시 프로젝트별로 ~/.claude.json의 두 목록 중 하나에 기록해요. disabledMcpServers(사용자 구성 서버, 플러그인 서버, 관리 설정이 제공하는 서버, claude.ai 커넥터, 기본 켜짐인 빌트인 서버의 옵트아웃 목록)와 enabledMcpServers(기본 꺼짐인 computer-use 같은 빌트인 서버의 옵트인 목록). 각 서버에 대해 정확히 한 목록만 참고해 어느 것도 다른 것을 오버라이드하지 않아요.

MCP 클라이언트 런타임

Claude Code는 두 클라이언트 런타임 중 하나로 MCP 서버에 연결해요. v1 런타임은 MCP TypeScript SDK 1.x, v2 런타임은 프로토콜 개정 2026-07-28을 추가하는 MCP TypeScript SDK 2.0 기반이에요. Claude Code v2.1.232 이상에서 v2 런타임을 써요. 시작마다 런타임을 골라 종료까지 유지해요. Amazon Bedrock·Claude Platform on AWS·Google Cloud's Agent Platform·Microsoft Foundry, Claude apps gateway 로그인, feature-flag fetching off에서는 v1을 써요. v2에서 Claude Code는 HTTP·claude.ai 커넥터 서버에 새 개정 지원 여부를 물어 지원하는 쪽과 쓰고, stdio 서버는 MCP_PROTOCOL_NEGOTIATION을 auto로 설정해야만 물어요. 새 개정의 서버에서 list_changed 알림을 열어 둔 스트림으로 받고, 그 개정에 연결되는 채널 서버는 채널 메시지를 못 실으므로 등록하지 않아요.

런타임을 직접 고르려면 MCP_SDK_GENERATION을 v1·v2로, 프로토콜 협상 여부는 MCP_PROTOCOL_NEGOTIATION을 auto·legacy로 설정하세요.

동적 도구 갱신

Claude Code는 MCP list_changed 알림을 지원해, 서버가 연결을 끊고 다시 붙지 않고도 사용 가능한 도구·프롬프트·리소스를 동적으로 갱신하게 해요. 서버가 list_changed를 보내면 해당 서버의 능력을 자동으로 새로 고쳐요. 갱신 요청이 실패하면 이전에 발견한 도구·프롬프트·리소스를 이후 갱신이 성공할 때까지 유지해요. v2.1.214 이전에는 갱신 중 일시 오류가 그 목록을 빈 목록으로 바꿨어요. v2 런타임에서 스트림이 닫히면: 10초 내 재닫힘이면 최대 3회 재개 후 그 연결에서 멈추고, 10초 이상 열렸다 닫히면(서버리스 호스트에 흔함) 한 시간에 5회 재개 후 다음까지 약 6시간 기다려요.

자동 재연결

Claude Code는 세션 중간에 끊긴 원격 서버를 재연결하고, 일시 오류 후 HTTP·SSE 서버의 첫 연결을 재시도해요. stdio 서버는 로컬 프로세스라 자동 재연결되지 않아요.

끊긴 원격 서버는 지수 백오프(최대 5회, 1초 지연부터 두 배씩)로 재연결해요. 인터랙티브 세션이면 /mcp가 재연결 동안 pending으로 보여주고, 5회 실패 후 실패 또는 재인증 필요로 표시해요. claude -p·Agent SDK 세션도 같은 일정으로 재연결돼요. HTTP·SSE 서버의 첫 연결이 5xx, 연결 거부, 타임아웃 같은 일시 오류로 실패하면 최대 3회 재시도해요. WebSocket 첫 연결, 인증·not-found 오류는 재시도하지 않아요(headersHelper가 유일한 Authorization 소스면 재시도). 연결 후 tools/list·prompts/list·resources/list 같은 발견 요청은 짧은 백오프로 최대 3회 재시도하지만 인증 오류·4xx·타임아웃은 재시도하지 않아요.

연결 실패를 Claude에게 알릴지 여부는 기본 켜진 tool search에 달려요. tool search면 어느 서버가 어떤 연결 오류로 실패했는지 알려주고, 없으면 보고하지 않아요.

채널로 메시지 밀어 넣기

MCP 서버는 세션에 직접 메시지를 밀어 넣어 Claude가 CI 결과·모니터링 알림·채팅 메시지 같은 외부 이벤트에 반응하게 할 수 있어요. 이렇게 하려면 서버가 claude/channel 능력을 선언하고 시작 시 --channels 플래그로 옵트인해야 해요. 공식 지원 채널은 Channels, 자체 구축은 Channels reference를 보세요.

팁:

-s/--scope 플래그로 설정 저장 위치 지정: local(기본, 현재 프로젝트에서만), project(.mcp.json으로 프로젝트 내 공유), user(모든 프로젝트에서만).

-e/--env 플래그로 환경변수 설정(예: -e KEY=value).

--transport·--header는 -t·-H 단축형 지원.

MCP_TIMEOUT 환경변수로 시작 타임아웃 설정(예: MCP_TIMEOUT=10000 claude는 10초).

서버별 도구 실행 타임아웃은 그 서버 .mcp.json 항목에 ms 단위 timeout 필드 추가, 예: "timeout": 600000(10분). 그 서버에만 MCP_TOOL_TIMEOUT을 오버라이드해요.

MCP 도구 출력이 10,000 토큰을 넘으면 경고, 기본 제한 25,000 토큰. MAX_MCP_OUTPUT_TOKENS로 상향(경고 임계값은 고정).

OAuth 2.0 인증이 필요한 원격 서버 인증은 /mcp 사용.

서버별 timeout은 도구 호출당 하드 wall-clock 제한이고, 서버의 진행 알림이 연장하지 않아요. 1000 미만은 무시되고 MCP_TOOL_TIMEOUT(미설정 시 기본 약 28시간)으로 넘어가요. HTTP·SSE·claude.ai 커넥터 서버에는 두 번째 요청당 타이머가 있어 60초, 해당 서버의 도구 타임아웃, MCP_TIMEOUT 중 최댓값으로 설정해요. 서버별 timeout이 1000 이상이면 아래 idle 타임아웃의 최소값으로도 동작해요(v2.1.203 이상). 응답 없고 진행 알림도 없는 도구 호출은 idle 기간이 지나면 wall-clock 제한을 기다리는 대신 오류로 중단돼요. idle 타임아웃은 v2.1.187 이상, HTTP·SSE·WebSocket·claude.ai 커넥터는 기본 5분, stdio는 30분. CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT(ms)로 변경하거나 0으로 비활성.

긴 도구 호출의 자동 백그라운드화

메인 대화의 MCP 도구 호출이 2분 넘게 돌면 세션을 막는 대신 백그라운드 태스크로 이동해요. Claude는 태스크 ID를 즉시 받고 계속 작업하고, 결과는 태스크 알림으로 도착해요(v2.1.212 이상). /tasks에 나타나고 종료하면 없어져요. 서브에이전트 호출, IDE 서버 호출, 비인터랙티브 모드 호출(CLAUDE_AUTO_BACKGROUND_TASKS=1 아니면)은 백그라운드로 안 옮겨져요. 열린 elicitation 대화를 기다리는 호출도 백그라운드화하지 않아요. CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS로 임계값 변경, 0으로 끄기, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1로 모든 백그라운드 태스크 해제.

플러그인 제공 MCP 서버

Plugins이 플러그인 활성화 시 도구·통합을 제공하는 MCP 서버를 번들할 수 있어요. 플러그인은 .mcp.json(플러그인 루트) 또는 plugin.json 인라인으로 MCP 서버를 정의해요. 플러그인 활성화 시 서버가 자동 시작되고, /mcp 명령이 아니라 플러그인 설치·제거로 추가·제거돼요. 경로 placeholder: ${CLAUDE_PLUGIN_ROOT}은 플러그인 설치 디렉토리, ${CLAUDE_PLUGIN_DATA}은 영구 상태, ${CLAUDE_PROJECT_DIR}은 안정 프로젝트 루트로 치환돼요. stdio 서버는 command·args·env, http/sse/ws는 url·headers·headersHelper에 적용돼요.

플러그인 번들 MCP 서버의 도구는 호출 가능한 이름에 플러그인 이름과 서버 키를 포함해요. 전체 형식은 mcp__plugin_<plugin-name>_<server-name>__<tool-name>이고, A-Z·a-z·0-9·_·- 밖의 문자는 _로 치환돼요. 예: my-plugin 플러그인의 database-tools 서버의 query 도구는 mcp__plugin_my-plugin_database-tools__query. 허용 규칙, 스킬 allowed-tools, 서브에이전트 tools 필드, 훅 매처에서 이 전체 이름을 써요. 서버 자체는 plugin:<plugin-name>:<server-name>(예: plugin:my-plugin:database-tools)으로 등록돼요.

MCP 설치 스코프

스코프	로드 위치	팀 공유	저장 위치
Local	현재 프로젝트만	아니요	`~/.claude.json`
Project	현재 프로젝트만	예, 버전 관리로	프로젝트 루트 `.mcp.json`
User	모든 프로젝트	아니요	`~/.claude.json`

관리자는 관리 설정으로 모든 사용자에게 서버를 배포·제공할 수도 있어요.

Local 스코프: 기본값. 추가한 프로젝트에서만 로드되고 사용자에게 비공개. ~/.claude.json의 그 프로젝트 경로 아래 저장. 개인 개발 서버, 실험 설정, 버전 관리에 넣기 싫은 자격 증명이 있는 서버에 쓰세요. MCP "local scope"는 일반 로컬 설정과 달라요. MCP local 스코프 서버는 ~/.claude.json(홈)에, 일반 로컬 설정은 .claude/settings.local.json(프로젝트)에 있어요.

# local 스코프 서버 추가(기본)
claude mcp add --transport http stripe https://mcp.stripe.com

# local 스코프 명시
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

/path/to/your/project에서 실행하면 ~/.claude.json의 그 프로젝트 항목 아래 {"projects": {"/path/to/your/project": {"mcpServers": {"stripe": {"type":"http","url":"https://mcp.stripe.com"}}}}}가 기록돼요.

Project 스코프: 프로젝트 루트 .mcp.json에 저장해 팀 협업을 가능하게 해요. 커밋하면 팀원 모두가 같은 MCP 도구를 받아요.

claude mcp add --transport http shared-server --scope project https://example.com/mcp

결과 .mcp.json:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

보안상 인터랙티브 세션에서 .mcp.json의 프로젝트 스코프 서버를 쓰기 전 승인을 요구해요. 승인 선택을 초기화하려면 claude mcp reset-project-choices. claude -p·Agent SDK·클라우드 세션에서는 그 프롬프트를 못 보여주니 물어보지 않고 로드해요. disabledMcpjsonServers에 넣거나, --setting-sources를 쓰거나, --strict-mcp-config로 시작해 막을 수 있어요.

User 스코프: ~/.claude.json에 저장되고 모든 프로젝트에 걸쳐 접근 가능, 사용자 계정에 비공개. 개인 유틸리티 서버, 개발 도구, 여러 프로젝트에서 자주 쓰는 서비스에 좋아요.

claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

스코프 계층과 우선순위: 같은 서버가 둘 이상 장소에 정의되면 최고 우선순위 소스의 정의로 한 번 연결돼요. 1. Local, 2. Project, 3. User, 4. 플러그인 제공 서버, 5. claude.ai 커넥터. 세 스코프는 이름으로 중복을 매칭하고, 플러그인·커넥터는 엔드포인트로 매칭해요. 조직이 managedMcpServers 관리 설정으로 제공하는 서버는 전부 위에 있어요(v2.1.259 이상).

.mcp.json의 환경변수 확장: ${VAR}는 환경변수 VAR로, ${VAR:-default}는 설정 시 VAR, 아니면 default로 확장돼요. command, args, env, url(HTTP), headers(HTTP 인증)에서 확장 가능해요.

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

참조한 변수가 미설정·기본값 없음이어도 설정은 로드되고, claude mcp list에 누락 변수 경고가 나와요.

실용 예제

GitHub 연결 (코드 리뷰): GitHub 원격 MCP 서버는 헤더로 전달하는 GitHub 개인 액세스 토큰으로 인증해요. GitHub 토큰 설정에서 fine-grained 토큰을 생성하고:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer ***"

claude mcp add는 자격 검증 없이 설정을 저장하므로 placeholder 값이 받아들여지지만 나중에 연결이 실패해요. /mcp에서 connected인지 확인하세요. 잘못된 자격은 failed로 보이고 실패 상세에 401 같은 HTTP 상태가 포함돼요. 그다음 "Review PR #456 and suggest improvements", "Create a new issue for the bug we just found", "Show me all open PRs assigned to me" 같은 요청으로 GitHub와 작업해요.

PostgreSQL 쿼리: DBHub(@bytebase/dbhub 패키지)는 --dsn으로 넘긴 연결 문자열로 Claude를 관계형 DB에 연결하는 MCP 서버예요. 연결 문자열에 읽기 전용 DB 사용자를 써서 Claude가 실행하는 쿼리가 데이터를 수정하지 못하게 하세요:

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:***@prod.db.com:5432/analytics"

/mcp에서 db가 connected인지 확인 후 "What's our total revenue this month?", "Show me the schema for the orders table", "Find customers who haven't made a purchase in 90 days" 같은 자연어로 쿼리해요.

원격 MCP 서버 인증

많은 클라우드 MCP 서버가 인증을 요구해요. Claude Code는 OAuth 2.0을 지원해요. 서버가 401 Unauthorized·403 Forbidden으로 응답하면 네팅 인증 필요로 표시해요. 이미 로그인한 OAuth 서버의 요청이 401을 반환하면 저장 토큰을 갱신하고 재연결·재시도하며, 재시도도 실패해야만 인증 필요로 표시해요. 갱신 토큰이 거부되면 /mcp를 가리키는 알림을 즉시 보여요. 스타트업 알림도 있어 하나 이상 서버가 인증을 필요로 할 때 /mcp를 열지 않아도 알 수 있어요(v2.1.193 이상).

비인터랙티브 모드엔 /mcp 패널이 없어 OAuth 흐름을 직접 못 돌려요. v2.1.196부터 tool search 켜진 claude -p·Agent SDK 실행 중 인증이 필요한 서버가 있으면 Claude가 그 서버 도구가 인증 전까지 사용 불가함을 알려줘요. 인터랙티브 세션에서 /mcp나 claude mcp login <name>으로 로그인하세요.

명령줄에서 인증: v2.1.186부터 claude mcp login <name>이 셸에서 직접 OAuth 흐름을 돌려 /mcp 패널을 열 필요가 없어요. claude mcp logout <name>으로 자격을 지워요. v2.1.191부터 로컬 브라우저가 없는 경우(SSH 세션, 디스플레이 없는 Linux) 인증 URL을 출력하고, 로컬 기기에서 연 뒤 브라우저 주소창의 전체 redirect URL을 프롬프트에 붙여 넣어요. ssh -t로 붙여넣을 인터랙티브 터미널이 필요해요. --no-browser로 브라우저가 감지돼도 URL 프롬프트를 강제해요.

고정 OAuth 콜백 포트: 일부 서버는 미리 등록된 redirect URI를 요구해요. 기본적으로 Claude Code는 랜덤 가용 포트를 골라요. --callback-port로 http://localhost:PORT/callback 형태의 미리 등록된 redirect URI와 맞추세요.

claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

사전 구성 OAuth 자격 증명: 일부 서버는 Dynamic Client Registration을 지원하지 않아요. "Incompatible auth server: does not support dynamic client registration" 오류가 나면 사전 구성 자격 증명 필요해요. CI인 --client-id로 앱 client ID, --client-secret은 마스킹 입력으로 프롬프트돼요.

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

CI 형태로 MCP_CLIENT_SECRET=your-secret을 환경변수로 설정해 인터랙티브 프롬프트를 건너뛸 수 있어요. v2.1.229에서는 http://127.0.0.1:PORT/callback을 보냈고 정확 일치 redirect URI를 거부당했지만, v2.1.231에서 localhost 형태를 복원했어요.

OAuth 메타데이터 발견 오버라이드: .mcp.json의 oauth 객체에 authServerMetadataUrl을 설정해서 특정 메타데이터 URL로 발견 사슬을 우회할 수 있어요. 기본은 RFC 9728 Protected Resource Metadata(/.well-known/oauth-protected-resource), 폴백은 RFC 8414(/.well-known/oauth-authorization-server). URL은 https://여야 해요.

OAuth 스코프 제한: oauth.scopes를 단일 공백 구분 문자열(RFC 6749 §3.3 scope 형식)로 설정해서 요청 스코프를 고정해요.

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

oauth.scopes가 authServerMetadataUrl과 서버의 발견 스코프보다 우선해요. 인증 서버가 scopes_supported에 offline_access를 광고하면 고정 스코프에 추가해 새 브라우저 로그인 없이 토큰을 갱신하게 해요. 도구 호출에 403 insufficient_scope가 나오면 같은 고정 스코프로 재인증해요.

커스텀 인증용 동적 헤더: OAuth 외 인증(Kerberos, 단기 토큰, 내부 SSO)을 쓰면 headersHelper로 연결 시 요청 헤더를 생성해요. Claude Code가 명령을 실행하고 출력을 연결 헤더에 병합해요.

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

인라인도 가능. 요구사항: 명령이 stdout으로 string key-value 쌍의 JSON 객체를 써야 하고, Claude Code가 셸에서 실행하며 10초 후 포기. 동적 헤더는 같은 이름의 정적 headers를 오버라이드해요. 도구 호출이 401·403을 반환하면 같은 규칙으로 헬퍼를 재실행하고 새 헤더로 재연결·재시도해요. 헬퍼 실행 시 환경변수: CLAUDE_CODE_MCP_SERVER_NAME(서버 이름), CLAUDE_CODE_MCP_SERVER_URL(서버 URL), CLAUDE_PLUGIN_ROOT(플러그인이 제공할 때만).

헬퍼가 실행되는 위치: headersHelper 명령의 작업 디렉토리는 서버를 선언한 설정에서 결정돼요. 플러그인 서버는 플러그인 루트(v2.1.195 이상), 프로젝트 .mcp.json·local 스코프 서버는 선언한 프로젝트 디렉토리, SDK mcpServers·setMcpServers()·--mcp-config 서버는 세션의 primary 작업 디렉토리, user 스코프·관리 MCP·claude.ai 커넥터·프로젝트 밖 에이전트 파일은 설정 디렉토리(~/.claude, CLAUDE_CONFIG_DIR 설정 시).

헬퍼가 읽는 변수: 리포지토리·플러그인이 제공하는 headersHelper는 사용자가 작성하지 않은 명령이므로, Claude Code는 ANTHROPIC_API_KEY 같은 자격 변수 없이 실행해요. 프로젝트 .mcp.json·플러그인·프로젝트·--add-dir의 에이전트 파일 인라인 서버에서는 제거하고, user·local 스코프·관리 MCP·claude.ai 커넥터·SDK·--mcp-config 서버·~/.claude/agents/·관리 설정·--agents 에이전트 파일에서는 제거하지 않아요. Git의 GIT_CONFIG_KEY_<n> 외에, 이름에 TOKEN·SECRET·PASSWORD·KEY·AUTH를 (대소문자 무관) 담은 모든 자격 변수를 제거해요. 헬퍼가 여기 해당하면 스크립트가 파일이나 자격 저장소에서 자격을 읽게 하세요.

헬퍼 실행 전 폴더 신뢰: headersHelper는 임의 셸 명령으로 실행돼요. 프로젝트 .mcp.json·local 스코프 서버는 서버가 선언된 프로젝트 디렉토리의 신뢰 대화를 받아들인 후에만 실행돼요. 대화 없이 신뢰하려면 ~/.claude.json의 projects["<path>"].hasTrustDialogAccepted를 true로 설정.

JSON 설정에서 MCP 서버 추가

# 기본 문법
claude mcp add-json <name> '<json>'

# HTTP 서버 예
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# stdio 서버 예
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

claude mcp get weather-api로 추가 확인. 셸에서 JSON을 제대로 이스케이프하고, MCP 서버 설정 스키마를 준수해야 해요.

Claude Desktop에서 MCP 서버 가져오기

claude mcp add-from-claude-desktop로 Claude Desktop에 설정한 MCP 서버를 가져와요. 인터랙티브 대화로 가져올 서버를 정하고, claude mcp list로 확인해요. claude mcp 명령으로 추가한 서버 이름은 문자·숫자·하이픈·언더스코어만 가능한데, Claude Desktop은 그 제한을 안 두므로 공백 같은 다른 문자를 가진 이름은 가져올 수 없어요(v2.1.205 이전엔 첫 잘못된 이름이 가져오기를 멈추게 했어요). macOS와 WSL에서만 동작. 같은 이름 서버가 있으면 숫자 접미사(server_1)가 붙어요.

claude.ai에서 MCP 서버 사용

claude.ai 계정으로 로그인했다면 claude.ai에서 추가한 MCP 서버(connectors)가 자동으로 Claude Code에서 사용 가능해요. claude.ai/customize/connectors에서 서버 추가(Team·Enterprise는 관리자만). 인증을 완료하고 /mcp에서 관리해요. claude.ai 커넥터는 활성 인증 방식이 claude.ai 구독 로그인일 때만 가져와요. ANTHROPIC_API_KEY·ANTHROPIC_AUTH_TOKEN·apiKeyHelper·서드파티 공급자·ANTHROPIC_PROFILE·CLAUDE_CODE_OAUTH_TOKEN이 활성이면 로드되지 않아요. /mcp에 안 보이면 /status로 인증 방식을 확인하세요.

조직이 claude.ai에서 인증을 관리하면 Claude Code는 커넥터를 /mcp·/plugin에서 managed로 표시해요. claude.ai에서 추가한 서버(예: Slack 커넥터)를 차단하려면 deniedMcpServers에 이름·URL 패턴으로 추가해요. Microsoft 365, Gmail, Google Calendar 같은 일부 Anthropic 호스팅 커넥터는 로컬 OAuth를 지원하지 않아서(업스트림 IdP가 claude.ai가 등록한 redirect URL만 받으므로) claude.ai/customize/connectors로 연결해야 해요.

커넥터가 Claude Code에 도달하는 방법: 터미널·VS Code·JetBrains·Agent SDK 세션은 Claude Code가 claude.ai에서 직접 가져와요. 클라우드 세션은 원격 호스트가 넘겨주고, 데스크톱 앱 local·SSH 세션은 앱이 in-process로 전달해요. disableClaudeAiConnectors·ENABLE_CLAUDEAI_MCP_SERVERS·allowAllClaudeAiMcps는 첫 행(Claude Code가 직접 가져오는 커넥터)에만 작용해요.

조직의 커넥터 도구 제어: 조직이 claude.ai 커넥터에 도구별 컨트롤을 설정할 수 있어요. ask 도구는 매 호출 프롬프트(acceptEdits·auto·bypassPermissions 포함, 기억 옵션 없음), blocked 도구는 Claude가 보기 전에 필터링돼요. 데스크톱 앱 local·SSH 세션에서는 앱이 전달 전에 blocked 도구를 보류해요.

claude.ai 커넥터 비활성화: disableClaudeAiConnectors를 true로(어느 스코프든) 설정하면 Claude Code가 직접 가져오는 커넥터를 꺼요. any-source-true 의미론이라 어느 스코프의 true든 우선하고, 프로젝트 레벨 false가 재활성화하지 못해요. --mcp-config로 명시 전달한 서버는 영향 없음. ENABLE_CLAUDEAI_MCP_SERVERS=false claude도 같은 효과.

Claude Code를 MCP 서버로 사용

# Claude를 stdio MCP 서버로 시작
claude mcp serve

명령은 시작 시 아무것도 출력하지 않아요. stdio MCP 서버는 stdin/stdout으로 통신하므로 조용히 블록된 터미널은 서버가 돌며 클라이언트 연결을 기다린다는 뜻이에요. Claude Desktop의 claude_desktop_config.json에:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

command 필드는 Claude Code 실행 파일을 가리켜야 해요. claude가 PATH에 없으면 전체 경로(which claude로 확인)를 명시하세요. 올바른 경로 없이는 spawn claude ENOENT 같은 오류가 나요.

MCP 출력 제한과 경고

출력 경고 임계값: MCP 도구 출력이 10,000 토큰을 넘으면 경고 표시.
구성 가능한 제한: MAX_MCP_OUTPUT_TOKENS 환경변수로 최대 MCP 출력 토큰 조정.
기본 제한: 25,000 토큰.
경계: 환경변수는 자체 제한을 선언하지 않은 도구에 적용돼요. anthropic/maxResultSizeChars를 설정한 도구는 텍스트 콘텐츠에 그 값을 쓰고, 이미지 데이터 반환 도구는 여전히 MAX_MCP_OUTPUT_TOKENS를 따르고, 한도를 넘는 결과는 파일로 저장 후 대화에서 파일 경로를 이름 짓는 메시지로 대체돼요(Claude는 필요할 때 파일을 읽어요). 파일은 세션 tool-results 디렉토리(~/.claude/projects/)에 있어요.

export MAX_MCP_OUTPUT_TOKENS=50000
claude

특정 도구 제한 올리기: MCP 서버를 구축 중이라면 도구의 tools/list 응답 항목에서 _meta["anthropic/maxResultSizeChars"]를 설정해 기본 persist-to-disk 임계값보다 큰 결과를 개별 도구가 반환하게 할 수 있어요. Claude Code는 그 도구의 임계값을 주석 값(최대 상한 500,000자)으로 올려요. DB 스키마·전체 파일 트리처럼 본질적으로 크고 필요한 출력을 반환하는 도구에 유용해요.

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

루트 레벨 컴비네이터가 있는 도구 입력 스키마

일부 MCP 서버는 anyOf·oneOf·allOf를 스키마 최상위에 둔 JSON Schema 유니온으로 도구 입력 스키마를 선언해요. Claude API는 그 키워드를 스키마 루트에서 받지 않아요(properties 안에 중첩된 컴비네이터는 그대로 보내요). 루트 컴비네이터가 있는 도구는 사용 가능하게 유지돼요. API로 보내기 전 Claude Code가 스키마를 단일 객체로 평탄화하고 도구 설명 앞에 어떤 파라미터 그룹이 함께 속하는지 알려주는 문장을 붙여요. allOf는 모든 분기 속성을 병합하고 각 분기의 required가 적용, anyOf·oneOf는 모든 분기 속성을 병합하되 각 분기의 required를 스키마가 강제하는 대신 도구 설명에 서술해요. 서버는 Claude가 고른 인자를 받으므로 서버 쪽 검증을 유지하세요.

잘못된 입력 스키마를 가진 도구

Claude API는 요청의 모든 도구 입력 스키마를 검사하고 하나라도 실패하면 전체 요청을 거부(400)해요. Claude Code는 서버 도구를 로드할 때 API 체크 두 가지를 스스로 실행하고 실패할 도구를 제외해 나머지 도구가 계속 동작하게 해요: ① 최상위 속성 이름은 1~64자, ASCII 문자·숫자·_·.·-만, ② 스키마가 JSON Schema draft 2020-12 meta-schema에 유효. $schema 미선언 또는 2020-12 선언 스키마에 적용, 다른 방언 선언 시 속성 이름 체크만 적용. 제외 시 이유를 서버 로그에 기록하고 Claude에게 알려줘요. v2.1.216부터.

특정 도구에 승인 요구

MCP 서버에서 _meta["anthropic/requiresUserInteraction"]를 true로 설정하면 도구를 매 호출 명시 승인으로 표시할 수 있어요(반드시 JSON boolean true, 다른 값은 무시). Claude Code는 acceptEdits·auto·bypassPermissions에서도 그 도구 권한 프롬프트를 매 호출 보여주고 "다시 묻지 않기" 옵션이 없어요. 일치하는 allow rule도 프롬프트를 건너뛰지 못해요. v2.1.199 이상 필요. Remote Control·Agent SDK 앱 같은 곳에서는 원탭 승인을 보류하고 전체 권한 프롬프트를 보여줘요.

{
  "name": "grant_access",
  "description": "Requests access to a protected resource",
  "_meta": {
    "anthropic/requiresUserInteraction": true
  }
}

MCP elicitation 요청에 응답

MCP 서버가 작업 중간에 구조화된 입력을 요청할 수 있어요(elicitation). 서버가 혼자 얻을 수 없는 정보가 필요하면 Claude Code가 인터랙티브 대화를 보여주고 응답을 서버에 전달해요. 설정은 필요 없어요. 서버는 두 방식으로 요청해요. 폼 모드(서버가 정의한 폼 필드 대화)와 URL 모드(인증·승인용 브라우저 URL, 완료 후 CLI에서 확인). URL 모드에서 URL을 명령줄 인자로 넘기고 길이 상한이 있어요. 상한을 넘으면 거절만 가능해요. %·& 같은 이스케이프 문자가 상한에 4배로 카운트돼요(자기 문자 + 이스케이프 3개). 대화 없이 자동 응답하려면 Elicitation 훅을 쓰세요.

MCP 리소스 사용

MCP 서버는 파일처럼 @ 맨션으로 참조할 수 있는 리소스를 노출해요. 프롬프트에 @를 입력하면 연결된 모든 서버의 리소스를 볼 수 있어요. @server:protocol://resource/path 형식으로 참조해요.

Can you analyze @github:issue://123 and suggest a fix?
Please review the API documentation at @docs:file://api/authentication
Compare @postgres:schema://users with @docs:file://database/user-model

리소스는 참조 시 자동으로 가져와 첨부로 포함되고, 경로는 @ 맨션 자동완성에서 퍼지 검색 가능해요. 서버가 지원하면 목록·읽기 도구도 자동 제공돼요.

MCP 툴 서치로 확장

툴 서치는 Claude가 필요할 때까지 도구 정의를 지연시켜 MCP 컨텍스트 사용을 낮게 유지해요. 시작 시 도구 이름과 서버 지시만 로드되므로 MCP 서버를 추가해도 컨텍스트 윈도우 영향이 최소예요. 서버별 고정 도구 상한은 없고, 실질 한계는 컨텍스트 윈도우 예산이에요. Azure 호스팅 Microsoft Foundry 배포는 서버 쪽에서 거부하므로 지원되지 않고, Claude Code가 그 배포에서 도구를 사전 로드해요.

MCP 서버 작성자를 위해: 서버 지시 필드가 툴 서치에서 더 유용해져요. 도구가 다루는 작업 카테고리, 언제 검색해야 하는지, 핵심 능력을 설명하는 명확하고 서술적인 지시를 추가하세요. 도구 설명·서버 지시는 각각 2KB로 잘려요.

툴 서치 구성: 기본 켜짐. ANTHROPIC_BASE_URL이 비(非)퍼스트파티 호스트를 가리키면(대부분 프록시가 tool_reference 블록을 안 넘기므로) 비활성돼요. ENABLE_TOOL_SEARCH로 명시 오버라이드 가능. CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS 설정은 툴 서치를 끄고 자신이 ENABLE_TOOL_SEARCH로 오버라이드할 수 없어요. 툴 서치는 tool_reference 블록을 지원하는 모델(Claude Sonnet 4.5, Haiku 4.5, Opus 4.5 및 이후)이 필요해요. Google Cloud's Agent Platform에서는 Claude 4.5 세대 이후면 기본 켜짐, 이전 모델은 사전 로드.

값	동작
(미설정)	모든 MCP 도구 지연·온디맨드 로드. 일부 경우 사전 로드로 폴백
`true`	모든 MCP 도구 지연, 일부 배포 예외. 프록시로 beta 헤더 전송
`auto`	정의가 컨텍스트 윈도우 10% 미만이면 사전 로드, 10% 도달 시 모두 지연
`auto:N`	커스텀 퍼센트 임계값 모드, `N`은 0-100. 예: `auto:5`
`false`	모든 MCP 도구 사전 로드, 지연 없음

# 커스텀 5% 임계값
ENABLE_TOOL_SEARCH=auto:5 claude

# 툴 서치 완전 비활성
ENABLE_TOOL_SEARCH=false claude

settings.json env 필드에서도 설정 가능. ToolSearch 도구만 별도로 비활성하려면 permissions.deny에 ["ToolSearch"].

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

지연 면제 서버: 서버 도구가 항상 보이게 하려면 설정에서 alwaysLoad: true로 설정해요. 그 서버의 모든 도구가 ENABLE_TOOL_SEARCH와 무관하게 시작 시 컨텍스트에 로드돼요. alwaysLoad는 모든 서버 유형에서 사용 가능하고, 도구의 _meta에 "anthropic/alwaysLoad": true로 개별 도구도 항상 로드 표시할 수 있어요. alwaysLoad: true는 첫 프롬프트에 반드시 있어야 하므로 시작이 서버 도구를 (표준 5초 연결 타임아웃 상한으로) 기다리게 해요. 유효한 cached 항목이 있는 원격 서버는 캐시에서 공급해 시작을 잡지 않아요.

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

MCP 프롬프트를 명령으로 사용

MCP 서버는 Claude Code에서 명령으로 사용 가능해지는 프롬프트를 노출해요. /를 입력하면 MCP 서버의 프롬프트를 포함한 명령을 볼 수 있어요. Claude Code는 각 MCP 프롬프트를 /servername:promptname (MCP)로 나열하고 /mcp__servername__promptname으로도 실행돼요.

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue login-bug high

인자는 공백으로 구분해 전달하고, 각 인자는 단일 토큰이에요. /mcp__servername__promptname 형식에서 서버 이름의 A-Z·a-z·0-9·_·- 밖의 문자는 _로 치환돼요.

관리형 MCP 설정

조직이 어떤 MCP 서버에 사용자가 연결할 수 있는지 중앙 통제하려면 Managed MCP configuration을 보세요. managed-mcp.json으로 고정 서버 집합 배포, managedMcpServers로 모든 사용자에게 서버 제공, allowedMcpServers·deniedMcpServers로 서버 제한, 서버가 차단됐을 때 사용자가 보는 것까지 다뤄요.

더 알아보기

MCP 연결 퀵스타트 — 첫 서버를 단계별로 연결
Channels — MCP 서버로 세션에 이벤트 밀어 넣기
Managed MCP — 조직 단위 MCP 접근 통제
Plugins — MCP 서버를 번들하는 플러그인
Model Context Protocol — 공식 MCP 사이트