MCP를 통해 Claude Code를 도구에 연결하기

Model Context Protocol을 사용하여 Claude Code를 도구에 연결하는 방법을 알아봅니다.

Claude Code는 AI 도구 통합을 위한 오픈 소스 표준인 Model Context Protocol (MCP)를 통해 수백 개의 외부 도구 및 데이터 소스에 연결할 수 있습니다. MCP 서버는 Claude Code에 도구, 데이터베이스 및 API에 대한 액세스를 제공합니다.

다른 도구(예: 이슈 추적기 또는 모니터링 대시보드)에서 채팅으로 데이터를 복사하는 자신을 발견할 때 서버를 연결하세요. 연결되면 Claude는 붙여넣은 내용에서 작업하는 대신 해당 시스템을 직접 읽고 작동할 수 있습니다.

첫 번째 서버를 연결하는 경우 단계별 안내를 위해 MCP 빠른 시작으로 시작하세요. 이 페이지는 전체 참고 자료입니다.

MCP로 할 수 있는 것

MCP 서버가 연결되면 Claude Code에 다음을 요청할 수 있습니다:

이슈 추적기에서 기능 구현: "JIRA 이슈 ENG-4521에 설명된 기능을 추가하고 GitHub에서 PR을 생성하세요."
모니터링 데이터 분석: "Sentry와 Statsig을 확인하여 ENG-4521에 설명된 기능의 사용량을 확인하세요."
데이터베이스 쿼리: "PostgreSQL 데이터베이스를 기반으로 기능 ENG-4521을 사용한 무작위 사용자 10명의 이메일을 찾으세요."
디자인 통합: "Slack에 게시된 새로운 Figma 디자인을 기반으로 표준 이메일 템플릿을 업데이트하세요."
워크플로우 자동화: "이 10명의 사용자를 새로운 기능에 대한 피드백 세션에 초대하는 Gmail 초안을 생성하세요."
외부 이벤트에 반응: MCP 서버는 채널로도 작동할 수 있으며, 세션에 메시지를 푸시하므로 Claude는 자리를 비운 동안 Telegram 메시지, Discord 채팅 또는 webhook 이벤트에 반응할 수 있습니다.

MCP 서버 찾기 및 구축

Anthropic Directory에서 검토된 커넥터를 찾아보세요. Directory 커넥터는 Claude Code와 동일한 MCP 인프라를 사용하므로 claude mcp add를 사용하여 여기에 나열된 모든 원격 서버를 추가할 수 있습니다.

자신만의 서버를 구축하려면 프로토콜 기본 사항에 대한 MCP 서버 가이드와 인증, 테스트 및 Directory 제출에 대한 Claude 커넥터 구축 문서를 참조하세요.

공식 mcp-server-dev 플러그인을 사용하여 Claude가 서버를 스캐폴드하도록 할 수도 있습니다.

플러그인 설치

Claude Code 세션에서 다음을 실행하세요:

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

설치가 실패하면 Claude Code가 보고하는 메시지와 일치하는지 확인하세요:

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 your-token"

.mcp.json, ~/.claude.json 또는 claude mcp add-json을 통해 JSON으로 MCP 서버를 구성할 때, type 필드는 http의 별칭으로 streamable-http를 허용합니다. MCP 사양은 이 전송에 대해 streamable-http라는 이름을 사용하므로 서버 설명서에서 복사한 구성이 수정 없이 작동합니다.

url은 있지만 type이 없는 JSON 항목은 구성 오류입니다. Claude Code는 type이 없는 항목을 stdio 서버로 읽기 때문입니다. Claude Code는 해당 서버를 건너뛰고 MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry를 보고합니다. v2.1.202 이전에는 Claude Code가 이 잘못된 구성을 command: expected string, received undefined로 보고했습니다.

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

옵션 2: 원격 SSE 서버 추가

일부 서비스는 여전히 SSE 엔드포인트만 노출합니다. HTTP 서버와 동일한 claude mcp add --transport http <name> <url> 명령으로 추가하세요. Claude Code는 HTTP 전송을 먼저 시도하고 서버가 이를 허용하지 않을 때 SSE로 전환합니다. 자동 전환에는 Claude Code 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: your-key-here"

옵션 3: 로컬 stdio 서버 추가

Stdio 서버는 컴퓨터에서 로컬 프로세스로 실행됩니다. 시스템에 직접 액세스하거나 사용자 정의 스크립트가 필요한 도구에 이상적입니다.

Claude Code는 생성된 서버의 환경에서 CLAUDE_PROJECT_DIR을 프로젝트 루트로 설정하므로 서버는 작업 디렉터리에 의존하지 않고 프로젝트 상대 경로를 확인할 수 있습니다. 이는 hooks가 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 설정으로 부여한 모든 추가 작업 디렉터리로 응답합니다. Claude Code는 해당 집합이 변경될 때 notifications/roots/list_changed를 보냅니다. v2.1.203 이전에는 roots/list가 시작 디렉터리만 반환했고 Claude Code는 notifications/roots/list_changed를 보내지 않았습니다.

이 변수는 Claude Code 자체의 환경이 아닌 서버의 환경에 설정되므로 프로젝트 범위 또는 사용자 범위의 .mcp.json 항목 또는 로컬 범위 서버 항목의 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

Note

중요: 서버 인수를 --로 구분

Stdio 서버의 경우, -- (이중 대시)는 Claude의 자체 옵션(예: --transport, --env, --scope)과 서버를 실행하는 명령 및 인수를 구분합니다. -- 이후의 모든 것은 서버에 그대로 전달됩니다.

예를 들어:

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은 둘 다 지원하지 않습니다.

.mcp.json 또는 claude mcp add-json으로 WebSocket 서버를 구성하세요:

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 블록: 다른 클라이언트의 설정 파일용으로 작성된 구성입니다.

각각은 MCP 서버 설치의 네 가지 옵션 중 하나가 취하는 입력 중 하나입니다. 아래에서 보유한 형태를 찾아 Claude Code가 허용하는 명령으로 변환하세요. 각 명령은 --scope project 또는 --scope user를 추가하지 않는 한 로컬 범위에 씁니다.

URL에서

URL은 서버가 원격임을 의미합니다. https:// 엔드포인트의 경우 --transport http로 추가하거나, 지침에서 엔드포인트가 SSE를 사용한다고 말할 때 옵션 2를 따르세요. wss:// 엔드포인트의 경우 --transport가 ws를 허용하지 않으므로 대신 옵션 4를 사용하세요:

claude mcp add --transport http example https://mcp.example.com/mcp

지침에서 API 키 또는 토큰 헤더도 제공하면 옵션 1에 표시된 대로 --header로 전달하세요.

`npx`, `uvx` 또는 바이너리 명령에서

시작 명령은 서버가 로컬 stdio 프로세스로 실행됨을 의미합니다. 전체 명령을 -- 뒤에 배치하여 Claude Code가 -y와 같은 플래그를 서버를 시작하는 명령에 전달하도록 하고 자신의 옵션으로 읽지 않도록 하세요. 지침에서 요청하는 환경 변수를 --env로 전달하세요. 서버 이름 뒤에 -- 앞에:

claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server

옵션 3은 -- 구분자를 완전히 다룹니다.

`mcpServers` JSON 블록에서

Claude Desktop과 같은 다른 MCP 클라이언트용으로 작성된 mcpServers 블록은 Claude Code가 읽는 래퍼 키와 항목 형태를 사용합니다. claude mcp add-json에 mcpServers 내부의 객체를 전달하세요. 래퍼는 아닙니다. 두 항목은 먼저 수리가 필요합니다:

type이 없는 url: 엔드포인트와 일치하도록 "type": "http", "type": "sse" 또는 "type": "ws"를 추가하세요. Claude Code는 type이 없는 항목을 stdio 서버로 읽으므로 type이 없는 url 항목은 실패합니다.
문자, 숫자, 하이픈 및 밑줄 이외의 문자가 있는 키: 해당 문자만 사용하는 서버 이름을 선택하세요. 그렇지 않으면 키가 서버 이름입니다.

예를 들어, 이 블록:

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

이 명령이 됩니다:

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

JSON 구성에서 MCP 서버 추가는 셸 이스케이프 및 add-json의 --scope 플래그를 다룹니다. 대신 팀과 공유하려면 --scope project를 추가하거나 프로젝트 루트의 .mcp.json에서 mcpServers 아래에 항목을 추가하고 커밋하세요. 프로젝트 범위는 Claude Code가 해당 파일을 로드하고 승인하는 방법을 다룹니다.

각 claude mcp add 및 claude mcp add-json 명령은 Added ... 줄을 인쇄합니다. Claude Code가 연결되었는지 확인하려면 claude mcp get <name>을 실행하세요. 서버 상태는 표시되는 상태 및 .mcp.json 서버의 승인 단계를 다룹니다.

서버 관리

구성한 후에는 다음 명령으로 MCP 서버를 관리할 수 있습니다:

# 구성된 모든 서버 나열
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가 해당 서버에 연결할 수 없음을 의미하며, list 명령이 실패했음을 의미하지 않습니다.

이 목록의 상태는 연결 시도가 아닌 구성 결정을 보고하므로 Claude Code는 서버에 연결하지 않고 인쇄합니다:

⏸ Pending approval (run `claude` to approve): 아직 승인하지 않은 .mcp.json의 프로젝트 범위 서버입니다. Claude Code는 claude mcp list 및 claude mcp get <name> 모두에 표시합니다. 대화형으로 claude를 실행하여 검토하고 승인하세요.
✘ Rejected (see disabledMcpjsonServers in settings): disabledMcpjsonServers 항목이 거부하는 .mcp.json 서버입니다. Claude Code는 claude mcp get <name>에만 표시합니다.
⊘ Disabled for this project (re-enable via /mcp): 프로젝트의 disabledMcpServers 목록이 이름을 지정하는 서버입니다. Claude Code는 claude mcp list 및 claude mcp get <name> 모두에 표시합니다. /mcp 패널에서 서버를 다시 켜세요. v2.1.238 이전에는 두 명령 모두 비활성화된 서버에 연결하여 상태 확인을 수행하고 연결 결과를 보고했습니다.

WebSocket 서버는 claude mcp list 출력에 나타나지 않습니다. claude mcp get <name> 또는 /mcp 패널을 사용하여 확인하세요.

프로젝트 서버 승인 및 작업 영역 신뢰

v2.1.196부터 claude mcp list 및 claude mcp get은 .mcp.json 승인을 claude를 실행하고 작업 영역 신뢰 대화 상자를 수락하여 작업 영역을 신뢰할 때까지 저장소에 체크인되지 않은 설정 파일에서만 읽습니다. 복제된 저장소는 자신의 서버를 승인할 수 없습니다: 프로젝트의 .claude/settings.json에 커밋된 enableAllProjectMcpServers 또는 enabledMcpjsonServers는 신뢰할 수 없는 폴더에서 무시되며, 서버는 연결되고 상태 확인되는 대신 ⏸ Pending approval으로 유지됩니다.

이러한 소스의 승인은 신뢰할 수 없는 폴더에서도 적용됩니다:

사용자 ~/.claude/settings.json
관리되는 설정
--settings로 전달된 설정

Claude Code는 또한 추적되지 않은 .claude/settings.local.json의 승인을 적용하지만, git을 실행하여 파일이 추적되는지 확인하며, 신뢰할 수 있는 폴더에서만 해당 확인을 실행합니다. 신뢰한 적이 없는 폴더에서는 파일의 승인이 신뢰 대화 상자를 기다립니다. 단, 폴더가 자신의 구성 홈인 경우는 제외됩니다: 홈 디렉터리 또는 .claude를 CLAUDE_CONFIG_DIR으로 설정한 디렉터리입니다. v2.1.207 이전에는 신뢰한 적이 없는 폴더에서 추적되지 않은 .claude/settings.local.json이 서버를 승인했습니다.

모든 설정 파일의 disabledMcpjsonServers 항목은 여전히 서버를 거부합니다.

서버 상태 세부 정보

/mcp에서 (서버의 메뉴 포함) 및 /plugin 관리자에서, 이전에 사용한 원격 HTTP 또는 SSE 서버는 cached 2h ago · connects on first use · 5 tools와 같은 cached 상태를 표시할 수 있습니다. Claude Code는 이전 세션에서 저장된 검색 캐시에서 서버의 도구 목록을 로드했으며, Claude Code는 Claude가 서버의 도구 중 하나를 처음 호출할 때 서버에 연결합니다. 도구는 첫 번째 메시지부터 사용 가능하므로 아무것도 할 필요가 없습니다. 검색 캐시 및 cached 상태에는 Claude Code v2.1.221 이상이 필요합니다.

검색 캐시는 기본적으로 꺼져 있으며, 점진적 롤아웃이 계정에 대해 활성화하지 않는 한 꺼져 있습니다. MCP_DISCOVERY_CACHE=1을 설정하여 켜거나, 롤아웃이 활성화했을 때도 꺼진 상태로 유지하려면 0으로 설정하세요. v2.1.238 이전에는 캐시가 기본적으로 켜져 있었습니다.

/mcp의 서버 메뉴의 두 가지 작업도 해당 서버의 캐시 항목에 영향을 미칩니다:

Reconnect: cached 서버에서 Claude Code는 첫 번째 도구 호출이 아닌 지금 연결하고 항목을 유지합니다. 연결되거나 실패한 서버에서 Claude Code는 재연결하고 항목도 삭제합니다.
Clear authentication: Claude Code는 서버의 인증을 취소하고 항목도 삭제합니다.

