MCP 서버 (Model Context Protocol)

공식 문서: https://code.claude.com/docs/ko/mcp

MCP란?

MCP(Model Context Protocol)는 Claude Code를 외부 시스템, 도구, 데이터 소스에 연결하는 오픈소스 표준 프로토콜입니다. USB-C 포트처럼 표준화된 연결 방식을 제공하여, 다양한 서비스를 Claude Code에 통합할 수 있습니다.

MCP 서버를 연결하면 Claude Code에서:

GitHub 이슈를 읽고 PR을 생성
Sentry 에러를 분석하고 수정
PostgreSQL 데이터베이스를 쿼리(Query, 질의)
Slack 메시지를 보내고 받기
Figma 디자인을 참조하여 코드 생성
커스텀 도구를 추가하여 워크플로우 자동화

MCP 연결 구조

🤖

Claude Desktop

AI 에이전트 · Claude Code

⟷

⚡

MCP Protocol

stdio / HTTP / SSE

표준화된 연결 방식

⟷

외부 서비스

🗄️ 데이터베이스
PostgreSQL, Redis

🔌 API 서비스
GitHub, Slack, Jira

📂 파일시스템
로컬·원격 파일

🐙 GitHub
PR, Issue, Code

USB-C처럼 표준화된 방식으로 Claude와 외부 시스템을 연결합니다

핵심 개념

서버와 도구

용어	설명	예시
MCP 서버	특정 서비스에 대한 연결 브릿지	GitHub 서버, PostgreSQL 서버
MCP 도구	서버가 제공하는 개별 기능	`list_issues`, `query`, `send_message`
도구 이름 규칙	`mcp__서버이름__도구이름`	`mcp__github__list_issues`

Claude가 MCP 도구를 사용하는 흐름:

사용자 요청 → Claude가 적절한 도구 선택 → 권한 확인 → MCP 서버 호출 → 결과 반환

전송 방식 (Transport)

MCP 서버는 세 가지 전송 방식을 지원합니다:

방식	설명	적합한 경우
stdio (기본값)	로컬 프로세스로 실행, stdin/stdout 통신	로컬 개발, 커스텀 스크립트
HTTP (권장)	원격 서버에 HTTP Streamable 요청	클라우드 서비스, SaaS API, OAuth 인증
SSE (레거시)	서버가 클라이언트에 이벤트 푸시	기존 SSE 서버 호환 (신규는 HTTP 권장)

SSE는 더 이상 권장되지 않음

SSE(Server-Sent Events) 전송 방식은 레거시로 분류되었습니다. 새로운 MCP 서버를 구축하거나 연결할 때는 HTTP Streamable 전송 방식을 사용하세요. 기존 SSE 서버는 계속 동작하지만, 향후 지원이 축소될 수 있습니다.

설정 방법

방법 1: /mcp 명령어 (대화형)

Claude Code 세션에서 가장 쉽게 MCP 서버를 관리하는 방법입니다:

/mcp

대화형 메뉴에서:

새 MCP 서버 추가
연결된 서버 목록 확인
OAuth 인증 설정
서버 제거
인증 선택 초기화

방법 2: CLI에서 직접 추가

# stdio 서버 추가 (기본)
claude mcp add <이름> -- <command> [args...]

# HTTP 서버 추가 (권장)
claude mcp add --transport http <이름> <url>

# SSE 서버 추가 (레거시)
claude mcp add --transport sse <이름> <url>

실전 예시:

# GitHub MCP 서버 추가
claude mcp add github -- npx -y @modelcontextprotocol/server-github

# HTTP 기반 원격 서버 추가
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 범위 지정 (local: 현재 프로젝트만, user: 모든 프로젝트)
claude mcp add --scope local github -- npx -y @modelcontextprotocol/server-github
claude mcp add --scope user my-tool -- npx -y my-custom-tool

방법 3: 설정 파일 (.mcp.json)

프로젝트 루트에 .mcp.json 파일을 만들어 설정합니다:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

방법 4: Claude Desktop에서 가져오기

Claude Desktop에 이미 MCP 서버를 설정했다면:

claude mcp add-from-claude-desktop

이 명령어를 실행하면 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS 기준)의 MCP 서버 설정을 자동으로 읽어 Claude Code 설정으로 가져옵니다.

설정 파일 형식

로컬 서버 (stdio)

로컬에서 프로세스로 실행되는 서버:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

원격 서버 (HTTP) — 권장

클라우드에서 호스팅되는 서버:

{
  "mcpServers": {
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SENTRY_API_KEY}"
      }
    }
  }
}

동적 인증 헤더 (headersHelper)

정적 환경변수 대신 스크립트로 동적으로 헤더를 생성해야 할 때는 headersHelper를 사용합니다:

{
  "mcpServers": {
    "my-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headersHelper": "./scripts/get-auth-headers.sh"
    }
  }
}

headersHelper에 지정한 스크립트는 JSON 형식의 헤더 객체를 stdout으로 출력해야 합니다:

