Model Context Protocol로 외부 도구와 데이터 소스 연결
MCP는 AI 모델과 외부 도구, 데이터 소스를 연결하는 오픈소스 표준 프로토콜입니다. Anthropic이 주도하여 개발했으며, Claude Code에서 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 서버는 프롬프트 인젝션 위험에 노출될 수 있으므로 주의가 필요합니다.
Claude Code에 연결할 수 있는 일반적인 MCP 서버들입니다. 더 많은 MCP 서버는 GitHub에서 찾아볼 수 있으며, MCP SDK를 사용하여 직접 만들 수도 있습니다.
MCP 서버는 필요에 따라 3가지 방식으로 설정할 수 있습니다.
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"SSE(Server-Sent Events) 전송 방식은 더 이상 지원되지 않습니다. 가능하면 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 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
}
}
}MCP 서버가 추가 정보를 요청하는 경우 적절히 응답하여 작업을 완료할 수 있습니다.
MCP 서버가 제공하는 리소스(문서, 설정, 데이터)를 직접 참조할 수 있습니다.
필요한 리소스를 MCP 서버에 요청하여 컨텍스트 확장이 가능합니다.
Claude Code는 MCP 서버가 제공하는 도구를 자동으로 발견하고 인덱싱합니다. 사용자가 특정 작업을 요청할 때, Claude는 적절한 도구를 자동으로 선택합니다.
MCP 서버를 개발할 때 도구의 설명과 메타데이터를 명확하게 정의하면 Claude Code의 도구 검색이 더 효율적으로 작동합니다.
MCP 서버가 제공하는 프롬프트 템플릿을 명령어처럼 실행할 수 있습니다. 예를 들어, "@code-review"라는 프롬프트를 통해 자동화된 코드 리뷰 프로세스를 시작할 수 있습니다.
엔터프라이즈 환경에서 MCP 서버의 사용을 제어하고 제한할 수 있습니다.
managed-mcp.json 파일을 통해 조직에서 승인한 MCP 서버만 사용하도록 제한할 수 있습니다. 이 설정은 사용자가 추가로 MCP 서버를 설치하는 것을 완전히 차단합니다.
{
"managedMcpServers": {
"sentry": {
"transport": "http",
"url": "https://mcp.sentry.io/mcp",
"headers": {
"Authorization": "Bearer ${SENTRY_TOKEN}"
}
},
"github": {
"transport": "stdio",
"command": "npx",
"args": ["@modelcontextprotocol/server-github"]
}
}
}조직에서 승인한 MCP 서버를 명시적으로 지정하거나, 특정 서버를 거부할 수 있습니다.
{
"allowedMcpServers": ["sentry", "github", "postgres"],
"deniedMcpServers": ["untrusted-server"],
"allowedUrls": ["https://mcp.*.io", "https://api.company.com"],
"allowedCommands": ["npx", "python", "node"]
}MCP 서버를 stdio 전송으로 추가할 때, 지정된 명령어만 실행 가능하도록 제한합니다.
HTTP/SSE 전송을 사용하는 경우, 허용된 URL 패턴만 연결할 수 있습니다.
허용 목록에 명시된 서버만 사용 가능합니다. 다른 모든 서버는 거부됩니다.
거부 목록에 명시된 서버는 사용할 수 없습니다. 다른 서버는 모두 허용됩니다.
관리형 MCP 설정은 조직 정책을 시행하기 위한 것이므로, 관리자 권한이 있는 사용자만 수정할 수 있어야 합니다.
Model Context Protocol은 다음의 핵심 프로젝트들로 구성됩니다:
MCP는 컨텍스트 교환 프로토콜에만 집중하며, AI 애플리케이션이 LLM을 어떻게 사용하거나 컨텍스트를 어떻게 관리할지는 정하지 않습니다.
MCP는 클라이언트-서버 아키텍처를 따릅니다:
예시: Visual Studio Code가 MCP Host 역할을 하면, Sentry MCP 서버에 연결할 때 하나의 MCP Client를 생성하고, 로컬 파일시스템 서버에도 연결할 때 또 다른 MCP Client를 생성합니다. 각 MCP Client는 해당 MCP Server와 전용 연결을 유지합니다.
중요한 특성:
Local vs Remote MCP Server:
MCP는 두 가지 계층으로 구성됩니다:
JSON-RPC 2.0 기반 프로토콜을 구현하며, 클라이언트와 서버 간의 메시지 구조와 의미를 정의합니다. 데이터 계층은 다음을 포함합니다:
전송 계층은 클라이언트와 서버 간의 통신 채널과 인증을 관리합니다. 연결 설정, 메시지 프레이밍, 보안 통신을 처리합니다.
MCP는 두 가지 전송 메커니즘을 지원합니다:
개념적으로 데이터 계층이 내부 계층이고 전송 계층이 외부 계층입니다.