fix(mcp): persist discovered OAuth endpoints and keep last known good on failed re-discovery

[tin-berri]

Relevant issues

Live-diagnosed on a sandbox gateway: interactive MCP OAuth servers intermittently return 400 "MCP server authorization url is not set" from /{server}/authorize with no configuration change, then start working again on their own

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

Setup: local proxy on :4000 backed by Postgres, plus a stub upstream MCP server and OAuth authorization server on one origin (localhost:9321) serving the real RFC 9728 -> RFC 8414 discovery chain (401 with WWW-Authenticate resource_metadata, protected resource metadata, authorization server metadata) with a kill switch that turns every endpoint into a 500 to simulate a transient upstream outage

Repro on unfixed code (staging tip 477ef3a). Create an oauth2 authorization_code server with admin-supplied client credentials and no URLs typed in, so everything depends on discovery

$ curl -sX POST http://localhost:4000/v1/mcp/server -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" \
    -d '{"server_name": "rig_oauth_server", "url": "http://localhost:9321/mcp", "transport": "http",
         "auth_type": "oauth2", "oauth2_flow": "authorization_code",
         "credentials": {"client_id": "my-manual-client", "client_secret": "my-manual-secret"}}'

# the row never stores the discovered endpoints
$ docker exec pg psql -U postgres -tc 'SELECT server_name, authorization_url, token_url FROM "LiteLLM_MCPServerTable";'
 rig_oauth_server |                   |

# in-memory discovery worked, so authorize redirects to the real IdP
$ curl -s -o /dev/null -w "%{http_code} -> %{redirect_url}\n" "http://localhost:4000/rig_oauth_server/authorize?redirect_uri=http%3A%2F%2Flocalhost%3A8945%2Fcallback&client_id=test-client&state=abc123"
307 -> http://localhost:9321/idp/authorize?client_id=my-manual-client&...&scope=mcp.read+mcp.write

# simulate a transient upstream outage, then any row write (a no-op admin edit here) forces a rebuild
$ touch rig_down
$ curl -sX PUT http://localhost:4000/v1/mcp/server -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" -d '{"server_id": "67ffbbe4-...", "description": "noop touch"}' -o /dev/null -w "edit: %{http_code}\n"
edit: 202

$ curl -s -w "\nHTTP %{http_code}\n" "http://localhost:4000/rig_oauth_server/authorize?redirect_uri=http%3A%2F%2Flocalhost%3A8945%2Fcallback&client_id=test-client&state=abc123"
{"detail":"MCP server authorization url is not set"}
HTTP 400

# upstream comes back, another no-op edit, and it works again with zero configuration change
$ rm rig_down && curl -sX PUT ... -d '{"server_id": "67ffbbe4-...", "description": "noop touch 2"}' && curl -s -o /dev/null -w "%{http_code} -> %{redirect_url}\n" ".../rig_oauth_server/authorize?..."
307 -> http://localhost:9321/idp/authorize?client_id=my-manual-client&...