#!/bin/bash
# get-auth-headers.sh
TOKEN=$(vault read -field=token secret/myapp)
echo "{\"Authorization\": \"Bearer $TOKEN\"}"

headersHelper 사용 시기

OAuth 액세스 토큰처럼 만료 기간이 있거나, Vault/Secrets Manager에서 런타임에 가져와야 하는 동적 인증 정보에 headersHelper를 사용하세요.

도구별 출력 크기 제한 (maxResultSizeChars)

특정 MCP 도구의 출력 크기를 제한할 수 있습니다. 대규모 검색 결과나 로그가 컨텍스트를 낭비하는 것을 방지합니다:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      },
      "toolConfig": {
        "list_issues": {
          "maxResultSizeChars": 5000
        }
      }
    }
  }
}

전역 설정은 MAX_MCP_OUTPUT_TOKENS 환경변수로도 제어할 수 있습니다.

스트리밍 서버 (SSE) — 레거시

기존 SSE 서버와의 호환을 위해 사용합니다:

{
  "mcpServers": {
    "monitoring": {
      "type": "sse",
      "url": "https://api.example.com/mcp/sse",
      "headers": {
        "X-API-Key": "${API_KEY}"
      }
    }
  }
}

OAuth 인증 서버

설정 파일 방식

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://slack.example.com/mcp",
      "oauth": {
        "clientId": "${SLACK_CLIENT_ID}",
        "clientSecret": "${SLACK_CLIENT_SECRET}",
        "authServerMetadataUrl": "https://slack.com/.well-known/openid-configuration",
        "redirectUrl": "http://localhost:8080/callback",
        "scopes": ["channels:read", "chat:write", "users:read"]
      }
    }
  }
}

OAuth 설정에서 지원하는 추가 필드:

필드	설명
`scopes`	요청할 OAuth 권한 범위 목록
`authServerMetadataUrl`	OAuth 인증 서버 메타데이터 URL (기본 발견 URL 재정의 시)

CLI 방식

OAuth 인증이 필요한 서버는 /mcp 명령어 또는 CLI 옵션으로 설정할 수 있습니다:

# OAuth 서버 추가 (브라우저 인증 플로우 자동 시작)
claude mcp add --transport http my-service https://my-service.com/mcp

# 콜백 포트 지정 (기업 방화벽 환경)
claude mcp add --transport http --callback-port 9090 my-service https://my-service.com/mcp

# Client ID/Secret 직접 지정
claude mcp add --transport http \
  --client-id "${CLIENT_ID}" \
  --client-secret "${CLIENT_SECRET}" \
  my-service https://my-service.com/mcp

OAuth 인증 흐름

claude mcp add로 서버 추가 시 OAuth 인증이 필요하면 브라우저가 자동으로 열립니다
서비스에 로그인하고 권한을 승인합니다
토큰이 자동으로 저장되어 이후 재인증 없이 사용합니다
/mcp 메뉴에서 "Reset auth choices"로 인증을 초기화할 수 있습니다

환경변수 확장

.mcp.json에서 ${변수명} 문법으로 환경변수를 참조합니다. API 키 같은 민감한 정보를 파일에 직접 넣지 않아도 됩니다.

기본 문법

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

기본값 지정 문법

환경변수가 설정되지 않았을 때 사용할 기본값을 지정할 수 있습니다:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL:-postgres://localhost:5432/devdb}",
        "MAX_CONNECTIONS": "${MAX_CONNECTIONS:-10}",
        "LOG_LEVEL": "${LOG_LEVEL:-info}"
      }
    }
  }
}

문법	설명	예시
`${VAR}`	환경변수 참조 (없으면 빈 문자열)	`${GITHUB_TOKEN}`
`${VAR:-default}`	환경변수가 없거나 빈 문자열이면 기본값 사용	`${PORT:-3000}`

환경변수 설정:

# ~/.zshrc 또는 ~/.bashrc에 추가
export GITHUB_TOKEN="ghp_xxxxxxxxxxxx"
export DATABASE_URL="postgres://user:pass@localhost:5432/db"

설정 범위

MCP 서버 설정은 여러 범위로 관리됩니다:

범위	파일 위치	용도	버전 관리
조직 (관리)	`managed-mcp.json`	관리자 강제 적용	관리자 배포
로컬	`.claude/settings.json`	현재 프로젝트 전용 (gitignore)	❌
프로젝트	`.mcp.json` (프로젝트 루트)	팀 공유 설정	✅ Git 커밋
사용자	`~/.claude/settings.json`	개인 전역 (모든 프로젝트)	❌

범위 우선순위

조직(Managed) > 로컬(Local) > 프로젝트(Project) > 사용자(User) > 플러그인 > Claude.ai

관리형 MCP 설정 (Managed MCP)

조직 관리자가 MCP 서버를 중앙에서 배포하고 강제 적용할 수 있습니다. managed-mcp.json 파일은 시스템 디렉토리에 위치합니다:

OS	경로
macOS	`/Library/Application Support/ClaudeCode/managed-mcp.json`
Linux	`/etc/claude-code/managed-mcp.json`
Windows	`%PROGRAMDATA%\ClaudeCode\managed-mcp.json`

{
  "mcpServers": {
    "company-tools": {
      "command": "npx",
      "args": ["-y", "@company/mcp-tools"],
      "env": {
        "API_KEY": "${COMPANY_API_KEY}"
      }
    }
  }
}

관리형 MCP의 특징

사용자가 제거하거나 수정할 수 없습니다
프로젝트/개인 설정보다 항상 우선합니다
MDM(Mobile Device Management) 도구로 배포할 수 있습니다
조직 전체에 일관된 도구 환경을 보장합니다

조직 설정 (Enterprise)

관리자가 MCP 서버를 조직 전체에 강제 적용하거나 제한할 수 있습니다:

{
  "allowedMcpServers": ["github", "slack", "postgresql"],
  "deniedMcpServers": ["untrusted-server"]
}

allowedMcpServers: 허용 목록 (이 서버만 사용 가능)
deniedMcpServers: 차단 목록 (이 서버는 사용 불가)
빈 배열 []: 모든 MCP 서버 차단

플러그인 제공 MCP 서버

Claude Code 플러그인은 자체 MCP 서버를 번들로 포함할 수 있습니다. 플러그인 루트에 .mcp.json을 배치하면, 플러그인 활성화 시 해당 MCP 서버가 자동으로 로딩됩니다.

my-plugin/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── my-skill/
│       └── SKILL.md
└── .mcp.json              ← 플러그인 전용 MCP 서버

플러그인의 .mcp.json 예시:

{
  "mcpServers": {
    "plugin-db": {
      "command": "node",
      "args": ["./mcp-server/index.js"],
      "env": {
        "DB_PATH": "${PLUGIN_DB_PATH:-./data/plugin.db}"
      }
    }
  }
}

플러그인 MCP 네임스페이스

플러그인이 제공하는 MCP 서버의 도구는 mcp__pluginname-servername__toolname 형태로 네임스페이스가 구분됩니다. 다른 서버와 이름이 충돌하지 않습니다.

claude.ai 커넥터 (Connectors)

claude.ai에서 설정한 **커넥터(Connector)**도 Claude Code에서 사용할 수 있습니다. 커넥터는 GitHub, Slack, Google Drive 등을 OAuth로 간편하게 연결하는 기능으로, claude.ai 웹에서 설정하면 Claude Code CLI에서도 해당 도구를 사용할 수 있습니다.

항목	MCP 서버	커넥터
설정 방식	`.mcp.json` 또는 CLI	claude.ai 웹 UI
인증	환경변수, OAuth	OAuth (자동)
커스터마이징	완전한 제어	제한적
팀 공유	`.mcp.json` Git 커밋	개인 계정에 연결
사용 가능 환경	Claude Code	claude.ai + Claude Code

# claude.ai에서 커넥터를 설정한 후
# Claude Code에서 바로 사용 가능
> GitHub에서 내 PR 목록을 확인해줘
> Slack #dev 채널의 최근 메시지를 요약해줘

동적 도구 업데이트

MCP 서버는 실행 중에 제공하는 도구 목록을 동적으로 변경할 수 있습니다. 서버가 list_changed 알림을 보내면, Claude Code가 자동으로 도구 목록을 갱신합니다.

이 기능은 다음과 같은 경우에 유용합니다:

서버가 사용자 권한에 따라 도구를 다르게 제공할 때
서버가 런타임에 새로운 기능을 추가할 때
서버 설정이 변경되어 사용 가능한 도구가 달라질 때

푸시 메시지와 채널

MCP 서버는 claude/channel capability를 통해 Claude Code 세션에 푸시 메시지를 보낼 수 있습니다. 이를 통해 외부 이벤트(배포 완료, 에러 발생, CI 결과 등)가 Claude 세션에 실시간으로 전달됩니다.

MCP 서버 (Sentry) → 새 에러 발생 → 푸시 메시지 → Claude 세션에 알림

자세한 내용은 채널 문서를 참고하세요.

서버	패키지	용도
GitHub	`@modelcontextprotocol/server-github`	이슈, PR, 코드 리뷰
GitLab	`@modelcontextprotocol/server-gitlab`	GitLab API 연동
Sentry	`@modelcontextprotocol/server-sentry`	에러 모니터링 분석
Figma	`@modelcontextprotocol/server-figma`	디자인 참조

서버	패키지	용도
PostgreSQL	`@modelcontextprotocol/server-postgres`	PostgreSQL 쿼리
MySQL	`@modelcontextprotocol/server-mysql`	MySQL 쿼리
SQLite	`@modelcontextprotocol/server-sqlite`	SQLite 쿼리

서버	패키지	용도
Slack	`@modelcontextprotocol/server-slack`	Slack 연동

서버	패키지	용도
Filesystem	`@modelcontextprotocol/server-filesystem`	파일시스템 접근
Google Docs	`@modelcontextprotocol/server-google-docs`	구글 문서 접근
AWS	`@modelcontextprotocol/server-aws`	AWS 서비스 연동

