SEP-835: Update authorization spec with default scopes definition

Preamble

• Title: Update authorization spec with default scopes definition
• Author: Den Delimarsky (@localden)
• Status: Proposal
• Type: Standards Track SEP

Abstract

This SEP proposes enhancements to the MCP OAuth 2.1-based authorization specification to improve scope management, client experience, and support for different client types. The changes include: (1) structured scope selection strategies following the principle of least privilege, (2) comprehensive scope error handling with upgrade flows, (3) differentiated behavior for client credentials vs. interactive clients, and (4) improved consistency in error responses.

Motivation

The current authorization specification lacks detailed guidance for:

• Scope selection: Clients don't have clear guidance on which scopes to request initially
• Runtime scope upgrades: No standardized flow for handling insufficient scope errors during operation
• Client type differences: Client credentials clients have different capabilities than interactive clients but are treated the same
• Error response consistency: 403 responses lack resource metadata present in 401 responses, complicating client implementations

These gaps lead to over-privileged token requests, poor user experience, and implementation inconsistencies across MCP clients and servers.

Specification

The specification changes include:

4.1 Scope Selection Strategy

• Priority-based scope selection: WWW-Authenticate scope parameter first, fallback to scopes_supported in PRM
• Principle of least privilege guidance
• Flexibility for out-of-band scope decisions

4.2 Enhanced Error Handling

• Standardized 403 insufficient_scope responses with resource_metadata
• Scope upgrade flow with differentiated client behavior:
  • Interactive clients SHOULD attempt upgrade
  • Client credentials clients MAY attempt or abort immediately
• Retry limits and caching to prevent infinite loops

4.3 Security Enhancements

• New Scope Minimization security section
• Guidance on fine-grained scopes
• Progressive access patterns support

Rationale

Scope Selection: The priority-based approach balances security (least privilege) with usability. The WWW-Authenticate scope parameter provides immediate, contextual guidance while scopes_supported offers fallback coverage.

Client Type Differentiation: Client credentials clients lack interactive authorization capabilities, making automatic scope upgrade less practical. The MAY vs SHOULD distinction reflects this reality while still allowing implementation flexibility.

Error Response Consistency: Including resource_metadata in 403 responses matches 401 behavior, simplifying client implementations by making error responses self-contained.

Removed Restrictive Logic: Original draft prevented reauthorization in scenarios where it might succeed (timed access, conditional policies). The retry limits provide sufficient protection against infinite loops without being overly restrictive.

Backward Compatibility

This SEP is backward compatible. All changes are additive or clarifications:

• New scope selection behavior is recommended (SHOULD) not required (MUST)
• Error handling enhancements are optional for servers
• Existing client implementations continue to work unchanged
• No breaking changes to protocol messages or flow

Reference Implementation

• Update MCP specification documentation
• Example client implementations demonstrating scope selection strategies
• Example server implementations showing enhanced error responses
• Test cases covering upgrade flows and edge cases

Security Implications

Positive impacts:

• Reduced token privilege through better scope selection
• Improved error handling reduces attack surface
• Clear guidance prevents security antipatterns

Considerations:

• Scope upgrade flows must implement proper retry limits
• Caching mechanisms should not leak authorization state
• Client credentials flow limitations are clearly documented

Community Impact

• Client developers: Clearer implementation guidance, better user experience
• Server developers: Standardized error responses, security best practices
• End users: Reduced permission prompts, more secure access patterns
• Ecosystem: Better interoperability through consistent behavior

This SEP qualifies as a Standards Track SEP because it proposes significant enhancements to the MCP authorization protocol that will affect multiple implementations and improve ecosystem

Proposed flow

sequenceDiagram
    participant C as Client
    participant M as MCP Server (Resource Server)
    participant A as Authorization Server
    participant B as User-Agent (Browser)

    Note over C,M: Initial successful authorization with limited scopes
    C->>M: MCP request with access token (limited scopes)
    M-->>C: HTTP 200 OK (operation succeeds)

    Note over C,M: Later request requires additional scopes
    C->>M: MCP request requiring additional scope
    M-->>C: HTTP 403 Forbidden with WWW-Authenticate header
    Note over C: Parse insufficient_scope error<br/>Extract required scopes and resource_metadata

    alt Interactive Client (authorization_code)
        Note over C: Client acting on behalf of user<br/>SHOULD attempt scope upgrade
        C->>M: GET resource metadata (if needed)
        M-->>C: Protected Resource Metadata
        
        C->>A: GET Authorization server metadata
        A-->>C: Authorization server metadata
        
        Note over C: Calculate union of current + required scopes<br/>Apply scope selection strategy
        C->>B: Open browser with authorization URL (broader scopes)
        B->>A: Authorization request with expanded scopes
        Note over A: User authorizes expanded permissions
        A->>B: Redirect with authorization code
        B->>C: Authorization code callback
        C->>A: Token request + code_verifier + resource
        A->>C: New access token (expanded scopes)
        
        C->>M: Retry original request with new token
        M-->>C: HTTP 200 OK (operation succeeds)
        
    else Client Credentials Client
        Note over C: Client acting on own behalf<br/>MAY attempt upgrade or abort
        
        alt Attempt Upgrade
            C->>A: Token request (client_credentials + expanded scopes)
            A->>C: New access token (if authorized)
            C->>M: Retry original request with new token
            M-->>C: HTTP 200 OK or still 403 if unauthorized
        else Abort Request
            Note over C: Client chooses not to upgrade<br/>Reports error to application
        end
    end

    Note over C: Retry limits and caching prevent infinite loops

This change formalizes some of the authorizaiton spec requirements based on items such as:

• [auth] Handle dynamically selecting scopes in client authorization url typescript-sdk#672
• Adding invalidateCredentials() to OAuthClientProvider typescript-sdk#570