Claude Code에서 MCP 사용하기

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 채팅, 웹훅 이벤트에 반응하도록 할 수 있습니다.

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가 마켓플레이스를 찾을 수 없다고 보고하면, 먼저 /plugin marketplace add anthropics/claude-plugins-official를 실행한 뒤 다시 설치를 시도하세요. 설치가 끝나면 /reload-plugins를 실행해 현재 세션에서 활성화합니다.

빌드 스킬 실행

/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 필드는 streamable-http를 http의 별칭으로 허용합니다. MCP 명세는 이 전송 방식의 이름으로 streamable-http를 사용하므로, 서버 문서에서 복사한 설정이 수정 없이 그대로 동작합니다.

옵션 2: 원격 SSE 서버 추가

SSE(Server-Sent Events) 전송 방식은 더 이상 사용되지 않습니다(deprecated). 가능하다면 HTTP 서버를 대신 사용하세요.

# 기본 구문
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를 프로젝트 루트로 설정합니다. 따라서 서버는 작업 디렉터리에 의존하지 않고도 프로젝트 기준 상대 경로를 해석할 수 있습니다. 이는 훅이 받는 CLAUDE_PROJECT_DIR 변수와 동일한 디렉터리입니다. 서버 프로세스 내부에서 이를 읽으면 됩니다. 예를 들어 Node에서는 process.env.CLAUDE_PROJECT_DIR, Python에서는 os.environ["CLAUDE_PROJECT_DIR"]로 읽습니다.

서버는 MCP roots/list 요청을 호출할 수도 있는데, 이는 Claude Code가 시작된 디렉터리를 반환합니다.

이 변수는 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

중요: 서버 인자는 --로 구분하세요.

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

# 특정 서버의 상세 정보 조회
claude mcp get github

# 서버 제거
claude mcp remove github

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

.mcp.json에서 온 프로젝트 스코프 서버 중 승인을 기다리는 것은 claude mcp list에 ⏸ Pending approval로 표시됩니다. claude를 대화형으로 실행해 검토하고 승인하세요. claude mcp get은 대기 중인 서버를 ⏸ Pending approval로, 거부된 서버를 ✗ Rejected로 보여 줍니다.

/mcp 패널은 연결된 각 서버 옆에 도구 개수를 표시하고, 도구 기능(capability)을 광고하지만 노출하는 도구가 없는 서버를 표시해 줍니다.

요청에 백그라운드에서 아직 연결 중인 서버의 도구가 필요하면, Claude는 진행에 앞서 해당 서버를 기다립니다. 기본값인 도구 검색이 활성화된 경우, 대기는 ToolSearch 호출 내부에서 일어납니다. Vertex AI, 사용자 지정 ANTHROPIC_BASE_URL, ENABLE_TOOL_SEARCH=false처럼 도구 검색이 없는 구성에서는 Claude가 대신 WaitForMcpServers 도구를 사용합니다.

서버 이름 workspace는 내부용으로 예약되어 있습니다. 구성에 그 이름의 서버가 정의되어 있으면 Claude Code는 로드 시점에 이를 건너뛰고, 이름을 바꿔 달라는 경고를 표시합니다.

동적 도구 업데이트

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

자동 재연결

HTTP 또는 SSE 서버가 세션 도중 연결이 끊기면, Claude Code는 지수 백오프로 자동 재연결을 시도합니다. 최대 5회, 1초 지연으로 시작해 매번 두 배로 늘립니다. 재연결이 진행되는 동안 서버는 /mcp에 대기(pending)로 표시됩니다. 5회 시도가 모두 실패하면 서버는 실패(failed)로 표시되며, /mcp에서 수동으로 다시 시도할 수 있습니다. stdio 서버는 로컬 프로세스이므로 자동으로 재연결되지 않습니다.

HTTP 또는 SSE 서버가 시작 시 초기 연결에 실패할 때도 동일한 백오프가 적용됩니다. v2.1.121부터 Claude Code는 5xx 응답, 연결 거부, 타임아웃 같은 일시적 오류 발생 시 초기 연결을 최대 3회 재시도하고, 그래도 연결되지 않으면 서버를 실패로 표시합니다. 인증 오류와 not-found 오류는 구성 변경이 있어야 해결되므로 재시도하지 않습니다.

