Claude Code 공식문서 리뷰-Build with Claude Code[7] : Connect Claude Code to tools via MCP

안녕하세요! 갓대희입니다. 

Claude Code Docs 공식 문서 >> Build with Claude Code 섹션의 내용 중 [Connect Claude Code to tools via MCP]를 살펴 보려고 합니다.

https://code.claude.com/docs/en/mcp

Connect Claude Code to tools via MCP - Claude Code Docs

 

이 카테고리의 글은 편하게 공식 문서 위주의 내용을 눈으로 쭉 살펴 보고 넘어가는 목적을 갖고 시작 하게 되었습니다.

저도 초심으로 돌아가 기초적읜 글을 살펴보다보니, 지금와서 클로드에서 강조 하고자 하는 원칙이 어떤건지 되돌아볼 수 있는 계기가 되기도 하는 것 같아, 다른 분들도 꼭 한번 눈으로라도 이해 하고 넘어가는것이 좋다고 생각하여 공식 문서의 내용을 억지로 리뷰해보게 되었습니다. 

 

 

MCP 시작하기

• MCP란: AI와 외부 도구 연결을 위한 오픈소스 프로토콜
• 지원 서버: HTTP (권장), SSE (deprecated), Stdio 방식
• 활용 사례: GitHub, Slack, 데이터베이스, Sentry 등 다양한 서비스 연결
• 설치 범위: 로컬, 프로젝트, 사용자 수준 설정 지원

Claude Code는 Model Context Protocol (MCP)를 통해 외부 도구와 데이터 소스에 연결된다. MCP는 AI-도구 통합을 위한 오픈소스 표준이다.

용어 설명: MCP (Model Context Protocol)
Anthropic이 개발한 AI와 외부 도구 연결을 위한 오픈소스 프로토콜이다. GitHub, Slack, 데이터베이스 등 다양한 서비스를 Claude와 연결할 수 있다. REST API가 웹 서비스를 연결하듯, MCP는 AI를 도구에 연결한다.

⚠️ 보안 주의사항
Anthropic은 모든 제3자 MCP 서버를 검증하지 않았다. 신뢰할 수 없는 콘텐츠를 가져오는 서버는 프롬프트 인젝션 위험이 있으므로 특히 주의해야 한다. MCP 서버를 추가하기 전에 항상 신뢰성을 확인하자.

 

빠른 시작: 첫 번째 MCP 서버 연결

사전 요구사항

• Claude Code CLI가 설치되어 있어야 한다
• stdio 서버 사용 시 Node.js (npx) 필요

 

Step 1: MCP 서버 추가

GitHub MCP 서버를 추가해보자:

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

💡 팁
--transport http는 HTTP 방식으로 원격 서버에 연결한다는 의미다. 대부분의 클라우드 MCP 서버는 HTTP를 사용한다.

 

Step 2: 서버 확인

추가된 서버를 확인한다:

claude mcp list

 

Step 3: 인증하기

Claude Code를 시작하고 /mcp 명령으로 인증한다:

claude
> /mcp
# github 서버에서 "Authenticate" 선택
# 브라우저에서 GitHub 로그인 완료

 - 하기 방법으로 진행하려고 하면 오류가 발생한다.

 - 다음과 같은 방법을 통해 다시 설치하여 인증하도록 하자. 

# 기존 GitHub MCP 제거
claude mcp remove github

# 1. https://github.com/settings/tokens 접속
# 2. "Generate new token 
# 3. 필요한 권한 선택:
#   - repo (전체)
#   - read:org
#   - read:user
# 4. 토큰 생성 후 복사

# 새 GitHub MCP 서버 추가
# YOUR_TOKEN_HERE 부분을 생성한 토큰으로 교체
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_TOKEN_HERE -- npx -y @modelcontextprotocol/server-github

 

Step 4: MCP 도구 사용

이제 Claude에게 GitHub 작업을 요청할 수 있다:

