Model Context Protocol (MCP)

Model Context Protocol (MCP)은 LLM이 외부 도구와 데이터 소스에 액세스할 수 있도록 하는 개방형 프로토콜입니다. MCP에 대한 자세한 내용은 MCP 문서를 참조하세요.

​

MCP 서버 구성

# 기본 구문
claude mcp add <name> <command> [args...]

# 예시: 로컬 서버 추가
claude mcp add my-server -e API_KEY=123 -- /path/to/server arg1 arg2

# 기본 구문
claude mcp add --transport sse <name> <url>

# 예시: SSE 서버 추가
claude mcp add --transport sse sse-server https://example.com/sse-endpoint

# 예시: 사용자 정의 헤더가 있는 SSE 서버 추가
claude mcp add --transport sse api-server https://api.example.com/mcp -e X-API-Key=your-key

# 기본 구문
claude mcp add --transport http <name> <url>

# 예시: 스트리밍 가능한 HTTP 서버 추가
claude mcp add --transport http http-server https://example.com/mcp

# 예시: 인증 헤더가 있는 HTTP 서버 추가
claude mcp add --transport http secure-server https://api.example.com/mcp -e Authorization="Bearer your-token"

# 구성된 모든 서버 목록 표시
claude mcp list

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

# 서버 제거
claude mcp remove my-server

​

MCP 서버 범위 이해

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

​

범위 계층 및 우선순위

MCP 서버 구성은 명확한 우선순위 계층을 따릅니다. 동일한 이름의 서버가 여러 범위에 존재할 때, 시스템은 로컬 범위 서버를 먼저 우선시하고, 그 다음 프로젝트 범위 서버, 마지막으로 사용자 범위 서버 순으로 충돌을 해결합니다. 이 설계는 필요할 때 개인 구성이 공유 구성을 재정의할 수 있도록 보장합니다.

​

로컬 범위

로컬 범위 서버는 기본 구성 수준을 나타내며 프로젝트별 사용자 설정에 저장됩니다. 이러한 서버는 사용자에게만 비공개로 유지되며 현재 프로젝트 디렉터리 내에서 작업할 때만 액세스할 수 있습니다. 이 범위는 개인 개발 서버, 실험적 구성 또는 공유되어서는 안 되는 민감한 자격 증명이 포함된 서버에 이상적입니다.

# 로컬 범위 서버 추가 (기본값)
claude mcp add my-private-server /path/to/server

# 명시적으로 로컬 범위 지정
claude mcp add my-private-server -s local /path/to/server

​

프로젝트 범위

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

# 프로젝트 범위 서버 추가
claude mcp add shared-server -s project /path/to/server

결과 .mcp.json 파일은 표준화된 형식을 따릅니다:

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

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

​

사용자 범위

사용자 범위 서버는 프로젝트 간 접근성을 제공하여 사용자 계정에 비공개로 유지하면서 머신의 모든 프로젝트에서 사용할 수 있게 합니다. 이 범위는 개인 유틸리티 서버, 개발 도구 또는 다양한 프로젝트에서 자주 사용하는 서비스에 적합합니다.

# 사용자 서버 추가
claude mcp add my-user-server -s user /path/to/server

​

올바른 범위 선택

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

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

​

원격 MCP 서버와 인증

많은 원격 MCP 서버는 인증이 필요합니다. Claude Code는 이러한 서버에 안전하게 연결하기 위한 OAuth 2.0 인증 플로우를 지원합니다.

# OAuth가 필요한 SSE 또는 HTTP 서버 추가
claude mcp add --transport sse github-server https://api.github.com/mcp

> /mcp

​

Postgres MCP 서버에 연결

Claude에게 쿼리 및 스키마 검사를 위해 PostgreSQL 데이터베이스에 대한 읽기 전용 액세스 권한을 부여하려고 한다고 가정해 보겠습니다.

claude mcp add postgres-server /path/to/postgres-mcp-server --connection-string "postgresql://user:pass@localhost:5432/mydb"

> 사용자 테이블의 스키마를 설명해 주세요

> 시스템에서 가장 최근 주문은 무엇인가요?

> 고객과 송장 간의 관계를 보여주세요

​

JSON 구성에서 MCP 서버 추가

Claude Code에 추가하려는 단일 MCP 서버에 대한 JSON 구성이 있다고 가정해 보겠습니다.

# 기본 구문
claude mcp add-json <name> '<json>'

# 예시: JSON 구성으로 stdio 서버 추가
claude mcp add-json weather-api '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

claude mcp get weather-api

​

Claude Desktop에서 MCP 서버 가져오기

Claude Desktop에서 이미 MCP 서버를 구성했고 수동으로 다시 구성하지 않고 Claude Code에서 동일한 서버를 사용하려고 한다고 가정해 보겠습니다.

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

claude mcp list 

​

Claude Code를 MCP 서버로 사용

Claude Code 자체를 다른 애플리케이션이 연결할 수 있는 MCP 서버로 사용하여 Claude의 도구와 기능을 제공하려고 한다고 가정해 보겠습니다.

# 기본 구문
claude mcp serve

{
  "command": "claude",
  "args": ["mcp", "serve"],
  "env": {}
}

​

MCP 리소스 사용

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

​

MCP 리소스 참조

> @github:issue://123을 분석하고 수정 방법을 제안해 주실 수 있나요?

> @docs:file://api/authentication에서 API 문서를 검토해 주세요

> @postgres:schema://users와 @docs:file://database/user-model을 비교해 주세요

​

MCP 프롬프트를 슬래시 명령으로 사용

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

​

MCP 프롬프트 실행

> /mcp__github__list_prs

> /mcp__github__pr_review 456

> /mcp__jira__create_issue "로그인 플로우의 버그" high