mcp-authorization

Instruction file imported from egoavara/overlay-mcp (.cursor/rules/mcp-authorization.mdc). Copyright stays with the author.

1. Introduction

1.1 Purpose and Scope

The Model Context Protocol provides authorization capabilities at the transport level, enabling MCP clients to make requests to restricted MCP servers on behalf of resource owners. This specification defines the authorization flow for HTTP-based transports.

1.2 Protocol Requirements

Authorization is OPTIONAL for MCP implementations. When supported:

• Implementations using an HTTP-based transport SHOULD conform to this specification.
• Implementations using an STDIO transport SHOULD NOT follow this specification, and instead retrieve credentials from the environment.
• Implementations using alternative transports MUST follow established security best practices for their protocol.

1.3 Standards Compliance

This authorization mechanism is based on established specifications listed below, but implements a selected subset of their features to ensure security and interoperability while maintaining simplicity:

• @OAuth 2.1 IETF DRAFT
• OAuth 2.0 Authorization Server Metadata (@RFC8414)
• OAuth 2.0 Dynamic Client Registration Protocol (@RFC7591)

2. Authorization Flow

2.1 Overview

1. MCP auth implementations MUST implement OAuth 2.1 with appropriate security measures for both confidential and public clients.

2. MCP auth implementations SHOULD support the OAuth 2.0 Dynamic Client Registration Protocol (@RFC7591).

3. MCP servers SHOULD and MCP clients MUST implement OAuth 2.0 Authorization Server Metadata (@RFC8414). Servers that do not support Authorization Server Metadata MUST follow the default URI schema.

2.1.1 OAuth Grant Types

OAuth specifies different flows or grant types, which are different ways of obtaining an access token. Each of these targets different use cases and scenarios.

MCP servers SHOULD support the OAuth grant types that best align with the intended audience. For instance:

1. Authorization Code: useful when the client is acting on behalf of a (human) end user.
   • For instance, an agent calls an MCP tool implemented by a SaaS system.
2. Client Credentials: the client is another application (not a human)
   • For instance, an agent calls a secure MCP tool to check inventory at a specific store. No need to impersonate the end user.

2.2 Example: authorization code grant

This demonstrates the OAuth 2.1 flow for the authorization code grant type, used for user auth.

NOTE: The following example assumes the MCP server is also functioning as the authorization server. However, the authorization server may be deployed as its own distinct service.

A human user completes the OAuth flow through a web browser, obtaining an access token that identifies them personally and allows the client to act on their behalf.

When authorization is required and not yet proven by the client, servers MUST respond with HTTP 401 Unauthorized.

Clients initiate the @OAuth 2.1 IETF DRAFT authorization flow after receiving the HTTP 401 Unauthorized.

The following demonstrates the basic OAuth 2.1 for public clients using PKCE.

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

    C->>M: MCP Request
    M->>C: HTTP 401 Unauthorized
    Note over C: Generate code_verifier and code_challenge
    C->>B: Open browser with authorization URL + code_challenge
    B->>M: GET /authorize
    Note over M: User logs in and authorizes
    M->>B: Redirect to callback URL with auth code
    B->>C: Callback with authorization code
    C->>M: Token Request with code + code_verifier
    M->>C: Access Token (+ Refresh Token)
    C->>M: MCP Request with Access Token
    Note over C,M: Begin standard MCP message exchange

2.3 Server Metadata Discovery

For server capability discovery:

• MCP clients MUST follow the OAuth 2.0 Authorization Server Metadata protocol defined in @RFC8414.
• MCP server SHOULD follow the OAuth 2.0 Authorization Server Metadata protocol.
• MCP servers that do not support the OAuth 2.0 Authorization Server Metadata protocol, MUST support fallback URLs.

The discovery flow is illustrated below:

sequenceDiagram
    participant C as Client
    participant S as Server

    C->>S: GET /.well-known/oauth-authorization-server
    alt Discovery Success
        S->>C: 200 OK + Metadata Document
        Note over C: Use endpoints from metadata
    else Discovery Failed
        S->>C: 404 Not Found
        Note over C: Fall back to default endpoints
    end
    Note over C: Continue with authorization flow

