MCP 문제 해결 가이드

MCP 문제 해결 가이드 (Troubleshooting Guide)

LiteLLM이 MCP 게이트웨이로 작동할 때 트래픽은 클라이언트 → LiteLLM 프록시 → MCP 서버로 흐르고, OAuth 활성화 설정은 메타데이터 디스커버리에 authorization server를 추가해요. 이 페이지는 증상-수정 런북이에요. 진단 하나를 실행하고 매트릭스의 증상과 일치시킨 다음 행의 수정을 따르세요. 여전히 에스컬레이션이 필요하면 지원 번들이 아무도 나중에 컨텍스트를 재구성하지 않도록 수집하세요.

프로비저닝 단계와 구성 필드에는 mcp.md를, 엔드포인트·전송·인증 패턴 선택에는 MCP Configuration Reference를 참고하세요.

출처: 문서

본문

5분 분류 (Five-Minute Triage)

이 페이지의 모든 명령은 퀵스타트 규칙을 사용해요. http://localhost:4000의 프록시, x-litellm-api-key의 LiteLLM 키, config.yaml의 mcp_servers에서 온 deepwiki 같은 서버 별칭. 자신의 호스트, 키, 별칭으로 바꾸세요.

1단계: 실패한 서버의 이름 있는 엔드포인트에 대해 아래 진단을 실행하세요. HTTP 상태, 응답 헤더, 본문을 유지하며, 이것이 필요한 모든 증거예요. 레이어를 식별하는 부분을 버리므로 grep으로 파이프하지 마세요.

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

2단계: HTTP 상태 줄과 본문을 읽고 매트릭스에서 행을 찾으세요. 상태가 레이어를 말해줍니다. 401/403/404/405/406은 LiteLLM에서 업스트림 호출 전(클라이언트 → LiteLLM) 발생하고, "status": "unreachable"을 보고하는 200 본문 또는 빈 도구 목록은 LiteLLM이 응답했지만 업스트림 홉이 실패했음을 의미해요(LiteLLM → MCP 서버).

3단계: x-mcp-debug-* 응답 헤더(x-litellm-mcp-debug: true로 활성화, 디버그 헤더 참고)와 일치하는 프록시 로그 줄로 레이어를 확인한 다음 행의 수정을 적용하세요.

건강한 대조 응답은 이렇게 생겼어요. 먼저 이걸 얻으세요. 작동 기준선이 있어야 아래 실패가 해석 가능해지니까요:

HTTP/1.1 200 OK
content-type: text/event-stream

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"_meta":{"litellm.ai/server_outcomes":{"deepwiki":{"status":"ok","tool_count":3}}},"tools":[{"name":"deepwiki-ask_question",...}]}}

증상 매트릭스 (Symptom Matrix)