v2.1.191부터는 연결 성공 후 실행되는 기능 탐색 요청(tools/list, prompts/list, resources/list 등)도 일시적인 네트워크 및 서버 오류에 대해 짧은 백오프로 최대 3회 재시도합니다. 인증 오류, 4xx 응답, 요청 타임아웃은 재시도하지 않습니다.

채널로 메시지 밀어 넣기

MCP 서버는 메시지를 세션으로 직접 밀어 넣어, Claude가 CI 결과, 모니터링 경고, 채팅 메시지 같은 외부 이벤트에 반응하도록 할 수도 있습니다. 이를 활성화하려면, 서버가 claude/channel 기능을 선언하고, 사용자는 시작 시 --channels 플래그로 이를 옵트인합니다. 공식 지원 채널을 사용하려면 Channels를, 직접 채널을 만들려면 Channels 레퍼런스를 참고하세요.

팁:

--scope 플래그로 구성이 저장되는 위치를 지정합니다.
local(기본값): 현재 프로젝트에서 본인에게만 제공됩니다. 이전 버전에서는 이 스코프를 project라고 불렀습니다.
project: .mcp.json 파일을 통해 프로젝트의 모든 사람과 공유됩니다.
user: 본인의 모든 프로젝트에서 제공됩니다. 이전 버전에서는 이 스코프를 global이라고 불렀습니다.
--env 플래그로 환경 변수를 설정합니다(예: --env KEY=value).
MCP 서버 시작 타임아웃은 MCP_TIMEOUT 환경 변수로 구성합니다(예: MCP_TIMEOUT=10000 claude는 10초 타임아웃을 설정).
서버별 도구 실행 타임아웃은 해당 서버의 .mcp.json 항목에 밀리초 단위 timeout 필드를 추가해 설정합니다(예: 10분이면 "timeout": 600000). 이는 해당 서버에 한해 MCP_TOOL_TIMEOUT 환경 변수를 재정의합니다.
MCP 도구 출력이 10,000 토큰을 초과하면 Claude Code가 경고를 표시합니다. 이 한도를 늘리려면 MAX_MCP_OUTPUT_TOKENS 환경 변수를 설정하세요(예: MAX_MCP_OUTPUT_TOKENS=50000).
OAuth 2.0 인증이 필요한 원격 서버는 /mcp로 인증합니다.

서버별 timeout은 도구 호출당 적용되는 절대 시간(wall-clock) 한도이며, 서버의 진행 알림이 이를 연장하지 않습니다. 1000 미만 값은 무시되어 MCP_TOOL_TIMEOUT로 넘어가며, 해당 변수가 설정되지 않았다면 기본값인 약 28시간이 적용됩니다. v2.1.162 이전에는 1000 미만 값을 1초로 내림 처리했습니다.

HTTP 및 SSE 서버의 경우, 요청당 첫 바이트 수신 예산에는 60초의 최솟값이 있습니다.

v2.1.187부터, 원격 HTTP, SSE, WebSocket, claude.ai 커넥터 서버에 대한 도구 호출이 5분 동안 응답도 진행 알림도 보내지 않으면, 절대 시간 한도를 기다리지 않고 오류와 함께 중단됩니다. 유휴 시간을 변경하려면 CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT 환경 변수를 밀리초 단위로 설정하고, 검사를 비활성화하려면 0으로 설정하세요. stdio 서버는 로컬 프로세스이므로 유휴 타임아웃의 대상이 아닙니다.

플러그인이 제공하는 MCP 서버

플러그인은 MCP 서버를 번들로 포함할 수 있어, 플러그인이 활성화되면 도구와 통합 기능을 자동으로 제공합니다. 플러그인 MCP 서버는 사용자가 직접 구성한 서버와 동일하게 동작합니다.

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

