MCP 설정 가이드

Claude Code에서 MCP(Model Context Protocol) 서버를 설정하고 관리하는 가이드.

1. Transport 선택

stdio (로컬 도구)

{
  "mcpServers": {
    "서버명": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@scope/mcp-server-xxx"]
    }
  }
}

http (원격 서버)

{
  "mcpServers": {
    "서버명": {
      "type": "http",
      "url": "https://mcp.example.com/sse"
    }
  }
}

2. Scope 우선순위

MCP 설정은 3개 위치에서 정의 가능. 우선순위:

1. 프로젝트 .mcp.json (최우선) - 프로젝트 루트
2. 유저 ~/.claude/ - 전역 설정
3. 엔터프라이즈 정책 - 조직 관리

같은 이름의 서버가 여러 스코프에 있으면 상위 우선순위가 적용

3. 환경변수 확장

.mcp.json에서 환경변수 참조:

{
  "env": {
    "API_KEY": "${MY_API_KEY}",
    "TIMEOUT": "${TIMEOUT:-30000}",
    "MODE": "${MODE:-production}"
  }
}

환경변수는 .env 또는 시스템 환경변수로 설정. 절대 .mcp.json에 직접 입력 금지

4. 보안

필수 규칙

• API 키, 토큰은 반드시 ${VAR} 환경변수로 참조
• .env 파일은 .gitignore에 등록 (커밋 금지)
• Service Role Key 등 고권한 키는 로컬 개발에서만 사용
• 프로덕션 DB 직접 연결 피하기

.mcp.json 예시 (안전)

{
  "mcpServers": {
    "supabase": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "supabase-mcp"],
      "env": {
        "SUPABASE_URL": "${SUPABASE_URL}",
        "SUPABASE_SERVICE_ROLE_KEY": "${SUPABASE_SERVICE_ROLE_KEY}"
      }
    }
  }
}

.env 예시

SUPABASE_URL=https://xxx.supabase.co
SUPABASE_SERVICE_ROLE_KEY=eyJhbGciOiJIUzI1NiIs...

5. Tool Search

Sonnet 4+ / Opus 4+ 에서 사용 가능. 도구가 100개 이상이거나 지연 로딩이 필요할 때 유용.

# 자동 Tool Search 활성화
ENABLE_TOOL_SEARCH=auto:5

• auto:N: N개 이상 도구 시 자동 활성화
• MCP 서버가 많아 도구 수가 급증할 때 권장

6. 환경변수 튜닝

7. 트러블슈팅

디버깅 명령

# MCP 서버 수동 실행 테스트
npx -y @anthropic-ai/mcp-server-playwright

# 환경변수 확인
echo $TAVILY_API_KEY

# Claude Code에서 MCP 상태 확인
# /kdymcp health

8. 프리셋 사용

프로젝트 타입별 사전 정의된 .mcp.json 프리셋:

# 프리셋 적용
/kdymcp template web-fullstack

관련 문서

• MCP 공식 스펙 섹션 4
• MCP 서버 카탈로그
• MCP 관리 스킬