증상	가능한 레이어	진단	예상 증거	수정	함께 에스컬레이션
`401` `Authentication Error, Malformed API Key`	클라이언트 → LiteLLM	키 헤더 없이/있음 진단 curl	`{"detail":"Authentication Error, Malformed API Key passed in. Ensure Key has 'Bearer ' prefix."}`	`x-litellm-api-key: *** <key>` 접두사 포함 전송	전체 상태+본문, 번들
`401` 유효하지 않거나 만료된 키	클라이언트 → LiteLLM	진단 curl; `x-mcp-debug-inbound-auth` 확인	401 본문이 키 이름, 디버그 헤더가 프록시가 본 마스킹 키 표시	유효한 가상 키 또는 마스터 키 사용; 만료 시 재생성	마스킹된 키 ID, 키 생성 시간
`403` 키는 유효하지만 허용되지 않음	LiteLLM 인증/라우팅	이름 있는 엔드포인트에 대한 진단 curl	팀/키 MCP 권한을 인용하는 403 본문	키/팀에 서버 또는 접근 그룹 접근 부여	키/팀 구성 부분
`404` `MCP server, toolset, or access group '<alias>' not found`	LiteLLM 인증/라우팅	`/<alias>/mcp`에 대한 진단 curl	별칭을 이름 짓는 정확한 404 본문	`config.yaml`의 `mcp_servers`와 일치하도록 별칭 수정 또는 서버 추가	`mcp_servers` 구성 부분
`404` `{"detail":"Not Found"}`	클라이언트 → LiteLLM	URL을 `/<alias>/mcp`와 비교	별칭이 없는 일반 FastAPI 404	누락된 `/mcp` 접미사 추가 또는 경로 수정	사용된 정확한 URL
`405` `Method Not Allowed`	클라이언트 → LiteLLM	`curl -sS -D - -X PUT ...` 재현	`allow: GET, POST, DELETE` 헤더 + JSON-RPC 오류 본문	JSON-RPC 호출에 POST 사용. 엔드포인트는 streamable HTTP를 말하며 SSE 전용이나 WebSocket이 아님	메서드+전송 클라이언트 구성
`406` `Not Acceptable`	클라이언트 → LiteLLM	`Accept` 헤더 없는 진단 curl	`Client must accept both application/json and text/event-stream`	`Accept: application/json, text/event-stream` 전송	클라이언트 HTTP 구성
UI OAuth Connect 시 `400`: `{"detail":"invalid_request"}`	LiteLLM 인증/라우팅	OAuth redirect_uri 거부 참고	로그 줄 `MCP OAuth: rejecting redirect_uri ...`	`PROXY_BASE_URL` 설정 또는 `X-Forwarded-*` 신뢰	`.well-known` issuer 출력
OAuth 흐름이 LiteLLM 키를 업스트림으로 보냄	LiteLLM 인증/라우팅	진단 curl, `x-mcp-debug-oauth2-token` 읽기	헤더에 `SAME_AS_LITELLM_KEY`	LiteLLM 키를 `x-litellm-api-key`로 옮겨 `Authorization`이 업스트림 토큰용으로 비도록. Debugging OAuth 참고	디버그 헤더
클라이언트가 등록(DCR) 못하거나 디스커버리 실패	LiteLLM 인증/라우팅	`curl -sS http://localhost:4000/.well-known/oauth-authorization-server`	`authorization_endpoint`·`token_endpoint`가 있는 JSON	클라이언트에서 메타데이터가 도달 가능한지 검증; 지원 그랜트는 OAuth 문서 확인	메타데이터 JSON, 클라이언트 오류 원문
`200`이지만 `"status": "unreachable"`, 빈 도구	LiteLLM → MCP 서버	진단 curl + 별칭에 대한 프록시 로그 grep	로그: `httpx.ConnectError: All connection attempts failed`(네트워크) 또는 `CERTIFICATE_VERIFY_FAILED`(TLS)	업스트림 URL, 네트워크 경로, 방화벽, 서버 인증서 수정	프록시 로그 줄 + MCP 서버 로그
`200`이지만 집계 `/mcp`에서 빈 도구 목록	LiteLLM → MCP 서버	본문의 `litellm.ai/server_outcomes` 읽기	서버별 `status`가 어떤 업스트림 실패·도구 반환 표시	실패 서버 수정. 집계는 전체 목록을 실패시키는 대신 서버별 실패를 흡수	`server_outcomes` 객체
도구 호출 실패: `Tool '<name>' not found`	클라이언트 → LiteLLM	`tools/list`의 정확한 이름으로 `tools/call`	`{"content":[{"type":"text","text":"Error: Tool 'nonexistent_tool' not found"}],"isError":true}`	집계·이름 있는 엔드포인트 둘 다 접두사 이름(`deepwiki-ask_question`) 사용	`tools/list` 출력
`/v1/responses` 또는 `/v1/chat/completions`가 MCP 도구 무시	LiteLLM 인증/라우팅	`server_label`을 구성 별칭과 비교	성공은 `mcp_tools_fetched`·`tool_execution_results` 출력 항목, 잘못된 라벨은 도구 항목 없는 일반 답변	`server_label`을 정확한 별칭으로, `server_url`은 `litellm_proxy`로 설정	(마스킹된) 전체 요청 본문 + 응답
요청 중 타임아웃	LiteLLM → MCP 서버	진단 curl 시간 측정; MCP 서버 로그 확인	curl이 멈췄다가 오류, 프록시 로그가 타임아웃 표시	클라이언트 타임아웃 높이기, 업스트림 지연·네트워크 경로 확인	양쪽 타임스탬프, 토폴로지

엔드포인트와 세션 (Endpoints and Sessions)

LiteLLM은 집계 엔드포인트 하나와 서버당 이름 있는 엔드포인트 하나를 노출해요. POST /mcp는 키가 접근할 수 있는 모든 서버의 도구를 나열하며, 각 도구는 서버 별칭으로 접두사(deepwiki-ask_question)가 붙고 _meta에 서버별 litellm.ai/server_outcomes 보고가 있어요. POST /<alias>/mcp는 호출을 한 서버로 범위를 정하며 분류의 올바른 대상이에요. 집계 응답이 다른 건강한 서버 뒤에 실패 서버 하나를 숨길 수 있으니까요.

