MCP OAuth

LiteLLM 支援 MCP 伺服器的幾種 OAuth 2.0 模式。每個 auth_type: oauth2 伺服器在 config.yaml 中都必須透過 oauth2_flow 宣告其流程；轉送模式本身是各自的 auth_type 值，詳見 MCP OAuth 轉送：

流程	`oauth2_flow`	使用情境	運作方式
互動式（PKCE）	`authorization_code`	面向使用者的應用程式（Claude Code、Cursor）	以瀏覽器為基礎的同意流程、每位使用者各自的權杖
機器對機器（M2M）	`client_credentials`	後端服務、CI/CD、自動化代理程式	`client_credentials` 授權，代理管理的權杖
代為（OBO）	n/a（使用 `auth_type: oauth2_token_exchange`）	具使用者脈絡的工具呼叫，呼叫受保護的 MCP 伺服器	LiteLLM 將呼叫者權杖交換為具範圍限定的 MCP 權杖。請參閱 MCP OBO 驗證。
轉送（透明）	n/a（使用 `auth_type: true_passthrough`）	用戶端已持有上游權杖；LiteLLM 不另外加入任何驗證	原樣轉送用戶端的 `Authorization`，不經 LiteLLM 准入。請參閱 MCP OAuth 轉送
委派的上游 OAuth	n/a（使用 `auth_type: oauth_delegate`）	LiteLLM 准入呼叫者；上游負責工具授權	LiteLLM 准入加上另一個轉送的上游 bearer，同時保留費用與速率限制。請參閱 MCP OAuth 轉送

互動式流程中的每位使用者權杖都會儲存在呼叫該金鑰的 user_id 底下。關於這與服務帳戶金鑰如何互動，以及非 OAuth 的每位使用者選項（每次請求標頭、BYOK 金鑰、每位使用者環境變數），請參閱每位使用者與每把金鑰的上游憑證。

互動式 OAuth（PKCE）

對於面向使用者的 MCP 用戶端（Claude Code、Cursor），LiteLLM 支援完整的帶有 PKCE 的 OAuth 2.0 授權碼流程。

設定

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

請參閱 Claude Code 教學

運作方式

參與者

Client -- 啟動 OAuth 探索、授權與工具呼叫、代表使用者操作的具備 MCP 功能的 AI 代理程式（例如 Claude Code、Cursor，或其他 IDE/代理程式）。
LiteLLM Proxy -- 在保護已儲存憑證的同時，處理所有 OAuth 探索、註冊、token 交換與 MCP 流量。
Authorization Server -- 透過動態用戶端註冊、PKCE 授權與 token 端點發出 OAuth 2.0 token。
MCP Server (Resource Server) -- 接收 LiteLLM 已驗證 JSON-RPC 請求的受保護 MCP 端點。
User-Agent (Browser) -- 暫時參與其中，讓最終使用者可在授權步驟中授予同意。

流程步驟

資源探索：用戶端會從 LiteLLM 的 .well-known/oauth-protected-resource 端點擷取 MCP 資源中繼資料，以了解範圍與功能。
授權伺服器探索：用戶端透過 LiteLLM 的 .well-known/oauth-authorization-server 端點取得 OAuth 伺服器中繼資料（token 端點、authorization 端點、支援的 PKCE 方法）。
動態用戶端註冊：用戶端透過 LiteLLM 註冊，而 LiteLLM 會將請求轉送至授權伺服器（RFC 7591）。如果提供者不支援動態註冊，您可以在 LiteLLM 中預先儲存 client_id/client_secret（例如 GitHub MCP），流程會以相同方式進行。
使用者授權：用戶端啟動瀏覽器工作階段（含 code challenge 與 resource hints）。使用者核准存取後，授權伺服器會透過 LiteLLM 將 code 傳回給用戶端。
Token 交換：用戶端以 authorization code、code verifier 與 resource 呼叫 LiteLLM。LiteLLM 會與授權伺服器交換這些資訊，並傳回已核發的 access/refresh tokens。
MCP 呼叫：有了有效 token 後，用戶端會將 MCP JSON-RPC 請求（以及 LiteLLM API key）送至 LiteLLM，LiteLLM 再將其轉送至 MCP server，並轉遞工具回應。

如需其他參考，請參閱官方 MCP Authorization Flow。