2.3.1 Server Metadata Discovery Headers

MCP clients SHOULD include the header MCP-Protocol-Version: <protocol-version> during Server Metadata Discovery to allow the MCP server to respond based on the MCP protocol version.

For example: MCP-Protocol-Version: 2024-11-05

2.3.2 Authorization Base URL

The authorization base URL MUST be determined from the MCP server URL by discarding any existing path component. For example:

If the MCP server URL is https://api.example.com/v1/mcp, then:

• The authorization base URL is https://api.example.com
• The metadata endpoint MUST be at https://api.example.com/.well-known/oauth-authorization-server

This ensures authorization endpoints are consistently located at the root level of the domain hosting the MCP server, regardless of any path components in the MCP server URL.

2.3.3 Fallbacks for Servers without Metadata Discovery

For servers that do not implement OAuth 2.0 Authorization Server Metadata, clients MUST use the following default endpoint paths relative to the authorization base URL (as defined in @Section 2.3.2):

For example, with an MCP server hosted at https://api.example.com/v1/mcp, the default endpoints would be:

• https://api.example.com/authorize
• https://api.example.com/token
• https://api.example.com/register

Clients MUST first attempt to discover endpoints via the metadata document before falling back to default paths. When using default paths, all other protocol requirements remain unchanged.

2.4 Dynamic Client Registration

MCP clients and servers SHOULD support the @OAuth 2.0 Dynamic Client Registration Protocol to allow MCP clients to obtain OAuth client IDs without user interaction. This provides a standardized way for clients to automatically register with new servers, which is crucial for MCP because:

• Clients cannot know all possible servers in advance
• Manual registration would create friction for users
• It enables seamless connection to new servers
• Servers can implement their own registration policies

Any MCP servers that do not support Dynamic Client Registration need to provide alternative ways to obtain a client ID (and, if applicable, client secret). For one of these servers, MCP clients will have to either:

1. Hardcode a client ID (and, if applicable, client secret) specifically for that MCP server, or
2. Present a UI to users that allows them to enter these details, after registering an OAuth client themselves (e.g., through a configuration interface hosted by the server).

2.5 Authorization Flow Steps

The complete Authorization flow proceeds as follows:

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

    C->>M: GET /.well-known/oauth-authorization-server
    alt Server Supports Discovery
        M->>C: Authorization Server Metadata
    else No Discovery
        M->>C: 404 (Use default endpoints)
    end

    alt Dynamic Client Registration
        C->>M: POST /register
        M->>C: Client Credentials
    end

    Note over C: Generate PKCE Parameters
    C->>B: Open browser with authorization URL + code_challenge
    B->>M: Authorization Request
    Note over M: User /authorizes
    M->>B: Redirect to callback with authorization code
    B->>C: Authorization code callback
    C->>M: Token Request + code_verifier
    M->>C: Access Token (+ Refresh Token)
    C->>M: API Requests with Access Token

2.5.1 Decision Flow Overview

flowchart TD
    A[Start Auth Flow] --> B{Check Metadata Discovery}
    B -->|Available| C[Use Metadata Endpoints]
    B -->|Not Available| D[Use Default Endpoints]

    C --> G{Check Registration Endpoint}
    D --> G

    G -->|Available| H[Perform Dynamic Registration]
    G -->|Not Available| I[Alternative Registration Required]

    H --> J[Start OAuth Flow]
    I --> J

    J --> K[Generate PKCE Parameters]
    K --> L[Request Authorization]
    L --> M[User Authorization]
    M --> N[Exchange Code for Tokens]
    N --> O[Use Access Token]

2.6 Access Token Usage

2.6.1 Token Requirements

Access token handling MUST conform to @OAuth 2.1 Section 5 requirements for resource requests. Specifically:

1. MCP client MUST use the Authorization request header field @Section 5.1.1:

Authorization: Bearer <access-token>

Note that authorization MUST be included in every HTTP request from client to server, even if they are part of the same logical session.

2. Access tokens MUST NOT be included in the URI query string

Example request:

GET /v1/contexts HTTP/1.1
Host: mcp.example.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

2.6.2 Token Handling

Resource servers MUST validate access tokens as described in @Section 5.2. If validation fails, servers MUST respond according to @Section 5.3 error handling requirements. Invalid or expired tokens MUST receive a HTTP 401 response.

2.7 Security Considerations

The following security requirements MUST be implemented:

1. Clients MUST securely store tokens following OAuth 2.0 best practices
2. Servers SHOULD enforce token expiration and rotation
3. All authorization endpoints MUST be served over HTTPS
4. Servers MUST validate redirect URIs to prevent open redirect vulnerabilities
5. Redirect URIs MUST be either localhost URLs or HTTPS URLs

2.8 Error Handling

Servers MUST return appropriate HTTP status codes for authorization errors:

2.9 Implementation Requirements

1. Implementations MUST follow OAuth 2.1 security best practices
2. PKCE is REQUIRED for all clients
3. Token rotation SHOULD be implemented for enhanced security
4. Token lifetimes SHOULD be limited based on security requirements

2.10 Third-Party Authorization Flow

2.10.1 Overview

MCP servers MAY support delegated authorization through third-party authorization servers. In this flow, the MCP server acts as both an OAuth client (to the third-party auth server) and an OAuth authorization server (to the MCP client).

2.10.2 Flow Description

The third-party authorization flow comprises these steps:

1. MCP client initiates standard OAuth flow with MCP server
2. MCP server redirects user to third-party authorization server
3. User authorizes with third-party server
4. Third-party server redirects back to MCP server with authorization code
5. MCP server exchanges code for third-party access token
6. MCP server generates its own access token bound to the third-party session
7. MCP server completes original OAuth flow with MCP client

sequenceDiagram
    participant B as User-Agent (Browser)
    participant C as MCP Client
    participant M as MCP Server
    participant T as Third-Party Auth Server

    C->>M: Initial OAuth Request
    M->>B: Redirect to Third-Party /authorize
    B->>T: Authorization Request
    Note over T: User authorizes
    T->>B: Redirect to MCP Server callback
    B->>M: Authorization code
    M->>T: Exchange code for token
    T->>M: Third-party access token
    Note over M: Generate bound MCP token
    M->>B: Redirect to MCP Client callback
    B->>C: MCP authorization code
    C->>M: Exchange code for token
    M->>C: MCP access token

2.10.3 Session Binding Requirements

MCP servers implementing third-party authorization MUST:

1. Maintain secure mapping between third-party tokens and issued MCP tokens
2. Validate third-party token status before honoring MCP tokens
3. Implement appropriate token lifecycle management
4. Handle third-party token expiration and renewal

2.10.4 Security Considerations

When implementing third-party authorization, servers MUST:

1. Validate all redirect URIs
2. Securely store third-party credentials
3. Implement appropriate session timeout handling
4. Consider security implications of token chaining
5. Implement proper error handling for third-party auth failures

3. Best Practices

3.1 Local clients as Public OAuth 2.1 Clients

We strongly recommend that local clients implement OAuth 2.1 as a public client:

1. Utilizing code challenges (PKCE) for authorization requests to prevent interception attacks
2. Implementing secure token storage appropriate for the local system
3. Following token refresh best practices to maintain sessions
4. Properly handling token expiration and renewal

3.2 Authorization Metadata Discovery

We strongly recommend that all clients implement metadata discovery. This reduces the need for users to provide endpoints manually or clients to fallback to the defined defaults.

3.3 Dynamic Client Registration

Since clients do not know the set of MCP servers in advance, we strongly recommend the implementation of dynamic client registration. This allows applications to automatically register with the MCP server, and removes the need for users to obtain client ids manually.