항목을 삭제한 후 Claude Code는 캐시 대신 서버에서 서버의 도구 목록을 가져옵니다.

서버의 상태가 ✘ Failed to connect일 때, claude mcp list는 해당 상태 줄에 실패 세부 정보를 추가하고, claude mcp get <name>은 Issue: 줄에 표시합니다: HTTP 상태 또는 오류 코드, 그리고 서버가 반환한 오류 텍스트입니다. /mcp의 서버 세부 정보 보기는 Issue: 행에 동일한 서버 보고 텍스트를 포함합니다. Claude Code는 이 세부 정보에서 자격 증명 같은 텍스트를 수정하고 확장된 서버 URL을 포함하지 않습니다. 이는 비밀을 전달할 수 있습니다. Claude Code는 ✘ Connection error 상태에 세부 정보를 추가하지 않습니다. 인쇄할 예외 텍스트가 해당 URL을 포함할 수 있기 때문입니다. v2.1.219 이전에는 두 명령 모두 상태 코드 또는 서버의 오류 텍스트 없이 기본 실패 상태만 표시했습니다.

/mcp에서 인증을 완료하고 연결이 여전히 HTTP 상태 또는 전송 오류 코드로 실패하면 Claude Code는 시도한 URL의 코드와 원점을 메시지에 추가합니다. 원점은 체계 및 호스트, 그리고 URL이 이름을 지정할 때 포트입니다. 예: https://mcp.example.com.

경로 및 쿼리는 해당 메시지에 나타나지 않습니다.
로컬, 프로젝트, 사용자 범위 또는 관리되는 MCP 구성의 서버의 경우, 원점은 해당 구성에 작성된 호스트를 표시하므로 호스트의 ${VAR} 참조는 메시지에서 확장되지 않습니다.
상태 또는 오류 코드가 없는 실패의 경우 Claude Code는 원점 없이 오류 텍스트를 표시합니다.

URL이 비어 있는 원격 서버의 구성은 /mcp, claude mcp list 및 /plugin 관리자에서 not configured로 표시되며, Claude Code는 연결을 시도하지 않습니다. 플러그인은 나중에 구성할 커넥터에 대한 자리 표시자 항목을 포함할 수 있으므로 Claude Code가 오류 또는 설정 문제로 보고하지 않습니다. /mcp의 서버 세부 정보 보기에는 No URL configured for this server가 표시됩니다. 연결하려면 항목의 url을 설정하세요. v2.1.208 이전에는 Claude Code가 빈 url을 재연결 프롬프트와 함께 구성 문제로 보고했습니다.

구성 경고

Claude Code는 아래의 구성 문제에 대해 경고합니다. 각 항목은 Claude Code가 확인하는 내용과 경고를 지우는 방법을 설명합니다:

숨겨진 공백: Claude Code는 MCP 구성 값이 숨겨진 선행 또는 후행 공백을 전달할 때 경고합니다. 이는 종종 후행 줄 바꿈이 있는 토큰을 붙여넣기에서 나옵니다. Claude Code는 command, url, 각 args 항목, 그리고 env 및 headers 아래의 값과 키 이름을 확인합니다. Claude Code는 claude mcp list 출력 및 /mcp에서 경고를 표시하며, 영향을 받는 필드의 이름을 지정합니다. 예: Leading or trailing whitespace in: headers.Authorization. Claude Code는 공백을 자르지 않고 작성된 대로 정확히 값을 사용하므로 구성을 편집하여 제거하세요.
둘 이상의 범위에서 동일한 이름: 다른 엔드포인트를 사용하여 둘 이상의 범위에서 동일한 서버 이름을 정의하면 Claude Code는 claude mcp list 출력 및 /mcp에서 충돌에 대해 경고합니다. Claude Code는 엔드포인트당 OAuth 로그인을 저장하므로 한 프로젝트에서 로드되는 정의를 인증할 때, 다른 정의가 로드되는 프로젝트에서는 여전히 별도로 로그인해야 합니다. 원하는 엔드포인트를 유지하고 claude mcp remove <name> --scope <scope>로 다른 엔드포인트를 제거하세요. 경고에서 Claude Code는 각 범위의 엔드포인트를 구성에 작성된 대로 인용합니다. ${VAR} 참조는 확장되지 않으므로 API 키와 같은 확인된 값을 표시하지 않습니다.
예약된 이름: Claude Code는 workspace, claude-in-chrome, computer-use, Claude Preview 및 Claude Browser를 포함한 기본 제공 서버의 이름을 예약합니다. 구성에서 예약된 이름의 서버를 정의하면 Claude Code는 로드 시 이를 건너뛰고 이름을 바꾸도록 요청하는 경고를 표시합니다. claude mcp add는 예약된 이름을 오류로 거부합니다. Claude Preview 및 Claude Browser는 모두 Claude Code 데스크톱 앱의 미리보기 창이 사용하는 기본 제공 서버의 이름입니다. v2.1.205 이전에는 Claude Browser가 예약되지 않았으므로 사용자 구성 서버가 해당 이름으로 등록될 수 있었습니다.
누락된 환경 변수: ${VAR} 참조가 설정되지 않은 변수의 이름을 지정하고 :-default가 없으면 Claude Code는 claude mcp list 출력 및 /mcp에서 경고하며, 변수의 이름을 지정하고, 여전히 ${VAR} 텍스트가 확장되지 않은 상태로 서버를 로드합니다. 변수를 설정하거나 ${VAR:-default} 폴백을 추가하세요. 원격 서버의 url 및 headers에서 일부 자격 증명 변수는 경고 없이 비어 있는 것으로 읽습니다.

도구 가용성

/mcp 패널은 각 연결된 서버 옆에 도구 개수를 표시하고 도구 기능을 광고하지만 도구를 노출하지 않는 서버에 플래그를 지정합니다.

요청이 백그라운드에서 아직 연결 중인 서버의 도구가 필요한 경우 Claude는 해당 서버가 연결될 때까지 기다립니다. 대기 방식은 구성에 따라 다릅니다:

도구 검색 포함 (기본값): 대기는 ToolSearch 호출 내에서 발생합니다.
도구 검색 없음: Claude는 대신 WaitForMcpServers 도구를 사용합니다. 도구 검색이 없는 구성에는 사용자 정의 ANTHROPIC_BASE_URL, ENABLE_TOOL_SEARCH=false 및 Google Cloud의 Agent Platform에서 Claude 4.5 세대보다 이전 모델이 포함됩니다.
Microsoft Foundry Azure에서 호스팅되는 배포: Claude는 API에서만 배포의 서버 측 거부를 발견하므로 도구 검색 경로에서 시작합니다. Claude Code가 해당 배포를 사전 로드로 전환한 후, 서버 연결을 완료하는 도구는 Claude의 다음 요청에서 사용 가능해집니다.

도구 검색이 활성화되면 Claude가 작업 중일 때 서버가 연결을 완료하면 Claude Code는 같은 턴의 다음 요청에서 서버의 도구 이름을 Claude에 나열합니다. Claude는 메시지를 기다리지 않고 해당 도구를 검색하고 호출할 수 있습니다.

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

/mcp 패널에서 서버를 토글하여 Claude Code가 구성을 잃지 않고 연결하지 않도록 중지합니다. Claude Code는 여전히 /mcp에서 서버를 나열하며, 비활성화로 표시합니다.

서버를 토글하면 Claude Code는 ~/.claude.json의 프로젝트당 선택을 기록합니다. 이는 분리된 서버 집합을 포함하는 두 목록 중 하나입니다:

disabledMcpServers: 사용자 구성 서버, 플러그인 서버, 조직이 관리되는 설정을 통해 제공하는 서버, Claude Code가 자체적으로 가져오는 claude.ai 커넥터 및 기본적으로 켜져 있는 기본 제공 서버에 대한 옵트아웃 목록입니다. Claude Code는 여기에 나열한 서버에 연결하지 않습니다. /mcp 토글로 claude.ai 커넥터를 비활성화할 때 Claude Code는 이를 표시 이름 (예: claude.ai Slack) 아래 이 목록에 씁니다.
enabledMcpServers: computer-use와 같이 기본적으로 꺼져 있는 기본 제공 서버에 대한 옵트인 목록입니다. Claude Code는 여기에 나열할 때만 기본 꺼짐 서버에 연결합니다.

Claude Code는 각 서버에 대해 정확히 두 목록 중 하나를 참조하므로 어느 목록도 다른 목록을 재정의하지 않습니다. 일반 서버를 enabledMcpServers에 추가하거나 기본 꺼짐 기본 제공 서버를 disabledMcpServers에 추가하면 Claude Code는 항목을 무시합니다.

disabledMcpServers 및 enabledMcpServers는 enabledMcpjsonServers 및 disabledMcpjsonServers와 무관합니다. 이는 프로젝트의 .mcp.json 파일에 정의된 서버의 승인을 제어합니다.

MCP 클라이언트 런타임

Claude Code는 두 클라이언트 런타임 중 하나를 통해 MCP 서버에 연결합니다. v1 런타임은 MCP TypeScript SDK 1.x를 기반으로 합니다. v2 런타임은 MCP TypeScript SDK 2.0의 동일한 코드이며, MCP 프로토콜 개정 2026-07-28을 추가합니다. 이 페이지의 나머지는 v2 런타임을 이름으로 지정하는 섹션을 제외하고 두 런타임 모두에 적용됩니다.

Claude Code는 시작할 때마다 런타임을 선택하고 종료할 때까지 유지합니다. 기능 플래그를 가져오는 세션에서 Claude Code v2.1.232 이상에서 v2 런타임을 사용합니다.

기능 플래그를 가져오지 않는 세션에서 Claude Code는 Claude Code v2.1.274 이상에서 기본적으로 v2 런타임을 사용합니다:

Amazon Bedrock, Claude Platform on AWS, Google Cloud의 Agent Platform 또는 Microsoft Foundry의 세션. Claude Code를 내장한 호스트 플랫폼이 CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST를 설정한 경우는 제외
Claude 앱 게이트웨이를 통해 로그인
텔레메트리 또는 기능 플래그 가져오기를 끈 세션. 예를 들어 DISABLE_TELEMETRY

v2에서 Claude Code는 또한:

HTTP 서버에 더 새로운 개정을 지원하는지 묻고, 지원하는 서버와 함께 사용합니다. 또한 기능 플래그를 가져오는 세션에서 claude.ai 커넥터 서버에 묻습니다. stdio 서버에 묻거나 모든 세션에서 커넥터 서버에 묻도록 하려면 MCP_PROTOCOL_NEGOTIATION을 auto로 설정하세요. 다른 모든 서버에 v1처럼 연결합니다.
열린 스트림을 통해 더 새로운 개정의 서버에서 list_changed 알림을 받습니다.
더 새로운 개정에 연결되는 채널 서버를 등록하지 않습니다. 해당 개정은 채널 메시지를 전달할 수 없기 때문입니다.
인증 응답이 예상치 못한 발급자의 이름을 지정하는 MCP OAuth 로그인을 실패합니다.

Anthropic은 기능 플래그 Claude Code가 가져오는 특정 서버를 더 이전 프로토콜에 유지하거나 해당 스트림에서 제외할 수 있습니다.

런타임을 직접 선택하려면 MCP_SDK_GENERATION을 v1 또는 v2로 설정하세요. Claude Code가 묻는지 결정하려면 MCP_PROTOCOL_NEGOTIATION을 auto 또는 legacy로 설정하세요.

동적 도구 업데이트

Claude Code는 MCP list_changed 알림을 지원하므로 MCP 서버가 연결을 끊었다가 다시 연결할 필요 없이 사용 가능한 도구, 프롬프트 및 리소스를 동적으로 업데이트할 수 있습니다. MCP 서버가 list_changed 알림을 보내면 Claude Code는 해당 서버에서 사용 가능한 기능을 자동으로 새로 고칩니다.

새로 고침 요청이 실패하면 Claude Code는 나중에 새로 고침이 성공할 때까지 서버의 이전에 발견된 도구, 프롬프트 및 리소스를 유지합니다. v2.1.214 이전에는 새로 고침 중 일시적 오류가 서버의 도구, 프롬프트 및 리소스를 빈 목록으로 바꿨습니다.

v2 런타임의 알림 스트림

v2 런타임에서 Claude Code는 더 새로운 프로토콜 개정의 서버에서 열린 스트림을 통해 list_changed 알림을 받습니다. 스트림이 닫히면 Claude Code는 두 가지 제한으로 다시 엽니다:

스트림이 10초 이내에 다시 닫힘: Claude Code는 최대 3번 다시 열고, 그 후 해당 연결에 대해 중지합니다.
스트림이 10초 이상 열려 있다가 닫힘 (서버리스 호스트에 대한 스트림이 일반적으로 하는 것처럼): 1시간에 5번 다시 열기 후 Claude Code는 다음 열기 전에 약 6시간을 기다립니다.

스트림이 다시 열릴 때까지 서버의 마지막 가져온 도구, 프롬프트 및 리소스를 유지합니다. 변경 사항을 더 빨리 선택하려면 /mcp에서 서버를 다시 연결하세요.

자동 재연결

Claude Code는 세션 중에 연결이 끊어진 원격 서버를 다시 연결하고 일시적 오류 후 HTTP 또는 SSE 서버의 첫 연결을 재시도합니다. Stdio 서버는 로컬 프로세스이며 Claude Code는 자동으로 재연결하지 않습니다.

원격 서버의 세션 중 연결 끊김

Claude Code는 지수 백오프를 사용하여 연결이 끊어진 원격 서버를 다시 연결합니다: 최대 5번의 시도, 1초 지연으로 시작하여 매번 두 배씩 증가합니다. 보이는 것은 Claude Code를 실행하는 방식에 따라 다릅니다:

