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

Model Context Protocol을 사용하여 Claude Code를 도구에 연결하는 방법을 알아보세요.

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

MCP로 할 수 있는 것

MCP 서버를 연결하면 Claude Code에 다음과 같은 작업을 요청할 수 있습니다:

이슈 트래커의 기능 구현: "JIRA 이슈 ENG-4521에 설명된 기능을 추가하고 GitHub에 PR을 생성해 줘."
모니터링 데이터 분석: "Sentry와 Statsig을 확인해서 ENG-4521에 설명된 기능의 사용량을 확인해 줘."
데이터베이스 쿼리: "PostgreSQL 데이터베이스를 기반으로 ENG-4521 기능을 사용한 무작위 사용자 10명의 이메일을 찾아줘."
디자인 통합: "Slack에 올라온 새로운 Figma 디자인을 기반으로 표준 이메일 템플릿을 업데이트해 줘."
워크플로우 자동화: "이 10명의 사용자에게 새 기능에 대한 피드백 세션 초대 Gmail 초안을 작성해 줘."

서버	설명
Notion	워크스페이스 검색/업데이트, 워크플로우 지원
Canva	디자인 검색, 생성, 자동 채우기 및 내보내기
Figma	Figma 컨텍스트에서 고품질 코드 생성
Slack	메시지 전송, 캔버스 생성, 데이터 조회
Atlassian	Jira/Confluence 이슈 및 문서 관리
Linear	이슈, 프로젝트 및 팀 워크플로우 관리
monday.com	프로젝트, 보드 및 워크플로우 관리
Vercel	프로젝트 배포 분석, 디버깅 및 관리
Sentry	오류 검색, 쿼리 및 지능형 디버깅
Asana	작업, 프로젝트 및 목표 조정
Supabase	데이터베이스, 인증 및 저장소 관리
ClickUp	프로젝트 관리 및 팀 협업
Hugging Face	Hub 및 Gradio 앱 접근
Excalidraw	손그림 스타일 다이어그램 생성
Context7	LLM/AI 코드 편집기용 최신 문서 제공

MCP 서버 설치

MCP 서버는 필요에 따라 세 가지 방법으로 구성할 수 있습니다:

옵션 1: 원격 HTTP 서버 추가

HTTP 서버는 원격 MCP 서버에 연결하기 위해 권장되는 옵션입니다. 클라우드 기반 서비스에서 가장 널리 지원되는 전송 방식입니다.

# Basic syntax
claude mcp add --transport http <name> <url>

# Real example: Connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Example with Bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

옵션 2: 원격 SSE 서버 추가

주의:

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

# Basic syntax
claude mcp add --transport sse <name> <url>

# Real example: Connect to Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Example with authentication header
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

옵션 3: 로컬 stdio 서버 추가

Stdio 서버는 로컬 머신에서 프로세스로 실행됩니다. 직접적인 시스템 접근이나 커스텀 스크립트가 필요한 도구에 적합합니다.

# Basic syntax
claude mcp add [options] <name> -- <command> [args...]

# Real example: Add Airtable server
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

참고:

중요: 옵션 순서

모든 옵션(--transport, --env, --scope, --header)은 서버 이름 앞에 와야 합니다. -- (이중 대시)는 서버 이름과 MCP 서버에 전달되는 명령어 및 인자를 구분합니다.

예시:

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

claude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080 → 환경 변수 KEY=value와 함께 python server.py --port 8080을 실행

이렇게 하면 Claude의 플래그와 서버의 플래그 간 충돌을 방지할 수 있습니다.

서버 관리

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

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get github

# Remove a server
claude mcp remove github

# (within Claude Code) Check server status
/mcp

동적 도구 업데이트

Claude Code는 MCP list_changed 알림을 지원하여, MCP 서버가 연결 해제 및 재연결 없이 사용 가능한 도구, 프롬프트, 리소스를 동적으로 업데이트할 수 있습니다. MCP 서버가 list_changed 알림을 보내면 Claude Code는 해당 서버에서 사용 가능한 기능을 자동으로 갱신합니다.

팁:

--scope 플래그를 사용하여 구성이 저장되는 위치를 지정할 수 있습니다:

local (기본값): 현재 프로젝트에서 자신만 사용 가능 (이전 버전에서는 project로 불림)

project: .mcp.json 파일을 통해 프로젝트의 모든 사람과 공유

user: 모든 프로젝트에서 자신이 사용 가능 (이전 버전에서는 global로 불림)

--env 플래그로 환경 변수를 설정할 수 있습니다 (예: --env KEY=value)

MCP_TIMEOUT 환경 변수를 사용하여 MCP 서버 시작 타임아웃을 설정할 수 있습니다 (예: MCP_TIMEOUT=10000 claude는 10초 타임아웃을 설정)

MCP 도구 출력이 10,000 토큰을 초과하면 Claude Code가 경고를 표시합니다. 이 제한을 늘리려면 MAX_MCP_OUTPUT_TOKENS 환경 변수를 설정하세요 (예: MAX_MCP_OUTPUT_TOKENS=50000)

/mcp를 사용하여 OAuth 2.0 인증이 필요한 원격 서버에 인증할 수 있습니다

주의:

Windows 사용자: 네이티브 Windows(WSL 제외)에서는 npx를 사용하는 로컬 MCP 서버에 cmd /c 래퍼가 필요합니다.
# This creates command="cmd" which Windows can execute
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package
cmd /c 래퍼가 없으면 Windows가 npx를 직접 실행할 수 없어 "Connection closed" 오류가 발생합니다. (-- 매개변수에 대한 설명은 위의 참고 사항을 확인하세요.)

플러그인 제공 MCP 서버

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

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

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

플러그인 MCP 구성 예시:

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

