One read of Model Context Protocolmcp-20261020T200724Z
306 pages moved out of 357 read.
Pages moved
306
significant first
Pages read
357
in this capture
Captured
20:07 UTC
Corpus hash
077a51951f96
corpus-hash
What this read moved
201-225 of 306, page 9 of 13This capture is too large to show at once. Changes 201-225 of 306 are below, significant first; the rest are on the following screens.
specification/2025-11-25/basic/lifecycle Changed · +5 / -7 lines
from line 1
11# Lifecycle
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol (MCP) defines a rigorous lifecycle for client-server
64connections that ensures proper capability negotiation and state management.
75
from line 170
172170If the client does not support the version in the server's response, it **SHOULD**
173171disconnect.
174172
175<Note>
176 If using HTTP, the client **MUST** include the `MCP-Protocol-Version: <protocol-version>` HTTP header on all subsequent requests to the MCP
177 server.
178 For details, see [the Protocol Version Header section in Transports](/specification/2025-11-25/basic/transports#protocol-version-header).
179</Note>
173> [!NOTE]
174>
175> If using HTTP, the client **MUST** include the `MCP-Protocol-Version: <protocol-version>` HTTP header on all subsequent requests to the MCP
176> server.
177> For details, see [the Protocol Version Header section in Transports](/specification/2025-11-25/basic/transports#protocol-version-header).
180178
181179#### Capability Negotiation
182180
specification/2025-11-25/basic/transports Changed · +6 / -8 lines
from line 1
11# Transports
22
3<div id="enable-section-numbers" />
4
53MCP uses JSON-RPC to encode messages. JSON-RPC messages **MUST** be UTF-8 encoded.
64
75The protocol currently defines two standard transport mechanisms for client-server
from line 47
4947
5048## Streamable HTTP
5149
52<Info>
53 This replaces the [HTTP+SSE
54 transport](/specification/2024-11-05/basic/transports#http-with-sse) from
55 protocol version 2024-11-05. See the [backwards compatibility](#backwards-compatibility)
56 guide below.
57</Info>
50> [!NOTE]
51>
52> This replaces the [HTTP+SSE
53> transport](/specification/2024-11-05/basic/transports#http-with-sse) from
54> protocol version 2024-11-05. See the [backwards compatibility](#backwards-compatibility)
55> guide below.
5856
5957In the **Streamable HTTP** transport, the server operates as an independent process that
6058can handle multiple client connections. This transport uses HTTP POST and GET requests.
specification/2025-11-25/basic/utilities/tasks Changed · +36 / -38 lines
from line 1
11# Tasks
22
3<div id="enable-section-numbers" />
3> [!NOTE]
4>
5> Tasks were introduced in version 2025-11-25 of the MCP specification and are currently considered **experimental**.
6> The design and behavior of tasks may evolve in future protocol versions.
47
5<Note>
6 Tasks were introduced in version 2025-11-25 of the MCP specification and are currently considered **experimental**.
7 The design and behavior of tasks may evolve in future protocol versions.
8</Note>
9
108The Model Context Protocol (MCP) allows requestors — which can be either clients or servers, depending on the direction of communication — to augment their requests with **tasks**. Tasks are durable state machines that carry information about the underlying execution state of the request they wrap, and are intended for requestor polling and deferred result retrieval. Each task is uniquely identifiable by a receiver-generated **task ID**.
119
1210Tasks are useful for representing expensive computations and batch processing requests, and integrate seamlessly with external job APIs.
from line 162
164162
165163When a receiver accepts a task-augmented request, it returns a [`CreateTaskResult`](/specification/2025-11-25/schema#createtaskresult) containing task data. The response does not include the actual operation result. The actual result (e.g., tool result for `tools/call`) becomes available only through `tasks/result` after the task completes.
166164
167<Note>
168 When a task is created in response to a `tools/call` request, host applications may wish to return control to the model while the task is executing. This allows the model to continue processing other requests or perform additional work while waiting for the task to complete.
165> [!NOTE]
166>
167> When a task is created in response to a `tools/call` request, host applications may wish to return control to the model while the task is executing. This allows the model to continue processing other requests or perform additional work while waiting for the task to complete.
168>
169> To support this pattern, servers can provide an optional `io.modelcontextprotocol/model-immediate-response` key in the `_meta` field of the `CreateTaskResult`. The value of this key should be a string intended to be passed as an immediate tool result to the model.
170> If a server does not provide this field, the host application can fall back to its own predefined message.
171>
172> This guidance is non-binding and is provisional logic intended to account for the specific use case. This behavior may be formalized or modified as part of `CreateTaskResult` in future protocol versions.
169173
170 To support this pattern, servers can provide an optional `io.modelcontextprotocol/model-immediate-response` key in the `_meta` field of the `CreateTaskResult`. The value of this key should be a string intended to be passed as an immediate tool result to the model.
171 If a server does not provide this field, the host application can fall back to its own predefined message.
172
173 This guidance is non-binding and is provisional logic intended to account for the specific use case. This behavior may be formalized or modified as part of `CreateTaskResult` in future protocol versions.
174</Note>
175
176174### Getting Tasks
177175
178<Note>
179 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.
176> [!NOTE]
177>
178> 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.
179>
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).
180181
181 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).
182</Note>
183
184182Requestors poll for task completion by sending [`tasks/get`](/specification/2025-11-25/schema#tasks%2Fget) requests.
185183Requestors **SHOULD** respect the `pollInterval` provided in responses when determining polling frequency.
186184
from line 217
219217
220218### Retrieving Task Results
221219
222<Note>
223 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.
220> [!NOTE]
221>
222> 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.
223>
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).
224225
225 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).
226</Note>
227
228226After 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`).
229227
230228To retrieve the result of a completed task, requestors can send a `tasks/result` request:
from line 418
420418
421419### Input Required Status
422420
423<Note>
424 With the Streamable HTTP (SSE) transport, servers often close SSE streams after delivering a response message, which can lead to ambiguity regarding the stream used for subsequent task messages.
421> [!NOTE]
422>
423> With the Streamable HTTP (SSE) transport, servers often close SSE streams after delivering a response message, which can lead to ambiguity regarding the stream used for subsequent task messages.
424>
425> Servers can handle this by enqueueing messages to the client to side-channel task-related messages alongside other responses.
426>
427> Servers have flexibility in how they manage SSE streams during task polling and result retrieval, and clients **SHOULD** expect messages to be delivered on any SSE stream, including the HTTP GET stream.
428> One possible approach is maintaining an SSE stream on `tasks/result` (see notes on the `input_required` status).
429> 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.
430>
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).
425432
426 Servers can handle this by enqueueing messages to the client to side-channel task-related messages alongside other responses.
427
428 Servers have flexibility in how they manage SSE streams during task polling and result retrieval, and clients **SHOULD** expect messages to be delivered on any SSE stream, including the HTTP GET stream.
429 One possible approach is maintaining an SSE stream on `tasks/result` (see notes on the `input_required` status).
430 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.
431
432 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).
433</Note>
434
4354331. 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.
4364342. The receiver **MUST** include the `io.modelcontextprotocol/related-task` metadata in the request to associate it with the task.
4374353. When the requestor encounters the `input_required` status, it **SHOULD** preemptively call `tasks/result`.
from line 801
803801}
804802```
805803
806<Note>
807 Receivers are not required to retain tasks indefinitely. It is compliant behavior for a receiver to return an error stating the task cannot be found if it has purged an expired task.
808</Note>
804> [!NOTE]
805>
806> Receivers are not required to retain tasks indefinitely. It is compliant behavior for a receiver to return an error stating the task cannot be found if it has purged an expired task.
809807
810808**Example: Task cancellation rejected (already terminal)**
811809
specification/2025-11-25/client/elicitation Changed · +43 / -45 lines
from line 1
11# Elicitation
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol (MCP) provides a standardized way for servers to request additional
64information from users through the client during interactions. This flow allows clients to
75maintain control over user interactions and data sharing while enabling servers to gather
from line 19
2119their needs—the protocol itself does not mandate any specific user interaction
2220model.
2321
24<Warning>
25 For trust & safety and security:
22> [!WARNING]
23>
24> For trust & safety and security:
25>
26> * Servers **MUST NOT** use form mode elicitation to request sensitive information such as
27> passwords, API keys, access tokens, or payment credentials
28> * Servers **MUST** use [URL mode](#url-mode-elicitation-requests) for interactions involving
29> such sensitive information
30>
31> "Sensitive information" in this context refers to secrets and credentials that grant access or
32> authorize transactions. General contact or profile information (such as a name, email address,
33> or username) is not categorically prohibited; whether to request such data via form mode is at
34> the discretion of the server and subject to the user's ability to review and decline.
35>
36> MCP clients **MUST**:
37>
38> * Provide UI that makes it clear which server is requesting information
39> * Respect user privacy and provide clear decline and cancel options
40> * For form mode, allow users to review and modify their responses before sending
41> * For URL mode, clearly display the target domain/host and gather user consent before navigation to the target URL
2642
27 * Servers **MUST NOT** use form mode elicitation to request sensitive information such as
28 passwords, API keys, access tokens, or payment credentials
29 * Servers **MUST** use [URL mode](#url-mode-elicitation-requests) for interactions involving
30 such sensitive information
31
32 "Sensitive information" in this context refers to secrets and credentials that grant access or
33 authorize transactions. General contact or profile information (such as a name, email address,
34 or username) is not categorically prohibited; whether to request such data via form mode is at
35 the discretion of the server and subject to the user's ability to review and decline.
36
37 MCP clients **MUST**:
38
39 * Provide UI that makes it clear which server is requesting information
40 * Respect user privacy and provide clear decline and cancel options
41 * For form mode, allow users to review and modify their responses before sending
42 * For URL mode, clearly display the target domain/host and gather user consent before navigation to the target URL
43</Warning>
44
4543## Capabilities
4644
4745Clients that support elicitation **MUST** declare the `elicitation` capability during
from line 323
325323
326324### URL Mode Elicitation Requests
327325
328<Note>
329 **New feature:** URL mode elicitation is introduced in the `2025-11-25` version of the MCP specification. Its design and implementation may change in future protocol revisions.
330</Note>
326> [!NOTE]
327>
328> **New feature:** URL mode elicitation is introduced in the `2025-11-25` version of the MCP specification. Its design and implementation may change in future protocol revisions.
331329
332330URL mode elicitation enables servers to direct users to external URLs for out-of-band interactions that must not pass through the MCP client. This is essential for auth flows, payment processing, and other sensitive or secure operations.
333331
from line 338
340338
341339The `url` parameter **MUST** contain a valid URL.
342340
343<Note>
344 **Important**: URL mode elicitation is *not* for authorizing the MCP client's
345 access to the MCP server (that's handled by [MCP
346 authorization](../basic/authorization)). Instead, it's used when the MCP
347 server needs to obtain sensitive information or third-party authorization on
348 behalf of the user. The MCP client's bearer token remains unchanged. The
349 client's only responsibility is to provide the user with context about the
350 elicitation URL the server wants them to open.
351</Note>
341> [!NOTE]
342>
343> **Important**: URL mode elicitation is *not* for authorizing the MCP client's
344> access to the MCP server (that's handled by [MCP
345> authorization](../basic/authorization)). Instead, it's used when the MCP
346> server needs to obtain sensitive information or third-party authorization on
347> behalf of the user. The MCP client's bearer token remains unchanged. The
348> client's only responsibility is to provide the user with context about the
349> elicitation URL the server wants them to open.
352350
353351#### Example: Request Sensitive Data
354352
from line 573
575573* State storage **MUST** be protected against unauthorized access
576574* For remote MCP servers, user identification **MUST** be derived from credentials acquired via [MCP authorization](../basic/authorization) when possible (e.g. `sub` claim)
577575
578<Note>
579 The examples in this section are non-normative and illustrate potential uses
580 of elicitation. Implementers should adapt these patterns to their specific
581 requirements while maintaining security best practices.
582</Note>
576> [!NOTE]
577>
578> The examples in this section are non-normative and illustrate potential uses
579> of elicitation. Implementers should adapt these patterns to their specific
580> requirements while maintaining security best practices.
583581
584582### URL Mode Elicitation for Sensitive Data
585583
from line 623
625623
626624Credentials obtained via URL mode elicitation are distinct from the MCP server credentials used by the MCP client. The MCP server **MUST NOT** transmit credentials obtained through URL mode elicitation to the MCP client.
627625
628<Note>
629 For additional background, refer to the [token passthrough
630 section](../basic/security_best_practices#token-passthrough) of the Security
631 Best Practices document to understand why MCP servers cannot act as
632 pass-through proxies.
633</Note>
626> [!NOTE]
627>
628> For additional background, refer to the [token passthrough
629> section](../basic/security_best_practices#token-passthrough) of the Security
630> Best Practices document to understand why MCP servers cannot act as
631> pass-through proxies.
634632
635633#### Implementation Pattern
636634
specification/2025-11-25/client/sampling Changed · +17 / -19 lines
from line 1
11# Sampling
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol (MCP) provides a standardized way for servers to request LLM
64sampling ("completions" or "generations") from language models via clients. This flow
75allows clients to maintain control over model access, selection, and permissions while
from line 16
1816their needs—the protocol itself does not mandate any specific user interaction
1917model.
2018
21<Warning>
22 For trust & safety and security, there **SHOULD** always
23 be a human in the loop with the ability to deny sampling requests.
19> [!WARNING]
20>
21> For trust & safety and security, there **SHOULD** always
22> be a human in the loop with the ability to deny sampling requests.
23>
24> Applications **SHOULD**:
25>
26> * Provide UI that makes it easy and intuitive to review sampling requests
27> * Allow users to view and edit prompts before sending
28> * Present generated responses for review before delivery
2429
25 Applications **SHOULD**:
26
27 * Provide UI that makes it easy and intuitive to review sampling requests
28 * Allow users to view and edit prompts before sending
29 * Present generated responses for review before delivery
30</Warning>
31
3230## Tools in Sampling
3331
3432Servers can request that the client's LLM use tools during sampling by providing a `tools` array and optional `toolChoice` configuration in their sampling requests. This enables servers to implement agentic behaviors where the LLM can call tools, receive results, and continue the conversation - all within a single sampling request flow.
from line 72
7472}
7573```
7674
77<Note>
78 The `includeContext` parameter values `"thisServer"` and `"allServers"` are
79 soft-deprecated. Servers **SHOULD** avoid using these values (e.g. can just
80 omit `includeContext` since it defaults to `"none"`), and **SHOULD NOT** use
81 them unless the client declares `sampling.context` capability. These values
82 may be removed in future spec releases.
83</Note>
75> [!NOTE]
76>
77> The `includeContext` parameter values `"thisServer"` and `"allServers"` are
78> soft-deprecated. Servers **SHOULD** avoid using these values (e.g. can just
79> omit `includeContext` since it defaults to `"none"`), and **SHOULD NOT** use
80> them unless the client declares `sampling.context` capability. These values
81> may be removed in future spec releases.
8482
8583## Protocol Messages
8684
specification/2025-11-25/index Changed · +5 / -9 lines
from line 1
11# Specification
22
3<div id="enable-section-numbers" />
4
53[Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that
64enables seamless integration between LLM applications and external data sources and
75tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating
from line 120
122120
123121Explore the detailed specification for each protocol component:
124122
125<CardGroup cols={5}>
126 <Card title="Architecture" icon="sitemap" href="/specification/2025-11-25/architecture" />
123> **[Architecture](/specification/2025-11-25/architecture)**
127124
128 <Card title="Base Protocol" icon="code" href="/specification/2025-11-25/basic" />
125> **[Base Protocol](/specification/2025-11-25/basic)**
129126
130 <Card title="Server Features" icon="server" href="/specification/2025-11-25/server" />
127> **[Server Features](/specification/2025-11-25/server)**
131128
132 <Card title="Client Features" icon="user" href="/specification/2025-11-25/client" />
129> **[Client Features](/specification/2025-11-25/client)**
133130
134 <Card title="Contributing" icon="pencil" href="/community/contributing" />
135</CardGroup>
131> **[Contributing](/community/contributing)**
136132
specification/2025-11-25/server/index Changed · +3 / -5 lines
from line 20
2020
2121Explore these key primitives in more detail below:
2222
23<CardGroup cols={3}>
24 <Card title="Prompts" icon="message" href="/specification/2025-11-25/server/prompts" />
23> **[Prompts](/specification/2025-11-25/server/prompts)**
2524
26 <Card title="Resources" icon="file-lines" href="/specification/2025-11-25/server/resources" />
25> **[Resources](/specification/2025-11-25/server/resources)**
2726
28 <Card title="Tools" icon="wrench" href="/specification/2025-11-25/server/tools" />
29</CardGroup>
27> **[Tools](/specification/2025-11-25/server/tools)**
3028
specification/2025-11-25/server/prompts Changed · +6 / -8 lines
from line 1
11# Prompts
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol (MCP) provides a standardized way for servers to expose prompt
64templates to clients. Prompts allow servers to provide structured messages and
75instructions for interacting with language models. Clients can discover available
from line 15
1715
1816For example, as slash commands:
1917
20<img src="https://mintcdn.com/mcp/uzELntid9uQ-QMAr/specification/2025-11-25/server/slash-command.png?fit=max&auto=format&n=uzELntid9uQ-QMAr&q=85&s=965e4fa2273b376721d6f26c396c69c5" alt="Example of prompt exposed as slash command" width="293" height="106" data-path="specification/2025-11-25/server/slash-command.png" />
18
2119
2220However, implementors are free to expose prompts through any interface pattern that suits
2321their needs—the protocol itself does not mandate any specific user interaction
from line 188
190188* `role`: Either "user" or "assistant" to indicate the speaker
191189* `content`: One of the following content types:
192190
193<Note>
194 All content types in prompt messages support optional
195 [annotations](./resources#annotations) for metadata about audience, priority,
196 and modification times.
197</Note>
191> [!NOTE]
192>
193> All content types in prompt messages support optional
194> [annotations](./resources#annotations) for metadata about audience, priority,
195> and modification times.
198196
199197#### Text Content
200198
specification/2025-11-25/server/tools Changed · +30 / -32 lines
from line 1
11# Tools
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol (MCP) allows servers to expose tools that can be invoked by
64language models. Tools enable models to interact with external systems, such as querying
75databases, calling APIs, or performing computations. Each tool is uniquely identified by
from line 15
1715suits their needs—the protocol itself does not mandate any specific user
1816interaction model.
1917
20<Warning>
21 For trust & safety and security, there **SHOULD** always
22 be a human in the loop with the ability to deny tool invocations.
18> [!WARNING]
19>
20> For trust & safety and security, there **SHOULD** always
21> be a human in the loop with the ability to deny tool invocations.
22>
23> Applications **SHOULD**:
24>
25> * Provide UI that makes clear which tools are being exposed to the AI model
26> * Insert clear visual indicators when tools are invoked
27> * Present confirmation prompts to the user for operations, to ensure a human is in the
28> loop
2329
24 Applications **SHOULD**:
25
26 * Provide UI that makes clear which tools are being exposed to the AI model
27 * Insert clear visual indicators when tools are invoked
28 * Present confirmation prompts to the user for operations, to ensure a human is in the
29 loop
30</Warning>
31
3230## Capabilities
3331
3432Servers that support tools **MUST** declare the `tools` capability:
from line 203
205203* `execution`: Optional object describing execution-related properties
206204 * `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"`
207205
208<Warning>
209 For trust & safety and security, clients **MUST** consider tool annotations to
210 be untrusted unless they come from trusted servers.
211</Warning>
206> [!WARNING]
207>
208> For trust & safety and security, clients **MUST** consider tool annotations to
209> be untrusted unless they come from trusted servers.
212210
213211#### Tool Names
214212
from line 227
229227
230228**Unstructured** content is returned in the `content` field of a result, and can contain multiple content items of different types:
231229
232<Note>
233 All content types (text, image, audio, resource links, and embedded resources)
234 support optional
235 [annotations](/specification/2025-11-25/server/resources#annotations) that
236 provide metadata about audience, priority, and modification times. This is the
237 same annotation format used by resources and prompts.
238</Note>
230> [!NOTE]
231>
232> All content types (text, image, audio, resource links, and embedded resources)
233> support optional
234> [annotations](/specification/2025-11-25/server/resources#annotations) that
235> provide metadata about audience, priority, and modification times. This is the
236> same annotation format used by resources and prompts.
239237
240238#### Text Content
241239
from line 285
287285
288286Resource links support the same [Resource annotations](/specification/2025-11-25/server/resources#annotations) as regular resources to help clients understand how to use them.
289287
290<Info>
291 Resource links returned by tools are not guaranteed to appear in the results
292 of a `resources/list` request.
293</Info>
288> [!NOTE]
289>
290> Resource links returned by tools are not guaranteed to appear in the results
291> of a `resources/list` request.
294292
295293#### Embedded Resources
296294
from line 319
321319
322320For backwards compatibility, a tool that returns structured content SHOULD also return the serialized JSON in a TextContent block.
323321
324<Note>
325 `structuredContent` is server-produced result data and is unrelated to LLM
326 "structured outputs" (schema-constrained model generation).
327</Note>
322> [!NOTE]
323>
324> `structuredContent` is server-produced result data and is unrelated to LLM
325> "structured outputs" (schema-constrained model generation).
328326
329327#### Output Schema
330328
specification/2026-07-28/basic/authorization/client-registration Changed · +6 / -8 lines
from line 1
11# Client Registration
22
3<div id="enable-section-numbers" />
4
53MCP supports three client registration mechanisms. Choose based on your scenario:
64
75* **[Client ID Metadata Documents](#client-id-metadata-documents)**: When client and server have no prior relationship (most common)
from line 133
135133
136134## Dynamic Client Registration
137135
138<Warning>
139 Dynamic Client Registration is deprecated. New implementations should use
140 [Client ID Metadata Documents](#client-id-metadata-documents) instead. This
141 option remains available for backwards compatibility with authorization
142 servers that do not support Client ID Metadata Documents.
143</Warning>
136> [!WARNING]
137>
138> Dynamic Client Registration is deprecated. New implementations should use
139> [Client ID Metadata Documents](#client-id-metadata-documents) instead. This
140> option remains available for backwards compatibility with authorization
141> servers that do not support Client ID Metadata Documents.
144142
145143MCP clients and authorization servers **MAY** support the
146144OAuth 2.0 Dynamic Client Registration Protocol [RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)
specification/2026-07-28/basic/index Changed · +17 / -19 lines
from line 1
11# Overview
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol consists of several key components that work together:
64
75* **Base Protocol**: Core JSON-RPC message types
from line 197
199197 application-level handles) **MUST** be referenced by an explicit identifier
200198 the client passes on each request.
201199
202<Note>
203 This implies that an open connection, such as a STDIO process, is not a
204 conversation or session: clients may interleave unrelated requests on the same
205 transport, and a server must not treat connection or process identity as a
206 proxy for conversation or session continuity.
207</Note>
200> [!NOTE]
201>
202> This implies that an open connection, such as a STDIO process, is not a
203> conversation or session: clients may interleave unrelated requests on the same
204> transport, and a server must not treat connection or process identity as a
205> proxy for conversation or session continuity.
208206
209207Long-lived requests like
210208[`subscriptions/listen`](/specification/2026-07-28/basic/patterns/subscriptions)
from line 209
211209remain request/response; the response is just an open stream of notifications.
212210Their state is scoped to the request itself, not to the connection underneath.
213211
214<Info>
215 For a walkthrough of how the per-request model maps to SDK code, see the
216 [Architecture guide](/docs/2026-07-28/learn/architecture#example).
217</Info>
212> [!NOTE]
213>
214> 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).
218216
219217## Auth
220218
from line 397
399397| - | - | - | - |
400398| `io.modelcontextprotocol/serverInfo` | `Implementation` | No | Server name and version |
401399
402<Note>
403 `io.modelcontextprotocol/clientInfo` and `io.modelcontextprotocol/serverInfo`
404 are self-reported by the sender and are not verified by the protocol. They are
405 intended for display, logging, and debugging. Implementations **SHOULD NOT**
406 use them to change the behavior of the client or server, and **SHOULD NOT**
407 rely on them for security decisions.
408</Note>
400> [!NOTE]
401>
402> `io.modelcontextprotocol/clientInfo` and `io.modelcontextprotocol/serverInfo`
403> are self-reported by the sender and are not verified by the protocol. They are
404> intended for display, logging, and debugging. Implementations **SHOULD NOT**
405> use them to change the behavior of the client or server, and **SHOULD NOT**
406> rely on them for security decisions.
409407
410408On notifications delivered via a [`subscriptions/listen`][subscriptions-listen] stream,
411409the server **MUST** include `io.modelcontextprotocol/subscriptionId` in `_meta` so the
specification/2026-07-28/basic/patterns/mrtr Changed · +23 / -25 lines
from line 1
11# Multi Round-Trip Requests
22
3<div id="enable-section-numbers" />
3> [!NOTE]
4>
5> Multi Round-Trip Requests (MRTR) was introduced in this version of the MCP
6> specification. This replaces the previous approach of sending server-initiated
7> requests. Servers **MUST** send server-to-client requests (such as
8> `roots/list`, `sampling/createMessage`, or `elicitation/create`) using the
9> MRTR pattern. The previous pattern of server-initiated requests is no longer
10> supported. This is a breaking change.
411
5<Note>
6 Multi Round-Trip Requests (MRTR) was introduced in this version of the MCP
7 specification. This replaces the previous approach of sending server-initiated
8 requests. Servers **MUST** send server-to-client requests (such as
9 `roots/list`, `sampling/createMessage`, or `elicitation/create`) using the
10 MRTR pattern. The previous pattern of server-initiated requests is no longer
11 supported. This is a breaking change.
12</Note>
12> [!NOTE]
13>
14> For brevity, the request examples on this page omit the `_meta` request
15> metadata (`io.modelcontextprotocol/protocolVersion`,
16> `io.modelcontextprotocol/clientInfo`, and
17> `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
18> the required `_meta` fields; see
19> [`_meta`](/specification/2026-07-28/basic/index#meta).
1320
14<Note>
15 For brevity, the request examples on this page omit the `_meta` request
16 metadata (`io.modelcontextprotocol/protocolVersion`,
17 `io.modelcontextprotocol/clientInfo`, and
18 `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
19 the required `_meta` fields; see
20 [`_meta`](/specification/2026-07-28/basic/index#meta).
21</Note>
22
2321## Multi Round-Trip Requests
2422
2523The Model Context Protocol (MCP) defines several ways for servers to request additional information
from line 234
236234 * the authenticated principal, rejecting state presented by a different principal.
237235 * a short expiry (TTL), rejecting state presented after it lapses;
238236 * an identifier for the originating request, e.g. the method name and a digest of its salient parameters, rejecting state presented on a request that does not match.
239 <Warning>
240 Note that these measures bound the replay window and prevent cross-user
241 and cross-request reuse, but do not by themselves guarantee single-use.
242 Servers for which a given `requestState` must be consumed at most once
243 (e.g., one-time redemptions) **MUST** enforce that invariant server-side.
244 </Warning>
237 > [!WARNING]
238 >
239 > Note that these measures bound the replay window and prevent cross-user
240 > and cross-request reuse, but do not by themselves guarantee single-use.
241 > Servers for which a given `requestState` must be consumed at most once
242 > (e.g., one-time redemptions) **MUST** enforce that invariant server-side.
245243
2462446. Servers **MUST** include at least one of `inputRequests` or `requestState` in every `InputRequiredResult` response.
247245
specification/2026-07-28/basic/transports/streamable-http Changed · +66 / -68 lines
from line 1
11# Streamable HTTP
22
3<div id="enable-section-numbers" />
3> [!NOTE]
4>
5> Streamable HTTP was introduced in protocol version 2025-03-26 as a replacement
6> for the \[HTTP+SSE transport]\[http-sse] from protocol version 2024-11-05.
47
5<Info>
6 Streamable HTTP was introduced in protocol version 2025-03-26 as a replacement
7 for the [HTTP+SSE transport][http-sse] from protocol version 2024-11-05.
8</Info>
8> [!NOTE]
9>
10> Revision 2026-07-28 changed the behavior of Streamable HTTP. Clients must
11> ensure they handle backwards compatibility correctly. Changes included:
12>
13> * Removal of the GET stream endpoint.
14> * Removal of protocol-level sessions.
15>
16> See the [changelog](/specification/2026-07-28/changelog) and
17> [Backward Compatibility](#backward-compatibility) below.
918
10<Info>
11 Revision 2026-07-28 changed the behavior of Streamable HTTP. Clients must
12 ensure they handle backwards compatibility correctly. Changes included:
13
14 * Removal of the GET stream endpoint.
15 * Removal of protocol-level sessions.
16
17 See the [changelog](/specification/2026-07-28/changelog) and
18 [Backward Compatibility](#backward-compatibility) below.
19</Info>
20
2119In the **Streamable HTTP** transport, the server operates as an independent
2220process that can handle multiple client connections. At a glance:
2321
from line 83
8583 `Content-Type: text/event-stream` (an SSE response stream). The client
8684 **MUST** support both.
8785
88<Note>
89 This revision of the core protocol defines no client-to-server
90 *notifications* over Streamable HTTP. The only client-sent notification in
91 the core protocol, `notifications/cancelled`, is used only on the
92 [stdio](/specification/2026-07-28/basic/transports/stdio) transport; on
93 Streamable HTTP, closing the SSE response stream is itself the cancellation
94 signal and no `notifications/cancelled` message is expected (see
95 [Cancellation][cancellation]). The notification rules above describe the
96 transport mechanics for a notification POST; header requirements for
97 notification POSTs are not defined by this revision.
98</Note>
86> [!NOTE]
87>
88> This revision of the core protocol defines no client-to-server
89> *notifications* over Streamable HTTP. The only client-sent notification in
90> the core protocol, `notifications/cancelled`, is used only on the
91> [stdio](/specification/2026-07-28/basic/transports/stdio) transport; on
92> Streamable HTTP, closing the SSE response stream is itself the cancellation
93> signal and no `notifications/cancelled` message is expected (see
94> \[Cancellation]\[cancellation]). The notification rules above describe the
95> transport mechanics for a notification POST; header requirements for
96> notification POSTs are not defined by this revision.
9997
10098## Receiving Messages
10199
from line 132
134132them to the client, introducing unwanted latency and potentially breaking the
135133real-time nature of SSE communication.
136134
137<Note>
138 For long-lived streams — in particular the
139 [`subscriptions/listen`][subscriptions-listen] response stream — servers are
140 encouraged to periodically emit an SSE comment line (a line beginning with a
141 colon, e.g. `:\r\n`) as a keep-alive. This keeps the connection from being
142 closed by intermediaries or client idle timeouts during quiet periods when no
143 notifications are flowing. Per the [SSE specification][sse], any line beginning
144 with a colon is a comment that carries no event data; clients must ignore such
145 lines and must not treat them as malformed input.
146</Note>
135> [!NOTE]
136>
137> For long-lived streams — in particular the
138> \[`subscriptions/listen`]\[subscriptions-listen] response stream — servers are
139> encouraged to periodically emit an SSE comment line (a line beginning with a
140> colon, e.g. `:\r\n`) as a keep-alive. This keeps the connection from being
141> closed by intermediaries or client idle timeouts during quiet periods when no
142> notifications are flowing. Per the \[SSE specification]\[sse], any line beginning
143> with a colon is a comment that carries no event data; clients must ignore such
144> lines and must not treat them as malformed input.
147145
148146Resumable SSE streams via `Last-Event-ID` are not supported.
149147
from line 581
583581(e.g., a load balancer routing on the header value while the MCP server
584582executes based on the body value).
585583
586<Note>
587 When validating integer parameter values, servers **SHOULD** compare the
588 header value and the body value numerically rather than as strings (e.g.,
589 `42.0` and `42` are considered equal).
590</Note>
584> [!NOTE]
585>
586> When validating integer parameter values, servers **SHOULD** compare the
587> header value and the body value numerically rather than as strings (e.g.,
588> `42.0` and `42` are considered equal).
591589
592590When rejecting a request due to header validation failure, servers **MUST**
593591return HTTP status `400 Bad Request` and **MUST** include a JSON-RPC error
from line 622
624622 [Value Encoding](#value-encoding)) before comparing them to the body value.
625623* A header value contains invalid characters.
626624
627<Note>
628 Intermediaries **MUST** return an appropriate HTTP error status (e.g.,
629 `400 Bad Request`) for validation failures but are not required to return
630 a JSON-RPC error response.
631</Note>
625> [!NOTE]
626>
627> Intermediaries **MUST** return an appropriate HTTP error status (e.g.,
628> `400 Bad Request`) for validation failures but are not required to return
629> a JSON-RPC error response.
632630
633<Note>
634 Intermediaries that enforce policy based on mirrored headers (e.g., routing
635 or rate-limiting by tenant) **SHOULD** verify that the `MCP-Protocol-Version`
636 header indicates a version that requires header–body validation. If the
637 version is older or the header is absent, the intermediary **SHOULD** reject
638 the request rather than trusting unvalidated header values.
639</Note>
631> [!NOTE]
632>
633> Intermediaries that enforce policy based on mirrored headers (e.g., routing
634> or rate-limiting by tenant) **SHOULD** verify that the `MCP-Protocol-Version`
635> header indicates a version that requires header–body validation. If the
636> version is older or the header is absent, the intermediary **SHOULD** reject
637> the request rather than trusting unvalidated header values.
640638
641639## Backward Compatibility
642640
from line 683
685683
686684### HTTP+SSE Transport (2024-11-05)
687685
688<Warning>
689 **Deprecated**: The [HTTP+SSE transport][http-sse] from protocol version
690 2024-11-05 has been deprecated since protocol version `2025-03-26` and is
691 classified as Deprecated under the [feature lifecycle
692 policy](/community/feature-lifecycle#deprecating-a-feature)
693 ([SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596)).
694 New implementations **SHOULD NOT** adopt it; existing implementations
695 **SHOULD** migrate to [Streamable
696 HTTP](/specification/2026-07-28/basic/transports/streamable-http). It is
697 eligible for removal in a future revision; see the [deprecated features
698 registry](/specification/2026-07-28/deprecated).
699</Warning>
686> [!WARNING]
687>
688> **Deprecated**: The \[HTTP+SSE transport]\[http-sse] from protocol version
689> 2024-11-05 has been deprecated since protocol version `2025-03-26` and is
690> classified as Deprecated under the [feature lifecycle
691> policy](/community/feature-lifecycle#deprecating-a-feature)
692> ([SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596)).
693> New implementations **SHOULD NOT** adopt it; existing implementations
694> **SHOULD** migrate to [Streamable
695> HTTP](/specification/2026-07-28/basic/transports/streamable-http). It is
696> eligible for removal in a future revision; see the [deprecated features
697> registry](/specification/2026-07-28/deprecated).
700698
701699Clients and servers can maintain backward compatibility with the
702700deprecated [HTTP+SSE transport][http-sse] (from
specification/2026-07-28/client/elicitation Changed · +43 / -45 lines
from line 1
11# Elicitation
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol (MCP) provides a standardized way for servers to request additional
64information from users through the client during interactions. This flow allows clients to
75maintain control over user interactions and data sharing while enabling servers to gather
from line 19
2119their needs—the protocol itself does not mandate any specific user interaction
2220model.
2321
24<Warning>
25 For trust & safety and security:
22> [!WARNING]
23>
24> For trust & safety and security:
25>
26> * Servers **MUST NOT** use form mode elicitation to request sensitive information such as
27> passwords, API keys, access tokens, or payment credentials
28> * Servers **MUST** use [URL mode](#url-mode-elicitation-requests) for interactions involving
29> such sensitive information
30>
31> "Sensitive information" in this context refers to secrets and credentials that grant access or
32> authorize transactions. General contact or profile information (such as a name, email address,
33> or username) is not categorically prohibited; whether to request such data via form mode is at
34> the discretion of the server and subject to the user's ability to review and decline.
35>
36> MCP clients **MUST**:
37>
38> * Provide UI that makes it clear which server is requesting information
39> * Respect user privacy and provide clear decline and cancel options
40> * For form mode, allow users to review and modify their responses before sending
41> * For URL mode, clearly display the target domain/host and gather user consent before navigation to the target URL
2642
27 * Servers **MUST NOT** use form mode elicitation to request sensitive information such as
28 passwords, API keys, access tokens, or payment credentials
29 * Servers **MUST** use [URL mode](#url-mode-elicitation-requests) for interactions involving
30 such sensitive information
31
32 "Sensitive information" in this context refers to secrets and credentials that grant access or
33 authorize transactions. General contact or profile information (such as a name, email address,
34 or username) is not categorically prohibited; whether to request such data via form mode is at
35 the discretion of the server and subject to the user's ability to review and decline.
36
37 MCP clients **MUST**:
38
39 * Provide UI that makes it clear which server is requesting information
40 * Respect user privacy and provide clear decline and cancel options
41 * For form mode, allow users to review and modify their responses before sending
42 * For URL mode, clearly display the target domain/host and gather user consent before navigation to the target URL
43</Warning>
44
4543## Capabilities
4644
4745Clients that support elicitation **MUST** declare the `elicitation` capability in
from line 315
317315
318316### URL Mode Elicitation Requests
319317
320<Note>
321 **New feature:** URL mode elicitation is introduced in the `2025-11-25` version of the MCP specification. Its design and implementation may change in future protocol revisions.
322</Note>
318> [!NOTE]
319>
320> **New feature:** URL mode elicitation is introduced in the `2025-11-25` version of the MCP specification. Its design and implementation may change in future protocol revisions.
323321
324322URL mode elicitation enables servers to direct users to external URLs for out-of-band interactions that must not pass through the MCP client. This is essential for auth flows, payment processing, and other sensitive or secure operations.
325323
from line 329
331329
332330The `url` parameter **MUST** contain a valid URL.
333331
334<Note>
335 **Important**: URL mode elicitation is *not* for authorizing the MCP client's
336 access to the MCP server (that's handled by [MCP
337 authorization](../basic/authorization)). Instead, it's used when the MCP
338 server needs to obtain sensitive information or third-party authorization on
339 behalf of the user. The MCP client's bearer token remains unchanged. The
340 client's only responsibility is to provide the user with context about the
341 elicitation URL the server wants them to open.
342</Note>
332> [!NOTE]
333>
334> **Important**: URL mode elicitation is *not* for authorizing the MCP client's
335> access to the MCP server (that's handled by [MCP
336> authorization](../basic/authorization)). Instead, it's used when the MCP
337> server needs to obtain sensitive information or third-party authorization on
338> behalf of the user. The MCP client's bearer token remains unchanged. The
339> client's only responsibility is to provide the user with context about the
340> elicitation URL the server wants them to open.
343341
344342#### Example: Request Sensitive Data
345343
from line 469
471469* State storage **MUST** be protected against unauthorized access
472470* For remote MCP servers, user identification **MUST** be derived from credentials acquired via [MCP authorization](../basic/authorization) when possible (e.g. `sub` claim)
473471
474<Note>
475 The examples in this section are non-normative and illustrate potential uses
476 of elicitation. Implementers should adapt these patterns to their specific
477 requirements while maintaining security best practices.
478</Note>
472> [!NOTE]
473>
474> The examples in this section are non-normative and illustrate potential uses
475> of elicitation. Implementers should adapt these patterns to their specific
476> requirements while maintaining security best practices.
479477
480478### URL Mode Elicitation for Sensitive Data
481479
from line 519
521519
522520Credentials obtained via URL mode elicitation are distinct from the MCP server credentials used by the MCP client. The MCP server **MUST NOT** transmit credentials obtained through URL mode elicitation to the MCP client.
523521
524<Note>
525 For additional background, refer to the [token passthrough
526 section](/docs/2026-07-28/tutorials/security/security_best_practices#token-passthrough)
527 of the Security Best Practices document to understand why MCP servers cannot
528 act as pass-through proxies.
529</Note>
522> [!NOTE]
523>
524> For additional background, refer to the [token passthrough
525> section](/docs/2026-07-28/tutorials/security/security_best_practices#token-passthrough)
526> of the Security Best Practices document to understand why MCP servers cannot
527> act as pass-through proxies.
530528
531529#### Implementation Pattern
532530
specification/2026-07-28/client/roots Changed · +11 / -13 lines
from line 1
11# Roots
22
3<div id="enable-section-numbers" />
4
5<Warning>
6 **Deprecated**: The Roots feature is deprecated as of protocol version
7 `2026-07-28`
8 ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)).
9 Under the [feature lifecycle policy](/community/feature-lifecycle), it remains
10 in the specification for at least twelve months after this revision's release
11 before it becomes eligible for removal. New implementations **SHOULD NOT**
12 adopt it; existing implementations **SHOULD** migrate to passing directories
13 or files via tool parameters, resource URIs, or server configuration. See the
14 [deprecated features registry](/specification/2026-07-28/deprecated).
15</Warning>
3> [!WARNING]
4>
5> **Deprecated**: The Roots feature is deprecated as of protocol version
6> `2026-07-28`
7> ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)).
8> Under the [feature lifecycle policy](/community/feature-lifecycle), it remains
9> in the specification for at least twelve months after this revision's release
10> before it becomes eligible for removal. New implementations **SHOULD NOT**
11> adopt it; existing implementations **SHOULD** migrate to passing directories
12> or files via tool parameters, resource URIs, or server configuration. See the
13> [deprecated features registry](/specification/2026-07-28/deprecated).
1614
1715The Model Context Protocol (MCP) provides a standardized way for clients to expose
1816filesystem "roots" to servers. Roots inform servers about the directories and files the
specification/2026-07-28/client/sampling Changed · +32 / -34 lines
from line 1
11# Sampling
22
3<div id="enable-section-numbers" />
3> [!WARNING]
4>
5> **Deprecated**: The Sampling feature is deprecated as of protocol version
6> `2026-07-28`
7> ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)).
8> Under the [feature lifecycle policy](/community/feature-lifecycle), it remains
9> in the specification for at least twelve months after this revision's release
10> before it becomes eligible for removal. New implementations **SHOULD NOT**
11> adopt it; existing implementations **SHOULD** migrate to integrating directly
12> with LLM provider APIs. See the [deprecated features
13> registry](/specification/2026-07-28/deprecated).
414
5<Warning>
6 **Deprecated**: The Sampling feature is deprecated as of protocol version
7 `2026-07-28`
8 ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)).
9 Under the [feature lifecycle policy](/community/feature-lifecycle), it remains
10 in the specification for at least twelve months after this revision's release
11 before it becomes eligible for removal. New implementations **SHOULD NOT**
12 adopt it; existing implementations **SHOULD** migrate to integrating directly
13 with LLM provider APIs. See the [deprecated features
14 registry](/specification/2026-07-28/deprecated).
15</Warning>
16
1715The Model Context Protocol (MCP) provides a standardized way for servers to request LLM
1816sampling ("completions" or "generations") from language models via clients. This flow
1917allows clients to maintain control over model access, selection, and permissions while
from line 28
3028their needs—the protocol itself does not mandate any specific user interaction
3129model.
3230
33<Warning>
34 For trust & safety and security, there **SHOULD** always
35 be a human in the loop with the ability to deny sampling requests.
31> [!WARNING]
32>
33> For trust & safety and security, there **SHOULD** always
34> be a human in the loop with the ability to deny sampling requests.
35>
36> Applications **SHOULD**:
37>
38> * Provide UI that makes it easy and intuitive to review sampling requests
39> * Allow users to view and edit prompts before sending
40> * Present generated responses for review before delivery
3641
37 Applications **SHOULD**:
38
39 * Provide UI that makes it easy and intuitive to review sampling requests
40 * Allow users to view and edit prompts before sending
41 * Present generated responses for review before delivery
42</Warning>
43
4442## Tools in Sampling
4543
4644Servers can request that the client's LLM use tools during sampling by providing a `tools` array and optional `toolChoice` configuration in their sampling requests. The tool definitions in the `tools` array are scoped to the sampling request — they don't need to correspond to registered tools. This enables servers to implement agentic behaviors where the LLM can call specially designated tools, receive results, and continue the conversation - all within a single sampling request flow.
from line 90
9290}
9391```
9492
95<Note>
96 The `includeContext` parameter values `"thisServer"` and `"allServers"` are
97 deprecated under the [feature lifecycle
98 policy](/community/feature-lifecycle#deprecating-a-feature)
99 ([SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596));
100 they will be removed no later than the Sampling feature itself. Servers
101 **SHOULD** avoid using these values (e.g. can just omit `includeContext` since
102 it defaults to `"none"`), and **SHOULD NOT** use them unless the client
103 declares `sampling.context` capability. See the [deprecated features
104 registry](/specification/2026-07-28/deprecated).
105</Note>
93> [!NOTE]
94>
95> The `includeContext` parameter values `"thisServer"` and `"allServers"` are
96> deprecated under the [feature lifecycle
97> policy](/community/feature-lifecycle#deprecating-a-feature)
98> ([SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596));
99> they will be removed no later than the Sampling feature itself. Servers
100> **SHOULD** avoid using these values (e.g. can just omit `includeContext` since
101> it defaults to `"none"`), and **SHOULD NOT** use them unless the client
102> declares `sampling.context` capability. See the [deprecated features
103> registry](/specification/2026-07-28/deprecated).
106104
107105## Protocol Messages
108106
specification/2026-07-28/index Changed · +5 / -9 lines
from line 1
11# Specification
22
3<div id="enable-section-numbers" />
4
53[Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that
64enables seamless integration between LLM applications and external data sources and
75tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating
from line 123
125123
126124Explore the detailed specification for each protocol component:
127125
128<CardGroup cols={5}>
129 <Card title="Architecture" icon="sitemap" href="/specification/2026-07-28/architecture" />
126> **[Architecture](/specification/2026-07-28/architecture)**
130127
131 <Card title="Base Protocol" icon="code" href="/specification/2026-07-28/basic" />
128> **[Base Protocol](/specification/2026-07-28/basic)**
132129
133 <Card title="Server Features" icon="server" href="/specification/2026-07-28/server" />
130> **[Server Features](/specification/2026-07-28/server)**
134131
135 <Card title="Client Features" icon="user" href="/specification/2026-07-28/client" />
132> **[Client Features](/specification/2026-07-28/client)**
136133
137 <Card title="Contributing" icon="pencil" href="/community/contributing" />
138</CardGroup>
134> **[Contributing](/community/contributing)**
139135
specification/2026-07-28/server/discover Changed · +6 / -8 lines
from line 1
11# Discovery
22
3<div id="enable-section-numbers" />
4
53`server/discover` lets a client query a server's supported protocol versions,
64capabilities, and identity before sending any other requests. Servers **MUST**
75implement it.
from line 96
9896* `instructions`: Optional natural-language guidance for LLMs on how to use
9997 this server effectively
10098
101<Note>
102 `serverInfo` is self-reported by the server and is not verified by the
103 protocol. It is intended for display, logging, and debugging. Clients **SHOULD
104 NOT** use it to change their behavior, and **SHOULD NOT** rely on it for
105 security decisions.
106</Note>
99> [!NOTE]
100>
101> `serverInfo` is self-reported by the server and is not verified by the
102> protocol. It is intended for display, logging, and debugging. Clients **SHOULD
103> NOT** use it to change their behavior, and **SHOULD NOT** rely on it for
104> security decisions.
107105
specification/2026-07-28/server/index Changed · +3 / -5 lines
from line 20
2020
2121Explore these key primitives in more detail below:
2222
23<CardGroup cols={3}>
24 <Card title="Prompts" icon="message" href="/specification/2026-07-28/server/prompts" />
23> **[Prompts](/specification/2026-07-28/server/prompts)**
2524
26 <Card title="Resources" icon="file-lines" href="/specification/2026-07-28/server/resources" />
25> **[Resources](/specification/2026-07-28/server/resources)**
2726
28 <Card title="Tools" icon="wrench" href="/specification/2026-07-28/server/tools" />
29</CardGroup>
27> **[Tools](/specification/2026-07-28/server/tools)**
3028
specification/2026-07-28/server/prompts Changed · +14 / -16 lines
from line 1
11# Prompts
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol (MCP) provides a standardized way for servers to expose prompt
64templates to clients. Prompts allow servers to provide structured messages and
75instructions for interacting with language models. Clients can discover available
86prompts, retrieve their contents, and provide arguments to customize them.
97
10<Note>
11 For brevity, the request examples on this page omit the `_meta` request
12 metadata (`io.modelcontextprotocol/protocolVersion`,
13 `io.modelcontextprotocol/clientInfo`, and
14 `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
15 the required `_meta` fields; see
16 [`_meta`](/specification/2026-07-28/basic/index#meta).
17</Note>
8> [!NOTE]
9>
10> For brevity, the request examples on this page omit the `_meta` request
11> metadata (`io.modelcontextprotocol/protocolVersion`,
12> `io.modelcontextprotocol/clientInfo`, and
13> `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
14> the required `_meta` fields; see
15> [`_meta`](/specification/2026-07-28/basic/index#meta).
1816
1917## User Interaction Model
2018
from line 26
2826
2927For example, as slash commands:
3028
31<img src="https://mintcdn.com/mcp/UAHvrCg8SwnAZwI3/specification/2026-07-28/server/slash-command.png?fit=max&auto=format&n=UAHvrCg8SwnAZwI3&q=85&s=7ed7762fc5e3b4b32cba2a71ede48000" alt="Example of prompt exposed as slash command" width="293" height="106" data-path="specification/2026-07-28/server/slash-command.png" />
29
3230
3331However, implementors are free to expose prompts through any interface pattern that suits
3432their needs—the protocol itself does not mandate any specific user interaction
from line 218
220218* `role`: Either "user" or "assistant" to indicate the speaker
221219* `content`: One of the following content types:
222220
223<Note>
224 All content types in prompt messages support optional
225 [annotations](/specification/2026-07-28/server/resources#annotations) for
226 metadata about audience, priority, and modification times.
227</Note>
221> [!NOTE]
222>
223> All content types in prompt messages support optional
224> [annotations](/specification/2026-07-28/server/resources#annotations) for
225> metadata about audience, priority, and modification times.
228226
229227#### Text Content
230228
specification/2026-07-28/server/resources Changed · +9 / -11 lines
from line 1
11# Resources
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol (MCP) provides a standardized way for servers to expose
64resources to clients. Resources allow servers to share data that provides context to
75language models, such as files, database schemas, or application-specific information.
from line 6
86Each resource is uniquely identified by a
97[URI](https://datatracker.ietf.org/doc/html/rfc3986).
108
11<Note>
12 For brevity, the request examples on this page omit the `_meta` request
13 metadata (`io.modelcontextprotocol/protocolVersion`,
14 `io.modelcontextprotocol/clientInfo`, and
15 `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
16 the required `_meta` fields; see
17 [`_meta`](/specification/2026-07-28/basic/index#meta).
18</Note>
9> [!NOTE]
10>
11> For brevity, the request examples on this page omit the `_meta` request
12> metadata (`io.modelcontextprotocol/protocolVersion`,
13> `io.modelcontextprotocol/clientInfo`, and
14> `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
15> the required `_meta` fields; see
16> [`_meta`](/specification/2026-07-28/basic/index#meta).
1917
2018## User Interaction Model
2119
from line 26
2826* Allow the user to search through and filter available resources
2927* Implement automatic context inclusion, based on heuristics or the AI model's selection
3028
31<img src="https://mintcdn.com/mcp/UAHvrCg8SwnAZwI3/specification/2026-07-28/server/resource-picker.png?fit=max&auto=format&n=UAHvrCg8SwnAZwI3&q=85&s=e2aa63c0e97d97eff5da87bdd3c2260e" alt="Example of resource context picker" width="174" height="181" data-path="specification/2026-07-28/server/resource-picker.png" />
29
3230
3331However, implementations are free to expose resources through any interface pattern that
3432suits their needs—the protocol itself does not mandate any specific user
specification/2026-07-28/server/tools Changed · +56 / -58 lines
from line 1
11# Tools
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol (MCP) allows servers to expose tools that can be invoked by
64language models. Tools enable models to interact with external systems, such as querying
75databases, calling APIs, or performing computations. Each tool is uniquely identified by
86a name and includes metadata describing its schema.
97
10<Note>
11 For brevity, the request examples on this page omit the `_meta` request
12 metadata (`io.modelcontextprotocol/protocolVersion`,
13 `io.modelcontextprotocol/clientInfo`, and
14 `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
15 the required `_meta` fields; see
16 [`_meta`](/specification/2026-07-28/basic/index#meta).
17</Note>
8> [!NOTE]
9>
10> For brevity, the request examples on this page omit the `_meta` request
11> metadata (`io.modelcontextprotocol/protocolVersion`,
12> `io.modelcontextprotocol/clientInfo`, and
13> `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
14> the required `_meta` fields; see
15> [`_meta`](/specification/2026-07-28/basic/index#meta).
1816
1917## User Interaction Model
2018
from line 24
2624suits their needs—the protocol itself does not mandate any specific user
2725interaction model.
2826
29<Warning>
30 For trust & safety and security, there **SHOULD** always
31 be a human in the loop with the ability to deny tool invocations.
27> [!WARNING]
28>
29> For trust & safety and security, there **SHOULD** always
30> be a human in the loop with the ability to deny tool invocations.
31>
32> Applications **SHOULD**:
33>
34> * Provide UI that makes clear which tools are being exposed to the AI model
35> * Insert clear visual indicators when tools are invoked
36> * Present confirmation prompts to the user for operations, to ensure a human is in the
37> loop
3238
33 Applications **SHOULD**:
34
35 * Provide UI that makes clear which tools are being exposed to the AI model
36 * Insert clear visual indicators when tools are invoked
37 * Present confirmation prompts to the user for operations, to ensure a human is in the
38 loop
39</Warning>
40
4139## Capabilities
4240
4341Servers that support tools **MUST** declare the `tools` capability:
from line 295
297295 * Defaults to 2020-12 if no `$schema` field is present
298296* `annotations`: Optional properties describing tool behavior
299297
300<Warning>
301 For trust & safety and security, clients **MUST** consider tool annotations to
302 be untrusted unless they come from trusted servers.
303</Warning>
298> [!WARNING]
299>
300> For trust & safety and security, clients **MUST** consider tool annotations to
301> be untrusted unless they come from trusted servers.
304302
305303#### Tool Names
306304
from line 313
315313 * `DATA_EXPORT_v2`
316314 * `admin.tools.list`
317315
318<Note>
319 Tool name uniqueness is scoped to a single server. Clients or proxies that
320 aggregate tools from multiple servers **MAY** encounter naming collisions (for
321 example, two servers each exposing a `search` tool) and **SHOULD** implement a
322 disambiguation strategy such as prefixing tool names with a server identifier.
316> [!NOTE]
317>
318> Tool name uniqueness is scoped to a single server. Clients or proxies that
319> aggregate tools from multiple servers **MAY** encounter naming collisions (for
320> example, two servers each exposing a `search` tool) and **SHOULD** implement a
321> disambiguation strategy such as prefixing tool names with a server identifier.
322>
323> The server `name` (from `serverInfo`) is not guaranteed to be unique across
324> servers and **SHOULD NOT** be relied upon for disambiguation.
323325
324 The server `name` (from `serverInfo`) is not guaranteed to be unique across
325 servers and **SHOULD NOT** be relied upon for disambiguation.
326</Note>
327
328326#### x-mcp-header
329327
330328The `x-mcp-header` extension property allows servers to designate specific tool
from line 386
388386In this example, when the tool is called with `"region": "us-west1"`, the client adds
389387the header `Mcp-Param-Region: us-west1` to the HTTP request.
390388
391<Warning>
392 Server developers **SHOULD NOT** mark sensitive parameters (passwords, API keys, tokens,
393 PII) with `x-mcp-header`, as header values are visible to network intermediaries.
394</Warning>
389> [!WARNING]
390>
391> Server developers **SHOULD NOT** mark sensitive parameters (passwords, API keys, tokens,
392> PII) with `x-mcp-header`, as header values are visible to network intermediaries.
395393
396394### Tool Result
397395
from line 397
399397
400398**Unstructured** content is returned in the `content` field of a result, and can contain multiple content items of different types:
401399
402<Note>
403 All content types (text, image, audio, resource links, and embedded resources)
404 support optional
405 [annotations](/specification/2026-07-28/server/resources#annotations) that
406 provide metadata about audience, priority, and modification times. This is the
407 same annotation format used by resources and prompts.
408</Note>
400> [!NOTE]
401>
402> All content types (text, image, audio, resource links, and embedded resources)
403> support optional
404> [annotations](/specification/2026-07-28/server/resources#annotations) that
405> provide metadata about audience, priority, and modification times. This is the
406> same annotation format used by resources and prompts.
409407
410408#### Text Content
411409
from line 455
457455
458456Resource links support the same [Resource annotations](/specification/2026-07-28/server/resources#annotations) as regular resources to help clients understand how to use them.
459457
460<Info>
461 Resource links returned by tools are not guaranteed to appear in the results
462 of a `resources/list` request.
463</Info>
458> [!NOTE]
459>
460> Resource links returned by tools are not guaranteed to appear in the results
461> of a `resources/list` request.
464462
465463#### Embedded Resources
466464
from line 489
491489
492490For backwards compatibility, a tool that returns structured content SHOULD also return the serialized JSON in a TextContent block.
493491
494<Note>
495 `structuredContent` is server-produced result data and is unrelated to LLM
496 "structured outputs" (schema-constrained model generation).
497</Note>
492> [!NOTE]
493>
494> `structuredContent` is server-produced result data and is unrelated to LLM
495> "structured outputs" (schema-constrained model generation).
498496
499497#### Output Schema
500498
from line 670
672670
673671## Stateful Tools
674672
675<Note>
676 This section is non-normative guidance for tool design. The protocol has no
677 concept of a state handle; from the wire's perspective a handle is an ordinary
678 string in a tool result and an ordinary argument to subsequent tool calls.
679</Note>
673> [!NOTE]
674>
675> This section is non-normative guidance for tool design. The protocol has no
676> concept of a state handle; from the wire's perspective a handle is an ordinary
677> string in a tool result and an ordinary argument to subsequent tool calls.
680678
681679MCP has no protocol-level session, so a server cannot rely on implicit
682680per-connection state to relate one tool call to the next. Servers that need to
specification/2026-07-28/server/utilities/caching Changed · +8 / -10 lines
from line 1
11# Caching
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol (MCP) supports caching for some results. This allows clients to cache responses and reduce unnecessary re-fetching.
64Caching is complementary to [change notifications](#interaction-with-notifications)—both
75mechanisms can coexist.
from line 36
3836
3937Cacheable Results in MCP use two fields to provide caching hints to clients:
4038
41* The <b>Time-to-live (TTL) Field</b>,`ttlMs`, is an integer value in milliseconds specifying how long the client MAY consider the result fresh.
42* The <b>Cache Scope Field</b>,`cacheScope`, indicates the intended scope of the cached response, either `"public"` or `"private"`.
39* The **Time-to-live (TTL) Field**,`ttlMs`, is an integer value in milliseconds specifying how long the client MAY consider the result fresh.
40* The **Cache Scope Field**,`cacheScope`, indicates the intended scope of the cached response, either `"public"` or `"private"`.
4341
4442### Time-to-Live (TTL) Field
4543
from line 55
5755
5856Servers **MUST** provide a `ttlMs` value that is `>= 0`.
5957
60<Note>
61 TTL is a **freshness hint**, not a guarantee. Servers MAY change the
62 underlying data before the TTL expires. The TTL tells the client how long it
63 can reasonably avoid re-fetching, not how long the data is guaranteed to
64 remain unchanged.
65</Note>
58> [!NOTE]
59>
60> TTL is a **freshness hint**, not a guarantee. Servers MAY change the
61> underlying data before the TTL expires. The TTL tells the client how long it
62> can reasonably avoid re-fetching, not how long the data is guaranteed to
63> remain unchanged.
6664
6765#### Freshness Calculation
6866
specification/2026-07-28/server/utilities/completion Changed · +8 / -10 lines
from line 1
11# Completion
22
3<div id="enable-section-numbers" />
4
53The Model Context Protocol (MCP) provides a standardized way for servers to offer
64autocompletion suggestions for the arguments of prompts and resource templates. When
75users are filling in argument values for a specific prompt (identified by name) or
86resource template (identified by URI), servers can provide contextual suggestions.
97
10<Note>
11 For brevity, the request examples on this page omit the `_meta` request
12 metadata (`io.modelcontextprotocol/protocolVersion`,
13 `io.modelcontextprotocol/clientInfo`, and
14 `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
15 the required `_meta` fields; see
16 [`_meta`](/specification/2026-07-28/basic/index#meta).
17</Note>
8> [!NOTE]
9>
10> For brevity, the request examples on this page omit the `_meta` request
11> metadata (`io.modelcontextprotocol/protocolVersion`,
12> `io.modelcontextprotocol/clientInfo`, and
13> `io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
14> the required `_meta` fields; see
15> [`_meta`](/specification/2026-07-28/basic/index#meta).
1816
1917## User Interaction Model
2018
specification/2026-07-28/server/utilities/logging Changed · +12 / -14 lines
from line 1
11# Logging
22
3<div id="enable-section-numbers" />
4
5<Warning>
6 **Deprecated**: The Logging feature is deprecated as of protocol version
7 `2026-07-28`
8 ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)).
9 Under the [feature lifecycle policy](/community/feature-lifecycle), it remains
10 in the specification for at least twelve months after this revision's release
11 before it becomes eligible for removal. New implementations **SHOULD NOT**
12 adopt it; existing implementations **SHOULD** migrate to logging to `stderr`
13 for stdio transports, or to [OpenTelemetry](https://opentelemetry.io/) for
14 structured observability. See the [deprecated features
15 registry](/specification/2026-07-28/deprecated).
16</Warning>
3> [!WARNING]
4>
5> **Deprecated**: The Logging feature is deprecated as of protocol version
6> `2026-07-28`
7> ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)).
8> Under the [feature lifecycle policy](/community/feature-lifecycle), it remains
9> in the specification for at least twelve months after this revision's release
10> before it becomes eligible for removal. New implementations **SHOULD NOT**
11> adopt it; existing implementations **SHOULD** migrate to logging to `stderr`
12> for stdio transports, or to [OpenTelemetry](https://opentelemetry.io/) for
13> structured observability. See the [deprecated features
14> registry](/specification/2026-07-28/deprecated).
1715
1816The Model Context Protocol (MCP) provides a standardized way for servers to send
1917structured log messages to clients. Clients control logging verbosity per-request via