대화형 세션: /mcp는 Claude Code가 재연결하는 동안 서버를 보류 중으로 표시합니다. 5번의 실패 시도 후 Claude Code는 서버를 실패로 표시하거나 서버가 다시 인증이 필요할 때 인증 필요로 표시합니다. /mcp에서 수동으로 재시도할 수 있습니다.
claude -p 실행 및 Agent SDK 세션: Claude Code는 동일한 일정으로 재연결하지만, 시도를 표시할 /mcp 패널은 없습니다.

실패한 첫 연결

HTTP 또는 SSE 서버의 첫 연결이 5xx 응답, 연결 거부 또는 시간 초과와 같은 일시적 오류로 실패하면 Claude Code는 최대 3번 재시도합니다. 연결이 여전히 실패하면 Claude Code는 서버를 실패로 표시합니다. Claude Code는 시작 시 및 서버가 세션 중에 추가될 때 이 방식으로 재시도합니다. 여기에는 Claude Code가 클라우드 세션에 구성에서 추가하는 서버 및 Agent SDK의 setMcpServers()로 추가하는 서버가 포함됩니다.

Claude Code는 이 경우에 재시도하지 않습니다:

WebSocket 서버의 첫 연결
인증 또는 찾을 수 없음 오류. 구성 변경이 필요하기 때문입니다. headersHelper가 서버의 Authorization 헤더의 유일한 소스일 때 Claude Code는 인증 오류를 재시도합니다. 각 시도에서 도우미를 다시 실행하고 새 자격 증명을 선택할 수 있기 때문입니다.

실패한 검색 요청

서버가 연결된 후 Claude Code는 tools/list, prompts/list 및 resources/list와 같은 기능 검색 요청을 보냅니다. Claude Code는 일시적 네트워크 또는 서버 오류 후 짧은 백오프로 최대 3번 재시도합니다. 인증 오류, 4xx 응답 또는 요청 시간 초과는 재시도하지 않습니다.

Claude가 서버 실패를 배우는 방법

구성된 서버가 연결에 실패하면 Claude Code가 Claude에 알리는지 여부는 도구 검색에 따라 다릅니다. 기본적으로 켜져 있습니다:

도구 검색을 사용하면 Claude Code는 Claude에 어느 서버가 실패했는지와 연결 오류를 알립니다. Claude Code는 일치하는 도구를 찾지 못한 ToolSearch 결과에 동일한 정보를 포함합니다.
도구 검색이 없는 구성에서 Claude Code는 실패한 서버 연결을 Claude에 보고하지 않습니다.

채널을 사용한 메시지 푸시

MCP 서버는 또한 메시지를 세션에 직접 푸시할 수 있으므로 Claude는 CI 결과, 모니터링 경고 또는 채팅 메시지와 같은 외부 이벤트에 반응할 수 있습니다. 이를 활성화하려면 서버가 claude/channel 기능을 선언하고 시작 시 --channels 플래그로 옵트인합니다. 공식적으로 지원되는 채널을 사용하려면 채널을 참조하거나, 자신만의 채널을 구축하려면 채널 참조를 참조하세요.

v2 런타임에서 MCP_PROTOCOL_NEGOTIATION을 auto로 설정하고 채널 서버가 MCP 프로토콜 개정 2026-07-28을 협상하면 채널 메시지를 전달할 수 없으므로 Claude Code는 채널로 등록하지 않습니다. 변수를 설정하지 않거나 legacy로 설정하면 stdio 서버가 이전 핸드셰이크에 유지됩니다.

Tip

팁:

-s 또는 --scope 플래그를 사용하여 구성이 저장되는 위치를 지정하세요:
local (기본값): 현재 프로젝트에서만 사용자에게만 사용 가능
project: .mcp.json 파일을 통해 프로젝트의 모든 사람과 공유
user: 모든 프로젝트에서 사용자에게 사용 가능
-e 또는 --env 플래그로 환경 변수를 설정하세요 (예: -e KEY=value)
--transport 및 --header 플래그는 -t 및 -H 단축형도 허용합니다
MCP_TIMEOUT 환경 변수를 사용하여 MCP 서버 시작 시간 초과를 구성하세요 (예: MCP_TIMEOUT=10000 claude는 10초 시간 초과를 설정)
서버당 도구 실행 시간 초과를 설정하려면 해당 서버의 .mcp.json 항목에 밀리초 단위의 timeout 필드를 추가하세요. 예를 들어 10분의 경우 "timeout": 600000입니다. 이는 해당 서버에만 MCP_TOOL_TIMEOUT 환경 변수를 재정의합니다
Claude Code는 MCP 도구 출력이 10,000 토큰을 초과할 때 경고를 표시하고 기본적으로 출력을 25,000 토큰으로 제한합니다. 이 제한을 늘리려면 MAX_MCP_OUTPUT_TOKENS 환경 변수를 설정하세요 (예: MAX_MCP_OUTPUT_TOKENS=50000). 경고 임계값은 고정됩니다. MCP 출력 제한 및 경고를 참조하세요
OAuth 2.0 인증이 필요한 원격 서버로 인증하려면 /mcp를 사용하세요

서버당 timeout은 도구 호출당 하드 월클록 제한이며, 서버의 진행 알림은 이를 연장하지 않습니다. 1000 미만의 값은 무시되고 MCP_TOOL_TIMEOUT으로 넘어가거나, 해당 변수가 설정되지 않은 경우 약 28시간의 기본값으로 넘어갑니다. HTTP, SSE 또는 claude.ai 커넥터 서버의 경우 서버의 첫 응답 바이트까지 각 요청을 포함하는 요청당 두 번째 타이머도 있습니다. Claude Code는 해당 타이머를 60초, 서버에 적용되는 도구 시간 초과 및 MCP_TIMEOUT 중 가장 큰 값으로 설정합니다. 설정되지 않은 MCP_TOOL_TIMEOUT의 28시간 기본값은 해당 비교에 들어가지 않으며, 60초 미만의 값은 타이머를 단축하지 않습니다. Stdio 및 WebSocket 서버에는 요청당 타이머가 없습니다.

서버당 최소 1000의 timeout은 또한 아래에 설명된 유휴 시간 초과의 하한으로 작동합니다: Claude Code는 서버당 timeout보다 더 빨리 유휴 상태로 인해 해당 서버의 도구 호출을 중단하지 않습니다. Claude Code v2.1.203 이상이 필요합니다.

MCP 서버에 대한 도구 호출이 유휴 윈도우 동안 응답 및 진행 알림을 보내지 않으면 월클록 제한을 기다리는 대신 오류로 중단됩니다. 유휴 시간 초과에는 Claude Code v2.1.187 이상이 필요합니다. IDE 서버 및 SDK 인프로세스 서버를 제외한 모든 서버 유형에 적용됩니다. 유휴 윈도우는 HTTP, SSE, WebSocket 및 claude.ai 커넥터 서버의 경우 기본값 5분, stdio 서버의 경우 30분입니다. v2.1.203 이전에는 stdio 서버가 유휴 시간 초과에서 제외되었습니다.

CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT 환경 변수를 밀리초 단위로 설정하여 유휴 윈도우를 변경하거나, 0으로 설정하여 확인을 비활성화하세요.

이 시간 초과는 호출이 실행될 수 있는 기간을 제한하며, 항상 차단되는 기간을 제한하지는 않습니다: 2분을 지나 실행되는 주 대화 호출은 먼저 백그라운드 작업으로 이동합니다. 긴 도구 호출의 자동 백그라운드 처리를 참조하세요.

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

주 대화에서 2분 이상 실행 중인 MCP 도구 호출은 세션을 차단하는 대신 백그라운드 작업으로 이동합니다. Claude는 작업 ID를 즉시 받고 계속 작업하며, 호출이 정착할 때 결과가 작업 알림으로 도착합니다. 자동 백그라운드 처리에는 Claude Code v2.1.212 이상이 필요합니다.

작업은 /tasks에 나타나며, 여기서 중지할 수도 있으며, 세션을 종료하면 생존하지 않습니다. 호출이 백그라운드에서 실행되는 동안 호출당 제한이 여전히 적용됩니다: 서버당 timeout 또는 MCP_TOOL_TIMEOUT으로 설정된 월클록 제한 및 CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT으로 설정된 유휴 시간 초과입니다.

CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 환경 변수를 밀리초 단위로 설정하여 임계값을 변경하거나, 0으로 설정하여 자동 백그라운드 처리를 끕니다. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS를 1로 설정하면 모든 다른 백그라운드 작업 기능과 함께 꺼집니다.

일부 호출은 백그라운드로 이동하지 않습니다:

서브에이전트의 호출; Claude Code는 주 대화 호출만 백그라운드 처리합니다
IDE 서버에 대한 호출
비대화형 모드의 호출. CLAUDE_AUTO_BACKGROUND_TASKS가 1로 설정되지 않는 한. 일회성 실행은 결과가 도착하기 전에 끝날 수 있기 때문입니다

열린 유도 대화 상자를 기다리는 호출은 대화 상자가 열려 있는 동안 백그라운드 처리되지 않습니다. 서버가 느린 것이 아니라 입력을 기다리고 있으므로 Claude Code는 대화 상자가 닫힐 때까지 이동을 연기합니다.

플러그인 제공 MCP 서버

플러그인은 MCP 서버를 번들로 제공할 수 있으며, 플러그인을 활성화하면 도구 및 통합을 제공합니다. 플러그인 MCP 서버는 사용자 구성 서버와 동일하게 작동합니다.

플러그인 MCP 서버의 작동 방식:

플러그인은 플러그인 루트의 .mcp.json 또는 plugin.json에 인라인으로 MCP 서버를 정의합니다
플러그인을 활성화하면 Claude Code는 MCP 서버를 자동으로 시작합니다
Claude Code는 플러그인 MCP 도구를 수동으로 구성된 MCP 도구와 함께 제공합니다
플러그인 서버를 추가하고 제거하려면 플러그인을 설치하거나 제거하세요. /mcp 명령이 아닙니다. 설치된 플러그인 서버를 /mcp에서 토글하여 끌 수 있습니다. 이는 플러그인을 제거하지 않고 Claude Code가 연결하지 않도록 중지합니다.

플러그인 MCP 구성 예:

플러그인 루트의 .mcp.json:

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

또는 plugin.json에 인라인:

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

플러그인 MCP 기능:

자동 라이프사이클: 서버는 다음 지점에서 연결 및 연결 해제됩니다:
- 세션 시작 시 Claude Code는 활성화된 플러그인의 서버를 자동으로 연결합니다. /mcp에서 이전에 사용한 원격 (HTTP 또는 SSE) 플러그인 서버는 cached 상태를 대신 표시할 수 있습니다. Claude Code는 Claude가 도구 중 하나를 처음 호출할 때 연결합니다.
- 세션 중에 플러그인을 활성화하거나 비활성화하면 Claude Code는 변경이 적용될 때 MCP 서버를 연결하거나 연결 해제합니다. 플러그인 변경 사항을 다시 시작하지 않고 적용은 그 시기를 설명합니다. 대화형 터미널이 없는 세션에서 /reload-plugins는 플러그인 MCP 서버를 연결하거나 연결 해제하지 않습니다. 이 변경 사항은 다음 세션에서 적용됩니다.
- 다시 로드할 때 Claude Code는 구성이 변경되지 않은 플러그인 서버의 라이브 연결을 유지하고, 이름을 지정하지 않고 Agent SDK에서 세션의 MCP 서버 목록을 바꿀 때 동일하게 수행합니다.
- v2.1.246 이상에서 /cd로 세션을 이동할 때 Claude Code는 새 디렉터리의 설정이 활성화하는 플러그인의 서버를 연결하고 더 이상 활성화되지 않는 플러그인의 서버를 연결 해제합니다. 이동 후 /reload-plugins를 실행할 필요가 없습니다.
- 웹 세션에서 아직 연결되지 않은 플러그인 서버에 대한 MCP 호출 (예: 유휴 세션이 깨어난 직후)은 서버를 요청 시 시작하고 연결을 기다립니다.
경로 자리 표시자: ${CLAUDE_PLUGIN_ROOT}는 플러그인의 설치 디렉터리로 확인되고, ${CLAUDE_PLUGIN_DATA}는 지속적인 상태 디렉터리로 확인되며, ${CLAUDE_PROJECT_DIR}은 안정적인 프로젝트 루트로 확인됩니다. 대체는 다음에 적용됩니다:
- stdio 서버: command, args, env
- http, sse 및 ws 서버: url, headers 및 headersHelper. v2.1.195 이전에는 headersHelper가 자리 표시자를 리터럴 문자열로 전달했습니다.
사용자 환경 액세스: 수동으로 구성된 서버와 동일한 환경 변수에 액세스
여러 전송 유형: stdio, SSE, HTTP 및 WebSocket 전송 지원. 전송 지원은 서버에 따라 다를 수 있습니다.

플러그인 서버는 플러그인에서 온 것을 나타내는 표시기와 함께 /mcp에 나타납니다.

플러그인 MCP 도구 이름:

플러그인 번들 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 필드에서, 또는 hook matcher에서 이 전체 이름을 사용하세요. mcp__database-tools__.*와 같은 베어 서버 키에 대해 작성된 hook matcher는 플러그인 번들 서버에 대해 절대 실행되지 않습니다.

