fix(mcp): discover missing OAuth scopes and token_url when authorization_url is set manually

[tin-berri]

Relevant issues

Follow-up to #33286 (now merged). Originally stacked on that PR's branch; rebased onto litellm_internal_staging after its merge. The first commit widens the discovery gate so a manually pinned authorization_url no longer suppresses discovery of the blank fields. The follow-ups, all from review on this PR (Veria and Bugbot), converge that on one trust rule: when authorization_url is admin-pinned, a discovered metadata document backfills token_url, registration_url, and scopes only if it corroborates the pin, and the same rule governs the last-known-good carry-forward. Provenance is a property of the whole document, not per field

Linear ticket

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

Live proxy on localhost:4010 backed by Postgres. The upstream is the public Linear MCP server (https://mcp.linear.app/mcp), which advertises its OAuth metadata via RFC 9728/8414 discovery, including scopes_supported: ["read", "write"]. The scenario is an oauth2 server whose Authorization URL was typed by hand (the documented workaround when build-time discovery has failed) with Scopes left blank, which the UI labels optional

Before (commit 55a9f1917c, the base of this stack). Create the server and request the authorize redirect:

curl -s -X POST http://localhost:4010/v1/mcp/server \
  -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" \
  -d '{
    "alias": "linear_scopegate",
    "url": "https://mcp.linear.app/mcp",
    "transport": "http",
    "auth_type": "oauth2",
    "oauth2_flow": "authorization_code",
    "authorization_url": "https://mcp.linear.app/authorize"
  }'

curl -si "http://localhost:4010/linear_scopegate/authorize?response_type=code&client_id=demo-client&redirect_uri=http%3A%2F%2Flocalhost%3A8976%2Fcallback&state=demo123" \
  | grep -iE "^HTTP|^location"

HTTP/1.1 307 Temporary Redirect
location: https://mcp.linear.app/authorize?client_id=demo-client&redirect_uri=http%3A%2F%2Flocalhost%3A4010%2Fcallback&state=X_Ttbf15hoD-N1366OEovYLtbvnPylzbJ3Lco6bIZTU&response_type=code

There is no scope parameter in the redirect, and the DB row confirms discovery never ran (token_url empty, credentials {}) even though the upstream advertises everything:

psql litellm_scopegate -c 'SELECT authorization_url, token_url, credentials FROM "LiteLLM_MCPServerTable";'
https://mcp.linear.app/authorize | <null> | {}

IdPs that require scope reject this request outright; Google for example returns 400 "Missing required parameter: scope". The form said Scopes was optional and the flow then deterministically failed without it

After (captured at commit 8375c79b67, which is 66f012a06b after the post-merge rebase; identical diff). Same DB row, no configuration change; restart the proxy so the registry rebuild runs the new gate:

curl -si "http://localhost:4010/linear_scopegate/authorize?response_type=code&client_id=demo-client&redirect_uri=http%3A%2F%2Flocalhost%3A8976%2Fcallback&state=demo123" \
  | grep -iE "^HTTP|^location"

HTTP/1.1 307 Temporary Redirect
location: https://mcp.linear.app/authorize?client_id=demo-client&redirect_uri=http%3A%2F%2Flocalhost%3A4010%2Fcallback&state=tFn-TzmLsTZi0atAaFXy5rS9t4MBgJDPn-DCuGmm0us&response_type=code&scope=read+write

The redirect now carries the discovered scopes, and the row self-heals because the write-back from #33286 persists what discovery found while leaving the hand-typed authorization_url untouched:

psql litellm_scopegate -c 'SELECT authorization_url, token_url, credentials FROM "LiteLLM_MCPServerTable";'
https://mcp.linear.app/authorize | https://mcp.linear.app/token | {"scopes": ["read", "write"]}

This capture reflects the current behavior: the pinned-config scope backfill is resource-driven, so for this upstream the redirect carries the resource-advertised read write

Type

🐛 Bug Fix

Changes