靜態 OAuth 用戶端的重新導向 URL

當上游身分識別提供者（IdP）要求應用程式事先註冊時，請使用靜態 OAuth 用戶端。在 LiteLLM MCP 伺服器項目中設定應用程式的 client_id 與 client_secret。這支援不提供動態用戶端註冊（RFC 7591）的提供者。

授權流程使用兩個回呼 URL：

回呼	用途	設定
LiteLLM 回呼	接收來自上游 IdP 的授權回應。	在 IdP 應用程式的 Redirect URI 或 Callback URL 欄位中註冊 `<proxy origin>/callback`。
MCP 用戶端回呼	將來自 LiteLLM 的授權回應返回給 MCP 用戶端。	用戶端會將此 URL 作為 `redirect_uri` 提供給 `/{mcp_server_name}/authorize`。當下方驗證規則需要時，請在 LiteLLM 中設定額外受信任的回呼。

範例來說，位於 https://llm.example.com 的代理程式會使用 https://llm.example.com/callback 作為其 IdP 回呼。桌面用戶端的本機回呼，例如 http://localhost:33418/callback，是提供給 LiteLLM 的，不需要在上游 IdP 中註冊。

設定上游 OAuth 應用程式

將 PROXY_BASE_URL 設為代理程式的公開 origin，並向 IdP 註冊對應的 /callback URL：

export PROXY_BASE_URL=https://llm.example.com
# IdP callback URL: https://llm.example.com/callback

LiteLLM 會依序從 PROXY_BASE_URL、受信任的 X-Forwarded-* 標頭，或傳入的請求 URL 解析其公開 origin。關於標頭信任需求，請參閱反向代理與 ingress 設定。

將應用程式的憑證與 OAuth 端點加入 MCP 伺服器設定：

config.yaml
mcp_servers:
  jira_mcp:
    url: https://mcp.example.com/mcp
    auth_type: oauth2
    oauth2_flow: authorization_code
    client_id: os.environ/JIRA_OAUTH_CLIENT_ID
    client_secret: os.environ/JIRA_OAUTH_CLIENT_SECRET
    authorization_url: https://idp.example.com/oauth2/authorize
    token_url: https://idp.example.com/oauth2/token
    scopes:
      - read:jira-work

請以您的提供者對應值取代範例伺服器 URL、OAuth 端點與範圍。當上游 MCP 伺服器發布 LiteLLM 可探索的 OAuth 中繼資料時，authorization_url 與 token_url 為選用。明確設定的端點會優先於衝突的已探索端點。

當上游伺服器完全未發布任何 OAuth 中繼資料時（例如 ms-365-mcp-server 後方的 Microsoft Graph），請加入 per_server_oauth_discovery: true，讓 LiteLLM 自行發布 /{mcp_server_name}/mcp 的探索文件，並以自己的 /{mcp_server_name}/authorize 與 /{mcp_server_name}/token 端點作為上方提供者 URL 的前端。此設定僅在 auth_type: oauth2、oauth2_flow: authorization_code 且沒有 delegate_auth_to_upstream 時才接受。

對於靜態用戶端，LiteLLM 會在本機處理 POST /{mcp_server_name}/register。它會將 MCP 伺服器名稱回傳為 client_id、dummy 回傳為 client_secret，以及用戶端提交的 redirect_uris。LiteLLM 會使用已設定的上游憑證進行授權與權杖交換。

識別 MCP 用戶端的回呼 URL

從用戶端的 redirect_uris 欄位（位於 POST /{mcp_server_name}/register）或其在 redirect_uri 中的 GET /{mcp_server_name}/authorize 參數取得回呼 URL。回呼路徑與連接埠可能因用戶端版本與部署而異。

若發生 origin 不符，HTTP 400 回應會在 detail.redirect_uri 中包含提交的 URL。代理程式也會在警告層級將被拒絕的值記錄為 MCP OAuth: rejecting redirect_uri '<value>'。

以下範例總結常見的回呼設定：

