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

​

MCP로 할 수 있는 것

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

​

MCP 서버 찾기 및 구축

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

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

​

MCP 서버 설치

​

옵션 1: 원격 HTTP 서버 추가

# 기본 구문
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"

​

옵션 2: 원격 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 서버 추가

# 기본 구문
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

​

Claude Code가 stdio 서버를 중지하는 방법

• macOS 및 Linux: Claude Code는 SIGINT를 보내고, 100밀리초 후에도 프로세스가 실행 중이면 SIGTERM을, 그로부터 400밀리초가 더 지나면 SIGKILL을 보냅니다.
• Windows: Claude Code는 서버의 stdin을 닫고, 300밀리초 후에도 프로세스가 실행 중이면 서버의 프로세스 트리를 종료합니다.

​

옵션 4: 원격 WebSocket 서버 추가

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

​

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

• URL (예: https://mcp.example.com/mcp): 서버는 원격입니다.
• 시작 명령 (예: npx -y @example/mcp-server): 서버는 컴퓨터에서 실행됩니다.
• mcpServers JSON 블록: 다른 클라이언트의 설정 파일용으로 작성된 구성입니다.

​

URL에서 서버 추가

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

​

npx, uvx 또는 바이너리 명령에서 서버 추가

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

​

mcpServers JSON 블록에서 서버 추가

• 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"]}'

​

서버 관리

# 구성된 모든 서버 나열
claude mcp list

# 특정 서버의 세부 정보 가져오기
claude mcp get notion

# 서버 제거
claude mcp remove notion

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

​

서버 상태

• ⏸ 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 패널에서 서버를 다시 켜세요.

​

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

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

​

서버 상태 세부 정보

• 경로 및 쿼리는 해당 메시지에 나타나지 않습니다.
• 로컬, 프로젝트, 사용자 범위 또는 관리형 MCP 구성의 서버의 경우, 원점은 해당 구성에 작성된 호스트를 표시하므로 호스트의 ${VAR} 참조는 메시지에서 확장되지 않습니다.
• 상태 또는 오류 코드가 없는 실패의 경우 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 데스크톱 앱의 미리보기 창이 사용하는 기본 제공 서버의 이름입니다.
• 누락된 환경 변수: 서버 구성의 ${VAR} 참조가 설정되지 않은 변수의 이름을 지정하고 :-default가 없으면 Claude Code는 claude mcp list 출력 및 /mcp에서 경고하며, 변수의 이름을 지정하고, 여전히 ${VAR} 텍스트가 확장되지 않은 상태로 서버를 로드합니다. 변수를 설정하거나 ${VAR:-default} 폴백을 추가하세요. 원격 서버의 url 및 headers에서 일부 자격 증명 변수는 경고 없이 비어 있는 것으로 읽습니다.

​

도구 가용성

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

​

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

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

​

MCP 클라이언트 런타임

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

• HTTP, stdio 및 claude.ai 커넥터 서버에 더 새로운 개정을 지원하는지 묻고, 지원하는 서버와 함께 사용합니다. 여기에는 클라우드 세션 및 Remote Control 세션의 커넥터가 포함됩니다. 다른 모든 서버에는 v1처럼 연결합니다.
• 열린 스트림을 통해 더 새로운 개정의 서버에서 list_changed 알림을 받습니다.
• 더 새로운 개정에 연결되는 채널 서버를 등록하지 않습니다. 해당 개정은 채널 메시지를 전달할 수 없기 때문입니다.
• 인증 응답이 예상치 못한 발급자의 이름을 지정하는 MCP OAuth 로그인을 실패합니다.
• MCP OAuth 자격 증명을 HTTPS를 통해 제공되거나 localhost, 127.0.0.1 또는 ::1에서 제공되는 토큰 엔드포인트에만 보냅니다. 토큰 엔드포인트가 로컬 네트워크의 장치와 같은 다른 곳에서 일반 http://인 서버의 로그인이 실패합니다. HTTPS가 아닌 토큰 엔드포인트로 자격 증명 전송 거부를 참조하세요.

​

동적 도구 업데이트

• 대화형 터미널 세션에서는 Claude Code가 해당 서버에서 업데이트된 목록을 가져오므로 서버를 다시 연결할 필요가 없습니다.
• -p 플래그를 사용하는 비대화형 모드 및 Agent SDK에서는 Claude Code가 이러한 알림에 대해 도구 목록만 새로 고칩니다.

​

v2 런타임의 알림 스트림

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

​

자동 재연결

​

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

• 대화형 세션: /mcp는 Claude Code가 재연결하는 동안 서버를 보류 중으로 표시합니다. 5번의 실패 시도 후 Claude Code는 서버를 실패로 표시하거나 서버가 다시 인증이 필요할 때 인증 필요로 표시합니다. 실패로 표시할 때 MCP server "<name>" disconnected · open /mcp to reconnect 알림이 표시됩니다. /mcp에서 수동으로 재시도할 수 있습니다.
• claude -p 실행 및 Agent SDK 세션: Claude Code는 동일한 5번의 시도를 수행하지만, 시도를 표시할 /mcp 패널은 없습니다. 5번 모두 실패하면 서버의 도구 없이 실행이 계속됩니다:
  • 5xx 응답이나 시간 초과와 같은 일시적 오류 후: Claude Code는 HTTP 또는 SSE 서버를 백그라운드에서 계속 재시도합니다. 재시도는 최대 약 30분 동안 지속되며, 재시도로 연결되면 서버의 도구를 다시 사용할 수 있게 됩니다. 그때까지 Agent SDK 세션은 상태를 failed로 보고하며, 코드에서 서버를 다시 연결할 수 있습니다. claude -p에서 다시 연결하려면 실행을 다시 시작하세요.
  • 서버가 다시 로그인하도록 요구할 때: Claude Code는 재시도를 중지하고, Agent SDK 세션은 서버의 상태를 needs-auth로 보고합니다. 셸에서 claude mcp login <name>으로 로그인하세요. 그런 다음 실행을 다시 시작하거나, Agent SDK 세션에서는 대신 서버를 다시 연결하세요.

​

실패한 첫 연결

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

​

종료되거나 시작에 실패한 stdio 서버

​

실패한 검색 요청

​

실패한 서버 직접 재시도

​

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

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

​

채널을 사용한 메시지 푸시

​

MCP 도구 호출의 시간 제한

• 서버별: 해당 서버의 구성 항목에 밀리초 단위의 timeout 필드를 추가합니다
• 모든 서버 공통: MCP_TOOL_TIMEOUT을 설정합니다

​

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

• 임계값을 변경하려면 CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 환경 변수를 밀리초 단위로 설정하고, 자동 백그라운드 전환을 끄려면 0으로 설정합니다. 0으로 설정하면 대화형 세션에서 Claude가 MCP 작업을 기다립니다
• CLAUDE_CODE_DISABLE_BACKGROUND_TASKS를 1로 설정합니다. 이렇게 하면 백그라운드 명령 및 백그라운드 서브에이전트와 함께 자동 백그라운드 전환도 꺼집니다

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

​

서버에서 실행되는 MCP 작업

​

MCP 작업 중지 또는 결과 받기

MCP task <server task id> (<server>/<tool>) completed.

​

MCP 작업의 질문에 답변

​

MCP 작업 실행 중 종료, 지우기 또는 재개

​

호출이 MCP 작업이 되기 위한 조건

• 서버가 작업을 지원합니다
• 서버가 프로토콜 개정판 2026-07-28로 연결된 HTTP, stdio 또는 claude.ai 커넥터 서버입니다. MCP_SDK_GENERATION=v1 또는 MCP_PROTOCOL_NEGOTIATION=legacy를 설정하면 이 조건이 충족되지 않습니다
• 세션이 기능 플래그를 가져옵니다. 따라서 Amazon Bedrock과 같은 서드파티 제공업체가 아니어야 하며, 텔레메트리나 플래그 가져오기가 꺼져 있지 않아야 합니다
• Anthropic이 해당 종류의 세션에 MCP 작업을 활성화했습니다. v2.1.304 이상에서는 터미널 CLI 세션, Agent SDK 세션, GitHub Actions 실행이 포함됩니다. VS Code 확장이나 데스크톱 앱과 같은 다른 사용 환경에서는 MCP 작업을 사용할 수 없습니다
• 호출이 서브에이전트가 아니라 메인 대화에서 이루어집니다
• 세션이 대화형이거나, Agent SDK 세션 또는 --input-format stream-json을 읽는 claude -p 실행이 다음을 충족합니다.
  • CLAUDE_AUTO_BACKGROUND_TASKS가 1
  • CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND가 1이 아님
  • CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS가 0이 아님

​

MCP 작업의 상태 메시지

​

MCP 작업의 시간 제한

​

Claude가 MCP 작업의 결과를 기다리도록 설정

• CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS를 0으로 설정: Claude는 모든 MCP 도구 호출이 끝날 때까지 기다립니다
• CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND를 1로 설정: Claude는 작업의 결과를 기다립니다. 자동 백그라운드 전환이 켜져 있으면 기본적으로 2분 후에 호출을 전환하므로, 짧은 작업은 그 자리에서 끝나고 긴 작업은 사용자를 차단하지 않습니다. 전환된 호출은 MCP 작업이 아니라 일반 백그라운드 호출이며, 세션을 종료하면 유지되지 않습니다

{
  "env": {
    "CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS": "0"
  }
}

​

서버 개발자를 위한 MCP 작업

​

작업으로 호출에 응답

{
  "resultType": "task",
  "taskId": "build-7f3a9c2e",
  "status": "working",
  "statusMessage": "Compiling, 40 of 212 files done",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:03:07Z",
  "ttlMs": null,
  "pollIntervalMs": 5000
}

​

상태, 결과, 질문 보고

{
  "resultType": "complete",
  "taskId": "build-7f3a9c2e",
  "status": "completed",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:09:41Z",
  "ttlMs": null,
  "result": {
    "content": [{ "type": "text", "text": "Build succeeded: 212 files, 0 warnings" }]
  }
}

​

플러그인 제공 MCP 서버

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

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

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

• 자동 라이프사이클: 서버는 다음 지점에서 연결 및 연결 해제됩니다:
  • 세션 시작 시 Claude Code는 활성화된 플러그인의 서버를 자동으로 연결합니다. /mcp에서 이전에 사용한 원격 (HTTP 또는 SSE) 플러그인 서버는 cached 상태를 대신 표시할 수 있습니다. Claude Code는 Claude가 도구 중 하나를 처음 호출할 때 연결합니다. stdio 플러그인 서버의 연결이 15분 이내에 실패한 경우 Claude Code는 연결을 건너뜁니다.
  • 세션 중에 플러그인을 활성화하거나 비활성화하면 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
• 사용자 환경 액세스: 수동으로 구성된 서버와 동일한 환경 변수에 액세스
• 여러 전송 유형: stdio, SSE, HTTP 및 WebSocket 전송 지원. 전송 지원은 서버에 따라 다를 수 있습니다.

• stdio 서버: Command: stdio, 빈 Args: 줄, 그리고 각 환경 변수를 NAME=[REDACTED]로 인쇄합니다
• WebSocket 서버: URL: ws와 각 헤더를 <name>: [REDACTED]로 인쇄하며, claude mcp list는 URL 대신 ws를 표시합니다

mcp__plugin_my-plugin_database-tools__query

​

MCP 설치 범위

​

로컬 범위

# Add a local-scoped server (default)
claude mcp add --transport http stripe https://mcp.stripe.com

# Explicitly specify local scope
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

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

​

프로젝트 범위

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

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

• 서버를 disabledMcpjsonServers에 추가합니다. 이렇게 하면 모든 권한 모드에서 해당 서버가 차단됩니다.
• --setting-sources 또는 SDK의 settingSources 옵션으로 프로젝트 설정을 완전히 제외합니다.
• --strict-mcp-config로 세션을 시작합니다. 그러면 Claude Code는 --mcp-config로 전달한 MCP 서버만 사용합니다. Claude Code가 로드하지 않는 프로젝트 범위 서버에 대해 승인 프롬프트를 건너뛰려면 Claude Code v2.1.246 이상이 필요합니다. v2.1.246 이전에는 strict 세션에서도 해당 서버에 대한 승인을 기다렸기 때문에 백그라운드 세션이 시작 시 대기 상태로 남았습니다. 관리형 MCP 파일이 있을 때 이 플래그가 어떻게 동작하는지는 managed-mcp.json을 통한 독점 제어를 참조하세요.

​

사용자 범위

# Add a user server
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

​

범위 계층 구조와 우선순위

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

​

.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}"
      }
    }
  }
}

