MCP 통합

읽는 시간: 14분 | 난이도: 중급

Model Context Protocol(MCP)을 사용하여 Claude Code를 수백 가지 외부 도구와 데이터 소스에 연결하는 방법을 알아봅니다.

MCP란?

MCP(Model Context Protocol)는 AI와 외부 도구를 통합하기 위한 오픈 표준입니다. Claude Code는 MCP를 통해 GitHub, Sentry, 데이터베이스, 사내 API 등 다양한 서비스에 접근할 수 있습니다.

MCP 서버가 연결되면 Claude Code에 다음과 같이 요청할 수 있습니다:

이슈 트래커 기반 기능 구현: "JIRA 이슈 ENG-4521에 설명된 기능을 추가하고 GitHub에 PR을 생성해줘"
모니터링 데이터 분석: "Sentry에서 최근 24시간 동안 가장 많이 발생한 오류를 확인해줘"
데이터베이스 쿼리: "PostgreSQL 데이터베이스에서 지난 90일간 구매하지 않은 고객을 찾아줘"
디자인 통합: "Slack에 올라온 새 Figma 디자인을 기반으로 이메일 템플릿을 업데이트해줘"
워크플로우 자동화: "이 10명의 사용자에게 피드백 세션 초대 이메일 초안을 Gmail에 작성해줘"

MCP 서버 추가하기

MCP 서버는 세 가지 방식으로 추가할 수 있습니다: HTTP(원격), SSE(원격, 더 이상 사용 권장 안 함), stdio(로컬 프로세스).

방법 1: 원격 HTTP 서버 추가 (권장)

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 서버 추가

SSE(Server-Sent Events) 방식은 더 이상 사용을 권장하지 않습니다. 가능하면 HTTP 서버를 사용하세요.

# 기본 문법
claude mcp add --transport sse <이름> <URL>

# 예제: Asana 연결
claude mcp add --transport sse asana https://mcp.asana.com/sse

# API Key 인증 헤더와 함께
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 [옵션] <이름> -- <명령어> [인수...]

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

중요: 옵션 순서

모든 옵션(--transport, --env, --scope, --header)은 서버 이름 앞에 와야 합니다. --(이중 대시)는 서버 이름과 MCP 서버에 전달될 명령어를 구분합니다.

# 올바른 예
claude mcp add --transport stdio myserver -- npx server
claude mcp add --transport stdio --env KEY=value myserver -- python server.py --port 8080

서버 관리 명령어

# 등록된 서버 목록 확인
claude mcp list

# 특정 서버 세부 정보 확인
claude mcp get github

# 서버 제거
claude mcp remove github

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

설치 범위 (Scope)

MCP 서버는 세 가지 범위(scope)로 설치할 수 있습니다. --scope 플래그로 지정합니다.

local 범위 (기본값)

현재 프로젝트 디렉터리에서만 본인에게만 사용 가능합니다. 설정은 ~/.claude.json에 저장됩니다. 개인 개발 서버, 실험적 설정, 민감한 자격증명을 공유하지 않을 때 적합합니다.

# 기본값(local)으로 추가
claude mcp add --transport http stripe https://mcp.stripe.com

# 명시적으로 local 범위 지정
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

project 범위

프로젝트 루트의 .mcp.json 파일에 저장됩니다. 이 파일은 버전 관리에 커밋하여 팀원 모두가 동일한 MCP 도구를 사용할 수 있게 합니다.

# project 범위로 추가
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

.mcp.json 파일 형식:

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

보안 상의 이유로 .mcp.json에 있는 project 범위 서버를 사용하기 전에 Claude Code가 승인을 요청합니다. 승인 선택을 초기화하려면 claude mcp reset-project-choices를 실행하세요.

user 범위

~/.claude.json에 저장되며, 모든 프로젝트에서 사용 가능하지만 본인에게만 보입니다. 여러 프로젝트에서 자주 사용하는 개인 도구에 적합합니다.

# user 범위로 추가
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

범위 선택 가이드

범위	저장 위치	용도
`local` (기본)	`~/.claude.json`	개인 서버, 민감한 자격증명
`project`	`.mcp.json` (프로젝트 루트)	팀 공유 서버, 버전 관리
`user`	`~/.claude.json`	여러 프로젝트에서 사용하는 개인 도구