用戶端或回呼類型	回呼範例	LiteLLM 設定
Cursor	`cursor://anysphere.cursor-mcp/oauth/callback`	已包含在內建的受信任回呼中。
使用 loopback listener 的桌面或命令列用戶端	`http://localhost:33418/callback`	loopback 回呼可接受任何連接埠。
網頁版 VS Code	`https://vscode.dev/redirect` 或 `https://insiders.vscode.dev/redirect`	將 `vscode.dev,insiders.vscode.dev` 加入 `MCP_TRUSTED_REDIRECT_ORIGINS`。
位於不同 origin 的 Web 應用程式	`https://app.example.com/oauth/callback`	將 `app.example.com` 加入 `MCP_TRUSTED_REDIRECT_ORIGINS`。
使用自訂 URI scheme 的原生用戶端	`myclient://auth/callback`	將回呼 URI 加入 `MCP_TRUSTED_NATIVE_REDIRECT_URIS`。
LiteLLM Admin UI	`<proxy origin>/ui/mcp/oauth/callback`	當代理程式解析後的公開 origin 與 UI origin 相符時可接受。

對於需要額外受信任回呼的用戶端，請在代理程式部署中設定適用的環境變數：

# Trusted HTTPS client hosts, with optional ports or wildcard subdomains.
export MCP_TRUSTED_REDIRECT_ORIGINS='app.example.com,*.tools.example.com'

# Trusted native client callback URIs.
export MCP_TRUSTED_NATIVE_REDIRECT_URIS='myclient://auth/callback'

MCP_TRUSTED_REDIRECT_ORIGINS 接受以逗號分隔的主機或 host:port 項目清單。MCP_TRUSTED_NATIVE_REDIRECT_URIS 接受以逗號分隔的原生回呼 URI 清單。請包含回呼路徑；myclient://auth/callback 與 myclient://auth/callback/ 是不同的項目。

重新導向 URI 驗證

針對每個伺服器的靜態 OAuth，/{mcp_server_name}/authorize 會依這些規則驗證回呼：

回呼類型	要求
受信任的原生回呼	與內建的 Cursor 回呼或 `MCP_TRUSTED_NATIVE_REDIRECT_URIS` 中的項目相符。
Loopback	使用 HTTP 或 HTTPS，且主機為 `localhost`、`127.0.0.0/8` 中的位址，或 `::1`。任何連接埠與路徑都可接受。
相同 origin	使用與代理程式解析後公開 origin 相同的通訊協定、主機與連接埠。預設連接埠會被標準化。
額外受信任 origin	使用 HTTPS，且主機或 `host:port` 列在 `MCP_TRUSTED_REDIRECT_ORIGINS` 中。像 `*.tools.example.com` 這類萬用字元會比對子網域，包括 `a.tools.example.com`，但不包含 `tools.example.com` 本身。

回呼 URL 必須包含主機，且不得包含片段（#...）、內嵌憑證（user:pass@host），或主機中的反斜線。自訂 URI scheme 需要受信任的原生回呼項目。原生回呼 URI 不得包含查詢字串。HTTP 與 HTTPS 回呼可以包含查詢字串，LiteLLM 在重新導向至用戶端時會予以保留。

疑難排解回呼錯誤

當 LiteLLM 拒絕每個伺服器的回呼時，會回傳 HTTP 400，並將 detail.error 設為 invalid_request。detail.error_description 會指出驗證失敗原因。部分回應也會包含 detail.hint 與設定指引；origin 不符的回應則會包含 detail.redirect_uri。

錯誤或症狀	解決方式
上游 IdP 回報重新導向 URI 不符。	請確認 IdP 應用程式註冊的回呼為 `<proxy origin>/callback`，且 LiteLLM 解析出的公開原始來源符合預期。
LiteLLM 拒絕來自代理伺服器公開原始來源的回呼。	設定 `PROXY_BASE_URL` 或設定受信任的轉送標頭。請參閱反向代理與入口配置。
LiteLLM 拒絕來自不同原始來源的 HTTPS 回呼。	將已核准的用戶端主機（如適用，請包含其連接埠）加入 `MCP_TRUSTED_REDIRECT_ORIGINS`。
LiteLLM 拒絕自訂 URI scheme。	將用戶端的回呼 URI 加入 `MCP_TRUSTED_NATIVE_REDIRECT_URIS`。
LiteLLM 回報回呼包含 URL 片段。	設定用戶端使用不含片段的回呼 URL。

例如，原始來源不符的回應會包含以下欄位：