{
  "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 기능:

자동 수명주기: 플러그인이 활성화되면 서버가 시작되지만, MCP 서버 변경(활성화 또는 비활성화)을 적용하려면 Claude Code를 재시작해야 합니다
환경 변수: 플러그인 상대 경로에 ${CLAUDE_PLUGIN_ROOT}를 사용합니다
사용자 환경 접근: 수동으로 구성한 서버와 동일한 환경 변수에 접근 가능합니다
다양한 전송 방식 지원: stdio, SSE, HTTP 전송 방식을 지원합니다 (전송 방식 지원은 서버에 따라 다를 수 있음)

플러그인 MCP 서버 확인하기:

# Within Claude Code, see all MCP servers including plugin ones
/mcp

플러그인 서버는 플러그인에서 제공되었음을 나타내는 표시와 함께 목록에 표시됩니다.

플러그인 MCP 서버의 이점:

번들 배포: 도구와 서버가 함께 패키징됩니다
자동 설정: 수동 MCP 구성이 필요 없습니다
팀 일관성: 플러그인 설치 시 모든 사람이 동일한 도구를 사용할 수 있습니다

플러그인과 함께 MCP 서버를 번들링하는 자세한 내용은 플러그인 컴포넌트 레퍼런스를 참조하세요.

MCP 설치 범위

MCP 서버는 세 가지 범위 수준으로 구성할 수 있으며, 각각 서버 접근성과 공유를 관리하기 위한 고유한 목적이 있습니다. 이러한 범위를 이해하면 특정 요구사항에 맞는 최적의 서버 구성 방법을 결정하는 데 도움이 됩니다.

Local 범위

Local 범위 서버는 기본 구성 수준이며 프로젝트 경로 아래 ~/.claude.json에 저장됩니다. 이 서버는 자신에게만 비공개이며 현재 프로젝트 디렉토리에서 작업할 때만 접근 가능합니다. 이 범위는 개인 개발 서버, 실험적 구성, 또는 공유해서는 안 되는 민감한 자격 증명이 포함된 서버에 적합합니다.

참고:

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

# 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

Project 범위

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

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

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

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

보안상의 이유로, .mcp.json 파일의 project 범위 서버를 사용하기 전에 Claude Code가 승인을 요청합니다. 이 승인 선택을 초기화해야 하는 경우 claude mcp reset-project-choices 명령을 사용하세요.

User 범위

User 범위 서버는 ~/.claude.json에 저장되며 프로젝트 간 접근성을 제공하여 머신의 모든 프로젝트에서 사용할 수 있으면서 사용자 계정에 비공개로 유지됩니다. 이 범위는 개인 유틸리티 서버, 개발 도구 또는 여러 프로젝트에서 자주 사용하는 서비스에 적합합니다.

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

적절한 범위 선택

다음 기준으로 범위를 선택하세요:

Local 범위: 개인 서버, 실험적 구성, 또는 하나의 프로젝트에 특화된 민감한 자격 증명
Project 범위: 팀 공유 서버, 프로젝트별 도구, 또는 협업에 필요한 서비스
User 범위: 여러 프로젝트에서 필요한 개인 유틸리티, 개발 도구, 또는 자주 사용하는 서비스

참고:

MCP 서버는 어디에 저장되나요?

User 및 local 범위: ~/.claude.json (mcpServers 필드 또는 프로젝트 경로 아래)

Project 범위: 프로젝트 루트의 .mcp.json (소스 관리에 체크인)

관리형(Managed): 시스템 디렉토리의 managed-mcp.json (관리형 MCP 구성 참조)

범위 계층 구조 및 우선순위

MCP 서버 구성은 명확한 우선순위 계층을 따릅니다. 동일한 이름의 서버가 여러 범위에 존재하는 경우, local 범위 서버를 먼저 우선시하고, 그 다음 project 범위 서버, 마지막으로 user 범위 서버 순으로 충돌을 해결합니다. 이 설계를 통해 필요할 때 개인 구성이 공유 구성을 재정의할 수 있습니다.

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

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

What are the most common errors in the last 24 hours?

Show me the stack trace for error ID abc123

Which deployment introduced these new errors?

예시: GitHub에 연결하여 코드 리뷰

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

필요한 경우 GitHub의 "Authenticate"를 선택하여 인증합니다:

/mcp

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

Review PR #456 and suggest improvements

Create a new issue for the bug we just found

Show me all open PRs assigned to me

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

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:[email protected]:5432/analytics"

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

What's our total revenue this month?

Show me the schema for the orders table

Find customers who haven't made a purchase in 90 days

원격 MCP 서버 인증

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

Step 1: 인증이 필요한 서버 추가

예시:

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

Step 2: Claude Code 내에서 /mcp 명령어 사용

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

/mcp

그런 다음 브라우저의 안내에 따라 로그인합니다.

팁:

인증 토큰은 안전하게 저장되며 자동으로 갱신됩니다

/mcp 메뉴에서 "Clear authentication"을 사용하여 접근을 취소할 수 있습니다

브라우저가 자동으로 열리지 않으면 제공된 URL을 복사하여 수동으로 여세요

인증 후 브라우저 리디렉션이 연결 오류와 함께 실패하면, 브라우저 주소 표시줄의 전체 콜백 URL을 Claude Code에 나타나는 URL 프롬프트에 붙여넣으세요

OAuth 인증은 HTTP 서버에서 작동합니다

고정 OAuth 콜백 포트 사용

일부 MCP 서버는 사전에 등록된 특정 리디렉트 URI를 필요로 합니다. 기본적으로 Claude Code는 OAuth 콜백을 위해 사용 가능한 임의의 포트를 선택합니다. --callback-port를 사용하여 http://localhost:PORT/callback 형식의 사전 등록된 리디렉트 URI와 일치하도록 포트를 고정할 수 있습니다.

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

# Fixed callback port with dynamic client registration
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"과 같은 오류가 표시되면 해당 서버는 사전 구성된 자격 증명을 필요로 합니다. 먼저 서버의 개발자 포털을 통해 OAuth 앱을 등록한 다음, 서버 추가 시 자격 증명을 제공하세요.

Step 1: 서버에 OAuth 앱 등록

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

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

Step 2: 자격 증명과 함께 서버 추가

다음 방법 중 하나를 선택하세요. --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 (callback port only)

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

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

CI / env var

대화형 프롬프트를 건너뛰려면 환경 변수로 시크릿을 설정합니다:

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

Step 3: Claude Code에서 인증

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

팁:

클라이언트 시크릿은 구성 파일이 아닌 시스템 키체인(macOS) 또는 자격 증명 파일에 안전하게 저장됩니다

서버가 시크릿 없는 공개 OAuth 클라이언트를 사용하는 경우, --client-secret 없이 --client-id만 사용하세요

--callback-port는 --client-id와 함께 또는 단독으로 사용할 수 있습니다

이 플래그들은 HTTP 및 SSE 전송 방식에만 적용됩니다. stdio 서버에는 영향이 없습니다

claude mcp get <name>을 사용하여 서버에 OAuth 자격 증명이 구성되었는지 확인하세요

OAuth 메타데이터 검색 재정의

MCP 서버가 표준 OAuth 메타데이터 엔드포인트(/.well-known/oauth-authorization-server)에서 오류를 반환하지만 작동하는 OIDC 엔드포인트를 노출하는 경우, 표준 검색 체인을 우회하여 지정한 URL에서 직접 OAuth 메타데이터를 가져오도록 Claude Code에 지시할 수 있습니다.

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

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

URL은 https://를 사용해야 합니다. 이 옵션은 Claude Code v2.1.64 이상이 필요합니다.

JSON 구성에서 MCP 서버 추가

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

Step 1: JSON에서 MCP 서버 추가

# Basic syntax
claude mcp add-json <name> '<json>'

# Example: Adding an HTTP server with JSON configuration
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# Example: Adding a stdio server with JSON configuration
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# Example: Adding an HTTP server with pre-configured OAuth credentials
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

Step 2: 서버가 추가되었는지 확인

claude mcp get weather-api

팁:

셸에서 JSON이 올바르게 이스케이프되었는지 확인하세요

JSON은 MCP 서버 구성 스키마를 준수해야 합니다

--scope user를 사용하여 프로젝트별 구성 대신 사용자 구성에 서버를 추가할 수 있습니다

Claude Desktop에서 MCP 서버 가져오기

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

Step 1: Claude Desktop에서 서버 가져오기

# Basic syntax
claude mcp add-from-claude-desktop

Step 2: 가져올 서버 선택

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

Step 3: 서버가 가져와졌는지 확인

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에서 자동으로 사용 가능합니다:

Step 1: Claude.ai에서 MCP 서버 구성

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

Step 2: MCP 서버 인증

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

Step 3: Claude Code에서 서버 확인 및 관리

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

/mcp

Claude.ai 서버는 Claude.ai에서 제공되었음을 나타내는 표시와 함께 목록에 표시됩니다.

Claude Code에서 Claude.ai MCP 서버를 비활성화하려면 ENABLE_CLAUDEAI_MCP_SERVERS 환경 변수를 false로 설정합니다:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

Claude Code를 MCP 서버로 사용

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

# Start Claude as a stdio MCP server
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와 같은 오류가 발생합니다.

팁:

이 서버는 Claude의 View, Edit, LS 등의 도구에 대한 접근을 제공합니다.

Claude Desktop에서 디렉토리의 파일을 읽고, 편집하는 등의 작업을 요청해 보세요.

이 MCP 서버는 Claude Code의 도구를 MCP 클라이언트에 노출하기만 하므로, 개별 도구 호출에 대한 사용자 확인은 클라이언트 자체에서 구현해야 합니다.

MCP 출력 제한 및 경고

MCP 도구가 대량의 출력을 생성할 때, Claude Code는 대화 컨텍스트가 과부하되는 것을 방지하기 위해 토큰 사용량을 관리합니다:

출력 경고 임계값: MCP 도구 출력이 10,000 토큰을 초과하면 Claude Code가 경고를 표시합니다
설정 가능한 제한: MAX_MCP_OUTPUT_TOKENS 환경 변수를 사용하여 최대 허용 MCP 출력 토큰을 조정할 수 있습니다
기본 제한: 기본 최대값은 25,000 토큰입니다

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

# Set a higher limit for MCP tool outputs
export MAX_MCP_OUTPUT_TOKENS=50000
claude

이 기능은 다음과 같은 MCP 서버를 사용할 때 특히 유용합니다:

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

주의:

특정 MCP 서버에서 출력 경고가 자주 발생하는 경우, 제한을 늘리거나 서버가 응답을 페이지네이션하거나 필터링하도록 구성하는 것을 고려하세요.

MCP 리소스 사용

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

MCP 리소스 참조

Step 1: 사용 가능한 리소스 목록 보기

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

Step 2: 특정 리소스 참조

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

Can you analyze @github:issue://123 and suggest a fix?

Please review the API documentation at @docs:file://api/authentication

Step 3: 여러 리소스 참조

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

Compare @postgres:schema://users with @docs:file://database/user-model

팁:

리소스는 참조 시 자동으로 가져와 첨부 파일로 포함됩니다

리소스 경로는 @ 멘션 자동완성에서 퍼지 검색이 가능합니다

서버가 지원하는 경우 Claude Code가 MCP 리소스를 나열하고 읽는 도구를 자동으로 제공합니다

리소스는 MCP 서버가 제공하는 모든 유형의 콘텐츠(텍스트, JSON, 구조화된 데이터 등)를 포함할 수 있습니다

MCP Tool Search로 확장

많은 MCP 서버가 구성되어 있으면 도구 정의가 컨텍스트 윈도우의 상당 부분을 차지할 수 있습니다. MCP Tool Search는 모든 도구를 미리 로드하는 대신 필요에 따라 동적으로 도구를 로드하여 이 문제를 해결합니다.

작동 방식

MCP 도구 설명이 컨텍스트 윈도우의 10% 이상을 차지하면 Claude Code가 자동으로 Tool Search를 활성화합니다. 이 임계값을 조정하거나 Tool Search를 완전히 비활성화할 수 있습니다. 활성화되면:

MCP 도구가 컨텍스트에 미리 로드되지 않고 지연(defer)됩니다
Claude가 필요할 때 검색 도구를 사용하여 관련 MCP 도구를 검색합니다
Claude가 실제로 필요한 도구만 컨텍스트에 로드됩니다
사용자 관점에서 MCP 도구는 이전과 동일하게 작동합니다

MCP 서버 개발자를 위한 안내

MCP 서버를 개발하는 경우, Tool Search가 활성화되면 서버 지침(instructions) 필드가 더 유용해집니다. 서버 지침은 스킬의 작동 방식과 유사하게 Claude가 도구를 검색해야 할 시점을 이해하는 데 도움이 됩니다.

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

도구가 처리하는 작업 카테고리
Claude가 도구를 검색해야 하는 시점
서버가 제공하는 주요 기능

Tool Search 구성

Tool Search는 기본적으로 auto 모드로 실행되며, MCP 도구 정의가 컨텍스트 임계값을 초과하는 경우에만 활성화됩니다. 도구가 적으면 Tool Search 없이 정상적으로 로드됩니다. 이 기능은 tool_reference 블록을 지원하는 모델이 필요합니다: Sonnet 4 이상 또는 Opus 4 이상. Haiku 모델은 Tool Search를 지원하지 않습니다.

ENABLE_TOOL_SEARCH 환경 변수로 Tool Search 동작을 제어합니다:

Value	Behavior
`auto`	MCP 도구가 컨텍스트의 10%를 초과하면 활성화 (기본값)
`auto:<N>`	사용자 정의 임계값으로 활성화, `<N>`은 백분율 (예: `auto:5`는 5%)
`true`	항상 활성화
`false`	비활성화, 모든 MCP 도구를 미리 로드

# Use a custom 5% threshold
ENABLE_TOOL_SEARCH=auto:5 claude

# Disable tool search entirely
ENABLE_TOOL_SEARCH=false claude

또는 settings.json env 필드에서 값을 설정할 수 있습니다.

disallowedTools 설정을 사용하여 MCPSearch 도구를 구체적으로 비활성화할 수도 있습니다:

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

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

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

MCP 프롬프트 실행

Step 1: 사용 가능한 프롬프트 검색

/를 입력하면 MCP 서버의 프롬프트를 포함한 모든 사용 가능한 명령어를 볼 수 있습니다. MCP 프롬프트는 /mcp__servername__promptname 형식으로 표시됩니다.

Step 2: 인자 없이 프롬프트 실행

/mcp__github__list_prs

Step 3: 인자와 함께 프롬프트 실행

많은 프롬프트는 인자를 받습니다. 명령어 뒤에 공백으로 구분하여 전달합니다:

/mcp__github__pr_review 456

/mcp__jira__create_issue "Bug in login flow" high

팁:

MCP 프롬프트는 연결된 서버에서 동적으로 검색됩니다

인자는 프롬프트에 정의된 매개변수를 기반으로 파싱됩니다

프롬프트 결과는 대화에 직접 주입됩니다

서버 및 프롬프트 이름은 정규화됩니다 (공백은 밑줄로 변환)

관리형 MCP 구성

중앙 집중식 MCP 서버 관리가 필요한 조직을 위해 Claude Code는 두 가지 구성 옵션을 지원합니다:

managed-mcp.json을 통한 독점적 제어: 사용자가 수정하거나 확장할 수 없는 고정된 MCP 서버 세트를 배포합니다
허용 목록/차단 목록을 통한 정책 기반 제어: 사용자가 자체 서버를 추가할 수 있지만 허용되는 서버를 제한합니다

이러한 옵션을 통해 IT 관리자는 다음을 수행할 수 있습니다:

직원이 접근할 수 있는 MCP 서버 제어: 조직 전체에 표준화된 승인 MCP 서버 세트를 배포합니다
승인되지 않은 MCP 서버 방지: 사용자가 승인되지 않은 MCP 서버를 추가하는 것을 제한합니다
MCP 완전 비활성화: 필요한 경우 MCP 기능을 완전히 제거합니다

옵션 1: managed-mcp.json을 통한 독점적 제어

managed-mcp.json 파일을 배포하면 모든 MCP 서버에 대해 독점적 제어를 갖게 됩니다. 사용자는 이 파일에 정의된 것 이외의 MCP 서버를 추가, 수정, 사용할 수 없습니다. 이는 완전한 제어를 원하는 조직을 위한 가장 간단한 접근 방식입니다.

시스템 관리자는 구성 파일을 시스템 전체 디렉토리에 배포합니다:

macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
Linux 및 WSL: /etc/claude-code/managed-mcp.json
Windows: C:\Program Files\ClaudeCode\managed-mcp.json

참고:

이것은 시스템 전체 경로이며 (사용자 홈 디렉토리 ~/Library/...가 아님) 관리자 권한이 필요합니다. IT 관리자가 배포하도록 설계되었습니다.

managed-mcp.json 파일은 표준 .mcp.json 파일과 동일한 형식을 사용합니다:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"],
      "env": {
        "COMPANY_API_URL": "https://internal.company.com"
      }
    }
  }
}