build_mcp_server_from_table skipped upstream OAuth discovery whenever the row already had an authorization_url. One hand-typed field disabled the whole RFC 9728/8414 chain, so token_url and scopes were never backfilled from upstream metadata. The practical failure mode: an admin fills Authorization URL manually (the documented way to un-wedge a server whose build-time discovery failed), leaves Scopes blank because the form labels it optional, and every authorize redirect then goes out without a scope parameter, which strict IdPs hard-fail

The gate now checks whether any of authorization_url, token_url, or scopes is still missing and runs discovery if so. Hand-entered values keep winning on every field because the build merges row values over discovered ones, and the endpoint write-back from #33286 only persists fields the admin left blank. A useful side effect: rows previously wedged in this state self-heal on their next rebuild, since discovery now runs, finds scopes_supported, and persists it

The config.yaml loader already discovers unconditionally for these auth types, so this brings the DB path in line with it. Also removed an unused SimpleNamespace import in the touched test file that ruff flags on changed-file lint

Widening the gate introduces one new hazard, which the second commit closes. Because discovery is rooted at the MCP resource (RFC 9728), a compromised or malicious upstream can advertise its own authorization server. With authorization_url pinned by the admin but token_url left blank, the per-field merge would pair the trusted authorize endpoint with the attacker's token_endpoint: the user signs in at the real IdP, then the gateway posts the authorization code, the stored client secret, and the PKCE verifier to the attacker's token endpoint, and #33286's write-back would persist that endpoint so the compromise outlives the transient upstream state. This is a configuration-time instance of the RFC 9700 authorization-server mix-up

The gate is one predicate applied to the endpoints. _endpoints_corroborate_authorization_url compares a discovered authorization_endpoint against the pinned authorization_url on scheme, host, and path, with default port, query, and trailing slash ignored so hand-copied URLs (case, :443, a ?prompt=consent, a stray slash) still match; a blank pin counts as unpinned, matching the merge's truthiness. When the document corroborates, the gateway adopts its token_url and registration_url; when it does not, those are dropped with a warning and the admin can set Token URL by hand if the mismatch is intentional. When nothing is pinned there is no anchor and discovery is adopted as-is

Scopes are deliberately NOT gated by this predicate. An earlier revision of this PR restricted a pinned server's discovered scopes to the authorization server's own scopes_supported to blunt scope inflation by a compromised resource; that was the wrong layer. Per RFC 8414 §2 the authorization server's scopes_supported is a non-exhaustive capability list (the server MAY omit supported scopes) and is never the scope-selection source, and per the MCP authorization spec Scope Selection Strategy and RFC 9728 §2/§7.2 the scopes a client requests are resource-driven (the WWW-Authenticate challenge scope, else the RFC 9728 protected-resource scopes_supported, requesting the minimum per RFC 9700 §2.3). Scope inflation is bounded by the authorization server and user consent (RFC 6749 §3.3: the server MAY ignore requested scope per policy or the resource owner's instructions) plus downscoping (RFC 8707 §2.2), not by the client restricting the request. So scopes stay resource-driven, the authorization_server_scopes field is removed, and the corroboration gate protects only the endpoints

There are exactly two sources that adopt non-manual OAuth fields: fresh discovery and last-known-good carry-forward. Both go through the one predicate, so the config loader's long-standing unconditional per-field merge and the registry rebuild are covered by the same rule. Carry-forward previously keyed only on the MCP url and auth_type, so re-pointing authorization_url to a different server while the MCP url stayed the same would keep serving the old server's token endpoint and scopes under the new authorize endpoint, a durable mix-up the discovery gate alone could not see because the stale values come from the registry. It now carries the previous token_url/registration_url/scopes only when the previous authorization_url corroborates the authorize endpoint the rebuild will use

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

High Risk
Changes OAuth endpoint/scope resolution and persistence for MCP servers—security-sensitive auth flows (RFC 9700 mix-up, scope inflation) and authorize redirects; behavior shifts for pinned authorize URL with hostile or mismatched discovery.

Overview
OAuth self-heal for partially manual MCP servers now runs upstream discovery when authorization_url, token_url, or scopes are still missing (DB path previously skipped discovery if authorize URL was set). Blank/whitespace OAuth fields are normalized via _blank_to_none so merges and trust checks agree.