Origin mismatch response (selected fields)
{
  "detail": {
    "error": "invalid_request",
    "error_description": "redirect_uri origin (https://app.example.com) does not match the proxy origin. host/port: redirect_uri 'app.example.com' does not match the proxy origin",
    "redirect_uri": "https://app.example.com/oauth/callback"
  }
}

閘道動態用戶端註冊

彙總的 /mcp 端點透過 POST /register、GET /authorize 和 POST /token 使用閘道層級註冊。每次註冊接受一到四個 redirect_uris，每個 URI 最多 256 個字元。

對於此流程，提供給 /authorize 的 redirect_uri 必須與已註冊值完全相符。未註冊的值會回傳 HTTP 400，並附帶以下最上層 JSON 欄位：

{
  "error": "invalid_request",
  "error_description": "redirect_uri is not registered for this client"
}

每台伺服器的靜態註冊會回傳預留憑證，且不會儲存特定於用戶端的回呼允許清單。其授權端點會套用上方所述的每台伺服器驗證規則。

驗證配置

使用以下請求來驗證探索、靜態註冊與授權重新導向。範例使用一個在 http://localhost:4000 上監聽、搭配 PROXY_BASE_URL=https://llm.example.com，以及上述 jira_mcp 配置的代理。

擷取授權伺服器中繼資料：

curl -sS http://localhost:4000/.well-known/oauth-authorization-server/jira_mcp | jq .issuer
# "https://llm.example.com/jira_mcp"

發行者的原始來源是 https://llm.example.com，因此 IdP 回呼 URL 為 https://llm.example.com/callback。

驗證靜態註冊回應：

curl -sS -X POST http://localhost:4000/jira_mcp/register \
  -H 'Content-Type: application/json' \
  -d '{"client_name":"my-mcp-client","redirect_uris":["http://localhost:33418/callback"]}'
# {"client_id":"jira_mcp","client_secret":"dummy","redirect_uris":["http://localhost:33418/callback"]}

使用迴圈回呼請求授權：

curl -sS -o /dev/null -D - --get http://localhost:4000/jira_mcp/authorize \
  --data-urlencode 'response_type=code' \
  --data-urlencode 'client_id=jira_mcp' \
  --data-urlencode 'redirect_uri=http://localhost:33418/callback' \
  --data-urlencode 'state=example-state' \
  --data-urlencode 'code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM' \
  --data-urlencode 'code_challenge_method=S256'

預期回應為 HTTP 307 Temporary Redirect。其 Location 標頭指向上游授權端點，並包含已設定的上游 client_id 以及 URL 編碼後的 redirect_uri=https://llm.example.com/callback。

若要驗證額外受信任的原始來源，請使用 redirect_uri=https://app.example.com/oauth/callback 重複授權請求。若沒有相符的 MCP_TRUSTED_REDIRECT_ORIGINS 項目，預期回應為 HTTP 400。設定 MCP_TRUSTED_REDIRECT_ORIGINS=app.example.com，重新啟動代理，然後重複該請求；預期回應為 HTTP 307。

反向代理與 ingress 設定

如果 LiteLLM 執行於 TLS 終止型 ingress（Kubernetes、ALB、nginx、Cloudflare 等）之後，proxy 需要知道其公開 origin，才能讓 OAuth authorize 端點比較瀏覽器提供的 redirect_uri（例如 https://llm.example.com/ui/mcp/oauth/callback）與其自身的 scheme + host + port。如果 proxy 解析到其內部位址（http://<pod-ip>:4000），相同來源檢查就會失敗，而 MCP server 頁面上的 Connect 按鈕會回傳 400 Bad Request 與 {"detail":"invalid_request"}。

最簡單且建議的修正方式，是將 PROXY_BASE_URL 設為使用者在網址列中看到的精確 origin：

PROXY_BASE_URL=https://llm.example.com

此值規則：

只能是完整 origin：scheme + host（+ 若非預設則含 port）。
不可有結尾斜線，也不可包含 path 元件。
必須與網址列完全一致。https://llm.example.com 與 https://llm.example.com:443 會被視為相同的 origin（預設 port 會被正規化移除），但 https://llm.example.com 不會與執行於 https://llm.example.com:8443 的瀏覽器相符。

當設定了 PROXY_BASE_URL 時，LiteLLM 會直接使用它，並略過下方所述的 X-Forwarded-* 信任路徑。

