Fix OAuth discovery fallback and URL ordering

This commit addresses two related OAuth discovery issues:

1. Enable fallback to March 2025 spec for legacy servers (issue #1495)
   - Remove exception when PRM discovery fails completely
   - Fall back to root-level OAuth discovery for backward compatibility
   - When PRM unavailable, only check /.well-known/oauth-authorization-server
   - Maintains compatibility with legacy servers like Linear and Atlassian

2. Fix OAuth discovery URL ordering (issue #1623)
   - Only check path-based URLs when auth server URL contains a path
   - Prevents incorrectly discovering root AS when tenant-specific AS exists
   - Follows RFC 8414 priority: path-aware OAuth, then path-aware OIDC, then root
   - Fixes issue where root URLs were tried before path-based OIDC URLs

Changes:
- Renamed build_protected_resource_discovery_urls to build_protected_resource_metadata_discovery_urls
- Renamed get_discovery_urls to build_oauth_authorization_server_metadata_discovery_urls
- New function signature accepts optional auth_server_url and required server_url
- Legacy behavior: when auth_server_url is None, only try root URL
- Path-aware behavior: when auth_server_url has path, only try path-based URLs
- Root behavior: when auth_server_url has no path, only try root URLs

Breaking changes:
- Some invalid server configurations will no longer work:
  - No PRM available and OASM at a path other than root
  - PRM returns auth server URL with path, but OASM only at root

These configurations violate RFC specifications and are not expected to exist.

Github-Issue: #1495
Github-Issue: #1623

Author: maxisbey

src/mcp/client/auth/oauth2.py

@@ -21,14 +21,14 @@
 
 from mcp.client.auth import OAuthFlowError, OAuthTokenError
 from mcp.client.auth.utils import (
-    build_protected_resource_discovery_urls,
+    build_oauth_authorization_server_metadata_discovery_urls,
+    build_protected_resource_metadata_discovery_urls,
     create_client_registration_request,
     create_oauth_metadata_request,
     extract_field_from_www_auth,
     extract_resource_metadata_from_www_auth,
     extract_scope_from_www_auth,
     get_client_metadata_scopes,
-    get_discovery_urls,
     handle_auth_metadata_response,
     handle_protected_resource_response,
     handle_registration_response,
@@ -463,34 +463,34 @@ async def async_auth_flow(self, request: httpx.Request) -> AsyncGenerator[httpx.
                     www_auth_resource_metadata_url = extract_resource_metadata_from_www_auth(response)
 
                     # Step 1: Discover protected resource metadata (SEP-985 with fallback support)
-                    prm_discovery_urls = build_protected_resource_discovery_urls(
+                    prm_discovery_urls = build_protected_resource_metadata_discovery_urls(
                         www_auth_resource_metadata_url, self.context.server_url
                     )
-                    prm_discovery_success = False
+
                     for url in prm_discovery_urls:  # pragma: no branch
                         discovery_request = create_oauth_metadata_request(url)
 
                         discovery_response = yield discovery_request  # sending request
 
                         prm = await handle_protected_resource_response(discovery_response)
                         if prm:
-                            prm_discovery_success = True
-
-                            # saving the response metadata
                             self.context.protected_resource_metadata = prm
-                            if prm.authorization_servers:  # pragma: no branch
-                                self.context.auth_server_url = str(prm.authorization_servers[0])
 
+                            # todo: try all authorization_servers to find the OASM
+                            assert (
+                                len(prm.authorization_servers) > 0
+                            )  # this is always true as authorization_servers has a min length of 1
+
+                            self.context.auth_server_url = str(prm.authorization_servers[0])
                             break
                         else:
                             logger.debug(f"Protected resource metadata discovery failed: {url}")
-                    if not prm_discovery_success:
-                        raise OAuthFlowError(
-                            "Protected resource metadata discovery failed: no valid metadata found"
-                        )  # pragma: no cover
 
-                    # Step 2: Discover OAuth metadata (with fallback for legacy servers)
-                    asm_discovery_urls = get_discovery_urls(self.context.auth_server_url or self.context.server_url)
+                    asm_discovery_urls = build_oauth_authorization_server_metadata_discovery_urls(
+                        self.context.auth_server_url, self.context.server_url
+                    )
+
+                    # Step 2: Discover OAuth Authorization Server Metadata (OASM) (with fallback for legacy servers)
                     for url in asm_discovery_urls:  # pragma: no cover
                         oauth_metadata_request = create_oauth_metadata_request(url)
                         oauth_metadata_response = yield oauth_metadata_request

src/mcp/client/auth/utils.py

@@ -64,7 +64,7 @@ def extract_resource_metadata_from_www_auth(response: Response) -> str | None:
     return extract_field_from_www_auth(response, "resource_metadata")
 
 
-def build_protected_resource_discovery_urls(www_auth_url: str | None, server_url: str) -> list[str]:
+def build_protected_resource_metadata_discovery_urls(www_auth_url: str | None, server_url: str) -> list[str]:
     """
     Build ordered list of URLs to try for protected resource metadata discovery.
 
@@ -126,8 +126,21 @@ def get_client_metadata_scopes(
         return None
 
 
-def get_discovery_urls(auth_server_url: str) -> list[str]:
-    """Generate ordered list of (url, type) tuples for discovery attempts."""
+def build_oauth_authorization_server_metadata_discovery_urls(auth_server_url: str | None, server_url: str) -> list[str]:
+    """
+    Generate ordered list of (url, type) tuples for discovery attempts.
+
+    Args:
+        auth_server_url: URL for the OAuth Authorization Metadata URL if found, otherwise None
+        server_url: URL for the MCP server, used as a fallback if auth_server_url is None
+    """
+
+    if not auth_server_url:
+        # Legacy path using the 2025-03-26 spec:
+        # link: https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization
+        parsed = urlparse(server_url)
+        return [f"{parsed.scheme}://{parsed.netloc}/.well-known/oauth-authorization-server"]
+
     urls: list[str] = []
     parsed = urlparse(auth_server_url)
     base_url = f"{parsed.scheme}://{parsed.netloc}"
@@ -137,18 +150,22 @@ def get_discovery_urls(auth_server_url: str) -> list[str]:
         oauth_path = f"/.well-known/oauth-authorization-server{parsed.path.rstrip('/')}"
         urls.append(urljoin(base_url, oauth_path))
 
-    # OAuth root fallback
-    urls.append(urljoin(base_url, "/.well-known/oauth-authorization-server"))
-
-    # RFC 8414 section 5: Path-aware OIDC discovery
-    # See https://www.rfc-editor.org/rfc/rfc8414.html#section-5
-    if parsed.path and parsed.path != "/":
+        # RFC 8414 section 5: Path-aware OIDC discovery
+        # See https://www.rfc-editor.org/rfc/rfc8414.html#section-5
         oidc_path = f"/.well-known/openid-configuration{parsed.path.rstrip('/')}"
         urls.append(urljoin(base_url, oidc_path))
 
+        # https://openid.net/specs/openid-connect-discovery-1_0.html
+        oidc_path = f"{parsed.path.rstrip('/')}/.well-known/openid-configuration"
+        urls.append(urljoin(base_url, oidc_path))
+        return urls
+
+    # OAuth root
+    urls.append(urljoin(base_url, "/.well-known/oauth-authorization-server"))
+
     # OIDC 1.0 fallback (appends to full URL per OIDC spec)
-    oidc_fallback = f"{auth_server_url.rstrip('/')}/.well-known/openid-configuration"
-    urls.append(oidc_fallback)
+    # https://openid.net/specs/openid-connect-discovery-1_0.html
+    urls.append(urljoin(base_url, "/.well-known/openid-configuration"))
 
     return urls
 

tests/client/test_auth.py

@@ -12,13 +12,13 @@
 
 from mcp.client.auth import OAuthClientProvider, PKCEParameters
 from mcp.client.auth.utils import (
-    build_protected_resource_discovery_urls,
+    build_oauth_authorization_server_metadata_discovery_urls,
+    build_protected_resource_metadata_discovery_urls,
     create_oauth_metadata_request,
     extract_field_from_www_auth,
     extract_resource_metadata_from_www_auth,
     extract_scope_from_www_auth,
     get_client_metadata_scopes,
-    get_discovery_urls,
     handle_registration_response,
 )
 from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken, ProtectedResourceMetadata
@@ -275,7 +275,7 @@ async def callback_handler() -> tuple[str, str | None]:
             status_code=401, headers={}, request=httpx.Request("GET", "https://request-api.example.com")
         )
 
-        urls = build_protected_resource_discovery_urls(
+        urls = build_protected_resource_metadata_discovery_urls(
             extract_resource_metadata_from_www_auth(init_response), provider.context.server_url
         )
         assert len(urls) == 1
@@ -286,7 +286,7 @@ async def callback_handler() -> tuple[str, str | None]:
             'Bearer resource_metadata="https://prm.example.com/.well-known/oauth-protected-resource/path"'
         )
 
-        urls = build_protected_resource_discovery_urls(
+        urls = build_protected_resource_metadata_discovery_urls(
             extract_resource_metadata_from_www_auth(init_response), provider.context.server_url
         )
         assert len(urls) == 2
@@ -309,12 +309,16 @@ class TestOAuthFallback:
 
     @pytest.mark.anyio
     async def test_oauth_discovery_fallback_order(self, oauth_provider: OAuthClientProvider):
-        """Test fallback URL construction order."""
-        discovery_urls = get_discovery_urls(oauth_provider.context.auth_server_url or oauth_provider.context.server_url)
+        """Test fallback URL construction order when auth server URL has a path."""
+        # Simulate PRM discovery returning an auth server URL with a path
+        oauth_provider.context.auth_server_url = oauth_provider.context.server_url
+
+        discovery_urls = build_oauth_authorization_server_metadata_discovery_urls(
+            oauth_provider.context.auth_server_url, oauth_provider.context.server_url
+        )
 
         assert discovery_urls == [
             "https://api.example.com/.well-known/oauth-authorization-server/v1/mcp",
-            "https://api.example.com/.well-known/oauth-authorization-server",
             "https://api.example.com/.well-known/openid-configuration/v1/mcp",
             "https://api.example.com/v1/mcp/.well-known/openid-configuration",
         ]
@@ -1084,7 +1088,7 @@ async def callback_handler() -> tuple[str, str | None]:
         )
 
         # Build discovery URLs
-        discovery_urls = build_protected_resource_discovery_urls(
+        discovery_urls = build_protected_resource_metadata_discovery_urls(
             extract_resource_metadata_from_www_auth(init_response), provider.context.server_url
         )
 
@@ -1224,7 +1228,7 @@ async def callback_handler() -> tuple[str, str | None]:
         )
 
         # Build discovery URLs
-        discovery_urls = build_protected_resource_discovery_urls(
+        discovery_urls = build_protected_resource_metadata_discovery_urls(
             extract_resource_metadata_from_www_auth(init_response), provider.context.server_url
         )