Open Model Context Protocol

Proposals · SEP-985 · Final

Align OAuth 2.0 Protected Resource Metadata with RFC 9728

Standards Track · Created 2025-07-16 · Source

Abstract

This proposal brings the MCP spec's handling of OAuth 2.0 Protected Resource Metadata in line with RFC 9728.

Currently, the MCP spec requires the use of the HTTP WWW-Authenticate header when returning a 401 Unauthorized to indicate the location of the protected resource metadata. However, RFC 9728, Section 5 states:

“A protected resource MAY use the WWW-Authenticate HTTP response header field, as discussed in RFC 9110, to return a URL to its protected resource metadata to the client.”

This suggests that the MCP spec could be made more flexible while still maintaining RFC compliance.

Rationale

Many large-scale, dynamic, multi-tenant environments rely on a centralized authentication service separate from the backend resource servers. In such deployments, injecting WWW-Authenticate headers from backend services is non-trivial due to separation of concerns and infrastructure complexity.

In these scenarios, having the option to discover metadata via a well-known URL provides a practical path forward for easier MCP adoption. Requiring only the header would impose significant communication overhead between components, especially when hundreds or thousands of MCP instances are created and destroyed dynamically. Also if there are specific managed MCP servers, adopting headers across centralized system would add significant overhead.

While this increases complexity for clients—who must now implement logic to probe metadata endpoints—it reduces friction for server deployments and may encourage broader adoption. There are tradeoffs:

Pros for Server Developers: Avoid complex header injection; simplifies integration in distributed environments.

Cons for Client Developers: Clients must fall back to metadata discovery logic when the header is absent, increasing client complexity.

Proposed State

Update the MCP spec to:

Clients MUST interpret the WWW-Authenticate header, and fallback to probing for metadata if not present.
Servers SHOULD return the WWW-Authenticate header

The reason for deviating a bit on the RFC: Go with SHOULD over MAY for WWW-Authenticate is that it makes supporting other features, such as incremental authorization easier (e.g. you make a request for a tool, but need additional scopes, and receive a WWW-Authenticate challenge indicating the scopes).

Based on the above, following the updated flow:

This change allows more flexible deployment models without removing existing capabilities.

Authorization ServerMCP Server (Resource Server)ClientAuthorization ServerMCP Server (Resource Server)ClientAttempt unauthenticated MCP requestExtract resource_metadata URL from headerFallback to metadata probingAbort or use pre-configured valuesalt[Metadata found][Metadata not found]alt[Header includes resource_metadata][No resource_metadata in header]Validate RS metadata,build AS metadata URLOAuth 2.1 authorization flow happens hereMCP communication continues with valid tokenMCP request without tokenHTTP 401 Unauthorized (may include WWW-Authenticate header)GET resource_metadata URIResource metadata with authorization server URLGET /.well-known/oauth-protected-resourceResource metadata with authorization server URLGET /.well-known/oauth-authorization-serverAuthorization server metadataToken requestAccess tokenMCP request with access tokenMCP response

Backward Compatibility

This proposal is fully backward-compatible.

It retains support for the WWW-Authenticate header (already in the spec) and introduces a fallback mechanism using the .well-known metadata path, which is already defined in MCP as a MUST-support location.

Clients that already support metadata probing benefit from improved interoperability. Servers are not required to emit the WWW-Authenticate header if it is infeasible, but doing so is still encouraged to reduce client complexity and enable future extensibility.