Origin 解析順序

對於 MCP OAuth 端點，LiteLLM 會依下列順序解析 proxy 的公開 origin：

PROXY_BASE_URL env var — 若設定且為有效的 http(s) URL，則會原樣使用。無效值會被忽略並記錄警告。
X-Forwarded-Proto / X-Forwarded-Host / X-Forwarded-Port — 僅在同時 use_x_forwarded_for 為 true 且請求對等端的 IP 落在 mcp_trusted_proxy_ranges 內時才會接受。若在未設定 use_x_forwarded_for 的情況下啟用 mcp_trusted_proxy_ranges，則這些標頭不會被信任（因為無法區分受信任的反向 proxy 與直接攻擊者）。
request.base_url — FastAPI 在請求上看到的字面 URL。對於經由 ingress 的部署，這通常是 http://<internal-host>:4000，且不會與瀏覽器 origin 相符。

如果您無法或不想設定 PROXY_BASE_URL，請明確設定 X-Forwarded 路徑：

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

並確認您的 ingress 會送出 X-Forwarded-Proto、X-Forwarded-Host，以及（若非預設）X-Forwarded-Port。請參閱 MCP OAuth 疑難排解取得診斷用 curl。

允許其他第一方 redirect_uri origin

如果第一方 OAuth client 位於姊妹網域（例如，app.example.com 上的內部 web app，向 llm.example.com 上的 MCP proxy 註冊），請設定 MCP_TRUSTED_REDIRECT_ORIGINS，以將其 origin 加入允許清單，除了 proxy 自身的 origin 之外：

MCP_TRUSTED_REDIRECT_ORIGINS=app.example.com,*.tools.example.com

以逗號分隔的 host 或 host:port 項目清單。
僅限 HTTPS。允許清單路徑會拒絕任何非 https 的 redirect_uri。
*.suffix 項目會比對任何嚴格更深一層的 suffix 子網域（*.tools.example.com 會比對 a.tools.example.com，但不會比對 tools.example.com）。
Loopback（localhost、127.0.0.0/8、::1）無論此設定為何一律接受。

這適用於您可控的第一方 OAuth 用戶端。對於標準的入口案例，請優先使用 PROXY_BASE_URL。

為什麼會存在同源檢查

MCP 代理的 /v1/mcp/server/oauth/<server_id>/authorize 端點會驗證呼叫者的 redirect_uri 是否與代理本身的公開原始來源共享 scheme + host + port（或與上述其中一個迴圈回呼／允許清單項目相符）。此檢查的目的在於防止攻擊者以釣魚方式誘導已登入的管理員點擊一個連結，將授權碼經由攻擊者控制的主機轉送，進而影響像 GitHub 或 Slack 這類受上游 OAuth 保護的 MCP 伺服器。相同來源（加上明確的營運允許清單）是與用於原生 MCP 用戶端的僅限迴圈回呼規則在威脅模型上同等安全的做法。

PROXY_BASE_URL 是入口部署的正確逃逸閥，因為營運者是透過帶外方式宣告代理程式的真實公開來源，而不是要求代理程式從攻擊者可能可設定的標頭推斷。此檢查本身不會放寬。

機器對機器（M2M）驗證

LiteLLM 會使用 client_credentials 授權，自動擷取、快取並重新整理 OAuth2 權杖。無需手動管理權杖。

設定

您可以透過 LiteLLM UI 或 config.yaml 設定 M2M OAuth。

UI 設定

前往 MCP Servers 頁面並點擊 + Add New MCP Server。

輸入您的伺服器名稱，並將傳輸類型選為 HTTP。

貼上 MCP 伺服器 URL。

在 Authentication 下選擇 OAuth。

選擇 Machine-to-Machine (M2M) 作為 OAuth 流程類型。這是使用 client_credentials 授權的伺服器對伺服器驗證，且不需要瀏覽器互動。

填入您的 OAuth 提供者提供的 Client ID 與 Client Secret。

輸入 Token URL，也就是 LiteLLM 將用來透過 client_credentials 擷取存取權杖的端點。

向下捲動並檢查伺服器 URL 與所有欄位，然後按一下 Create MCP Server。

建立完成後，開啟伺服器並前往 MCP Tools 分頁，以確認 LiteLLM 可以連線並列出可用工具。