서버 자체는 plugin:<plugin-name>:<server-name> (예: plugin:my-plugin:database-tools)과 같은 범위 지정 이름으로 등록됩니다. 구성된 서버 이름이 예상되는 위치 (예: mcp_tool hook의 server 필드)에서 해당 이름을 사용하세요.

플러그인과 함께 MCP 서버를 번들로 제공하는 방법에 대한 자세한 내용은 플러그인 구성 요소 참조를 참조하세요.

MCP 설치 범위

MCP 서버는 세 가지 범위에서 구성할 수 있습니다. 선택한 범위는 서버가 로드되는 프로젝트와 구성이 팀과 공유되는지 여부를 제어합니다. 관리자는 관리형 구성을 통해 모든 사용자를 위해 서버를 배포하거나 제공할 수도 있습니다.

범위	로드 위치	팀과 공유	저장 위치
로컬	현재 프로젝트만	아니오	`~/.claude.json`
프로젝트	현재 프로젝트만	예, 버전 제어를 통해	프로젝트 루트의 `.mcp.json`
사용자	모든 프로젝트	아니오	`~/.claude.json`

로컬 범위

로컬 범위는 기본값입니다. 로컬 범위 서버는 추가한 프로젝트에서만 로드되며 사용자에게만 비공개입니다. Claude Code는 해당 프로젝트의 경로 아래 ~/.claude.json에 저장하므로 다른 프로젝트에는 동일한 서버가 나타나지 않습니다. 개인 개발 서버, 실험적 구성 또는 버전 제어에 포함하고 싶지 않은 자격 증명이 있는 서버에 로컬 범위를 사용하세요.

# 로컬 범위 서버 추가 (기본값)
claude mcp add --transport http stripe https://mcp.stripe.com

# 명시적으로 로컬 범위 지정
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

명령은 ~/.claude.json 내의 현재 프로젝트 항목에 서버를 작성합니다. 아래 예는 /path/to/your/project에서 실행할 때의 결과를 보여줍니다:

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

프로젝트 범위

프로젝트 범위 서버는 프로젝트 루트 디렉토리의 .mcp.json 파일에 구성을 저장하여 팀 협업을 가능하게 합니다. 프로젝트 범위 서버를 추가하면 Claude Code는 자동으로 이 파일을 생성하거나 적절한 구성 구조로 업데이트합니다. .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"
    }
  }
}

보안상의 이유로 Claude Code는 대화형 세션에서 .mcp.json 파일의 프로젝트 범위 서버를 사용하기 전에 승인을 요청합니다. 이러한 승인 선택을 재설정하려면 claude mcp reset-project-choices를 실행하세요.

claude -p 실행, Agent SDK 세션 및 클라우드 세션에서 Claude Code는 해당 프롬프트를 표시할 수 없습니다. 프로젝트 범위 서버를 묻지 않고 로드합니다. Claude Code는 또한 skipDangerousModePermissionPrompt가 사용자 설정 또는 관리형 설정에 설정된 bypassPermissions 모드에서 시작한 세션에서 프롬프트를 건너뜁니다. 어쨌든 서버를 제외하려면:

disabledMcpjsonServers에 추가하면 모든 권한 모드에서 차단됩니다.
--setting-sources를 사용하거나 SDK의 settingSources 옵션으로 프로젝트 설정을 완전히 제외합니다.
--strict-mcp-config로 세션을 시작합니다. Claude Code는 --mcp-config로 전달한 MCP 서버만 사용합니다. Claude Code가 로드하지 않는 프로젝트 범위 서버에 대한 승인 프롬프트를 건너뛰려면 Claude Code v2.1.246 이상이 필요합니다. v2.1.246 이전에는 엄격한 세션도 승인을 기다렸으므로 백그라운드 세션이 시작 시 대기했습니다. 관리형 MCP 파일에서 플래그가 수행하는 작업에 대해서는 관리형-mcp.json을 사용한 독점 제어를 참조하세요.

프로젝트 서버 승인 및 워크스페이스 신뢰는 저장소에 커밋된 승인이 워크스페이스 신뢰와 상호 작용하는 방식을 다룹니다.

사용자 범위

사용자 범위 서버는 ~/.claude.json에 저장되며 교차 프로젝트 접근성을 제공하므로 컴퓨터의 모든 프로젝트에서 사용할 수 있으면서 사용자 계정에만 비공개입니다. 이 범위는 개인 유틸리티 서버, 개발 도구 또는 다양한 프로젝트에서 자주 사용하는 서비스에 적합합니다.

# 사용자 서버 추가
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

범위 계층 및 우선순위

동일한 서버가 둘 이상의 위치에 정의되면 Claude Code는 가장 높은 우선순위 소스의 정의를 사용하여 한 번 연결합니다. 해당 소스의 전체 서버 항목이 사용되며, 필드는 범위 간에 병합되지 않습니다.

로컬 범위
프로젝트 범위
사용자 범위
플러그인 제공 서버
claude.ai 커넥터

세 범위는 이름으로 중복을 일치시킵니다. 플러그인과 커넥터는 엔드포인트로 일치하므로 위의 서버와 동일한 URL 또는 명령을 가리키는 것은 중복으로 처리됩니다.

조직이 managedMcpServers 관리형 설정을 통해 제공하는 서버는 이 모든 것 위에 순위가 매겨지므로 이 중 하나가 중복되면 Claude Code는 조직의 정의를 연결합니다. Claude Code v2.1.259 이상이 필요합니다.

Desktop 앱의 Code 탭에서 로컬 세션을 열 때 ~/.claude.json (사용자 범위)의 최상위 수준과 .mcp.json에 동일한 stdio 서버 이름이 있으면 Code 탭은 ~/.claude.json 정의를 사용합니다.

`.mcp.json`의 환경 변수 확장

Claude Code는 .mcp.json 파일의 환경 변수 확장을 지원하므로 팀이 구성을 공유하면서 머신 특정 경로 및 API 키와 같은 민감한 값에 대한 유연성을 유지할 수 있습니다.

지원되는 구문

