fix(mcp): make the preemptive-401 OAuth challenge decision mode-aware

[tin-berri]

Relevant issues

Linear ticket

Part of LIT-4263 (migrate client_credentials M2M into v2); this ships the connect-time gate fix that track requires

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)

Screenshots / Proof of Fix

The gateway's preemptive-401 challenge for auth_type: oauth2 MCP servers decided whether to challenge based on whether an Authorization header was present, when the decision should depend on the server's oauth2 sub-mode. Two behaviors were wrong: a LiteLLM virtual key sent as Authorization: Bearer sk-... on a gateway-managed authorization_code server suppressed the challenge and opened a session whose tools/list masked the missing upstream token as 200 with an empty tool list, and client_credentials (M2M) servers were challenged even though the gateway mints their token itself.

Reproduced and verified against a live dockerized gateway (ghcr.io/berriai/litellm:main-latest) with a real Postgres, registering an oauth2 authorization_code server and driving the MCP initialize over streamable HTTP two ways: the key in x-litellm-api-key (the working control) and the same key in Authorization.

Register the server and mint a user-bound key scoped to it:

curl -s -X POST http://localhost:4000/v1/mcp/server -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" -d '{
  "alias": "reprooauth", "url": "http://mcp-stub:8765/oauthuser/mcp", "transport": "http", "allow_all_keys": false,
  "auth_type": "oauth2", "oauth2_flow": "authorization_code",
  "authorization_url": "http://localhost:8765/oauth/authorize", "token_url": "http://mcp-stub:8765/oauth/token",
  "credentials": {"client_id": "...", "client_secret": "..."}}'

curl -s -X POST http://localhost:4000/key/generate -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" \
  -d '{"user_id": "e2e-test-user", "object_permission": {"mcp_servers": ["<server_id>"]}}'

Before the fix (stock image):

# (A) key in x-litellm-api-key  [control: correctly challenged]
curl -si -X POST http://localhost:4000/reprooauth/mcp -H "x-litellm-api-key: Bearer <key>" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"repro","version":"0"}}}'
HTTP/1.1 401 Unauthorized
www-authenticate: Bearer authorization_uri="http://localhost:4000/.well-known/oauth-authorization-server/reprooauth"

# (B) same key in Authorization  [BUG: masked, no challenge]
curl -si -X POST http://localhost:4000/reprooauth/mcp -H "Authorization: Bearer <key>" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}'
HTTP/1.1 200 OK
mcp-session-id: 284b1f29becd4c38a96ac538e8826405

After the fix (same running container with server.py replaced and the proxy restarted, same two commands):

# (A) key in x-litellm-api-key  [unchanged]
HTTP/1.1 401 Unauthorized
www-authenticate: Bearer authorization_uri="http://localhost:4000/.well-known/oauth-authorization-server/reprooauth"

# (B) same key in Authorization  [FIXED: now the same 401 challenge, was 200]
HTTP/1.1 401 Unauthorized
www-authenticate: Bearer authorization_uri="http://localhost:4000/.well-known/oauth-authorization-server/reprooauth"

The x-litellm-api-key control is byte-identical before and after, so nothing about the working path changed; the Authorization case flips from a silent 200 masked-empty session to the same loud 401 challenge, so an OAuth-capable host now engages instead of seeing zero tools with no error.

Note on the Authorization header placement: this fix makes the gateway fail closed and loudly (challenge) instead of silently (masked-empty). Completing the full interactive round-trip still requires the LiteLLM key in x-litellm-api-key, because once the host completes the OAuth dance it carries the minted upstream token in Authorization, so that slot cannot also hold the LiteLLM key. Turning the silent masking into a diagnosable challenge is the customer-facing fix here.

Type

🐛 Bug Fix

Changes

_raise_preemptive_401_for_unauthenticated_servers in litellm/proxy/_experimental/mcp_server/server.py gated the oauth2 challenge on server.auth_type == MCPAuth.oauth2 and not oauth2_headers. oauth2_headers is populated by _get_oauth2_headers_from_headers, which classifies any Authorization header as an OAuth token; it has to be mode-blind because it runs before the target server is resolved. So on a gateway-managed server a LiteLLM key riding in Authorization made oauth2_headers truthy and skipped the whole challenge block.

The gate is now decided per oauth2 sub-mode, using the resolved server object that is already in hand. client_credentials (M2M) is never challenged, since the gateway mints its own token at egress from the stored client credentials. Gateway-managed interactive (authorization_code, delegate_auth_to_upstream false) is challenged whenever no stored per-user token exists, regardless of any bearer, because a bearer there is a LiteLLM key and never an upstream token. Only the delegate/upstream-PKCE mode, where a present bearer genuinely is the upstream token, keeps keying the challenge on not oauth2_headers. oauth2_headers itself is not mutated, so the delegate and pass-through egress paths that forward the client bearer are untouched.

The M2M classification goes through MCPServerManager.effective_oauth2_flow, the same shape-inference chokepoint egress uses via resolve_oauth2_flow_for_request, rather than the bare has_client_credentials column. So a legacy row with oauth2_flow left null but the M2M shape (client_id, client_secret, token_url) is treated as M2M in the challenge gate exactly as it is at egress, instead of being misread as interactive and getting a spurious 401.

The second commit grafts the transport-level regression tests from PR #33582, which this PR supersedes: they drive handle_streamable_http_mcp end to end with real MCPServer objects, parametrized over a stamped client_credentials row and a legacy unstamped M2M-shape row, asserting the request reaches the session manager and the per-user token store is never consulted

QA runbook

• tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server.py::TestPreemptive401ModeAware
  • Run the class; all six pass on this branch. On the mode-blind code the Authorization-masking and both M2M cases fail while the already-correct cases pass, so the failing cases isolate exactly the behaviors this change fixes
  • test_gateway_managed_interactive_no_token_challenges_with_x_litellm_api_key: interactive server, no stored token, key in x-litellm-api-key; expect a 401 with a WWW-Authenticate header
  • test_gateway_managed_interactive_no_token_challenges_with_authorization_bearer: same server and no stored token, key in Authorization; expect the same 401 challenge, not a suppressed session
  • test_gateway_managed_interactive_with_stored_token_does_not_challenge: a stored per-user token exists; expect no challenge under either header
  • test_m2m_never_challenges: client_credentials server; expect no challenge under either header, stored token or not
  • test_delegate_challenges_only_when_bearer_absent: delegate_auth_to_upstream server; expect a challenge only when no bearer is present
  • test_unstamped_m2m_shape_never_challenges: a row with oauth2_flow null but the M2M shape (client_id, client_secret, token_url); expect no challenge, since effective_oauth2_flow resolves it to client_credentials exactly as egress does
  • Live proxy: register an oauth2 authorization_code server, mint a user-bound key, and confirm the initialize on /{alias}/mcp returns 401 + WWW-Authenticate with the key in either x-litellm-api-key or Authorization (was 200 + empty for Authorization)

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

---

Note

Medium Risk
Changes MCP gateway OAuth connect behavior on a security-sensitive path; scope is localized to preemptive 401 logic with targeted regression tests.

Overview
Preemptive MCP OAuth challenges no longer skip when Authorization: Bearer … is present. _raise_preemptive_401_for_unauthenticated_servers now branches on each server's oauth2 sub-mode instead of gating on not oauth2_headers.

For gateway-managed authorization_code servers, the gateway issues a 401 + WWW-Authenticate whenever there is no stored per-user token, even if the bearer is a LiteLLM virtual key (the regression that allowed initialize to return 200 with an empty tools list). client_credentials (M2M) servers are never challenged; classification uses MCPServerManager.effective_oauth2_flow so legacy null-oauth2_flow rows with M2M field shape match egress. Delegate / upstream-PKCE mode still challenges only when no bearer is present (bearer treated as upstream token).

Adds TestPreemptive401ModeAware with six async tests covering interactive (both header styles), stored token, M2M, unstamped M2M shape, and delegate behavior.

^{Reviewed by Cursor Bugbot for commit 2c19550. Bugbot is set up for automated code reviews on this repo. Configure here.}

[tin-berri]

@greptileai

[greptile-apps]

Greptile Summary

This PR fixes a bug in the MCP gateway's preemptive-401 challenge logic, where the decision to challenge oauth2 servers was incorrectly keyed on the presence of an Authorization header rather than the server's actual oauth2 sub-mode. The rewrite makes each sub-mode terminal and consistent with how egress resolves the flow via MCPServerManager.effective_oauth2_flow.

• server.py: _raise_preemptive_401_for_unauthenticated_servers now branches on each server's effective sub-mode — M2M (client_credentials) is immediately admitted, gateway-managed interactive (authorization_code) challenges whenever no stored per-user token exists regardless of any bearer, and delegate mode retains the original bearer-presence check. Every sub-mode path is terminal (continue or raise).
• Tests: Six new unit tests in TestPreemptive401ModeAware cover all sub-modes with both header placements; a parametrized transport-level test in test_mcp_stale_session.py exercises the end-to-end path through handle_streamable_http_mcp and asserts has_user_oauth_token is never consulted for M2M servers. All tests use mocks only.

Confidence Score: 5/5

Safe to merge; the change is localized to the preemptive-challenge gate, every sub-mode is terminal, and the fix is backed by six targeted unit tests plus a transport-level integration test.

The logic rewrite is correct and consistent with how egress resolves the flow. All three sub-mode paths are terminal, the unstamped M2M shape is handled via effective_oauth2_flow matching egress behavior, and the explicit continue at the end of the delegate-with-bearer path resolves the previously flagged maintenance risk.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/proxy/_experimental/mcp_server/server.py	Rewrites _raise_preemptive_401_for_unauthenticated_servers to branch on each server's effective oauth2 sub-mode rather than the presence of an Authorization header; logic is terminal on every sub-mode path
tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server.py	Adds TestPreemptive401ModeAware with six async tests covering all three oauth2 sub-modes; all tests use mocks only
tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_stale_session.py	Adds a parametrized transport-level test for stamped and legacy unstamped M2M servers; asserts has_user_oauth_token is never awaited for M2M

_{Reviews (5): Last reviewed commit: "test(mcp): add transport-level M2M regre..." | Re-trigger Greptile}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[tin-berri]

@greptileai

[tin-berri]

bugbot run

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_mcp_oauth_challenge_mode_aware (f023c81) with litellm_internal_staging (68f0fb0)}

[tin-berri]

Good catch, addressed in 2c19550. The M2M skip now classifies the sub-mode through MCPServerManager.effective_oauth2_flow(server) == "client_credentials", the same shape-inference chokepoint egress uses (resolve_oauth2_flow_for_request), instead of the bare has_client_credentials column. So an unstamped row (null oauth2_flow) with the M2M shape (client_id + client_secret + token_url) is now treated as M2M in the challenge gate exactly as it is at egress, and no longer gets a spurious preemptive 401. Added a regression test (test_unstamped_m2m_shape_never_challenges) that pins the null-flow M2M-shape case under both the x-litellm-api-key and Authorization headers.

[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 2c19550. Configure here.}

[tin-berri]

@greptileai

[mateo-berri]

bugbot run

[mateo-berri]

LGTM; thanks!