MCP 구성 참조

MCP 구성 참조 (Configuration Reference)

LiteLLM의 MCP 게이트웨이 연결을 위한 표준 의사결정 참조예요. 어떤 엔드포인트를 쓸지, 어떤 전송을 구성할지, 두 인증 레이어가 어떻게 맞물리는지 다뤄요. 설정 단계와 프로바이더별 요구사항은 연결된 가이드를 사용하세요.

엔드포인트 예시는 http://localhost:4000을 프록시 기본 URL로 사용해요. 자신의 것으로 바꾸세요. LITELLM_API_KEY를 선택한 MCP 서버에 접근 권한이 있는 키로 설정하세요. URL이나 헤더로 서버를 선택하면 기존 접근이 좁혀질 뿐 접근을 부여하지는 않아요. 키·팀 설정은 MCP access grants를 참고하세요.

출처: 문서

본문

프로토콜 버전 (Protocol version)

게이트웨이와 업스트림 MCP 서버는 initialize 중에 프로토콜 버전을 협상해요. LiteLLM v1.101.0(18243cd7)은 MCP SDK 1.28.1을 고정하며 그 릴리스의 게이트웨이 초기화는 2025-11-25을 협상했어요. LiteLLM v1.103.0-rc.1(ccf5e8c9)은 SDK 2.2.0을 고정해요. SDK 고정이나 협상된 버전만으로 모든 선택적 프로토콜 기능을 지원한다고 보장되지는 않습니다. 사용하는 엔드포인트가 반환하는 capabilities를 검사하세요.

지원되는 서버별 spec_version 구성 필드는 없어요. 레거시 위임 인증 디스커버리 프로브는 2025-06-18을 보내며, 그 프로브는 클라이언트·업스트림 SDK 협상과 별개예요.

두 인증 레이어 (Two layers of authentication)

게이트웨이·업스트림 인증은 별도로 구성돼요. 그 자격 증명을 분리하세요.