${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 Code는 claude mcp list 출력에서 해당 서버에 대한 누락된 변수 경고를 보고하고 확장되지 않은 ${VAR} 텍스트를 그대로 사용합니다. 변수를 설정하거나 :-default 폴백을 추가하여 서버가 의도한 값으로 시작하도록 하세요. 원격 서버의 url 및 headers에서 일부 자격 증명 변수는 경고 없이 빈 값으로 읽힙니다.

빈 값으로 읽히는 자격 증명 변수

원격 서버의 url 및 headers에서 Claude Code는 환경의 자격 증명 변수를 확장하지 않고 빈 값으로 읽습니다. 이는 프로젝트의 .mcp.json 또는 플러그인이 Claude Code 또는 클라우드 공급자 자격 증명을 이름이 지정된 서버로 보내는 것을 방지합니다. Bearer ${ANTHROPIC_AUTH_TOKEN}을 작성하면 서버는 자격 증명 없이 Bearer 를 수신하고 일반적으로 401로 요청을 거부합니다. Claude Code는 이를 실패한 연결로 보고합니다.

포함된 이름은 다음과 같습니다:

Claude Code의 자체 자격 증명(예: ANTHROPIC_API_KEY 및 ANTHROPIC_AUTH_TOKEN)
클라우드 공급자의 자격 증명(예: AWS_BEARER_TOKEN_BEDROCK)
환경이 전달하는 기타 자격 증명(예: HTTPS_PROXY 및 NPM_TOKEN)

포함된 이름은 변수를 설정했는지 여부와 관계없이 빈 값으로 읽히며, 이에 대한 :-default 폴백은 무시됩니다. ANTHROPIC_BASE_URL과 같은 공급자 기본 URL은 여전히 확장되므로 "url": "${ANTHROPIC_BASE_URL}/mcp"는 작동합니다. 단, URL의 값 자체에 사용자 이름 및 암호와 같은 자격 증명이 포함되지 않는 한입니다.

API_KEY와 같이 이 집합 외부의 이름은 작성된 대로 확장됩니다. 서버에 포함된 자격 증명 중 하나를 제공하려면 이를 자신의 이름을 가진 변수에 복사하고 대신 해당 이름을 참조하세요.

원격 서버의 url 또는 headers가 설정한 포함된 변수를 참조할 때 Claude Code는 디버그 로그 줄에 이름을 지정합니다. 줄을 읽으려면 claude --debug-file /tmp/claude-debug.log를 실행하고 해당 파일에서 never expanded toward a remote server를 검색하세요.

`/mcp` 및 CLI 출력에서 참조가 표시되는 방식

로컬, 프로젝트 또는 사용자 범위의 서버의 경우 다음 표면은 ${VAR} 참조를 해결된 값이 아닌 이름으로 표시합니다:

서버의 /mcp 상세 보기의 URL 또는 명령줄
claude mcp list 및 claude mcp get 출력

/mcp 상세 보기는 Claude Code v2.1.268 이상에서 이러한 방식으로 참조를 표시합니다.

조직이 managedMcpServers 설정을 통해 제공하는 서버의 경우 이러한 표면은 URL의 호스트만 표시합니다.

연결이 실패할 때 claude mcp list, claude mcp get 및 /mcp가 표시하는 내용을 확인하려면 서버 상태 상세를 참조하세요.

실제 예

예: 코드 검토를 위해 GitHub에 연결

GitHub의 원격 MCP 서버는 헤더로 전달된 GitHub 개인 액세스 토큰으로 인증합니다. 하나를 얻으려면 GitHub 토큰 설정을 열고, Claude가 작업하려는 리포지토리에 액세스할 수 있는 새로운 세분화된 토큰을 생성한 다음 서버를 추가하세요:

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

YOUR_GITHUB_PAT를 개인 액세스 토큰으로 바꾸세요. claude mcp add 명령은 자격 증명을 검증하지 않고 구성을 저장하므로 여기서 자리 표시자 값이 허용되지만 서버는 나중에 연결하지 못합니다. 연결을 확인하려면 /mcp를 실행하고 서버가 connected를 표시하는지 확인하세요. 잘못된 자격 증명이 있는 서버는 failed를 표시하며, 실패 세부 정보에는 서버가 반환한 HTTP 상태(예: 401)가 포함됩니다.

그런 다음 GitHub로 작업합니다:

PR #456을 검토하고 개선 사항을 제안하세요

방금 발견한 버그에 대한 새 이슈를 생성하세요

나에게 할당된 모든 열린 PR을 보여주세요

예: PostgreSQL 데이터베이스 쿼리

DBHub, @bytebase/dbhub 패키지는 --dsn에서 전달하는 연결 문자열을 통해 Claude를 관계형 데이터베이스에 연결하는 MCP 서버입니다. Claude가 실행하는 쿼리가 데이터를 수정할 수 없도록 연결 문자열에서 읽기 전용 데이터베이스 사용자를 사용하세요:

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

서버가 시작되는지 확인하려면 /mcp를 실행하고 db가 connected를 표시하는지 확인하세요.

그런 다음 자연스럽게 데이터베이스를 쿼리합니다:

이번 달 총 수익은 얼마입니까?

주문 테이블의 스키마를 보여주세요

지난 90일 동안 구매하지 않은 고객을 찾으세요

원격 MCP 서버로 인증

많은 클라우드 기반 MCP 서버는 인증이 필요합니다. Claude Code는 보안 연결을 위해 OAuth 2.0을 지원합니다.

Claude Code는 서버가 401 Unauthorized 또는 403 Forbidden으로 응답할 때 원격 서버를 인증이 필요한 것으로 표시합니다. Claude Code가 표시하는 내용은 서버에 따라 다릅니다:

로그인하지 않은 서버의 경우 두 상태 코드 모두 /mcp에서 서버를 플래그하여 OAuth 흐름을 완료할 수 있습니다.
claude.ai 커넥터의 경우 claude.ai가 세션 토큰을 거부하여 발생한 401은 커넥터를 플래그하지 않습니다. 커넥터를 다시 인증해도 로그인을 수정할 수 없기 때문입니다. Claude Code는 대신 세션 토큰 거부 상태를 표시합니다.
Authorization 헤더를 구성한 서버의 경우 headers에서 또는 headersHelper를 통해 연결 중에 401 또는 403이 발생하면 서버를 플래그하지 않습니다. 수정할 자격 증명은 구성한 것이기 때문입니다. Claude Code는 대신 연결이 실패한 것으로 보고합니다. 해당 헤더를 ${VAR} 참조에서 설정한 경우 해당 변수가 Claude Code 빈 값으로 읽는 변수 중 하나인지 확인합니다.
클라우드 세션에 전달된 커넥터의 경우 Claude Code는 로그인 흐름을 실행하지 않습니다. 세션의 프록시가 claude.ai에서 부여한 인증으로 커넥터에 인증하기 때문입니다. 거기서 커넥터를 다시 인증해야 할 때는 세션에서가 아니라 claude.ai/customize/connectors에서 다시 연결합니다.

이미 로그인한 OAuth 서버에 대한 요청이 401 Unauthorized를 반환하면 Claude Code는 저장된 토큰을 새로 고치고 재연결한 후 요청을 한 번 재시도합니다. 해당 재시도도 실패한 경우에만 /mcp에서 서버를 플래그합니다. v2.1.206 이전에는 네트워크 오류와 같은 일시적인 이유로 토큰 새로 고침이 실패하면 새로 고침 토큰이 여전히 유효했음에도 불구하고 OAuth 서버를 세션의 나머지 기간 동안 인증이 필요한 것으로 플래그했습니다.

저장된 새로 고침 토큰을 서버가 거부하면 Claude Code는 즉시 /mcp를 가리키는 알림을 표시합니다. /mcp를 열고 서버에서 다시 인증을 선택하여 다음 도구 호출이 실패하기 전에 다시 로그인합니다.

인증 서버를 가리키는 WWW-Authenticate 헤더를 반환하는 사용자 정의 서버는 다른 원격 서버와 동일한 자동 검색을 받습니다.

Claude Code는 또한 하나 이상의 구성된 서버가 인증이 필요할 때 시작 알림을 표시하므로 어떤 서버가 로그인이 필요한지 알아내기 위해 /mcp를 열 필요가 없습니다. 알림에는 Claude Code v2.1.193 이상이 필요합니다. Claude Code에서 로그인할 수 있는 서버만 계산합니다. v2.1.218 이전에는 claude.ai에서 연결되지 않은 claude.ai 커넥터도 계산했으며, 이는 claude.ai 설정에서만 연결할 수 있습니다.

알림은 각 서버를 한 번 공지하고 해당 서버가 연결되어 다시 로그인이 필요할 때까지 이후 시작 시 계산에서 제외합니다. /mcp는 여전히 로그인이 필요한 모든 서버를 나열합니다.

비대화형 모드에는 /mcp 패널이 없으므로 Claude Code는 OAuth 흐름을 실행할 수 없습니다. v2.1.196부터 구성된 서버가 도구 검색이 활성화된 claude -p 또는 Agent SDK 실행 중에 인증이 필요할 때 (기본값), Claude Code는 Claude에게 서버의 도구가 인증할 때까지 사용할 수 없음을 알립니다. Claude는 서버가 구성되지 않은 것처럼 응답하는 대신 로그인이 필요한 서버의 이름을 지정할 수 있습니다. /mcp를 사용하는 대화형 세션에서 또는 claude mcp login <name>으로 로그인을 완료합니다.

서버에 대해 headers.Authorization을 구성했는데 서버가 해당 헤더를 거부하면 Claude Code는 OAuth로 폴백하지 않고 연결이 실패한 것으로 보고합니다. MCP 엔드포인트에 대해 토큰이 유효한지 확인하거나 OAuth 흐름을 사용하려면 헤더를 제거합니다.

인증이 필요한 서버 추가

MCP 빠른 시작에서 이미 sentry 서버를 추가했다면 이 단계를 건너뜁니다. 동일한 서버 이름으로 동일한 범위에서 claude mcp add를 다시 실행하면 MCP server sentry already exists in local config로 실패합니다. 그렇지 않으면 다음을 실행합니다:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Claude Code 내에서 /mcp 명령 사용

Claude Code에서 다음 명령을 사용합니다:

/mcp

그런 다음 브라우저에서 로그인 단계를 따릅니다.

명령줄에서 인증

v2.1.186부터 claude mcp login <name>은 구성된 서버의 OAuth 흐름을 셸에서 직접 실행하므로 세션 내에서 /mcp 패널을 열 필요가 없습니다.

claude mcp login sentry

나중에 저장된 자격 증명을 지우려면 claude mcp logout <name>을 실행합니다.

v2.1.191부터 명령은 SSH 세션 중이거나 디스플레이 서버가 없는 Linux와 같이 로컬 브라우저를 사용할 수 없는 경우를 감지하고 브라우저를 열려고 시도하는 대신 인증 URL을 출력합니다. 로컬 머신에서 URL을 열고 브라우저의 주소 표시줄에서 전체 리디렉션 URL을 프롬프트에 다시 붙여넣습니다. 명령은 붙여넣기 단계를 위해 대화형 터미널이 필요하므로 ssh -t로 연결합니다. 로컬 브라우저가 감지되었을 때도 URL 프롬프트를 강제하려면 --no-browser를 전달합니다.

claude mcp login sentry --no-browser

고정 OAuth 콜백 포트 사용

일부 MCP 서버는 미리 등록된 특정 리디렉션 URI가 필요합니다. 기본적으로 Claude Code는 OAuth 콜백을 위해 무작위로 사용 가능한 포트를 선택합니다. --callback-port를 사용하여 포트를 고정하여 http://localhost:PORT/callback 형식의 사전 등록된 리디렉션 URI와 일치하도록 합니다. Claude Code v2.1.229에서 리디렉션 URI 불일치로 로그인이 실패하면 사전 구성된 OAuth 자격 증명 사용의 버전 참고를 참조합니다.

--callback-port를 단독으로 사용할 수 있습니다 (동적 클라이언트 등록 포함) 또는 --client-id와 함께 사용할 수 있습니다 (사전 구성된 자격 증명 포함).

# 동적 클라이언트 등록을 사용한 고정 콜백 포트
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

사전 구성된 OAuth 자격 증명 사용

일부 MCP 서버는 동적 클라이언트 등록을 통한 자동 OAuth 설정을 지원하지 않습니다. "Incompatible auth server: does not support dynamic client registration"과 같은 오류가 표시되면 서버에 사전 구성된 자격 증명이 필요합니다. Claude Code는 또한 동적 클라이언트 등록 대신 클라이언트 ID 메타데이터 문서 (CIMD)를 사용하는 서버를 지원하며 자동으로 검색합니다. 자동 검색이 실패하면 먼저 서버의 개발자 포털을 통해 OAuth 앱을 등록한 다음 서버를 추가할 때 자격 증명을 제공합니다.

서버로 OAuth 앱 등록

서버의 개발자 포털을 통해 앱을 생성하고 클라이언트 ID와 클라이언트 시크릿을 기록합니다.

많은 서버는 리디렉션 URI도 필요합니다. 그렇다면 포트를 선택하고 http://localhost:PORT/callback 형식으로 리디렉션 URI를 등록합니다. 다음 단계에서 --callback-port와 함께 동일한 포트를 사용합니다.

v2.1.229에서 Claude Code는 http://127.0.0.1:PORT/callback을 대신 보냈으며, 등록된 리디렉션 URI와 정확히 일치하는 서버는 리디렉션 URI 불일치로 로그인을 거부했습니다. Claude Code v2.1.231은 localhost 형식을 복원했습니다. v2.1.229에서 복구하려면 Claude Code를 업그레이드하거나 임시로 http://127.0.0.1:PORT/callback 형식을 서버의 등록된 리디렉션 URI에 추가합니다.

자격 증명으로 서버 추가

다음 방법 중 하나를 선택합니다. --callback-port에 사용되는 포트는 사용 가능한 모든 포트일 수 있습니다. 이전 단계에서 등록한 리디렉션 URI와 일치하기만 하면 됩니다.

--client-id를 사용하여 앱의 클라이언트 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

JSON 구성에 oauth 객체를 포함하고 --client-secret을 별도의 플래그로 전달합니다:

claude mcp add-json my-server \
'{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
--client-secret

동적 클라이언트 등록을 사용하면서 포트를 고정하려면 클라이언트 ID 없이 --callback-port를 사용합니다:

claude mcp add-json my-server \
'{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

환경 변수를 통해 시크릿을 설정하여 대화형 프롬프트를 건너뜁니다:

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

Claude Code에서 인증

Claude Code에서 /mcp를 실행하고 브라우저 로그인 흐름을 따릅니다.

Tip

팁:

클라이언트 시크릿은 구성에 저장되지 않고 시스템 키체인 (macOS) 또는 자격 증명 파일에 안전하게 저장됩니다
서버를 추가할 때만 클라이언트 시크릿을 설정할 수 있습니다. claude mcp login 또는 /mcp에서 인증할 때 Claude Code는 저장된 시크릿을 사용하며 시크릿을 요청하거나 MCP_CLIENT_SECRET을 읽지 않습니다
나중에 시크릿을 추가하거나 변경하려면 claude mcp remove <name>으로 서버를 제거한 다음 --client-secret과 동일한 --scope로 다시 추가합니다
서버가 시크릿이 없는 공개 OAuth 클라이언트를 사용하는 경우 --client-secret 없이 --client-id만 사용합니다
이러한 플래그는 HTTP 및 SSE 전송에만 적용됩니다. stdio 서버에는 영향을 주지 않습니다
claude mcp get <name>을 사용하여 OAuth 자격 증명이 서버에 대해 구성되었는지 확인합니다

OAuth 메타데이터 검색 재정의

특정 OAuth 인증 서버 메타데이터 URL을 가리켜 기본 검색 체인을 우회하도록 Claude Code를 설정합니다. MCP 서버의 표준 엔드포인트가 오류를 반환하거나 내부 프록시를 통해 검색을 라우팅하려는 경우에 authServerMetadataUrl을 설정합니다. 기본적으로 Claude Code는 먼저 /.well-known/oauth-protected-resource에서 RFC 9728 보호된 리소스 메타데이터를 확인한 다음 /.well-known/oauth-authorization-server에서 RFC 8414 인증 서버 메타데이터로 돌아갑니다.

.mcp.json의 서버 구성의 oauth 객체에 authServerMetadataUrl을 설정합니다:

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

URL은 https://를 사용해야 합니다. 메타데이터 URL의 scopes_supported는 업스트림 서버가 광고하는 범위를 재정의합니다.

OAuth 범위 제한

oauth.scopes를 설정하여 인증 흐름 중에 Claude Code가 요청하는 범위를 고정합니다. 이는 업스트림 인증 서버가 광고하는 것보다 더 많은 범위를 부여하고 싶지 않을 때 MCP 서버를 보안 팀이 승인한 부분 집합으로 제한하는 지원되는 방법입니다. 값은 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과 서버가 /.well-known에서 검색하는 범위 모두보다 우선합니다. 설정하지 않으면 MCP 서버가 요청된 범위 집합을 결정합니다.

v2.1.196부터 oauth.scopes가 설정되지 않으면 Claude Code는 서버의 WWW-Authenticate 헤더 또는 보호된 리소스 메타데이터에서 제공하는 범위를 요청하고 둘 다 제공하지 않을 때 scope 매개변수를 보내지 않습니다. 더 이상 자동으로 검색된 인증 서버 메타데이터에서 전체 scopes_supported 카탈로그를 요청하지 않습니다. 해당 카탈로그를 요청하면 관리자 전용 또는 템플릿 범위를 광고하는 ID 공급자가 invalid_scope 오류로 인증 요청을 거부하게 했습니다. 구성된 authServerMetadataUrl에서 가져온 메타데이터는 여전히 scopes_supported를 요청된 범위로 제공합니다.

인증 서버가 scopes_supported에서 offline_access를 광고하면 Claude Code는 액세스 토큰을 새로운 브라우저 로그인 없이 새로 고칠 수 있도록 고정된 범위에 추가합니다.

서버가 나중에 도구 호출에 대해 403 insufficient_scope을 반환하면 호출이 추가 권한 필요 메시지로 실패하며 서버가 요청하는 범위의 이름을 지정합니다. 서버는 /mcp에서 인증이 필요한 것으로 표시됩니다.

해당 범위가 고정된 oauth.scopes에 없으면 범위를 추가한 다음 /mcp를 실행하고 서버를 다시 인증합니다. Claude Code는 서버가 명명한 범위가 아니라 고정된 범위를 요청하므로 추가하지 않고 다시 인증하면 받는 토큰에 여전히 범위가 없습니다.

사용자 정의 인증을 위한 동적 헤더 사용

MCP 서버가 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"
    }
  }
}

명령은 인라인일 수도 있습니다:

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

요구 사항:

명령은 JSON 객체의 문자열 키-값 쌍을 stdout에 작성해야 합니다
Claude Code는 명령을 셸에서 실행하고 10초 후에 포기합니다
Claude Code는 서버를 구성한 위치에 따라 명령의 작업 디렉토리를 선택하므로 스크립트에 절대 경로를 사용하거나 PATH에 넣습니다
동적 헤더는 동일한 이름의 정적 headers를 재정의합니다

Claude Code는 프로젝트 및 로컬 범위 서버에 대한 신뢰 규칙이 실행을 허용한 후 각 연결 (세션 시작 및 재연결 시)에서 헬퍼를 새로 실행합니다. 결과를 캐싱하지 않으므로 스크립트는 토큰 재사용을 담당합니다.

도구 호출이 401 Unauthorized 또는 403 Forbidden을 반환하면 Claude Code는 자동으로 동일한 규칙에 따라 헬퍼를 다시 실행하고 새로운 헤더로 재연결한 다음 호출을 한 번 재시도합니다. Claude Code는 해당 재시도도 실패한 경우에만 서버를 /mcp에서 인증이 필요한 것으로 표시합니다.

헬퍼의 출력에 Authorization 헤더가 포함되면 Claude Code는 해당 자격 증명을 서버의 인증으로 사용하고 서버에 대해 OAuth로 폴백하지 않습니다.

서버가 연결 중에 헬퍼의 자격 증명을 거부하면 Claude Code는 서버를 인증이 필요한 것으로 표시하지 않고 연결이 실패한 것으로 보고합니다. 헬퍼가 반환하는 자격 증명을 수정한 다음 /mcp에서 재연결하여 헬퍼를 다시 실행합니다.

Claude Code는 헬퍼를 실행할 때 다음 환경 변수를 설정합니다:

변수	값
`CLAUDE_CODE_MCP_SERVER_NAME`	MCP 서버의 이름
`CLAUDE_CODE_MCP_SERVER_URL`	MCP 서버의 URL
`CLAUDE_PLUGIN_ROOT`	플러그인의 루트 디렉토리. 플러그인이 서버를 제공할 때만 설정됩니다

이를 사용하여 여러 MCP 서버를 제공하는 단일 헬퍼 스크립트를 작성합니다.