選取一個工具（例如 echo）來測試。填入所需參數，然後按一下 Call Tool。

LiteLLM 會在幕後自動擷取 OAuth token 並呼叫工具。結果確認 M2M OAuth 流程已端對端正常運作。

Config.yaml 設定

config.yaml
mcp_servers:
  my_mcp_server:
    url: "https://my-mcp-server.com/mcp"
    auth_type: oauth2
    oauth2_flow: client_credentials
    client_id: os.environ/MCP_CLIENT_ID
    client_secret: os.environ/MCP_CLIENT_SECRET
    token_url: "https://auth.example.com/oauth/token"
    scopes: ["mcp:read", "mcp:write"]  # optional

將權杖送到不同的標頭

預設情況下，LiteLLM 解析出的權杖會以 Authorization: Bearer <token> 送出，這也是幾乎所有 MCP 伺服器所預期的。某些部署會將 MCP 伺服器置於 API 閘道之後，該閘道會從私有標頭讀取自己的憑證，而閘道後方的伺服器仍希望自己的 bearer 置於 Authorization。這就需要在同一個請求中帶上兩組憑證。

設定 upstream_token_header 來指定已解析權杖應使用的標頭。您在 static_headers 下設定的任何內容都會保持不變，因此第二組憑證會原封不動地送到閘道後方的伺服器。

config.yaml
mcp_servers:
  my_mcp_server:
    url: "https://my-mcp-server.com/mcp"
    auth_type: oauth2
    oauth2_flow: client_credentials
    client_id: os.environ/MCP_CLIENT_ID
    client_secret: os.environ/MCP_CLIENT_SECRET
    token_url: "https://auth.example.com/oauth/token"
    upstream_token_header: "esb-oauth"
    static_headers:
      Authorization: "Bearer os.environ/UPSTREAM_MCP_TOKEN"

之後每個送往 MCP 伺服器的請求都會同時帶有：

esb-oauth: Bearer <the token LiteLLM minted>
Authorization: Bearer <the token you configured>

若不設定 upstream_token_header，則會維持預設值，因此既有伺服器不受影響。該值必須是有效的 HTTP 標頭名稱；若格式錯誤，代理會拒絕啟動，而管理 API 會以 400 拒絕。

在 UI 中，相同設定是 MCP 伺服器表單 OAuth 區段中的 Token Header 欄位，且它同樣適用於互動式流程、權杖交換模式以及 M2M。

運作方式

在第一次 MCP 請求時，LiteLLM 會 POST 到 token_url，並帶上 grant_type=client_credentials
存取 token 會以 TTL = expires_in - 60s 快取於記憶體中
後續請求會重用已快取的 token
當 token 到期時，LiteLLM 會自動擷取新的 token

使用 Mock Server 測試

使用 BerriAI/mock-oauth2-mcp-server 進行本機測試：

Terminal 1 - Start mock server
uv add fastapi uvicorn
python mock_oauth2_mcp_server.py  # starts on :8765

config.yaml
mcp_servers:
  test_oauth2:
    url: "http://localhost:8765/mcp"
    auth_type: oauth2
    oauth2_flow: client_credentials
    client_id: "test-client"
    client_secret: "test-secret"
    token_url: "http://localhost:8765/oauth/token"

Terminal 2 - Start proxy and test
litellm --config config.yaml --port 4000

# See MCP REST API guide for full examples (server_id, tool naming, common errors)
# https://docs.litellm.ai/docs/mcp_rest_api

curl http://localhost:4000/mcp-rest/tools/list \
  -H "Authorization: Bearer $LITELLM_API_KEY"

curl http://localhost:4000/mcp-rest/tools/call \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LITELLM_API_KEY" \
  -d '{
    "server_id": "test_oauth2",
    "name": "echo",
    "arguments": {"message": "hello"}
  }'

設定參考

