SEP-985: Updating the Authorization spec to fallback to WWW-Authenticate when Protected Resource Metadata is not found (modelcontextprotocol#971)

* Updating the Authorization spec to fallback to WWW-Authenticate when Protected Resource Metadata is not found

* Updating the sequence diagram based on SEP changes

* clarify metadata hosting options

* make mermaid more explicit

* Apply suggestions from code review

Co-authored-by: Den Delimarsky <[email protected]>

* Update docs/specification/draft/basic/authorization.mdx

* Apply suggestions from code review

Co-authored-by: Geoff Goodman <[email protected]>

* Apply suggestions from code review

* formatting

---------

Co-authored-by: Paul Carleton <[email protected]>
Co-authored-by: Den Delimarsky <[email protected]>
Co-authored-by: Paul Carleton <[email protected]>
Co-authored-by: Geoff Goodman <[email protected]>

Author: 4 people

docs/specification/draft/basic/authorization.mdx

@@ -88,12 +88,19 @@ guidance on implementation details.
 Implementors should note that Protected Resource Metadata documents can define multiple authorization servers. The responsibility for selecting which authorization server to use lies with the MCP client, following the guidelines specified in
 [RFC9728 Section 7.6 "Authorization Servers"](https://datatracker.ietf.org/doc/html/rfc9728#name-authorization-servers).
 
-MCP servers **MUST** use the HTTP header `WWW-Authenticate` when returning a _401 Unauthorized_ to indicate the location of the resource server metadata URL
-as described in [RFC9728 Section 5.1 "WWW-Authenticate Response"](https://datatracker.ietf.org/doc/html/rfc9728#name-www-authenticate-response).
+#### Protected Resource Metadata Discovery Requirements
 
-MCP clients **MUST** be able to parse `WWW-Authenticate` headers and respond appropriately to `HTTP 401 Unauthorized` responses from the MCP server.
+MCP servers **MUST** implement one of the following discovery mechanisms to provide authorization server location information to MCP clients:
 
-#### Server Metadata Discovery
+1. **WWW-Authenticate Header**: Include the resource metadata URL in the `WWW-Authenticate` HTTP header under `resource_metadata` when returning `401 Unauthorized` responses, as described in [RFC9728 Section 5.1](https://datatracker.ietf.org/doc/html/rfc9728#name-www-authenticate-response).
+
+2. **Well-Known URI**: Serve metadata at a well-known URI as specified in [RFC9728](https://datatracker.ietf.org/doc/html/rfc9728). This can be either:
+   - At the path of the server's MCP endpoint: `https://example.com/public/mcp` could host metadata at `https://example.com/.well-known/oauth-protected-resource/public/mcp`
+   - At the root: `https://example.com/.well-known/oauth-protected-resource`
+
+MCP clients **MUST** support both discovery mechanisms and use the resource metadata URL from the parsed WWW-Authenticate headers when present; otherwise, they **MUST** fall back to constructing and requesting the well-known URIs in the order listed above.
+
+#### Authorization Server Metadata Discovery
 
 To handle different issuer URL formats and ensure interoperability with both OAuth 2.0 Authorization Server Metadata and OpenID Connect Discovery 1.0 specifications, MCP clients **MUST** attempt multiple well-known endpoints when discovering authorization server metadata.
 
@@ -120,12 +127,30 @@ sequenceDiagram
     participant M as MCP Server (Resource Server)
     participant A as Authorization Server
 
+    Note over C: Attempt unauthenticated MCP request
     C->>M: MCP request without token
-    M-->>C: HTTP 401 Unauthorized with WWW-Authenticate header
-    Note over C: Extract resource_metadata<br />from WWW-Authenticate
+    M-->>C: HTTP 401 Unauthorized (may include WWW-Authenticate header)
+
+    alt Header includes resource_metadata
+        Note over C: Extract resource_metadata URL from header
+        C->>M: GET resource_metadata URI
+        M-->>C: Resource metadata with authorization server URL
+    else No resource_metadata in header
+        Note over C: Fallback to well-known URI probing
+        Note over M: _Not applicable if the MCP server is at the root_
+        C->>M: GET /.well-known/oauth-protected-resource/mcp
+        alt Sub-path metadata found
+            M-->>C: Resource metadata with authorization server URL
+        else Sub-path not found
+            C->>M: GET /.well-known/oauth-protected-resource
+            alt Root metadata found
+                M-->>C: Resource metadata with authorization server URL
+            else Root metadata not found
+                Note over C: Abort or use pre-configured values
+            end
+        end
+    end
 
-    C->>M: GET /.well-known/oauth-protected-resource
-    M-->>C: Resource metadata with authorization server URL
     Note over C: Validate RS metadata,<br />build AS metadata URL
 
     C->>A: GET Authorization server metadata endpoint