플러그인 제공 headersHelper는 명령이 셸을 통해 실행되기 때문에 플러그인의 ${user_config.*} 값을 참조할 수 없습니다. Claude Code는 서버를 오류와 함께 잘못 구성된 것으로 보고하고 값을 대체하지 않습니다. ${user_config.KEY}를 셸 구문 분석되지 않는 서버의 headers 필드에 넣거나 헬퍼 스크립트가 구성 파일에서 값을 읽도록 합니다. v2.1.207 이전에는 headersHelper가 ${user_config.*} 값을 대체했습니다.

헬퍼가 실행되는 위치

Claude Code는 서버를 선언한 구성에서 headersHelper 명령의 작업 디렉토리를 선택합니다. Claude Code에서 실행하는 cd는 이를 이동하지 않으며, /cd는 세션의 기본 작업 디렉토리에서 실행되는 서버에 대해서만 이를 이동합니다. 아래의 각 행은 headersHelper 명령의 상대 경로가 확인되는 디렉토리를 제공합니다.

서버를 구성한 위치	작업 디렉토리
플러그인	플러그인의 루트 디렉토리. Claude Code v2.1.195 이상이 필요합니다
프로젝트 `.mcp.json` 또는 로컬 범위 서버	서버가 선언된 프로젝트 디렉토리
프로젝트의 에이전트 파일, SDK의 `mcpServers` 옵션 또는 `setMcpServers()` 메서드의 서버, 또는 `--mcp-config`	세션의 기본 작업 디렉토리
사용자 범위, 관리형 MCP, claude.ai 커넥터, 또는 프로젝트 외부의 에이전트 파일 (`--add-dir` 디렉토리 포함)	구성 디렉토리 `~/.claude` (또는 `CLAUDE_CONFIG_DIR`을 설정한 경우)

v2.1.238 이전에는 Claude Code는 또한 사용자 범위, 관리형, claude.ai 커넥터 서버의 헬퍼와 프로젝트 외부의 에이전트 파일을 시작한 디렉토리에서 실행했습니다.

헬퍼가 읽을 수 있는 변수

저장소 또는 플러그인이 제공하는 headersHelper는 작성하지 않은 명령이므로 Claude Code는 ANTHROPIC_API_KEY와 같은 환경의 자격 증명 변수 없이 실행합니다. 서버를 구성한 위치에 따라 이것이 적용되는지 결정됩니다:

제거됨: 프로젝트 .mcp.json 또는 플러그인의 서버, 프로젝트 또는 --add-dir 디렉토리의 에이전트 파일의 인라인 서버
제거되지 않음: 사용자 또는 로컬 범위의 서버, 관리형 MCP, claude.ai 커넥터, SDK 또는 --mcp-config에서 제공되는 서버, ~/.claude/agents/, 관리형 설정 또는 --agents로 전달되는 에이전트 파일의 인라인 서버

Git의 GIT_CONFIG_KEY_<n> 변수를 제외하고 Claude Code는 TOKEN, SECRET, PASSWORD, KEY 또는 AUTH가 포함된 이름과 같이 자격 증명처럼 보이는 이름을 가진 환경의 모든 변수를 제거합니다 (대소문자 모두). ANTHROPIC_API_KEY와 MY_REGISTRY_TOKEN 모두 제거됩니다. Claude Code는 또한 ANTHROPIC_CUSTOM_HEADERS와 같이 해당 패턴을 따르지 않는 이름의 고정 자격 증명 변수 목록을 제거합니다.

이것이 헬퍼에 적용되면 스크립트가 파일 또는 자격 증명 저장소에서 자격 증명을 읽도록 합니다. 서버의 url이 이러한 변수 중 하나를 확장하면 헬퍼가 받는 CLAUDE_CODE_MCP_SERVER_URL 값도 해당 부분이 REDACTED로 대체됩니다.

headersHelper가 실행되기 전에 폴더를 신뢰합니다

Claude Code는 headersHelper를 임의의 셸 명령으로 실행합니다. 프로젝트 .mcp.json 또는 로컬 범위의 서버의 경우 서버가 선언된 프로젝트 디렉토리에 대한 신뢰 대화 상자를 수락한 후에만 헬퍼를 실행합니다. v2.1.238 이전에는 claude -p 또는 SDK 세션이 신뢰를 확인하지 않고 이러한 헬퍼를 실행했으며, 대화형 세션은 부모 폴더를 신뢰한 후 한 번 실행했습니다.

신뢰하지 않는 것: 부모 폴더의 신뢰, 그리고 설정 파일의 hooks에 대해 claude -p 또는 SDK 세션이 받는 자동 신뢰
폴더를 신뢰할 때까지: Claude Code는 정적 headers만으로 서버를 연결합니다. claude -p 또는 SDK 세션에서 stderr에 서버당 하나의 headersHelper not run 줄을 출력하여 신뢰를 부여하는 방법을 알려줍니다.
대화 상자 없이 신뢰: ~/.claude.json에서 projects["<path>"].hasTrustDialogAccepted를 true로 설정합니다. <path>는 프로젝트 허용 규칙 및 작업 공간 신뢰가 Claude Code가 신뢰를 기반으로 하는 폴더입니다.

Claude Code는 에이전트 파일에 인라인으로 선언된 서버에 동일한 규칙을 적용하여 해당 에이전트 파일이 어디에서 왔는지 확인합니다: 프로젝트의 경우 .claude/agents/ 디렉토리의 파일, 또는 --add-dir 디렉토리. 해당 프로젝트 또는 디렉토리 자체를 신뢰할 때까지 Claude Code는 서버를 로드하지 않으므로 헬퍼도 실행되지 않습니다.

JSON 구성에서 MCP 서버 추가

MCP 서버에 대한 JSON 구성이 있는 경우 직접 추가할 수 있습니다:

JSON에서 MCP 서버 추가

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

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

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

# 예: 사전 구성된 OAuth 자격 증명으로 HTTP 서버 추가
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

서버가 추가되었는지 확인

claude mcp get weather-api

Claude Desktop에서 MCP 서버 가져오기

Claude Desktop에서 MCP 서버를 이미 구성한 경우 가져올 수 있습니다:

Claude Desktop에서 서버 가져오기

# 기본 구문 
claude mcp add-from-claude-desktop

가져올 서버 선택

명령을 실행한 후 가져올 서버를 선택할 수 있는 대화형 대화 상자가 표시됩니다.

서버가 가져와졌는지 확인

claude mcp list

claude mcp 명령을 통해 추가된 서버 이름은 문자, 숫자, 하이픈 및 언더스코어만 포함할 수 있습니다. Claude Desktop은 해당 제한을 적용하지 않으므로 공백과 같은 다른 문자를 포함하는 이름의 Claude Desktop 서버는 가져올 수 없습니다. 가져오기는 거부된 각 이름을 보고하며 선택한 다른 서버는 계속 가져옵니다. v2.1.205 이전에는 첫 번째 잘못된 이름이 가져오기를 중지했으며 선택한 서버 중 어느 것도 추가되지 않았습니다.

claude.ai에서 MCP 서버 사용

claude.ai 계정으로 Claude Code에 로그인한 경우, claude.ai에서 추가한 MCP 서버(커넥터라고 함)가 Claude Code에서 자동으로 사용 가능합니다:

claude.ai에서 MCP 서버 구성

claude.ai/customize/connectors에서 서버를 추가합니다. Team 및 Enterprise 플랜에서는 관리자만 서버를 추가할 수 있습니다.

MCP 서버 인증

claude.ai에서 필요한 인증 단계를 완료합니다.

Claude Code에서 서버 보기 및 관리

Claude Code에서 다음 명령을 사용합니다:

/mcp

claude.ai의 서버는 claude.ai에서 온 것을 나타내는 표시기와 함께 목록에 나타납니다.

조직이 claude.ai에서 인증을 관리할 때 Claude Code는 커넥터를 /mcp와 /plugin 관리자에서 managed로 표시합니다. Managed 상태는 Claude Code가 커넥터에 연결하는 방식이나 조직의 도구 제어를 적용하는 방식을 변경하지 않습니다.

한 번도 로그인하지 않은 커넥터는 claude.ai 섹션의 끝에 있는 Show unused connectors 행 뒤에 축소되므로 조직에서 제공한 목록이 패널을 채우지 않습니다. 행을 선택하여 확장합니다. 이전에 로그인한 커넥터는 현재 재인증이 필요한 경우에도 계속 표시됩니다.

claude.ai의 커넥터는 활성 인증 방법이 claude.ai 구독 로그인일 때만 가져옵니다. 다음의 경우 이전에 /login을 실행했더라도 로드되지 않습니다:

ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN 또는 apiKeyHelper가 활성 상태
Amazon Bedrock 또는 Google Cloud의 Agent Platform과 같은 타사 제공자가 활성 상태
ANTHROPIC_PROFILE, 페더레이션 변수 또는 활성 Anthropic 프로필이 자격 증명을 제공
CLAUDE_CODE_OAUTH_TOKEN이 claude setup-token의 토큰을 보유 중(모델 요청만 수행 가능)

/mcp에 추가한 커넥터가 나열되지 않으면 /status를 실행하여 활성 인증 방법을 확인합니다. 해당 환경 변수를 설정 해제하거나 apiKeyHelper 설정을 제거하거나 프로필을 끕니다. 그런 다음 /login을 실행하여 claude.ai 계정을 선택합니다.

임시 네트워크 문제로 인해 세션 시작 시 커넥터 목록이 로드되지 않으면 Claude Code는 백그라운드에서 최대 3회까지 가져오기를 다시 시도하며, 재시도가 성공하면 커넥터가 나타납니다. 여전히 나타나지 않으면 Claude Code를 다시 시작하여 목록을 다시 가져옵니다.

/mcp에 커넥터가 connected · session token rejected로 표시되거나 세부 정보 보기에 claude.ai rejected the session token이 표시되면 claude.ai가 Claude Code 로그인의 토큰을 거부한 것입니다. 일반적으로 로그인이 만료되어 새로 고칠 수 없기 때문입니다. 커넥터를 다시 인증해도 이 상태가 지워지지 않습니다. 커넥터 자체의 인증이 거부된 것이 아니기 때문입니다. 이를 지우려면:

/login을 실행하여 다시 로그인합니다.
/mcp에서 커넥터를 다시 연결합니다.

v2.1.222 이전에는 Claude Code가 커넥터를 인증이 필요한 것으로 표시했으며, 이를 인증해도 해결되지 않았습니다.

Claude Code에서 추가한 서버는 동일한 URL을 가리키는 claude.ai 커넥터보다 우선합니다. 이 경우 /mcp는 커넥터를 숨김으로 나열하고 중복을 제거하려면 어떻게 해야 하는지 보여줍니다.

Microsoft 365, Gmail 및 Google Calendar와 같은 일부 Anthropic 호스팅 커넥터는 업스트림 ID 제공자가 claude.ai가 등록한 리디렉션 URL만 허용하기 때문에 Claude Code의 로컬 OAuth를 지원하지 않습니다. claude mcp add 또는 .mcp.json에서 추가한 서버가 이러한 호스트 중 하나를 가리키고 /mcp에서 또는 claude mcp login으로 로그인하면 Claude Code는 is Anthropic-hosted and doesn't support local OAuth를 표시하여 대신 claude.ai/customize/connectors에서 서비스를 연결하도록 지시합니다.

claude mcp remove <name>으로 항목을 제거하고 claude.ai에서 서비스를 연결한 후 커넥터가 Claude Code에 자동으로 나타납니다.

커넥터가 Claude Code에 도달하는 방식

claude.ai 커넥터를 제어하는 설정은 세션이 실행되는 위치에 따라 달라집니다. 일부 세션만 claude.ai에서 커넥터를 가져오기 때문입니다. 아래의 각 행은 한 종류의 세션에서 커넥터가 도착하는 방식과 그곳에서 이를 제어하는 것을 이름 지정합니다. 데스크톱 앱의 WSL 세션은 아직 커넥터를 사용할 수 없으므로 행이 없습니다.

세션이 실행되는 위치	커넥터가 도착하는 방식	이를 제어하는 것
Terminal, VS Code, JetBrains 및 Agent SDK 세션	Claude Code가 claude.ai에서 가져옴	이 섹션의 설정 및 관리형 MCP 구성
클라우드 세션	원격 호스트가 전달	claude.ai 조직 설정, 그리고 세션에 도달하는 허용 목록 및 거부 목록 설정 및 이를 실행하는 호스트의 모든 `managed-mcp.json`
데스크톱 앱의 로컬 및 SSH 세션	데스크톱 앱이 프로세스 내에서 전달	조직의 커넥터 도구 제어의 `blocked` 항목

disableClaudeAiConnectors, ENABLE_CLAUDEAI_MCP_SERVERS 및 allowAllClaudeAiMcps는 첫 번째 행(Claude Code가 자체적으로 가져오는 커넥터)에만 작용합니다. 다른 두 행은 다음과 같은 방식으로 다릅니다:

클라우드 세션: 세션에 도달하는 allowedMcpServers 및 deniedMcpServers 항목(예: 서버 관리 설정을 통해)도 전달된 커넥터를 필터링합니다. 세션의 프록시는 각 커넥터의 URL을 다시 작성하므로 커넥터 자체의 URL에 대해 작성된 serverUrl 패턴은 일치하지 않습니다. 자체 호스팅 환경에서 URL 허용 목록과 함께 전달된 커넥터를 허용하려면 커넥터 트래픽이 네트워크를 떠남 아래에 나열된 serverUrl 항목을 추가합니다. Claude Code는 자체 호스팅 실행기 호스트와 같이 세션을 실행하는 호스트에 managed-mcp.json이 있을 때 전달된 커넥터를 삭제합니다. allowAllClaudeAiMcps를 설정했는지 여부와 관계없이 말입니다.
데스크톱 앱 로컬 및 SSH 세션: 데스크톱 앱은 커넥터를 프로세스 내 type: "sdk" 서버로 등록하며, MCP 설정이나 managed-mcp.json이 이에 도달하지 않습니다. 사용자는 claude.ai/customize/connectors에서 연결을 끊어 자신의 세션에서 커넥터를 제외합니다. 조직은 커넥터의 도구를 차단하거나 데스크톱 앱에서 Claude Code를 완전히 끕니다.

