fix(mcp): relay upstream OAuth token and DCR rejections instead of a generic 500

[tin-berri]

Relevant issues

Behavior changes at a glance

Token exchange, POST /v1/mcp/server/oauth/{server_id}/token (the dashboard's Authorize & Fetch Token callback) plus the discoverable POST /v1/mcp/{name}/token and POST /v1/mcp/token routes; the refresh_token grant flows through the same path

Scenario	Before	After
IdP rejects with a caller-actionable code (invalid_grant expired/redeemed code, invalid_scope, unrecognized codes)	500 Internal server error	400 with {"error", "error_description", "error_uri"} relayed, each field capped at 500 chars
Caller supplied their own client_id/client_secret and the IdP rejects them (invalid_client)	500	401 invalid_client with the IdP's fields relayed; the caller owns the credential
IdP rejects the server's stored credentials (invalid_client, unauthorized_client)	500	502 server_error, "the upstream authorization server rejected the gateway's configured client credentials (invalid_client); verify the MCP server's client_id and client_secret"; IdP prose goes to server logs
IdP blames itself (server_error, temporarily_unavailable)	500	502 or 503 with the matching code and a gateway-authored description
IdP requires RFC 8707 resource indicators (invalid_target)	500	502 server_error naming invalid_target and the missing gateway capability, regardless of whose credentials were sent
IdP pairs a caller-fault code with a server-fault status (HTTP 500 body invalid_grant)	500	400 invalid_grant; status derives from the code's meaning, never from the upstream's status
Out-of-contract rejection (HTML 404 page, no JSON error field)	500	502 "upstream token endpoint returned HTTP 404"; the body never reaches the client, logged bounded server-side
Rejection body unreadable (lying content-encoding, decode failure)	500	same 502 protocol fault; classifiers are total
IdP returns 200 without a usable access_token	500 (KeyError)	502 "the upstream token response has no usable access_token"

Every error response above now carries Cache-Control: no-store and Pragma: no-cache per RFC 6749 section 5.1

DCR registration, POST /v1/mcp/server/oauth/{server_id}/register and POST /v1/mcp/{name}/register

Scenario	Before	After
Upstream RFC 7591 rejection (invalid_redirect_uri, invalid_client_metadata)	500	400 with detail "invalid_redirect_uri: redirect_uri not allowed", normalized to 400 per RFC 7591 even when the upstream chose another status
Upstream self-blame code (server_error)	500	502 with a gateway-authored description
Out-of-contract failure (HTML error page, stack trace)	500	502 "upstream registration failed with HTTP 500"; body server-logged only
Bridge-relay arm	relay code existed but was unreachable in production (the HTTP client raises at call time, before the status check)	reachable; both arms behave identically

Dashboard

Scenario	Before	After
Red text under Authorize & Fetch Token on any failure	"Internal server error"	the composed reason, e.g. "invalid_request: client_secret is missing." or the verify-client_id-and-client_secret guidance

Deliberately unchanged: egress token refresh, M2M, and OBO keep their fail-closed absorb-then-challenge behavior; the aggregate tools/list still omits failed servers; the connect-time probe still fails open on network errors. Raw upstream bodies and provider prose for gateway-fault codes no longer reach callers anywhere on these endpoints; when debugging an IdP's exact words, read the proxy logs

Linear ticket

Resolves LIT-4420

Pre-Submission checklist

Please complete all items before asking a LiteLLM maintainer to review your PR

• I have added meaningful tests
• My PR passes all CI/CD checks (e.g., lint, format, unit tests)
• My PR's scope is as isolated as possible; it only solves 1 specific problem
• I have received a Greptile Confidence Score of at least 4/5 before requesting a maintainer review (Greptile reviews automatically once the PR is opened; only comment @greptileai to re-request a review after pushing changes)

Delays in PR merge?

If you're seeing a delay in your PR being merged, ping the LiteLLM Team on Slack (#pr-review).

Screenshots / Proof of Fix

Setup for both runs: proxy on localhost:4000 backed by Postgres, then a temporary create-flow session server pointing at the real Google token endpoint (this is exactly what the dashboard's "Authorize & Fetch Token" button creates)

curl -s -X POST http://localhost:4000/v1/mcp/server/oauth/session \
  -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" \
  -d '{"server_name":"gcal_proof","url":"https://calendarmcp.googleapis.com/mcp/v1","transport":"http","auth_type":"oauth2","oauth2_flow":"authorization_code","credentials":{"client_id":"not-a-real-client.apps.googleusercontent.com"},"authorization_url":"https://accounts.google.com/o/oauth2/v2/auth","token_url":"https://oauth2.googleapis.com/token","scopes":["https://www.googleapis.com/auth/calendar.readonly"]}'

What Google itself answers for this exchange (the signal the gateway was destroying)

$ curl -s -w '\nHTTP_STATUS:%{http_code}\n' -X POST https://oauth2.googleapis.com/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" --data-urlencode "code=bogus-auth-code" \
  --data-urlencode "client_id=not-a-real-client.apps.googleusercontent.com" \
  --data-urlencode "code_verifier=abcdefghijklmnopqrstuvwxyz0123456789abcdefg" \
  --data-urlencode "redirect_uri=http://localhost:4000/ui/mcp/oauth/callback"
{
  "error": "invalid_client",
  "error_description": "The OAuth client was not found."
}
HTTP_STATUS:401

Before (at fa09cde, the litellm_internal_staging tip this branch is based on): the same exchange through the gateway is an opaque 500, which is what the dashboard shows as "Internal server error" under the Authorize & Fetch Token button

$ curl -s -w '\nHTTP_STATUS:%{http_code}\n' -X POST "http://localhost:4000/v1/mcp/server/oauth/$SID/token" \
  -H "Authorization: Bearer sk-1234" -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=authorization_code" --data-urlencode "code=bogus-auth-code" \
  --data-urlencode "code_verifier=abcdefghijklmnopqrstuvwxyz0123456789abcdefg" \
  --data-urlencode "redirect_uri=http://localhost:4000/ui/mcp/oauth/callback"
{"error":{"message":"Internal server error","type":"internal_server_error"}}
HTTP_STATUS:500

with the proxy log showing the raw escape

LiteLLM Proxy:ERROR: proxy_server.py:1411 - Unhandled exception in request: MaskedHTTPStatusError
litellm.llms.custom_httpx.http_handler.MaskedHTTPStatusError: Client error '401 Unauthorized' for url 'https://oauth2.googleapis.com/token'

After (at 9e94f2b): the same command classifies the rejection before rendering. The server's stored client credentials were what Google rejected, so the fault is the operator's, not the caller's: 502 server_error with gateway-authored prose naming the code and what to fix, while Google's own prose goes to server logs

{"error":"server_error","error_description":"the upstream authorization server rejected the gateway's configured client credentials (invalid_client); verify the MCP server's client_id and client_secret"}
HTTP_STATUS:502

Same run, but with a session server that has no stored client and the caller supplying client_id on the token request: now the rejection is the caller's to act on, so the section 5.2 fields relay verbatim on the status the code implies

$ curl ... --data-urlencode "client_id=caller-client.apps.googleusercontent.com" ...
{"error":"invalid_client","error_description":"The OAuth client was not found."}
HTTP_STATUS:401

Edge case, same commit: a token_url answering outside the RFC 6749 section 5.2 contract (HTML 404 from https://oauth2.googleapis.com/no-such-token-endpoint) maps to 502, keeps the no-store headers, and the upstream body stays out of the client response (it is logged server-side, bounded)

{"error":"server_error","error_description":"upstream token endpoint returned HTTP 404"}
HTTP_STATUS:502

UI verification (needs a screenshot from a browser): on http://localhost:3000, MCP Servers, Add New MCP Server, fill an OAuth Interactive (PKCE) server with a Google client_id and no client secret, click Authorize & Fetch Token and complete the consent; the red text under the button now reads "invalid_client: The OAuth client was not found." (or Google's actual reason, e.g. "invalid_request: client_secret is missing.") instead of "Internal server error"

Type

🐛 Bug Fix

Changes

The create-flow "Authorize & Fetch Token" exchange (POST /v1/mcp/server/oauth/{server_id}/token) and the discoverable runtime token routes delegate to exchange_token_with_server, which let the upstream rejection escape as a raw httpx.HTTPStatusError; FastAPI's global handler turned that into a generic 500 that hid the IdP's reason. The classic way to hit this is Google, which rejects a secret-less token exchange even for PKCE web application clients, so the one message the admin needed ("client_secret is missing.") was exactly the one being destroyed

The fix is a small framework rather than another try/except: a new mcp_server/faults package (types.py, classify.py, render_oauth.py) classifies an upstream token or DCR rejection into exactly one frozen fault value, and the response status, wire error code, and prose are all derived from that value. Deriving all three from one classification makes contradictory pairings unrepresentable; the review-bot findings on earlier iterations of this branch (a caller-fault invalid_grant relayed on a 502, a response.text decode error resurrecting the opaque 500) were both symptoms of relaying independent facts from the same upstream response, and both are now closed structurally rather than patched individually

Classification rules, each pinned by a test: a body with a section 5.2 error field is contract-conformant and blame follows the code and the credential source. Codes by which the upstream blames itself (server_error, temporarily_unavailable) stay upstream faults and render 502/503 with a matching wire code. invalid_target is a gateway capability gap (RFC 8707 resource indicators, which the gateway does not send yet) and is gateway-blamed regardless of whose credentials were presented. Credential-indicting codes (invalid_client, unauthorized_client) against the server's stored credentials are the operator's fault: 502 server_error with gateway-authored prose naming the code and the fix, upstream prose logged server-side only; the same codes against caller-supplied credentials stay caller faults and relay. Remaining caller-actionable codes (invalid_grant, invalid_scope, unknown extensions) relay code, bounded description, and error_uri on the status the code implies (401 for invalid_client, else 400), regardless of whatever status the upstream chose. Anything without a usable error field, including bodies that cannot be decoded at all (the classifiers are total), is an upstream protocol fault: 502 with a gateway-authored note and the body kept out of the client response entirely. DCR rejections share the same blame assignment and normalize to 400 per RFC 7591 section 3.2.2. All token-endpoint faults carry the section 5.1 no-store headers

The same relay covers register_client_with_server (both bridge and non-bridge arms, previously divergent), and a 200 token response without a usable access_token answers 502 instead of KeyErroring into a 500. Exhaustive matches with assert_never keep any future fault arm from shipping unrendered

One finding from live verification worth calling out: litellm's AsyncHTTPHandler.post calls raise_for_status() internally and raises MaskedHTTPStatusError at call time, so a try/except around the explicit raise_for_status() after the post never fires in production (unit tests with mocked clients pass regardless, which is how the pre-existing bridge-relay status check at the registration site was unreachable live without any test noticing). The relays therefore wrap the post call itself, and two regression tests pin that exact mechanism by making the mocked client raise at call time

The deliberate contract change: test_register_non_bridge_upstream_error_still_raises_500 pinned the old non-bridge propagation for flag-off parity when the bridge relay landed; it is rewritten as test_register_non_bridge_upstream_error_relays_status_not_500 since the generic 500 hides RFC 7591 rejections from the create-flow UI admin just as badly as token rejections

On the dashboard side, exchangeMcpOAuthToken composes error: error_description when the response body carries the section 5.2 fields, so the form under Authorize & Fetch Token shows the IdP's own reason

Egress token machinery (per-user refresh, M2M client_credentials, OBO token exchange) deliberately keeps its fail-closed absorb-then-challenge behavior; those paths serve tool calls, not the browser-facing OAuth endpoints, and were audited but intentionally left unchanged

Final Attestation

• The tests check the right things, including the edge cases, and regressions in the respective real-world customer use-cases are not possible after this PR

[greptile-apps]

Greptile Summary

Upstream OAuth token-exchange and DCR registration failures on MCP discoverable endpoints no longer surface as opaque 500s. A new mcp_server/faults package classifies each upstream rejection once into a typed fault, then derives HTTP status, wire error code, and client-visible prose from that single value so the three facts can never contradict each other.

• Token exchange (exchange_token_with_server): wraps async_client.post in a try/except for httpx.HTTPStatusError (covering both the return-then-raise and the raise-at-call-time paths that litellm's MaskedHTTPStatusError triggers in production); gateway-credential faults become 502 with operator-facing prose, caller faults relay bounded §5.2 fields on 400/401, and a 200 without a usable access_token answers 502 instead of KeyError.
• DCR registration (register_client_with_server): unified bridge and non-bridge arms under the same classify/render path via dcr_fault_detail; non-bridge path previously let raw HTTPStatusError escape to the global handler, producing a generic 500.
• Dashboard (exchangeMcpOAuthToken): now surfaces error: error_description when the proxy returns §5.2-shaped JSON, showing the IdP's actual rejection reason in the UI.

Confidence Score: 5/5

Safe to merge — changes are isolated to MCP OAuth relay error paths, all new code paths are covered by mocked unit and integration tests, and the egress token machinery (refresh, M2M, OBO) is explicitly unchanged.

The implementation is structurally sound: every classifier is total (bare-except fallbacks, length-bounded fields), the exhaustive match with assert_never in the renderer prevents an unhandled fault arm from silently shipping, and the two distinct raise mechanisms (client returns then raise_for_status fires; client raises at call time) are each covered by dedicated regression tests. The test rewrite for the non-bridge DCR path correctly asserts the fixed behavior rather than weakening coverage. No logic bugs were found across the fault taxonomy, classification rules, or rendering paths.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/proxy/_experimental/mcp_server/faults/types.py	New file: defines a frozen Pydantic fault taxonomy (CallerRejected, GatewayRejected, UpstreamReportedFault, UpstreamProtocolFault) with string constants for credential and capability codes; all models are frozen and well-typed.
litellm/proxy/_experimental/mcp_server/faults/classify.py	New file: total classifiers for token and DCR rejections; all body accessors are guarded (_safe_json/_safe_text), field values are length-bounded, and every code path returns a fault value rather than propagating exceptions.
litellm/proxy/_experimental/mcp_server/faults/render_oauth.py	New file: renders classified faults to RFC 6749 §5.2 JSONResponses; exhaustive match with assert_never prevents unrendered fault arms, and all token responses carry the no-store headers.
litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py	Token exchange and DCR registration now wrap async_client.post in a try/except for HTTPStatusError (catching both return-then-raise and raise-at-call-time paths), classify via the faults package, and return structured responses; missing access_token on 200 is also handled as a protocol fault instead of a KeyError.
tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py	Extended with integration tests covering gateway vs caller credential faults, contradictory upstream status/code, field bounding, out-of-contract bodies, missing access_token, and the raise-at-call-time regression for both token and DCR paths; test_register_non_bridge_upstream_error_still_raises_500 rewritten to assert the corrected behavior.
ui/litellm-dashboard/src/components/networking.tsx	exchangeMcpOAuthToken now surfaces error: error_description when the proxy returns §5.2-shaped JSON, so the dashboard form shows the IdP's actual reason instead of a generic failure message.

_{Reviews (5): Last reviewed commit: "fix(mcp): keep upstream self-blame codes..." | Re-trigger Greptile}

[tin-berri]

@greptileai

[codecov]

Codecov Report

❌ Patch coverage is 95.80420% with 6 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...xy/_experimental/mcp_server/faults/render_oauth.py	87.80%	5 Missing ⚠️
..._experimental/mcp_server/discoverable_endpoints.py	95.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[veria-ai]

PR overview

All previously flagged issues have been addressed. No open security concerns remain on this pull request.

Security review

No open security issues remain on this pull request.

Fixed/addressed: 1 · PR risk: 0/10

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_mcp_oauth_error_relay (b70de76) with litellm_internal_staging (53aaabb)}

[tin-berri]

@greptileai

[tin-berri]

bugbot run

[tin-berri]

@greptileai

[tin-berri]

bugbot run

[tin-berri]

@greptileai

[tin-berri]

bugbot run

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 9335ede. Configure here.}

[mateo-berri]

LGTM; thanks!

[mateo-berri]

Just resolve the merge conflict; seems trivial