feat: add authentication specification for MCP HTTP+SSE transport

This adds a comprehensive authentication specification for the Model
Context Protocol that uses OAuth 2.1 for HTTP+SSE transport. The
spec defines the complete authentication flow including metadata
discovery, dynamic client registration, token handling, and security
best practices. It supports both localhost and non-localhost scenarios
with appropriate security measures.

Author: dsp-ant

README.md

@@ -3,7 +3,8 @@
 This repo contains the specification and protocol schema for the Model Context Protocol.
 
 The schema is [defined in TypeScript](schema/2024-11-05/schema.ts) first, but
-[made available as JSON Schema](schema/2024-11-05/schema.json) as well, for wider compatibility.
+[made available as JSON Schema](schema/2024-11-05/schema.json) as well, for wider
+compatibility.
 
 ## Contributing
 

docs/specification/draft/basic/authorization.md

@@ -0,0 +1,381 @@
+---
+title: Authorization
+type: docs
+weight: 15
+---
+
+{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}}
+
+## 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+SSE transport.
+
+### 1.2 Protocol Requirements
+
+Authorization is **OPTIONAL** for MCP implementations. When supported:
+
+- Implementations using an HTTP+SSE 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](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12)
+- OAuth 2.0 Authorization Server Metadata
+  ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414))
+- OAuth 2.0 Dynamic Client Registration Protocol
+  ([RFC7591](https://datatracker.ietf.org/doc/html/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](https://datatracker.ietf.org/doc/html/rfc7591)).
+
+3. MCP servers **SHOULD** and MCP clients **MUST** implement OAuth 2.0 Authorization
+   Server Metadata ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)). Servers
+   that do not support Authorization Server Metadata **MUST** follow the default URI
+   schema.
+
+### 2.2 Basic OAuth 2.1 Authorization
+
+When authorization is required and not yet prooven by the client, servers **MUST**
+respond with _HTTP 401 Unauthorized_.
+
+Clients initiate the
+[OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12)
+authorization flow after receiving the _HTTP 401 Unauthorized_.
+
+The following demonstrates the basic OAuth 2.1 for public clients using PKCE.
+
+```mermaid
+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](https://datatracker.ietf.org/doc/html/rfc8414).
+- MCP server _SHOULD_ support 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:
+
+```mermaid
+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 Discover Headers
+
+MCP clients _SHOULD_ include the header `MCP-Protocol-Version: <protocol-version>` during
+Server Metadata Discover to allow MCP server to respond based on MCP protocol version.
+
+For example: `MCP-Protocol-Version: 2024-11-05`
+
+#### 2.3.1 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 server's base URL:
+
+| Endpoint               | Default Path | Description                          |
+| ---------------------- | ------------ | ------------------------------------ |
+| Authorization Endpoint | /authorize   | Used for authorization requests      |
+| Token Endpoint         | /token       | Used for token exchange & refresh    |
+| Registration Endpoint  | /register    | Used for dynamic client registration |
+
+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.3 Dynamic Client Registration
+
+MCP authorization makes use of the
+[OAuth 2.0 Dynamic Client Registration Protocol](https://datatracker.ietf.org/doc/html/rfc7591)
+to allow MCP clients to obtain OAuth client IDs without user interaction.
+
+- MCP clients **SHOULD** support
+  [OAuth 2.0 Dynamic Client Registration Protocol](https://datatracker.ietf.org/doc/html/rfc7591)
+- MCP servers with non-localhost redirect URIs **SHOULD** support Dynamic Client
+  Registration.
+- MCP servers with localhost redirect URIs **OPTIONALLY** support Dynamic Client
+  Registration.
+
+Note that are not required to support Dynamic Client Registration. MCP clients that do
+not support Dynamic Client Registration need to provide alternative ways to obtain a
+client id (and if applicable client secret).
+
+#### 2.3.1 Localhost Redirect URIs
+
+When using localhost redirect URIs (http://localhost:{port} or http://127.0.0.1:{port}),
+clients:
+
+- Dynamic registration is **OPTIONAL** (a client ID is not required)
+- **MAY** proceed directly to authorization
+- **MUST NOT** require client secrets
+
+This exception for localhost is explicitly supported by OAuth 2.1 for public clients and
+provides a secure flow through the combination of PKCE and localhost-only redirects.
+
+#### 2.3.2 Non-Localhost Redirect URIs
+
+For all other redirect URIs, MCP clients and servers **SHOULD** support dynamic client
+registration. 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
+
+### 2.4 Authorization Flow Steps
+
+The complete Authorization flow proceeds as follows:
+
+```mermaid
+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 Non-Localhost Redirect URI
+        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.4.1 Decision Flow Overview
+
+```mermaid
+flowchart TD
+    A[Start Auth Flow] --> B{Check Metadata Discovery}
+    B -->|Available| C[Use Metadata Endpoints]
+    B -->|Not Available| D[Use Default Endpoints]
+
+    C --> E{Check Redirect URI}
+    D --> E
+
+    E -->|Localhost| F[Skip Registration]
+    E -->|Non-localhost| G{Check Registration Endpoint}
+
+    G -->|Available| H[Perform Dynamic Registration]
+    G -->|Not Available| I[Alternative Registration Required]
+
+    F --> J[Start OAuth Flow]
+    H --> J
+    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.5 Access Token Usage
+
+#### 2.5.1 Token Requirements
+
+Access token handling **MUST** conform to
+[OAuth 2.1 Section 5](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5)
+requirements for resource requests. Specifically:
+
+1. MCP client **MUST** use the Authorization request header field
+   [Section 5.1.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.1.1):
+
+```
+Authorization: Bearer <access-token>
+```
+
+2. Access tokens **MUST NOT** be included in the URI query string
+
+Example request:
+
+```http
+GET /v1/contexts HTTP/1.1
+Host: mcp.example.com
+Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
+```
+
+#### 2.5.2 Token Handling
+
+Resource servers **MUST** validate access tokens as described in
+[Section 5.2](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.2).
+If validation fails, servers **MUST** respond according to
+[Section 5.3](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.3)
+error handling requirements. Invalid or expired tokens **MUST** receive a HTTP 401
+response.
+
+### 2.6 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.7 Error Handling
+
+Servers **MUST** return appropriate HTTP status codes for authorization errors:
+
+| Status Code | Description  | Usage                                      |
+| ----------- | ------------ | ------------------------------------------ |
+| 401         | Unauthorized | Authorization required or token invalid    |
+| 403         | Forbidden    | Invalid scopes or insufficient permissions |
+| 400         | Bad Request  | Malformed authorization request            |
+
+### 2.8 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.9 Third-Party Authorization Flow
+
+#### 2.9.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.9.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
+
+```mermaid
+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.9.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.9.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 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 either manually or 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.