欄位	必填	說明
`auth_type`	是	必須為 `oauth2`。對於 RFC 8693 On-Behalf-Of，請改用 `oauth2_token_exchange`——請參閱 MCP OBO Auth。
`oauth2_flow`	是	流程選擇器。為 `"client_credentials"`（M2M）或 `"authorization_code"`（互動式 PKCE，包含 `delegate_auth_to_upstream`）之一。對於 `auth_type: oauth2` 伺服器，在 `config.yaml` 中必填；如果缺少或無效，proxy 會拒絕啟動。透過 UI 建立的伺服器會從 OAuth 流程類型選擇器取得此值。只有在此欄位存在之前建立的舊版資料庫列，才會在請求時根據欄位形狀回退推斷；設定項目永遠不會被推斷。
`client_id`	M2M 必填，互動式選填	OAuth2 client ID。`client_credentials` 時必填。對於互動式流程，如果上游支援，可透過位於 `POST /{server_name}/register` 的 Dynamic Client Registration（RFC 7591）取得。支援 `os.environ/VAR_NAME`。
`client_secret`	M2M 必填，互動式選填	OAuth2 client secret。適用性與 `client_id` 相同。支援 `os.environ/VAR_NAME`。
`token_url`	M2M 必填，互動式選填	Token endpoint URL。LiteLLM 會對此發送 POST，用於 `client_credentials` 以及授權碼交換。
`authorization_url`	僅互動式	上游授權端點。存在時，LiteLLM 會將伺服器視為互動式 PKCE，並將 `GET /{server_name}/authorize` 代理到此 URL。
`registration_url`	選填	上游 Dynamic Client Registration 端點（RFC 7591）。存在時，`POST /{server_name}/register` 會代理到此 URL。
`scopes`	否	要請求的 scope 清單。對於 M2M，會合併成 token 請求中的 `scope` 參數。對於互動式，則在 authorize 請求中轉送。
`token_validation`	否	在 `/token` 交換之後，針對 OAuth token 回應檢查的鍵值規則字典。任何規則不符都會以 `token_validation_failed` 失敗。可用於斷言像 `{"team.enterprise_id": "T12345"}` 之類的 tenant claim。
`token_storage_ttl_seconds`	否	覆寫每位使用者 token 快取（互動式流程）的 TTL。若未設定，LiteLLM 會使用 token 回應中的 `expires_in - buffer`。

OAuth 除錯

當 LiteLLM proxy 遠端代管，且無法存取伺服器記錄時，請啟用除錯標頭，以在 HTTP 回應中取得已遮蔽的驗證診斷資訊。

啟用除錯模式

將 x-litellm-mcp-debug: true 標頭加入您的 MCP client 請求。

Claude Code：

claude mcp add --transport http litellm_proxy http://proxy.example.com/atlassian_mcp/mcp \
  --header "x-litellm-api-key: Bearer sk-..." \
  --header "x-litellm-mcp-debug: true"

curl：

curl -X POST http://localhost:4000/atlassian_mcp/mcp \
  -H "Content-Type: application/json" \
  -H "x-litellm-api-key: Bearer sk-..." \
  -H "x-litellm-mcp-debug: true" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

讀取除錯回應標頭

回應包含以下標頭（所有敏感值均已遮罩）：

標頭	說明
`x-mcp-debug-inbound-auth`	顯示有哪些傳入的驗證標頭存在。
`x-mcp-debug-oauth2-token`	OAuth2 權杖（已遮罩）。如果 LiteLLM 金鑰外洩，會顯示 `SAME_AS_LITELLM_KEY`。
`x-mcp-debug-auth-resolution`	使用了哪種驗證方法：`oauth2-passthrough`、`m2m-client-credentials`、`per-request-header`、`static-token`，或 `no-auth`。
`x-mcp-debug-outbound-url`	上游 MCP 伺服器 URL。
`x-mcp-debug-server-auth-type`	伺服器上設定的 `auth_type`。

範例，健康的 OAuth2 passthrough：

x-mcp-debug-inbound-auth: x-litellm-api-key=Bearer****1234; authorization=Bearer****ef01
x-mcp-debug-oauth2-token: Bearer****ef01
x-mcp-debug-auth-resolution: oauth2-passthrough
x-mcp-debug-outbound-url: https://mcp.atlassian.com/v1/mcp
x-mcp-debug-server-auth-type: oauth2

範例，LiteLLM 金鑰外洩（設定錯誤）：

x-mcp-debug-inbound-auth: authorization=Bearer****1234
x-mcp-debug-oauth2-token: Bearer****1234 (SAME_AS_LITELLM_KEY - likely misconfigured)
x-mcp-debug-auth-resolution: oauth2-passthrough
x-mcp-debug-outbound-url: https://mcp.atlassian.com/v1/mcp
x-mcp-debug-server-auth-type: oauth2

