feat(mcp): interactive SSO sign-in for dcr_bridge oauth_delegate DCR clients

[tin-berri]

Relevant issues

Linear ticket

Part of LIT-4338 (the interactive producer/flow, PR stack step G) under LIT-4262

Pre-Submission checklist

• 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

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

This completes the oauth_delegate bridge for real DCR clients, so it is inert until stacked on the consumer (#32824) and producer (#32828). The end-to-end contract is pinned by unit tests driving authorize, callback, and the token endpoint with a real gateway-sealed code, then opening the minted envelope through the consumer's resolver. The full interactive proof against a live proxy with a stub IdP and a real DCR client (MCP Inspector / Claude Code) completing sign-in is the remaining acceptance step, to run once the stack lands

Type

🆕 New Feature

Changes

This is the last piece of the oauth_delegate dcr_bridge stack, the interactive sign-in that lets a real DCR client (Claude Code, Claude Desktop) connect. Those clients send no litellm key and cannot use the scripted two-header path, so their litellm identity has to be captured server-side during the browser authorize step and carried to the back-channel token call

The first commit generalizes the envelope identity. The scripted client mints under a virtual key it presents at the token endpoint, but the interactive client authenticates via SSO, which yields a user, not a key. EnvelopeIdentity becomes a discriminated subject (subject_type key_hash or user_id) with key_hash_identity / user_identity constructors, and admission dispatches on it: a key_hash reloads the key, a user_id reloads the user and admits them as themselves. A user belongs to many teams or none, so no team is bound; the user's own budget and SCIM state are enforced through the same centralized policy gate the key path uses, and a missing or SCIM-deactivated user fails closed. This is faithful to how the identity was actually established, an SSO login produces a user subject, and it is the model the aggregate authorization_code flow (LIT-3637) reuses

The second commit wires the flow on the short-circuit bridge arm, where the gateway runs /authorize, /callback, and /token in the loop. At /authorize the gateway reads the SSO user from the browser's UI session cookie (reusing the BYOK session helper) and seals it, plus the target server, into the encrypted OAuth state; without a session there is nothing to bind, so the browser is sent through login first. At /callback, instead of forwarding the raw upstream code, the gateway seals the user and the upstream code into a gateway authorization code (encrypted with the same authenticated helper the state uses, server-bound so it cannot be replayed across servers) and forwards that. At /token the gateway recovers the user and the real upstream code from the gateway code, exchanges the upstream code, and mints a user-subject envelope. Nothing is stored server-side; the identity captured in the browser rides the client-held code to the token call. The scripted key_hash path is untouched, a raw upstream code opens to None and falls through to it

Everything is gated on is_dcr_bridge and is_oauth_delegate, so flag-off and every other auth mode are byte-identical. Tests cover the identity generalization and its admission (both subject variants, with the user path enforced through the centralized gate and failing closed on a missing or deactivated user), the gateway-code round-trip and its server binding, the authorize-time capture and the login redirect when no session is present, the callback sealing the user into the code, and the token endpoint minting a user-subject envelope that opens back to that user while exchanging the recovered upstream code

The relay bridge arm (client registered directly with the upstream, authorize and callback bypass the gateway) cannot capture identity gateway-side, so interactive user-subject minting is scoped to the short-circuit arm (admin-configured OAuth client), which is the primary dcr_bridge configuration; the seamless post-login return-to round-trip, which is origin-validated against the control-plane URL, is a follow-up

---

Note

High Risk
Changes OAuth/MCP authentication, envelope identity, and admission error mapping in security-sensitive paths; misclassification could admit wrong principals or turn outages into 401s.

Overview
Enables real DCR clients (no LiteLLM API key) to complete dcr_bridge oauth_delegate by binding gateway envelopes to the SSO user captured in the browser, not only to a virtual key presented at the token endpoint.

Envelope identity is generalized: JWT claims and EnvelopeIdentity use subject_type (key_hash | user_id) plus subject, with key_hash_identity / user_identity helpers. Bridge minting picks the subject from either a presented key or a recovered gateway authorization code. Admission reloads via _reload_admitted_principal—keys through the existing key path, users through new _reload_admitted_user (user record, MCP object permission, SCIM fail-closed, same policy gate).

Interactive flow on the short-circuit bridge arm: /authorize reads the UI session user into encrypted OAuth state (login redirect if missing); /callback replaces the raw upstream code with an encrypted llm_bcode_ gateway code (user + server + upstream code); /token opens that code, exchanges the inner upstream code, and mints a user_id envelope. Server binding on the gateway code blocks cross-server replay.

DB outage handling for user reload uses is_database_service_unavailable_error_in_chain so get_user_object's ValueError wrapping still yields 503 vs 401 for missing users.

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

Follow-up: DB-outage classification hardening

A later review pass flagged the user-subject reload's error handling, and the root cause was that get_user_object catches every DB failure and re-raises a bare ValueError, so a real outage and a missing user are indistinguishable by type and the original error survives only as context. The admission path keyed its 503-vs-401 decision on the exception type, so a transient outage during a user reload surfaced as a 401 rather than a retryable 503, and the object_permission load sat outside the classified boundary. The regression test made it worse by injecting a raw ConnectionError, a shape get_user_object never produces, so it passed on a fiction

The fix adds PrismaDBExceptionHandler.is_database_service_unavailable_error_in_chain, which walks the cause/context chain (bounded and cycle-safe) the PEP 3134 way, routes the admission path through it, and moves the object_permission resolution inside the single classified try so an outage there is a 503 too. A contract test now drives the real get_user_object to pin its wrapping, and the reload tests use that same faithful shape, verified by mutation testing so a chain-blind regression fails them

[codecov]

Codecov Report

❌ Patch coverage is 92.59259% with 8 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...erimental/mcp_server/auth/user_api_key_auth_mcp.py	81.81%	6 Missing ⚠️
..._experimental/mcp_server/discoverable_endpoints.py	96.29%	2 Missing ⚠️

📢 Thoughts on this report? Let us know!

[tin-berri]

@greptileai review

[tin-berri]

bugbot run

[greptile-apps]

Greptile Summary

This PR completes the interactive SSO sign-in path for dcr_bridge oauth_delegate DCR clients (Claude Code, Claude Desktop), which present no LiteLLM API key and thus cannot use the existing scripted two-header path. It also hardens DB-outage classification for the user reload path added in the same stack.

• Envelope identity generalised – EnvelopeIdentity replaces the key_hash field with subject_type (\"key_hash\" | \"user_id\") + subject, and _reload_admitted_principal dispatches to the existing _reload_admitted_key or the new _reload_admitted_user depending on the sealed type.
• Short-circuit bridge flow wired – At /authorize, the SSO user is captured from the browser session and sealed (along with mcp_server_id) into the encrypted OAuth state; a missing session redirects to login. At /callback, a sealed gateway authorization code (llm_bcode_ prefix, server-bound) replaces the raw upstream code. At /token, the gateway code is opened to recover the user and the real upstream code, exchanges the latter with the upstream, and mints a user-subject envelope.
• DB-outage hardening – is_database_service_unavailable_error_in_chain walks the __cause__/__context__ chain so that get_user_object's pattern of wrapping every DB error in a bare ValueError does not mask a real outage as a 401; a contract test pins that wrapping behaviour in auth_checks.

Confidence Score: 5/5

The change is safe to merge: the new SSO identity path is fully gated behind is_dcr_bridge and is_oauth_delegate, relay bridges return before the session gate, and the gateway code is server-bound encrypted so it cannot be replayed across servers or forged by clients.

The envelope identity generalisation, user reload path, and gateway authorization code flow are all correct. The DB-outage classification follow-up correctly walks the cause/context chain and is independently pinned by a contract test on get_user_object. Test coverage is thorough across both subject types, missing-user 401, outage 503, SCIM deactivation, server-binding rejection, authorize session capture, login redirect, and callback sealing. No existing tests were weakened.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/proxy/_experimental/mcp_server/outbound_credentials/envelope.py	Envelope identity generalised from key_hash to subject_type+subject; constructor helpers key_hash_identity/user_identity added; JWT claims and open_envelope updated correctly.
litellm/proxy/_experimental/mcp_server/auth/user_api_key_auth_mcp.py	_reload_admitted_principal dispatch added; _reload_admitted_user handles SCIM gate and get_object_permission inside the same try boundary with chain-aware 503 classifier.
litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py	Gateway authorization code (seal/open, server binding) and SSO capture at authorize added; relay bridge returns early before the session gate.
litellm/proxy/db/exception_handler.py	is_database_service_unavailable_error_in_chain added: depth-bounded, cycle-safe chain walk.
tests/test_litellm/proxy/_experimental/mcp_server/auth/test_user_api_key_auth_mcp.py	New tests for user-subject admission including missing-user 401, DB-outage 503, and SCIM-deactivated 401.
tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py	New tests cover gateway code round-trip, server-binding rejection, interactive token exchange, authorize SSO capture, login redirect, and callback sealing.
tests/test_litellm/proxy/auth/test_auth_checks.py	Contract test pins get_user_object's exception-wrapping behaviour that the chain-aware classifier relies on.
tests/test_litellm/proxy/db/test_exception_handler.py	Tests for is_database_service_unavailable_error_in_chain: wrapping visibility, cycle termination, and parity.
tests/test_litellm/proxy/_experimental/mcp_server/outbound_credentials/test_envelope.py	Envelope tests updated for subject_type/subject wire format; user_identity round-trip test added.
tests/test_litellm/proxy/_experimental/mcp_server/outbound_credentials/test_bridge_credentials.py	Migrated from EnvelopeIdentity(key_hash=...) to key_hash_identity constructor.

_{Reviews (4): Last reviewed commit: "fix(mcp): classify get_user_object's wra..." | Re-trigger Greptile}

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_lit4338_delegate_flow (61c7e70) with litellm_internal_staging (fa09cde)}

[tin-berri]

Addressed the review findings on the user-subject reload at the root rather than one at a time, since they were all symptoms of _reload_admitted_user being an incomplete mirror of _reload_admitted_key

Error classification (Greptile P1 + Bugbot): the user reload now has the same except-Exception arm the key path uses, so a transient DB outage surfaces as a retryable 503 via _raise_503_if_db_unavailable. The missing-user case needed one deliberate difference from the key path: get_user_object raises a bare Exception for a deleted user (not a ProxyException like get_key_object does for a missing key), so the reload catches it and fails closed as a 401 rather than letting it propagate as an opaque 500. The regression tests now drive the real behavior (get_user_object raising) instead of a None return that never happens in production, covering both the 503 outage and the 401 missing-user paths

Allowlist (Bugbot High, user gets no tools): the reload now resolves the user's own MCP object permission onto the returned auth, so the same get_allowed_mcp_servers the key path uses grants the user their litellm-granted servers and access groups. This reuses get_object_permission (the id-to-grants resolver keys and teams already use); no permission logic is duplicated. One scoped limitation stated in the code and commit: a UserAPIKeyAuth carries a single team_id while a user may belong to many teams, so team-inherited MCP grants for a user are a follow-up (they need a many-teams union get_allowed_mcp_servers does not do off one auth object), not something faked here

@greptileai

[greptile-apps]

Both fix commits look correct. Here's the assessment:

f96899ae — 503/401 error classification

The fix adds the same except Exception as e arm that the key path uses, wires it through _raise_503_if_db_unavailable, and re-raises on outage. The deliberate difference from the key path is justified: get_user_object raises a bare Exception for a deleted user (not a ProxyException), so the broad except Exception block translates that to a fail-closed 401 before the outage check, rather than the user_object is None branch that was unreachable in production. The test update driving get_user_object to raise (rather than returning None) is the right regression fix — it tests the actual production code path.

c46863b0 — MCP object permission

Resolving object_permission from object_permission_id via the existing get_object_permission helper and mounting it onto the returned UserAPIKeyAuth is the correct fix — it's the same resolver the key and team paths use, and no permission logic is duplicated. The acknowledged limitation (team-inherited grants require a many-teams union that a single team_id on UserAPIKeyAuth can't express) is the right call: stating it in the code and deferring it rather than approximating it with a half-measure.

Both issues are fully addressed. The implementation is solid.

[tin-berri]

@greptileai rereview

[tin-berri]

bugbot run

[tin-berri]

@greptileai rereview

[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 61c7e70. Configure here.}

[mateo-berri]

LGTM; thanks!