> "나한테 할당된 열린 PR 목록 보여줘"
> "PR #456 리뷰하고 개선 사항 제안해줘"
> "방금 찾은 버그에 대한 새 이슈 만들어줘"

 

MCP로 할 수 있는 것

MCP 서버가 연결되면 다음과 같은 작업이 가능하다:

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

 

MCP 서버 설치 방법

옵션 1: 원격 HTTP 서버 (권장)

# 기본 문법
claude mcp add --transport http <이름> <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"

 

옵션 2: 원격 SSE 서버 (Deprecated)

⚠️ 참고
SSE (Server-Sent Events) 전송은 deprecated되었다. 가능한 경우 HTTP 서버를 대신 사용하자.

# 기본 문법
claude mcp add --transport sse <이름> <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"

 

옵션 3: 로컬 Stdio 서버

Stdio 서버는 로컬 머신에서 프로세스로 실행된다:

# 기본 문법
claude mcp add --transport stdio <이름> -- <명령> [인자...]

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

💡 팁: -- 파라미터 이해하기
--는 Claude CLI 옵션과 MCP 서버 실행 명령을 구분한다:

• -- 앞: Claude 옵션 (--env, --scope 등)
• -- 뒤: 실제 MCP 서버 실행 명령

Windows 사용자 주의
npx를 사용하는 로컬 MCP 서버는 cmd /c 래퍼가 필요하다:

claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

 

MCP 서버 관리

# 설정된 모든 서버 나열
claude mcp list

# 특정 서버 상세 정보 보기
claude mcp get github

# 서버 제거
claude mcp remove github

# 프로젝트 승인 선택 초기화
claude mcp reset-project-choices

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

팁

• --scope 플래그로 저장 위치 지정: local (기본값), project, user
• 환경 변수 설정: --env KEY=value
• 시작 타임아웃 설정: MCP_TIMEOUT=10000 claude (10초)
• MCP 출력 제한 증가: MAX_MCP_OUTPUT_TOKENS=50000
• OAuth 2.0 인증은 /mcp 명령 사용

✗ claude mcp list
Checking MCP server health...

sequential-thinking: npx -y @modelcontextprotocol/server-sequential-thinking - ✓ Connected
linear: https://mcp.linear.app/mcp (HTTP) - ⚠ Needs authentication
linear-server: https://mcp.linear.app/mcp (HTTP) - ✓ Connected

✗ claude mcp get github
github:
  Scope: Local config (private to you in this project)
  Status: ✓ Connected
  Type: stdio
  Command: npx
  Args: -y @modelcontextprotocol/server-github
  Environment:
    GITHUB_PERSONAL_ACCESS_TOKEN=토큰

 

MCP 설치 범위

범위별 비교

범위	저장 위치	사용 범위	공유 여부
local (기본)	~/.claude.json	현재 프로젝트만	본인만
project	프로젝트 루트 .mcp.json	현재 프로젝트	팀 공유 가능
user	~/.claude.json	모든 프로젝트	본인만

 

범위별 사용 예시

# 로컬 범위 (기본값) - 현재 프로젝트에서만 사용
claude mcp add --transport http stripe https://mcp.stripe.com

# 프로젝트 범위 - .mcp.json에 저장, 팀과 공유 가능
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# 사용자 범위 - 모든 프로젝트에서 사용
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

 

우선순위

같은 이름의 서버가 여러 범위에 있을 때:

1. local (최우선)
2. project
3. user (최하위)

 

.mcp.json 파일 형식

프로젝트 범위로 추가하면 .mcp.json 파일이 생성된다:

{
  "mcpServers": {
    "paypal": {
      "type": "http",
      "url": "https://mcp.paypal.com/mcp"
    },
    "local-db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DB_CONNECTION_STRING}"],
      "env": {}
    }
  }
}

 

환경 변수 확장

.mcp.json에서 환경 변수를 사용할 수 있다:

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

문법	설명
${VAR}	환경 변수 값으로 확장
${VAR:-default}	설정되지 않으면 기본값 사용

확장 가능 위치: command, args, env, url, headers

 