옵션 2: 허용 목록과 차단 목록을 통한 정책 기반 제어

독점적 제어 대신, 관리자는 사용자가 자체 MCP 서버를 구성할 수 있도록 허용하면서 허용되는 서버에 대한 제한을 적용할 수 있습니다. 이 접근 방식은 관리형 설정 파일의 allowedMcpServers와 deniedMcpServers를 사용합니다.

참고:

옵션 간 선택: 사용자 맞춤 없이 고정된 서버 세트를 배포하려면 옵션 1(managed-mcp.json)을 사용하세요. 정책 제약 내에서 사용자가 자체 서버를 추가할 수 있도록 하려면 옵션 2(허용 목록/차단 목록)를 사용하세요.

제한 옵션

허용 목록 또는 차단 목록의 각 항목은 세 가지 방법으로 서버를 제한할 수 있습니다:

서버 이름 기준 (serverName): 서버의 구성된 이름과 일치
명령어 기준 (serverCommand): stdio 서버를 시작하는 데 사용되는 정확한 명령어 및 인자와 일치
URL 패턴 기준 (serverUrl): 와일드카드를 지원하여 원격 서버 URL과 일치

중요: 각 항목에는 serverName, serverCommand, serverUrl 중 정확히 하나만 있어야 합니다.

구성 예시