권한 관리

MCP 도구는 사용 전 명시적 권한 승인이 필요합니다.

권한 설정

# 대화형으로 권한 관리
/permissions

# 특정 서버의 모든 도구 허용
# allowedTools에 추가: mcp__github__*

# 특정 도구만 허용
# allowedTools에 추가: mcp__postgres__query

와일드카드 패턴

패턴	의미
`mcp__github__*`	GitHub 서버의 모든 도구
`mcp__postgres__query`	PostgreSQL의 query 도구만
`mcp__slack__send_message`	Slack의 send_message만

프로젝트 범위 서버 승인

프로젝트 범위 (.mcp.json)의 MCP 서버를 처음 사용할 때, 보안을 위해 승인 프롬프트가 표시됩니다.

승인을 초기화하려면:

/mcp
# "Reset project choices" 선택

# 또는 CLI에서
claude mcp reset-project-choices

도구 검색 (Tool Search)

Claude Code는 **도구 검색(Tool Search)**으로 컨텍스트 사용을 최적화합니다:

세션 시작 시 도구 이름만 컨텍스트에 로딩 (최소 토큰)
Claude가 필요한 도구의 전체 정의를 온디맨드로 로딩
관련 없는 도구는 컨텍스트에 포함되지 않음

이 방식 덕분에 수십 개의 MCP 서버를 연결해도 컨텍스트 윈도우에 부담이 없습니다.

도구 검색 모드는 환경변수로 제어할 수 있습니다:

# 항상 활성화
export ENABLE_TOOL_SEARCH=1
# 또는
export ENABLE_TOOL_SEARCH=true

# Claude가 자동으로 판단 (기본 동작)
export ENABLE_TOOL_SEARCH=auto

# 도구 수가 N개 이상일 때만 자동 활성화
export ENABLE_TOOL_SEARCH=auto:50   # 50개 이상일 때 활성화

# 비활성화
export ENABLE_TOOL_SEARCH=false
# 또는
export ENABLE_TOOL_SEARCH=0

값	동작
`true` / `1`	항상 도구 검색 활성화
`auto`	Claude가 상황에 따라 자동 판단
`auto:N`	연결된 도구가 N개 이상일 때 자동 활성화
`false` / `0`	도구 검색 비활성화

ENABLE_TOOL_SEARCH

이 환경변수를 설정하면 Claude Code가 도구 목록을 처음부터 모두 로딩하지 않고 필요할 때마다 검색하여 가져옵니다. MCP 서버가 많을수록 효과가 큽니다.

모델 요구사항: 도구 검색(Tool Search)은 Claude Sonnet 이상 모델에서만 동작합니다. Haiku 등 경량 모델에서는 지원되지 않으므로, Tool Search 사용 시 --model sonnet 이상을 지정하세요.

MCP 프롬프트 슬래시 명령어

MCP 서버가 **프롬프트(Prompts)**를 제공하는 경우, 인터랙티브 모드에서 슬래시 명령어로 바로 실행할 수 있습니다:

/mcp__서버이름__프롬프트이름

예시:

# github MCP 서버의 create-pr 프롬프트 실행
> /mcp__github__create-pr

# postgres MCP 서버의 explain-query 프롬프트 실행
> /mcp__postgres__explain-query SELECT * FROM users LIMIT 10

MCP 프롬프트 목록은 /mcp 명령어로 확인할 수 있습니다.

MCP 리소스 참조

MCP 서버가 **리소스(Resources)**를 제공하는 경우, @ 기호를 사용하여 대화 중에 참조할 수 있습니다:

@서버명:protocol://resource/path

예시:

# postgres 서버의 schema 리소스 참조
> @postgres:schema://tables 테이블 구조를 보여줘

# github 서버의 특정 파일 리소스 참조
> @github:file://src/main.ts 이 파일을 분석해줘

레거시 참조 형식

이전에 사용하던 mcp__<서버명>__resource__<리소스명> 형식도 계속 동작합니다. 신규 작성 시에는 @서버명:protocol://path 형식을 권장합니다.

MCP 리소스는 서버가 제공하는 정적 또는 동적 데이터로, 도구(tool)와 달리 부작용 없이 읽을 수 있는 컨텍스트 정보입니다.

MCP 자동 재연결

Claude Code는 MCP 서버 연결이 끊어지면 자동으로 재연결을 시도합니다:

연결 중단 감지 시 자동으로 서버 재시작 시도 (지수 백오프 방식)
최대 5회 재연결 시도 (1초부터 시작해 매회 2배씩 증가하는 지수 백오프)
재연결 성공 시 서버 이름과 함께 성공 메시지 표시
/mcp 명령어로 연결 상태를 수동으로 확인하거나 재연결 트리거 가능
CLAUDE_CODE_MCP_SERVER_NAME / CLAUDE_CODE_MCP_SERVER_URL 은 headersHelper 실행 시 Claude Code가 자동으로 설정하는 변수로, 사용자가 직접 설정하는 변수가 아닙니다