커넥터 도구에 대한 조직 제어

조직은 claude.ai 커넥터에 도구별 제어를 설정할 수 있습니다. Claude Code는 시작 시 이러한 설정을 읽고 로컬에서 적용합니다. 단, 데스크톱 앱의 로컬 및 SSH 세션은 예외입니다. 거기서 데스크톱 앱은 커넥터를 전달하기 전에 blocked 도구를 보류하며, ask 설정은 Claude Code에 도달하지 않으므로 모든 호출에서 프롬프트하는 대신 세션의 일반 권한 규칙을 해당 도구에 적용합니다. Claude Code가 자체적으로 커넥터를 가져오는 세션에서는 /mcp를 실행하여 커넥터의 각 도구에 적용되는 설정을 확인합니다.

도구가 ask로 설정됨: Claude Code는 Your organization requires approval for this tool 이유로 모든 호출에서 프롬프트합니다. 프롬프트는 acceptEdits, auto 및 bypassPermissions 권한 모드에서도 나타나며 선택을 기억하는 옵션을 제공하지 않습니다. 도구와 일치하는 허용 규칙도 프롬프트를 건너뛰지 않습니다. 프롬프트를 하지 않는 dontAsk 모드에서 Claude Code는 호출을 거부합니다.
도구가 blocked로 설정됨: Claude Code는 Claude가 보기 전에 도구를 필터링하므로 도구 목록에 나타나지 않습니다. 데스크톱 앱과 claude.ai 채팅은 동일한 blocked 설정을 적용하므로 Claude는 거기서도 도구를 사용할 수 없으며, 데스크톱 앱의 세션에서 도구를 보류하면서 채팅에서 사용 가능하게 유지할 수 없습니다. 데스크톱 앱은 모든 도구가 차단된 커넥터를 건너뜁니다.

claude.ai 커넥터 비활성화

Claude Code는 disableClaudeAiConnectors를 자체적으로 가져오는 커넥터에만 적용하며, 클라우드 호스트 또는 데스크톱 앱이 전달하는 커넥터에는 적용하지 않습니다. 가져오는 커넥터를 끄려면 설정을 모든 설정 범위에서 true로 설정합니다:

{
  "disableClaudeAiConnectors": true
}

이 설정은 any-source-true 의미론을 사용합니다: 모든 설정 소스의 true가 우선합니다. 체크인된 프로젝트 .claude/settings.json은 Claude Code가 자체적으로 가져오는 커넥터를 저장소에서 제외할 수 있지만, 프로젝트 수준 false는 사용자 또는 정책 수준 true가 비활성화한 커넥터를 다시 활성화할 수 없습니다. --mcp-config를 통해 명시적으로 전달된 서버는 영향을 받지 않습니다.

ENABLE_CLAUDEAI_MCP_SERVERS 환경 변수를 false로 설정할 수도 있습니다. 이는 현재 셸 세션에 대해 동일한 효과를 갖습니다:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

모든 claude.ai 커넥터를 차단하는 대신 개별 커넥터를 차단하려면 이름 또는 URL 패턴으로 deniedMcpServers에 추가합니다. 예를 들어, serverName 항목 "claude.ai Slack"은 Slack 커넥터를 차단합니다. /mcp를 실행하여 Claude Code가 현재 프로젝트에만 가져오는 모든 커넥터를 켜거나 끌 수도 있습니다.

Claude Code를 MCP 서버로 사용하기

Claude Code 자체를 다른 애플리케이션이 연결할 수 있는 MCP 서버로 사용할 수 있습니다:

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

이 명령은 시작할 때 아무것도 출력하지 않습니다. stdio MCP 서버는 stdin과 stdout을 통해 통신하므로, 침묵하고 차단된 터미널은 서버가 실행 중이며 클라이언트의 연결을 기다리고 있다는 의미입니다.

claude_desktop_config.json에 다음 구성을 추가하여 Claude Desktop에서 이를 사용할 수 있습니다:

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

Warning

실행 파일 경로 구성: command 필드는 Claude Code 실행 파일을 참조해야 합니다. claude 명령이 시스템의 PATH에 없으면 실행 파일의 전체 경로를 지정해야 합니다.

전체 경로를 찾으려면:

which claude

그런 다음 구성에서 전체 경로를 사용합니다:

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

올바른 실행 파일 경로가 없으면 spawn claude ENOENT와 같은 오류가 발생합니다.

MCP 출력 제한 및 경고

MCP 도구가 대용량 출력을 생성할 때, Claude Code는 토큰 사용량을 관리하여 대화 컨텍스트가 압도되지 않도록 도움을 줍니다:

출력 경고 임계값: Claude Code는 MCP 도구 출력이 10,000 토큰을 초과할 때 경고를 표시합니다
구성 가능한 제한: MAX_MCP_OUTPUT_TOKENS 환경 변수를 사용하여 최대 허용 MCP 출력 토큰을 조정할 수 있습니다
기본 제한: 기본 최댓값은 25,000 토큰입니다
범위: 환경 변수는 자체 제한을 선언하지 않은 도구에 적용됩니다. anthropic/maxResultSizeChars를 설정한 도구는 MAX_MCP_OUTPUT_TOKENS가 무엇으로 설정되어 있든 관계없이 텍스트 콘텐츠에 대해 해당 값을 대신 사용합니다. 이미지 데이터를 반환하는 도구는 여전히 MAX_MCP_OUTPUT_TOKENS의 적용을 받습니다
제한 초과: 이미지 콘텐츠가 없는 결과가 제한을 초과하면, Claude Code는 이를 파일에 저장하고 대화에서 파일 경로를 이름으로 하는 메시지로 대체하므로, Claude는 필요할 때 파일을 읽습니다. 파일은 ~/.claude/projects/ 아래의 세션의 tool-results 디렉터리에 저장됩니다.

대용량 출력을 생성하는 도구의 제한을 늘리려면:

export MAX_MCP_OUTPUT_TOKENS=50000
claude

특정 도구의 제한 늘리기

MCP 서버를 구축하는 경우, 도구의 tools/list 응답 항목에서 _meta["anthropic/maxResultSizeChars"]를 설정하여 개별 도구가 기본 디스크 저장 임계값보다 큰 결과를 반환하도록 허용할 수 있습니다. Claude Code는 해당 도구의 임계값을 주석 처리된 값으로 올립니다. 단, 500,000자의 하드 상한선까지입니다.

이는 데이터베이스 스키마나 전체 파일 트리와 같이 본질적으로 크지만 필요한 출력을 반환하는 도구에 유용합니다. 주석 처리 없이 기본 임계값을 초과하는 결과는 디스크에 저장되고 대화에서 파일 참조로 대체됩니다.

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

주석 처리는 텍스트 콘텐츠에 대해 MAX_MCP_OUTPUT_TOKENS와 독립적으로 적용되므로, 사용자는 이를 선언한 도구에 대해 환경 변수를 올릴 필요가 없습니다. 이미지 데이터를 반환하는 도구는 여전히 토큰 제한의 적용을 받습니다.

루트 레벨 결합자가 있는 도구 입력 스키마

일부 MCP 서버는 도구의 입력 스키마를 JSON Schema 합집합으로 선언하며, 스키마의 최상위 레벨에 anyOf, oneOf 또는 allOf를 포함합니다. Claude API는 스키마 루트에서 이러한 키워드를 허용하지 않습니다. 이는 properties 내에 중첩된 결합자를 허용하며, Claude Code는 이를 변경하지 않고 전송합니다.

루트 레벨 결합자가 있는 도구는 계속 사용 가능합니다. 도구를 API로 전송하기 전에 Claude Code는 스키마를 단일 객체로 평탄화하고 도구의 설명 앞에 어느 매개변수 그룹이 함께 속하는지 Claude에게 알려주는 문장을 추가합니다:

allOf: 모든 분기의 속성이 병합되며, 각 분기의 required 목록은 여전히 적용됩니다
anyOf 및 oneOf: 모든 분기의 속성이 병합되며, 각 분기의 required 목록은 스키마에 의해 강제되지 않고 도구 설명에 설명됩니다

서버는 Claude가 선택한 인수를 수신하므로 서버 측에서 조합을 계속 검증하십시오.

Claude Code가 API가 허용하는 스키마를 생성할 수 없거나 스키마 재작성을 활성화하는 원격 구성을 받지 않는 배포에서는 해당 도구 하나를 건너뛰고, 서버의 로그에 이유를 기록하며, 서버의 다른 도구는 사용 가능하게 유지합니다. v2.1.195보다 이전 버전은 입력 스키마에 루트 레벨 anyOf, oneOf 또는 allOf가 있는 모든 도구를 건너뜁니다.

유효하지 않은 입력 스키마를 가진 도구

Claude API는 요청의 모든 도구의 입력 스키마를 확인하고 하나의 스키마라도 실패하면 전체 요청을 거부하므로, 형식이 잘못된 스키마를 가진 단일 MCP 도구가 있으면 이를 포함하는 모든 요청이 400 오류로 실패합니다. Claude Code는 서버의 도구를 로드할 때 API의 확인 중 두 가지를 직접 실행하고 이를 실패할 각 도구를 제외하므로, 서버의 다른 도구는 계속 작동합니다:

최상위 속성 이름은 1~64자 길이여야 하며 ASCII 문자와 숫자, _, ., -만 사용해야 합니다
스키마는 JSON Schema draft 2020-12 메타스키마에 대해 유효해야 합니다. Claude Code는 $schema를 선언하지 않는 스키마와 draft 2020-12를 선언하는 스키마에 이 확인을 적용합니다. 다른 방언을 선언하는 스키마는 이 확인을 건너뛰지만, 위의 속성 이름 확인은 여전히 적용됩니다

Claude Code는 루트 수준 결합자 재작성 후에 확인을 실행하며, 실제로 전송할 스키마에 대해 실행합니다.

Claude Code가 도구를 제외할 때, 서버의 로그에 이유를 기록하고 제외된 도구와 그 이유를 Claude에 알리므로, Claude에 도구가 누락된 이유를 물어볼 수 있습니다. 서버에서 스키마를 수정하면, Claude Code가 다음에 서버의 도구를 로드할 때 도구가 다시 나타납니다.

Claude Code는 Anthropic에서 가져오는 기능 플래그를 통해 제외를 켭니다. 플래그 가져오기가 꺼진 배포에서 또는 에어갭 머신과 같이 플래그가 도착한 적이 없는 머신에서, Claude Code는 여전히 확인을 실행하고 서버의 로그에 어떤 도구가 거부될 것인지 기록하지만, 도구의 스키마를 API로 어쨌든 전송합니다. API는 도구를 위치로 이름 지은 400 오류로 해당 스키마를 포함하는 요청을 거부합니다. v2.1.216 이전에는 배포가 이러한 확인을 실행하지 않았습니다.

루트 수준 결합자 처리는 별개이며 플래그 가져오기가 꺼져 있거나 플래그가 도착한 적이 없을 때 자체 동작을 유지합니다.

특정 도구에 대한 승인 필요

MCP 서버를 구축하는 경우, 도구의 tools/list 응답 항목에서 _meta["anthropic/requiresUserInteraction"]을 true로 설정하여 도구가 모든 호출에서 명시적 승인을 요구하도록 표시할 수 있습니다. 값은 JSON 부울 true여야 하며, 다른 값은 무시됩니다.

Claude Code는 acceptEdits, auto, bypassPermissions 권한 모드에서도 모든 호출에 대해 해당 도구의 권한 프롬프트를 표시하며, "다시 묻지 않기" 옵션을 제공하지 않습니다. 도구와 일치하는 허용 규칙도 프롬프트를 건너뛰지 않습니다. 절대 프롬프트를 표시하지 않는 dontAsk 모드에서는 Claude Code가 호출을 거부합니다.

프롬프트는 사람에게 도달해야 합니다. --permission-prompt-tool을 사용하는 비대화형 모드에서, 플래그된 도구에 대한 프롬프트 도구의 allow 결과는 MCP tool requires user interaction; not supported via --permission-prompt-tool 메시지와 함께 거부로 변환됩니다. Agent SDK의 canUseTool 콜백은 이러한 호출을 수신하고 승인할 수 있습니다. SDK 애플리케이션이 사용자에게 이를 표시할 것으로 예상되기 때문입니다.

동의 또는 액세스 부여 단계와 같이 권한 프롬프트 자체가 목적인 도구에 이를 사용하십시오. 자동 승인은 인간이 절대 동의하지 않음을 의미합니다. 동일한 서버의 다른 도구는 일반적인 권한 동작을 유지합니다.

다음 tools/list 항목은 한 도구를 항상 승인이 필요한 것으로 표시합니다.

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

anthropic/requiresUserInteraction 주석은 Claude Code v2.1.199 이상이 필요합니다. 이전 버전은 이를 무시하고 표준 권한 흐름을 적용합니다.

Remote Control 및 Agent SDK를 기반으로 구축된 애플리케이션과 같은 일부 표면에서는 일반적으로 한 번의 탭으로 도구 호출을 승인할 수 있습니다. 이 주석으로 표시된 도구의 경우, Claude Code는 한 번의 탭 작업을 보류하고 도구의 전체 권한 프롬프트를 대신 표시하므로, 승인은 탭이 아닌 프롬프트에 응답하는 사람으로부터 나옵니다.