{
  "allowedMcpServers": [
    // Allow by server name
    { "serverName": "github" },
    { "serverName": "sentry" },

    // Allow by exact command (for stdio servers)
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },
    { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },

    // Allow by URL pattern (for remote servers)
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ],
  "deniedMcpServers": [
    // Block by server name
    { "serverName": "dangerous-server" },

    // Block by exact command (for stdio servers)
    { "serverCommand": ["npx", "-y", "unapproved-package"] },

    // Block by URL pattern (for remote servers)
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}

명령어 기반 제한의 작동 방식

정확한 일치:

명령어 배열은 정확히 일치해야 합니다 - 명령어와 모든 인자가 올바른 순서여야 합니다
예: ["npx", "-y", "server"]는 ["npx", "server"]나 ["npx", "-y", "server", "--flag"]와 일치하지 않습니다

Stdio 서버 동작:

허용 목록에 serverCommand 항목이 하나라도 포함되면 stdio 서버는 해당 명령어 중 하나와 반드시 일치해야 합니다
명령어 제한이 있으면 stdio 서버는 이름만으로 통과할 수 없습니다
이를 통해 관리자가 실행 가능한 명령어를 강제할 수 있습니다

비-stdio 서버 동작:

원격 서버(HTTP, SSE, WebSocket)는 허용 목록에 serverUrl 항목이 있으면 URL 기반 일치를 사용합니다
URL 항목이 없으면 원격 서버는 이름 기반 일치로 대체됩니다
명령어 제한은 원격 서버에 적용되지 않습니다

URL 기반 제한의 작동 방식

URL 패턴은 *를 사용한 와일드카드를 지원하여 임의의 문자 시퀀스와 일치시킵니다. 전체 도메인 또는 하위 도메인을 허용하는 데 유용합니다.

와일드카드 예시:

https://mcp.company.com/* - 특정 도메인의 모든 경로 허용
https://*.example.com/* - example.com의 모든 하위 도메인 허용
http://localhost:*/* - localhost의 모든 포트 허용

원격 서버 동작:

허용 목록에 serverUrl 항목이 하나라도 포함되면 원격 서버는 해당 URL 패턴 중 하나와 반드시 일치해야 합니다
URL 제한이 있으면 원격 서버는 이름만으로 통과할 수 없습니다
이를 통해 관리자가 허용되는 원격 엔드포인트를 강제할 수 있습니다

예시: URL 전용 허용 목록

{
  "allowedMcpServers": [
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ]
}

결과:

https://mcp.company.com/api의 HTTP 서버: ✅ 허용 (URL 패턴 일치)
https://api.internal.corp/mcp의 HTTP 서버: ✅ 허용 (와일드카드 하위 도메인 일치)
https://external.com/mcp의 HTTP 서버: ❌ 차단 (URL 패턴과 일치하지 않음)
임의의 명령어를 가진 Stdio 서버: ❌ 차단 (일치할 이름 또는 명령어 항목 없음)

예시: 명령어 전용 허용 목록

{
  "allowedMcpServers": [
    { "serverCommand": ["npx", "-y", "approved-package"] }
  ]
}

결과:

["npx", "-y", "approved-package"] 명령어의 Stdio 서버: ✅ 허용 (명령어 일치)
["node", "server.js"] 명령어의 Stdio 서버: ❌ 차단 (명령어 불일치)
"my-api"라는 이름의 HTTP 서버: ❌ 차단 (일치할 이름 항목 없음)

예시: 이름과 명령어 혼합 허용 목록

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverCommand": ["npx", "-y", "approved-package"] }
  ]
}

결과:

["npx", "-y", "approved-package"] 명령어의 "local-tool" Stdio 서버: ✅ 허용 (명령어 일치)
["node", "server.js"] 명령어의 "local-tool" Stdio 서버: ❌ 차단 (명령어 항목이 존재하지만 일치하지 않음)
["node", "server.js"] 명령어의 "github" Stdio 서버: ❌ 차단 (명령어 항목이 존재하면 stdio 서버는 반드시 명령어와 일치해야 함)
"github"이라는 이름의 HTTP 서버: ✅ 허용 (이름 일치)
"other-api"라는 이름의 HTTP 서버: ❌ 차단 (이름 불일치)

예시: 이름 전용 허용 목록

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "internal-tool" }
  ]
}

결과:

임의의 명령어를 가진 "github" Stdio 서버: ✅ 허용 (명령어 제한 없음)
임의의 명령어를 가진 "internal-tool" Stdio 서버: ✅ 허용 (명령어 제한 없음)
"github"이라는 이름의 HTTP 서버: ✅ 허용 (이름 일치)
"other"라는 이름의 모든 서버: ❌ 차단 (이름 불일치)

허용 목록 동작 (`allowedMcpServers`)

undefined (기본값): 제한 없음 - 사용자가 모든 MCP 서버를 구성 가능
빈 배열 []: 완전 잠금 - 사용자가 MCP 서버를 구성할 수 없음
항목 목록: 사용자는 이름, 명령어 또는 URL 패턴으로 일치하는 서버만 구성 가능

차단 목록 동작 (`deniedMcpServers`)

undefined (기본값): 차단되는 서버 없음
빈 배열 []: 차단되는 서버 없음
항목 목록: 지정된 서버가 모든 범위에서 명시적으로 차단됨

중요 참고 사항

옵션 1과 옵션 2는 결합 가능: managed-mcp.json이 존재하면 독점적 제어를 가지며 사용자는 서버를 추가할 수 없습니다. 허용 목록/차단 목록은 관리형 서버 자체에도 여전히 적용됩니다.
차단 목록이 절대적 우선: 서버가 차단 목록 항목(이름, 명령어 또는 URL)과 일치하면 허용 목록에 있더라도 차단됩니다
이름 기반, 명령어 기반, URL 기반 제한은 함께 작동합니다: 서버는 이름 항목, 명령어 항목 또는 URL 패턴 중 하나라도 일치하면 통과합니다 (차단 목록에 의해 차단되지 않는 한)