# MCP 서버 상태 및 연결 확인
> /mcp

실전 설정 예시

풀스택 개발 환경

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SENTRY_API_KEY}"
      }
    }
  }
}

이 설정으로 할 수 있는 것들:

> GitHub 이슈 #42를 확인하고 관련 코드를 수정해줘

> 최근 Sentry 에러 중 가장 많이 발생하는 것을 분석하고 수정해줘

> users 테이블에서 지난 7일간 가입한 사용자 수를 확인해줘

실전 예시: Sentry 모니터링 연동

Sentry를 MCP 서버로 연결하여 에러 모니터링을 Claude Code 워크플로우에 통합하는 방법입니다.

1단계: Sentry API 토큰 발급

Sentry 대시보드 → Settings → Auth Tokens에서 토큰을 발급합니다. project:read, event:read 스코프가 필요합니다.

export SENTRY_API_KEY="sntrys_xxxxxxxxxxxx"

2단계: .mcp.json에 추가

{
  "mcpServers": {
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SENTRY_API_KEY}"
      }
    }
  }
}

3단계: 권한 설정

# Claude Code 세션에서
/permissions
# mcp__sentry__* 를 allowedTools에 추가

4단계: 활용

> 최근 24시간 동안 가장 많이 발생한 에러 Top 5를 알려줘

> SENTRY-1234 이슈의 스택트레이스를 분석하고 원인을 찾아줘

> 이번 릴리스(v2.1.0) 이후 새로 발생한 에러를 정리해줘

> 프로덕션에서 500 에러가 급증했어. Sentry 로그를 확인하고 관련 코드를 수정해줘

실전 예시: PostgreSQL 직접 쿼리

데이터베이스를 Claude Code에서 직접 쿼리하여 데이터 기반 개발을 가속화하는 방법입니다.

1단계: 환경변수 설정

# ~/.zshrc에 추가
export DATABASE_URL="postgres://user:password@localhost:5432/myapp_development"

2단계: .mcp.json 설정

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

3단계: 활용

> users 테이블의 스키마를 확인하고, 최근 7일간 가입자 통계를 알려줘

> orders 테이블에서 결제 완료 건수가 갑자기 줄었어.
  최근 3일 vs 이전 3일을 비교해서 분석해줘

> N+1 쿼리 의심이 돼. posts와 comments의 관계를 확인하고
  적절한 인덱스를 제안해줘

> 마이그레이션 파일을 확인하고 누락된 인덱스가 있으면 생성해줘

프로덕션 DB 주의

프로덕션 데이터베이스 연결 시에는 읽기 전용 레플리카를 사용하세요. mcp__postgres__query 도구만 허용하고 쓰기 도구는 차단하는 것이 안전합니다:

# allowedTools에 읽기만 허용
mcp__postgres__query
# deniedTools에 쓰기 차단
mcp__postgres__execute

Windows 환경 설정

Windows (WSL이 아닌 네이티브)에서는 cmd /c 래퍼(Wrapper)가 필요합니다:

{
  "mcpServers": {
    "github": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

보안 모범 사례

사항	설명
신뢰할 수 있는 서버만	Anthropic이 서드파티 MCP 서버를 검증하지 않음
환경변수 사용	API 키를 `.mcp.json`에 직접 넣지 말 것
최소 권한	필요한 도구만 허용 (`mcp__server__*` 대신 개별 도구)
정기 감사	`/mcp`로 연결된 서버를 주기적으로 확인
프로젝트 승인 검토	프로젝트 범위 서버 승인 시 내용을 반드시 확인
기본값 활용	`${VAR:-default}` 문법으로 개발 환경 분리

CLI vs Desktop MCP 비교

항목	Claude Code (CLI)	Claude Desktop
설정 UI	터미널 (`/mcp`) + 파일	그래픽 UI
설정 저장	`.mcp.json` 파일	앱 데이터베이스
버전 관리	✅ Git 커밋 가능	❌
팀 공유	✅ `.mcp.json` 공유	❌
환경변수	`${VAR}` 확장 + 기본값 지원	기본 지원
커넥터	MCP 서버 직접 사용	커넥터 UI + MCP
OAuth	CLI 옵션 + `/mcp`	GUI 자동

커넥터(Connector)와의 차이

Claude Desktop의 커넥터는 GitHub, Slack 등을 OAuth로 쉽게 연결하는 GUI 기능입니다. MCP 서버는 더 저수준의 통합 프로토콜로, CLI에서 직접 사용합니다. 커넥터는 내부적으로 MCP를 사용할 수 있습니다.

Claude Code를 MCP 서버로 실행하기

claude mcp serve 명령어로 Claude Code 자체를 MCP 서버로 실행할 수 있습니다. 이를 통해 다른 Claude 인스턴스나 앱에서 Claude Code 기능을 도구로 사용할 수 있습니다.

# Claude Code를 MCP 서버로 실행 (기본 포트 3000)
claude mcp serve

# 특정 포트 지정
claude mcp serve --port 4000

# 허용할 도구 지정
claude mcp serve --allowed-tools read,write,bash

다른 Claude 설정에서 이 서버를 도구로 사용:

{
  "mcpServers": {
    "claude-code": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

주요 사용 사례:

CI/CD 파이프라인에서 여러 Claude 에이전트 병렬 실행
Claude Desktop에서 Claude Code의 파일 접근 기능 활용
다중 에이전트 워크플로우 구축

커스텀 MCP 서버 만들기

직접 MCP 서버를 만들 수 있습니다. 공식 SDK를 사용하세요:

SDK	언어
MCP Python SDK	Python
MCP TypeScript SDK	TypeScript/JavaScript
FastMCP	Python (경량)

공식 문서: MCP 서버 빌드 가이드

문제 해결

MCP 스코프(범위) 이해하기

MCP 서버를 추가할 때 --scope 옵션으로 적용 범위를 지정합니다:

스코프	명칭	파일 위치	적용 범위
`--scope local`	로컬	`.claude/settings.json`	현재 프로젝트만
`--scope project`	프로젝트	`.mcp.json` (저장소 루트)	팀 공유
`--scope user`	사용자	`~/.claude/settings.json`	모든 프로젝트

# 현재 프로젝트에만 추가 (기본값)
claude mcp add --scope local github -- npx -y @modelcontextprotocol/server-github

# 팀 전체가 공유하는 프로젝트 범위로 추가 (.mcp.json)
claude mcp add --scope project github -- npx -y @modelcontextprotocol/server-github

# 모든 프로젝트에서 사용
claude mcp add --scope user my-tool -- npx -y my-custom-tool

MCP 디버깅

# 연결 상태 및 오류 확인
/mcp

# 환경 진단 (MCP 포함)
/doctor

MCP 로그 파일 위치:

~/.claude/logs/mcp-<서버이름>.log

디버그 모드로 서버 실행:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "env": { "DEBUG": "mcp:*" }
    }
  }
}

MCP 서버가 "Failed" 상태

# 진단 실행
/doctor

# 상세 상태 확인
/mcp

확인 사항:

환경변수가 설정되어 있는지 (echo $GITHUB_TOKEN)
패키지가 설치 가능한지 (npx -y @modelcontextprotocol/server-github)
API 키가 유효한지
네트워크 연결이 되는지 (HTTP/SSE 서버)

도구가 호출되지 않음

권한이 설정되지 않았을 수 있습니다:

/permissions
# mcp__서버이름__* 를 allowedTools에 추가

환경변수가 확장되지 않음

셸에서 변수 확인: echo $GITHUB_TOKEN
올바른 문법 사용: ${VAR_NAME} ($VAR_NAME 아님)
기본값 문법 확인: ${VAR:-default} (하이픈-꺾쇠 사이 공백 없음)
.mcp.json이 유효한 JSON인지 확인 (후행 쉼표 없음)
Claude Code 재시작

MCP 출력이 너무 클 때

export MAX_MCP_OUTPUT_TOKENS=10000

MCP 연결 타임아웃 조정

MCP 서버가 느리거나 네트워크 지연이 큰 환경에서 연결 타임아웃을 늘릴 수 있습니다:

# 타임아웃을 30초로 늘리기 (기본값보다 큰 경우)
export MCP_TIMEOUT=30000

claude.ai MCP 서버 비활성화

claude.ai에서 설정한 커넥터/MCP 서버를 Claude Code에서 사용하지 않으려면:

export ENABLE_CLAUDEAI_MCP_SERVERS=false

이 환경변수를 false로 설정하면 claude.ai 계정에 연결된 MCP 서버가 Claude Code에 로딩되지 않습니다. 개인 커넥터와 로컬 MCP 서버를 분리하여 사용할 때 유용합니다.

OAuth 인증 실패

증상	원인	해결
브라우저가 열리지 않음	헤드리스 환경	`--callback-port`로 포트 지정 후 수동 인증
"Invalid redirect" 에러	콜백 URL 불일치	서비스 설정에서 redirect URI 확인
토큰 만료	OAuth 토큰 갱신 실패	`/mcp` → Reset auth choices → 재인증
CORS 에러	HTTP 서버 설정 문제	서버측 CORS 허용 목록 확인

플러그인 MCP 서버가 로딩되지 않음

플러그인이 활성화되어 있는지 확인
.mcp.json이 플러그인 루트에 있는지 확인
JSON 문법이 올바른지 확인
/mcp에서 플러그인 서버 상태 확인

MCP vs 다른 데이터 연결 방법 비교

외부 데이터나 서비스에 접근하는 방법은 여러 가지입니다. 어떤 방법이 내 상황에 맞는지 비교해보세요.

방법	연결 대상	설정 난이도	유연성	사용 사례
MCP 서버	API/DB/파일시스템	중간	매우 높음	GitHub PR 관리, DB 쿼리, Slack 메시지
Knowledge Files (Chat)	문서 파일	쉬움	낮음	PDF/CSV 분석, 참고 자료 첨부
Computer Use	GUI 앱	낮음	높음	화면 조작이 필요한 앱
직접 복사/붙여넣기	텍스트	매우 쉬움	낮음	일회성 데이터 분석

어떤 방법을 선택할까?

반복적으로 같은 서비스에 접근한다면 → MCP 서버. 한 번 설정해두면 매번 "GitHub PR 목록 보여줘"처럼 자연어로 바로 호출 가능합니다.
한 번만 분석할 파일이라면 → Knowledge Files (Chat에 첨부). 설정 없이 드래그앤드롭으로 바로 사용하세요.
GUI만 있는 앱이라면 → Computer Use. API가 없고 화면을 직접 클릭해야 하는 앱에 사용하세요.

연계 기능

MCP와 함께 사용하면 더욱 강력해지는 기능들

⚙️ 스킬 (Skills)

MCP 도구를 스킬로 패키징하여 /deploy, /review 처럼 한 명령어로 실행할 수 있습니다.

스킬 가이드 →

📡 채널 (Channels)

Slack, Telegram 채널 MCP 서버와 연결하면 채팅 앱에서 Claude에게 직접 명령을 보낼 수 있습니다.

채널 가이드 →

🔧 초기 설정 (Setup)

MCP 서버 인증 정보와 환경변수를 설치 시 함께 구성하면 팀 전체가 동일한 MCP 환경을 사용할 수 있습니다.

설정 가이드 →

장점, 단점과 한계점

장점

외부 도구 무한 확장: 데이터베이스, API, 모니터링, 파일 시스템 등 MCP 서버만 연결하면 Claude Code의 능력을 무한히 확장할 수 있습니다.
표준 프로토콜: MCP는 오픈소스 표준이므로 한 번 만든 서버를 Claude Code, Claude Desktop 등 여러 클라이언트에서 재사용할 수 있습니다.
다양한 전송 방식 지원: stdio(로컬), HTTP Streamable(원격), SSE(레거시) 등 환경에 맞는 전송 방식을 선택할 수 있어 유연합니다.
OAuth 인증 지원: 브라우저 기반 OAuth 플로우를 내장 지원하여 Slack, GitHub 등 서드파티 서비스에 안전하게 인증할 수 있습니다.
팀 공유 가능: .mcp.json 파일을 Git에 커밋하면 팀 전체가 동일한 MCP 서버 설정을 공유할 수 있습니다.

단점과 한계점

서버 설정이 복잡함: .mcp.json 파일을 수동으로 편집해야 하며, JSON 문법 오류, 환경변수 설정 누락 등으로 인한 실패가 잦습니다.
보안 위험: Anthropic이 서드파티 MCP 서버를 검증하지 않으므로, 신뢰할 수 없는 서버를 연결하면 데이터 유출이나 악의적 명령 실행 위험이 있습니다.
디버깅 어려움: MCP 서버가 "Failed" 상태가 되었을 때 원인을 파악하기 어렵고, 환경변수 확장 실패, 네트워크 문제, 패키지 호환성 등 다양한 원인이 있을 수 있습니다.
서버 호환성 문제: MCP 서버마다 지원하는 기능과 API 버전이 다르고, 특히 SSE에서 HTTP Streamable로의 전환 과정에서 호환성 문제가 발생할 수 있습니다.
Windows에서 cmd /c 래퍼 필요: Windows 네이티브 환경에서는 별도의 래퍼 설정이 필요하여 크로스 플랫폼 설정 공유가 번거롭습니다.

활용 팁

MCP 서버 설정 문제는 /doctor 명령어로 진단하고, /mcp 명령어로 상태를 확인하세요. 보안을 위해 mcp__서버__* 대신 개별 도구만 허용하고, API 키는 반드시 환경변수(${VAR})로 관리하세요.

다음 단계

스킬 - 재사용 가능한 워크플로우 만들기
고급 기능 - 후크, 서브에이전트 활용
기능 비교 - 모든 기능 한눈에 비교

도구 검색(Tool Search) 성능

MCP 도구들은 온디맨드로 로딩됩니다. 이는 다음의 장점을 제공합니다:

항목	설명	영향
초기 로딩 시간	첫 번째 도구 사용 시 50-200ms 추가 소요	Claude가 도구 목록을 받아오는 시간
메모리 효율	사용하지 않는 도구는 메모리 낭비 없음	많은 MCP 서버를 연결해도 부담 적음
네트워크 비용	HTTP 서버는 각 도구 호출 시 요청 발생	안정적인 네트워크 필요
캐싱	Claude가 도구 목록을 일시적으로 캐싱	같은 도구 반복 사용 시 빠름

성능 최적화 팁:

자주 사용하는 도구는 stdio 방식 (로컬) 추천
클라우드 서비스는 HTTP 방식 권장
여러 MCP 서버를 연결할 때는 우선순위 고려

전송 방식 선택 기준

stdio (기본값, 권장):

✅ 로컬 개발 환경에서 가장 빠름
✅ 추가 네트워크 지연 없음
✅ 단순한 명령어로 설정 가능
❌ 원격 서버/클라우드 환경에서는 부적합

HTTP Streamable (권장):

✅ 클라우드 서버, SaaS API에 적합
✅ 중앙집중식 관리 가능
✅ OAuth 인증 지원
❌ 네트워크 지연 가능성
❌ 보안 설정 필요

SSE (레거시, 미권장):

✅ 기존 시스템과의 호환성
❌ 새로운 MCP는 HTTP 권장
❌ 향후 지원 축소 예정

OAuth 콜백 URL 네트워크 설정

GitHub, Google 등 OAuth 인증이 필요한 서비스를 MCP로 연결할 때 고려사항:

방화벽 설정:

# Linux/macOS에서 포트 허용 예시
sudo ufw allow 9999/tcp  # Ubuntu

# macOS firewall
sudo defaults write /Library/Preferences/com.apple.alf allowdownloadsignedenabled -int 1

프록시 환경:

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://mcp.github.com/oauth",
      "env": {
        "HTTP_PROXY": "http://proxy.company.com:8080",
        "HTTPS_PROXY": "http://proxy.company.com:8080"
      }
    }
  }
}