Single trust rule (_endpoints_corroborate_authorization_url + _restrict_discovery_to_corroborated_authorization_server): when an admin pins authorization_url, discovered token_url, registration_url, and scopes are applied only if the discovery document’s authorization_endpoint matches the pin (normalized comparison). Uncorroborated metadata is stripped with a warning. Corroborated backfill uses authorization_server_scopes on MCPOAuthMetadata (RFC 8414 scopes_supported) instead of resource-advertised scopes. The same rule applies to carry-forward on registry rebuild so stale token endpoints are not kept after repointing authorize URL.

Config-YAML and DB loaders both gate discovery output before merge/persist; discovery is skipped when all three upstream OAuth fields are already set manually.

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

[greptile-apps]

Greptile Summary

This PR fixes a bug where manually pinning authorization_url on an MCP server suppressed the entire RFC 9728/8414 discovery chain, leaving token_url and scopes empty and causing strict IdPs to reject the authorize redirect. It also closes a security exposure introduced by widening the discovery gate.

• Discovery gate widened (DB path): build_mcp_server_from_table now runs discovery whenever any of authorization_url, token_url, or scopes is still unset; all three fields are normalized through _blank_to_none so whitespace-only values are treated as unpinned.
• Single corroboration rule: when authorization_url is admin-pinned, discovered token_url and registration_url are adopted only if the same discovery document advertises a matching authorization_endpoint; unmatched documents have their endpoints stripped while resource-driven scopes are intentionally kept (bounded by IdP consent).
• Carry-forward gated by the same rule: _carry_forward_resolved_oauth_endpoints now applies the corroboration check so that re-pointing authorization_url to a new server does not silently persist the old server's token endpoint or scopes.

Confidence Score: 5/5

Safe to merge; corroboration gate, carry-forward trust rule, and whitespace normalization are applied consistently across both code paths.

No defects found. The trust rule is applied at both entry points, _blank_to_none eliminates the whitespace split-brain, and the may_carry computation in carry-forward is correctly ordered against the already-resolved new server URL. The asymmetry where discovery scopes pass through uncorroborated documents while carry-forward scopes are gated is deliberate and documented with RFC citations.

No files require special attention.

Important Files Changed

Filename	Overview
litellm/proxy/_experimental/mcp_server/mcp_server_manager.py	Adds _blank_to_none, _normalized_authorize_endpoint, _endpoints_corroborate_authorization_url, and _restrict_discovery_to_corroborated_authorization_server helpers, applied correctly at both DB and YAML build entry points; carry-forward trust gating and the fully-configured skip-discovery optimization are well-placed.
litellm/types/mcp_server/mcp_server_manager.py	Adds a docstring to the scopes field on MCPOAuthMetadata clarifying it is resource-driven; no structural changes.
tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server_manager.py	Adds 7 new test cases covering corroboration, whitespace normalization, carry-forward trust, and skip-discovery; updates test_load_servers_from_config_overrides_discovery_metadata to expect None for uncorroborated endpoints, correctly reflecting the new security behavior.

_{Reviews (8): Last reviewed commit: "fix(mcp): keep scope selection resource-..." | Re-trigger Greptile}

[codecov]

Codecov Report

❌ Patch coverage is 93.61702% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...oxy/_experimental/mcp_server/mcp_server_manager.py	93.47%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!

[veria-ai]

PR overview

This PR updates MCP OAuth handling so that when an authorization URL is configured manually, the server can still discover missing OAuth metadata such as scopes and the token URL. The touched logic is in the MCP server manager’s OAuth discovery and redirect setup path.

One security issue remains open around trusting OAuth scopes discovered from MCP resource challenges or protected-resource metadata. A malicious or compromised resource could cause broader scopes to be persisted and used in the authorization redirect, potentially resulting in a more privileged token if the identity provider grants the request. Two prior issues have already been addressed, so the remaining concern is focused on constraining discovered scopes to administrator-approved values.

Open issues (1)

• Medium: Untrusted OAuth scope expansion — litellm/proxy/_experimental/mcp_server/mcp_server_manager.py:295