참고:

managed-mcp.json 사용 시: 사용자는 claude mcp add 또는 구성 파일을 통해 MCP 서버를 추가할 수 없습니다. allowedMcpServers 및 deniedMcpServers 설정은 실제로 로드되는 관리형 서버를 필터링하는 데 여전히 적용됩니다.

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

Model Context Protocol을 사용하여 Claude Code를 도구에 연결하는 방법을 알아보세요.

MCP로 할 수 있는 것

MCP 서버를 연결하면 Claude Code에 다음과 같은 작업을 요청할 수 있습니다:

이슈 트래커의 기능 구현: "JIRA 이슈 ENG-4521에 설명된 기능을 추가하고 GitHub에 PR을 생성해 줘."
모니터링 데이터 분석: "Sentry와 Statsig을 확인해서 ENG-4521에 설명된 기능의 사용량을 확인해 줘."
데이터베이스 쿼리: "PostgreSQL 데이터베이스를 기반으로 ENG-4521 기능을 사용한 무작위 사용자 10명의 이메일을 찾아줘."
디자인 통합: "Slack에 올라온 새로운 Figma 디자인을 기반으로 표준 이메일 템플릿을 업데이트해 줘."
워크플로우 자동화: "이 10명의 사용자에게 새 기능에 대한 피드백 세션 초대 Gmail 초안을 작성해 줘."

서버	설명
Notion	워크스페이스 검색/업데이트, 워크플로우 지원
Canva	디자인 검색, 생성, 자동 채우기 및 내보내기
Figma	Figma 컨텍스트에서 고품질 코드 생성
Slack	메시지 전송, 캔버스 생성, 데이터 조회
Atlassian	Jira/Confluence 이슈 및 문서 관리
Linear	이슈, 프로젝트 및 팀 워크플로우 관리
monday.com	프로젝트, 보드 및 워크플로우 관리
Vercel	프로젝트 배포 분석, 디버깅 및 관리
Sentry	오류 검색, 쿼리 및 지능형 디버깅
Asana	작업, 프로젝트 및 목표 조정
Supabase	데이터베이스, 인증 및 저장소 관리
ClickUp	프로젝트 관리 및 팀 협업
Hugging Face	Hub 및 Gradio 앱 접근
Excalidraw	손그림 스타일 다이어그램 생성
Context7	LLM/AI 코드 편집기용 최신 문서 제공

MCP 서버 설치

MCP 서버는 필요에 따라 세 가지 방법으로 구성할 수 있습니다:

옵션 1: 원격 HTTP 서버 추가

HTTP 서버는 원격 MCP 서버에 연결하기 위해 권장되는 옵션입니다. 클라우드 기반 서비스에서 가장 널리 지원되는 전송 방식입니다.

# Basic syntax
claude mcp add --transport http <name> <url>

# Real example: Connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Example with Bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

옵션 2: 원격 SSE 서버 추가

주의:

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

# Basic syntax
claude mcp add --transport sse <name> <url>

# Real example: Connect to Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Example with authentication header
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

옵션 3: 로컬 stdio 서버 추가

Stdio 서버는 로컬 머신에서 프로세스로 실행됩니다. 직접적인 시스템 접근이나 커스텀 스크립트가 필요한 도구에 적합합니다.

# Basic syntax
claude mcp add [options] <name> -- <command> [args...]

# Real example: Add Airtable server
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

참고:

중요: 옵션 순서

모든 옵션(--transport, --env, --scope, --header)은 서버 이름 앞에 와야 합니다. -- (이중 대시)는 서버 이름과 MCP 서버에 전달되는 명령어 및 인자를 구분합니다.

예시:

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

claude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080 → 환경 변수 KEY=value와 함께 python server.py --port 8080을 실행

이렇게 하면 Claude의 플래그와 서버의 플래그 간 충돌을 방지할 수 있습니다.

서버 관리

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

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get github

# Remove a server
claude mcp remove github

# (within Claude Code) Check server status
/mcp

동적 도구 업데이트

팁:

--scope 플래그를 사용하여 구성이 저장되는 위치를 지정할 수 있습니다:

local (기본값): 현재 프로젝트에서 자신만 사용 가능 (이전 버전에서는 project로 불림)

project: .mcp.json 파일을 통해 프로젝트의 모든 사람과 공유

user: 모든 프로젝트에서 자신이 사용 가능 (이전 버전에서는 global로 불림)

--env 플래그로 환경 변수를 설정할 수 있습니다 (예: --env KEY=value)

MCP_TIMEOUT 환경 변수를 사용하여 MCP 서버 시작 타임아웃을 설정할 수 있습니다 (예: MCP_TIMEOUT=10000 claude는 10초 타임아웃을 설정)

MCP 도구 출력이 10,000 토큰을 초과하면 Claude Code가 경고를 표시합니다. 이 제한을 늘리려면 MAX_MCP_OUTPUT_TOKENS 환경 변수를 설정하세요 (예: MAX_MCP_OUTPUT_TOKENS=50000)

/mcp를 사용하여 OAuth 2.0 인증이 필요한 원격 서버에 인증할 수 있습니다

주의:

Windows 사용자: 네이티브 Windows(WSL 제외)에서는 npx를 사용하는 로컬 MCP 서버에 cmd /c 래퍼가 필요합니다.
# This creates command="cmd" which Windows can execute
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package
cmd /c 래퍼가 없으면 Windows가 npx를 직접 실행할 수 없어 "Connection closed" 오류가 발생합니다. (-- 매개변수에 대한 설명은 위의 참고 사항을 확인하세요.)

플러그인 제공 MCP 서버

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

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

플러그인 MCP 구성 예시:

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