# the only trace of the outage was at DEBUG level
[92m14:51:05 - LiteLLM:DEBUG[0m: mcp_server_manager.py:3126 - Failed to fetch authorization metadata from http://localhost:9321/...: Server error '500 Internal Server Error' ...

Verify on fixed code. Restarting the proxy backfills the same pre-existing row on the first successful rebuild

$ docker exec pg psql -U postgres -tc "SELECT authorization_url, token_url, updated_by FROM \"LiteLLM_MCPServerTable\" WHERE server_name='rig_oauth_server';"
 http://localhost:9321/idp/authorize | http://localhost:9321/idp/token | mcp_oauth_discovery

# scopes merged into the credentials blob, stored client credentials untouched
credentials keys: ['client_id', 'client_secret', 'scopes'] | scopes: ['mcp.read', 'mcp.write']

# the exact repro sequence (outage + no-op edit + rebuild) now keeps working
$ touch rig_down && curl -sX PUT ... -d '{"server_id": "67ffbbe4-...", "description": "noop touch 3"}'
$ curl -s -o /dev/null -w "%{http_code} -> %{redirect_url}\n" ".../rig_oauth_server/authorize?..."
307 -> http://localhost:9321/idp/authorize?client_id=my-manual-client&...&scope=mcp.read+mcp.write

Origin-fallback and last-known-good, on a second server where the stub advertises no protected resource metadata so discovery only succeeds by guessing the origin as the authorization server

# authorize works off the in-memory guess
$ curl -s -o /dev/null -w "%{http_code} -> %{redirect_url}\n" ".../rig_fallback_server/authorize?..."
307 -> http://localhost:9321/idp/authorize?client_id=fb-client&...

# but the guessed endpoints are never persisted as configuration
$ docker exec pg psql -U postgres -tc "SELECT COALESCE(authorization_url,'NULL'), COALESCE(token_url,'NULL') FROM \"LiteLLM_MCPServerTable\" WHERE server_name='rig_fallback_server';"
 NULL     | NULL

# full outage plus a rebuild: the last known good endpoints carry forward instead of downgrading to None
$ touch rig_down && curl -sX PUT ... -d '{"server_id": "c4edcdc4-...", "description": "noop"}'
$ curl -s -o /dev/null -w "%{http_code} -> %{redirect_url}\n" ".../rig_fallback_server/authorize?..."
307 -> http://localhost:9321/idp/authorize?client_id=fb-client&...

# and the failure is now visible
[92m15:05:37 - LiteLLM:WARNING[0m: mcp_server_manager.py:1464 - MCP OAuth discovery yielded no metadata for server c4edcdc4-... (http://localhost:9321/mcp); OAuth endpoints stay unresolved until a rebuild succeeds

Type

🐛 Bug Fix

Changes

MCP servers with auth_type oauth2, true_passthrough, or oauth_delegate resolve their upstream OAuth endpoints (authorization_url, token_url, scopes) through RFC 9728 -> RFC 8414 discovery at registry build time, but the resolved values only ever lived on the in-memory registry entry; the DB row keeps NULL. That entry is rebuilt far more often than it looks: every /register that reuses a persisted DCR client calls update_server, and any row write bumps updated_at, which defeats the reuse cache in reload_servers_from_database (the 30s scheduler job), so each rebuild re-runs discovery over the network. A rebuild whose discovery attempt fails (timeout, upstream blip, rate limiting) replaces a working authorization_url with None, and every /{server}/authorize returns 400 "MCP server authorization url is not set" until a later rebuild happens to succeed. With multiple pods each rolling their own discovery, the same server works or 400s depending on which pod serves the request. Failures were logged at DEBUG, so the flapping looked random

build_mcp_server_from_table now writes discovered authorization_url, token_url, and scopes back onto the row after a successful discovery, extending the existing _persist_discovered_obo_token_url precedent (whose docstring describes this exact failure mode for the token-exchange arm) to the interactive oauth2 family. It only fills row fields that are currently empty so admin-typed values always win, goes through update_mcp_server so scopes merge into the credentials blob without touching the stored client credentials, never persists origin-fallback guesses (RFC 9728/8414-advertised metadata only, tracked by a new from_origin_fallback flag on MCPOAuthMetadata), and deliberately skips registration_url because _dcr_bridge_relays_client_registration keys off that column. Once the row has authorization_url, needs_discovery is False and rebuilds stop hitting the network entirely; rows that predate the fix backfill automatically on their first successful rebuild after deploy

The DCR registration persist deliberately does not write authorization_url (a regression test asserts it stays absent from the persist payload): the build-path hook is the single authorization_url writer, so the origin-fallback guard cannot be bypassed. The old asymmetry (token_url persisted while authorization_url never was, both values from the same authorization server metadata document) produced the diagnostic signature of this bug, /token working while /authorize 400d, and is closed by the build-path hook

A rebuild whose re-discovery returns nothing carries forward the previous registry entry's resolved endpoints and scopes, mirroring the existing short_prefix carry-forward and skipped when url or auth_type changed. This protects rows that predate the fix and is the standard stale-on-failure behavior for OAuth metadata (compare Microsoft.IdentityModel's ConfigurationManager, which keeps the last known good configuration when a metadata refresh fails)

The temporary session endpoint (POST /server/oauth/session) builds registry entries whose server_id has no DB row; it now passes persist_discovered_endpoints=False so neither this write-back nor the OBO one attempts a write for it. Discovery that yields no metadata now logs at WARNING with the server id

QA runbook

Create an oauth2 authorization_code MCP server with your own client_id/client_secret and leave Authorization URL, Token URL, and Scopes blank. After the server loads, check the DB row: authorization_url and token_url columns should be populated and updated_by should read mcp_oauth_discovery, with scopes inside the credentials JSON. Take the upstream IdP offline (or block egress), edit the server description to force a rebuild, and confirm /{server}/authorize still 307-redirects to the upstream authorize URL instead of returning 400. Confirm an admin-typed Authorization URL is never overwritten by discovery. For the guess guard, point a server at an upstream that serves authorization server metadata at its origin but no protected resource metadata, and confirm the row's URL columns stay NULL while /authorize still works

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
Touches interactive OAuth authorize flows and DB writes for MCP server rows; guards limit overwrites and skip temporary servers, but mis-persisted endpoints could still affect multi-pod behavior until corrected.

Overview
Fixes intermittent 400 "MCP server authorization url is not set" on /{server}/authorize when registry rebuilds re-run OAuth discovery and a transient failure clears in-memory endpoints that were never stored on the DB row.

Persist discovery: After a successful RFC 9728/8414 discovery in build_mcp_server_from_table, empty row fields get authorization_url, token_url, and scopes (via update_mcp_server, touched_by=mcp_oauth_discovery). Only empty fields are filled; registration_url is never persisted; metadata tagged from_origin_fallback is excluded from writes. persist_discovered_endpoints=False skips DB writes for temporary session servers.

Resilience: _carry_forward_resolved_oauth_endpoints copies the previous registry entry’s OAuth URLs/scopes when re-discovery returns nothing (unless url/auth_type changed). Failed discovery logs at WARNING.

MCPOAuthMetadata.from_origin_fallback marks origin-guess discovery so it stays in-memory only.

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

[greptile-apps]

Greptile Summary

This PR fixes intermittent 400 "MCP server authorization url is not set" responses from /{server}/authorize caused by in-memory-only OAuth endpoint discovery: every registry rebuild re-ran network discovery, and a transient failure cleared the in-memory endpoints that were never stored in the DB row, leaving authorization_url = NULL until a later rebuild succeeded.

• Persistence layer: build_mcp_server_from_table now calls _persist_discovered_oauth_endpoints after successful RFC 9728/8414 discovery, writing authorization_url, token_url, and scopes into empty DB row fields through the existing update_mcp_server credential-merge path. Origin-fallback guesses (flagged via from_origin_fallback on MCPOAuthMetadata) are excluded from persistence. Temporary session servers (no DB row) pass persist_discovered_endpoints=False.
• Resilience layer: _carry_forward_resolved_oauth_endpoints copies the previous registry entry's resolved OAuth endpoints and scopes into a newly rebuilt server when re-discovery yields nothing, unless url or auth_type changed. This prevents a transient outage during rebuild from degrading an in-memory working server to a broken one.
• Test coverage: Five new focused unit tests cover persistence, persistence guards, partial-field updates, temporary-server opt-out, and carry-forward behavior, including the carry-forward skip when URL or auth_type changes.

Confidence Score: 5/5

Safe to merge. The change is tightly scoped: it adds DB write-back for discovered OAuth endpoints (guarded by empty-field checks and the from_origin_fallback flag) and carry-forward resilience when re-discovery fails. Both paths leave admin-typed values untouched.

The persistence guard (existing_authorization_url check) ensures admin-typed values always win. The credential merge in update_mcp_server preserves client_id/client_secret when only scopes are written. The carry-forward correctly skips when url or auth_type changed. Origin-fallback metadata is explicitly flagged and excluded from persistence. persist_discovered_endpoints=False correctly gates the temporary-session path. Previously flagged concerns (carry-forward vs persist asymmetry undocumented; potential double WARNING) are both addressed — the docstring now explicitly explains the intentional asymmetry, and the exception path logs at DEBUG leaving only one WARNING for the discovery-returned-None case.

No files require special attention. All five changed files have clear, correct logic and matching test coverage.

Important Files Changed

Filename	Overview
litellm/proxy/_experimental/mcp_server/mcp_server_manager.py	Adds _carry_forward_resolved_oauth_endpoints, _persist_discovered_oauth_endpoints, and a WARNING log for failed discovery; guards both persistence paths behind persist_discovered_endpoints; applies carry-forward in both update_server and reload_servers_from_database. Logic is sound: carry-forward is skipped when URL or auth_type change, persistence only fills empty fields, and origin-fallback metadata is excluded.
litellm/types/mcp_server/mcp_server_manager.py	Adds from_origin_fallback: bool = False to MCPOAuthMetadata with a clear docstring explaining why guessed endpoints must not be persisted. Clean, minimal change.
litellm/proxy/management_endpoints/mcp_management_endpoints.py	Single one-line addition of persist_discovered_endpoints=False for the temporary session server path; correctly prevents write-back for ephemeral server records that have no DB row.
tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py	Adds assertion that authorization_url is absent from fields_set() in the DCR registration persist call, ensuring the build-path hook remains the sole writer of authorization_url.
tests/test_litellm/proxy/_experimental/mcp_server/test_mcp_server_manager.py	Replaces SimpleNamespace with typed MCPOAuthMetadata in one existing test; adds five new well-structured unit tests for persistence, guards, partial-field updates, temporary-server opt-out, and carry-forward edge cases. Tests check the right things and no coverage is weakened.

_{Reviews (5): Last reviewed commit: "fix(mcp): do not persist authorization_u..." | Re-trigger Greptile}

[tin-berri]

@greptileai

[veria-ai]

PR overview

All previously flagged issues have been addressed. No open security concerns remain on this pull request.

Security review

No open security issues remain on this pull request.

Fixed/addressed: 1 · PR risk: 0/10

[codspeed-hq]

Merging this PR will not alter performance

✅ 31 untouched benchmarks

---

_{Comparing litellm_mcp_oauth_discovery_persist (a0d5df2) with litellm_internal_staging (65ca095)}

[tin-berri]

@greptileai rereview

[tin-berri]

bugbot run

[codecov]

Codecov Report

❌ Patch coverage is 95.74468% with 2 lines in your changes missing coverage. Please review.

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

📢 Thoughts on this report? Let us know!

[tin-berri]

Both Bugbot findings reviewed

Finding 1 (DCR persists origin-fallback URLs) is correct and is fixed in a0d5df2 by removing the authorization_url write from _persist_dcr_client_registration. By the time that persist runs, the build-path hook has already written any RFC 9728/8414-advertised authorization_url to the row under the provenance guard, so the DCR-path copy was redundant in the advertised case and was the only writer precisely when the value came from the origin-fallback guess. The regression test now asserts authorization_url is absent from the DCR persist payload

Finding 2 (carry-forward revives cleared endpoints) is intended stale-while-revalidate behavior. Clearing the columns still forces re-discovery on every rebuild because needs_discovery keys off the row, which stays cleared; the carry-forward only bridges rebuilds whose re-discovery failed, lives in memory only, and the next successful discovery overwrites it and persists fresh values. Honoring the clear immediately during an upstream outage would serve 400 "authorization url is not set", which is the exact failure this PR removes. When old endpoints must go away immediately there are three paths the carry never crosses: changing url or auth_type, typing an explicit replacement (explicit values always win), or restarting (memory resets and the cleared row is honored from scratch). This mirrors how Microsoft.IdentityModel's ConfigurationManager keeps last known good metadata when a refresh fails

[tin-berri]

@greptileai

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

[mateo-berri]

LGTM; thanks!