엔드포인트는 MCP streamable HTTP를 말해요. 단일 JSON-RPC 호출에도 응답이 text/event-stream 프레임으로 도착하는데, 이 때문에 Accept 헤더가 두 콘텐츠 타입을 모두 허용해야 해요. 일반 tools/list·tools/call 요청은 이전 initialize 핸드셰이크 없이도 작동하므로 curl 분류에 세션 설정이 필요 없어요. initialize를 실행하는 MCP 클라이언트는 세션을 얻어요. 클라이언트가 도구를 나열하기 전에 실패하면 최초 HTTP 교환을 캡처하세요. 전송 불일치(405)와 Accept 헤더 누락(406)이 그 첫 요청에서 발생하니까요.

검증된 실패 모드 (Verified Failure Modes)

아래 모든 응답은 퀵스타트 구성과 deepwiki 서버, 그리고 네트워크·TLS 행을 위한 의도적으로 깨뜨린 서버로 라이브 프록시에 대해 캡처되었어요.

401과 403: 인증

누락 또는 잘못된 키:

HTTP/1.1 401 Unauthorized
{"detail":"Authentication Error, Malformed API Key passed in. Ensure Key has `Bearer ` prefix."}

알 수 없거나 만료된 키도 401을 반환하며, 거부된 키를 이름 짓는 본문과 함께요:

HTTP/1.1 401 Unauthorized
{"detail":"Authentication Error, Invalid proxy server token passed. Received API Key = sk-..., Key Hash (Token) =2ab06c... Unable to find token in cache or `LiteLLM_VerificationTokenTable`"}

403은 키가 인증됐지만 그 서버에 대한 MCP 권한이 없음을 의미해요. 자격 증명이 아니라 키/팀 권한 부여를 수정하세요.

404: 서버 또는 라우트

알 수 없는 별칭, LiteLLM 라우팅이 거부:

HTTP/1.1 404 Not Found
{"detail":"MCP server, toolset, or access group 'nosuchserver' not found"}

잘못된 경로(/mcp 접미사 누락), 요청이 MCP 라우팅에 도달하지 못함:

HTTP/1.1 404 Not Found
{"detail":"Not Found"}

두 본문은 비슷해 보이지만 의미가 달라요. 첫 번째는 구성/별칭 문제, 두 번째는 URL 문제예요.

405와 406: 전송 또는 엔드포인트 불일치

JSON-RPC가 아닌 메서드(예: PUT)는 허용 메서드와 함께 405를 반환:

HTTP/1.1 405 Method Not Allowed
allow: GET, POST, DELETE
{"jsonrpc":"2.0","id":"server-error","error":{"code":-32600,"message":"Method Not Allowed"}}

Accept 헤더를 생략하면 406:

HTTP/1.1 406 Not Acceptable
{"jsonrpc":"2.0","id":"server-error","error":{"code":-32600,"message":"Not Acceptable: Client must accept both application/json and text/event-stream"}}

둘 다 업스트림 서버가 아니라 클라이언트의 전송 구성을 나타내요. 엔드포인트의 GET은 streamable HTTP 이벤트 스트림을 열며(: ping keepalive가 보일 것), 이는 오류가 아니라 예상 동작이에요.

OAuth 디스커버리, DCR, 리다이렉트

클라이언트 흐름을 디버깅하기 전에 프록시가 OAuth 메타데이터를 게시하는지 확인:

curl -sS http://localhost:4000/.well-known/oauth-authorization-server

{"issuer":"http://localhost:4000","authorization_endpoint":"http://localhost:4000/v1/mcp/oauth/authorize","token_endpoint":"http://localhost:4000/v1/mcp/oauth/token","response_types_supported":["code"],"grant_types_supported":["authorization_code"],"code_challenge_methods_supported":["S256"]}

issuer는 사용자가 브라우저에 입력하는 origin과 일치해야 해요. 인그레스 뒤에서 내부 호스트명이 보이면 아래 redirect_uri 섹션을 참고하세요. 토큰 흐름 디버깅에서 x-mcp-debug-oauth2-token의 SAME_AS_LITELLM_KEY는 OAuth 토큰 대신 LiteLLM 키가 업스트림으로 새고 있음을 의미해요(Debugging OAuth 참고).