{
  "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 기능:

자동 수명주기: 플러그인이 활성화되면 서버가 시작되지만, MCP 서버 변경(활성화 또는 비활성화)을 적용하려면 Claude Code를 재시작해야 합니다
환경 변수: 플러그인 상대 경로에 ${CLAUDE_PLUGIN_ROOT}를 사용합니다
사용자 환경 접근: 수동으로 구성한 서버와 동일한 환경 변수에 접근 가능합니다
다양한 전송 방식 지원: stdio, SSE, HTTP 전송 방식을 지원합니다 (전송 방식 지원은 서버에 따라 다를 수 있음)

플러그인 MCP 서버 확인하기:

# Within Claude Code, see all MCP servers including plugin ones
/mcp

플러그인 서버는 플러그인에서 제공되었음을 나타내는 표시와 함께 목록에 표시됩니다.

플러그인 MCP 서버의 이점:

번들 배포: 도구와 서버가 함께 패키징됩니다
자동 설정: 수동 MCP 구성이 필요 없습니다
팀 일관성: 플러그인 설치 시 모든 사람이 동일한 도구를 사용할 수 있습니다

플러그인과 함께 MCP 서버를 번들링하는 자세한 내용은 플러그인 컴포넌트 레퍼런스를 참조하세요.

MCP 설치 범위

Local 범위

참고:

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

# 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

Project 범위

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

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

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

User 범위

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

적절한 범위 선택

다음 기준으로 범위를 선택하세요:

Local 범위: 개인 서버, 실험적 구성, 또는 하나의 프로젝트에 특화된 민감한 자격 증명
Project 범위: 팀 공유 서버, 프로젝트별 도구, 또는 협업에 필요한 서비스
User 범위: 여러 프로젝트에서 필요한 개인 유틸리티, 개발 도구, 또는 자주 사용하는 서비스

참고:

MCP 서버는 어디에 저장되나요?

User 및 local 범위: ~/.claude.json (mcpServers 필드 또는 프로젝트 경로 아래)

Project 범위: 프로젝트 루트의 .mcp.json (소스 관리에 체크인)

관리형(Managed): 시스템 디렉토리의 managed-mcp.json (관리형 MCP 구성 참조)

범위 계층 구조 및 우선순위

`.mcp.json`에서 환경 변수 확장

지원되는 구문:

${VAR} - 환경 변수 VAR의 값으로 확장
${VAR:-default} - VAR가 설정되어 있으면 그 값을 사용하고, 아니면 default를 사용

확장 위치:
환경 변수는 다음 위치에서 확장 가능합니다:

command - 서버 실행 파일 경로
args - 명령줄 인자
env - 서버에 전달되는 환경 변수
url - HTTP 서버 유형용
headers - HTTP 서버 인증용

변수 확장 예시:

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

필수 환경 변수가 설정되어 있지 않고 기본값도 없는 경우 Claude Code가 구성 파싱에 실패합니다.

실전 예시

예시: Sentry로 오류 모니터링

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

Sentry 계정으로 인증합니다:

/mcp

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

What are the most common errors in the last 24 hours?

Show me the stack trace for error ID abc123

Which deployment introduced these new errors?

예시: GitHub에 연결하여 코드 리뷰

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

필요한 경우 GitHub의 "Authenticate"를 선택하여 인증합니다:

/mcp

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

Review PR #456 and suggest improvements

Create a new issue for the bug we just found

Show me all open PRs assigned to me

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

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:[email protected]:5432/analytics"

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

What's our total revenue this month?

Show me the schema for the orders table

Find customers who haven't made a purchase in 90 days

원격 MCP 서버 인증

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

Step 1: 인증이 필요한 서버 추가

예시:

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

Step 2: Claude Code 내에서 /mcp 명령어 사용

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

/mcp

그런 다음 브라우저의 안내에 따라 로그인합니다.

팁:

인증 토큰은 안전하게 저장되며 자동으로 갱신됩니다

/mcp 메뉴에서 "Clear authentication"을 사용하여 접근을 취소할 수 있습니다

브라우저가 자동으로 열리지 않으면 제공된 URL을 복사하여 수동으로 여세요

인증 후 브라우저 리디렉션이 연결 오류와 함께 실패하면, 브라우저 주소 표시줄의 전체 콜백 URL을 Claude Code에 나타나는 URL 프롬프트에 붙여넣으세요

OAuth 인증은 HTTP 서버에서 작동합니다

고정 OAuth 콜백 포트 사용

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

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

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

Step 1: 서버에 OAuth 앱 등록

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

Step 2: 자격 증명과 함께 서버 추가

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 (callback port only)

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

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

CI / env var

대화형 프롬프트를 건너뛰려면 환경 변수로 시크릿을 설정합니다:

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

Step 3: Claude Code에서 인증

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

팁:

클라이언트 시크릿은 구성 파일이 아닌 시스템 키체인(macOS) 또는 자격 증명 파일에 안전하게 저장됩니다

서버가 시크릿 없는 공개 OAuth 클라이언트를 사용하는 경우, --client-secret 없이 --client-id만 사용하세요

--callback-port는 --client-id와 함께 또는 단독으로 사용할 수 있습니다

이 플래그들은 HTTP 및 SSE 전송 방식에만 적용됩니다. stdio 서버에는 영향이 없습니다

claude mcp get <name>을 사용하여 서버에 OAuth 자격 증명이 구성되었는지 확인하세요

OAuth 메타데이터 검색 재정의

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

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

URL은 https://를 사용해야 합니다. 이 옵션은 Claude Code v2.1.64 이상이 필요합니다.

JSON 구성에서 MCP 서버 추가

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

Step 1: JSON에서 MCP 서버 추가

# Basic syntax
claude mcp add-json <name> '<json>'

# Example: Adding an HTTP server with JSON configuration
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# Example: Adding a stdio server with JSON configuration
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# Example: Adding an HTTP server with pre-configured OAuth credentials
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

Step 2: 서버가 추가되었는지 확인

claude mcp get weather-api

팁:

셸에서 JSON이 올바르게 이스케이프되었는지 확인하세요

JSON은 MCP 서버 구성 스키마를 준수해야 합니다

--scope user를 사용하여 프로젝트별 구성 대신 사용자 구성에 서버를 추가할 수 있습니다

Claude Desktop에서 MCP 서버 가져오기

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

Step 1: Claude Desktop에서 서버 가져오기

# Basic syntax
claude mcp add-from-claude-desktop

Step 2: 가져올 서버 선택

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

Step 3: 서버가 가져와졌는지 확인

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에서 자동으로 사용 가능합니다:

Step 1: Claude.ai에서 MCP 서버 구성

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

Step 2: MCP 서버 인증

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

Step 3: Claude Code에서 서버 확인 및 관리

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

/mcp

Claude.ai 서버는 Claude.ai에서 제공되었음을 나타내는 표시와 함께 목록에 표시됩니다.

Claude Code에서 Claude.ai MCP 서버를 비활성화하려면 ENABLE_CLAUDEAI_MCP_SERVERS 환경 변수를 false로 설정합니다:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

Claude Code를 MCP 서버로 사용

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

# Start Claude as a stdio MCP server
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와 같은 오류가 발생합니다.

팁:

이 서버는 Claude의 View, Edit, LS 등의 도구에 대한 접근을 제공합니다.

Claude Desktop에서 디렉토리의 파일을 읽고, 편집하는 등의 작업을 요청해 보세요.

이 MCP 서버는 Claude Code의 도구를 MCP 클라이언트에 노출하기만 하므로, 개별 도구 호출에 대한 사용자 확인은 클라이언트 자체에서 구현해야 합니다.

MCP 출력 제한 및 경고

MCP 도구가 대량의 출력을 생성할 때, Claude Code는 대화 컨텍스트가 과부하되는 것을 방지하기 위해 토큰 사용량을 관리합니다:

출력 경고 임계값: MCP 도구 출력이 10,000 토큰을 초과하면 Claude Code가 경고를 표시합니다
설정 가능한 제한: MAX_MCP_OUTPUT_TOKENS 환경 변수를 사용하여 최대 허용 MCP 출력 토큰을 조정할 수 있습니다
기본 제한: 기본 최대값은 25,000 토큰입니다

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

# Set a higher limit for MCP tool outputs
export MAX_MCP_OUTPUT_TOKENS=50000
claude

이 기능은 다음과 같은 MCP 서버를 사용할 때 특히 유용합니다:

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

주의:

특정 MCP 서버에서 출력 경고가 자주 발생하는 경우, 제한을 늘리거나 서버가 응답을 페이지네이션하거나 필터링하도록 구성하는 것을 고려하세요.

MCP 리소스 사용

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

MCP 리소스 참조

Step 1: 사용 가능한 리소스 목록 보기

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

Step 2: 특정 리소스 참조

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

Can you analyze @github:issue://123 and suggest a fix?

Please review the API documentation at @docs:file://api/authentication

Step 3: 여러 리소스 참조

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

Compare @postgres:schema://users with @docs:file://database/user-model

팁:

리소스는 참조 시 자동으로 가져와 첨부 파일로 포함됩니다

리소스 경로는 @ 멘션 자동완성에서 퍼지 검색이 가능합니다

서버가 지원하는 경우 Claude Code가 MCP 리소스를 나열하고 읽는 도구를 자동으로 제공합니다

리소스는 MCP 서버가 제공하는 모든 유형의 콘텐츠(텍스트, JSON, 구조화된 데이터 등)를 포함할 수 있습니다

MCP Tool Search로 확장

작동 방식

MCP 도구가 컨텍스트에 미리 로드되지 않고 지연(defer)됩니다
Claude가 필요할 때 검색 도구를 사용하여 관련 MCP 도구를 검색합니다
Claude가 실제로 필요한 도구만 컨텍스트에 로드됩니다
사용자 관점에서 MCP 도구는 이전과 동일하게 작동합니다

MCP 서버 개발자를 위한 안내

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

도구가 처리하는 작업 카테고리
Claude가 도구를 검색해야 하는 시점
서버가 제공하는 주요 기능

Tool Search 구성

ENABLE_TOOL_SEARCH 환경 변수로 Tool Search 동작을 제어합니다:

Value	Behavior
`auto`	MCP 도구가 컨텍스트의 10%를 초과하면 활성화 (기본값)
`auto:<N>`	사용자 정의 임계값으로 활성화, `<N>`은 백분율 (예: `auto:5`는 5%)
`true`	항상 활성화
`false`	비활성화, 모든 MCP 도구를 미리 로드

# Use a custom 5% threshold
ENABLE_TOOL_SEARCH=auto:5 claude

# Disable tool search entirely
ENABLE_TOOL_SEARCH=false claude

또는 settings.json env 필드에서 값을 설정할 수 있습니다.

disallowedTools 설정을 사용하여 MCPSearch 도구를 구체적으로 비활성화할 수도 있습니다:

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

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

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

MCP 프롬프트 실행

Step 1: 사용 가능한 프롬프트 검색

/를 입력하면 MCP 서버의 프롬프트를 포함한 모든 사용 가능한 명령어를 볼 수 있습니다. MCP 프롬프트는 /mcp__servername__promptname 형식으로 표시됩니다.

Step 2: 인자 없이 프롬프트 실행

/mcp__github__list_prs

Step 3: 인자와 함께 프롬프트 실행

많은 프롬프트는 인자를 받습니다. 명령어 뒤에 공백으로 구분하여 전달합니다:

/mcp__github__pr_review 456

/mcp__jira__create_issue "Bug in login flow" high

팁:

MCP 프롬프트는 연결된 서버에서 동적으로 검색됩니다

인자는 프롬프트에 정의된 매개변수를 기반으로 파싱됩니다

프롬프트 결과는 대화에 직접 주입됩니다

서버 및 프롬프트 이름은 정규화됩니다 (공백은 밑줄로 변환)

관리형 MCP 구성

중앙 집중식 MCP 서버 관리가 필요한 조직을 위해 Claude Code는 두 가지 구성 옵션을 지원합니다:

managed-mcp.json을 통한 독점적 제어: 사용자가 수정하거나 확장할 수 없는 고정된 MCP 서버 세트를 배포합니다
허용 목록/차단 목록을 통한 정책 기반 제어: 사용자가 자체 서버를 추가할 수 있지만 허용되는 서버를 제한합니다

이러한 옵션을 통해 IT 관리자는 다음을 수행할 수 있습니다:

직원이 접근할 수 있는 MCP 서버 제어: 조직 전체에 표준화된 승인 MCP 서버 세트를 배포합니다
승인되지 않은 MCP 서버 방지: 사용자가 승인되지 않은 MCP 서버를 추가하는 것을 제한합니다
MCP 완전 비활성화: 필요한 경우 MCP 기능을 완전히 제거합니다

옵션 1: managed-mcp.json을 통한 독점적 제어

시스템 관리자는 구성 파일을 시스템 전체 디렉토리에 배포합니다:

macOS: /Library/Application Support/ClaudeCode/managed-mcp.json
Linux 및 WSL: /etc/claude-code/managed-mcp.json
Windows: C:\Program Files\ClaudeCode\managed-mcp.json

참고:

이것은 시스템 전체 경로이며 (사용자 홈 디렉토리 ~/Library/...가 아님) 관리자 권한이 필요합니다. IT 관리자가 배포하도록 설계되었습니다.

managed-mcp.json 파일은 표준 .mcp.json 파일과 동일한 형식을 사용합니다:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"],
      "env": {
        "COMPANY_API_URL": "https://internal.company.com"
      }
    }
  }
}