플러그인은 플러그인 루트의 .mcp.json에서, 또는 plugin.json에 인라인으로 MCP 서버를 정의합니다.
플러그인이 활성화되면 해당 MCP 서버가 자동으로 시작됩니다.
플러그인 MCP 도구는 수동으로 구성한 MCP 도구와 나란히 표시됩니다.
플러그인 서버는 /mcp 명령이 아니라 플러그인 설치를 통해 관리됩니다.

플러그인 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 기능:

자동 생명주기: 세션 시작 시 활성화된 플러그인의 서버가 자동으로 연결됩니다. 세션 도중 플러그인을 활성화하거나 비활성화했다면, /reload-plugins를 실행해 해당 MCP 서버를 연결하거나 끊습니다.
환경 변수: 번들된 플러그인 파일에는 ${CLAUDE_PLUGIN_ROOT}를, 플러그인 업데이트 후에도 유지되는 영구 상태에는 ${CLAUDE_PLUGIN_DATA}를, 안정적인 프로젝트 루트에는 ${CLAUDE_PROJECT_DIR}를 사용합니다.
사용자 환경 접근: 수동으로 구성한 서버와 동일한 환경 변수에 접근합니다.
다중 전송 방식: stdio, SSE, HTTP, WebSocket 전송을 지원합니다. 다만 전송 지원 여부는 서버마다 다를 수 있습니다.

플러그인 MCP 서버 보기:

# Claude Code 내부에서, 플러그인 서버를 포함한 모든 MCP 서버 보기
/mcp

플러그인 서버는 플러그인에서 온 것임을 나타내는 표시와 함께 목록에 나타납니다.

플러그인 MCP 도구 이름:

플러그인에 번들된 MCP 서버의 도구는 호출 가능한 이름에 플러그인 이름과 서버 키를 모두 포함합니다. 전체 형식은 mcp__plugin_<플러그인>_<서버키>__<도구>이며, A-Z, a-z, 0-9, _, - 이외의 문자는 모두 _로 치환됩니다. my-plugin이라는 플러그인에 번들된 database-tools 서버의 query 도구는 다음과 같이 호출됩니다.

mcp__plugin_my-plugin_database-tools__query

이 전체 이름은 권한 규칙, 스킬의 allowed-tools 목록, 서브에이전트의 tools 필드에서 도구를 참조할 때 사용하세요.

플러그인 MCP 서버의 이점:

번들 배포: 도구와 서버가 함께 패키징됩니다.
자동 설정: 수동 MCP 구성이 필요 없습니다.
팀 일관성: 플러그인을 설치하면 모두가 동일한 도구를 갖게 됩니다.

플러그인에 MCP 서버를 번들하는 방법은 플러그인 컴포넌트 레퍼런스를 참고하세요.

MCP 설치 스코프

MCP 서버는 세 가지 스코프로 구성할 수 있습니다. 선택한 스코프는 서버가 어떤 프로젝트에서 로드되는지, 그리고 구성이 팀과 공유되는지를 결정합니다. 관리자는 관리형 구성을 통해 엔터프라이즈 수준에서 서버를 배포할 수도 있습니다.

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

Local 스코프

Local 스코프가 기본값입니다. Local 스코프 서버는 추가한 프로젝트에서만 로드되며 본인에게만 비공개로 유지됩니다. Claude Code는 이를 ~/.claude.json의 해당 프로젝트 경로 아래에 저장하므로, 같은 서버가 다른 프로젝트에는 나타나지 않습니다. 개인 개발용 서버, 실험적 구성, 버전 관리에 두고 싶지 않은 자격 증명을 가진 서버에는 local 스코프를 사용하세요.

MCP 서버의 "local 스코프"라는 용어는 일반적인 로컬 설정과는 다릅니다. MCP local 스코프 서버는 ~/.claude.json(홈 디렉터리)에 저장되는 반면, 일반 로컬 설정은 .claude/settings.local.json(프로젝트 디렉터리)을 사용합니다. 설정 파일 위치에 대한 자세한 내용은 Settings를 참고하세요.

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

# local 스코프를 명시적으로 지정
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"
        }
      }
    }
  }
}

Project 스코프

