Model Context Protocol로 외부 도구와 데이터 소스 연결
Claude Code는 **Model Context Protocol (MCP)**을 통해 수백 가지의 외부 도구 및 데이터 소스에 연결할 수 있습니다. MCP는 AI-도구 통합을 위한 오픈소스 표준입니다. MCP 서버는 Claude Code에 도구, 데이터베이스 및 API에 대한 액세스를 제공합니다. 이슈 트래커나 모니터링 대시보드와 같은 다른 도구에서 데이터를 채팅으로 복사하는 자신을 발견할 때 서버를 연결하세요. 일단 연결되면 Claude는 사용자가 붙여넣는 내용으로 작업하는 대신 해당 시스템을 직접 읽고 조작할 수 있습니다. 첫 서버를 연결하는 경우, 단계별 안내를 위해 MCP 퀵스타트부터 시작하세요. 이 페이지는 전체 참조 문서입니다.
MCP는 쉽게 말해 "AI에게 외부 도구를 연결해주는 USB 포트" 같은 것입니다.
예를 들어 Claude Code에 Notion MCP를 연결하면, "Notion에서 회의록 찾아줘"라고 말하는 것만으로 AI가 직접 Notion을 검색합니다. GitHub MCP를 연결하면 "최근 PR 목록 보여줘"라고 말하면 됩니다.
MCP 없이는 Claude Code가 코드 파일만 다룰 수 있지만, MCP를 연결하면 Notion, GitHub, Slack, 데이터베이스 등 외부 서비스를 AI가 직접 조작할 수 있게 됩니다.
MCP를 사용하면 Claude Code가 외부 API를 직접 호출하거나, 데이터베이스를 조회하거나, SaaS 도구를 조작할 수 있습니다.
MCP 서버가 연결되어 있으면 Claude Code에 다음과 같이 요청할 수 있습니다. 다른 도구에서 데이터를 복사해서 chat에 붙여넣는 경우, MCP 서버를 연결하면 Claude가 그 시스템을 직접 읽고 작업할 수 있으므로 더 효율적입니다. 이슈 트래커나 모니터링 대시보드 같은 도구를 발견했다면 서버를 연결해보세요.
타사 MCP 서버를 사용할 때는 주의가 필요합니다. Anthropic은 모든 MCP 서버의 정확성이나 보안을 검증하지 않습니다. 신뢰할 수 있는 MCP 서버만 설치하세요. 특히 신뢰할 수 없는 콘텐츠를 가져올 수 있는 MCP 서버는 프롬프트 인젝션 위험에 노출될 수 있으므로 주의가 필요합니다.
Anthropic Directory에서 검토된 커넥터를 찾아보세요. 디렉토리 커넥터는 Claude Code와 동일한 MCP 인프라를 사용하므로, claude mcp add 명령으로 나열된 원격 서버를 추가할 수 있습니다. 각 서버를 연결하기 전에 신뢰할 수 있는지 확인하세요. 외부 콘텐츠를 가져오는 서버는 프롬프트 인젝션 위험에 노출될 수 있습니다.
자신만의 서버를 빌드하려면, 프로토콜 기본 사항에 대한 MCP 서버 가이드와 인증, 테스트 및 디렉토리 제출에 대한 Claude 커넥터 빌드 문서를 참조하세요. 또한 공식 mcp-server-dev 플러그인을 사용하여 Claude가 서버를 스캐폴드(scaffold)하도록 할 수도 있습니다.
Claude Code 세션에서 다음을 실행하세요:
/plugin install mcp-server-dev@claude-plugins-officialClaude Code가 Marketplace "claude-plugins-official" not found를 보고하면, /plugin marketplace add anthropics/claude-plugins-official 명령으로 마켓플레이스를 추가하세요. 플러그인이 마켓플레이스에서 찾을 수 없다고 보고하면, 로컬 복사본이 오래된 것입니다. /plugin marketplace update claude-plugins-official 명령으로 새로고침한 다음 다시 설치를 시도하세요. 설치가 완료되면 /reload-plugins를 실행하여 현재 세션에서 활성화하세요.
/mcp-server-dev:build-mcp-serverClaude가 사용 사례에 대해 묻고 원격 HTTP 또는 로컬 stdio 서버를 스캐폴드합니다.
MCP 서버는 필요에 따라 여러 가지 방식으로 설정할 수 있습니다.
HTTP 서버는 원격 MCP 서버에 연결하기 위한 권장 방식입니다. 클라우드 기반 서비스에서 가장 널리 지원되는 전송 방식입니다.
# 기본 문법
claude mcp add --transport http <name> <url>
# 실제 예제: Notion 연결
claude mcp add --transport http notion https://mcp.notion.com/mcp
# Bearer 토큰을 사용한 예제
claude mcp add --transport http secure-api https://api.example.com/mcp \
--header "Authorization: Bearer your-token".mcp.json, ~/.claude.json 또는 claude mcp add-json을 통해 JSON으로 MCP 서버를 설정할 때, type 필드는 http의 별칭으로 streamable-http를 허용합니다. MCP 사양은 이 전송 방식에 streamable-http라는 이름을 사용하므로, 서버 문서에서 복사한 설정은 수정 없이 작동합니다. url은 있지만 type이 없는 JSON 항목은 설정 오류입니다. Claude Code는 type이 없는 항목을 stdio 서버로 읽기 때문에 해당 서버를 건너뛰고 MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry라고 보고합니다. v2.1.20 이전에는 Claude Code가 이 잘못된 설정을 command: expected string, received undefined로 보고했습니다.
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"Stdio 서버는 당신의 머신에서 로컬 프로세스로 실행됩니다. 시스템에 직접 접근하거나 사용자 정의 스크립트를 실행해야 하는 도구에 이상적입니다. Claude Code는 생성된 서버의 환경에 CLAUDE_PROJECT_DIR을 프로젝트 루트로 설정하므로, 서버는 작업 디렉토리에 의존하지 않고 프로젝트 상대 경로를 확인할 수 있습니다. 이는 훅(hooks)이 CLAUDE_PROJECT_DIR 변수에서 받는 것과 동일한 디렉토리입니다. Node에서는 process.env.CLAUDE_PROJECT_DIR 또는 Python에서는 os.environ["CLAUDE_PROJECT_DIR"]과 같이 서버 프로세스 내부에서 읽을 수 있습니다. CLAUDE_PROJECT_DIR은 안정적인 프로젝트 루트이며, 세션 중간에 작업 디렉토리를 추가하거나 제거해도 변경되지 않습니다. 파일 시스템 접근을 허용된 디렉토리 집합으로 제한하는 서버는 대신 MCP roots/list 요청을 구현해야 합니다. Claude Code는 roots/list 요청에 세션의 시작 디렉토리와 --add-dir, /add-dir 또는 additionalDirectories 설정으로 부여한 모든 추가 작업 디렉토리로 응답합니다. Claude Code는 해당 집합이 변경될 때 notifications/roots/list_changed를 보냅니다. v2.1.203 이전에는 roots/list가 시작 디렉토리만 반환했으며 Claude Code는 notifications/roots/list_changed를 보내지 않았습니다. 이 변수는 서버의 환경에 설정되며, Claude Code 자체 환경에는 설정되지 않으므로, 프로젝트 범위의 .mcp.json 항목 또는 ~/.claude.json의 로컬 또는 사용자 범위 서버 항목의 command 또는 args에서 ${VAR} 확장을 통해 참조하려면 ${CLAUDE_PROJECT_DIR:-.}와 같은 기본값이 필요합니다.
# 기본 문법
claude mcp add [options] <name> -- <command> [args...]
# 실제 예제: Airtable 서버 추가
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
-- npx -y airtable-mcp-server모든 옵션(--transport, --env, --scope, --header)은 서버 이름 앞에 위치해야 합니다. --(더블 대시)가 Claude의 플래그와 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 서버를 관리하기 위한 명령어들입니다.
# 설정된 모든 서버 목록 조회
claude mcp list
# 특정 서버의 상세 정보 확인
claude mcp get github
# MCP 서버 연결 제거
claude mcp remove github
# (Claude Code 내에서) 서버 상태 확인
/mcpClaude Code는 MCP의 list_changed 알림을 지원하므로, MCP 서버가 재연결 없이도 사용 가능한 도구, 프롬프트, 리소스를 동적으로 업데이트할 수 있습니다. MCP 서버가 list_changed 알림을 보내면, Claude Code는 자동으로 새로운 도구 목록을 가져옵니다.
Claude Code는 MCP 서버와의 연결이 끊어진 경우 자동으로 재연결을 시도합니다. 이를 통해 일시적인 네트워크 문제나 서버 재시작으로 인한 연결 손실을 자동으로 복구할 수 있습니다.
MCP 서버는 채널(channel) 기능을 통해 Claude Code 세션으로 메시지를 푸시할 수 있습니다. 이를 통해 외부 이벤트(예: Telegram 메시지, Discord 알림, webhook 이벤트)가 발생할 때 Claude가 자동으로 반응하도록 구성할 수 있습니다.
설치한 플러그인은 자체 MCP 서버를 제공할 수 있습니다. 이 경우 별도의 설정 없이 플러그인 설치 시 자동으로 해당 MCP 서버가 활성화됩니다.
MCP 서버는 3가지 범위로 설치할 수 있습니다.
scope는 MCP 서버의 적용 범위를 정하는 것입니다.
예를 들어, 특정 프로젝트에서만 Notion을 사용한다면 --scope project로 설정하고, 모든 프로젝트에서 GitHub를 사용한다면 --scope local 또는 --scope user로 설정합니다.
| 범위 | 설정 파일 | 적용 대상 | 사용 시점 |
|---|---|---|---|
| local | ~/.claude/claude.json | 현재 사용자 전체 | 개인 도구 (기본값) |
| project | .mcp.json | 해당 프로젝트 | 팀 공유 도구 |
| user | 클라우드 설정 | 사용자 계정 전체 | 클라우드 동기화 필요 시 |
# 프로젝트 범위로 설치 (팀 공유, .mcp.json에 저장)
claude mcp add --scope project notion --transport http https://mcp.notion.com/mcp
# 로컬 범위로 설치 (개인 전용, 기본값)
claude mcp add --scope local github --transport stdio -- npx -y @modelcontextprotocol/server-github특정 MCP 서버가 여러 범위에서 정의된 경우, 다음 우선순위로 적용됩니다:
프로젝트 범위의 설정이 있으면 그 외 범위의 동일한 서버 설정을 무시합니다.
.mcp.json 파일에서 환경 변수를 참조할 수 있습니다. $VARIABLE_NAME 또는 ${VARIABLE_NAME} 형식으로 사용하면, Claude Code가 실행될 때 해당 환경 변수 값으로 자동으로 확장됩니다.
Sentry MCP를 연결하여 실시간 에러 데이터를 분석할 수 있습니다.
claude mcp add --transport http sentry https://mcp.sentry.io/mcp \
--header "Authorization: Bearer your-sentry-token"GitHub MCP를 연결하여 PR을 검토하고 피드백을 제공할 수 있습니다.
claude mcp add --transport stdio github -- npx -y @modelcontextprotocol/server-githubPostgreSQL MCP를 통해 데이터베이스를 직접 쿼리할 수 있습니다.
claude mcp add --transport stdio --env DATABASE_URL=postgresql://user:pass@localhost/db postgres \
-- npx -y @modelcontextprotocol/server-postgresOAuth를 사용하는 MCP 서버의 경우 특정 포트를 콜백으로 지정할 수 있습니다.
OAuth 토큰을 환경 변수로 미리 설정하여 자동 인증을 구성할 수 있습니다.
Custom OAuth 제공자의 경우 메타데이터 발견을 재정의할 수 있습니다.
OAuth 인증 시 필요한 범위만 요청하도록 설정할 수 있습니다.
API 키나 커스텀 인증 헤더를 동적으로 전달할 수 있습니다.
claude mcp add --transport http custom-api https://api.example.com/mcp \
--header "X-API-Key: ${API_KEY}" \
--header "X-Custom-Auth: ${CUSTOM_TOKEN}".mcp.json 파일에 JSON 형식으로 MCP 서버를 설정할 수 있습니다:
{
"mcpServers": {
"notion": {
"transport": "http",
"url": "https://mcp.notion.com/mcp",
"headers": {
"Authorization": "Bearer ${NOTION_TOKEN}"
}
},
"github": {
"transport": "stdio",
"command": "npx",
"args": ["@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "${GITHUB_TOKEN}"
}
}
}
}Claude Desktop에 설정된 MCP 서버를 Claude Code로 가져올 수 있습니다. Claude Desktop의 설정 디렉토리를 연결하면 동일한 MCP 서버를 공유할 수 있습니다.
Claude.ai 웹 버전에서도 특정 MCP 서버를 연결할 수 있습니다. 웹 기반 서비스와의 통합이 필요한 경우 HTTP 또는 SSE 전송을 사용하세요.
Claude Code 자체를 MCP 서버로 설정하여, 다른 Claude 애플리케이션에서 Code 기능을 활용할 수 있습니다.
대용량 데이터를 처리하는 MCP 도구의 경우 출력 제한을 늘릴 수 있습니다:
{
"mcpServers": {
"database": {
"transport": "stdio",
"command": "python",
"args": ["server.py"],
"outputLimit": 100000
}
}
}