게이트웨이 인증(클라이언트 → LiteLLM). LiteLLM 가상 키예요. x-litellm-api-key 헤더(x-litellm-api-key: *** <key>)로 보내세요. Authorization: Bearer ***도 작동하지만, MCP 트래픽에서는 Authorization헤더를 OAuth 토큰·업스트림 자격 증명용으로 비워 두려고x-litellm-api-key`를 선호하세요. 별도 업스트림 베어러 토큰을 보낼 때 전용 헤더를 사용하세요.
업스트림 인증(LiteLLM → MCP 서버). auth_type으로 서버별 구성(정적 키, OAuth, SigV4 등), 또는 클라이언트가 x-mcp-{server_alias}-{header_name} 헤더로 요청별 제공. Upstream auth 매트릭스 참고.

LiteLLM 키가 업스트림 MCP 서버에 도착하는 것을 본다면(디버그 헤더가 SAME_AS_LITELLM_KEY 표시), Authorization을 업스트림으로 전달하는 서버에 LiteLLM 키를 Authorization에 넣은 상태예요. 이를 x-litellm-api-key로 옮기세요. Debugging OAuth 참고.

엔드포인트 매트릭스 (Endpoint matrix)

엔드포인트	프로토콜	사용 시점	필수 헤더	서버 범위	예상 응답
`/mcp`	MCP JSON-RPC(streamable HTTP)	직접 MCP 클라이언트(Claude Desktop/Code, Cursor, MCP Inspector, FastMCP)가 키가 접근할 수 있는 모든 서버를 봐야 할 때	`x-litellm-api-key: *** sk-...`; 선택적으로 `x-mcp-servers: <name1>,<group1>`로 집합 좁히기	키/팀이 사용이 허용된 모든 서버, 선택적으로 `x-mcp-servers`로 좁힘	MCP `initialize` / `tools/list` / `tools/call` JSON-RPC 응답; 도구 이름은 서버 별칭으로 접두사 붙음(예: `github_mcp-search_issues`)
`/{server_name}/mcp`	MCP JSON-RPC(streamable HTTP)	직접 MCP 클라이언트가 정확히 한 서버(또는 쉼표 구분 목록 `/{name1,name2}/mcp`)를 봐야 할 때	`x-litellm-api-key: *** sk-...`	이름 있는 서버(들), 툴셋, 접근 그룹만	그 서버로 범위가 정해진 같은 JSON-RPC 응답
`/toolset/{toolset_name}/mcp`	MCP JSON-RPC(streamable HTTP)	직접 MCP 클라이언트가 툴셋의 도구만 정확히 봐야 할 때	`x-litellm-api-key: *** sk-...`	이름 있는 툴셋	툴셋으로 범위가 정해진 같은 JSON-RPC 응답
`tools` 안의 `server_url: "litellm_proxy"`	LLM API(`/v1/responses` 또는 `/v1/chat/completions`)	완성 중에 LLM이 MCP 도구를 발견·실행해야 할 때. `litellm_proxy`는 리터럴 센티널이며 URL이 아님	LLM 요청의 `Authorization: Bearer ***;` x-mcp-...`헤더나 도구의`headers` 객체로 서버별 업스트림 자격 증명	모든 허용 서버, 또는 서버·툴셋용 `litellm_proxy/mcp/<server_alias>` 사용	Responses / Chat Completions 출력; `require_approval: "never"`가 모델 선택 도구 실행 활성화
`GET /v1/mcp/server`	REST	구성된 서버 목록 및 실제 `server_id` / `server_name` 가져오기	`Authorization: Bearer * 또는` x-litellm-api-key: *`	키에 보이는 모든 서버	서버 객체의 JSON 배열
`GET /mcp-rest/tools/list`	REST	LLM·MCP 클라이언트 없이 일반 HTTP로 도구 나열	위와 동일	접근 가능한 모든 서버, 또는 `?server_id=`로 하나	`tools`, `error`, `message`가 있는 JSON 객체; MCP REST API 참고
`POST /mcp-rest/tools/call`	REST	일반 HTTP로 알려진 도구 하나 실행	위와 동일 + `Content-Type: application/json`	필수 `server_id` 본문 필드가 이름을 지정한 서버	JSON 도구 결과; 오류 형태는 MCP REST API 참고

한 문장의 선택 규칙: MCP를 말하는 클라이언트는 /mcp(전체 허용 서버) 또는 /{server_name}/mcp(한 서버)에 연결하고, /v1/responses 또는 /v1/chat/completions 안의 LLM 주도 도구 사용은 리터럴 server_url: "litellm_proxy"를 쓰며, MCP 클라이언트 없이 스크립트 HTTP 호출은 /mcp-rest/*를 씁니다.

LiteLLM의 LLM API로 보내는 요청 안에서 litellm_proxy를 사용하세요. 받아들여지는 집계 형태 litellm_proxy/mcp도 같은 목적이며, 새 예시는 litellm_proxy로 통일하세요. 서버나 툴셋이면 litellm_proxy/mcp/<name>을 쓰세요. 이 선택기들은 네트워크 URL이 아니에요. 호스팅 LLM API를 직접 호출할 때는 도달 가능한 https://<proxy-host>/mcp URL을 제공하세요.

스모크 테스트로 유용한 최소 직접 클라이언트 요청:

curl -s -X POST http://localhost:4000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-litellm-api-key: *** $LITELLM_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

예상: 키가 접근할 수 있는 도달 가능한 서버의 접두사 도구 이름을 담은 tools 배열이 있는 JSON-RPC result. 업스트림이 도구를 반환하지 않으면 result._meta에서 서버별 결과를 검사하세요. 401은 게이트웨이 자격 증명이 틀렸다는 뜻이고, /{server_name}/mcp의 404는 서버 이름, 툴셋, 접근 그룹이 존재하지 않는다는 뜻이에요.

전송 매트릭스 (Transport matrix)

transport는 LiteLLM이 업스트림 MCP 서버에 어떻게 연결하는지 설명해요. 클라이언트는 업스트림 전송과 무관하게 항상 streamable HTTP로 LiteLLM에 도달해요.

transport를 config.yaml에서 생략하면 로더는 http(streamable HTTP)로 기본 설정돼요. 관리 API 생성/업데이트 요청 모델은 sse로 기본 설정돼요. 두 진입점에서 transport를 명시적으로 설정해 다른 기본값에 의존하지 마세요.

config.yaml: 세 전송 나란히:

mcp_servers:
  # Streamable HTTP (default): url required
  deepwiki_mcp:
    url: "https://mcp.deepwiki.com/mcp"
    transport: "http"

  # SSE: url required, transport must be set explicitly
  legacy_mcp:
    url: "https://your-sse-server.example.com/sse"
    transport: "sse"

  # stdio: command required, url unused; LiteLLM launches the process
  everything_mcp:
    transport: "stdio"
    command: "npx"
    args: ["-y", "@modelcontextprotocol/[email protected]"]

전송	필수 필드	사용 시점	예상 동작
`http`(YAML 기본)	`url`	모든 현대 원격 MCP 서버; MCP streamable HTTP 전송	LiteLLM이 `url`에 JSON-RPC를 POST하고 응답 스트리밍
`sse`	`url`, `transport: "sse"`	SSE 엔드포인트만 노출하는 레거시 서버	LiteLLM이 `url`에 SSE 스트림 열기
`stdio`	`transport: "stdio"`, `command`; 선택 `args`, `env`	프록시 호스트에서 하위 프로세스로 실행되는 로컬 MCP 서버	LiteLLM이 `command`를 실행하고 stdin/stdout으로 MCP 대화. 요청별 헤더는 `${X-HEADER-NAME}` 구문으로 `env`에 매핑 가능(header-to-env forwarding 참고)

SSE URL을 실행 중인 레거시 SSE 서버로 바꾸세요. stdio 예시는 프록시 호스트에 Node.js와 npx를 필요로 하고 고정 데모 서버를 실행해요. 연결성 제어입니다. 프로덕션에서는 자신의 서버 명령을 사용하세요.

UI(MCP Servers, Add New MCP Server)에서 같은 세 전송이 Streamable HTTP, SSE, Standard Input/Output(stdio)로 나타나며, stdio 구성은 JSON으로 붙여넣습니다.

업스트림 인증 매트릭스 (Upstream auth matrix)

auth_type은 LiteLLM이 업스트림 MCP 서버에 어떻게 인증하는지 선택해요. 아래 YAML은 업스트림 자격 증명을 구성해요. 클라이언트는 여전히 게이트웨이에 별도로 인증해요. 예시 엔드포인트를 바꾸고, 필수 OAuth 클라이언트를 등록하고, 참조된 각 시크릿을 시작 전에 프록시 환경에 설정하세요.

config.yaml: 업스트림 인증 나란히:

mcp_servers:
  # 1. none: server needs no credentials
  open_server:
    url: "https://mcp.example.com/mcp"
    transport: "http"
    auth_type: "none"

  # 2. Static API key: sent as X-API-Key
  api_key_server:
    url: "https://mcp.example.com/mcp"
    transport: "http"
    auth_type: "api_key"
    auth_value: os.environ/MCP_API_KEY          # -> X-API-Key: ***

  # 3. Static bearer token: sent as Authorization: Bearer ***
  bearer_server:
    url: "https://mcp.example.com/mcp"
    transport: "http"
    auth_type: "bearer_token"
    auth_value: os.environ/MCP_BEARER_TOKEN     # -> Authorization: Bearer ***

  # 4. Interactive OAuth (PKCE): each user signs in via browser
  oauth_interactive_server:
    url: "https://mcp.example.com/mcp"
    transport: "http"
    auth_type: "oauth2"
    oauth2_flow: "authorization_code"
    client_id: os.environ/OAUTH_CLIENT_ID
    client_secret: os.environ/OAUTH_CLIENT_SECRET

  # 5. M2M OAuth (client_credentials): LiteLLM fetches and refreshes the token
  oauth_m2m_server:
    url: "https://mcp.example.com/mcp"
    transport: "http"
    auth_type: "oauth2"
    oauth2_flow: "client_credentials"
    client_id: os.environ/M2M_CLIENT_ID
    client_secret: os.environ/M2M_CLIENT_SECRET
    token_url: "https://auth.example.com/oauth/token"
    scopes: ["tool.read", "tool.write"]

  # 6. OBO / delegated (RFC 8693 token exchange): user's token exchanged per request
  obo_server:
    url: "https://mcp.example.com/mcp"
    transport: "http"
    auth_type: "oauth2_token_exchange"
    token_exchange_endpoint: "https://auth.example.com/oauth/token"
    client_id: os.environ/OBO_CLIENT_ID
    client_secret: os.environ/OBO_CLIENT_SECRET
    audience: "https://mcp.example.com"

`auth_type`	LiteLLM이 업스트림으로 보내는 헤더	자격 증명 소스	사용 시점	설정 가이드
`none`(또는 생략)	`auth_type`에서 생성된 인증 헤더 없음	n/a	공개 또는 네트워크 보호 서버
`api_key`	`X-API-Key: ***`	`auth_value`	서버가 키 헤더 기대
`bearer_token`	`Authorization: Bearer ***`	`auth_value`	서버가 정적 베어러 토큰 기대
`basic`	`Authorization: Basic <base6...)>`	`auth_value`(원시 `username:password`)	서버가 HTTP Basic 사용
`authorization`	`Authorization: ***`(그대로)	`auth_value`	서버가 비표준 스킴 필요
`token`	`Authorization: token ***`	`auth_value`	GitHub 스타일 토큰 스킴
`oauth2` + `oauth2_flow: authorization_code`	`Authorization: Bearer *** token>`	사용자별 대화형 PKCE 로그인	인간 사용자가 개별 동의해야 함	MCP OAuth
`oauth2` + `oauth2_flow: client_credentials`	`Authorization: Bearer *** token>`	LiteLLM이 가져오고·캐시·새로고침	백엔드 서비스, 인간 개입 없음	MCP OAuth M2M
`oauth2_token_exchange`	`Authorization: Bearer *** token>`	RFC 8693 또는 Entra OBO 프로필로 호출자 토큰 교환	On-behalf-of / 위임 접근	MCP OBO Auth
`oauth2_id_jag`	`Authorization: Bearer *** assertion-derived token>`	Okta ID-JAG 두-다리 교환	Okta AI 에이전트 토큰 교환	MCP ID-JAG
`true_passthrough` / `oauth_delegate`	호출자 자신의 토큰, 전달	클라이언트 요청	업스트림이 최종 사용자 토큰을 그대로 봐야 함	MCP OAuth Passthrough
`aws_sigv4`	요청별 SigV4 서명	AWS 자격 증명 또는 boto3 체인	AWS Bedrock AgentCore 서버	MCP AWS SigV4

auth_type: oauth2는 명시적 oauth2_flow가 필요해요. 누락되거나 잘못된 값은 YAML 시작을 막아요. 사용자별 동의에는 authorization_code를, 서비스 신원에는 client_credentials를 쓰세요. 업스트림이 동적 클라이언트 등록을 지원할 때만 대화형 클라이언트 ID/시크릿을 생략하세요(interactive setup and redirects 참고).

다른 헤더의 토큰은 static_headers와 함께 upstream_token_header를 재사용하세요. Microsoft Entra ID는 기존 token_exchange_profile: entra_obo 가이드를 따르세요. 게이트웨이 입장, 업스트림 토큰 교환, 서버 접근 부여는 별도 요구사항이에요.

완전한 정적 자격 증명 입력은 비-OAuth 인증을 참고하세요. 헤더 열은 관리되는 SSE/HTTP 전송 경로를 설명해요. OpenAPI 도구 경로는 auth_type: api_key에 대해 X-API-Key 대신 Authorization: ApiKey ***를 내보내요.

auth_type이 아닌 두 가지 더 업스트림 자격 증명 전송 방법:

정적 헤더(Static headers): 서버 구성의 static_headers: {X-API-Key: *** X-Custom: "..."}가 모든 업스트림 요청에 고정 헤더를 붙여요.
클라이언트 공급 서버별 헤더: 클라이언트가 x-mcp-{server_alias}-{header_name}(예: x-mcp-github_mcp-authorization: Bearer ***)을 보내면 LiteLLM이 {header_name}`을 그 서버에만 전달해요. 이것이 지원되는 클라이언트 측 자격 증명 메커니즘이에요.