Claude Code는 터미널 대화 상자에서만 완전히 렌더링할 수 있는 모든 권한 요청(예: 안전 경고 또는 원격 표면이 표시할 수 없는 항상 허용 옵션을 포함하는 요청)에 대해 동일한 방식으로 한 번의 탭 승인을 보류합니다. 해당 요청에 Remote Control이 아닌 터미널 대화 상자에서 응답합니다. Claude Code v2.1.214 이상이 필요합니다.

MCP 유도 요청에 응답하기

MCP 서버는 작업 중에 유도(elicitation)를 사용하여 구조화된 입력을 요청할 수 있습니다. 서버가 자체적으로 얻을 수 없는 정보가 필요할 때, Claude Code는 대화형 대화 상자를 표시하고 사용자의 응답을 서버에 다시 전달합니다. 사용자 측에서 구성할 필요가 없습니다. 유도 대화 상자는 서버가 요청할 때 자동으로 나타납니다.

서버는 두 가지 방식으로 입력을 요청할 수 있습니다.

양식 모드: Claude Code는 서버에서 정의한 양식 필드가 있는 대화 상자를 표시합니다(예: 사용자 이름 및 암호 프롬프트). 필드를 채우고 제출합니다.
URL 모드: Claude Code는 인증 또는 승인을 위해 브라우저 URL을 엽니다. 브라우저에서 흐름을 완료한 후 CLI에서 확인합니다.

URL 모드에서 Claude Code는 URL을 명령줄 인수로 시스템의 URL 핸들러에 전달하며, 해당 인수의 길이를 제한합니다. URL이 명령줄에 대해 이스케이프된 후 해당 제한을 초과하면 요청을 거부할 수만 있습니다. % 또는 &와 같이 이스케이프해야 하는 모든 문자는 제한에 대해 4배로 계산됩니다. 즉, 자신의 문자와 3개의 이스케이프 문자입니다. 이들이 없는 URL은 약 8,000자에서 제한에 도달합니다. 대부분 퍼센트 이스케이프로 구성된 URL(3번째 문자마다 %가 있는 경우)은 대략 4,000에서 도달합니다.

유도 요청에 대화 상자를 표시하지 않고 자동으로 응답하려면 Elicitation hook을 사용합니다.

유도를 사용하는 MCP 서버를 구축하는 경우, 프로토콜 세부 정보 및 스키마 예제는 MCP 유도 사양을 참조합니다.

MCP 리소스 사용

MCP 서버는 파일을 참조하는 방식과 유사하게 @ 멘션을 사용하여 참조할 수 있는 리소스를 노출할 수 있습니다.

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 서버를 추가해도 컨텍스트 윈도우에 미치는 영향이 최소화됩니다. Claude Code는 서버당 고정된 도구 상한을 부과하지 않으며, 실질적인 제한은 컨텍스트 윈도우 예산입니다.

MCP 서버 작성자를 위한 정보

MCP 서버를 구축하는 경우, 도구 검색이 활성화되면 서버 지침 필드가 더욱 유용해집니다. 서버 지침은 Claude가 도구를 검색할 시기를 이해하는 데 도움이 되며, 기술이 작동하는 방식과 유사합니다.

다음을 설명하는 명확하고 설명적인 서버 지침을 추가하세요:

도구가 처리하는 작업의 범주
Claude가 도구를 검색해야 할 시기
서버가 제공하는 주요 기능

Claude Code는 각 도구 설명과 각 서버의 지침을 기본적으로 2,048자에서 자릅니다. 간결하게 유지하고 중요한 세부 정보를 시작 부분에 배치하세요.

세션의 모든 MCP 서버에 대한 제한을 변경하려면 CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH를 문자 수로 설정하세요. 이 변수는 Claude Code v2.1.280 이상이 필요합니다.

도구 검색 구성

도구 검색은 기본적으로 활성화됩니다. MCP 도구는 연기되고 필요에 따라 발견됩니다. Claude Code는 ANTHROPIC_BASE_URL이 비자사 호스트를 가리킬 때 이를 비활성화합니다. 대부분의 프록시가 tool_reference 블록을 전달하지 않기 때문입니다. 해당 폴백을 재정의하려면 ENABLE_TOOL_SEARCH를 명시적으로 설정하세요.

CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS를 설정하면 도구 검색이 꺼집니다. ENABLE_TOOL_SEARCH를 직접 설정하여 재정의할 수 없습니다. 조직은 Claude Code v2.1.227 이상에서 관리 설정을 통해 도구 검색을 계속 활성화할 수 있습니다. 사전 릴리스 기능 비활성화는 재정의가 적용되는 위치와 변수가 제거하는 항목을 다룹니다.

도구 검색에는 tool_reference 블록을 지원하는 모델이 필요합니다. Claude Sonnet 4.5, Claude Haiku 4.5, Claude Opus 4.5 및 이후 모델입니다. 현재 목록은 API 문서의 모델 호환성을 참조하세요.

Google Cloud의 Agent Platform에서 Claude Code는 모델 세대별로 결정합니다:

Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 및 이후 모델: 도구 검색은 기본적으로 활성화되며, Anthropic API와 동일합니다.
이전 Agent Platform 모델: Claude Code는 필요한 베타 헤더를 거부하는 서빙 스택 때문에 모든 MCP 도구를 미리 로드합니다. ENABLE_TOOL_SEARCH=true는 이를 재정의하지 않습니다.

v2.1.221 이전에는 Claude Code가 ENABLE_TOOL_SEARCH=true를 설정하지 않는 한 Google Cloud의 Agent Platform의 모든 모델에 대해 도구 검색을 비활성화했습니다.

ENABLE_TOOL_SEARCH 환경 변수로 도구 검색 동작을 제어하세요:

값	동작
(설정 안 함)	모든 MCP 도구가 연기되고 필요에 따라 로드됩니다. Google Cloud의 Agent Platform 모델이 Claude 4.5 세대보다 이전이거나, `ANTHROPIC_BASE_URL`이 비자사 호스트이거나, Microsoft Foundry 배포가 Azure에서 호스팅될 때 미리 로드로 폴백됩니다
`true`	모든 MCP 도구가 연기됩니다. 단, Microsoft Foundry 배포가 Azure에서 호스팅될 때는 서버 측 거부가 여전히 미리 로드를 강제하고, Google Cloud의 Agent Platform 모델이 Claude 4.5 세대보다 이전일 때는 Claude Code가 도구를 미리 로드합니다. Claude Code는 프록시를 통해 베타 헤더를 전송하며, `tool_reference` 블록을 지원하지 않는 프록시에서는 요청이 실패합니다
`auto`	임계값 모드: Claude Code는 정의가 컨텍스트 윈도우의 10% 미만일 때 연기할 도구를 미리 로드하고, 정의가 10%에 도달하면 모두 연기합니다
`auto:N`	사용자 정의 백분율이 있는 임계값 모드. `N`은 0-100입니다. 예를 들어 5%의 경우 `auto:5`
`false`	모든 MCP 도구가 미리 로드되고, 연기 없음

# 사용자 정의 5% 임계값 사용
ENABLE_TOOL_SEARCH=auto:5 claude

# 도구 검색 완전히 비활성화
ENABLE_TOOL_SEARCH=false claude

또는 settings.json env 필드에서 값을 설정하세요.

ToolSearch 도구를 특별히 비활성화할 수도 있습니다:

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

서버를 연기에서 제외

서버의 도구가 항상 검색 단계 없이 Claude에게 표시되어야 하는 경우, 해당 서버의 구성에서 alwaysLoad를 true로 설정하세요. 그러면 해당 서버의 모든 도구가 ENABLE_TOOL_SEARCH 설정과 관계없이 세션 시작 시 컨텍스트에 로드됩니다. 각 미리 로드된 도구가 대화에 사용할 수 있는 컨텍스트를 소비하므로, Claude가 모든 턴에서 필요한 적은 수의 도구에 이를 사용하세요.

다음 .mcp.json 항목은 다른 서버는 연기된 상태로 두고 하나의 HTTP 서버를 제외합니다:

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

alwaysLoad 필드는 모든 서버 유형에서 사용 가능합니다. MCP 서버는 도구의 _meta 객체에 "anthropic/alwaysLoad": true를 포함하여 개별 도구를 항상 로드되도록 표시할 수도 있으며, 이는 해당 도구에만 동일한 효과를 갖습니다.

alwaysLoad: true를 설정하면 시작 시 서버의 도구를 기다리게 되며, 첫 번째 프롬프트가 구축될 때 도구가 있어야 하므로 표준 5초 연결 타임아웃으로 제한됩니다. 유효한 cached 항목이 있는 원격 서버는 연결하지 않고 캐시에서 도구를 제공하므로 시작을 지연시키지 않습니다. 다른 서버는 기본적으로 백그라운드에서 연결됩니다. MCP_CONNECTION_NONBLOCKING=0을 설정하여 시작이 이들을 기다리도록 하세요.

MCP 프롬프트를 명령어로 사용하기

MCP 서버는 Claude Code에서 명령어로 사용 가능한 프롬프트를 노출할 수 있습니다.

MCP 프롬프트 실행하기

사용 가능한 프롬프트 발견하기

/를 입력하여 MCP 서버의 프롬프트를 포함한 사용 가능한 명령어를 확인합니다. Claude Code는 각 MCP 프롬프트를 /servername:promptname (MCP) 형식으로 나열합니다. /mcp__servername__promptname을 입력하여 실행할 수도 있습니다.

인수 없이 프롬프트 실행하기

/mcp__github__list_prs

인수를 포함하여 프롬프트 실행하기

많은 프롬프트는 인수를 허용합니다. 명령어 뒤에 공백으로 구분된 인수를 전달합니다. Claude Code는 공백을 기준으로 인수를 분할하므로 각 인수는 단일 토큰입니다:

/mcp__github__pr_review 456

/mcp__jira__create_issue login-bug high

관리형 MCP 구성

조직에서 사용자가 연결할 수 있는 MCP 서버를 중앙에서 제어해야 하는 경우 관리형 MCP 구성을 참조하십시오. 이 문서에서는 managed-mcp.json으로 고정 서버 세트를 배포하고, managedMcpServers로 모든 사용자에게 서버를 제공하며, allowedMcpServers 및 deniedMcpServers로 서버를 제한하고, 서버가 차단되었을 때 사용자에게 표시되는 내용을 다룹니다.

mcp.md 2026-09-22 23:59 UTC to 2026-09-23 23:57 UTC

MCP를 통해 Claude Code를 도구에 연결하기

MCP로 할 수 있는 것

MCP 서버 찾기 및 구축

플러그인 설치

빌드 스킬 실행

MCP 서버 설치

옵션 1: 원격 HTTP 서버 추가

옵션 2: 원격 SSE 서버 추가

옵션 3: 로컬 stdio 서버 추가

옵션 4: 원격 WebSocket 서버 추가

다른 클라이언트용으로 작성된 설정 지침에서 서버 추가

URL에서

`npx`, `uvx` 또는 바이너리 명령에서

`mcpServers` JSON 블록에서

서버 관리

서버 상태

프로젝트 서버 승인 및 작업 영역 신뢰

서버 상태 세부 정보

구성 경고

도구 가용성

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

MCP 클라이언트 런타임

동적 도구 업데이트

v2 런타임의 알림 스트림

자동 재연결

원격 서버의 세션 중 연결 끊김

실패한 첫 연결

실패한 검색 요청

Claude가 서버 실패를 배우는 방법

채널을 사용한 메시지 푸시

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

플러그인 제공 MCP 서버

MCP 설치 범위

로컬 범위

프로젝트 범위

사용자 범위

범위 계층 및 우선순위

`.mcp.json`의 환경 변수 확장

지원되는 구문

확장 위치

변수 확장을 사용한 예

기본값이 없는 설정되지 않은 변수

빈 값으로 읽히는 자격 증명 변수

`/mcp` 및 CLI 출력에서 참조가 표시되는 방식

실제 예

예: 코드 검토를 위해 GitHub에 연결

예: PostgreSQL 데이터베이스 쿼리

원격 MCP 서버로 인증

인증이 필요한 서버 추가

Claude Code 내에서 /mcp 명령 사용

명령줄에서 인증

고정 OAuth 콜백 포트 사용

사전 구성된 OAuth 자격 증명 사용

서버로 OAuth 앱 등록

자격 증명으로 서버 추가

Claude Code에서 인증

OAuth 메타데이터 검색 재정의

OAuth 범위 제한

사용자 정의 인증을 위한 동적 헤더 사용

헬퍼가 실행되는 위치

헬퍼가 읽을 수 있는 변수

headersHelper가 실행되기 전에 폴더를 신뢰합니다

JSON 구성에서 MCP 서버 추가

JSON에서 MCP 서버 추가

서버가 추가되었는지 확인

Claude Desktop에서 MCP 서버 가져오기

Claude Desktop에서 서버 가져오기

가져올 서버 선택

서버가 가져와졌는지 확인

claude.ai에서 MCP 서버 사용

claude.ai에서 MCP 서버 구성

MCP 서버 인증

Claude Code에서 서버 보기 및 관리

커넥터가 Claude Code에 도달하는 방식

커넥터 도구에 대한 조직 제어

claude.ai 커넥터 비활성화

Claude Code를 MCP 서버로 사용하기

MCP 출력 제한 및 경고

특정 도구의 제한 늘리기