fix(mcp): resolve OAuth2 root endpoints returning "MCP server not found"

[michelligabriele]

When MCP SDK hits root-level /register, /authorize, /token without server name prefix, auto-resolve to the single configured OAuth2 server. Also fix WWW-Authenticate header to use correct public URL behind reverse proxy.

Relevant issues

Follow-up to #20602 — separate bug reported by the same user.

Pre-Submission checklist

• I have Added testing in the tests/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

Problem

After connecting an MCP client to a LiteLLM proxy behind a reverse proxy (e.g. https://llm.example.com/mcp), the OAuth2 flow fails with {"detail":"MCP server not found"} at the /authorize endpoint. The customer's URL showed: /authorize?client_id=dummy_client — the MCP SDK was hitting root-level OAuth endpoints without the server name prefix.

Root Cause (3 issues chained together)

1. server.py — WWW-Authenticate header used str(request.base_url) (internal URL like http://0.0.0.0:4000) instead of get_request_base_url(request) (public URL). Behind a reverse proxy, the MCP SDK can't follow the internal URL and falls back to root-level OAuth discovery.

2. discoverable_endpoints.py /register — Root /register (no server name prefix) immediately returned client_id: "dummy_client" without trying to resolve the actual server.

3. discoverable_endpoints.py /authorize — lookup_name = mcp_server_name or client_id resolved to "dummy_client" which doesn't match any configured server → 404.

Fix

• Added _resolve_oauth2_server_for_root_endpoints() helper that auto-resolves to the single configured OAuth2 server when root-level endpoints are hit without a server name prefix. Returns None when 0 or 2+ OAuth2 servers exist (ambiguous case).
• Applied the resolver to /register, /authorize, /token endpoints and both _build_oauth_authorization_server_response() and _build_oauth_protected_resource_response().
• Fixed WWW-Authenticate header in server.py to use get_request_base_url(request) for correct public URL behind reverse proxy.

E2E Verification (via ngrok → LiteLLM proxy → Atlassian MCP)

• Test 1: Root discovery (/.well-known/oauth-authorization-server) now returns endpoints with /atlassian_mcp/ prefix
• Test 2: Root /register returns client_id: "atlassian_mcp" instead of "dummy_client"
• Test 3: Root /authorize?client_id=dummy_client returns 307 redirect to Atlassian instead of 404

Tests added

5 new tests in tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py:

• test_authorize_root_resolves_single_oauth2_server
• test_authorize_root_fails_with_multiple_oauth2_servers
• test_token_root_resolves_single_oauth2_server
• test_register_root_resolves_single_oauth2_server
• test_discovery_root_includes_server_name_prefix

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview, Comment	Feb 9, 2026 9:58pm

[greptile-apps]

Greptile Overview

Greptile Summary

Fixed OAuth2 flow failing with "MCP server not found" when MCP SDK hits root-level endpoints (/register, /authorize, /token) without server name prefix. Added _resolve_oauth2_server_for_root_endpoints() helper that auto-resolves to the single configured OAuth2 server when exactly 1 exists. Also fixed WWW-Authenticate header in server.py to use public URL (get_request_base_url()) instead of internal URL (str(request.base_url)) for correct reverse proxy support.

Key changes:

• Added resolver applied to /register, /authorize, /token endpoints and both discovery response builders
• Fixed 3 chained issues: incorrect WWW-Authenticate URL, root /register returning "dummy_client", and /authorize lookup failing on "dummy_client"
• Added 5 comprehensive tests covering single-server resolution, multi-server ambiguity, and discovery endpoint behavior
• Fixed 2 existing tests to clear registry and prevent resolver interference

Confidence Score: 5/5

• This PR is safe to merge with minimal risk
• The fix is well-scoped, addresses a specific bug with clear root cause analysis, includes comprehensive test coverage (5 new tests), and only touches MCP OAuth flow code without affecting critical request paths. The resolver logic is defensive (returns None when ambiguous) and all changes are backwards-compatible.
• No files require special attention

Important Files Changed

Filename	Overview
litellm/proxy/_experimental/mcp_server/discoverable_endpoints.py	Added _resolve_oauth2_server_for_root_endpoints() helper to auto-resolve single OAuth2 server for root endpoints; applied resolver to /register, /authorize, /token and discovery endpoints
litellm/proxy/_experimental/mcp_server/server.py	Fixed WWW-Authenticate header to use get_request_base_url() instead of str(request.base_url) for correct public URL behind reverse proxy
tests/test_litellm/proxy/_experimental/mcp_server/test_discoverable_endpoints.py	Added 5 new tests for root-level OAuth endpoint resolution; cleared global registry in existing tests to prevent resolver interference

Sequence Diagram

sequenceDiagram
    participant Client as MCP SDK Client
    participant Proxy as LiteLLM Proxy
    participant Resolver as _resolve_oauth2_server_for_root_endpoints()
    participant Provider as OAuth2 Provider

    Note over Client,Proxy: Root-level OAuth flow (no server name prefix)
    
    Client->>Proxy: GET /.well-known/oauth-authorization-server
    Proxy->>Resolver: Check for single OAuth2 server
    Resolver-->>Proxy: Return server (if exactly 1 exists)
    Proxy-->>Client: Return endpoints with /server_name/ prefix
    
    Client->>Proxy: POST /register (no server name)
    Proxy->>Resolver: Check for single OAuth2 server
    Resolver-->>Proxy: Return resolved server
    Proxy-->>Client: Return client_id: "server_name"
    
    Client->>Proxy: GET /authorize?client_id=dummy_client
    Proxy->>Resolver: Check for single OAuth2 server
    Resolver-->>Proxy: Return resolved server
    Proxy->>Provider: Redirect with actual client_id
    Provider-->>Client: 307 Redirect to OAuth provider
    
    Client->>Provider: User authorizes
    Provider-->>Proxy: Callback with auth code
    Proxy-->>Client: 302 Redirect with code
    
    Client->>Proxy: POST /token (no server name)
    Proxy->>Resolver: Check for single OAuth2 server
    Resolver-->>Proxy: Return resolved server
    Proxy->>Provider: Exchange code for token
    Provider-->>Proxy: Return access_token
    Proxy-->>Client: Return access_token

Loading

[greptile-apps]

_{3 files reviewed, no comments}

_{Edit Code Review Agent Settings | Greptile}

[ishaan-jaff]

lgtm

[hossainbuet]

@michelligabriele thanks for this. I believe this will fix my issue, can you please confirm ? cc: @jquinter
#19977