더 이상 사용하지 않음: `x-mcp-auth`

전역 x-mcp-auth 헤더(요청의 모든 MCP 서버에 브로드캐스트되는 하나의 자격 증명)는 더 이상 사용하지 않아요. 이를 서버별 형태 x-mcp-{server_alias}-{header_name}로 바꾸세요. 각 자격 증명을 한 서버로 범위를 정하며. x-mcp-auth는 오늘도 작동하지만(그 헤더 이름은 general_settings의 mcp_client_side_auth_header_name 또는 LITELLM_MCP_CLIENT_SIDE_AUTH_HEADER_NAME env var로 바꿀 수 있음), 새 구성에서는 쓰지 말아야 해요.

일반 클라이언트 구성 (Common client configs)

Cursor는 네트워크 URL을 사용하고 자격 증명 헤더를 구성된 github_mcp 별칭과 일치시켜야 해요. 키와 토큰 플레이스홀더를 바꾸세요. Claude Code는 CLI 설정 가이드를 사용하세요.

Cursor mcpServers 항목:

{
  "mcpServers": {
    "github": {
      "url": "http://localhost:4000/github_mcp/mcp",
      "headers": {
        "x-litellm-api-key": "Bearer sk-1234",
        "x-mcp-github_mcp-authorization": "Bearer gho_your_token"
      }
    }
  }
}