로컬 테스트용 콜백 URL:

http://localhost:9999/callback (로컬 개발)
http://127.0.0.1:9999/callback (테스트)
http://[YOUR_COMPUTER_IP]:9999/callback (네트워크 테스트)

관리형 MCP(Managed MCP) MDM 배포

엔터프라이즈 환경에서 MCP 서버를 중앙집중식으로 배포하는 방법:

1. 설정 준비

# 회사 MCP 설정 생성
cat > /opt/company/mcp-config.json << 'MCPCONFIG'
{
  "mcpServers": {
    "company-db": {
      "type": "http",
      "url": "https://mcp.company.internal/database",
      "headers": {
        "Authorization": "Bearer ${COMPANY_MCP_TOKEN}"
      }
    }
  }
}
MCPCONFIG

2. MDM 배포 설정

macOS: Jamf, Intune으로 설정 파일 배포
Windows: GPO, Intune으로 레지스트리 설정
Linux: Ansible, Chef로 자동화

3. 사용자 영향도

Claude Desktop을 재시작하면 자동으로 관리형 MCP 로드
사용자는 추가 설정 불필요
회사 정책에 따라 수정 제한 가능

MCP란?​

핵심 개념​

서버와 도구​

전송 방식 (Transport)​

설정 방법​

방법 1: /mcp 명령어 (대화형)​