Project 스코프 서버는 구성을 프로젝트 루트 디렉터리의 .mcp.json 파일에 저장해 팀 협업을 가능하게 합니다. 이 파일은 버전 관리에 체크인하도록 설계되어, 모든 팀원이 동일한 MCP 도구와 서비스에 접근할 수 있게 합니다. Project 스코프 서버를 추가하면 Claude Code가 적절한 구성 구조로 이 파일을 자동으로 생성하거나 업데이트합니다.

# project 스코프 서버 추가
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

생성된 .mcp.json 파일은 표준화된 형식을 따릅니다.

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

보안상의 이유로, Claude Code는 .mcp.json 파일에서 온 project 스코프 서버를 사용하기 전에 승인을 요청합니다. 이 승인 선택을 초기화하려면 claude mcp reset-project-choices 명령을 사용하세요.

User 스코프

User 스코프 서버는 ~/.claude.json에 저장되며 프로젝트 간 접근성을 제공합니다. 즉, 사용자 계정에 비공개로 유지되면서도 컴퓨터의 모든 프로젝트에서 사용할 수 있습니다. 이 스코프는 개인 유틸리티 서버, 개발 도구, 여러 프로젝트에 걸쳐 자주 쓰는 서비스에 적합합니다.

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

스코프 계층과 우선순위

같은 서버가 여러 곳에 정의되어 있으면, Claude Code는 우선순위가 가장 높은 소스의 정의를 사용해 한 번만 연결합니다. 해당 소스의 서버 항목 전체가 사용되며, 필드가 스코프 간에 병합되지는 않습니다.

Local 스코프
Project 스코프
User 스코프
플러그인이 제공하는 서버
claude.ai 커넥터

세 스코프는 이름으로 중복을 판단합니다. 플러그인과 커넥터는 엔드포인트로 판단하므로, 위 서버와 동일한 URL이나 명령을 가리키는 것은 중복으로 취급됩니다.