우선순위: 같은 이름의 서버가 여러 범위에 존재하면 local > project > user 순으로 우선합니다.

.mcp.json의 환경 변수 확장

.mcp.json 파일에서 환경 변수를 사용하면 팀이 설정을 공유하면서도 각자의 API 키나 경로를 유지할 수 있습니다.

지원 문법:

${VAR} - 환경 변수 VAR 값으로 치환
${VAR:-기본값} - VAR가 설정되어 있으면 해당 값, 없으면 기본값 사용

적용 가능한 필드: command, args, env, url, headers

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

환경 변수가 설정되지 않았고 기본값도 없으면 Claude Code는 설정을 파싱하지 못합니다.

실전 예제

예제 1: Sentry로 에러 모니터링

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

# 2. /mcp 명령어로 Sentry 계정 인증
> /mcp

# 3. 프로덕션 이슈 분석
> "최근 24시간 동안 가장 많이 발생한 오류는?"
> "오류 ID abc123의 스택 트레이스를 보여줘"
> "어떤 배포에서 이 새 오류들이 생겼어?"

예제 2: GitHub으로 코드 리뷰

# 1. GitHub MCP 서버 추가
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# 2. Claude Code 내에서 인증
> /mcp
# GitHub에 대해 "Authenticate" 선택

# 3. GitHub 작업 요청
> "PR #456을 리뷰하고 개선 사항을 제안해줘"
> "방금 발견한 버그에 대한 이슈를 생성해줘"
> "내게 할당된 오픈 PR 목록을 보여줘"

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

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

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

예제 4: 파일 시스템 서버

# 파일 시스템 MCP 서버 추가 (로컬 디렉터리 접근)
claude mcp add --transport stdio filesystem -- \
  npx -y @modelcontextprotocol/server-filesystem /path/to/your/project

OAuth 인증

많은 클라우드 기반 MCP 서버는 OAuth 2.0 인증이 필요합니다.

기본 OAuth 흐름

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

# 2. Claude Code 내에서 /mcp 명령어 실행
> /mcp

# 3. 브라우저에서 로그인 절차 진행

팁:

인증 토큰은 안전하게 저장되고 자동으로 갱신됩니다
/mcp 메뉴에서 "Clear authentication"으로 액세스를 취소할 수 있습니다
브라우저가 자동으로 열리지 않으면 제공된 URL을 복사해 직접 열어보세요
OAuth 인증은 HTTP 서버에서만 작동합니다

사전 구성된 OAuth 자격증명 사용

일부 MCP 서버는 자동 OAuth 설정을 지원하지 않습니다. "Incompatible auth server: does not support dynamic client registration" 오류가 표시되면 서버의 개발자 포털에서 OAuth 앱을 직접 등록해야 합니다.

# 방법 1: claude mcp add 사용
claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

# 방법 2: JSON 설정으로 추가
claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

# 방법 3: 환경 변수로 클라이언트 시크릿 전달 (CI 환경 등)
MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

팁:

클라이언트 시크릿은 macOS의 시스템 키체인 또는 자격증명 파일에 안전하게 저장됩니다 (설정 파일에는 포함되지 않음)
퍼블릭 OAuth 클라이언트처럼 시크릿이 없는 서버라면 --client-id만 사용하세요
이 플래그들은 HTTP와 SSE 전송에만 적용됩니다 (stdio 서버에는 영향 없음)
claude mcp get <이름>으로 OAuth 자격증명이 올바르게 설정되었는지 확인할 수 있습니다

JSON 설정으로 서버 추가

JSON 설정이 있다면 직접 추가할 수 있습니다.

# 기본 문법
claude mcp add-json <이름> '<json>'

# 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"}}'

# OAuth 자격증명이 포함된 HTTP 서버
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

Claude Desktop에서 가져오기

Claude Desktop에서 이미 MCP 서버를 설정했다면 가져올 수 있습니다.

# Claude Desktop 설정에서 서버 가져오기
claude mcp add-from-claude-desktop

실행하면 가져올 서버를 선택하는 대화상자가 나타납니다.

# 가져온 서버 목록 확인
claude mcp list

팁:

macOS와 WSL(Windows Subsystem for Linux)에서만 지원됩니다
--scope user 플래그를 사용하면 user 설정으로 추가됩니다
같은 이름의 서버가 이미 있으면 숫자 접미사가 붙습니다 (예: server_1)

Claude.ai 서버 사용

Claude.ai 계정으로 Claude Code에 로그인했다면, Claude.ai에서 추가한 MCP 서버가 자동으로 Claude Code에서도 사용 가능합니다.

claude.ai/settings/connectors에서 서버를 설정합니다 (Team/Enterprise 플랜은 관리자만 추가 가능)
Claude.ai에서 필요한 인증을 완료합니다
Claude Code에서 /mcp 명령어로 확인합니다. Claude.ai에서 온 서버는 표시기로 구분됩니다.

고급 기능

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

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

경로가 잘못되면 spawn claude ENOENT 오류가 발생합니다.

MCP Tool Search (대규모 도구 관리)

MCP 서버가 많아지면 모든 도구 정의가 컨텍스트 창을 많이 차지합니다. MCP Tool Search는 필요할 때만 도구를 동적으로 로드하여 이 문제를 해결합니다.

작동 방식:

MCP 도구가 컨텍스트 창의 10% 이상을 차지하면 자동으로 활성화됩니다
MCP 도구들이 컨텍스트에 미리 로드되지 않고 지연됩니다
Claude가 검색 도구를 사용해 필요한 MCP 도구를 발견합니다
실제로 필요한 도구만 컨텍스트에 로드됩니다

ENABLE_TOOL_SEARCH 환경 변수로 동작을 제어할 수 있습니다:

값	동작
`auto`	MCP 도구가 컨텍스트의 10% 초과 시 활성화 (기본값)
`auto:N`	사용자 정의 임계값 (예: `auto:5`는 5%)
`true`	항상 활성화
`false`	비활성화, 모든 MCP 도구를 미리 로드

# 커스텀 5% 임계값 사용
ENABLE_TOOL_SEARCH=auto:5 claude

# Tool Search 비활성화
ENABLE_TOOL_SEARCH=false claude

이 기능은 Sonnet 4 이상 또는 Opus 4 이상 모델이 필요합니다. Haiku 모델은 지원하지 않습니다.

MCPSearch 도구만 비활성화하려면:

{
  "permissions": {
    "deny": ["MCPSearch"]
  }
}

MCP Prompts를 명령어로 사용

MCP 서버에서 제공하는 프롬프트를 Claude Code의 명령어로 사용할 수 있습니다.

# 사용 가능한 명령어 확인 (/ 입력)
> /

# 인수 없이 프롬프트 실행
> /mcp__github__list_prs

# 인수와 함께 프롬프트 실행
> /mcp__github__pr_review 456
> /mcp__jira__create_issue "로그인 플로우 버그" high

프롬프트 명령어 형식: /mcp__서버이름__프롬프트이름

MCP Resources 참조

MCP 서버는 @ 멘션으로 참조할 수 있는 리소스를 제공할 수 있습니다.

# 파일 참조처럼 리소스 참조
> "@github:issue://123을 분석하고 수정 방법을 제안해줘"
> "@docs:file://api/authentication의 API 문서를 리뷰해줘"

# 여러 리소스를 한 번에 참조
> "@postgres:schema://users를 @docs:file://database/user-model과 비교해줘"

@ 멘션 자동완성에서 연결된 모든 MCP 서버의 리소스를 볼 수 있습니다.

플러그인 제공 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"]
    }
  }
}

${CLAUDE_PLUGIN_ROOT} 환경 변수를 사용해 플러그인 상대 경로를 지정할 수 있습니다.

출력 제한 설정

MCP 도구가 대용량 출력을 생성할 때 Claude Code가 토큰 사용량을 관리합니다.

기본 경고 임계값: 10,000 토큰 초과 시 경고 표시
기본 최대 허용량: 25,000 토큰

출력 한도를 늘리려면:

# 더 높은 출력 한도 설정
export MAX_MCP_OUTPUT_TOKENS=50000
claude

대용량 데이터셋 쿼리, 상세한 보고서 생성, 대규모 로그 파일 처리 시 유용합니다.

엔터프라이즈 관리

