fix(mcp): restore PKCE-triggering 401 when no stored per-user token exists

[ishaan-berri]

Relevant issues

Pre-Submission checklist

• I have Added testing in the tests/test_litellm/ directory, Adding at least 1 test is a hard requirement - see details
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible, it only solves 1 specific problem

Type

🐛 Bug Fix

Changes

Per-user OAuth MCP requests now only skip the pre-emptive 401 when a stored token is available. This preserves token-reuse behavior while restoring fast PKCE kickoff for first-time or missing-token users.

Before this fix, the 401 that triggers the PKCE flow was never sent when no stored token existed, leaving new users stuck.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[codspeed-hq]

Congrats! CodSpeed is installed 🎉

🆕 16 new benchmarks were detected.

You will start to see performance impacts in the reports once the benchmarks are run from your default branch.

Detected benchmarks

• test_cost_per_token_anthropic: 541.1 µs
• test_token_counter_simple_message: 236 µs
• test_get_model_info_with_provider: 80.2 µs
• test_token_counter_with_tools: 417.1 µs
• test_cost_per_token_openai: 541.1 µs
• test_get_llm_provider_azure: 144.1 µs
• test_get_llm_provider_anthropic: 141.1 µs
• test_token_counter_raw_text: 183.7 µs
• test_token_counter_long_content: 1.7 ms
• test_get_model_info_openai: 84 µs
• test_get_llm_provider_openai: 137.9 µs
• test_get_model_cost_key_case_insensitive: 82.1 µs
• test_get_model_info_anthropic: 82 µs
• test_token_counter_multi_turn: 566.8 µs
• test_get_llm_provider_with_prefix: 136.9 µs
• test_get_model_cost_key_exact_match: 79.8 µs

---

[greptile-apps]

Greptile Summary

This PR fixes a bug in the MCP per-user OAuth flow where first-time users (with no stored token) were never sent the pre-emptive HTTP 401 + WWW-Authenticate header needed to kick off the PKCE authorization flow. The fix adds a DB/cache lookup for the stored token before deciding to continue past the 401 — only skipping it when a valid token already exists.

Confidence Score: 5/5

Safe to merge — the fix is a targeted, logically sound change with appropriate test coverage and no security regressions.

The logic change is minimal and correct: continue (skip 401) now only fires when a stored token is confirmed to exist, otherwise the 401 falls through as intended. Both new tests accurately reflect the fixed behavior. The only remaining note is a P2 performance observation about the double fetch on the happy path, which is mitigated by the Redis cache layer.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/proxy/_experimental/mcp_server/server.py	Adds per-user OAuth token check before pre-emptive 401: only skips PKCE 401 when a stored token exists, otherwise falls through to trigger OAuth flow for new users.
tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_stale_session.py	Adds two new integration-style tests covering the fix: missing stored token raises 401, existing stored token skips pre-emptive 401 and forwards to session manager.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[handle_streamable_http_mcp] --> B{mcp_servers loop}
    B --> C{server.auth_type == oauth2\nAND no oauth2_headers?}
    C -- No --> G[Continue to request processing]
    C -- Yes --> D{server.needs_user_oauth_token?}
    D -- No --> F[Raise 401 + WWW-Authenticate\nPKCE kickoff]
    D -- Yes --> E[_get_user_oauth_extra_headers_from_db\nRedis → DB]
    E --> H{stored token found?}
    H -- Yes --> I[continue loop\nskip 401]
    H -- No --> F
    I --> G
    G --> J[_handle_stale_mcp_session]
    J --> K[session_manager.handle_request]

Loading

_{Reviews (1): Last reviewed commit: "fix(mcp): restore PKCE-triggering 401 wh..." | Re-trigger Greptile}

[greptile-apps]

Double DB/cache fetch for stored-token path

When a stored token exists (stored_oauth_headers is truthy and continue is executed), _get_user_oauth_extra_headers_from_db will be invoked a second time during actual request processing at the per-server extra_headers lookup (line ~1315). In the non-test code path this means two round-trips per request, mitigated only by the Redis cache layer. Consider passing the already-fetched stored_oauth_headers value forward (e.g. via a dict keyed by server name) rather than re-fetching it in the downstream path.

This doesn't affect correctness since the Redis cache will serve the second call, but it does add latency when the cache is cold (first request or after eviction).

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!