Skip to content

SEP-985: Align OAuth 2.0 Protected Resource Metadata with RFC 9728 #985

Closed

Description

@sunishsheth2009

Preamble

This SEP proposes aligning the OAuth 2.0 Protected Resource Metadata handling in the MCP specification with RFC 9728.

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:

  • Attempt the MCP request without a token.
  • If a 401 Unauthorized response is received: Check for a WWW-Authenticate header. If present and includes the resource_metadata parameter, use it to locate the resource metadata.
  • If the header is absent or does not include resource_metadata, fallback to requesting /.well-known/oauth-protected-resource.

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

sequenceDiagram
    participant C as Client
    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 (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 metadata probing
        C->>M: GET /.well-known/oauth-protected-resource
        alt Metadata found
            M-->>C: Resource metadata with authorization server URL
        else Metadata not found
            Note over C: Abort or use pre-configured values
        end
    end

    Note over C: Validate RS metadata,<br />build AS metadata URL

    C->>A: GET /.well-known/oauth-authorization-server
    A-->>C: Authorization server metadata

    Note over C,A: OAuth 2.1 authorization flow happens here

    C->>A: Token request
    A-->>C: Access token

    C->>M: MCP request with access token
    M-->>C: MCP response
    Note over C,M: MCP communication continues with valid token
Loading

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.

Activity

  1. changed the title [-]SEP-004: Align the OAuth 2.0 Protected Resource Metadata spec with the RFC: [rfc9728](https://datatracker.ietf.org/doc/html/rfc9728#name-obtaining-protected-resourc)[/-] [+]SEP-004: Align the OAuth 2.0 Protected Resource Metadata spec with the RFC: rfc9728[/+] on Jul 16, 2025
  2. changed the title [-]SEP-004: Align the OAuth 2.0 Protected Resource Metadata spec with the RFC: rfc9728[/-] [+]SEP-004: Align OAuth 2.0 Protected Resource Metadata with RFC 9728[/+] on Jul 16, 2025
  3. changed the title [-]SEP-004: Align OAuth 2.0 Protected Resource Metadata with RFC 9728[/-] [+]Align OAuth 2.0 Protected Resource Metadata with RFC 9728[/+] on Jul 17, 2025
  4. jonathanhefner commented on Jul 17, 2025

    @jonathanhefner
    Member

    Hi, @sunishsheth2009! 👋 Please do not assign an SEP number when submitting an SEP. The SEP number will be assigned by the sponsor. Thank you!

  5. self-assigned this
    on Jul 17, 2025
  6. added
    draftSEP proposal with a sponsor.
    and removed
    bugSomething isn't working
    proposalSEP proposal without a sponsor.
    on Jul 17, 2025
  7. changed the title [-]Align OAuth 2.0 Protected Resource Metadata with RFC 9728[/-] [+]SEP-004: Align OAuth 2.0 Protected Resource Metadata with RFC 9728[/+] on Jul 17, 2025
  8. pcarleton commented on Jul 17, 2025

    @pcarleton
    Member

    I'll sponsor this one. Assigned it draft and SEP number 004.

  9. 13 remaining items

  10. shays10 commented on Aug 10, 2025

    @shays10

    A very insightful discussion! Would it be correct to assume that this proposal could also address this issue?

  11. added
    acceptedSEP accepted by core maintainers, but still requires final wording and reference implementation.
    and removed
    in-reviewSEP proposal ready for review.
    on Aug 15, 2025
  12. self-assigned this
    on Aug 22, 2025
  13. moved this from Done to In progress in 2025-11-25 Implementationon Nov 5, 2025
  14. moved this from Accepted to Final in SEP Review Pipelineon Aug 23, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

SEPacceptedSEP accepted by core maintainers, but still requires final wording and reference implementation.authawaiting-sdk-changefinalSEP finalized.security

Type

No type

Projects

Relationships

None yet

Development

No branches or pull requests

Issue actions