One read of Model Context Protocolmcp-20261022T203719Z
295 pages moved out of 357 read.
Pages moved
295
significant first
Pages read
357
in this capture
Captured
20:37 UTC
Corpus hash
3ef457b31340
full-sweep
What this read moved
151-175 of 295, page 7 of 12This capture is too large to show at once. Changes 151-175 of 295 are below, significant first; the rest are on the following screens.
specification/2025-03-26/server/prompts Changed · +3 / -3 lines
from line 24
2424## Capabilities
2525
2626Servers that support prompts **MUST** declare the `prompts` capability during
27[initialization](/specification/2025-03-26/basic/lifecycle#initialization):
27[initialization](/specification/2025-03-26/basic/lifecycle.md#initialization):
2828
2929```json theme={null}
3030{
from line 44
4444### Listing Prompts
4545
4646To retrieve available prompts, clients send a `prompts/list` request. This operation
47supports [pagination](/specification/2025-03-26/server/utilities/pagination).
47supports [pagination](/specification/2025-03-26/server/utilities/pagination.md).
4848
4949**Request:**
5050
from line 87
8787### Getting a Prompt
8888
8989To retrieve a specific prompt, clients send a `prompts/get` request. Arguments may be
90auto-completed through [the completion API](/specification/2025-03-26/server/utilities/completion).
90auto-completed through [the completion API](/specification/2025-03-26/server/utilities/completion.md).
9191
9292**Request:**
9393
specification/2025-03-26/server/resources Changed · +3 / -3 lines
from line 81
8181### Listing Resources
8282
8383To discover available resources, clients send a `resources/list` request. This operation
84supports [pagination](/specification/2025-03-26/server/utilities/pagination).
84supports [pagination](/specification/2025-03-26/server/utilities/pagination.md).
8585
8686**Request:**
8787
from line 155
155155
156156Resource templates allow servers to expose parameterized resources using
157157[URI templates](https://datatracker.ietf.org/doc/html/rfc6570). Arguments may be
158auto-completed through [the completion API](/specification/2025-03-26/server/utilities/completion).
159This operation supports [pagination](/specification/2025-03-26/server/utilities/pagination).
158auto-completed through [the completion API](/specification/2025-03-26/server/utilities/completion.md).
159This operation supports [pagination](/specification/2025-03-26/server/utilities/pagination.md).
160160
161161**Request:**
162162
specification/2025-06-18/basic/authorization Changed · +4 / -4 lines
from line 292
292292* MCP clients **MUST** include the `resource` parameter in authorization and token requests as specified in the [Resource Parameter Implementation](#resource-parameter-implementation) section
293293* MCP servers **MUST** validate that tokens presented to them were specifically issued for their use
294294
295The [Security Best Practices document](/specification/2025-06-18/basic/security_best_practices#token-passthrough)
295The [Security Best Practices document](/specification/2025-06-18/basic/security_best_practices.md#token-passthrough)
296296outlines why token audience validation is crucial and why token passthrough is explicitly forbidden.
297297
298298### Token Theft
from line 340
340340
341341### Confused Deputy Problem
342342
343Attackers can exploit MCP servers acting as intermediaries to third-party APIs, leading to [confused deputy vulnerabilities](/specification/2025-06-18/basic/security_best_practices#confused-deputy-problem).
343Attackers can exploit MCP servers acting as intermediaries to third-party APIs, leading to [confused deputy vulnerabilities](/specification/2025-06-18/basic/security_best_practices.md#confused-deputy-problem).
344344By using stolen authorization codes, they can obtain access tokens without user consent.
345345
346346MCP proxy servers using static client IDs **MUST** obtain user consent for each dynamically
from line 353
353353This vulnerability has two critical dimensions:
354354
3553551. **Audience validation failures.** When an MCP server doesn't verify that tokens were specifically intended for it (for example, via the audience claim, as mentioned in [RFC9068](https://www.rfc-editor.org/rfc/rfc9068.html)), it may accept tokens originally issued for other services. This breaks a fundamental OAuth security boundary, allowing attackers to reuse legitimate tokens across different services than intended.
3562. **Token passthrough.** If the MCP server not only accepts tokens with incorrect audiences but also forwards these unmodified tokens to downstream services, it can potentially cause the ["confused deputy" problem](#confused-deputy-problem), where the downstream API may incorrectly trust the token as if it came from the MCP server or assume the token was validated by the upstream API. See the [Token Passthrough section](/specification/2025-06-18/basic/security_best_practices#token-passthrough) of the Security Best Practices guide for additional details.
3562. **Token passthrough.** If the MCP server not only accepts tokens with incorrect audiences but also forwards these unmodified tokens to downstream services, it can potentially cause the ["confused deputy" problem](#confused-deputy-problem), where the downstream API may incorrectly trust the token as if it came from the MCP server or assume the token was validated by the upstream API. See the [Token Passthrough section](/specification/2025-06-18/basic/security_best_practices.md#token-passthrough) of the Security Best Practices guide for additional details.
357357
358358MCP servers **MUST** validate access tokens before processing the request, ensuring the access token is issued specifically for the MCP server, and take all necessary steps to ensure no data is returned to unauthorized parties.
359359
360360A MCP server **MUST** follow the guidelines in [OAuth 2.1 - Section 5.2](https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-13.html#section-5.2) to validate inbound tokens.
361361
362MCP servers **MUST** only accept tokens specifically intended for themselves and **MUST** reject tokens that do not include them in the audience claim or otherwise verify that they are the intended recipient of the token. See the [Security Best Practices Token Passthrough section](/specification/2025-06-18/basic/security_best_practices#token-passthrough) for details.
362MCP servers **MUST** only accept tokens specifically intended for themselves and **MUST** reject tokens that do not include them in the audience claim or otherwise verify that they are the intended recipient of the token. See the [Security Best Practices Token Passthrough section](/specification/2025-06-18/basic/security_best_practices.md#token-passthrough) for details.
363363
364364If the MCP server makes requests to upstream APIs, it may act as an OAuth client to them. The access token used at the upstream API is a separate token, issued by the upstream authorization server. The MCP server **MUST NOT** pass through the token it received from the MCP client.
365365
specification/2025-06-18/basic/lifecycle Changed · +16 / -16 lines
from line 111
111111```
112112
113113* The client **SHOULD NOT** send requests other than
114 [pings](/specification/2025-06-18/basic/utilities/ping) before the server has responded to the
114 [pings](/specification/2025-06-18/basic/utilities/ping.md) before the server has responded to the
115115 `initialize` request.
116116* The server **SHOULD NOT** send requests other than
117 [pings](/specification/2025-06-18/basic/utilities/ping) and
118 [logging](/specification/2025-06-18/server/utilities/logging) before receiving the `initialized`
117 [pings](/specification/2025-06-18/basic/utilities/ping.md) and
118 [logging](/specification/2025-06-18/server/utilities/logging.md) before receiving the `initialized`
119119 notification.
120120
121121#### Version Negotiation
from line 134
134134>
135135> If using HTTP, the client **MUST** include the `MCP-Protocol-Version: <protocol-version>` HTTP header on all subsequent requests to the MCP
136136> server.
137> For details, see [the Protocol Version Header section in Transports](/specification/2025-06-18/basic/transports#protocol-version-header).
137> For details, see [the Protocol Version Header section in Transports](/specification/2025-06-18/basic/transports.md#protocol-version-header).
138138
139139#### Capability Negotiation
140140
from line 145
145145
146146| Category | Capability | Description |
147147| - | - | - |
148| Client | `roots` | Ability to provide filesystem [roots](/specification/2025-06-18/client/roots) |
149| Client | `sampling` | Support for LLM [sampling](/specification/2025-06-18/client/sampling) requests |
150| Client | `elicitation` | Support for server [elicitation](/specification/2025-06-18/client/elicitation) requests |
148| Client | `roots` | Ability to provide filesystem [roots](/specification/2025-06-18/client/roots.md) |
149| Client | `sampling` | Support for LLM [sampling](/specification/2025-06-18/client/sampling.md) requests |
150| Client | `elicitation` | Support for server [elicitation](/specification/2025-06-18/client/elicitation.md) requests |
151151| Client | `experimental` | Describes support for non-standard experimental features |
152| Server | `prompts` | Offers [prompt templates](/specification/2025-06-18/server/prompts) |
153| Server | `resources` | Provides readable [resources](/specification/2025-06-18/server/resources) |
154| Server | `tools` | Exposes callable [tools](/specification/2025-06-18/server/tools) |
155| Server | `logging` | Emits structured [log messages](/specification/2025-06-18/server/utilities/logging) |
156| Server | `completions` | Supports argument [autocompletion](/specification/2025-06-18/server/utilities/completion) |
152| Server | `prompts` | Offers [prompt templates](/specification/2025-06-18/server/prompts.md) |
153| Server | `resources` | Provides readable [resources](/specification/2025-06-18/server/resources.md) |
154| Server | `tools` | Exposes callable [tools](/specification/2025-06-18/server/tools.md) |
155| Server | `logging` | Emits structured [log messages](/specification/2025-06-18/server/utilities/logging.md) |
156| Server | `completions` | Supports argument [autocompletion](/specification/2025-06-18/server/utilities/completion.md) |
157157| Server | `experimental` | Describes support for non-standard experimental features |
158158
159159Capability objects can describe sub-capabilities like:
from line 180
180180
181181#### stdio
182182
183For the stdio [transport](/specification/2025-06-18/basic/transports), the client **SHOULD** initiate
183For the stdio [transport](/specification/2025-06-18/basic/transports.md), the client **SHOULD** initiate
184184shutdown by:
185185
1861861. First, closing the input stream to the child process (the server)
from line 193
193193
194194#### HTTP
195195
196For HTTP [transports](/specification/2025-06-18/basic/transports), shutdown is indicated by closing the
196For HTTP [transports](/specification/2025-06-18/basic/transports.md), shutdown is indicated by closing the
197197associated HTTP connection(s).
198198
199199## Timeouts
from line 201
201201Implementations **SHOULD** establish timeouts for all sent requests, to prevent hung
202202connections and resource exhaustion. When the request has not received a success or error
203203response within the timeout period, the sender **SHOULD** issue a [cancellation
204notification](/specification/2025-06-18/basic/utilities/cancellation) for that request and stop waiting for
204notification](/specification/2025-06-18/basic/utilities/cancellation.md) for that request and stop waiting for
205205a response.
206206
207207SDKs and other middleware **SHOULD** allow these timeouts to be configured on a
from line 208
208208per-request basis.
209209
210210Implementations **MAY** choose to reset the timeout clock when receiving a [progress
211notification](/specification/2025-06-18/basic/utilities/progress) corresponding to the request, as this
211notification](/specification/2025-06-18/basic/utilities/progress.md) corresponding to the request, as this
212212implies that work is actually happening. However, implementations **SHOULD** always
213213enforce a maximum timeout, regardless of progress notifications, to limit the impact of a
214214misbehaving client or server.
specification/2025-06-18/basic/transports Changed · +4 / -4 lines
from line 48
4848> [!NOTE]
4949>
5050> This replaces the [HTTP+SSE
51> transport](/specification/2024-11-05/basic/transports#http-with-sse) from
51> transport](/specification/2024-11-05/basic/transports.md#http-with-sse) from
5252> protocol version 2024-11-05. See the [backwards compatibility](#backwards-compatibility)
5353> guide below.
5454
from line 164
164164### Session Management
165165
166166An MCP "session" consists of logically related interactions between a client and a
167server, beginning with the [initialization phase](/specification/2025-06-18/basic/lifecycle). To support
167server, beginning with the [initialization phase](/specification/2025-06-18/basic/lifecycle.md). To support
168168servers which want to establish stateful sessions:
169169
1701701. A server using the Streamable HTTP transport **MAY** assign a session ID at
from line 239
239239For example: `MCP-Protocol-Version: 2025-06-18`
240240
241241The protocol version sent by the client **SHOULD** be the one [negotiated during
242initialization](/specification/2025-06-18/basic/lifecycle#version-negotiation).
242initialization](/specification/2025-06-18/basic/lifecycle.md#version-negotiation).
243243
244244For backwards compatibility, if the server does *not* receive an `MCP-Protocol-Version`
245245header, and has no other way to identify the version - for example, by relying on the
from line 252
252252### Backwards Compatibility
253253
254254Clients and servers can maintain backwards compatibility with the deprecated [HTTP+SSE
255transport](/specification/2024-11-05/basic/transports#http-with-sse) (from
255transport](/specification/2024-11-05/basic/transports.md#http-with-sse) (from
256256protocol version 2024-11-05) as follows:
257257
258258**Servers** wanting to support older clients should:
specification/2025-06-18/changelog Changed · +10 / -10 lines
from line 1
11# Key Changes
22
33This document lists changes made to the Model Context Protocol (MCP) specification since
4the previous revision, [2025-03-26](/specification/2025-03-26).
4the previous revision, [2025-03-26](/specification/2025-03-26.md).
55
66## Major changes
77
881. Remove support for JSON-RPC **[batching](https://www.jsonrpc.org/specification#batch)**
99 (PR [#416](https://github.com/modelcontextprotocol/specification/pull/416))
102. Add support for [structured tool output](/specification/2025-06-18/server/tools#structured-content)
102. Add support for [structured tool output](/specification/2025-06-18/server/tools.md#structured-content)
1111 (PR [#371](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/371))
123. Classify MCP servers as [OAuth Resource Servers](/specification/2025-06-18/basic/authorization#authorization-server-discovery),
123. Classify MCP servers as [OAuth Resource Servers](/specification/2025-06-18/basic/authorization.md#authorization-server-discovery),
1313 adding protected resource metadata to discover the corresponding Authorization server.
1414 (PR [#338](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/338))
15154. Require MCP clients to implement Resource Indicators as described in [RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html) to prevent
1616 malicious servers from obtaining access tokens.
1717 (PR [#734](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/734))
185. Clarify [security considerations](/specification/2025-06-18/basic/authorization#security-considerations) and best practices
19 in the authorization spec and in a new [security best practices page](/specification/2025-06-18/basic/security_best_practices).
206. Add support for **[elicitation](/specification/2025-06-18/client/elicitation)**, enabling servers to request additional
185. Clarify [security considerations](/specification/2025-06-18/basic/authorization.md#security-considerations) and best practices
19 in the authorization spec and in a new [security best practices page](/specification/2025-06-18/basic/security_best_practices.md).
206. Add support for **[elicitation](/specification/2025-06-18/client/elicitation.md)**, enabling servers to request additional
2121 information from users during interactions.
2222 (PR [#382](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/382))
237. Add support for **[resource links](/specification/2025-06-18/server/tools#resource-links)** in
237. Add support for **[resource links](/specification/2025-06-18/server/tools.md#resource-links)** in
2424 tool call results. (PR [#603](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/603))
258. Require [negotiated protocol version to be specified](/specification/2025-06-18/basic/transports#protocol-version-header)
258. Require [negotiated protocol version to be specified](/specification/2025-06-18/basic/transports.md#protocol-version-header)
2626 via `MCP-Protocol-Version` header in subsequent requests when using HTTP (PR [#548](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/548)).
279. Change **SHOULD** to **MUST** in [Lifecycle Operation](/specification/2025-06-18/basic/lifecycle#operation)
279. Change **SHOULD** to **MUST** in [Lifecycle Operation](/specification/2025-06-18/basic/lifecycle.md#operation)
2828
2929## Other schema changes
3030
31311. Add `_meta` field to additional interface types (PR [#710](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/710)),
32 and specify [proper usage](/specification/2025-06-18/basic#meta).
32 and specify [proper usage](/specification/2025-06-18/basic.md#meta).
33332. Add `context` field to `CompletionRequest`, providing for completion requests to include
3434 previously-resolved variables (PR [#598](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/598)).
35353. Add `title` field for human-friendly display names, so that `name` can be used as a programmatic
specification/2025-06-18/index Changed · +4 / -4 lines
from line 120
120120
121121Explore the detailed specification for each protocol component:
122122
123> **[Architecture](/specification/2025-06-18/architecture)**
123> **[Architecture](/specification/2025-06-18/architecture.md)**
124124
125> **[Base Protocol](/specification/2025-06-18/basic)**
125> **[Base Protocol](/specification/2025-06-18/basic.md)**
126126
127> **[Server Features](/specification/2025-06-18/server)**
127> **[Server Features](/specification/2025-06-18/server.md)**
128128
129129> **[Client Features](/specification/2025-06-18/client)**
130130
131> **[Contributing](/community/contributing)**
131> **[Contributing](/community/contributing.md)**
132132
specification/2025-06-18/server/index Changed · +3 / -3 lines
from line 20
2020
2121Explore these key primitives in more detail below:
2222
23> **[Prompts](/specification/2025-06-18/server/prompts)**
23> **[Prompts](/specification/2025-06-18/server/prompts.md)**
2424
25> **[Resources](/specification/2025-06-18/server/resources)**
25> **[Resources](/specification/2025-06-18/server/resources.md)**
2626
27> **[Tools](/specification/2025-06-18/server/tools)**
27> **[Tools](/specification/2025-06-18/server/tools.md)**
2828
specification/2025-06-18/server/prompts Changed · +4 / -4 lines
from line 24
2424## Capabilities
2525
2626Servers that support prompts **MUST** declare the `prompts` capability during
27[initialization](/specification/2025-06-18/basic/lifecycle#initialization):
27[initialization](/specification/2025-06-18/basic/lifecycle.md#initialization):
2828
2929```json theme={null}
3030{
from line 44
4444### Listing Prompts
4545
4646To retrieve available prompts, clients send a `prompts/list` request. This operation
47supports [pagination](/specification/2025-06-18/server/utilities/pagination).
47supports [pagination](/specification/2025-06-18/server/utilities/pagination.md).
4848
4949**Request:**
5050
from line 88
8888### Getting a Prompt
8989
9090To retrieve a specific prompt, clients send a `prompts/get` request. Arguments may be
91auto-completed through [the completion API](/specification/2025-06-18/server/utilities/completion).
91auto-completed through [the completion API](/specification/2025-06-18/server/utilities/completion.md).
9292
9393**Request:**
9494
from line 183
183183> [!NOTE]
184184>
185185> All content types in prompt messages support optional
186> [annotations](/specification/2025-06-18/server/resources#annotations) for
186> [annotations](/specification/2025-06-18/server/resources.md#annotations) for
187187> metadata about audience, priority, and modification times.
188188
189189#### Text Content
specification/2025-06-18/server/resources Changed · +3 / -3 lines
from line 81
8181### Listing Resources
8282
8383To discover available resources, clients send a `resources/list` request. This operation
84supports [pagination](/specification/2025-06-18/server/utilities/pagination).
84supports [pagination](/specification/2025-06-18/server/utilities/pagination.md).
8585
8686**Request:**
8787
from line 156
156156
157157Resource templates allow servers to expose parameterized resources using
158158[URI templates](https://datatracker.ietf.org/doc/html/rfc6570). Arguments may be
159auto-completed through [the completion API](/specification/2025-06-18/server/utilities/completion).
160This operation supports [pagination](/specification/2025-06-18/server/utilities/pagination).
159auto-completed through [the completion API](/specification/2025-06-18/server/utilities/completion.md).
160This operation supports [pagination](/specification/2025-06-18/server/utilities/pagination.md).
161161
162162**Request:**
163163
specification/2025-06-18/server/tools Changed · +7 / -7 lines
from line 49
4949### Listing Tools
5050
5151To discover available tools, clients send a `tools/list` request. This operation supports
52[pagination](/specification/2025-06-18/server/utilities/pagination).
52[pagination](/specification/2025-06-18/server/utilities/pagination.md).
5353
5454**Request:**
5555
from line 197
197197>
198198> All content types (text, image, audio, resource links, and embedded resources)
199199> support optional
200> [annotations](/specification/2025-06-18/server/resources#annotations) that
200> [annotations](/specification/2025-06-18/server/resources.md#annotations) that
201201> provide metadata about audience, priority, and modification times. This is the
202202> same annotation format used by resources and prompts.
203203
from line 238
238238
239239#### Resource Links
240240
241A tool **MAY** return links to [Resources](/specification/2025-06-18/server/resources), to provide additional context
241A tool **MAY** return links to [Resources](/specification/2025-06-18/server/resources.md), to provide additional context
242242or data. In this case, the tool will return a URI that can be subscribed to or fetched by the client:
243243
244244```json theme={null}
from line 255
255255}
256256```
257257
258Resource links support the same [Resource annotations](/specification/2025-06-18/server/resources#annotations) as regular resources to help clients understand how to use them.
258Resource links support the same [Resource annotations](/specification/2025-06-18/server/resources.md#annotations) as regular resources to help clients understand how to use them.
259259
260260> [!NOTE]
261261>
from line 264
264264
265265#### Embedded Resources
266266
267[Resources](/specification/2025-06-18/server/resources) **MAY** be embedded to provide additional context
268or data using a suitable [URI scheme](./resources#common-uri-schemes). Servers that use embedded resources **SHOULD** implement the `resources` capability:
267[Resources](/specification/2025-06-18/server/resources.md) **MAY** be embedded to provide additional context
268or data using a suitable [URI scheme](/specification/2025-06-18/server/resources.md#common-uri-schemes). Servers that use embedded resources **SHOULD** implement the `resources` capability:
269269
270270```json theme={null}
271271{
from line 283
283283}
284284```
285285
286Embedded resources support the same [Resource annotations](/specification/2025-06-18/server/resources#annotations) as regular resources to help clients understand how to use them.
286Embedded resources support the same [Resource annotations](/specification/2025-06-18/server/resources.md#annotations) as regular resources to help clients understand how to use them.
287287
288288#### Structured Content
289289
specification/2025-11-25/basic/authorization Changed · +5 / -5 lines
from line 340
340340
341341This approach minimizes user friction while following the principle of least privilege.
342342The `scopes_supported` field is intended to represent the minimal set of scopes necessary
343for basic functionality (see [Scope Minimization](/specification/2025-11-25/basic/security_best_practices#scope-minimization)),
343for basic functionality (see [Scope Minimization](/specification/2025-11-25/basic/security_best_practices.md#scope-minimization)),
344344with additional scopes requested incrementally through the step-up authorization flow steps
345345described in the [Scope Challenge Handling](#scope-challenge-handling) section.
346346
from line 564
564564* MCP clients **MUST** include the `resource` parameter in authorization and token requests as specified in the [Resource Parameter Implementation](#resource-parameter-implementation) section
565565* MCP servers **MUST** validate that tokens presented to them were specifically issued for their use
566566
567The [Security Best Practices document](/specification/2025-11-25/basic/security_best_practices#token-passthrough)
567The [Security Best Practices document](/specification/2025-11-25/basic/security_best_practices.md#token-passthrough)
568568outlines why token audience validation is crucial and why token passthrough is explicitly forbidden.
569569
570570### Token Theft
from line 665
665665
666666### Confused Deputy Problem
667667
668Attackers can exploit MCP servers acting as intermediaries to third-party APIs, leading to [confused deputy vulnerabilities](/specification/2025-11-25/basic/security_best_practices#confused-deputy-problem).
668Attackers can exploit MCP servers acting as intermediaries to third-party APIs, leading to [confused deputy vulnerabilities](/specification/2025-11-25/basic/security_best_practices.md#confused-deputy-problem).
669669By using stolen authorization codes, they can obtain access tokens without user consent.
670670
671671MCP proxy servers using static client IDs **MUST** obtain user consent for each dynamically
from line 678
678678This vulnerability has two critical dimensions:
679679
6806801. **Audience validation failures.** When an MCP server doesn't verify that tokens were specifically intended for it (for example, via the audience claim, as mentioned in [RFC9068](https://www.rfc-editor.org/rfc/rfc9068.html)), it may accept tokens originally issued for other services. This breaks a fundamental OAuth security boundary, allowing attackers to reuse legitimate tokens across different services than intended.
6812. **Token passthrough.** If the MCP server not only accepts tokens with incorrect audiences but also forwards these unmodified tokens to downstream services, it can potentially cause the ["confused deputy" problem](#confused-deputy-problem), where the downstream API may incorrectly trust the token as if it came from the MCP server or assume the token was validated by the upstream API. See the [Token Passthrough section](/specification/2025-11-25/basic/security_best_practices#token-passthrough) of the Security Best Practices guide for additional details.
6812. **Token passthrough.** If the MCP server not only accepts tokens with incorrect audiences but also forwards these unmodified tokens to downstream services, it can potentially cause the ["confused deputy" problem](#confused-deputy-problem), where the downstream API may incorrectly trust the token as if it came from the MCP server or assume the token was validated by the upstream API. See the [Token Passthrough section](/specification/2025-11-25/basic/security_best_practices.md#token-passthrough) of the Security Best Practices guide for additional details.
682682
683683MCP servers **MUST** validate access tokens before processing the request, ensuring the access token is issued specifically for the MCP server, and take all necessary steps to ensure no data is returned to unauthorized parties.
684684
685685A MCP server **MUST** follow the guidelines in [OAuth 2.1 - Section 5.2](https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-13.html#section-5.2) to validate inbound tokens.
686686
687MCP servers **MUST** only accept tokens specifically intended for themselves and **MUST** reject tokens that do not include them in the audience claim or otherwise verify that they are the intended recipient of the token. See the [Security Best Practices Token Passthrough section](/specification/2025-11-25/basic/security_best_practices#token-passthrough) for details.
687MCP servers **MUST** only accept tokens specifically intended for themselves and **MUST** reject tokens that do not include them in the audience claim or otherwise verify that they are the intended recipient of the token. See the [Security Best Practices Token Passthrough section](/specification/2025-11-25/basic/security_best_practices.md#token-passthrough) for details.
688688
689689If the MCP server makes requests to upstream APIs, it may act as an OAuth client to them. The access token used at the upstream API is a separate token, issued by the upstream authorization server. The MCP server **MUST NOT** pass through the token it received from the MCP client.
690690
specification/2025-11-25/basic/index Changed · +5 / -5 lines
from line 26
2626
2727### Requests
2828
29[Requests](/specification/2025-11-25/schema#jsonrpcrequest) are sent from the client to the server or vice versa, to initiate an operation.
29[Requests](/specification/2025-11-25/schema.md#jsonrpcrequest) are sent from the client to the server or vice versa, to initiate an operation.
3030
3131```typescript theme={null}
3232{
from line 50
5050
5151#### Result Responses
5252
53[Result responses](/specification/2025-11-25/schema#jsonrpcresultresponse) are sent when the operation completes successfully.
53[Result responses](/specification/2025-11-25/schema.md#jsonrpcresultresponse) are sent when the operation completes successfully.
5454
5555```typescript theme={null}
5656{
from line 68
6868
6969#### Error Responses
7070
71[Error responses](/specification/2025-11-25/schema#jsonrpcerrorresponse) are sent when the operation fails or encounters an error.
71[Error responses](/specification/2025-11-25/schema.md#jsonrpcerrorresponse) are sent when the operation fails or encounters an error.
7272
7373```typescript theme={null}
7474{
from line 88
8888
8989### Notifications
9090
91[Notifications](/specification/2025-11-25/schema#jsonrpcnotification) are sent from the client to the server or vice versa, as a one-way message.
91[Notifications](/specification/2025-11-25/schema.md#jsonrpcnotification) are sent from the client to the server or vice versa, as a one-way message.
9292The receiver **MUST NOT** send a response.
9393
9494```typescript theme={null}
from line 105
105105
106106## Auth
107107
108MCP provides an [Authorization](/specification/2025-11-25/basic/authorization) framework for use with HTTP.
108MCP provides an [Authorization](/specification/2025-11-25/basic/authorization.md) framework for use with HTTP.
109109Implementations using an HTTP-based transport **SHOULD** conform to this specification,
110110whereas implementations using STDIO transport **SHOULD NOT** follow this specification,
111111and instead retrieve credentials from the environment.
specification/2025-11-25/basic/lifecycle Changed · +18 / -18 lines
from line 151
151151```
152152
153153* The client **SHOULD NOT** send requests other than
154 [pings](/specification/2025-11-25/basic/utilities/ping) before the server has responded to the
154 [pings](/specification/2025-11-25/basic/utilities/ping.md) before the server has responded to the
155155 `initialize` request.
156156* The server **SHOULD NOT** send requests other than
157 [pings](/specification/2025-11-25/basic/utilities/ping) and
158 [logging](/specification/2025-11-25/server/utilities/logging) before receiving the `initialized`
157 [pings](/specification/2025-11-25/basic/utilities/ping.md) and
158 [logging](/specification/2025-11-25/server/utilities/logging.md) before receiving the `initialized`
159159 notification.
160160
161161#### Version Negotiation
from line 174
174174>
175175> If using HTTP, the client **MUST** include the `MCP-Protocol-Version: <protocol-version>` HTTP header on all subsequent requests to the MCP
176176> server.
177> For details, see [the Protocol Version Header section in Transports](/specification/2025-11-25/basic/transports#protocol-version-header).
177> For details, see [the Protocol Version Header section in Transports](/specification/2025-11-25/basic/transports.md#protocol-version-header).
178178
179179#### Capability Negotiation
180180
from line 185
185185
186186| Category | Capability | Description |
187187| - | - | - |
188| Client | `roots` | Ability to provide filesystem [roots](/specification/2025-11-25/client/roots) |
189| Client | `sampling` | Support for LLM [sampling](/specification/2025-11-25/client/sampling) requests |
190| Client | `elicitation` | Support for server [elicitation](/specification/2025-11-25/client/elicitation) requests |
191| Client | `tasks` | Support for [task-augmented](/specification/2025-11-25/basic/utilities/tasks) client requests |
188| Client | `roots` | Ability to provide filesystem [roots](/specification/2025-11-25/client/roots.md) |
189| Client | `sampling` | Support for LLM [sampling](/specification/2025-11-25/client/sampling.md) requests |
190| Client | `elicitation` | Support for server [elicitation](/specification/2025-11-25/client/elicitation.md) requests |
191| Client | `tasks` | Support for [task-augmented](/specification/2025-11-25/basic/utilities/tasks.md) client requests |
192192| Client | `experimental` | Describes support for non-standard experimental features |
193| Server | `prompts` | Offers [prompt templates](/specification/2025-11-25/server/prompts) |
194| Server | `resources` | Provides readable [resources](/specification/2025-11-25/server/resources) |
195| Server | `tools` | Exposes callable [tools](/specification/2025-11-25/server/tools) |
196| Server | `logging` | Emits structured [log messages](/specification/2025-11-25/server/utilities/logging) |
197| Server | `completions` | Supports argument [autocompletion](/specification/2025-11-25/server/utilities/completion) |
198| Server | `tasks` | Support for [task-augmented](/specification/2025-11-25/basic/utilities/tasks) server requests |
193| Server | `prompts` | Offers [prompt templates](/specification/2025-11-25/server/prompts.md) |
194| Server | `resources` | Provides readable [resources](/specification/2025-11-25/server/resources.md) |
195| Server | `tools` | Exposes callable [tools](/specification/2025-11-25/server/tools.md) |
196| Server | `logging` | Emits structured [log messages](/specification/2025-11-25/server/utilities/logging.md) |
197| Server | `completions` | Supports argument [autocompletion](/specification/2025-11-25/server/utilities/completion.md) |
198| Server | `tasks` | Support for [task-augmented](/specification/2025-11-25/basic/utilities/tasks.md) server requests |
199199| Server | `experimental` | Describes support for non-standard experimental features |
200200
201201Capability objects can describe sub-capabilities like:
from line 222
222222
223223#### stdio
224224
225For the stdio [transport](/specification/2025-11-25/basic/transports), the client **SHOULD** initiate
225For the stdio [transport](/specification/2025-11-25/basic/transports.md), the client **SHOULD** initiate
226226shutdown by:
227227
2282281. First, closing the input stream to the child process (the server)
from line 235
235235
236236#### HTTP
237237
238For HTTP [transports](/specification/2025-11-25/basic/transports), shutdown is indicated by closing the
238For HTTP [transports](/specification/2025-11-25/basic/transports.md), shutdown is indicated by closing the
239239associated HTTP connection(s).
240240
241241## Timeouts
from line 243
243243Implementations **SHOULD** establish timeouts for all sent requests, to prevent hung
244244connections and resource exhaustion. When the request has not received a success or error
245245response within the timeout period, the sender **SHOULD** issue a [cancellation
246notification](/specification/2025-11-25/basic/utilities/cancellation) for that request and stop waiting for
246notification](/specification/2025-11-25/basic/utilities/cancellation.md) for that request and stop waiting for
247247a response.
248248
249249SDKs and other middleware **SHOULD** allow these timeouts to be configured on a
from line 250
250250per-request basis.
251251
252252Implementations **MAY** choose to reset the timeout clock when receiving a [progress
253notification](/specification/2025-11-25/basic/utilities/progress) corresponding to the request, as this
253notification](/specification/2025-11-25/basic/utilities/progress.md) corresponding to the request, as this
254254implies that work is actually happening. However, implementations **SHOULD** always
255255enforce a maximum timeout, regardless of progress notifications, to limit the impact of a
256256misbehaving client or server.
specification/2025-11-25/basic/transports Changed · +5 / -5 lines
from line 50
5050> [!NOTE]
5151>
5252> This replaces the [HTTP+SSE
53> transport](/specification/2024-11-05/basic/transports#http-with-sse) from
53> transport](/specification/2024-11-05/basic/transports.md#http-with-sse) from
5454> protocol version 2024-11-05. See the [backwards compatibility](#backwards-compatibility)
5555> guide below.
5656
from line 186
186186### Session Management
187187
188188An MCP "session" consists of logically related interactions between a client and a
189server, beginning with the [initialization phase](/specification/2025-11-25/basic/lifecycle). To support
189server, beginning with the [initialization phase](/specification/2025-11-25/basic/lifecycle.md). To support
190190servers which want to establish stateful sessions:
191191
1921921. A server using the Streamable HTTP transport **MAY** assign a session ID at
from line 196
196196 securely generated UUID, a JWT, or a cryptographic hash).
197197 * The session ID **MUST** only contain visible ASCII characters (ranging from 0x21 to
198198 0x7E).
199 * The client **MUST** handle the session ID in a secure manner, see [Session Hijacking mitigations](/specification/2025-11-25/basic/security_best_practices#session-hijacking) for more details.
199 * The client **MUST** handle the session ID in a secure manner, see [Session Hijacking mitigations](/specification/2025-11-25/basic/security_best_practices.md#session-hijacking) for more details.
2002002. If an `MCP-Session-Id` is returned by the server during initialization, clients using
201201 the Streamable HTTP transport **MUST** include it in the `MCP-Session-Id` header on
202202 all of their subsequent HTTP requests.
from line 262
262262For example: `MCP-Protocol-Version: 2025-11-25`
263263
264264The protocol version sent by the client **SHOULD** be the one [negotiated during
265initialization](/specification/2025-11-25/basic/lifecycle#version-negotiation).
265initialization](/specification/2025-11-25/basic/lifecycle.md#version-negotiation).
266266
267267For backwards compatibility, if the server does *not* receive an `MCP-Protocol-Version`
268268header, and has no other way to identify the version - for example, by relying on the
from line 275
275275### Backwards Compatibility
276276
277277Clients and servers can maintain backwards compatibility with the deprecated [HTTP+SSE
278transport](/specification/2024-11-05/basic/transports#http-with-sse) (from
278transport](/specification/2024-11-05/basic/transports.md#http-with-sse) (from
279279protocol version 2024-11-05) as follows:
280280
281281**Servers** wanting to support older clients should:
specification/2025-11-25/basic/utilities/tasks Changed · +4 / -4 lines
from line 177
177177>
178178> In the Streamable HTTP (SSE) transport, clients **MAY** disconnect from an SSE stream opened by the server in response to a `tasks/get` request at any time.
179179>
180> While this note is not prescriptive regarding the specific usage of SSE streams, all implementations **MUST** continue to comply with the existing [Streamable HTTP transport specification](../transports#sending-messages-to-the-server).
180> While this note is not prescriptive regarding the specific usage of SSE streams, all implementations **MUST** continue to comply with the existing [Streamable HTTP transport specification](/specification/2025-11-25/basic/transports.md#sending-messages-to-the-server).
181181
182182Requestors poll for task completion by sending [`tasks/get`](/specification/2025-11-25/schema#tasks%2Fget) requests.
183183Requestors **SHOULD** respect the `pollInterval` provided in responses when determining polling frequency.
from line 221
221221>
222222> In the Streamable HTTP (SSE) transport, clients **MAY** disconnect from an SSE stream opened by the server in response to a `tasks/result` request at any time.
223223>
224> While this note is not prescriptive regarding the specific usage of SSE streams, all implementations **MUST** continue to comply with the existing [Streamable HTTP transport specification](../transports#sending-messages-to-the-server).
224> While this note is not prescriptive regarding the specific usage of SSE streams, all implementations **MUST** continue to comply with the existing [Streamable HTTP transport specification](/specification/2025-11-25/basic/transports.md#sending-messages-to-the-server).
225225
226226After a task completes the operation result is retrieved via [`tasks/result`](/specification/2025-11-25/schema#tasks%2Fresult). This is distinct from the initial `CreateTaskResult` response, which contains only task data. The result structure matches the original request type (e.g., `CallToolResult` for `tools/call`).
227227
from line 428
428428> One possible approach is maintaining an SSE stream on `tasks/result` (see notes on the `input_required` status).
429429> Where possible, servers **SHOULD NOT** upgrade to an SSE stream in response to a `tasks/get` request, as the client has indicated it wishes to poll for a result.
430430>
431> While this note is not prescriptive regarding the specific usage of SSE streams, all implementations **MUST** continue to comply with the existing [Streamable HTTP transport specification](../transports#sending-messages-to-the-server).
431> While this note is not prescriptive regarding the specific usage of SSE streams, all implementations **MUST** continue to comply with the existing [Streamable HTTP transport specification](/specification/2025-11-25/basic/transports.md#sending-messages-to-the-server).
432432
4334331. When the task receiver has messages for the requestor that are necessary to complete the task, the receiver **SHOULD** move the task to the `input_required` status.
4344342. The receiver **MUST** include the `io.modelcontextprotocol/related-task` metadata in the request to associate it with the task.
from line 466
466466
467467### Task Progress Notifications
468468
469Task-augmented requests support progress notifications as defined in the [progress](./progress) specification. The `progressToken` provided in the initial request remains valid throughout the task lifetime.
469Task-augmented requests support progress notifications as defined in the [progress](/specification/2025-11-25/basic/utilities/progress.md) specification. The `progressToken` provided in the initial request remains valid throughout the task lifetime.
470470
471471### Task Listing
472472
specification/2025-11-25/changelog Changed · +4 / -4 lines
from line 1
11# Key Changes
22
33This document lists changes made to the Model Context Protocol (MCP) specification since
4the previous revision, [2025-06-18](/specification/2025-06-18).
4the previous revision, [2025-06-18](/specification/2025-06-18.md).
55
66## Major changes
77
from line 10
10103. Enhance authorization flows with incremental scope consent via `WWW-Authenticate` ([SEP-835](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/835))
11114. Provide guidance on tool names ([SEP-986](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1603))
12125. Update `ElicitResult` and `EnumSchema` to use a more standards-based approach and support titled, untitled, single-select, and multi-select enums ([SEP-1330](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1330)).
136. Added support for [URL mode elicitation](/specification/2025-11-25/client/elicitation#url-elicitation-requests) ([SEP-1036](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/887))
136. Added support for [URL mode elicitation](/specification/2025-11-25/client/elicitation.md#url-elicitation-requests) ([SEP-1036](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/887))
14147. Add tool calling support to sampling via `tools` and `toolChoice` parameters ([SEP-1577](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1577))
15158. Add support for OAuth Client ID Metadata Documents as a recommended client registration mechanism ([SEP-991](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/991), PR [#1296](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1296))
169. Add experimental support for [tasks](/specification/2025-11-25/basic/utilities/tasks) to enable tracking durable requests with polling and deferred result retrieval ([SEP-1686](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1686)).
169. Add experimental support for [tasks](/specification/2025-11-25/basic/utilities/tasks.md) to enable tracking durable requests with polling and deferred result retrieval ([SEP-1686](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1686)).
1717
1818## Minor changes
1919
from line 20
20201. Clarify that servers using stdio transport may use stderr for all types of logging, not just error messages (PR [#670](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/670)).
21212. Add optional `description` field to `Implementation` interface to align with MCP registry server.json format and provide human-readable context during initialization.
22223. Clarify that servers must respond with HTTP 403 Forbidden for invalid Origin headers in Streamable HTTP transport. (PR [#1439](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/1439))
234. Updated the [Security Best Practices guidance](https://modelcontextprotocol.io/specification/draft/basic/security_best_practices).
234. Updated the [Security Best Practices guidance](https://modelcontextprotocol.io/specification/draft/basic/security_best_practices.md).
24245. Clarify that input validation errors should be returned as Tool Execution Errors rather than Protocol Errors to enable model self-correction ([SEP-1303](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1303)).
25256. Support polling SSE streams by allowing servers to disconnect at will ([SEP-1699](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1699)).
26267. Clarify SEP-1699: GET streams support polling, resumption always via GET regardless of stream origin, event IDs should encode stream identity, disconnection includes server-initiated closure (Issue [#1847](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1847)).
specification/2025-11-25/client/elicitation Changed · +11 / -11 lines
from line 43
4343## Capabilities
4444
4545Clients that support elicitation **MUST** declare the `elicitation` capability during
46[initialization](../basic/lifecycle#initialization):
46[initialization](/specification/2025-11-25/basic/lifecycle.md#initialization):
4747
4848```json theme={null}
4949{
from line 342
342342>
343343> **Important**: URL mode elicitation is *not* for authorizing the MCP client's
344344> access to the MCP server (that's handled by [MCP
345> authorization](../basic/authorization)). Instead, it's used when the MCP
345> authorization](/specification/2025-11-25/basic/authorization.md)). Instead, it's used when the MCP
346346> server needs to obtain sensitive information or third-party authorization on
347347> behalf of the user. The MCP client's bearer token remains unchanged. The
348348> client's only responsibility is to provide the user with context about the
from line 567
567567* Whether required information has been collected (e.g., the user's display name via form mode elicitation)
568568* Status of resource access (e.g., API keys or a payment flow via URL mode elicitation)
569569
570Servers implementing elicitation **MUST** securely associate this state with individual users following the guidelines in the [security best practices](../basic/security_best_practices) document. Specifically:
570Servers implementing elicitation **MUST** securely associate this state with individual users following the guidelines in the [security best practices](/specification/2025-11-25/basic/security_best_practices.md) document. Specifically:
571571
572572* State **MUST NOT** be associated with session IDs alone
573573* State storage **MUST** be protected against unauthorized access
574* For remote MCP servers, user identification **MUST** be derived from credentials acquired via [MCP authorization](../basic/authorization) when possible (e.g. `sub` claim)
574* For remote MCP servers, user identification **MUST** be derived from credentials acquired via [MCP authorization](/specification/2025-11-25/basic/authorization.md) when possible (e.g. `sub` claim)
575575
576576> [!NOTE]
577577>
from line 596
596596### URL Mode Elicitation for OAuth Flows
597597
598598URL mode elicitation enables a pattern where MCP servers act as OAuth clients to third-party resource servers.
599Authorization with external APIs enabled by URL mode elicitation is separate from [MCP authorization](../basic/authorization). MCP servers **MUST NOT** rely on URL mode elicitation to authorize users for themselves.
599Authorization with external APIs enabled by URL mode elicitation is separate from [MCP authorization](/specification/2025-11-25/basic/authorization.md). MCP servers **MUST NOT** rely on URL mode elicitation to authorize users for themselves.
600600
601601#### Understanding the Distinction
602602
603* **MCP Authorization**: Required OAuth flow between the MCP client and MCP server (covered in the [authorization specification](../basic/authorization))
603* **MCP Authorization**: Required OAuth flow between the MCP client and MCP server (covered in the [authorization specification](/specification/2025-11-25/basic/authorization.md))
604604* **External (third-party) Authorization**: Optional authorization between the MCP server and a third-party resource server, initiated via URL mode elicitation
605605
606606In external authorization, the server acts as both:
from line 617
617617The critical security requirements are:
618618
6196191. **The third-party credentials MUST NOT transit through the MCP client**: The client must never see third-party credentials to protect the security boundary
6202. **The MCP server MUST NOT use the client's credentials for the third-party service**: That would be [token passthrough](../basic/security_best_practices#token-passthrough), which is forbidden
6202. **The MCP server MUST NOT use the client's credentials for the third-party service**: That would be [token passthrough](/specification/2025-11-25/basic/security_best_practices.md#token-passthrough), which is forbidden
6216213. **The user MUST authorize the MCP server directly**: The interaction happens outside the MCP protocol, without involving the MCP client
6226224. **The MCP server is responsible for tokens**: The MCP server is responsible for storing and managing the third-party tokens obtained through the URL mode elicitation (in other words, the MCP server must be stateful).
623623
from line 626
626626> [!NOTE]
627627>
628628> For additional background, refer to the [token passthrough
629> section](../basic/security_best_practices#token-passthrough) of the Security
629> section](/specification/2025-11-25/basic/security_best_practices.md#token-passthrough) of the Security
630630> Best Practices document to understand why MCP servers cannot act as
631631> pass-through proxies.
632632
from line 727
727727### Identifying the User
728728
729729Servers **MUST NOT** rely on client-provided user identification without server verification, as this can be forged.
730Instead, servers **SHOULD** follow [security best practices](../basic/security_best_practices).
730Instead, servers **SHOULD** follow [security best practices](/specification/2025-11-25/basic/security_best_practices.md).
731731
732732Non-normative examples:
733733
734734* Incorrect: Treat user input like "I am [[email protected]](mailto:[email protected])" as authoritative
735* Correct: Rely on [authorization](../basic/authorization) to identify the user
735* Correct: Rely on [authorization](/specification/2025-11-25/basic/authorization.md) to identify the user
736736
737737### Form Mode Security
738738
from line 744
744744
745745URL mode elicitation returns a URL that an attacker can use to send to a victim. The MCP Server **MUST** verify the identity of the user who opens the URL before accepting information.
746746
747Typically identity verification is done by leveraging the [MCP authorization server](../basic/authorization) to identify the user, through a session cookie or equivalent in the browser.
747Typically identity verification is done by leveraging the [MCP authorization server](/specification/2025-11-25/basic/authorization.md) to identify the user, through a session cookie or equivalent in the browser.
748748
749749For example, URL mode elicitation may be used to perform OAuth flows where the server acts as an OAuth client of another resource server. Without proper mitigation, the following phishing attack is possible:
750750
specification/2025-11-25/index Changed · +4 / -4 lines
from line 120
120120
121121Explore the detailed specification for each protocol component:
122122
123> **[Architecture](/specification/2025-11-25/architecture)**
123> **[Architecture](/specification/2025-11-25/architecture.md)**
124124
125> **[Base Protocol](/specification/2025-11-25/basic)**
125> **[Base Protocol](/specification/2025-11-25/basic.md)**
126126
127> **[Server Features](/specification/2025-11-25/server)**
127> **[Server Features](/specification/2025-11-25/server.md)**
128128
129129> **[Client Features](/specification/2025-11-25/client)**
130130
131> **[Contributing](/community/contributing)**
131> **[Contributing](/community/contributing.md)**
132132
specification/2025-11-25/server/index Changed · +3 / -3 lines
from line 20
2020
2121Explore these key primitives in more detail below:
2222
23> **[Prompts](/specification/2025-11-25/server/prompts)**
23> **[Prompts](/specification/2025-11-25/server/prompts.md)**
2424
25> **[Resources](/specification/2025-11-25/server/resources)**
25> **[Resources](/specification/2025-11-25/server/resources.md)**
2626
27> **[Tools](/specification/2025-11-25/server/tools)**
27> **[Tools](/specification/2025-11-25/server/tools.md)**
2828
specification/2025-11-25/server/prompts Changed · +4 / -4 lines
from line 24
2424## Capabilities
2525
2626Servers that support prompts **MUST** declare the `prompts` capability during
27[initialization](/specification/2025-11-25/basic/lifecycle#initialization):
27[initialization](/specification/2025-11-25/basic/lifecycle.md#initialization):
2828
2929```json theme={null}
3030{
from line 44
4444### Listing Prompts
4545
4646To retrieve available prompts, clients send a `prompts/list` request. This operation
47supports [pagination](/specification/2025-11-25/server/utilities/pagination).
47supports [pagination](/specification/2025-11-25/server/utilities/pagination.md).
4848
4949**Request:**
5050
from line 95
9595### Getting a Prompt
9696
9797To retrieve a specific prompt, clients send a `prompts/get` request. Arguments may be
98auto-completed through [the completion API](/specification/2025-11-25/server/utilities/completion).
98auto-completed through [the completion API](/specification/2025-11-25/server/utilities/completion.md).
9999
100100**Request:**
101101
from line 191
191191> [!NOTE]
192192>
193193> All content types in prompt messages support optional
194> [annotations](./resources#annotations) for metadata about audience, priority,
194> [annotations](/specification/2025-11-25/server/resources.md#annotations) for metadata about audience, priority,
195195> and modification times.
196196
197197#### Text Content
specification/2025-11-25/server/tools Changed · +11 / -11 lines
from line 49
4949### Listing Tools
5050
5151To discover available tools, clients send a `tools/list` request. This operation supports
52[pagination](/specification/2025-11-25/server/utilities/pagination).
52[pagination](/specification/2025-11-25/server/utilities/pagination.md).
5353
5454**Request:**
5555
from line 190
190190* `description`: Human-readable description of functionality
191191* `icons`: Optional array of icons for display in user interfaces
192192* `inputSchema`: JSON Schema defining expected parameters
193 * Follows the [JSON Schema usage guidelines](/specification/2025-11-25/basic#json-schema-usage)
193 * Follows the [JSON Schema usage guidelines](/specification/2025-11-25/basic.md#json-schema-usage)
194194 * Defaults to 2020-12 if no `$schema` field is present
195195 * **MUST** be a valid JSON Schema object (not `null`)
196196 * For tools with no parameters, use one of these valid approaches:
from line 197
197197 * `{ "type": "object", "additionalProperties": false }` - **Recommended**: explicitly accepts only empty objects
198198 * `{ "type": "object" }` - accepts any object (including with properties)
199199* `outputSchema`: Optional JSON Schema defining expected output structure
200 * Follows the [JSON Schema usage guidelines](/specification/2025-11-25/basic#json-schema-usage)
200 * Follows the [JSON Schema usage guidelines](/specification/2025-11-25/basic.md#json-schema-usage)
201201 * Defaults to 2020-12 if no `$schema` field is present
202202* `annotations`: Optional properties describing tool behavior
203203* `execution`: Optional object describing execution-related properties
204 * `taskSupport`: Indicates whether this tool supports [task-augmented execution](/specification/2025-11-25/basic/utilities/tasks#tool-level-negotiation). Values: `"forbidden"` (default), `"optional"`, or `"required"`
204 * `taskSupport`: Indicates whether this tool supports [task-augmented execution](/specification/2025-11-25/basic/utilities/tasks.md#tool-level-negotiation). Values: `"forbidden"` (default), `"optional"`, or `"required"`
205205
206206> [!WARNING]
207207>
from line 231
231231>
232232> All content types (text, image, audio, resource links, and embedded resources)
233233> support optional
234> [annotations](/specification/2025-11-25/server/resources#annotations) that
234> [annotations](/specification/2025-11-25/server/resources.md#annotations) that
235235> provide metadata about audience, priority, and modification times. This is the
236236> same annotation format used by resources and prompts.
237237
from line 270
270270
271271#### Resource Links
272272
273A tool **MAY** return links to [Resources](/specification/2025-11-25/server/resources), to provide additional context
273A tool **MAY** return links to [Resources](/specification/2025-11-25/server/resources.md), to provide additional context
274274or data. In this case, the tool will return a URI that can be subscribed to or fetched by the client:
275275
276276```json theme={null}
from line 283
283283}
284284```
285285
286Resource links support the same [Resource annotations](/specification/2025-11-25/server/resources#annotations) as regular resources to help clients understand how to use them.
286Resource links support the same [Resource annotations](/specification/2025-11-25/server/resources.md#annotations) as regular resources to help clients understand how to use them.
287287
288288> [!NOTE]
289289>
from line 292
292292
293293#### Embedded Resources
294294
295[Resources](/specification/2025-11-25/server/resources) **MAY** be embedded to provide additional context
296or data using a suitable [URI scheme](./resources#common-uri-schemes). Servers that use embedded resources **SHOULD** implement the `resources` capability:
295[Resources](/specification/2025-11-25/server/resources.md) **MAY** be embedded to provide additional context
296or data using a suitable [URI scheme](/specification/2025-11-25/server/resources.md#common-uri-schemes). Servers that use embedded resources **SHOULD** implement the `resources` capability:
297297
298298```json theme={null}
299299{
from line 311
311311}
312312```
313313
314Embedded resources support the same [Resource annotations](/specification/2025-11-25/server/resources#annotations) as regular resources to help clients understand how to use them.
314Embedded resources support the same [Resource annotations](/specification/2025-11-25/server/resources.md#annotations) as regular resources to help clients understand how to use them.
315315
316316#### Structured Content
317317
from line 455
455455
4564561. **Protocol Errors**: Standard JSON-RPC errors for issues like:
457457 * Unknown tools
458 * Malformed requests (requests that fail to satisfy [CallToolRequest schema](/specification/2025-11-25/schema#calltoolrequest))
458 * Malformed requests (requests that fail to satisfy [CallToolRequest schema](/specification/2025-11-25/schema.md#calltoolrequest))
459459 * Server errors
460460
4614612. **Tool Execution Errors**: Reported in tool results with `isError: true`:
specification/2026-07-28/basic/authorization/index Changed · +11 / -11 lines
from line 49
4949
5050The *authorization server* is responsible for interacting with the user (if necessary) and issuing access tokens for use at the MCP server.
5151The implementation details of the authorization server are beyond the scope of this specification. It may be hosted with the
52resource server or a separate entity. [Authorization Server Discovery](/specification/2026-07-28/basic/authorization/authorization-server-discovery)
52resource server or a separate entity. [Authorization Server Discovery](/specification/2026-07-28/basic/authorization/authorization-server-discovery.md)
5353specifies how an MCP server indicates the location of its corresponding authorization server to a client.
5454
5555## Overview
from line 57
57571. Authorization servers **MUST** implement OAuth 2.1 with appropriate security
5858 measures for both confidential and public clients.
5959
602. Authorization servers and MCP clients **SHOULD** support [OAuth Client ID Metadata Documents](/specification/2026-07-28/basic/authorization/client-registration#client-id-metadata-documents)
602. Authorization servers and MCP clients **SHOULD** support [OAuth Client ID Metadata Documents](/specification/2026-07-28/basic/authorization/client-registration.md#client-id-metadata-documents)
6161 ([draft-ietf-oauth-client-id-metadata-document-00](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-00)).
6262
63633. Authorization servers and MCP clients **MAY** support the OAuth 2.0 Dynamic Client Registration
6464 Protocol ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)). Note that
65 [Dynamic Client Registration](/specification/2026-07-28/basic/authorization/client-registration#dynamic-client-registration)
65 [Dynamic Client Registration](/specification/2026-07-28/basic/authorization/client-registration.md#dynamic-client-registration)
6666 is deprecated and retained for backwards compatibility with authorization servers that do not support Client ID Metadata Documents.
6767
68684. MCP servers **MUST** implement OAuth 2.0 Protected Resource Metadata ([RFC9728](https://datatracker.ietf.org/doc/html/rfc9728)).
69 MCP clients **MUST** use OAuth 2.0 Protected Resource Metadata for [authorization server discovery](/specification/2026-07-28/basic/authorization/authorization-server-discovery).
69 MCP clients **MUST** use OAuth 2.0 Protected Resource Metadata for [authorization server discovery](/specification/2026-07-28/basic/authorization/authorization-server-discovery.md).
7070
71715. MCP authorization servers **MUST** provide at least one of the following discovery mechanisms:
7272
from line 73
7373 * OAuth 2.0 Authorization Server Metadata ([RFC8414](https://datatracker.ietf.org/doc/html/rfc8414))
7474 * [OpenID Connect Discovery 1.0](https://openid.net/specs/openid-connect-discovery-1_0.html)
7575
76 MCP clients **MUST** support both [discovery mechanisms](/specification/2026-07-28/basic/authorization/authorization-server-discovery#authorization-server-metadata-discovery) to obtain the information required to interact with the authorization server.
76 MCP clients **MUST** support both [discovery mechanisms](/specification/2026-07-28/basic/authorization/authorization-server-discovery.md#authorization-server-metadata-discovery) to obtain the information required to interact with the authorization server.
7777
7878## Authorization Server Discovery
7979
from line 81
8181Resource Metadata, and MCP clients determine authorization server endpoints and supported
8282capabilities through authorization server metadata discovery. Implementations **MUST**
8383follow the normative discovery requirements defined in
84[Authorization Server Discovery](/specification/2026-07-28/basic/authorization/authorization-server-discovery).
84[Authorization Server Discovery](/specification/2026-07-28/basic/authorization/authorization-server-discovery.md).
8585
8686## Client Registration
8787
from line 88
8888Before initiating the authorization flow, MCP clients **MUST** obtain a client ID through
8989one of three registration mechanisms: Client ID Metadata Documents, pre-registration, or
9090Dynamic Client Registration, following the requirements and selection priority defined in
91[Client Registration](/specification/2026-07-28/basic/authorization/client-registration).
91[Client Registration](/specification/2026-07-28/basic/authorization/client-registration.md).
9292
9393## Scope Selection Strategy
9494
from line 125
1251252. **If `scope` is not available**, use all scopes defined in `scopes_supported` from the Protected Resource Metadata document, omitting the `scope` parameter if `scopes_supported` is undefined.
126126
127127The `scopes_supported` field is intended to represent the minimal set of scopes necessary
128for basic functionality (see [Scope Minimization](/docs/2026-07-28/tutorials/security/security_best_practices#scope-minimization)),
128for basic functionality (see [Scope Minimization](/docs/2026-07-28/tutorials/security/security_best_practices.md#scope-minimization)),
129129with additional scopes requested incrementally through the step-up authorization flow steps
130130described in the [Scope Challenge Handling](#scope-challenge-handling) section.
131131
from line 132
132132## Authorization Flow Steps
133133
134134The registration step shown in the flow uses one of the mechanisms defined in
135[Client Registration](/specification/2026-07-28/basic/authorization/client-registration).
135[Client Registration](/specification/2026-07-28/basic/authorization/client-registration.md).
136136
137137The complete Authorization flow proceeds as follows:
138138
from line 185
185185
186186### Authorization Response Validation
187187
188Before redirecting the user-agent, the client **MUST** record the `issuer` value from the selected authorization server's validated metadata document (see [Authorization Server Metadata Discovery](/specification/2026-07-28/basic/authorization/authorization-server-discovery#authorization-server-metadata-discovery)) and associate it with the same per-request record used to store the PKCE code verifier (and the `state` value, if used). The validation in this section depends on that recorded value being authentic; it provides no protection if the expected issuer was obtained from an unvalidated source.
188Before redirecting the user-agent, the client **MUST** record the `issuer` value from the selected authorization server's validated metadata document (see [Authorization Server Metadata Discovery](/specification/2026-07-28/basic/authorization/authorization-server-discovery.md#authorization-server-metadata-discovery)) and associate it with the same per-request record used to store the PKCE code verifier (and the `state` value, if used). The validation in this section depends on that recorded value being authentic; it provides no protection if the expected issuer was obtained from an unvalidated source.
189189
190190MCP authorization servers **SHOULD** include the `iss` parameter in authorization responses, including error responses, as defined in [RFC9207 Section 2](https://datatracker.ietf.org/doc/html/rfc9207#section-2). Authorization servers that include the `iss` parameter **MUST** advertise this by setting `authorization_response_iss_parameter_supported` to `true` in their metadata ([RFC9207 Section 2.3](https://datatracker.ietf.org/doc/html/rfc9207#section-2.3)).
191191
from line 403
403403## Security Considerations
404404
405405Implementations of this specification **MUST** follow the normative security
406requirements in [Security Considerations](/specification/2026-07-28/basic/authorization/security-considerations),
406requirements in [Security Considerations](/specification/2026-07-28/basic/authorization/security-considerations.md),
407407covering token audience binding and validation, token theft, communication security,
408408authorization code protection, mix-up and confused deputy attacks, open redirection,
409409and Client ID Metadata Document security.
specification/2026-07-28/basic/authorization/security-considerations Changed · +7 / -7 lines
from line 11
1111[RFC 8707](https://www.rfc-editor.org/rfc/rfc8707.html) Resource Indicators provide critical security benefits by binding tokens to their intended
1212audiences **when the Authorization Server supports the capability**. To enable current and future adoption:
1313
14* MCP clients **MUST** include the `resource` parameter in authorization and token requests as specified in the [Resource Parameter Implementation](/specification/2026-07-28/basic/authorization#resource-parameter-implementation) section
14* MCP clients **MUST** include the `resource` parameter in authorization and token requests as specified in the [Resource Parameter Implementation](/specification/2026-07-28/basic/authorization.md#resource-parameter-implementation) section
1515* MCP servers **MUST** validate that tokens presented to them were specifically issued for their use
1616
17The [Security Best Practices document](/docs/2026-07-28/tutorials/security/security_best_practices#token-passthrough)
17The [Security Best Practices document](/docs/2026-07-28/tutorials/security/security_best_practices.md#token-passthrough)
1818outlines why token audience validation is crucial and why token passthrough is explicitly forbidden.
1919
2020## Token Theft
from line 57
5757
5858## Mix-Up Attacks
5959
60An attacker that controls one of the authorization servers an MCP client interacts with may attempt to have the client send it an authorization code or token issued by a different, honest authorization server (a mix-up attack, described in [RFC9207 Section 1](https://datatracker.ietf.org/doc/html/rfc9207#section-1)). [Authorization Response Validation](/specification/2026-07-28/basic/authorization#authorization-response-validation) specifies the required mitigation.
60An attacker that controls one of the authorization servers an MCP client interacts with may attempt to have the client send it an authorization code or token issued by a different, honest authorization server (a mix-up attack, described in [RFC9207 Section 1](https://datatracker.ietf.org/doc/html/rfc9207#section-1)). [Authorization Response Validation](/specification/2026-07-28/basic/authorization.md#authorization-response-validation) specifies the required mitigation.
6161
6262## Open Redirection
6363
from line 76
7676
7777## Client ID Metadata Document Security
7878
79When implementing [Client ID Metadata Documents](/specification/2026-07-28/basic/authorization/client-registration#client-id-metadata-documents), authorization servers **MUST** consider the security implications
79When implementing [Client ID Metadata Documents](/specification/2026-07-28/basic/authorization/client-registration.md#client-id-metadata-documents), authorization servers **MUST** consider the security implications
8080detailed in [OAuth Client ID Metadata Document, Section 6](https://datatracker.ietf.org/doc/html/draft-ietf-oauth-client-id-metadata-document-00#name-security-considerations).
8181Key considerations include:
8282
from line 101
101101
102102## Confused Deputy Problem
103103
104Attackers can exploit MCP servers acting as intermediaries to third-party APIs, leading to [confused deputy vulnerabilities](/docs/2026-07-28/tutorials/security/security_best_practices#confused-deputy-problem).
104Attackers can exploit MCP servers acting as intermediaries to third-party APIs, leading to [confused deputy vulnerabilities](/docs/2026-07-28/tutorials/security/security_best_practices.md#confused-deputy-problem).
105105By using stolen authorization codes, they can obtain access tokens without user consent.
106106
107107MCP proxy servers using static client IDs **MUST** obtain user consent for each
108[dynamically registered client](/specification/2026-07-28/basic/authorization/client-registration#dynamic-client-registration)
108[dynamically registered client](/specification/2026-07-28/basic/authorization/client-registration.md#dynamic-client-registration)
109109before forwarding to third-party authorization servers (which may require additional consent).
110110
111111## Access Token Privilege Restriction
from line 116
116116
117117A MCP server **MUST** follow the guidelines in [OAuth 2.1 - Section 5.2](https://www.ietf.org/archive/id/draft-ietf-oauth-v2-1-13.html#section-5.2) to validate inbound tokens.
118118
119MCP servers **MUST** only accept tokens specifically intended for themselves and **MUST** reject tokens that do not include them in the audience claim or otherwise verify that they are the intended recipient of the token. See the [Security Best Practices Token Passthrough section](/docs/2026-07-28/tutorials/security/security_best_practices#token-passthrough) for details.
119MCP servers **MUST** only accept tokens specifically intended for themselves and **MUST** reject tokens that do not include them in the audience claim or otherwise verify that they are the intended recipient of the token. See the [Security Best Practices Token Passthrough section](/docs/2026-07-28/tutorials/security/security_best_practices.md#token-passthrough) for details.
120120
121121If the MCP server makes requests to upstream APIs, it may act as an OAuth client to them. The access token used at the upstream API is a separate token, issued by the upstream authorization server. The MCP server **MUST NOT** pass through the token it received from the MCP client.
122122
specification/2026-07-28/basic/index Changed · +19 / -19 lines
from line 26
2626
2727### Requests
2828
29[Requests](/specification/2026-07-28/schema#jsonrpcrequest) are sent from the client to the server, to initiate an operation.
29[Requests](/specification/2026-07-28/schema.md#jsonrpcrequest) are sent from the client to the server, to initiate an operation.
3030
3131```typescript theme={null}
3232{
from line 50
5050
5151#### Result Responses
5252
53[Result responses](/specification/2026-07-28/schema#jsonrpcresultresponse) are sent when the operation completes successfully.
53[Result responses](/specification/2026-07-28/schema.md#jsonrpcresultresponse) are sent when the operation completes successfully.
5454
5555```typescript theme={null}
5656{
from line 82
8282
8383#### Error Responses
8484
85[Error responses](/specification/2026-07-28/schema#jsonrpcerrorresponse) are sent when the operation fails or encounters an error.
85[Error responses](/specification/2026-07-28/schema.md#jsonrpcerrorresponse) are sent when the operation fails or encounters an error.
8686
8787```typescript theme={null}
8888{
from line 117
117117 **MUST NOT** assume any specific meaning for these codes.
118118* **`-32020` to `-32099` — reserved for the MCP specification.** Error codes
119119 in this sub-range are defined exclusively by the MCP specification and
120 recorded in the [schema](/specification/2026-07-28/schema). Implementations
120 recorded in the [schema](/specification/2026-07-28/schema.md). Implementations
121121 **MUST NOT** emit any code from this sub-range that is not defined by this
122122 specification and **MUST** use defined codes only with their specified
123123 meanings.
from line 152
152152
153153### Notifications
154154
155[Notifications](/specification/2026-07-28/schema#jsonrpcnotification) are sent from the client to the server or vice versa, as a one-way message.
155[Notifications](/specification/2026-07-28/schema.md#jsonrpcnotification) are sent from the client to the server or vice versa, as a one-way message.
156156The receiver **MUST NOT** send a response.
157157
158158```typescript theme={null}
from line 169
169169
170170### Message Patterns
171171
172The Model Context Protocol (MCP) supports several [Message Patterns](/specification/2026-07-28/basic/patterns) that define how clients and servers interact:
172The Model Context Protocol (MCP) supports several [Message Patterns](/specification/2026-07-28/basic/patterns.md) that define how clients and servers interact:
173173
1741. **[Request and Response](/specification/2026-07-28/basic/patterns#request-and-response)**: A client sends a request to the server, and the server responds with a result or error.
1752. **[Multi Round-Trip Requests (MRTR)](/specification/2026-07-28/basic/patterns#multi-round-trip-requests)**: A server requires additional client input (sampling, elicitation, or roots) to complete a request.
1763. **[Subscribe and Notify](/specification/2026-07-28/basic/patterns#subscribe-and-notify)**: A client subscribes to a stream of notifications from the server, which are sent as they occur.
1741. **[Request and Response](/specification/2026-07-28/basic/patterns.md#request-and-response)**: A client sends a request to the server, and the server responds with a result or error.
1752. **[Multi Round-Trip Requests (MRTR)](/specification/2026-07-28/basic/patterns.md#multi-round-trip-requests)**: A server requires additional client input (sampling, elicitation, or roots) to complete a request.
1763. **[Subscribe and Notify](/specification/2026-07-28/basic/patterns.md#subscribe-and-notify)**: A client subscribes to a stream of notifications from the server, which are sent as they occur.
177177
178178## Statelessness
179179
from line 212
212212> [!NOTE]
213213>
214214> For a walkthrough of how the per-request model maps to SDK code, see the
215> [Architecture guide](/docs/2026-07-28/learn/architecture#example).
215> [Architecture guide](/docs/2026-07-28/learn/architecture.md#example).
216216
217217## Auth
218218
219MCP provides an [Authorization](/specification/2026-07-28/basic/authorization) framework for use with HTTP.
219MCP provides an [Authorization](/specification/2026-07-28/basic/authorization.md) framework for use with HTTP.
220220Implementations using an HTTP-based transport **SHOULD** conform to this specification,
221221whereas implementations using STDIO transport **SHOULD NOT** follow this specification,
222222and instead retrieve credentials from the environment.
from line 345
345345
346346| Key | Description | Defined in |
347347| - | - | - |
348| `progressToken` | Opts the request into progress notifications | [Progress](/specification/2026-07-28/basic/patterns/progress) |
348| `progressToken` | Opts the request into progress notifications | [Progress](/specification/2026-07-28/basic/patterns/progress.md) |
349349| `io.modelcontextprotocol/protocolVersion` | Protocol version for a request | Per-request protocol fields (below) |
350350| `io.modelcontextprotocol/clientInfo` | Client name and version | Per-request protocol fields (below) |
351351| `io.modelcontextprotocol/clientCapabilities` | Client capabilities relevant to a request | Per-request protocol fields (below) |
352| `io.modelcontextprotocol/logLevel` | Minimum log level the server should emit for a request | [Logging](/specification/2026-07-28/server/utilities/logging) |
353| `io.modelcontextprotocol/subscriptionId` | Correlates a notification with its originating subscription | [Subscriptions](/specification/2026-07-28/basic/patterns/subscriptions) |
352| `io.modelcontextprotocol/logLevel` | Minimum log level the server should emit for a request | [Logging](/specification/2026-07-28/server/utilities/logging.md) |
353| `io.modelcontextprotocol/subscriptionId` | Correlates a notification with its originating subscription | [Subscriptions](/specification/2026-07-28/basic/patterns/subscriptions.md) |
354354| `traceparent`, `tracestate`, `baggage` | OpenTelemetry trace context propagation | OpenTelemetry trace context (below) |
355355
356Official [extensions](/specification/2026-07-28/basic/versioning#extension-negotiation)
356Official [extensions](/specification/2026-07-28/basic/versioning.md#extension-negotiation)
357357define additional `_meta` keys under the `io.modelcontextprotocol/` prefix, and
358358third-party extensions use their own vendor prefix.
359359In both cases the keys are specified in the extension's documentation.
from line 409
409409the server **MUST** include `io.modelcontextprotocol/subscriptionId` in `_meta` so the
410410client can correlate the notification with the originating subscription request.
411411
412[lifecycle]: /specification/2026-07-28/basic/versioning
412[lifecycle]: /specification/2026-07-28/basic/versioning.md
413413
414[subscriptions-listen]: /specification/2026-07-28/basic/patterns/subscriptions
414[subscriptions-listen]: /specification/2026-07-28/basic/patterns/subscriptions.md
415415
416416**OpenTelemetry trace context:**
417417