MCP를 통해 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에 설명된 기능의 사용량을 확인해줘.”
• 데이터베이스 쿼리: “Postgres 데이터베이스를 기반으로 ENG-4521 기능을 사용한 무작위 사용자 10명의 이메일을 찾아줘.”
• 디자인 통합: “Slack에 게시된 새로운 Figma 디자인을 기반으로 표준 이메일 템플릿을 업데이트해줘.”
• 워크플로 자동화: “이 10명의 사용자를 새 기능에 대한 피드백 세션에 초대하는 Gmail 초안을 작성해줘.”

​

인기 있는 MCP 서버

다음은 Claude Code에 연결할 수 있는 일반적으로 사용되는 MCP 서버들입니다:

​

MCP 서버 설치

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

​

옵션 1: 로컬 stdio 서버 추가

Stdio 서버는 머신에서 로컬 프로세스로 실행됩니다. 직접적인 시스템 액세스나 사용자 정의 스크립트가 필요한 도구에 이상적입니다.

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

# 실제 예시: Airtable 서버 추가
claude mcp add airtable --env AIRTABLE_API_KEY=YOUR_KEY \
  -- npx -y airtable-mcp-server

​

옵션 2: 원격 SSE 서버 추가

SSE (Server-Sent Events) 서버는 실시간 스트리밍 연결을 제공합니다. 많은 클라우드 서비스가 실시간 업데이트를 위해 이를 사용합니다.

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

# 실제 예시: Linear에 연결
claude mcp add --transport sse linear https://mcp.linear.app/sse

# 인증 헤더가 있는 예시
claude mcp add --transport sse private-api https://api.company.com/mcp \
  --header "X-API-Key: your-key-here"

​

옵션 3: 원격 HTTP 서버 추가

HTTP 서버는 표준 요청/응답 패턴을 사용합니다. 대부분의 REST API와 웹 서비스가 이 전송 방식을 사용합니다.

# 기본 구문
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 서버를 관리할 수 있습니다:

# 구성된 모든 서버 나열
claude mcp list

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

# 서버 제거
claude mcp remove github

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

# 이렇게 하면 Windows가 실행할 수 있는 command="cmd"가 생성됩니다
claude mcp add my-server -- cmd /c npx -y @some/package

​

MCP 설치 범위

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

​

Local 범위

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

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

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

​

Project 범위

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

# project 범위 서버 추가
claude mcp add shared-server --scope project /path/to/server

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

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

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

​

User 범위

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

# user 서버 추가
claude mcp add my-user-server --scope user /path/to/server

​

올바른 범위 선택

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

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

​

범위 계층 및 우선순위

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

​

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

Claude Code는 .mcp.json 파일에서 환경 변수 확장을 지원하여 팀이 머신별 경로와 API 키와 같은 민감한 값에 대한 유연성을 유지하면서 구성을 공유할 수 있게 합니다.

지원되는 구문:

• ${VAR} - 환경 변수 VAR의 값으로 확장
• ${VAR:-default} - VAR이 설정되어 있으면 VAR로, 그렇지 않으면 default로 확장

확장 위치: 환경 변수는 다음에서 확장될 수 있습니다:

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

변수 확장이 있는 예시:

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

필요한 환경 변수가 설정되지 않고 기본값이 없으면 Claude Code는 구성 파싱에 실패합니다.

​

실용적인 예시

​

예시: Sentry로 오류 모니터링

# 1. Sentry MCP 서버 추가
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 2. /mcp를 사용하여 Sentry 계정으로 인증
> /mcp

# 3. 프로덕션 이슈 디버그
> "지난 24시간 동안 가장 일반적인 오류는 무엇이야?"
> "오류 ID abc123의 스택 트레이스를 보여줘"
> "어떤 배포가 이러한 새로운 오류를 도입했어?"

​

원격 MCP 서버와 인증

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

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

> /mcp

​

JSON 구성에서 MCP 서버 추가

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 mcp add-from-claude-desktop 

claude mcp list 

​

Claude Code를 MCP 서버로 사용

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

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

claude_desktop_config.json에 이 구성을 추가하여 Claude Desktop에서 사용할 수 있습니다:

{
  "mcpServers": {
    "claude-code": {
      "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