MCP와 함께 Claude Code 사용하기

MCP와 함께 Claude Code 사용하기

LiteLLM Proxy를 통해 MCP 서버를 Claude Code에 연결하는 방법을 알려드릴게요. 엔드포인트, 전송 방식, 자격 증명 선택에 대해서는 MCP 구성 참조(MCP Configuration Reference) 문서를 참고하세요.

출처: 문서

본문

참고: LiteLLM은 MCP 서버에 대한 OAuth도 지원해요. 더 알아보기

데모

MCP 서버 연결하기

LiteLLM Proxy를 통해 MCP 서버를 Claude Code에 연결할 수 있어요.

  • config.yaml에 MCP 서버를 추가해요

  • GitHub MCP

  • Atlassian MCP

이 예시에서는 config.yaml에 Github MCP 서버를 추가해 볼게요.

config.yaml

mcp_servers:  github_mcp:    url: "https://api.githubcopilot.com/mcp"    transport: "http"    auth_type: oauth2    oauth2_flow: authorization_code    client_id: os.environ/GITHUB_OAUTH_CLIENT_ID    client_secret: os.environ/GITHUB_OAUTH_CLIENT_SECRET

이 예시에서는 config.yaml에 Atlassian MCP 서버를 추가해 볼게요.

config.yaml

mcp_servers:  atlassian_mcp:    url: "https://mcp.atlassian.com/v1/mcp"    transport: "http"    auth_type: oauth2    oauth2_flow: authorization_code

important

mcp_servers: 아래의 서버 이름(예: atlassian_mcp, github_mcp)은 Claude Code URL 경로(//mcp)에 사용된 이름과 일치해야 해요. 불일치하면 OAuth 중 404 오류가 발생해요.

  • LiteLLM Proxy 시작하기

Claude Code는 OAuth 콜백을 위해 공개적으로 접근 가능한 URL이 필요하므로, ngrok이나 비슷한 도구로 프록시를 노출해요.

litellm --config /path/to/config.yaml# RUNNING on http://0.0.0.0:4000

# In a separate terminal — expose proxy for OAuth callbacksngrok http 4000

  • MCP 서버를 Claude Code에 추가하기

  • GitHub MCP

  • Atlassian MCP

claude mcp add --transport http litellm-github https://your-ngrok-url.ngrok-free.dev/github_mcp/mcp \  --header "x-litellm-api-key: *** $LITELLM_API_KEY"

claude mcp add --transport http litellm-atlassian https://your-ngrok-url.ngrok-free.dev/atlassian_mcp/mcp \  --header "x-litellm-api-key: *** $LITELLM_API_KEY"

파라미터 설명:

| 파라미터 | 설명 | | --transport http | MCP 연결에 HTTP 전송 방식을 사용 | | litellm-atlassian | Claude Code에서 이 MCP 서버의 이름 — 원하는 대로 지정 가능 | | https://your-ngrok-url.ngrok-free.dev/atlassian_mcp/mcp | LiteLLM 프록시 URL. 형식: //mcp. atlassian_mcp 부분은 LiteLLM 프록시 config의 mcp_servers: 키와 일치해야 함 | | --header "x-litellm-api-key: *** $LITELLM_API_KEY" | 프록시 인증용 LiteLLM 가상 키 |

claude mcp add 대신 ~/.claude.json 파일에 MCP 서버를 직접 추가할 수도 있어요. Claude Code 문서를 참고하세요.

note

OAuth가 필요한 MCP 서버(Atlassian 등)의 경우 LiteLLM 가상 키에는 Authorization 대신 x-litellm-api-key를 사용해요. Authorization 헤더는 OAuth 흐름을 위해 예약되어 있어요.

  • Claude Code로 인증하기

a. Claude Code 시작

claude

b. MCP 메뉴 열기

/mcp

c. MCP 서버 선택하기(예: litellm-atlassian)

d. OAuth 흐름 시작하기

> 1. Authenticate 2. Reconnect 3. Disable

e. 완료되면 다음 성공 메시지를 보게 돼요.

Claude Code는 보통 MCP 도구 스키마를 컨텍스트 창 밖에 유지하고, 내장된 tool search를 통해 필요할 때 로드해요. 그 흐름은 매 요청에 advanced-tool-use-2025-11-20 베타 헤더가 필요하고 tool_reference 블록이 API를 왕복해야 하므로, Claude Code 2.1.70부터 클라이언트는 ANTHROPIC_BASE_URL이 퍼스트파티 Anthropic 호스트가 아닌 다른 것을 가리킬 때마다 tool search를 스스로 꺼요. 그 결정은 어떤 요청도 보내기 전에 클라이언트에서 일어나는데, 그래서 Claude Code가 LiteLLM으로 라우팅되는 순간 /context가 모든 MCP 도구 스키마를 인라인으로 보여주고(수백 개의 도구라면 수만 토큰), 어떤 프록시 쪽 설정으로도 다시 켤 수 없는 이유예요.

LiteLLM은 베타 헤더, defer_loading, tool_reference 블록을 /v1/messages에서 변경 없이 통과시키고(Bedrock과 Vertex AI 이름으로 베타를 번역함) 해결책은 Claude Code 쪽에 있어요. Tool search는 ENABLE_TOOL_SEARCH 환경 변수로 제어돼요. Claude Code의 환경에서 true로 설정해야 해요. 최상위 설정 키가 없으므로 설정 파일의 "enableToolSearch": true는 아무것도 하지 않아요. Claude Code(2.1.72 이상)에게 tool search를 켜두라고 알려줘요:

export ANTHROPIC_BASE_URL=http://0.0.0.0:4000export ANTHROPIC_AUTH_TOKEN=sk-export ENABLE_TOOL_SEARCH=trueclaude

.claude/settings.json의 env 블록에 영구히 두는 것을 권장해요. 프로젝트의 .claude/settings.json 또는 사용자 수준 ~/.claude/settings.json(또는 팀 전체를 커버하는 관리형 설정 파일)에 두면, export를 기억하지 않고도 모든 세션이 그것을 받아요.

{  "env": {    "ENABLE_TOOL_SEARCH": "true"  }}

그러면 /context가 MCP 도구를 0토큰으로 loaded on-demand로 나열하고, Claude는 처음 필요할 때 ToolSearch를 통해 도구 스키마를 로드해요. ENABLE_TOOL_SEARCH=auto(또는 auto:N)는 도구 스키마가 컨텍스트 창의 N%를 넘어설 때만 지연해요. 전체 옵션 목록은 Claude Code 문서를 참고하세요.

더 알아보기 (Learn more)