docs(mcp): document passthrough auth modes, multi-server token isolation, and audience-lock steering

[devin-ai-integration]

Summary

Extends docs/mcp_oauth_passthrough.md so an operator can pick between true_passthrough, oauth_delegate and oauth2_token_exchange from the token they actually hold, and understand why a passthrough token minted for another resource is rejected upstream by design

New sections, each checked against litellm/proxy/_experimental/mcp_server/ on litellm_internal_staging:

"Audience-locked tokens: passthrough or token exchange" states that both passthrough modes forward the bearer verbatim (no decode, no audience/scope check, no exchange), so an upstream 401 for a token audienced to a different resource is the confused-deputy-safe outcome and the fix is oauth2_token_exchange (OBO re-mints an upstream-audienced token), never a widened audience. A three-row table maps "token minted for X" to the mode to use

"Multi-server aggregate requests" documents x-mcp-{alias}-authorization (alias sanitized per sanitize_mcp_alias_for_header: lowercase, non [a-z0-9_] becomes _) and the fan-out rule from _prepare_mcp_server_headers / _caller_authorization_fans_out: the request-wide Authorization is withheld from a client-forwarded server during tools/list, prompts and resources listings when another server in the same scope would also consume it, while per-server headers and explicitly addressed operations (tools/call, /{server_name}/mcp) still get it. Includes a curl for an aggregate tools/list with two per-server tokens

"Previewing tools in the Admin UI" describes the browser-only "Authorize & Fetch Tools" button (PassthroughAuthorizeSection.tsx): the upstream token stays in the browser session and is never written to the server row or credential store, while the optional OAuth Client ID/Secret are persisted config

"Intentional limits" covers the absent per-server re-auth signal on the aggregate (a failing server is absorbed into an empty listing), sender-constrained DPoP/mTLS tokens not being relayable at L7, and revocation not being checked at connect time

Also documents allowed_tools for true_passthrough as the only tool restriction (server-level, identical for every caller, since there is no per-key identity)

Linear ticket

Resolves LIT-4301

Screenshots / Proof of Fix

npm run build completed with [SUCCESS] Generated static files in "build" at 883eaa3, no broken links or MDX errors for this page

Rendered at /docs/mcp_oauth_passthrough from the local build:

Link to Devin session: https://app.devin.ai/sessions/c3f6277efdd24ead9ab000396f51a5ec
Open in Devin Desktop: https://app.devin.ai/desktop/session/c3f6277efdd24ead9ab000396f51a5ec?variant=devin
Requested by: @yassin-berriai

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
litellm	Ready	Preview	Sep 4, 2026 9:05am UTC