MCP OAuth: Connect가 `{"detail":"invalid_request"}` 반환

증상. LiteLLM UI에서 MCP OAuth 서버의 Connect 클릭이 반환:

HTTP/1.1 400 Bad Request
{"detail":"invalid_request"}

프록시 로그(verbose 로깅)에 MCP OAuth: rejecting redirect_uri ... as invalid_request. Computed proxy base=... 같은 줄이 보여요.

원인. /v1/mcp/server/oauth/{server_id}/authorize 엔드포인트는 브라우저가 제공한 redirect_uri(https://llm.example.com/ui/mcp/oauth/callback)가 프록시 자신의 공용 origin과 스킴·호스트·포트를 공유하는지 검증해요. TLS 종료 인그레스(Kubernetes, ALB, nginx, Cloudflare 등) 뒤에서는 프록시가 기본적으로 내부 주소(http://<pod-ip>:4000)로 해석되므로 동일 출처 검사가 거부해요.

진단. 프록시가 광고하는 origin과 브라우저가 보는 것을 비교:

curl -sS https://llm.example.com/.well-known/oauth-authorization-server | jq .issuer

issuer 값은 사용자가 브라우저에 입력하는 origin(https://llm.example.com)과 같아야 해요. 내부 호스트명이나 http://...를 반환하면 프록시의 해석된 origin이 틀린 거예요.

수정(선호 순):

PROXY_BASE_URL 설정(권장). 운영자가 대역 외로 프록시의 실제 공용 origin을 선언. 헤더 신뢰가 필요 없음:

PROXY_BASE_URL=https://llm.example.com

전체 origin만: 스킴 + 호스트(+ 비기본 포트), 후행 슬래시·경로 없음. Reverse proxy and ingress configuration 참고.

인그레스의 X-Forwarded-* 신뢰. general_settings에 두 키 모두 설정:

config.yaml:

general_settings:
  use_x_forwarded_for: true
  mcp_trusted_proxy_ranges:
    - "10.0.0.0/8"      # your ingress / load-balancer CIDR(s)

use_x_forwarded_for만으로는 부족해요. mcp_trusted_proxy_ranges가 없으면 프록시가 신뢰할 수 있는 리버스 프록시와 직접 공격자를 구분할 수 없어 X-Forwarded-*를 존중하지 않아요. 인그레스가 X-Forwarded-Proto, X-Forwarded-Host, (비기본 포트에서 실행 시) X-Forwarded-Port를 보내는지 검증하세요.

인그레스 수정. 인그레스가 X-Forwarded-*를 벗기거나 다시 쓰고 있다면 프록시 설정으로는 해결되지 않아요. 인그레스 레이어에서 헤더를 복원하세요.

승인된 OAuth 클라이언트가 별도 도메인(내부 웹 앱 같은)에 있다면 MCP_TRUSTED_REDIRECT_ORIGINS에 콜백 호스트를 추가하세요. Allowing additional first-party redirect_uri origins 참고.

사전 등록된 OAuth 앱은 Redirect URLs for static OAuth clients에서 IdP 콜백 구성, MCP 클라이언트 콜백 요구사항, 검증 오류를 참고하세요.

Dynamic Client Registration 실패 시 클라이언트의 오류 응답과 위에 보인 authorization server 메타데이터를 수집하세요. 메타데이터가 지원 그랜트 타입을 나열해요.

네트워크, TLS, 타임아웃

도달할 수 없는 업스트림은 게이트웨이 502로 드러나지 않아요. 이름 있는 엔드포인트가 빈 도구 목록과 서버별 상태로 200을 반환해요:

HTTP/1.1 200 OK
event: message
data: {"jsonrpc":"2.0","id":1,"result":{"_meta":{"litellm.ai/server_outcomes":{"brokenserver":{"status":"unreachable"}}},"tools":[]}}

프록시 로그가 어떤 실패 클래스였는지 식별해요. 연결 거부 또는 DNS:

09:00:34 - LiteLLM:WARNING: mcp_server_manager.py - Error listing tools from brokenserver: All connection attempts failed
httpx.ConnectError: All connection attempts failed

TLS 실패(만료 또는 신뢰할 수 없는 인증서):

09:01:40 - LiteLLM:WARNING: mcp_server_manager.py - Error listing tools from tlsbroken: [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: certificate has expired (_ssl.c:1000)

타임아웃의 경우 진단 curl의 시간을 측정하고 프록시·MCP 서버 로그 사이의 타임스탬프를 비교해 어느 쪽이 멈췄는지 보세요.

빈 도구 목록과 도구 명명

집계 /mcp 엔드포인트에서 깨진 서버 하나는 요청을 실패시키지 않아요. 건강한 서버는 여전히 도구를 반환하고 litellm.ai/server_outcomes가 각 서버를 별도로 보고해요:

data: {"jsonrpc":"2.0","id":1,"result":{"_meta":{"litellm.ai/server_outcomes":{"deepwiki":{"status":"ok","tool_count":3},"brokenserver":{"status":"unreachable"}}},"tools":[{"name":"deepwiki-ask_question",...}]}}

전체 목록이 비어 있으면 추측하지 말고 server_outcomes에서 서버별 실패 상태를 확인하세요. 도구 이름은 서버 별칭으로 접두사가 붙으므로 ask_question이 아니라 deepwiki-ask_question을 호출하세요. 접두사가 없거나 잘못된 이름을 호출하면 HTTP 레이어가 아니라 도구 결과 안에서 실패해요:

HTTP/1.1 200 OK
data: {"jsonrpc":"2.0","id":3,"result":{"content":[{"type":"text","text":"Error: Tool 'nonexistent_tool' not found"}],"isError":true}}

Responses 및 Chat Completions 실패

/v1/responses 또는 /v1/chat/completions 동안 server_url: "litellm_proxy"가 있는 MCP 도구를 요청이 포함하면 LiteLLM이 요청 중간에 MCP 도구 호출을 실행해요. 작동하는 요청은 출력 항목에서 MCP 홉을 명시적으로 보여줘요:

curl -sS http://localhost:4000/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "gpt-4o-mini",
    "input": "List the top-level wiki pages for BerriAI/litellm",
    "tools": [{"type": "mcp", "server_label": "deepwiki", "server_url": "litellm_proxy", "require_approval": "never"}]
  }'

성공에는 보조 메시지와 함께 mcp_tools_fetched와 tool_execution_results 항목이 포함돼요. server_label이 어떤 구성된 별칭과도 일치하지 않으면 요청은 여전히 200을 반환하지만 그 항목들이 없고 모델이 도구 없이 답해요. 이 조용한 저하가 찾아야 할 증상이에요. /v1/chat/completions에도 동일한 tools 배열로 동일하게 적용돼요. 도구 항목이 있지만 도구 결과에 오류가 포함되어 있으면, 내장 호출이 직접 curl과 같은 MCP 경로를 거치므로 그 오류의 행(알 수 없는 도구 이름, 업스트림 도달 불가)으로 점프하세요.

디버그 헤더 (Debug Headers)

모든 MCP 요청에 x-litellm-mcp-debug: true를 추가하면 마스킹된 진단 응답 헤더를 얻어요:

x-mcp-debug-inbound-auth: x-litellm-api-key=Bearer****1234
x-mcp-debug-oauth2-token: (none)
x-mcp-debug-auth-resolution: no-auth
x-mcp-debug-outbound-url: https://mcp.deepwiki.com/mcp
x-mcp-debug-server-auth-type: (none)

x-mcp-debug-auth-resolution은 LiteLLM이 아웃바운드 인증을 어떻게 해석했는지 알려줘요. oauth2-passthrough, m2m-client-credentials, per-request-header, static-token, no-auth. x-mcp-debug-outbound-url은 프록시가 실제로 호출한 업스트림을 확인해요. 값은 마스킹되므로 지원 번들에 안전하게 포함할 수 있어요.

Claude Code:

claude mcp add --transport http my_server http://localhost:4000/deepwiki/mcp \
  --header "x-litellm-api-key: *** sk-..." \
  --header "x-litellm-mcp-debug: true"

연결성 검증 (Verify Connectivity)

MCP Inspector

클라이언트 → LiteLLM과 클라이언트 → MCP 통신 둘 다 한곳에서 테스트해야 할 때 MCP Inspector를 사용하세요. 실패 홉을 격리하는 것이 간단해져요.

워크스테이션에서 npx @modelcontextprotocol/inspector 실행.
구성·연결:
- Transport Type: 클라이언트가 사용하는 전송(Streamable HTTP for LiteLLM) 선택.
- URL: 테스트 중인 엔드포인트(LiteLLM MCP URL 또는 MCP 서버 URL).
- Custom Headers: 예: x-litellm-api-key: *** <LiteLLM API Key>.
Tools 탭을 열고 List Tools를 클릭해 MCP 별칭이 응답하는지 확인.

`curl` 스모크 테스트

Inspector 설치가 비실용적인 서버에서 curl이 이상적이에요. LiteLLM이 만들 MCP 도구 호출을 재현하며, 테스트 중인 시스템(LiteLLM 또는 MCP 서버)의 도메인을 넣어요.

curl -sS -D - -X POST https://your-target-domain.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

대상이 인증이 필요한 LiteLLM 엔드포인트이면 -H "x-litellm-api-key: *** <LiteLLM API Key>"를 추가하세요. curl과 LiteLLM 사이의 일치 실패는 MCP 서버 또는 네트워크/OAuth 레이어가 원인임을 확인해줘요. LiteLLM 호스트에서 MCP 서버를 직접 테스트하면 네트워크 경로를 규명하거나 배제해요.

LiteLLM UI / Playground

MCP 생성 폼이나 MCP Tool Testing Playground에 표시된 실패는 LiteLLM 프록시가 MCP 서버에 도달할 수 없음을 의미해요. 일반적인 원인은 잘못된 구성(전송, 헤더, 자격 증명), MCP/서버 중단, 네트워크/방화벽 차단, 접근할 수 없는 OAuth 메타데이터예요. Playground에서 클라이언트 실패를 재현하면 문제가 클라이언트가 아니라 LiteLLM → MCP 홉에 있음을 확인해줘요.

로그 검토 (Review Logs)

잘 범위가 잡힌 로그는 LiteLLM이 MCP 서버에 도달했는지 그 다음 무슨 일이 일어났는지 분명하게 해줘요.

액세스 로그 예시(성공 MCP 호출)

INFO:     127.0.0.1:57230 - "POST /deepwiki/mcp HTTP/1.1" 200 OK

오류 로그 예시(실패 MCP 호출)

07:22:00 - LiteLLM:ERROR: client.py:224 - MCP client list_tools failed - Error Type: ExceptionGroup, Error: unhandled errors in a TaskGroup (1 sub-exception), Server: http://localhost:3001/mcp, Transport: MCPTransport.http
  httpcore.ConnectError: All connection attempts failed
ERROR:LiteLLM:MCP client list_tools failed - Error Type: ExceptionGroup, Error: unhandled errors in a TaskGroup (1 sub-exception)...
  httpx.ConnectError: All connection attempts failed

지원 번들 (Support Bundle)

매트릭스로 문제가 해결되지 않으면 아래 전부를 한 번에 수집하세요. 완전한 번들이 지원팀이 구성을 재구성하는 디스커버리 호출을 대체해요.

LiteLLM 버전: curl -sS http://localhost:4000/health/readiness 출력 또는 이미지 태그.
구성 부분: mcp_servers 블록과 MCP·전달을 건드리는 general_settings 키, 시크릿은 제거.
정확한 실패 요청: 키를 마스킹(sk-****1234)한 전체 curl 명령.
진단 curl의 HTTP 상태 줄, 응답 헤더, 본문(-D - 출력, 필터링 없음).
x-litellm-mcp-debug: true 실행의 x-mcp-debug-* 헤더(이미 마스킹됨).
실패 요청을 다루는 LiteLLM 프록시 로그, 가능하면 --detailed_debug로 시작.
같은 시간 창의 MCP 서버 로그.
토폴로지: 클라이언트, LiteLLM, 인그레스/로드 밸런서, MCP 서버가 어디서 실행되는지, TLS가 어디서 종료되는지.
각 캡처 요청의 타임존 포함 타임스탬프, 로그 상관을 위해.

절대 공유하지 마세요. 원시 LiteLLM 가상 키나 마스터 키, mcp_servers auth 구성의 업스트림 API 키·정적 토큰, OAuth 클라이언트 시크릿, 마스킹되지 않은 Authorization 헤더 값, .env 내용. 마스킹된 디버그 헤더는 라이브 자격 증명을 붙여넣지 않아도 되도록 존재해요.

더 알아보기 (Learn more)

MCP 개요 — LiteLLM의 MCP 알아보기
MCP 구성 참조 — 엔드포인트·전송·인증

MCP 문제 해결 가이드