`.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는 구성 파싱에 실패합니다.

실용 예시

예시: Sentry로 오류 모니터링

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

Sentry 계정으로 인증합니다.

/mcp

그런 다음 프로덕션 이슈를 디버깅합니다.

지난 24시간 동안 가장 흔한 오류는 무엇이야?

오류 ID abc123의 스택 트레이스를 보여 줘.

어떤 배포에서 이 새 오류들이 생겼어?

예시: 코드 리뷰를 위해 GitHub에 연결

GitHub의 원격 MCP 서버는 헤더로 전달되는 GitHub 개인 액세스 토큰으로 인증합니다. 토큰을 얻으려면 GitHub 토큰 설정을 열고, Claude가 작업할 저장소에 대한 접근 권한을 가진 새 fine-grained 토큰을 생성한 뒤 서버를 추가하세요.

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

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

PR #456을 리뷰하고 개선점을 제안해 줘.

방금 찾은 버그에 대한 새 이슈를 만들어 줘.

나에게 할당된 열린 PR을 모두 보여 줘.

예시: PostgreSQL 데이터베이스 쿼리

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

그런 다음 자연어로 데이터베이스를 쿼리합니다.

이번 달 총매출이 얼마야?

orders 테이블의 스키마를 보여 줘.

지난 90일 동안 구매하지 않은 고객을 찾아 줘.

원격 MCP 서버 인증

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

Claude Code는 서버가 401 Unauthorized 또는 403 Forbidden으로 응답하면 해당 원격 서버를 인증이 필요한 것으로 표시합니다. 두 상태 코드 중 하나가 오면 서버가 /mcp에 표시되어 OAuth 플로를 완료할 수 있습니다. 자신의 인가 서버를 가리키는 WWW-Authenticate 헤더를 반환하는 맞춤 서버는, 다른 원격 서버와 동일하게 자동 탐색의 대상이 됩니다.

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

인증이 필요한 서버 추가

예를 들면 다음과 같습니다.

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

Claude Code 내부에서 /mcp 명령 사용

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

/mcp

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

팁:

인증 토큰은 안전하게 저장되며 자동으로 갱신됩니다.
접근 권한을 취소하려면 /mcp 메뉴의 "Clear authentication"을 사용하세요.
브라우저가 자동으로 열리지 않으면, 제공된 URL을 복사해 직접 여세요.
인증 후 브라우저 리디렉트가 연결 오류로 실패하면, 브라우저 주소창의 전체 콜백 URL을 복사해 Claude Code에 나타나는 URL 입력란에 붙여넣으세요.
OAuth 인증은 HTTP 서버에서 동작합니다.

명령줄에서 인증

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와 맞출 수 있습니다.

--callback-port는 단독으로(동적 클라이언트 등록과 함께) 사용하거나, --client-id와 함께(미리 구성한 자격 증명과 함께) 사용할 수 있습니다.

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

미리 구성한 OAuth 자격 증명 사용

일부 MCP 서버는 Dynamic Client Registration을 통한 자동 OAuth 설정을 지원하지 않습니다. "Incompatible auth server: does not support dynamic client registration" 같은 오류가 보이면, 그 서버는 미리 구성한 자격 증명을 요구하는 것입니다. Claude Code는 Dynamic Client Registration 대신 Client ID Metadata Document(CIMD)를 사용하는 서버도 지원하며, 이를 자동으로 탐색합니다. 자동 탐색이 실패하면, 먼저 서버의 개발자 포털을 통해 OAuth 앱을 등록한 뒤 서버를 추가할 때 자격 증명을 제공하세요.

서버에 OAuth 앱 등록

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

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

자격 증명과 함께 서버 추가

다음 방법 중 하나를 선택하세요. --callback-port에 사용하는 포트는 사용 가능한 아무 포트나 가능합니다. 이전 단계에서 등록한 리디렉트 URI와 일치해야 합니다.

claude mcp add

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

claude mcp add-json

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

claude mcp add-json (콜백 포트만)

클라이언트 ID 없이 --callback-port를 사용하면, 동적 클라이언트 등록을 쓰면서 포트만 고정할 수 있습니다.

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

CI / 환경 변수

환경 변수로 시크릿을 설정하면 대화형 프롬프트를 건너뛸 수 있습니다.

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를 실행하고 브라우저 로그인 플로를 따릅니다.

팁:

클라이언트 시크릿은 구성이 아니라 시스템 키체인(macOS) 또는 자격 증명 파일에 안전하게 저장됩니다.
서버가 시크릿이 없는 공개 OAuth 클라이언트를 사용한다면, --client-secret 없이 --client-id만 사용하세요.
--callback-port는 --client-id와 함께 또는 단독으로 사용할 수 있습니다.
이 플래그들은 HTTP 및 SSE 전송에만 적용됩니다. stdio 서버에는 아무 영향이 없습니다.
서버에 OAuth 자격 증명이 구성되어 있는지 확인하려면 claude mcp get <name>을 사용하세요.

OAuth 메타데이터 탐색 재정의

기본 탐색 체인을 우회하려면 Claude Code를 특정 OAuth 인가 서버 메타데이터 URL로 향하게 하세요. MCP 서버의 표준 엔드포인트가 오류를 낼 때, 또는 탐색을 내부 프록시를 통해 라우팅하고 싶을 때 authServerMetadataUrl을 설정합니다. 기본적으로 Claude Code는 먼저 /.well-known/oauth-protected-resource에서 RFC 9728 Protected Resource Metadata를 확인하고, 그다음 /.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://를 사용해야 합니다. authServerMetadataUrl은 Claude Code v2.1.64 이상이 필요합니다. 메타데이터 URL의 scopes_supported는 업스트림 서버가 광고하는 스코프를 재정의합니다.

OAuth 스코프 제한

인가 플로 도중 Claude Code가 요청하는 스코프를 고정하려면 oauth.scopes를 설정하세요. 이는 업스트림 인가 서버가 원하는 것보다 더 많은 스코프를 광고할 때, 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 서버가 요청 스코프 집합을 정하도록 두려면 이를 설정하지 마세요.

인가 서버가 scopes_supported에 offline_access를 광고하면, Claude Code는 새로운 브라우저 로그인 없이도 액세스 토큰을 갱신할 수 있도록 이를 고정된 스코프에 덧붙입니다.

이후 서버가 어떤 도구 호출에 대해 403 insufficient_scope를 반환하면, Claude Code는 동일한 고정 스코프로 다시 인증합니다. 필요한 도구가 고정 집합 밖의 스코프를 요구한다면 oauth.scopes를 넓히세요.

맞춤 인증을 위한 동적 헤더 사용

MCP 서버가 Kerberos, 단기 토큰, 내부 SSO처럼 OAuth가 아닌 인증 방식을 사용한다면, 연결 시점에 요청 헤더를 생성하도록 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에 써야 합니다.
명령은 10초 타임아웃이 적용된 셸에서 실행됩니다.
동적 헤더는 동일한 이름의 정적 headers를 재정의합니다.

이 헬퍼는 연결마다 새로 실행됩니다. 즉, 세션 시작 시와 재연결 시마다 실행됩니다. 캐싱이 없으므로, 토큰 재사용은 스크립트가 책임져야 합니다.

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

변수	값
`CLAUDE_CODE_MCP_SERVER_NAME`	MCP 서버의 이름
`CLAUDE_CODE_MCP_SERVER_URL`	MCP 서버의 URL

이를 활용하면 여러 MCP 서버를 위한 단일 헬퍼 스크립트를 작성할 수 있습니다.

headersHelper는 임의의 셸 명령을 실행합니다. project 또는 local 스코프로 정의된 경우, 워크스페이스 신뢰 대화상자를 수락한 뒤에만 실행됩니다.

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

팁:

셸에서 JSON이 제대로 이스케이프되었는지 확인하세요.
JSON은 MCP 서버 구성 스키마를 준수해야 합니다.
--scope user를 사용하면 프로젝트별 구성 대신 사용자 구성에 서버를 추가할 수 있습니다.

Claude Desktop에서 MCP 서버 가져오기

Claude Desktop에 이미 MCP 서버를 구성해 두었다면, 이를 가져올 수 있습니다.

Claude Desktop에서 서버 가져오기

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

가져올 서버 선택

명령을 실행하면, 가져올 서버를 선택할 수 있는 대화형 대화상자가 나타납니다.

서버가 가져와졌는지 확인

claude mcp list

팁:

이 기능은 macOS와 Windows Subsystem for Linux(WSL)에서만 동작합니다.
해당 플랫폼의 표준 위치에서 Claude Desktop 구성 파일을 읽습니다.
사용자 구성에 서버를 추가하려면 --scope user 플래그를 사용하세요.
가져온 서버는 Claude Desktop에서와 동일한 이름을 유지합니다.
같은 이름의 서버가 이미 있으면, 숫자 접미사가 붙습니다(예: server_1).

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에서 왔음을 나타내는 표시와 함께 목록에 나타납니다.

v2.1.161부터, 한 번도 로그인한 적 없는 커넥터는 claude.ai 섹션 끝의 Show unused connectors 행 뒤로 접혀, 조직이 프로비저닝한 목록이 패널을 가득 채우지 않게 합니다. 그 행을 선택하면 펼쳐집니다. 이전에 로그인한 커넥터는 현재 재인증이 필요하더라도 계속 표시됩니다.

claude.ai의 커넥터는 활성 인증 방식이 claude.ai 구독일 때만 가져와집니다. ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, apiKeyHelper, 또는 Bedrock이나 Vertex 같은 서드파티 제공자가 활성화되어 있으면, 이전에 /login을 실행했더라도 로드되지 않습니다.

추가한 커넥터가 /mcp에 나오지 않으면, /status를 실행해 어떤 인증 방식이 활성화되어 있는지 확인하고, 해당 환경 변수를 해제하거나 apiKeyHelper 설정을 제거한 뒤, /login을 실행해 claude.ai 계정을 선택하세요.

Claude Code에서 추가한 서버는 동일한 URL을 가리키는 claude.ai 커넥터보다 우선합니다. 이런 경우 /mcp는 그 커넥터를 숨김(hidden)으로 나열하고, 커넥터 쪽을 쓰고 싶다면 중복을 제거하는 방법을 보여 줍니다.

Microsoft 365, Gmail, Google Calendar 같은 일부 Anthropic 호스팅 커넥터는, 업스트림 신원 제공자가 claude.ai가 등록한 리디렉트 URL만 허용하기 때문에 Claude Code에서의 로컬 OAuth를 지원하지 않습니다. v2.1.162부터, 이런 호스트를 /mcp에서 인증하면 claude.ai의 Settings → Connectors에서 연결하라고 안내하는 메시지가 표시됩니다. 거기서 연결하면 커넥터가 Claude Code에 자동으로 나타납니다.

claude.ai 커넥터 비활성화

Claude Code에서 claude.ai MCP 서버를 비활성화하려면, 임의의 설정 스코프에서 disableClaudeAiConnectors를 true로 설정하세요.

{
  "disableClaudeAiConnectors": true
}

이 설정은 "어느 소스든 true면 적용(any-source-true)" 의미를 가집니다. 즉, 어느 설정 소스에서든 true이면 그것이 우선합니다. 체크인된 프로젝트 .claude/settings.json으로 저장소를 클라우드 커넥터에서 제외할 수는 있지만, 프로젝트 수준의 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 on the web 세션에서는 claude.ai 커넥터를 원격 호스트가 프로비저닝해 명시적인 --mcp-config 항목으로 전달하므로, disableClaudeAiConnectors가 적용되지 않습니다. 또한 커넥터 URL이 세션 프록시를 통해 다시 쓰이므로, 벤더 URL을 겨냥한 deniedMcpServers의 serverUrl 패턴은 매칭되지 않습니다. 클라우드 세션이 어떤 커넥터를 사용할 수 있는지는 claude.ai 조직 설정에서 관리하세요.

Claude Code를 MCP 서버로 사용

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

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

Claude Desktop에서 사용하려면 다음 구성을 claude_desktop_config.json에 추가합니다.

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

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

전체 경로를 찾으려면:

which claude

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

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

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

팁:

이 서버는 View, Edit, LS 등 Claude의 도구에 대한 접근을 제공합니다.
Claude Desktop에서, 디렉터리의 파일을 읽고 편집하는 등의 작업을 Claude에 요청해 보세요.
이 MCP 서버는 Claude Code의 도구를 여러분의 MCP 클라이언트에 노출할 뿐이므로, 개별 도구 호출에 대한 사용자 확인은 클라이언트 쪽에서 구현해야 합니다.

MCP 출력 한도와 경고

MCP 도구가 큰 출력을 만들면, Claude Code는 대화 컨텍스트가 압도되지 않도록 토큰 사용량을 관리합니다.

출력 경고 임계값: 어떤 MCP 도구든 출력이 10,000 토큰을 초과하면 Claude Code가 경고를 표시합니다.
구성 가능한 한도: MAX_MCP_OUTPUT_TOKENS 환경 변수로 허용되는 최대 MCP 출력 토큰을 조정할 수 있습니다.
기본 한도: 기본 최댓값은 25,000 토큰입니다.
적용 범위: 이 환경 변수는 자체 한도를 선언하지 않는 도구에 적용됩니다. anthropic/maxResultSizeChars를 설정한 도구는 MAX_MCP_OUTPUT_TOKENS 값과 무관하게, 텍스트 콘텐츠에 그 값을 대신 사용합니다. 이미지 데이터를 반환하는 도구는 여전히 MAX_MCP_OUTPUT_TOKENS의 적용을 받습니다.

큰 출력을 만드는 도구를 위해 한도를 높이려면:

export MAX_MCP_OUTPUT_TOKENS=50000
claude

이는 다음과 같은 MCP 서버를 다룰 때 특히 유용합니다.

큰 데이터셋이나 데이터베이스를 쿼리하는 경우
상세한 보고서나 문서를 생성하는 경우
방대한 로그 파일이나 디버깅 정보를 처리하는 경우

특정 도구에 대해 한도 높이기

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 서버에서 출력 경고가 자주 발생한다면, MAX_MCP_OUTPUT_TOKENS 한도를 높이는 것을 고려하세요. 또는 서버 작성자에게 anthropic/maxResultSizeChars 주석을 추가하거나 응답을 페이지네이션해 달라고 요청할 수도 있습니다. 이 주석은 이미지 콘텐츠를 반환하는 도구에는 효과가 없으며, 그런 경우에는 MAX_MCP_OUTPUT_TOKENS를 높이는 것이 유일한 방법입니다.

MCP elicitation 요청에 응답하기

MCP 서버는 elicitation을 사용해 작업 도중 구조화된 입력을 요청할 수 있습니다. 서버가 스스로 얻을 수 없는 정보가 필요하면, Claude Code가 대화형 대화상자를 표시하고 여러분의 응답을 서버에 전달합니다. 사용자 쪽에서는 별도 구성이 필요 없으며, 서버가 요청하면 elicitation 대화상자가 자동으로 나타납니다.

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

폼 모드: Claude Code가 서버가 정의한 폼 필드(예: 사용자 이름과 비밀번호 프롬프트)를 가진 대화상자를 보여 줍니다. 필드를 채우고 제출합니다.
URL 모드: Claude Code가 인증이나 승인을 위해 브라우저 URL을 엽니다. 브라우저에서 플로를 완료한 뒤 CLI에서 확인합니다.

대화상자를 표시하지 않고 elicitation 요청에 자동 응답하려면, Elicitation 훅을 사용하세요.

elicitation을 사용하는 MCP 서버를 만들고 있다면, 프로토콜 세부 사항과 스키마 예시는 MCP elicitation 명세를 참고하세요.

MCP 리소스 사용

MCP 서버는 리소스를 노출할 수 있으며, 파일을 참조하는 것과 비슷하게 @ 멘션으로 이를 참조할 수 있습니다.

MCP 리소스 참조

사용 가능한 리소스 나열

프롬프트에 @를 입력하면 연결된 모든 MCP 서버에서 사용 가능한 리소스를 볼 수 있습니다. 리소스는 자동완성 메뉴에서 파일과 나란히 나타납니다.

특정 리소스 참조

리소스를 참조하려면 @server:protocol://resource/path 형식을 사용합니다.

@github:issue://123을 분석하고 수정 방법을 제안해 줄 수 있어?

@docs:file://api/authentication에 있는 API 문서를 검토해 줘.

여러 리소스 참조

하나의 프롬프트에서 여러 리소스를 참조할 수 있습니다.

@postgres:schema://users를 @docs:file://database/user-model과 비교해 줘.

팁:

리소스를 참조하면 자동으로 가져와져 첨부로 포함됩니다.
리소스 경로는 @ 멘션 자동완성에서 유사 검색(fuzzy search)이 됩니다.
서버가 지원하는 경우, Claude Code는 MCP 리소스를 나열하고 읽는 도구를 자동으로 제공합니다.
리소스는 MCP 서버가 제공하는 모든 종류의 콘텐츠(텍스트, JSON, 구조화된 데이터 등)를 담을 수 있습니다.

MCP 도구 검색으로 확장하기

도구 검색은 도구 정의를 Claude가 필요로 할 때까지 미뤄, MCP 컨텍스트 사용량을 낮게 유지합니다. 세션 시작 시 도구 이름과 서버 지침만 로드되므로, MCP 서버를 더 추가해도 컨텍스트 윈도에 미치는 영향이 미미합니다. Claude Code는 서버당 고정된 도구 개수 상한을 두지 않으며, 실질적인 한계는 컨텍스트 윈도 예산입니다.

작동 방식

도구 검색은 기본적으로 활성화되어 있습니다. MCP 도구는 미리 컨텍스트에 로드되는 대신 미뤄지며, 작업에 필요할 때 Claude가 검색 도구를 사용해 관련 도구를 찾습니다. Claude가 실제로 사용하는 도구만 컨텍스트에 들어갑니다. 사용자 입장에서 MCP 도구는 이전과 똑같이 동작합니다.

임계값 기반 로딩을 선호한다면 ENABLE_TOOL_SEARCH=auto를 설정하세요. 그러면 스키마가 컨텍스트 윈도의 10% 안에 들어맞을 때는 미리 로드하고, 넘치는 부분만 미룹니다. 전체 내용은 Configure tool search를 참고하세요.