常見問題

LiteLLM API 金鑰洩漏到 MCP 伺服器

症狀： x-mcp-debug-oauth2-token 顯示 SAME_AS_LITELLM_KEY。

Authorization 標頭帶的是 LiteLLM API 金鑰，而不是 OAuth2 權杖。由於用戶端已經設定了 Authorization 標頭，OAuth2 流程根本沒有執行。

修正： 將 LiteLLM 金鑰移到 x-litellm-api-key：

# WRONG — blocks OAuth2 discovery
claude mcp add --transport http my_server http://proxy/server/mcp \
    --header "Authorization: Bearer sk-..."

# CORRECT — LiteLLM key in dedicated header, Authorization free for OAuth2
claude mcp add --transport http my_server http://proxy/server/mcp \
    --header "x-litellm-api-key: Bearer sk-..."

未存在 OAuth2 token

症狀： x-mcp-debug-oauth2-token 顯示 (none)，而 x-mcp-debug-auth-resolution 顯示 no-auth。

請確認：

Authorization 標頭未作為用戶端設定中的靜態標頭設定。
LiteLLM 設定中的 MCP 伺服器具有 auth_type: oauth2。
.well-known/oauth-protected-resource 端點會回傳有效的中繼資料。

使用 M2M token 代替使用者 token

症狀： x-mcp-debug-auth-resolution 顯示 m2m-client-credentials。

伺服器已設定 client_id/client_secret/token_url，因此 LiteLLM 取得的是機器對機器的權杖，而不是使用每位使用者的 OAuth2 權杖。若要使用每位使用者的權杖，請從伺服器設定中移除用戶端憑證。

Passthrough 與委派式上游 OAuth

對於用戶端已經直接向上游自身的 OAuth 發行者完成驗證的伺服器，LiteLLM 可以轉送用戶端的上游權杖，而不是自行管理權杖。透明的 auth_type: true_passthrough 模式、 admission-gated 的 auth_type: oauth_delegate 模式，以及舊版 delegate_auth_to_upstream 旗標，皆收錄於 MCP OAuth Passthrough。該頁面也說明了供 OpenCode、Claude Code、Cursor 和 Claude Desktop 等僅支援 OAuth 的用戶端使用的 dcr_bridge 旗標，其中閘道負責註冊與登入，讓用戶端可透過單一 OAuth 流程連線。

互動式 OAuth（PKCE）​

設定​

運作方式​

靜態 OAuth 用戶端的重新導向 URL​

設定上游 OAuth 應用程式​

識別 MCP 用戶端的回呼 URL​

重新導向 URI 驗證​

疑難排解回呼錯誤​

閘道動態用戶端註冊​

驗證配置​

反向代理與 ingress 設定​

Origin 解析順序​

允許其他第一方 redirect_uri origin​

為什麼會存在同源檢查​

機器對機器（M2M）驗證​

設定​

UI 設定​

Config.yaml 設定​

將權杖送到不同的標頭​

運作方式​

使用 Mock Server 測試​

設定參考​

OAuth 除錯​

啟用除錯模式​

讀取除錯回應標頭​

常見問題​

LiteLLM API 金鑰洩漏到 MCP 伺服器​

未存在 OAuth2 token​

使用 M2M token 代替使用者 token​

Passthrough 與委派式上游 OAuth​

互動式 OAuth（PKCE）

設定

運作方式

靜態 OAuth 用戶端的重新導向 URL

設定上游 OAuth 應用程式

識別 MCP 用戶端的回呼 URL

重新導向 URI 驗證

疑難排解回呼錯誤

閘道動態用戶端註冊

驗證配置

反向代理與 ingress 設定

Origin 解析順序

允許其他第一方 redirect_uri origin

為什麼會存在同源檢查

機器對機器（M2M）驗證

設定

UI 設定

Config.yaml 設定

將權杖送到不同的標頭

運作方式

使用 Mock Server 測試

設定參考

OAuth 除錯

啟用除錯模式

讀取除錯回應標頭

常見問題

LiteLLM API 金鑰洩漏到 MCP 伺服器

未存在 OAuth2 token

使用 M2M token 代替使用者 token

Passthrough 與委派式上游 OAuth