방법 2: CLI에서 직접 추가​

방법 3: 설정 파일 (.mcp.json)​

방법 4: Claude Desktop에서 가져오기​

설정 파일 형식​

로컬 서버 (stdio)​

원격 서버 (HTTP) — 권장​

동적 인증 헤더 (headersHelper)​

도구별 출력 크기 제한 (maxResultSizeChars)​

스트리밍 서버 (SSE) — 레거시​

OAuth 인증 서버​

설정 파일 방식​

CLI 방식​

환경변수 확장​

기본 문법​

기본값 지정 문법​

설정 범위​

범위 우선순위​

관리형 MCP 설정 (Managed MCP)​

조직 설정 (Enterprise)​

플러그인 제공 MCP 서버​

claude.ai 커넥터 (Connectors)​

동적 도구 업데이트​

푸시 메시지와 채널​

인기 MCP 서버​

개발 도구​

데이터베이스​

커뮤니케이션​

파일/클라우드​

권한 관리​

권한 설정​

와일드카드 패턴​

프로젝트 범위 서버 승인​

도구 검색 (Tool Search)​

MCP 프롬프트 슬래시 명령어​

MCP 리소스 참조​

MCP 자동 재연결​

실전 설정 예시​

풀스택 개발 환경​

실전 예시: Sentry 모니터링 연동​

실전 예시: PostgreSQL 직접 쿼리​

Windows 환경 설정​

보안 모범 사례​

CLI vs Desktop MCP 비교​

Claude Code를 MCP 서버로 실행하기​

커스텀 MCP 서버 만들기​

문제 해결​

MCP 스코프(범위) 이해하기​

MCP 디버깅​

MCP 서버가 "Failed" 상태​

도구가 호출되지 않음​

환경변수가 확장되지 않음​

MCP 출력이 너무 클 때​

MCP 연결 타임아웃 조정​

claude.ai MCP 서버 비활성화​

OAuth 인증 실패​

플러그인 MCP 서버가 로딩되지 않음​

MCP vs 다른 데이터 연결 방법 비교​

연계 기능​

장점, 단점과 한계점​

장점​

단점과 한계점​

다음 단계​

도구 검색(Tool Search) 성능​

전송 방식 선택 기준​

OAuth 콜백 URL 네트워크 설정​

관리형 MCP(Managed MCP) MDM 배포​