LLM 주도 도구 사용(프록시의 Responses API, server_url이 리터럴 문자열 litellm_proxy임을 참고):

MCP 도구가 있는 Responses API:

curl -s http://localhost:4000/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "gpt-5.6-terra",
    "input": "Run available tools",
    "tools": [{
      "type": "mcp",
      "server_label": "litellm",
      "server_url": "litellm_proxy",
      "require_approval": "never",
      "headers": {"x-mcp-github_mcp-authorization": "Bearer gho_your_token"}
    }],
    "tool_choice": "required"
  }'

스크립트 REST 호출은 위 HTTP 예시의 deepwiki_mcp를 재사용할 수 있어요. 먼저 서버와 도구를 발견한 다음 호출하세요. 서버의 이름이나 별칭이 다르다면 반환된 server_id를 사용하세요.

MCP REST API:

curl -sS http://localhost:4000/v1/mcp/server \
  -H "Authorization: Bearer ***"

curl -sS 'http://localhost:4000/mcp-rest/tools/list?server_id=deepwiki_mcp' \
  -H "Authorization: Bearer ***"

curl -sS -X POST http://localhost:4000/mcp-rest/tools/call \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{"server_id":"deepwiki_mcp","name":"read_wiki_structure","arguments":{"repoName":"BerriAI/litellm"}}'

리포지토리의 위키 구조를 담은 도구 결과를 기대해요. server_id를 생략하면 도구 이름이 접두사 붙어 있어도 400 missing_parameter를 반환해요. 인자가 없는 도구에는 {}를 쓰고 null은 전달하지 마세요.

MCP Overview: UI나 config.yaml로 서버 추가, 전체 필드 참조
Using your MCP: Responses API, Cursor, SDK 워크스루
MCP REST API: /mcp-rest/* 요청/응답 상세 및 오류 형태
MCP OAuth, MCP OBO Auth, MCP OAuth Passthrough, MCP AWS SigV4
MCP Troubleshooting: 디버그 헤더와 홉별 격리

더 알아보기 (Learn more)

MCP 개요 — LiteLLM의 MCP 알아보기
MCP 사용 — MCP 사용 워크스루

MCP 구성 참조