​

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

​

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

• ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN 등 Claude Code 자체의 자격 증명
• AWS_BEARER_TOKEN_BEDROCK 등 클라우드 제공업체의 자격 증명
• HTTPS_PROXY, NPM_TOKEN 등 환경에 포함된 기타 자격 증명

​

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

• 서버의 /mcp 세부 정보 보기에 있는 URL 또는 명령줄
• claude mcp list 및 claude mcp get 출력

​

실제 예

​

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

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

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

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

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

​

예: PostgreSQL 데이터베이스 쿼리

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

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

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

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

​

원격 MCP 서버로 인증

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

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

/mcp

​

명령줄에서 인증

claude mcp login sentry

claude mcp login sentry --no-browser

​

고정 OAuth 콜백 포트 사용

# Fixed callback port with dynamic client registration
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

​

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

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

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 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

​

OAuth 메타데이터 검색 재정의

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

​

OAuth 범위 제한

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

​

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

{
  "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를 재정의합니다.

​

헬퍼가 실행되는 위치

​

헬퍼가 읽을 수 있는 변수

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

​

headersHelper가 실행되기 전에 폴더 신뢰

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

​

헤더가 필요한 게이트웨이 뒤의 MCP 서버에 로그인

• 구성을 편집할 수 있는 서버: headers에 설정하거나 headersHelper에서 반환하세요
• 관리형 MCP 또는 플러그인이 제공하는 서버: 관리자나 플러그인 작성자에게 서버 항목에 헤더를 추가해 달라고 요청하세요

• 인가 페이지: 이 페이지에서는 브라우저로 로그인하며, 브라우저는 구성된 헤더를 보내지 않습니다. 브라우저에 페이지 대신 게이트웨이의 오류가 표시되면 게이트웨이 운영자에게 헤더 없이 페이지를 통과시켜 달라고 요청하세요.
• 다른 오리진의 인가 서버: 해당 서버 앞의 게이트웨이도 헤더를 요구하면 그곳에서 로그인이 실패합니다. 해당 게이트웨이 운영자에게 헤더 없이 OAuth 요청을 통과시켜 달라고 요청하세요.

​

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 mcp add-from-claude-desktop 

claude mcp list 

​

claude.ai에서 MCP 서버 사용

/mcp

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

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

​

커넥터가 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를 완전히 끕니다.

​

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

• 도구가 ask로 설정됨: Claude Code는 Your organization requires approval for this tool 이유로 모든 호출에서 프롬프트합니다. 프롬프트는 acceptEdits, auto 및 bypassPermissions 권한 모드에서도 나타납니다. 터미널에서는 프롬프트에 선택을 기억하는 옵션이 없습니다. 도구와 일치하는 허용 규칙도 프롬프트를 건너뛰지 않습니다. 프롬프트를 하지 않는 dontAsk 모드에서 Claude Code는 호출을 거부합니다.
• 도구가 blocked로 설정됨: Claude Code는 Claude가 보기 전에 도구를 필터링하므로 도구 목록에 나타나지 않습니다. Claude Code가 자체적으로 커넥터를 가져오는 세션에서는 /mcp 도구 목록이 여전히 도구를 표시하며, disabled by your organization으로 표시됩니다.

​

claude.ai 커넥터 비활성화

{
  "disableClaudeAiConnectors": true
}

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

​

Claude Code를 MCP 서버로 사용하기

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

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

which claude

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

​

MCP 클라이언트로서 백그라운드 명령의 출력 읽기

• 지금까지의 출력을 읽으려면: 클라이언트에서 해당 경로의 파일을 열거나, 서버의 Read 도구에 경로를 file_path로 전달합니다
• 명령이 완료되었는지 확인하려면: npm test; echo DONE처럼 command 값에 고정 문자열을 출력하는 echo를 추가합니다. 해당 문자열이 파일에 나타나면 명령이 완료된 것입니다. 이 문자열이 없으면 종료를 표시하는 것이 없습니다. Claude Code는 파일에 종료를 나타내는 줄을 추가하지 않으며 클라이언트에 알림도 보내지 않기 때문입니다.
• 긴 출력의 끝부분을 읽으려면: file_path만 지정한 Read는 첫 페이지를 반환하거나, 파일이 크기 제한을 초과하면 실패합니다. offset과 limit도 함께 전달하면 파일 크기에 관계없이 작동합니다:
  1. offset과 limit을 모두 1로 설정하여 Read를 호출하고, 결과에서 totalLines를 가져옵니다
  2. offset을 totalLines에서 9를 뺀 값으로, limit을 10으로 설정하여 Read를 다시 호출합니다
  3. 두 번째 호출이 반환하는 마지막 10줄에서 echo 문자열을 찾습니다

​

MCP 출력 제한 및 경고

• 출력 경고 임계값: 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 디렉터리에 저장됩니다.
• HTTP 및 SSE 서버의 응답 크기: HTTP 또는 SSE 서버의 응답이 16MiB를 넘으면 Claude Code는 응답 읽기를 중단하고 요청은 실패합니다. 이 제한은 압축 해제 후 하나의 JSON 응답 본문 또는 이벤트 스트림의 하나의 이벤트에 적용됩니다. 서버를 관리하는 경우, 결과를 페이지로 나누는 등의 방법으로 응답당 반환하는 데이터를 줄여 제한을 넘지 않도록 합니다
• WebSocket 서버의 메시지 크기: WebSocket 서버가 16MiB를 넘는 메시지 하나를 보내면 Claude Code는 연결을 닫으며, 해당 서버에서 진행 중인 호출은 실패합니다. 서버를 관리하는 경우, 메시지당 반환하는 데이터를 줄여 제한을 넘지 않도록 합니다

• 텍스트 결과의 문자 제한: anthropic/maxResultSizeChars를 선언하지 않은 도구의 경우, Claude Code는 이미지 콘텐츠가 없는 성공한 결과가 토큰 수와 관계없이 50,000자를 초과하면 이를 파일에 저장합니다. MAX_MCP_OUTPUT_TOKENS를 설정해도 이 임계값은 변경되지 않습니다
• 오류 결과: 도구가 isError: true로 표시된 결과를 반환하면, Claude는 결과의 텍스트를 도구의 오류 메시지로 받습니다. 약 11,000자보다 긴 오류 텍스트는 처음 5,000자와 마지막 5,000자만 유지되며, 그 사이에 제거된 문자 수를 알려 주는 표시가 삽입됩니다

export MAX_MCP_OUTPUT_TOKENS=50000
claude

​

특정 도구의 제한 늘리기

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

​

도구 결과의 이미지

​

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

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

​

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

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

​

이름이 128자보다 긴 도구

​

특정 도구에 승인 요구하기

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

​

두 번 호출해도 안전한 도구 표시하기

• idempotentHint: 도구가 무언가를 변경할 수 있지만, 동일한 인수로 다시 호출해도 안전합니다
• readOnlyHint: 도구가 아무것도 변경하지 않습니다. Claude Code는 또한 이 도구의 호출을 다른 읽기 전용 호출과 병렬로 실행합니다.

{
  "name": "set_issue_status",
  "annotations": {
    "idempotentHint": true
  }
}

​

MCP 유도 요청에 응답하기

• 양식 모드: Claude Code는 서버에서 정의한 양식 필드가 있는 대화 상자를 표시합니다(예: 사용자 이름 및 암호 프롬프트). 필드를 채우고 제출합니다.
• URL 모드: Claude Code는 브라우저에서 링크를 열지 여부를 묻습니다. 서버는 이 모드를 터미널 외부에서 완료되는 흐름(예: 로그인)에 사용합니다.

​

MCP 리소스 사용

​

MCP 리소스 참조

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 도구 검색으로 확장하기

​

MCP 서버 작성자를 위한 도구 검색

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

• 서버 지침 및 미리 로드되는 도구의 설명: 4,096자
• Claude가 도구 검색을 통해 로드하는 도구의 설명: 16,384자

​

도구를 미리 로드하거나 연기된 상태로 유지하도록 표시

{
  "name": "search_tickets",
  "description": "Searches the ticket tracker by keyword",
  "_meta": {
    "anthropic/alwaysLoad": true
  }
}

​

도구 검색 구성

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

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

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

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

​

LLM 게이트웨이를 통한 도구 검색

​

ENABLE_TOOL_SEARCH=auto 임계값 미만에서도 연기된 상태로 유지되는 도구

​

서버를 연기에서 제외

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

​

서버의 도구 연기

​

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

​

MCP 프롬프트 실행하기

/mcp__github__list_prs

/mcp__github__pr_review 456

/mcp__jira__create_issue login-bug high

​

관리형 MCP 구성