옵션 2: 허용 목록과 차단 목록을 통한 정책 기반 제어

참고:

옵션 간 선택: 사용자 맞춤 없이 고정된 서버 세트를 배포하려면 옵션 1(managed-mcp.json)을 사용하세요. 정책 제약 내에서 사용자가 자체 서버를 추가할 수 있도록 하려면 옵션 2(허용 목록/차단 목록)를 사용하세요.

제한 옵션

허용 목록 또는 차단 목록의 각 항목은 세 가지 방법으로 서버를 제한할 수 있습니다:

서버 이름 기준 (serverName): 서버의 구성된 이름과 일치
명령어 기준 (serverCommand): stdio 서버를 시작하는 데 사용되는 정확한 명령어 및 인자와 일치
URL 패턴 기준 (serverUrl): 와일드카드를 지원하여 원격 서버 URL과 일치

중요: 각 항목에는 serverName, serverCommand, serverUrl 중 정확히 하나만 있어야 합니다.

구성 예시

{
  "allowedMcpServers": [
    // Allow by server name
    { "serverName": "github" },
    { "serverName": "sentry" },

    // Allow by exact command (for stdio servers)
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },
    { "serverCommand": ["python", "/usr/local/bin/approved-server.py"] },

    // Allow by URL pattern (for remote servers)
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ],
  "deniedMcpServers": [
    // Block by server name
    { "serverName": "dangerous-server" },

    // Block by exact command (for stdio servers)
    { "serverCommand": ["npx", "-y", "unapproved-package"] },

    // Block by URL pattern (for remote servers)
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}

명령어 기반 제한의 작동 방식

정확한 일치:

명령어 배열은 정확히 일치해야 합니다 - 명령어와 모든 인자가 올바른 순서여야 합니다
예: ["npx", "-y", "server"]는 ["npx", "server"]나 ["npx", "-y", "server", "--flag"]와 일치하지 않습니다

Stdio 서버 동작:

허용 목록에 serverCommand 항목이 하나라도 포함되면 stdio 서버는 해당 명령어 중 하나와 반드시 일치해야 합니다
명령어 제한이 있으면 stdio 서버는 이름만으로 통과할 수 없습니다
이를 통해 관리자가 실행 가능한 명령어를 강제할 수 있습니다

비-stdio 서버 동작:

원격 서버(HTTP, SSE, WebSocket)는 허용 목록에 serverUrl 항목이 있으면 URL 기반 일치를 사용합니다
URL 항목이 없으면 원격 서버는 이름 기반 일치로 대체됩니다
명령어 제한은 원격 서버에 적용되지 않습니다

URL 기반 제한의 작동 방식

URL 패턴은 *를 사용한 와일드카드를 지원하여 임의의 문자 시퀀스와 일치시킵니다. 전체 도메인 또는 하위 도메인을 허용하는 데 유용합니다.

와일드카드 예시:

https://mcp.company.com/* - 특정 도메인의 모든 경로 허용
https://*.example.com/* - example.com의 모든 하위 도메인 허용
http://localhost:*/* - localhost의 모든 포트 허용

원격 서버 동작:

허용 목록에 serverUrl 항목이 하나라도 포함되면 원격 서버는 해당 URL 패턴 중 하나와 반드시 일치해야 합니다
URL 제한이 있으면 원격 서버는 이름만으로 통과할 수 없습니다
이를 통해 관리자가 허용되는 원격 엔드포인트를 강제할 수 있습니다

예시: URL 전용 허용 목록

{
  "allowedMcpServers": [
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ]
}

결과:

https://mcp.company.com/api의 HTTP 서버: ✅ 허용 (URL 패턴 일치)
https://api.internal.corp/mcp의 HTTP 서버: ✅ 허용 (와일드카드 하위 도메인 일치)
https://external.com/mcp의 HTTP 서버: ❌ 차단 (URL 패턴과 일치하지 않음)
임의의 명령어를 가진 Stdio 서버: ❌ 차단 (일치할 이름 또는 명령어 항목 없음)

예시: 명령어 전용 허용 목록

{
  "allowedMcpServers": [
    { "serverCommand": ["npx", "-y", "approved-package"] }
  ]
}

결과:

["npx", "-y", "approved-package"] 명령어의 Stdio 서버: ✅ 허용 (명령어 일치)
["node", "server.js"] 명령어의 Stdio 서버: ❌ 차단 (명령어 불일치)
"my-api"라는 이름의 HTTP 서버: ❌ 차단 (일치할 이름 항목 없음)

예시: 이름과 명령어 혼합 허용 목록

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverCommand": ["npx", "-y", "approved-package"] }
  ]
}

결과:

["npx", "-y", "approved-package"] 명령어의 "local-tool" Stdio 서버: ✅ 허용 (명령어 일치)
["node", "server.js"] 명령어의 "local-tool" Stdio 서버: ❌ 차단 (명령어 항목이 존재하지만 일치하지 않음)
["node", "server.js"] 명령어의 "github" Stdio 서버: ❌ 차단 (명령어 항목이 존재하면 stdio 서버는 반드시 명령어와 일치해야 함)
"github"이라는 이름의 HTTP 서버: ✅ 허용 (이름 일치)
"other-api"라는 이름의 HTTP 서버: ❌ 차단 (이름 불일치)

예시: 이름 전용 허용 목록

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "internal-tool" }
  ]
}

결과:

임의의 명령어를 가진 "github" Stdio 서버: ✅ 허용 (명령어 제한 없음)
임의의 명령어를 가진 "internal-tool" Stdio 서버: ✅ 허용 (명령어 제한 없음)
"github"이라는 이름의 HTTP 서버: ✅ 허용 (이름 일치)
"other"라는 이름의 모든 서버: ❌ 차단 (이름 불일치)

허용 목록 동작 (`allowedMcpServers`)

undefined (기본값): 제한 없음 - 사용자가 모든 MCP 서버를 구성 가능
빈 배열 []: 완전 잠금 - 사용자가 MCP 서버를 구성할 수 없음
항목 목록: 사용자는 이름, 명령어 또는 URL 패턴으로 일치하는 서버만 구성 가능

차단 목록 동작 (`deniedMcpServers`)

undefined (기본값): 차단되는 서버 없음
빈 배열 []: 차단되는 서버 없음
항목 목록: 지정된 서버가 모든 범위에서 명시적으로 차단됨

중요 참고 사항

옵션 1과 옵션 2는 결합 가능: managed-mcp.json이 존재하면 독점적 제어를 가지며 사용자는 서버를 추가할 수 없습니다. 허용 목록/차단 목록은 관리형 서버 자체에도 여전히 적용됩니다.
차단 목록이 절대적 우선: 서버가 차단 목록 항목(이름, 명령어 또는 URL)과 일치하면 허용 목록에 있더라도 차단됩니다
이름 기반, 명령어 기반, URL 기반 제한은 함께 작동합니다: 서버는 이름 항목, 명령어 항목 또는 URL 패턴 중 하나라도 일치하면 통과합니다 (차단 목록에 의해 차단되지 않는 한)

참고:

managed-mcp.json 사용 시: 사용자는 claude mcp add 또는 구성 파일을 통해 MCP 서버를 추가할 수 없습니다. allowedMcpServers 및 deniedMcpServers 설정은 실제로 로드되는 관리형 서버를 필터링하는 데 여전히 적용됩니다.

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

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

MCP로 할 수 있는 것

인기 MCP 서버

MCP 서버 설치

옵션 1: 원격 HTTP 서버 추가

옵션 2: 원격 SSE 서버 추가

옵션 3: 로컬 stdio 서버 추가

서버 관리

동적 도구 업데이트

플러그인 제공 MCP 서버

MCP 설치 범위

Local 범위

Project 범위

User 범위

적절한 범위 선택

범위 계층 구조 및 우선순위

.mcp.json에서 환경 변수 확장

실전 예시

예시: Sentry로 오류 모니터링

예시: GitHub에 연결하여 코드 리뷰

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

원격 MCP 서버 인증

Step 1: 인증이 필요한 서버 추가

Step 2: Claude Code 내에서 /mcp 명령어 사용

고정 OAuth 콜백 포트 사용

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

Step 1: 서버에 OAuth 앱 등록

Step 2: 자격 증명과 함께 서버 추가

Step 3: Claude Code에서 인증

OAuth 메타데이터 검색 재정의

JSON 구성에서 MCP 서버 추가

Step 1: JSON에서 MCP 서버 추가

Step 2: 서버가 추가되었는지 확인

Claude Desktop에서 MCP 서버 가져오기

Step 1: Claude Desktop에서 서버 가져오기

Step 2: 가져올 서버 선택

Step 3: 서버가 가져와졌는지 확인

Claude.ai의 MCP 서버 사용

Step 1: Claude.ai에서 MCP 서버 구성

Step 2: MCP 서버 인증

Step 3: Claude Code에서 서버 확인 및 관리

Claude Code를 MCP 서버로 사용

MCP 출력 제한 및 경고

MCP 리소스 사용

MCP 리소스 참조

Step 1: 사용 가능한 리소스 목록 보기

Step 2: 특정 리소스 참조

Step 3: 여러 리소스 참조

MCP Tool Search로 확장

작동 방식

MCP 서버 개발자를 위한 안내

Tool Search 구성

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

MCP 프롬프트 실행

Step 1: 사용 가능한 프롬프트 검색

Step 2: 인자 없이 프롬프트 실행

Step 3: 인자와 함께 프롬프트 실행

관리형 MCP 구성

옵션 1: managed-mcp.json을 통한 독점적 제어

옵션 2: 허용 목록과 차단 목록을 통한 정책 기반 제어

제한 옵션

구성 예시

명령어 기반 제한의 작동 방식

URL 기반 제한의 작동 방식

허용 목록 동작 (allowedMcpServers)

차단 목록 동작 (deniedMcpServers)

중요 참고 사항

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

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

MCP로 할 수 있는 것

인기 MCP 서버

MCP 서버 설치

옵션 1: 원격 HTTP 서버 추가

옵션 2: 원격 SSE 서버 추가

옵션 3: 로컬 stdio 서버 추가

서버 관리

동적 도구 업데이트

플러그인 제공 MCP 서버

MCP 설치 범위

`.mcp.json`에서 환경 변수 확장

허용 목록 동작 (`allowedMcpServers`)

차단 목록 동작 (`deniedMcpServers`)

`.mcp.json`에서 환경 변수 확장

허용 목록 동작 (`allowedMcpServers`)

차단 목록 동작 (`deniedMcpServers`)