Fixed/addressed: 2 · PR risk: 7/10

[tin-berri]

bugbot run

[tin-berri]

@greptileai rerevieww

[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 8375c79. Configure here.}

[tin-berri]

bugbot run

[tin-berri]

@greptileai rereview

[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 66f012a. Configure here.}

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_mcp_field_granular_oauth_discovery (e4a6516) with litellm_internal_staging (ff4a40f)}

[mateo-berri]

High: OAuth endpoint mix-up

When authorization_url is manually configured but another field is absent, discovery is rooted at the MCP resource and its resulting token_url is combined with the manual authorization endpoint. An attacker controlling or compromising that upstream can advertise their own token endpoint; after a user signs in at the trusted authorization endpoint, the gateway posts the authorization code and configured client secret to the attacker's endpoint. Only accept a discovered token endpoint when its metadata matches the manually configured authorization server, or discover the missing fields directly from that configured issuer.

Is this a valid security concern?

[tin-berri]

@greptileai rereview

[tin-berri]

bugbot run

[tin-berri]

@greptileai rereview

[tin-berri]

bugbot run

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

[mateo-berri]

I believe the corroboration gate trusts the document's self-attested authorization_endpoint, so a compromised upstream that simply echoes the pinned URL still smuggles its token_url and scopes through, right?

[tin-berri]

@mateo-berri you're right, and thanks for pushing on it. The corroboration gate reduces this but does not fully close it. It compares the discovered document's authorization_endpoint against the pinned authorization_url, but that document is fetched from an origin the resource chose (its RFC 9728 authorization_servers), so a compromised resource echoes the pinned authorize endpoint while smuggling its own token_endpoint and scopes, and the gate passes. I confirmed with curl that both Slack and Linear serve their own authorization-server metadata from their own domain, so an honest echo and a malicious echo are indistinguishable; corroborating a field inside a resource-served document cannot separate them

