Skip to content

Commit cf6dc35

Browse files
dsp-antdsp-ant
authored
Merge pull request modelcontextprotocol#133 from modelcontextprotocol/davidsp/auth
RFC: Authorization support
2 parents 363e36b + 5c35d6d commit cf6dc35

File tree

2 files changed

+383
-1
lines changed

2 files changed

+383
-1
lines changed

‎README.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@
33
This repo contains the specification and protocol schema for the Model Context Protocol.
44

55
The schema is [defined in TypeScript](schema/2024-11-05/schema.ts) first, but
6-
[made available as JSON Schema](schema/2024-11-05/schema.json) as well, for wider compatibility.
6+
[made available as JSON Schema](schema/2024-11-05/schema.json) as well, for wider
7+
compatibility.
78

89
## Contributing
910

‎docs/specification/draft/basic/authorization.md

Lines changed: 381 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,381 @@
1+
---
2+
title: Authorization
3+
type: docs
4+
weight: 15
5+
---
6+
7+
{{< callout type="info" >}} **Protocol Revision**: draft {{< /callout >}}
8+
9+
## 1. Introduction
10+
11+
### 1.1 Purpose and Scope
12+
13+
The Model Context Protocol provides authorization capabilities at the transport level,
14+
enabling MCP clients to make requests to restricted MCP servers on behalf of resource
15+
owners. This specification defines the authorization flow for HTTP+SSE transport.
16+
17+
### 1.2 Protocol Requirements
18+
19+
Authorization is **OPTIONAL** for MCP implementations. When supported:
20+
21+
- Implementations using an HTTP+SSE transport **SHOULD** conform to this specification.
22+
- Implementations using an STDIO transport **SHOULD NOT** follow this specification, and
23+
instead retrieve credentials from the environment.
24+
- Implementations using alternative transports **MUST** follow established security best
25+
practices for their protocol.
26+
27+
### 1.3 Standards Compliance
28+
29+
This authorization mechanism is based on established specifications listed below, but
30+
implements a selected subset of their features to ensure security and interoperability
31+
while maintaining simplicity:
32+
33+
- [OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12)
34+
- OAuth 2.0 Authorization Server Metadata
35+
([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414))
36+
- OAuth 2.0 Dynamic Client Registration Protocol
37+
([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591))
38+
39+
## 2. Authorization Flow
40+
41+
### 2.1 Overview
42+
43+
1. MCP auth implementations **MUST** implement OAuth 2.1 with appropriate security
44+
measures for both confidential and public clients.
45+
46+
2. MCP auth implementations **SHOULD** support the OAuth 2.0 Dynamic Client Registration
47+
Protocol ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)).
48+
49+
3. MCP servers **SHOULD** and MCP clients **MUST** implement OAuth 2.0 Authorization
50+
Server Metadata ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414)). Servers
51+
that do not support Authorization Server Metadata **MUST** follow the default URI
52+
schema.
53+
54+
### 2.2 Basic OAuth 2.1 Authorization
55+
56+
When authorization is required and not yet proven by the client, servers **MUST** respond
57+
with _HTTP 401 Unauthorized_.
58+
59+
Clients initiate the
60+
[OAuth 2.1 IETF DRAFT](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12)
61+
authorization flow after receiving the _HTTP 401 Unauthorized_.
62+
63+
The following demonstrates the basic OAuth 2.1 for public clients using PKCE.
64+
65+
```mermaid
66+
sequenceDiagram
67+
participant B as User-Agent (Browser)
68+
participant C as Client
69+
participant M as MCP Server
70+
71+
C->>M: MCP Request
72+
M->>C: HTTP 401 Unauthorized
73+
Note over C: Generate code_verifier and code_challenge
74+
C->>B: Open browser with authorization URL + code_challenge
75+
B->>M: GET /authorize
76+
Note over M: User logs in and authorizes
77+
M->>B: Redirect to callback URL with auth code
78+
B->>C: Callback with authorization code
79+
C->>M: Token Request with code + code_verifier
80+
M->>C: Access Token (+ Refresh Token)
81+
C->>M: MCP Request with Access Token
82+
Note over C,M: Begin standard MCP message exchange
83+
```
84+
85+
### 2.3 Server Metadata Discovery
86+
87+
For server capability discovery:
88+
89+
- MCP clients _MUST_ follow the OAuth 2.0 Authorization Server Metadata protocol defined
90+
in [RFC8414](https://datatracker.ietf.org/doc/html/rfc8414).
91+
- MCP server _SHOULD_ follow the OAuth 2.0 Authorization Server Metadata protocol.
92+
- MCP servers that do not support the OAuth 2.0 Authorization Server Metadata protocol,
93+
_MUST_ support fallback URLs.
94+
95+
The discovery flow is illustrated below:
96+
97+
```mermaid
98+
sequenceDiagram
99+
participant C as Client
100+
participant S as Server
101+
102+
C->>S: GET /.well-known/oauth-authorization-server
103+
alt Discovery Success
104+
S->>C: 200 OK + Metadata Document
105+
Note over C: Use endpoints from metadata
106+
else Discovery Failed
107+
S->>C: 404 Not Found
108+
Note over C: Fall back to default endpoints
109+
end
110+
Note over C: Continue with authorization flow
111+
```
112+
113+
#### 2.3.1 Server Metadata Discovery Headers
114+
115+
MCP clients _SHOULD_ include the header `MCP-Protocol-Version: <protocol-version>` during
116+
Server Metadata Discovery to allow the MCP server to respond based on the MCP protocol
117+
version.
118+
119+
For example: `MCP-Protocol-Version: 2024-11-05`
120+
121+
#### 2.3.1 Fallbacks for Servers without Metadata Discovery
122+
123+
For servers that do not implement OAuth 2.0 Authorization Server Metadata, clients
124+
**MUST** use the following default endpoint paths relative to the server's base URL:
125+
126+
| Endpoint | Default Path | Description |
127+
| ---------------------- | ------------ | ------------------------------------ |
128+
| Authorization Endpoint | /authorize | Used for authorization requests |
129+
| Token Endpoint | /token | Used for token exchange & refresh |
130+
| Registration Endpoint | /register | Used for dynamic client registration |
131+
132+
Clients **MUST** first attempt to discover endpoints via the metadata document before
133+
falling back to default paths. When using default paths, all other protocol requirements
134+
remain unchanged.
135+
136+
### 2.3 Dynamic Client Registration
137+
138+
MCP authorization makes use of the
139+
[OAuth 2.0 Dynamic Client Registration Protocol](https://datatracker.ietf.org/doc/html/rfc7591)
140+
to allow MCP clients to obtain OAuth client IDs without user interaction.
141+
142+
- MCP clients **SHOULD** support
143+
[OAuth 2.0 Dynamic Client Registration Protocol](https://datatracker.ietf.org/doc/html/rfc7591)
144+
- MCP servers with non-localhost redirect URIs **SHOULD** support Dynamic Client
145+
Registration.
146+
- MCP servers with localhost redirect URIs **MAY** support Dynamic Client Registration.
147+
148+
Note that it is not required to support Dynamic Client Registration. MCP clients that do
149+
not support Dynamic Client Registration need to provide alternative ways to obtain a
150+
client id (and if applicable client secret).
151+
152+
#### 2.3.1 Localhost Redirect URIs
153+
154+
When using localhost redirect URIs (http://localhost:{port} or http://127.0.0.1:{port}),
155+
clients:
156+
157+
- Dynamic registration is **OPTIONAL** (a client ID is not required).
158+
- **MAY** proceed directly to authorization.
159+
- **SHOULD** be considered public clients and not store any clients secrets.
160+
161+
This exception for localhost is explicitly supported by OAuth 2.1 for public clients and
162+
provides a secure flow through the combination of PKCE and localhost-only redirects.
163+
164+
#### 2.3.2 Non-Localhost Redirect URIs
165+
166+
For all other redirect URIs, MCP clients and servers **SHOULD** support dynamic client
167+
registration. This provides a standardized way for clients to automatically register with
168+
new servers, which is crucial for MCP because:
169+
170+
- Clients cannot know all possible servers in advance
171+
- Manual registration would create friction for users
172+
- It enables seamless connection to new servers
173+
- Servers can implement their own registration policies
174+
175+
### 2.4 Authorization Flow Steps
176+
177+
The complete Authorization flow proceeds as follows:
178+
179+
```mermaid
180+
sequenceDiagram
181+
participant B as User-Agent (Browser)
182+
participant C as Client
183+
participant M as MCP Server
184+
185+
C->>M: GET /.well-known/oauth-authorization-server
186+
alt Server Supports Discovery
187+
M->>C: Authorization Server Metadata
188+
else No Discovery
189+
M->>C: 404 (Use default endpoints)
190+
end
191+
192+
alt Non-Localhost Redirect URI
193+
C->>M: POST /register
194+
M->>C: Client Credentials
195+
end
196+
197+
Note over C: Generate PKCE Parameters
198+
C->>B: Open browser with authorization URL + code_challenge
199+
B->>M: Authorization Request
200+
Note over M: User /authorizes
201+
M->>B: Redirect to callback with authorization code
202+
B->>C: Authorization code callback
203+
C->>M: Token Request + code_verifier
204+
M->>C: Access Token (+ Refresh Token)
205+
C->>M: API Requests with Access Token
206+
```
207+
208+
#### 2.4.1 Decision Flow Overview
209+
210+
```mermaid
211+
flowchart TD
212+
A[Start Auth Flow] --> B{Check Metadata Discovery}
213+
B -->|Available| C[Use Metadata Endpoints]
214+
B -->|Not Available| D[Use Default Endpoints]
215+
216+
C --> E{Check Redirect URI}
217+
D --> E
218+
219+
E -->|Localhost| F[Skip Registration]
220+
E -->|Non-localhost| G{Check Registration Endpoint}
221+
222+
G -->|Available| H[Perform Dynamic Registration]
223+
G -->|Not Available| I[Alternative Registration Required]
224+
225+
F --> J[Start OAuth Flow]
226+
H --> J
227+
I --> J
228+
229+
J --> K[Generate PKCE Parameters]
230+
K --> L[Request Authorization]
231+
L --> M[User Authorization]
232+
M --> N[Exchange Code for Tokens]
233+
N --> O[Use Access Token]
234+
```
235+
236+
### 2.5 Access Token Usage
237+
238+
#### 2.5.1 Token Requirements
239+
240+
Access token handling **MUST** conform to
241+
[OAuth 2.1 Section 5](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5)
242+
requirements for resource requests. Specifically:
243+
244+
1. MCP client **MUST** use the Authorization request header field
245+
[Section 5.1.1](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.1.1):
246+
247+
```
248+
Authorization: Bearer <access-token>
249+
```
250+
251+
2. Access tokens **MUST NOT** be included in the URI query string
252+
253+
Example request:
254+
255+
```http
256+
GET /v1/contexts HTTP/1.1
257+
Host: mcp.example.com
258+
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
259+
```
260+
261+
#### 2.5.2 Token Handling
262+
263+
Resource servers **MUST** validate access tokens as described in
264+
[Section 5.2](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.2).
265+
If validation fails, servers **MUST** respond according to
266+
[Section 5.3](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-12#section-5.3)
267+
error handling requirements. Invalid or expired tokens **MUST** receive a HTTP 401
268+
response.
269+
270+
### 2.6 Security Considerations
271+
272+
The following security requirements **MUST** be implemented:
273+
274+
1. Clients **MUST** securely store tokens following OAuth 2.0 best practices
275+
2. Servers **SHOULD** enforce token expiration and rotation
276+
3. All authorization endpoints **MUST** be served over HTTPS
277+
4. Servers **MUST** validate redirect URIs to prevent open redirect vulnerabilities
278+
5. Redirect URIs **MUST** be either localhost URLs or HTTPS URLs
279+
280+
### 2.7 Error Handling
281+
282+
Servers **MUST** return appropriate HTTP status codes for authorization errors:
283+
284+
| Status Code | Description | Usage |
285+
| ----------- | ------------ | ------------------------------------------ |
286+
| 401 | Unauthorized | Authorization required or token invalid |
287+
| 403 | Forbidden | Invalid scopes or insufficient permissions |
288+
| 400 | Bad Request | Malformed authorization request |
289+
290+
### 2.8 Implementation Requirements
291+
292+
1. Implementations **MUST** follow OAuth 2.1 security best practices
293+
2. PKCE is **REQUIRED** for all clients
294+
3. Token rotation **SHOULD** be implemented for enhanced security
295+
4. Token lifetimes **SHOULD** be limited based on security requirements
296+
297+
### 2.9 Third-Party Authorization Flow
298+
299+
#### 2.9.1 Overview
300+
301+
MCP servers **MAY** support delegated authorization through third-party authorization
302+
servers. In this flow, the MCP server acts as both an OAuth client (to the third-party
303+
auth server) and an OAuth authorization server (to the MCP client).
304+
305+
#### 2.9.2 Flow Description
306+
307+
The third-party authorization flow comprises these steps:
308+
309+
1. MCP client initiates standard OAuth flow with MCP server
310+
2. MCP server redirects user to third-party authorization server
311+
3. User authorizes with third-party server
312+
4. Third-party server redirects back to MCP server with authorization code
313+
5. MCP server exchanges code for third-party access token
314+
6. MCP server generates its own access token bound to the third-party session
315+
7. MCP server completes original OAuth flow with MCP client
316+
317+
```mermaid
318+
sequenceDiagram
319+
participant B as User-Agent (Browser)
320+
participant C as MCP Client
321+
participant M as MCP Server
322+
participant T as Third-Party Auth Server
323+
324+
C->>M: Initial OAuth Request
325+
M->>B: Redirect to Third-Party /authorize
326+
B->>T: Authorization Request
327+
Note over T: User authorizes
328+
T->>B: Redirect to MCP Server callback
329+
B->>M: Authorization code
330+
M->>T: Exchange code for token
331+
T->>M: Third-party access token
332+
Note over M: Generate bound MCP token
333+
M->>B: Redirect to MCP Client callback
334+
B->>C: MCP authorization code
335+
C->>M: Exchange code for token
336+
M->>C: MCP access token
337+
```
338+
339+
#### 2.9.3 Session Binding Requirements
340+
341+
MCP servers implementing third-party authorization **MUST**:
342+
343+
1. Maintain secure mapping between third-party tokens and issued MCP tokens
344+
2. Validate third-party token status before honoring MCP tokens
345+
3. Implement appropriate token lifecycle management
346+
4. Handle third-party token expiration and renewal
347+
348+
#### 2.9.4 Security Considerations
349+
350+
When implementing third-party authorization, servers **MUST**:
351+
352+
1. Validate all redirect URIs
353+
2. Securely store third-party credentials
354+
3. Implement appropriate session timeout handling
355+
4. Consider security implications of token chaining
356+
5. Implement proper error handling for third-party auth failures
357+
358+
## 3. Best Practices
359+
360+
#### 3.1 Local clients as Public OAuth 2.1 Clients
361+
362+
We strongly recommend that local clients implement OAuth 2.1 as a public client:
363+
364+
1. Utilizing code challenges (PKCE) for authorization requests to prevent interception
365+
attacks
366+
2. Implementing secure token storage appropriate for the local system
367+
3. Following token refresh best practices to maintain sessions
368+
4. Properly handling token expiration and renewal
369+
370+
#### 3.2 Authorization Metadata Discovery
371+
372+
We strongly recommend that all clients implement metadata discovery. This reduces the
373+
need for users to provide endpoints manually or clients to fallback to the defined
374+
defaults.
375+
376+
#### 3.3 Dynamic Client Registration
377+
378+
Since clients do not know the set of MCP servers in advance, we strongly recommend the
379+
implementation of dynamic client registration. This allows applications to automatically
380+
register with the MCP server, and removes the need for users to obtain client ids
381+
manually.

0 commit comments

Comments
 (0)