조직에서 MCP 서버를 중앙 집중적으로 관리해야 할 때 두 가지 옵션이 있습니다.

옵션 1: managed-mcp.json으로 완전 제어

managed-mcp.json 파일을 배포하면 해당 파일이 모든 MCP 서버를 독점 제어합니다. 사용자는 이 파일에 정의된 서버 외의 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

이 경로들은 관리자 권한이 필요한 시스템 전체 경로입니다.

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"],
      "env": {
        "COMPANY_API_URL": "https://internal.company.com"
      }
    }
  }
}

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

사용자가 자체 서버를 추가하도록 허용하되, 허용 가능한 서버를 제한합니다. 관리형 설정 파일에 allowedMcpServers와 deniedMcpServers를 사용합니다.

각 항목은 다음 세 가지 방식 중 하나로 서버를 제한합니다:

serverName: 서버 이름으로 매칭
serverCommand: stdio 서버의 정확한 명령어와 인수로 매칭
serverUrl: 와일드카드를 지원하는 URL 패턴으로 매칭

중요: 각 항목에는 serverName, serverCommand, serverUrl 중 정확히 하나만 있어야 합니다.

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverName": "sentry" },
    { "serverCommand": ["npx", "-y", "@modelcontextprotocol/server-filesystem"] },
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" },
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}

동작 규칙:

allowedMcpServers가 undefined (기본): 모든 서버 허용
allowedMcpServers가 빈 배열 []: 모든 서버 차단
deniedMcpServers 목록에 있으면 허용 목록에 있어도 차단됩니다 (차단 목록이 우선)
URL 와일드카드: https://mcp.company.com/*는 해당 도메인의 모든 경로를 허용, https://*.example.com/*는 모든 서브도메인을 허용

트러블슈팅

Windows에서 npx 오류

Windows 네이티브 환경(WSL 아님)에서 npx를 사용하는 로컬 MCP 서버는 cmd /c 래퍼가 필요합니다.

# 올바른 방법: cmd /c 래퍼 사용
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

cmd /c 없이 사용하면 "Connection closed" 오류가 발생합니다. Windows는 npx를 직접 실행할 수 없기 때문입니다.

서버 연결 타임아웃

MCP 서버 시작 타임아웃은 MCP_TIMEOUT 환경 변수로 설정합니다.

# 10초 타임아웃 설정
MCP_TIMEOUT=10000 claude

project 범위 서버 승인 초기화

claude mcp reset-project-choices

서버 상태 확인

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

# 특정 서버 세부 정보 확인
claude mcp get <서버이름>

MCP 서버 보안 주의사항

서드파티 MCP 서버를 사용할 때는 신뢰할 수 있는 출처의 서버인지 확인하세요. 특히 신뢰할 수 없는 콘텐츠를 가져오는 MCP 서버는 프롬프트 인젝션 위험에 노출될 수 있습니다.

요약

MCP는 Claude Code를 수백 가지 외부 도구와 연결하는 강력한 표준입니다.

핵심 개념

세 가지 전송 방식: HTTP (권장), SSE (더 이상 사용 권장 안 함), stdio (로컬 프로세스)
세 가지 범위: local (기본, 개인 전용), project (팀 공유, .mcp.json), user (모든 프로젝트)
OAuth 인증: /mcp 명령어로 클라우드 서버에 안전하게 인증
환경 변수 확장: .mcp.json에서 ${VAR} 또는 ${VAR:-기본값} 문법 사용
MCP Tool Search: 도구가 많을 때 자동으로 필요한 도구만 로드

자주 사용하는 명령어

# 서버 추가
claude mcp add --transport http <이름> <URL>
claude mcp add --transport stdio <이름> -- <명령어>

# 서버 관리
claude mcp list
claude mcp get <이름>
claude mcp remove <이름>

# Claude Code 내부
> /mcp          # 서버 상태 및 인증
> /mcp__<서버>__<프롬프트>   # MCP 프롬프트 실행

다음 단계

훅 자동화 - 훅으로 워크플로우 자동화
플러그인 - 플러그인 개발 및 사용
설정 - Claude Code 상세 설정

이 가이드가 도움이 되셨나요?

MCP 통합에 대한 질문이 있으시면 언제든지 물어보세요!