The proper close is an admin-configured issuer as the trust anchor (your and Veria's "discover directly from the configured issuer"). I have it up as the stacked follow-up #33450: when an issuer is set, metadata is fetched from the issuer's own origin per RFC 8414 and adopted only when the document self-attests that same issuer (§3.3), so the resource cannot substitute the token endpoint or scopes. It is proven live against a stub compromised resource whose protected-resource-metadata points at an attacker token endpoint. To avoid making admins type it, the issuer is also discovered and persisted trust-on-first-use, with an admin-typed value always winning

On sequencing, two options. I can fold #33450 into this PR so the mix-up is fully closed before this merges, or keep this PR as the scope-discovery plus corroboration change (still a strict improvement, and it closes the honest-mismatch case) and land #33450 immediately behind it. I lean toward folding it in since it is the same threat you flagged; let me know which you prefer

[mateo-berri]

LGTM however:

1. Can we intersect AS scopes with resource scopes? It seems strictly safer and just fall back to the full AS set when the resource advertises none. Or am I misunderstanding something here?
2. It would be great to update the body's "the second commit closes this" claim to "reduces but doesn't close", referencing #33450
3. Can we redo the e2e testing on the latest commit?

Just some nonblocking thoughts

[tin-berri]

Correction on the scope handling, and I want to be explicit because I got it wrong earlier in this thread. When I responded to the mix-up finding I said the fix was to restrict discovered scopes to the authorization server's own scopes_supported. That was wrong. I ran the specs down (RFC 6749/6750/8414/8707/9728/9700, OAuth 2.1 draft, and the MCP authorization spec) and the correct behavior is resource-driven scope selection, not authorization-server-driven

The reasoning, with citations. The authorization server's RFC 8414 scopes_supported is a non-exhaustive capability advertisement ("Servers MAY choose not to advertise some supported scope values", RFC 8414 §2), so it cannot function as a whitelist and was never meant to drive what a client requests. Restricting to it is in fact the exact behavior Spring Security classified as a bug and removed in 5.4.0 (spring-projects/spring-security#8514). The resource-side signals are what drive the request: the RFC 9728 protected-resource scopes_supported ("scope values ... used in authorization requests to request access to this protected resource", §2) and the RFC 6750 §3 WWW-Authenticate challenge scope. The MCP authorization spec's Scope Selection Strategy makes this concrete: use the challenge scope if present, else the RFC 9728 scopes_supported, and it never references the AS list. Scope inflation by a compromised resource is real but is bounded by the authorization server and user consent (RFC 6749 §3.3: the AS "MAY fully or partially ignore the scope requested by the client, based on the authorization server policy or the resource owner's instructions") plus downscoping (RFC 8707 §2.2), not by the client second-guessing the request. RFC 9728 §7.2 also explicitly says the resource's advertised set is not a signal to request all of them, so the client should still request the minimum per RFC 9700 §2.3

So e4a6516b49 reverts the AS-scope restriction here: the corroboration gate now rejects only the uncorroborated token_url/registration_url (the RFC 9700 endpoint mix-up you flagged, @mateo-berri), and leaves scopes as the resource-driven value. The removed authorization_server_scopes field went with it. The endpoint mix-up itself is closed by the issuer anchor in the stacked #33450; that part stands. Net: endpoints are corroborated or issuer-anchored, scopes are resource-driven and the AS plus consent are the inflation backstop

[tin-berri]

bugbot run

[tin-berri]

@greptileai rereview

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

[veria-ai]

Medium: Untrusted OAuth scope expansion

A compromised MCP resource can advertise broader scopes through its challenge or protected-resource metadata. Because these scopes survive the corroboration gate, are persisted, and become the default scope on the authorization redirect, the resource can obtain a more privileged token when the IdP grants the request, including without a new prompt where consent already exists. For a manually pinned authorization server, require administrator-configured scopes or constrain discovered scopes to an explicit administrator-approved allowlist.

[tin-berri]

This is the resource-driven scope selection the MCP authorization spec mandates, so I want to lay out why it is working as specified and where the control you describe already lives, rather than treat it as a defect

Per the MCP authorization spec Scope Selection Strategy, a client requests the scope from the WWW-Authenticate challenge if present, else the RFC 9728 protected-resource scopes_supported, and the spec explicitly directs the client to request that advertised set, delegating least-privilege narrowing to the authorization server and the user at consent because general-purpose MCP clients lack the domain knowledge to curate individual scopes. RFC 9728 §7.2 says the resource's advertised list is not a signal to request all of them and the client SHOULD request the minimum per RFC 9700 §2.3, but neither makes the client the enforcement point. The authorization server's own RFC 8414 scopes_supported is a non-exhaustive capability list (RFC 8414 §2) and is not the selection source, which is why an earlier revision of this PR that restricted discovered scopes to it was reverted; that restriction was the behavior Spring Security classified as a bug and removed in 5.4.0 (spring-projects/spring-security#8514)

The backstop against a compromised resource inflating the request is the authorization server, per RFC 6749 §3.3: it MAY fully or partially ignore the requested scope based on its own policy or the resource owner's instructions, and per RFC 8707 §2.2 it downscopes the issued token to what the target resource can process. So a compromised resource cannot obtain scopes the gateway's registered OAuth client is not permitted, or that the authorization server declines to grant. You are right that this does not force a fresh prompt when existing consent already covers the requested scope; that residual is the spec's accepted tradeoff, and in the pinned and delegate cases the token's audience is the resource itself

The administrator control you ask for is already available and takes precedence. When an admin sets the Scopes field, those scopes win over discovery (the merge is manual-or-discovered) and are never overwritten by the write-back (it is fill-empty-only), so a security-conscious operator can pin exact least-privilege scopes today and discovery will not expand them. What we deliberately do not do is force an administrator allowlist as the default, because that deviates from the spec and breaks the general-purpose MCP client case the spec is built around. A discovered-scope allowlist that discovers and then filters to an approved set is a reasonable defense-in-depth enhancement we could add, but it is not a fix for a spec-conformant default

[veria-ai]

Thanks for the detail. I can't automatically confirm this is safe to dismiss, so I'm leaving the thread open for a maintainer to make the call.