더 많은 예제

예제: Sentry로 에러 모니터링

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

# 2. Claude Code에서 /mcp로 Sentry 계정 인증
> /mcp

# 3. 프로덕션 이슈 디버깅
> "지난 24시간 동안 가장 흔한 에러가 뭐야?"
> "에러 ID abc123의 스택 트레이스 보여줘"
> "어떤 배포가 이 새로운 에러를 도입했어?"

 

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

# 1. 연결 문자열로 데이터베이스 서버 추가
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:password@db.company.com:5432/analytics"

# 2. 자연어로 데이터베이스 쿼리
> "이번 달 총 매출이 얼마야?"
> "orders 테이블의 스키마 보여줘"
> "90일 동안 구매하지 않은 고객 찾아줘"

 

예제: JSON으로 MCP 서버 추가

# HTTP 서버 추가
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

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

# 서버 추가 확인
claude mcp get weather-api

 

예제: Claude Desktop에서 서버 가져오기

# Claude Desktop에서 서버 가져오기 (macOS/WSL만 지원)
claude mcp add-from-claude-desktop

# 대화형으로 가져올 서버 선택

# 가져온 서버 확인
claude mcp list

 

MCP 리소스와 프롬프트

MCP 리소스 참조하기

프롬프트에서 @를 입력해 MCP 서버의 리소스를 참조할 수 있다:

# 리소스 참조 형식
@서버:프로토콜://리소스/경로

# 예시
> @github:issue://123 분석하고 수정 방법 제안해줘
> @docs:file://api/authentication에서 API 문서 검토해줘
> @postgres:schema://users와 @docs:file://database/user-model 비교해줘

 

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

MCP 서버는 프롬프트를 슬래시 명령으로 노출할 수 있다. /를 입력해 확인:

# 형식: /mcp__서버이름__프롬프트이름

# 인자 없이 실행
> /mcp__github__list_prs

# 인자와 함께 실행
> /mcp__github__pr_review 456
> /mcp__jira__create_issue "로그인 버그" high

 

Claude Code를 MCP 서버로 사용하기

Claude Code 자체를 다른 MCP 클라이언트의 서버로 사용할 수 있다:

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

 

Claude Desktop에서 사용하기

claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

💡 초보자 팁
claude가 PATH에 없으면 which claude로 전체 경로를 확인하고 사용하자.

 

플러그인 제공 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 출력 제한

항목	값	설명
경고 임계값	10,000 토큰	초과 시 경고 표시
기본 최대값	25,000 토큰	기본 출력 제한
커스텀 설정	MAX_MCP_OUTPUT_TOKENS	환경 변수로 조정

# MCP 도구 출력에 더 높은 제한 설정
export MAX_MCP_OUTPUT_TOKENS=50000
claude

 

엔터프라이즈 MCP 설정

옵션 1: managed-mcp.json으로 독점 제어

사용자가 수정할 수 없는 고정된 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

 

옵션 2: 허용/차단 목록으로 정책 기반 제어

관리 설정 파일의 allowedMcpServers와 deniedMcpServers로 정책 적용:

{
  "allowedMcpServers": [
    // 서버 이름으로 허용
    { "serverName": "github" },
    { "serverName": "sentry" },

    // 정확한 명령으로 허용 (stdio 서버용)
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },

    // URL 패턴으로 허용 (와일드카드 지원)
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" },
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}

⚠️ 중요

• deniedMcpServers가 절대 우선 - 허용 목록에 있어도 차단됨
• allowedMcpServers: [] (빈 배열) = 완전 잠금
• allowedMcpServers: undefined = 제한 없음

 

MCP 서버 찾기

리소스	설명
MCP 서버 목록	공식 및 커뮤니티 MCP 서버 모음
MCP SDK	직접 MCP 서버 구축하기
MCP 공식 사이트	프로토콜 문서 및 가이드

더 알아보기

• Claude Code MCP 공식 문서
• Model Context Protocol 공식 사이트
• MCP 서버 GitHub 저장소