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
176-200 of 295, page 8 of 12This capture is too large to show at once. Changes 176-200 of 295 are below, significant first; the rest are on the following screens.
specification/2026-07-28/basic/patterns/index Changed · +3 / -3 lines
from line 2
22
33This page defines the message patterns of the core protocol: the ways a
44client and server compose JSON-RPC
5[requests, responses, and notifications](/specification/2026-07-28/basic/index#messages)
5[requests, responses, and notifications](/specification/2026-07-28/basic/index.md#messages)
66into interactions. Every
7[transport](/specification/2026-07-28/basic/transports) carries all of these
7[transport](/specification/2026-07-28/basic/transports.md) carries all of these
88patterns; transports differ only in how messages are framed and delivered.
99
1010Every interaction begins with the client:
from line 40
4040complete a request, it answers with an
4141[`InputRequiredResult`](/specification/2026-07-28/basic/patterns/mrtr#inputrequiredresult)
4242and the client retries the request with the matching `inputResponses`. See
43[Multi Round-Trip Requests](/specification/2026-07-28/basic/patterns/mrtr).
43[Multi Round-Trip Requests](/specification/2026-07-28/basic/patterns/mrtr.md).
4444
4545```mermaid theme={null}
4646sequenceDiagram
specification/2026-07-28/basic/transports/index Changed · +9 / -9 lines
from line 7
77**binding**: it defines how messages are framed and delivered, how request
88metadata is carried, and how cancellation and termination are signaled. It
99does not define what the messages mean: the
10[message patterns](/specification/2026-07-28/basic/patterns) are part of the core
10[message patterns](/specification/2026-07-28/basic/patterns.md) are part of the core
1111protocol and are the same on every binding. The binding pages specify the
1212standard transports:
1313
141. [stdio](/specification/2026-07-28/basic/transports/stdio): newline-delimited
141. [stdio](/specification/2026-07-28/basic/transports/stdio.md): newline-delimited
1515 messages over the standard streams of a client-launched subprocess.
162. [Streamable HTTP](/specification/2026-07-28/basic/transports/streamable-http):
162. [Streamable HTTP](/specification/2026-07-28/basic/transports/streamable-http.md):
1717 each message is an HTTP POST to a single MCP endpoint; replies arrive as
1818 a JSON object or a request-scoped SSE stream.
1919
from line 28
2828A binding **MUST** deliver client-sent *requests* and *notifications* to the
2929server, and server-sent *responses* and *notifications* to the client. No
3030other message direction exists: per the
31[message patterns](/specification/2026-07-28/basic/patterns), servers do not
31[message patterns](/specification/2026-07-28/basic/patterns.md), servers do not
3232initiate JSON-RPC requests and clients do not send JSON-RPC responses.
3333
3434## Request Metadata
from line 40
4040
4141A binding **MAY** additionally mirror selected body fields into envelope
4242metadata. The Streamable HTTP transport mirrors them into
43[HTTP headers](/specification/2026-07-28/basic/transports/streamable-http#request-metadata)
43[HTTP headers](/specification/2026-07-28/basic/transports/streamable-http.md#request-metadata)
4444so that intermediaries can route and inspect requests without parsing the
4545body. The body remains the source of truth; bindings that mirror metadata
4646define how mismatches are rejected.
from line 51
5151the client sends a `notifications/cancelled` notification; on Streamable
5252HTTP it closes the request's response stream. The protocol-level rules are
5353the same everywhere; see
54[Cancellation](/specification/2026-07-28/basic/patterns/cancellation).
54[Cancellation](/specification/2026-07-28/basic/patterns/cancellation.md).
5555
5656## Custom Transports
5757
from line 62
6262
6363Implementers who choose to support custom transports **MUST** preserve the
6464JSON-RPC message format, the
65[message patterns](/specification/2026-07-28/basic/patterns), and the per-request
65[message patterns](/specification/2026-07-28/basic/patterns.md), and the per-request
6666metadata model. Custom transports **SHOULD** document their connection
6767establishment, message framing, and cancellation patterns to aid
6868interoperability.
from line 69
6969
7070Custom transports that run over a reliable bidirectional byte stream (e.g.,
7171Unix domain sockets or TCP) **SHOULD** reuse the
72[stdio framing](/specification/2026-07-28/basic/transports/stdio) rather than
72[stdio framing](/specification/2026-07-28/basic/transports/stdio.md) rather than
7373defining a new one: the stdio binding is just newline-delimited JSON-RPC
7474over a byte stream, and only its process-lifecycle rules are specific to
7575standard streams.
from line 80
8080`initialize` handshake and allowed servers to initiate JSON-RPC requests.
8181Clients and servers that interoperate with those revisions detect the
8282counterpart's era and fall back as described in
83[Versioning: Backward Compatibility](/specification/2026-07-28/basic/versioning#backward-compatibility-with-initialization-based-versions),
83[Versioning: Backward Compatibility](/specification/2026-07-28/basic/versioning.md#backward-compatibility-with-initialization-based-versions),
8484which includes a compatibility matrix for implementors. Each binding page
8585describes its transport-specific detection mechanics.
8686
specification/2026-07-28/basic/transports/stdio Changed · +10 / -10 lines
from line 21
2121newline-delimited JSON-RPC message per line over a reliable bidirectional
2222byte stream) works unchanged over Unix domain sockets, TCP connections, or
2323any similar channel.
24[Custom transports](/specification/2026-07-28/basic/transports#custom-transports)
24[Custom transports](/specification/2026-07-28/basic/transports.md#custom-transports)
2525built on such streams **SHOULD** reuse this framing and the message rules on
2626this page; only the subprocess-specific aspects (launch, `stderr`, shutdown
2727by closing the stream, process restart) need channel-specific equivalents.
from line 53
5353[`InputRequiredResult`][mrtr-input-required] replies; see
5454[Multi Round-Trip Requests][mrtr].
5555
56[mrtr]: /specification/2026-07-28/basic/patterns/mrtr
56[mrtr]: /specification/2026-07-28/basic/patterns/mrtr.md
5757
58[mrtr-input-required]: /specification/2026-07-28/basic/patterns/mrtr#inputrequiredresult
58[mrtr-input-required]: /specification/2026-07-28/basic/patterns/mrtr.md#inputrequiredresult
5959
60[subscriptions-listen]: /specification/2026-07-28/basic/patterns/subscriptions
60[subscriptions-listen]: /specification/2026-07-28/basic/patterns/subscriptions.md
6161
62[subscriptions-listen-request]: /specification/2026-07-28/schema#subscriptionslistenrequest
62[subscriptions-listen-request]: /specification/2026-07-28/schema.md#subscriptionslistenrequest
6363
6464## Request Metadata
6565
from line 70
7070the method name and arguments live where JSON-RPC puts them. There is no
7171header layer.
7272
73[meta-fields]: /specification/2026-07-28/basic/index#meta
73[meta-fields]: /specification/2026-07-28/basic/index.md#meta
7474
7575## Cancellation
7676
from line 81
8181practical and **MUST NOT** send any further messages for it. See
8282[Cancellation][cancellation] for the full rules.
8383
84[cancellation]: /specification/2026-07-28/basic/patterns/cancellation
84[cancellation]: /specification/2026-07-28/basic/patterns/cancellation.md
8585
8686## Shutdown
8787
from line 150
150150See [Versioning: Backward Compatibility][lifecycle-compat] for the era model
151151and a compatibility matrix for implementors.
152152
153[server-discover]: /specification/2026-07-28/schema#discoverrequest
153[server-discover]: /specification/2026-07-28/schema.md#discoverrequest
154154
155[unsupported-version]: /specification/2026-07-28/schema#unsupportedprotocolversionerror
155[unsupported-version]: /specification/2026-07-28/schema.md#unsupportedprotocolversionerror
156156
157[lifecycle-compat]: /specification/2026-07-28/basic/versioning#backward-compatibility-with-initialization-based-versions
157[lifecycle-compat]: /specification/2026-07-28/basic/versioning.md#backward-compatibility-with-initialization-based-versions
158158
specification/2026-07-28/basic/transports/streamable-http Changed · +25 / -25 lines
from line 13
1313> * Removal of the GET stream endpoint.
1414> * Removal of protocol-level sessions.
1515>
16> See the [changelog](/specification/2026-07-28/changelog) and
16> See the [changelog](/specification/2026-07-28/changelog.md) and
1717> [Backward Compatibility](#backward-compatibility) below.
1818
1919In the **Streamable HTTP** transport, the server operates as an independent
from line 40
4040as the **MCP endpoint**) that supports POST. For example, this could be a URL
4141like `https://example.com/mcp`.
4242
43[http-sse]: /specification/2024-11-05/basic/transports#http-with-sse
43[http-sse]: /specification/2024-11-05/basic/transports.md#http-with-sse
4444
4545[sse]: https://en.wikipedia.org/wiki/Server-sent_events
4646
from line 88
8888> This revision of the core protocol defines no client-to-server
8989> *notifications* over Streamable HTTP. The only client-sent notification in
9090> the core protocol, `notifications/cancelled`, is used only on the
91> [stdio](/specification/2026-07-28/basic/transports/stdio) transport; on
91> [stdio](/specification/2026-07-28/basic/transports/stdio.md) transport; on
9292> Streamable HTTP, closing the SSE response stream is itself the cancellation
9393> signal and no `notifications/cancelled` message is expected (see
9494> \[Cancellation]\[cancellation]). The notification rules above describe the
from line 145
145145
146146Resumable SSE streams via `Last-Event-ID` are not supported.
147147
148[notifications-progress]: /specification/2026-07-28/basic/patterns/progress
148[notifications-progress]: /specification/2026-07-28/basic/patterns/progress.md
149149
150[notifications-message]: /specification/2026-07-28/server/utilities/logging
150[notifications-message]: /specification/2026-07-28/server/utilities/logging.md
151151
152[input-required-result]: /specification/2026-07-28/schema#inputrequiredresult
152[input-required-result]: /specification/2026-07-28/schema.md#inputrequiredresult
153153
154[mrtr]: /specification/2026-07-28/basic/patterns/mrtr
154[mrtr]: /specification/2026-07-28/basic/patterns/mrtr.md
155155
156[sep-2322]: /seps/2322-MRTR
156[sep-2322]: /seps/2322-MRTR.md
157157
158[subscriptions-listen]: /specification/2026-07-28/basic/patterns/subscriptions
158[subscriptions-listen]: /specification/2026-07-28/basic/patterns/subscriptions.md
159159
160160## Message Flow
161161
from line 233
233233any further messages for it. See
234234[Cancellation][cancellation] for the full rules.
235235
236[cancellation]: /specification/2026-07-28/basic/patterns/cancellation
236[cancellation]: /specification/2026-07-28/basic/patterns/cancellation.md
237237
238238## Request Metadata
239239
from line 274
274274server that does not support such clients **MUST** reject a request without
275275the header per [Server Validation](#server-validation).
276276
277[unsupported-version]: /specification/2026-07-28/schema#unsupportedprotocolversionerror
277[unsupported-version]: /specification/2026-07-28/schema.md#unsupportedprotocolversionerror
278278
279[lifecycle-version]: /specification/2026-07-28/basic/versioning#protocol-version-negotiation
279[lifecycle-version]: /specification/2026-07-28/basic/versioning.md#protocol-version-negotiation
280280
281281### Standard Request Headers
282282
from line 361
361361`x-mcp-header` annotations, conforming clients **MUST** mirror the
362362designated parameter values into HTTP headers.
363363
364[tool-definitions]: /specification/2026-07-28/server/tools#x-mcp-header
364[tool-definitions]: /specification/2026-07-28/server/tools.md#x-mcp-header
365365
366366#### Schema Extension
367367
from line 597
597597
598598This error code is allocated from the sub-range the MCP specification
599599reserves for protocol-defined errors. See
600[Error Codes](/specification/2026-07-28/basic/index#error-codes).
600[Error Codes](/specification/2026-07-28/basic/index.md#error-codes).
601601
602602**Example error response:**
603603
from line 678
678678Servers and clients that need to interoperate with counterparts speaking
679679those protocol versions implement the behavior described in the corresponding
680680revision (for example,
681[2025-11-25: Streamable HTTP](/specification/2025-11-25/basic/transports#streamable-http)),
681[2025-11-25: Streamable HTTP](/specification/2025-11-25/basic/transports.md#streamable-http)),
682682in addition to the version-negotiation fallback described above.
683683
684684### HTTP+SSE Transport (2024-11-05)
from line 688
688688> **Deprecated**: The \[HTTP+SSE transport]\[http-sse] from protocol version
689689> 2024-11-05 has been deprecated since protocol version `2025-03-26` and is
690690> classified as Deprecated under the [feature lifecycle
691> policy](/community/feature-lifecycle#deprecating-a-feature)
691> policy](/community/feature-lifecycle.md#deprecating-a-feature)
692692> ([SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596)).
693693> New implementations **SHOULD NOT** adopt it; existing implementations
694694> **SHOULD** migrate to [Streamable
695> HTTP](/specification/2026-07-28/basic/transports/streamable-http). It is
695> HTTP](/specification/2026-07-28/basic/transports/streamable-http.md). It is
696696> eligible for removal in a future revision; see the [deprecated features
697> registry](/specification/2026-07-28/deprecated).
697> registry](/specification/2026-07-28/deprecated.md).
698698
699699Clients and servers can maintain backward compatibility with the
700700deprecated [HTTP+SSE transport][http-sse] (from
from line 725
725725 server running the old HTTP+SSE transport, and should use that
726726 transport for all subsequent communication.
727727
728[lifecycle-compat]: /specification/2026-07-28/basic/versioning#backward-compatibility-with-initialization-based-versions
728[lifecycle-compat]: /specification/2026-07-28/basic/versioning.md#backward-compatibility-with-initialization-based-versions
729729
specification/2026-07-28/basic/versioning Changed · +6 / -6 lines
from line 76
7676## Extension Negotiation
7777
7878Clients and servers can negotiate support for optional
79[extensions](/docs/extensions/overview) beyond the core protocol. Extensions
79[extensions](/docs/extensions/overview.md) beyond the core protocol. Extensions
8080are advertised in the `extensions` field of capabilities, which is a map of
8181extension identifiers to per-extension settings objects. Extension identifiers
8282**MUST** follow the [`_meta` key naming rules](/specification/2026-07-28/basic/index#meta),
from line 83
8383with a mandatory prefix.
8484
8585The following is an example of a client that advertises the
86[MCP Apps extension](/extensions/apps/overview) identified as `io.modelcontextprotocol/ui`:
86[MCP Apps extension](/extensions/apps/overview.md) identified as `io.modelcontextprotocol/ui`:
8787
8888```json theme={null}
8989{
from line 98
9898}
9999```
100100
101An example of [Tasks extension](/extensions/tasks/overview) identified as `io.modelcontextprotocol/tasks`:
101An example of [Tasks extension](/extensions/tasks/overview.md) identified as `io.modelcontextprotocol/tasks`:
102102
103103```json theme={null}
104104{
from line 129
129129server's era with transport-specific mechanics, specified in the binding
130130pages:
131131
132* [stdio](/specification/2026-07-28/basic/transports/stdio#backward-compatibility):
132* [stdio](/specification/2026-07-28/basic/transports/stdio.md#backward-compatibility):
133133 probe with `server/discover` and fall back on any error that is not a
134134 recognized modern error.
135* [Streamable HTTP](/specification/2026-07-28/basic/transports/streamable-http#backward-compatibility):
135* [Streamable HTTP](/specification/2026-07-28/basic/transports/streamable-http.md#backward-compatibility):
136136 attempt a modern request and inspect the body of a `400 Bad Request`
137137 before falling back.
138138
from line 163
163163| Modern | Legacy | Fails. The server may reject the request with an implementation-defined error, stay silent, or even process an era-ambiguous method under legacy semantics. On stdio, clients **SHOULD** send `server/discover` first to fail deterministically; the client then surfaces an actionable error to the user. |
164164| Dual-era | Modern | Works. The stdio probe returns a `DiscoverResult` (or `UnsupportedProtocolVersionError`); on HTTP, the first modern request succeeds or returns a modern error. The client stays modern. |
165165| Dual-era | Legacy | Works. stdio: the probe returns a non-modern error or times out, and the client falls back to `initialize`. HTTP: the modern request returns a `4xx` without a recognized modern error body, and the client falls back to `initialize` (and possibly further to the deprecated HTTP+SSE transport). |
166| Legacy | Modern | Fails. stdio: the server rejects `initialize` with a JSON-RPC error; the exact code is implementation-defined (`initialize` is an unknown method and the request also lacks the required `_meta` fields). HTTP: the request is missing the required headers and is rejected per [server validation](/specification/2026-07-28/basic/transports/streamable-http#server-validation) with `400 Bad Request` (a client on the deprecated HTTP+SSE transport fails at its opening `GET` instead). Legacy clients have no fall-forward mechanism. |
166| Legacy | Modern | Fails. stdio: the server rejects `initialize` with a JSON-RPC error; the exact code is implementation-defined (`initialize` is an unknown method and the request also lacks the required `_meta` fields). HTTP: the request is missing the required headers and is rejected per [server validation](/specification/2026-07-28/basic/transports/streamable-http.md#server-validation) with `400 Bad Request` (a client on the deprecated HTTP+SSE transport fails at its opening `GET` instead). Legacy clients have no fall-forward mechanism. |
167167| Legacy | Dual-era | Works. The server answers `initialize` and serves the client according to the negotiated legacy revision. |
168168| Legacy | Legacy | Works according to the legacy revision; out of scope for this document. |
169169
specification/2026-07-28/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-11-25](/specification/2025-11-25).
4the previous revision, [2025-11-25](/specification/2025-11-25.md).
55
66## Major changes
77
from line 19
1919
20207. Multi Round-Trip Requests (MRTR) pattern introduced which replaces the previous approach of sending server-initiated requests, such as `roots/list`, `sampling/createMessage`, or `elicitation/create`. Servers return an `InputRequiredResult` (`resultType: "input_required"`) whose `inputRequests` field carries the requests for the additional information needed to process the request. Clients respond with `inputResponses` on a retry of the original request providing the requested information. ([SEP-2322](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2322)).
2121
228. All results now carry a required `resultType` field: `"complete"` for ordinary results and `"input_required"` for [multi round-trip request](/specification/2026-07-28/basic/patterns/mrtr) interim results. Clients **MUST** treat results from earlier-protocol servers that omit the field as `"complete"` ([SEP-2322](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2322)).
228. All results now carry a required `resultType` field: `"complete"` for ordinary results and `"input_required"` for [multi round-trip request](/specification/2026-07-28/basic/patterns/mrtr.md) interim results. Clients **MUST** treat results from earlier-protocol servers that omit the field as `"complete"` ([SEP-2322](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2322)).
2323
24249. Remove SSE stream resumability and message redelivery (the `Last-Event-ID` header and SSE event IDs) from the Streamable HTTP transport. A broken response stream loses the in-flight request; clients **MUST** re-issue it as a new request with a new request ID ([SEP-2575](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575)).
2525
2626## Minor changes
2727
281. Add `extensions` field to `ClientCapabilities` and `ServerCapabilities` to support optional [extensions](/docs/extensions/overview) beyond the core protocol.
281. Add `extensions` field to `ClientCapabilities` and `ServerCapabilities` to support optional [extensions](/docs/extensions/overview.md) beyond the core protocol.
29292. Document OpenTelemetry trace context propagation conventions for `_meta` keys (`traceparent`, `tracestate`, `baggage`) ([SEP-414](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/414)).
30303. Servers **SHOULD** return tools from `tools/list` in a deterministic order to enable client-side caching and improve LLM prompt cache hit rates.
31314. Require standard MCP request headers (`Mcp-Method`, `Mcp-Name`) on Streamable HTTP POST requests, and add support for custom headers from tool parameters via `x-mcp-header` ([SEP-2243](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2243)).
from line 49
494911. Remove the `notifications/elicitation/complete` notification and the
5050 `elicitationId` field of URL mode elicitation requests, both introduced in
5151 `2025-11-25`. Under the
52 [Multi Round-Trip Requests](/specification/2026-07-28/basic/patterns/mrtr) pattern, the
52 [Multi Round-Trip Requests](/specification/2026-07-28/basic/patterns/mrtr.md) pattern, the
5353 client learns the outcome of an out-of-band interaction by retrying the original
5454 request, so a server-initiated completion signal — and the identifier used to
5555 correlate it — no longer fit the protocol. Servers needing to correlate an
5656 elicitation across retries encode their own identifier in `requestState`.
5712. Define an [error code allocation policy](/specification/2026-07-28/basic/index#error-codes)
5712. Define an [error code allocation policy](/specification/2026-07-28/basic/index.md#error-codes)
5858 partitioning the JSON-RPC server-error range: `-32000` to `-32019` remains
5959 implementation-defined (existing SDK usage is grandfathered), `-32020` to `-32099` is
6060 reserved for the MCP specification. Renumber the error codes introduced in this draft
from line 64
6464
6565## Deprecated
6666
67Features listed here remain part of the specification but are scheduled for removal under the [feature lifecycle and deprecation policy](/community/feature-lifecycle). New implementations should not adopt them. The [deprecated features registry](/specification/2026-07-28/deprecated) tracks every feature currently in the Deprecated state.
67Features listed here remain part of the specification but are scheduled for removal under the [feature lifecycle and deprecation policy](/community/feature-lifecycle.md). New implementations should not adopt them. The [deprecated features registry](/specification/2026-07-28/deprecated.md) tracks every feature currently in the Deprecated state.
6868
69691. Deprecate the Roots, Sampling, and Logging features
7070 ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)).
from line 78
78782. Reclassify the HTTP+SSE transport (deprecated since protocol version
7979 `2025-03-26`) as Deprecated under the feature lifecycle policy
8080 ([SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596)).
81 Migrate to [Streamable HTTP](/specification/2026-07-28/basic/transports/streamable-http).
81 Migrate to [Streamable HTTP](/specification/2026-07-28/basic/transports/streamable-http.md).
8282
83833. Reclassify the `includeContext` values `"thisServer"` and `"allServers"`
8484 (soft-deprecated since protocol version `2025-11-25`) as Deprecated
from line 89
89894. Deprecate the OAuth 2.0 Dynamic Client Registration Protocol
9090 ([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)) as a client registration
9191 mechanism in favor of
92 [Client ID Metadata Documents](/specification/2026-07-28/basic/authorization/client-registration#client-id-metadata-documents)
92 [Client ID Metadata Documents](/specification/2026-07-28/basic/authorization/client-registration.md#client-id-metadata-documents)
9393 ([PR #2858](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2858)).
9494 It remains available for backwards compatibility with authorization servers that do
9595 not support Client ID Metadata Documents.
from line 101
101101## Governance and process updates
102102
1031031. Adopt a specification
104 [feature lifecycle and deprecation policy](/community/feature-lifecycle)
104 [feature lifecycle and deprecation policy](/community/feature-lifecycle.md)
105105 defining the Active, Deprecated, and Removed feature states, a minimum
106106 twelve-month deprecation window, and a
107 [registry of deprecated features](/specification/2026-07-28/deprecated)
107 [registry of deprecated features](/specification/2026-07-28/deprecated.md)
108108 ([SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596)).
109109
110110## Process changes
specification/2026-07-28/client/elicitation Changed · +12 / -12 lines
from line 333
333333>
334334> **Important**: URL mode elicitation is *not* for authorizing the MCP client's
335335> access to the MCP server (that's handled by [MCP
336> authorization](../basic/authorization)). Instead, it's used when the MCP
336> authorization](/specification/2026-07-28/basic/authorization.md)). Instead, it's used when the MCP
337337> server needs to obtain sensitive information or third-party authorization on
338338> behalf of the user. The MCP client's bearer token remains unchanged. The
339339> client's only responsibility is to provide the user with context about the
from line 462
462462
463463### Statefulness
464464
465Elicitations do not require that the server maintain state about users with the [multi round-trip requests](/specification/2026-07-28/basic/patterns/mrtr#multi-round-trip-requests) mechanism.
465Elicitations do not require that the server maintain state about users with the [multi round-trip requests](/specification/2026-07-28/basic/patterns/mrtr.md#multi-round-trip-requests) mechanism.
466466
467However, if state is stored, servers implementing elicitation **MUST** securely associate this state with individual users following the guidelines in the [security best practices](/docs/2026-07-28/tutorials/security/security_best_practices) document. Specifically:
467However, if state is stored, servers implementing elicitation **MUST** securely associate this state with individual users following the guidelines in the [security best practices](/docs/2026-07-28/tutorials/security/security_best_practices.md) document. Specifically:
468468
469469* State storage **MUST** be protected against unauthorized access
470* For remote MCP servers, user identification **MUST** be derived from credentials acquired via [MCP authorization](../basic/authorization) when possible (e.g. `sub` claim)
470* For remote MCP servers, user identification **MUST** be derived from credentials acquired via [MCP authorization](/specification/2026-07-28/basic/authorization.md) when possible (e.g. `sub` claim)
471471
472472> [!NOTE]
473473>
from line 492
492492### URL Mode Elicitation for OAuth Flows
493493
494494URL mode elicitation enables a pattern where MCP servers act as OAuth clients to third-party resource servers.
495Authorization 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.
495Authorization with external APIs enabled by URL mode elicitation is separate from [MCP authorization](/specification/2026-07-28/basic/authorization.md). MCP servers **MUST NOT** rely on URL mode elicitation to authorize users for themselves.
496496
497497#### Understanding the Distinction
498498
499* **MCP Authorization**: Required OAuth flow between the MCP client and MCP server (covered in the [authorization specification](../basic/authorization))
499* **MCP Authorization**: Required OAuth flow between the MCP client and MCP server (covered in the [authorization specification](/specification/2026-07-28/basic/authorization.md))
500500* **External (third-party) Authorization**: Optional authorization between the MCP server and a third-party resource server, initiated via URL mode elicitation
501501
502502In external authorization, the server acts as both:
from line 513
513513The critical security requirements are:
514514
5155151. **The third-party credentials MUST NOT transit through the MCP client**: The client must never see third-party credentials to protect the security boundary
5162. **The MCP server MUST NOT use the client's credentials for the third-party service**: That would be [token passthrough](/docs/2026-07-28/tutorials/security/security_best_practices#token-passthrough), which is forbidden
5162. **The MCP server MUST NOT use the client's credentials for the third-party service**: That would be [token passthrough](/docs/2026-07-28/tutorials/security/security_best_practices.md#token-passthrough), which is forbidden
5175173. **The user MUST authorize the MCP server directly**: The interaction happens outside the MCP protocol, without involving the MCP client
5185184. **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).
519519
from line 522
522522> [!NOTE]
523523>
524524> For additional background, refer to the [token passthrough
525> section](/docs/2026-07-28/tutorials/security/security_best_practices#token-passthrough)
525> section](/docs/2026-07-28/tutorials/security/security_best_practices.md#token-passthrough)
526526> of the Security Best Practices document to understand why MCP servers cannot
527527> act as pass-through proxies.
528528
from line 617
617617### Identifying the User
618618
619619Servers **MUST NOT** rely on client-provided user identification without server verification, as this can be forged.
620Instead, servers **SHOULD** follow [security best practices](/docs/2026-07-28/tutorials/security/security_best_practices).
620Instead, servers **SHOULD** follow [security best practices](/docs/2026-07-28/tutorials/security/security_best_practices.md).
621621
622622Non-normative examples:
623623
624624* Incorrect: Treat user input like "I am [[email protected]](mailto:[email protected])" as authoritative
625* Correct: Rely on [authorization](../basic/authorization) to identify the user
625* Correct: Rely on [authorization](/specification/2026-07-28/basic/authorization.md) to identify the user
626626
627627### Form Mode Security
628628
from line 634
634634
635635URL 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.
636636
637Typically 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.
637Typically identity verification is done by leveraging the [MCP authorization server](/specification/2026-07-28/basic/authorization.md) to identify the user, through a session cookie or equivalent in the browser.
638638
639639For 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:
640640
specification/2026-07-28/client/sampling Changed · +4 / -4 lines
from line 5
55> **Deprecated**: The Sampling feature is deprecated as of protocol version
66> `2026-07-28`
77> ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)).
8> Under the [feature lifecycle policy](/community/feature-lifecycle), it remains
8> Under the [feature lifecycle policy](/community/feature-lifecycle.md), it remains
99> in the specification for at least twelve months after this revision's release
1010> before it becomes eligible for removal. New implementations **SHOULD NOT**
1111> adopt it; existing implementations **SHOULD** migrate to integrating directly
1212> with LLM provider APIs. See the [deprecated features
13> registry](/specification/2026-07-28/deprecated).
13> registry](/specification/2026-07-28/deprecated.md).
1414
1515The Model Context Protocol (MCP) provides a standardized way for servers to request LLM
1616sampling ("completions" or "generations") from language models via clients. This flow
from line 94
9494>
9595> The `includeContext` parameter values `"thisServer"` and `"allServers"` are
9696> deprecated under the [feature lifecycle
97> policy](/community/feature-lifecycle#deprecating-a-feature)
97> policy](/community/feature-lifecycle.md#deprecating-a-feature)
9898> ([SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596));
9999> they will be removed no later than the Sampling feature itself. Servers
100100> **SHOULD** avoid using these values (e.g. can just omit `includeContext` since
101101> it defaults to `"none"`), and **SHOULD NOT** use them unless the client
102102> declares `sampling.context` capability. See the [deprecated features
103> registry](/specification/2026-07-28/deprecated).
103> registry](/specification/2026-07-28/deprecated.md).
104104
105105## Protocol Messages
106106
specification/2026-07-28/deprecated Changed · +8 / -8 lines
from line 2
22
33This page is the registry of specification features that are currently in the
44**Deprecated** state under the
5[feature lifecycle and deprecation policy](/community/feature-lifecycle)
5[feature lifecycle and deprecation policy](/community/feature-lifecycle.md)
66([SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596)).
77
88A Deprecated feature remains part of the specification but is scheduled for
from line 19
1919
2020| Feature | Deprecation SEP | Deprecated in | Migration path | Earliest removal |
2121| - | - | - | - | - |
22| [Roots](/specification/2026-07-28/client/roots) | [SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577) | `2026-07-28` | Pass directories or files via tool parameters, resource URIs, or server configuration | First revision released on or after 2027-07-28 |
23| [Sampling](/specification/2026-07-28/client/sampling) | [SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577) | `2026-07-28` | Integrate directly with LLM provider APIs | First revision released on or after 2027-07-28 |
24| [Logging](/specification/2026-07-28/server/utilities/logging) | [SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577) | `2026-07-28` | Log to `stderr` for stdio transports; use [OpenTelemetry](https://opentelemetry.io/) for observability | First revision released on or after 2027-07-28 |
25| [Dynamic Client Registration](/specification/2026-07-28/basic/authorization/client-registration#dynamic-client-registration) | [PR #2858](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2858) | `2026-07-28` | [Client ID Metadata Documents](/specification/2026-07-28/basic/authorization/client-registration#client-id-metadata-documents) | First revision released on or after 2027-07-28 |
26| `includeContext: "thisServer"` / `"allServers"` ([Sampling](/specification/2026-07-28/client/sampling#capabilities)) | [SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596) | `2025-11-25` | Omit the field or use `"none"` | Follows Sampling ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)) |
27| [HTTP+SSE transport](/specification/2024-11-05/basic/transports#http-with-sse) | [SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596) | `2025-03-26` | [Streamable HTTP](/specification/2026-07-28/basic/transports/streamable-http) | Three months after SEP-2596 reaches Final |
22| [Roots](/specification/2026-07-28/client/roots.md) | [SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577) | `2026-07-28` | Pass directories or files via tool parameters, resource URIs, or server configuration | First revision released on or after 2027-07-28 |
23| [Sampling](/specification/2026-07-28/client/sampling.md) | [SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577) | `2026-07-28` | Integrate directly with LLM provider APIs | First revision released on or after 2027-07-28 |
24| [Logging](/specification/2026-07-28/server/utilities/logging.md) | [SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577) | `2026-07-28` | Log to `stderr` for stdio transports; use [OpenTelemetry](https://opentelemetry.io/) for observability | First revision released on or after 2027-07-28 |
25| [Dynamic Client Registration](/specification/2026-07-28/basic/authorization/client-registration.md#dynamic-client-registration) | [PR #2858](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2858) | `2026-07-28` | [Client ID Metadata Documents](/specification/2026-07-28/basic/authorization/client-registration.md#client-id-metadata-documents) | First revision released on or after 2027-07-28 |
26| `includeContext: "thisServer"` / `"allServers"` ([Sampling](/specification/2026-07-28/client/sampling.md#capabilities)) | [SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596) | `2025-11-25` | Omit the field or use `"none"` | Follows Sampling ([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)) |
27| [HTTP+SSE transport](/specification/2024-11-05/basic/transports.md#http-with-sse) | [SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596) | `2025-03-26` | [Streamable HTTP](/specification/2026-07-28/basic/transports/streamable-http.md) | Three months after SEP-2596 reaches Final |
2828
2929The HTTP+SSE transport and the `includeContext` values were already described
3030as deprecated before the lifecycle policy existed; SEP-2596 reclassifies them
31as Deprecated under its [transition provisions](/community/feature-lifecycle).
31as Deprecated under its [transition provisions](/community/feature-lifecycle.md).
3232
3333## Removed
3434
specification/2026-07-28/index Changed · +8 / -8 lines
from line 70
7070
7171### Extensions
7272
73Beyond the core protocol, MCP defines optional [extensions](/extensions/overview)
73Beyond the core protocol, MCP defines optional [extensions](/extensions/overview.md)
7474that add modular, specialized, or experimental functionality. Extensions
7575are always opt-in and require explicit support from both client and server, negotiated
7676during initialization. Notable extensions include:
7777
78* **[Tasks](/extensions/tasks/overview)**: Asynchronous execution of long-running
78* **[Tasks](/extensions/tasks/overview.md)**: Asynchronous execution of long-running
7979 operations, with polling, mid-flight input, and durable handles
80* **[Skills over MCP](/community/working-groups/skills-over-mcp)**: Rich, structured
80* **[Skills over MCP](/community/working-groups/skills-over-mcp.md)**: Rich, structured
8181 instructions for agent workflows, discovered and consumed through MCP
82* **[MCP Apps](/extensions/apps/overview)**: Interactive UI elements (charts, forms,
82* **[MCP Apps](/extensions/apps/overview.md)**: Interactive UI elements (charts, forms,
8383 video players) rendered inline within conversations
8484
8585## Security and Trust & Safety
from line 123
123123
124124Explore the detailed specification for each protocol component:
125125
126> **[Architecture](/specification/2026-07-28/architecture)**
126> **[Architecture](/specification/2026-07-28/architecture.md)**
127127
128> **[Base Protocol](/specification/2026-07-28/basic)**
128> **[Base Protocol](/specification/2026-07-28/basic.md)**
129129
130> **[Server Features](/specification/2026-07-28/server)**
130> **[Server Features](/specification/2026-07-28/server.md)**
131131
132132> **[Client Features](/specification/2026-07-28/client)**
133133
134> **[Contributing](/community/contributing)**
134> **[Contributing](/community/contributing.md)**
135135
specification/2026-07-28/server/discover Changed · +4 / -4 lines
from line 29
2929## Response
3030
3131The server replies with its supported protocol versions, capabilities, and
32identity. This operation supports [caching](/specification/2026-07-28/server/utilities/caching).
32identity. This operation supports [caching](/specification/2026-07-28/server/utilities/caching.md).
3333
3434```json theme={null}
3535{
from line 73
7373 HTTP status code to drive fallback. A client that supports both modern
7474 (per-request `_meta`) and legacy (`initialize` handshake) servers **SHOULD**
7575 send `server/discover` first; see
76 [stdio: Backward Compatibility](/specification/2026-07-28/basic/transports/stdio#backward-compatibility)
76 [stdio: Backward Compatibility](/specification/2026-07-28/basic/transports/stdio.md#backward-compatibility)
7777 for the fallback rules.
7878
79See [Protocol Version Negotiation](/specification/2026-07-28/basic/versioning#protocol-version-negotiation)
79See [Protocol Version Negotiation](/specification/2026-07-28/basic/versioning.md#protocol-version-negotiation)
8080for the full version-selection flow. For HTTP-specific status codes returned for
81unknown methods, see the [Protocol Version Header](/specification/2026-07-28/basic/transports/streamable-http#protocol-version-header)
81unknown methods, see the [Protocol Version Header](/specification/2026-07-28/basic/transports/streamable-http.md#protocol-version-header)
8282section in Transports.
8383
8484## Data Types
specification/2026-07-28/server/index Changed · +3 / -3 lines
from line 20
2020
2121Explore these key primitives in more detail below:
2222
23> **[Prompts](/specification/2026-07-28/server/prompts)**
23> **[Prompts](/specification/2026-07-28/server/prompts.md)**
2424
25> **[Resources](/specification/2026-07-28/server/resources)**
25> **[Resources](/specification/2026-07-28/server/resources.md)**
2626
27> **[Tools](/specification/2026-07-28/server/tools)**
27> **[Tools](/specification/2026-07-28/server/tools.md)**
2828
specification/2026-07-28/server/prompts Changed · +6 / -6 lines
from line 64
6464### Listing Prompts
6565
6666To retrieve available prompts, clients send a `prompts/list` request. This operation
67supports [pagination](/specification/2026-07-28/server/utilities/pagination) and [caching](/specification/2026-07-28/server/utilities/caching).
67supports [pagination](/specification/2026-07-28/server/utilities/pagination.md) and [caching](/specification/2026-07-28/server/utilities/caching.md).
6868
6969**Request:**
7070
from line 118
118118### Getting a Prompt
119119
120120To retrieve a specific prompt, clients send a `prompts/get` request. Arguments may be
121auto-completed through [the completion API](/specification/2026-07-28/server/utilities/completion).
121auto-completed through [the completion API](/specification/2026-07-28/server/utilities/completion.md).
122122
123123**Request:**
124124
from line 158
158158}
159159```
160160
161Servers **MAY** also respond to `prompts/get` with an [`InputRequiredResult`](/specification/2026-07-28/basic/patterns/mrtr#inputrequiredresult) to indicate that additional input is needed before the prompt can be resolved. This follows the [multi round-trip requests](/specification/2026-07-28/basic/patterns/mrtr#multi-round-trip-requests) mechanism. When retrying the request, clients include `inputResponses` and, if provided by the server, `requestState` in the request parameters.
161Servers **MAY** also respond to `prompts/get` with an [`InputRequiredResult`](/specification/2026-07-28/basic/patterns/mrtr#inputrequiredresult) to indicate that additional input is needed before the prompt can be resolved. This follows the [multi round-trip requests](/specification/2026-07-28/basic/patterns/mrtr.md#multi-round-trip-requests) mechanism. When retrying the request, clients include `inputResponses` and, if provided by the server, `requestState` in the request parameters.
162162
163163### List Changed Notification
164164
from line 221
221221> [!NOTE]
222222>
223223> All content types in prompt messages support optional
224> [annotations](/specification/2026-07-28/server/resources#annotations) for
224> [annotations](/specification/2026-07-28/server/resources.md#annotations) for
225225> metadata about audience, priority, and modification times.
226226
227227#### Text Content
from line 270
270270#### Resource Links
271271
272272Prompt messages **MAY** include links to
273[Resources](/specification/2026-07-28/server/resources), to provide additional context or
273[Resources](/specification/2026-07-28/server/resources.md), to provide additional context or
274274data without embedding the resource contents directly. In this case, the prompt message
275275returns a URI that can be fetched by the client:
276276
from line 284
284284}
285285```
286286
287Resource links support the same [Resource annotations](/specification/2026-07-28/server/resources#annotations)
287Resource links support the same [Resource annotations](/specification/2026-07-28/server/resources.md#annotations)
288288as regular resources to help clients understand how to use them.
289289
290290#### Embedded Resources
specification/2026-07-28/server/resources Changed · +8 / -8 lines
from line 81
8181### Listing Resources
8282
8383To discover available resources, clients send a `resources/list` request. This operation
84supports [pagination](/specification/2026-07-28/server/utilities/pagination) and [caching](/specification/2026-07-28/server/utilities/caching).
84supports [pagination](/specification/2026-07-28/server/utilities/pagination.md) and [caching](/specification/2026-07-28/server/utilities/caching.md).
8585
8686**Request:**
8787
from line 130
130130### Reading Resources
131131
132132To retrieve resource contents, clients send a `resources/read` request. This operation
133supports [caching](/specification/2026-07-28/server/utilities/caching).
133supports [caching](/specification/2026-07-28/server/utilities/caching.md).
134134
135135**Request:**
136136
from line 170
170170`resources/read` request. For example, a server could return the contents of
171171several files when a directory resource is read.
172172
173Servers **MAY** also respond to `resources/read` with an [`InputRequiredResult`](/specification/2026-07-28/basic/patterns/mrtr#inputrequiredresult) to indicate that additional input is needed before the resource can be read. This follows the [multi round-trip requests](/specification/2026-07-28/basic/patterns/mrtr#multi-round-trip-requests) mechanism. When retrying the request, clients include `inputResponses` and, if provided by the server, `requestState` in the request parameters.
173Servers **MAY** also respond to `resources/read` with an [`InputRequiredResult`](/specification/2026-07-28/basic/patterns/mrtr#inputrequiredresult) to indicate that additional input is needed before the resource can be read. This follows the [multi round-trip requests](/specification/2026-07-28/basic/patterns/mrtr.md#multi-round-trip-requests) mechanism. When retrying the request, clients include `inputResponses` and, if provided by the server, `requestState` in the request parameters.
174174
175175Alternatively, if the scheme of `uri` is `https://`, clients may fetch the resource directly from the web. See the [Common URI Schemes section](#https%3A%2F%2F) for more information.
176176
from line 178
178178
179179Resource templates allow servers to expose parameterized resources using
180180[URI templates](https://datatracker.ietf.org/doc/html/rfc6570). Arguments may be
181auto-completed through [the completion API](/specification/2026-07-28/server/utilities/completion).
182This operation supports [pagination](/specification/2026-07-28/server/utilities/pagination) and [caching](/specification/2026-07-28/server/utilities/caching).
181auto-completed through [the completion API](/specification/2026-07-28/server/utilities/completion.md).
182This operation supports [pagination](/specification/2026-07-28/server/utilities/pagination.md) and [caching](/specification/2026-07-28/server/utilities/caching.md).
183183
184184**Request:**
185185
from line 259
259259See [Subscriptions][subscriptions] for the full protocol mechanics (acknowledgment,
260260`subscriptionId` correlation, and cancellation).
261261
262[subscriptions-listen]: /specification/2026-07-28/schema#subscriptionslistenrequest
262[subscriptions-listen]: /specification/2026-07-28/schema.md#subscriptionslistenrequest
263263
264[subscriptions]: /specification/2026-07-28/basic/patterns/subscriptions
264[subscriptions]: /specification/2026-07-28/basic/patterns/subscriptions.md
265265
266266## Message Flow
267267
specification/2026-07-28/server/tools Changed · +13 / -13 lines
from line 72
7272### Listing Tools
7373
7474To discover available tools, clients send a `tools/list` request. This operation supports
75[pagination](/specification/2026-07-28/server/utilities/pagination) and [caching](/specification/2026-07-28/server/utilities/caching).
75[pagination](/specification/2026-07-28/server/utilities/pagination.md) and [caching](/specification/2026-07-28/server/utilities/caching.md).
7676
7777**Request:**
7878
from line 167
167167
168168### Input Required Tool Results
169169
170Servers **MAY** respond to `tools/call` with an [`InputRequiredResult`](/specification/2026-07-28/basic/patterns/mrtr#inputrequiredresult) to indicate that additional input is needed before the tool call can be completed. This follows the [multi round-trip requests](/specification/2026-07-28/basic/patterns/mrtr#multi-round-trip-requests) mechanism.
170Servers **MAY** respond to `tools/call` with an [`InputRequiredResult`](/specification/2026-07-28/basic/patterns/mrtr#inputrequiredresult) to indicate that additional input is needed before the tool call can be completed. This follows the [multi round-trip requests](/specification/2026-07-28/basic/patterns/mrtr.md#multi-round-trip-requests) mechanism.
171171
172172When retrying the request with input responses, clients include `inputResponses` and, if provided by the server, `requestState` in the request parameters:
173173
from line 282
282282* `description`: Human-readable description of functionality
283283* `icons`: Optional array of icons for display in user interfaces
284284* `inputSchema`: JSON Schema defining expected parameters
285 * Follows the [JSON Schema usage guidelines](/specification/2026-07-28/basic#json-schema-usage)
285 * Follows the [JSON Schema usage guidelines](/specification/2026-07-28/basic.md#json-schema-usage)
286286 * Defaults to 2020-12 if no `$schema` field is present
287287 * **MUST** be a valid JSON Schema object (not `null`)
288288 * For tools with no parameters, use one of these valid approaches:
from line 291
291291 * Properties **MAY** include an [`x-mcp-header`](#x-mcp-header) annotation to expose
292292 parameter values as HTTP headers
293293* `outputSchema`: Optional JSON Schema defining expected output structure
294 * Follows the [JSON Schema usage guidelines](/specification/2026-07-28/basic#json-schema-usage)
294 * Follows the [JSON Schema usage guidelines](/specification/2026-07-28/basic.md#json-schema-usage)
295295 * Defaults to 2020-12 if no `$schema` field is present
296296* `annotations`: Optional properties describing tool behavior
297297
from line 327
327327
328328The `x-mcp-header` extension property allows servers to designate specific tool
329329parameters to be mirrored into HTTP headers when using the
330[Streamable HTTP transport](/specification/2026-07-28/basic/transports/streamable-http#custom-headers-from-tool-parameters).
330[Streamable HTTP transport](/specification/2026-07-28/basic/transports/streamable-http.md#custom-headers-from-tool-parameters).
331331This enables network intermediaries (load balancers, proxies, WAFs) to route and process
332332requests based on parameter values without parsing the request body.
333333
from line 348
348348 safe range for integers represented using IEEE754 double-precision floating point numbers (−2<sup>53</sup>+1 to 2<sup>53</sup>−1)
349349* **MUST** only be applied to properties that are *statically reachable* from the schema
350350 root, as defined in
351 [Custom Headers from Tool Parameters](/specification/2026-07-28/basic/transports/streamable-http#custom-headers-from-tool-parameters),
351 [Custom Headers from Tool Parameters](/specification/2026-07-28/basic/transports/streamable-http.md#custom-headers-from-tool-parameters),
352352 which also defines how header values are extracted from call arguments
353353
354354Clients using the Streamable HTTP transport **MUST** reject tool definitions where any
from line 401
401401>
402402> All content types (text, image, audio, resource links, and embedded resources)
403403> support optional
404> [annotations](/specification/2026-07-28/server/resources#annotations) that
404> [annotations](/specification/2026-07-28/server/resources.md#annotations) that
405405> provide metadata about audience, priority, and modification times. This is the
406406> same annotation format used by resources and prompts.
407407
from line 440
440440
441441#### Resource Links
442442
443A tool **MAY** return links to [Resources](/specification/2026-07-28/server/resources), to provide additional context
443A tool **MAY** return links to [Resources](/specification/2026-07-28/server/resources.md), to provide additional context
444444or data. In this case, the tool will return a URI that can be subscribed to or fetched by the client:
445445
446446```json theme={null}
from line 453
453453}
454454```
455455
456Resource links support the same [Resource annotations](/specification/2026-07-28/server/resources#annotations) as regular resources to help clients understand how to use them.
456Resource links support the same [Resource annotations](/specification/2026-07-28/server/resources.md#annotations) as regular resources to help clients understand how to use them.
457457
458458> [!NOTE]
459459>
from line 462
462462
463463#### Embedded Resources
464464
465[Resources](/specification/2026-07-28/server/resources) **MAY** be embedded to provide additional context
466or data using a suitable [URI scheme](./resources#common-uri-schemes). Servers that use embedded resources **SHOULD** implement the `resources` capability:
465[Resources](/specification/2026-07-28/server/resources.md) **MAY** be embedded to provide additional context
466or data using a suitable [URI scheme](/specification/2026-07-28/server/resources.md#common-uri-schemes). Servers that use embedded resources **SHOULD** implement the `resources` capability:
467467
468468```json theme={null}
469469{
from line 481
481481}
482482```
483483
484Embedded resources support the same [Resource annotations](/specification/2026-07-28/server/resources#annotations) as regular resources to help clients understand how to use them.
484Embedded resources support the same [Resource annotations](/specification/2026-07-28/server/resources.md#annotations) as regular resources to help clients understand how to use them.
485485
486486#### Structured Content
487487
from line 728
7287281. **Protocol Errors** indicate issues with the request structure itself that models are less likely to be able to fix:
729729
730730 * Unknown tool
731 * Malformed requests (requests that fail to satisfy [CallToolRequest schema](/specification/2026-07-28/schema#calltoolrequest))
731 * Malformed requests (requests that fail to satisfy [CallToolRequest schema](/specification/2026-07-28/schema.md#calltoolrequest))
732732 * Server errors
733733
734734 They are returned as standard JSON-RPC errors:
specification/2026-07-28/server/utilities/caching Changed · +3 / -3 lines
from line 17
1717* `resources/read`
1818
1919Interim results with `resultType: "input_required"` (see
20[multi round-trip requests](/specification/2026-07-28/basic/patterns/mrtr)) are not cacheable
20[multi round-trip requests](/specification/2026-07-28/basic/patterns/mrtr.md)) are not cacheable
2121and carry no caching hints.
2222
2323## Cache Key
from line 28
2828a request whose method or parameters differ from the request that produced it.
2929
3030Results produced by retrying a request through the
31[multi round-trip requests](/specification/2026-07-28/basic/patterns/mrtr) mechanism—that
31[multi round-trip requests](/specification/2026-07-28/basic/patterns/mrtr.md) mechanism—that
3232is, requests carrying `inputResponses` or `requestState`—**MUST NOT** be cached,
3333as they depend on inputs that are not part of the cache key.
3434
from line 142
142142
143143## Interaction with Pagination
144144
145When a list result is [paginated](/specification/2026-07-28/server/utilities/pagination), each
145When a list result is [paginated](/specification/2026-07-28/server/utilities/pagination.md), each
146146page is an independently cacheable response—consistent with how HTTP
147147`Cache-Control` treats paginated resources.
148148
specification/draft/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/draft/basic/authorization/authorization-server-discovery)
52resource server or a separate entity. [Authorization Server Discovery](/specification/draft/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/draft/basic/authorization/client-registration#client-id-metadata-documents)
602. Authorization servers and MCP clients **SHOULD** support [OAuth Client ID Metadata Documents](/specification/draft/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/draft/basic/authorization/client-registration#dynamic-client-registration)
65 [Dynamic Client Registration](/specification/draft/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/draft/basic/authorization/authorization-server-discovery).
69 MCP clients **MUST** use OAuth 2.0 Protected Resource Metadata for [authorization server discovery](/specification/draft/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/draft/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/draft/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/draft/basic/authorization/authorization-server-discovery).
84[Authorization Server Discovery](/specification/draft/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/draft/basic/authorization/client-registration).
91[Client Registration](/specification/draft/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/draft/tutorials/security/security_best_practices#scope-minimization)),
128for basic functionality (see [Scope Minimization](/docs/draft/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/draft/basic/authorization/client-registration).
135[Client Registration](/specification/draft/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/draft/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/draft/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/draft/basic/authorization/security-considerations),
406requirements in [Security Considerations](/specification/draft/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/draft/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/draft/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/draft/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/draft/tutorials/security/security_best_practices#token-passthrough)
17The [Security Best Practices document](/docs/draft/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/draft/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/draft/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/draft/basic/authorization/client-registration#client-id-metadata-documents), authorization servers **MUST** consider the security implications
79When implementing [Client ID Metadata Documents](/specification/draft/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/draft/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/draft/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/draft/basic/authorization/client-registration#dynamic-client-registration)
108[dynamically registered client](/specification/draft/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/draft/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/draft/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/draft/basic/index Changed · +19 / -19 lines
from line 26
2626
2727### Requests
2828
29[Requests](/specification/draft/schema#jsonrpcrequest) are sent from the client to the server, to initiate an operation.
29[Requests](/specification/draft/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/draft/schema#jsonrpcresultresponse) are sent when the operation completes successfully.
53[Result responses](/specification/draft/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/draft/schema#jsonrpcerrorresponse) are sent when the operation fails or encounters an error.
85[Error responses](/specification/draft/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/draft/schema). Implementations
120 recorded in the [schema](/specification/draft/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/draft/schema#jsonrpcnotification) are sent from the client to the server or vice versa, as a one-way message.
155[Notifications](/specification/draft/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/draft/basic/patterns) that define how clients and servers interact:
172The Model Context Protocol (MCP) supports several [Message Patterns](/specification/draft/basic/patterns.md) that define how clients and servers interact:
173173
1741. **[Request and Response](/specification/draft/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/draft/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/draft/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/draft/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/draft/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/draft/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/draft/learn/architecture#example).
215> [Architecture guide](/docs/draft/learn/architecture.md#example).
216216
217217## Auth
218218
219MCP provides an [Authorization](/specification/draft/basic/authorization) framework for use with HTTP.
219MCP provides an [Authorization](/specification/draft/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/draft/basic/patterns/progress) |
348| `progressToken` | Opts the request into progress notifications | [Progress](/specification/draft/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/draft/server/utilities/logging) |
353| `io.modelcontextprotocol/subscriptionId` | Correlates a notification with its originating subscription | [Subscriptions](/specification/draft/basic/patterns/subscriptions) |
352| `io.modelcontextprotocol/logLevel` | Minimum log level the server should emit for a request | [Logging](/specification/draft/server/utilities/logging.md) |
353| `io.modelcontextprotocol/subscriptionId` | Correlates a notification with its originating subscription | [Subscriptions](/specification/draft/basic/patterns/subscriptions.md) |
354354| `traceparent`, `tracestate`, `baggage` | OpenTelemetry trace context propagation | OpenTelemetry trace context (below) |
355355
356Official [extensions](/specification/draft/basic/versioning#extension-negotiation)
356Official [extensions](/specification/draft/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/draft/basic/versioning
412[lifecycle]: /specification/draft/basic/versioning.md
413413
414[subscriptions-listen]: /specification/draft/basic/patterns/subscriptions
414[subscriptions-listen]: /specification/draft/basic/patterns/subscriptions.md
415415
416416**OpenTelemetry trace context:**
417417
specification/draft/basic/patterns/index Changed · +3 / -3 lines
from line 2
22
33This page defines the message patterns of the core protocol: the ways a
44client and server compose JSON-RPC
5[requests, responses, and notifications](/specification/draft/basic/index#messages)
5[requests, responses, and notifications](/specification/draft/basic/index.md#messages)
66into interactions. Every
7[transport](/specification/draft/basic/transports) carries all of these
7[transport](/specification/draft/basic/transports.md) carries all of these
88patterns; transports differ only in how messages are framed and delivered.
99
1010Every interaction begins with the client:
from line 40
4040complete a request, it answers with an
4141[`InputRequiredResult`](/specification/draft/basic/patterns/mrtr#inputrequiredresult)
4242and the client retries the request with the matching `inputResponses`. See
43[Multi Round-Trip Requests](/specification/draft/basic/patterns/mrtr).
43[Multi Round-Trip Requests](/specification/draft/basic/patterns/mrtr.md).
4444
4545```mermaid theme={null}
4646sequenceDiagram
specification/draft/basic/transports/index Changed · +9 / -9 lines
from line 7
77**binding**: it defines how messages are framed and delivered, how request
88metadata is carried, and how cancellation and termination are signaled. It
99does not define what the messages mean: the
10[message patterns](/specification/draft/basic/patterns) are part of the core
10[message patterns](/specification/draft/basic/patterns.md) are part of the core
1111protocol and are the same on every binding. The binding pages specify the
1212standard transports:
1313
141. [stdio](/specification/draft/basic/transports/stdio): newline-delimited
141. [stdio](/specification/draft/basic/transports/stdio.md): newline-delimited
1515 messages over the standard streams of a client-launched subprocess.
162. [Streamable HTTP](/specification/draft/basic/transports/streamable-http):
162. [Streamable HTTP](/specification/draft/basic/transports/streamable-http.md):
1717 each message is an HTTP POST to a single MCP endpoint; replies arrive as
1818 a JSON object or a request-scoped SSE stream.
1919
from line 28
2828A binding **MUST** deliver client-sent *requests* and *notifications* to the
2929server, and server-sent *responses* and *notifications* to the client. No
3030other message direction exists: per the
31[message patterns](/specification/draft/basic/patterns), servers do not
31[message patterns](/specification/draft/basic/patterns.md), servers do not
3232initiate JSON-RPC requests and clients do not send JSON-RPC responses.
3333
3434## Request Metadata
from line 40
4040
4141A binding **MAY** additionally mirror selected body fields into envelope
4242metadata. The Streamable HTTP transport mirrors them into
43[HTTP headers](/specification/draft/basic/transports/streamable-http#request-metadata)
43[HTTP headers](/specification/draft/basic/transports/streamable-http.md#request-metadata)
4444so that intermediaries can route and inspect requests without parsing the
4545body. The body remains the source of truth; bindings that mirror metadata
4646define how mismatches are rejected.
from line 51
5151the client sends a `notifications/cancelled` notification; on Streamable
5252HTTP it closes the request's response stream. The protocol-level rules are
5353the same everywhere; see
54[Cancellation](/specification/draft/basic/patterns/cancellation).
54[Cancellation](/specification/draft/basic/patterns/cancellation.md).
5555
5656## Custom Transports
5757
from line 62
6262
6363Implementers who choose to support custom transports **MUST** preserve the
6464JSON-RPC message format, the
65[message patterns](/specification/draft/basic/patterns), and the per-request
65[message patterns](/specification/draft/basic/patterns.md), and the per-request
6666metadata model. Custom transports **SHOULD** document their connection
6767establishment, message framing, and cancellation patterns to aid
6868interoperability.
from line 69
6969
7070Custom transports that run over a reliable bidirectional byte stream (e.g.,
7171Unix domain sockets or TCP) **SHOULD** reuse the
72[stdio framing](/specification/draft/basic/transports/stdio) rather than
72[stdio framing](/specification/draft/basic/transports/stdio.md) rather than
7373defining a new one: the stdio binding is just newline-delimited JSON-RPC
7474over a byte stream, and only its process-lifecycle rules are specific to
7575standard streams.
from line 80
8080`initialize` handshake and allowed servers to initiate JSON-RPC requests.
8181Clients and servers that interoperate with those revisions detect the
8282counterpart's era and fall back as described in
83[Versioning: Backward Compatibility](/specification/draft/basic/versioning#backward-compatibility-with-initialization-based-versions),
83[Versioning: Backward Compatibility](/specification/draft/basic/versioning.md#backward-compatibility-with-initialization-based-versions),
8484which includes a compatibility matrix for implementors. Each binding page
8585describes its transport-specific detection mechanics.
8686
specification/draft/basic/transports/stdio Changed · +10 / -10 lines
from line 21
2121newline-delimited JSON-RPC message per line over a reliable bidirectional
2222byte stream) works unchanged over Unix domain sockets, TCP connections, or
2323any similar channel.
24[Custom transports](/specification/draft/basic/transports#custom-transports)
24[Custom transports](/specification/draft/basic/transports.md#custom-transports)
2525built on such streams **SHOULD** reuse this framing and the message rules on
2626this page; only the subprocess-specific aspects (launch, `stderr`, shutdown
2727by closing the stream, process restart) need channel-specific equivalents.
from line 53
5353[`InputRequiredResult`][mrtr-input-required] replies; see
5454[Multi Round-Trip Requests][mrtr].
5555
56[mrtr]: /specification/draft/basic/patterns/mrtr
56[mrtr]: /specification/draft/basic/patterns/mrtr.md
5757
58[mrtr-input-required]: /specification/draft/basic/patterns/mrtr#inputrequiredresult
58[mrtr-input-required]: /specification/draft/basic/patterns/mrtr.md#inputrequiredresult
5959
60[subscriptions-listen]: /specification/draft/basic/patterns/subscriptions
60[subscriptions-listen]: /specification/draft/basic/patterns/subscriptions.md
6161
62[subscriptions-listen-request]: /specification/draft/schema#subscriptionslistenrequest
62[subscriptions-listen-request]: /specification/draft/schema.md#subscriptionslistenrequest
6363
6464## Request Metadata
6565
from line 70
7070the method name and arguments live where JSON-RPC puts them. There is no
7171header layer.
7272
73[meta-fields]: /specification/draft/basic/index#meta
73[meta-fields]: /specification/draft/basic/index.md#meta
7474
7575## Cancellation
7676
from line 81
8181practical and **MUST NOT** send any further messages for it. See
8282[Cancellation][cancellation] for the full rules.
8383
84[cancellation]: /specification/draft/basic/patterns/cancellation
84[cancellation]: /specification/draft/basic/patterns/cancellation.md
8585
8686## Shutdown
8787
from line 150
150150See [Versioning: Backward Compatibility][lifecycle-compat] for the era model
151151and a compatibility matrix for implementors.
152152
153[server-discover]: /specification/draft/schema#discoverrequest
153[server-discover]: /specification/draft/schema.md#discoverrequest
154154
155[unsupported-version]: /specification/draft/schema#unsupportedprotocolversionerror
155[unsupported-version]: /specification/draft/schema.md#unsupportedprotocolversionerror
156156
157[lifecycle-compat]: /specification/draft/basic/versioning#backward-compatibility-with-initialization-based-versions
157[lifecycle-compat]: /specification/draft/basic/versioning.md#backward-compatibility-with-initialization-based-versions
158158
specification/draft/basic/transports/streamable-http Changed · +25 / -25 lines
from line 13
1313> * Removal of the GET stream endpoint.
1414> * Removal of protocol-level sessions.
1515>
16> See the [changelog](/specification/draft/changelog) and
16> See the [changelog](/specification/draft/changelog.md) and
1717> [Backward Compatibility](#backward-compatibility) below.
1818
1919In the **Streamable HTTP** transport, the server operates as an independent
from line 40
4040as the **MCP endpoint**) that supports POST. For example, this could be a URL
4141like `https://example.com/mcp`.
4242
43[http-sse]: /specification/2024-11-05/basic/transports#http-with-sse
43[http-sse]: /specification/2024-11-05/basic/transports.md#http-with-sse
4444
4545[sse]: https://en.wikipedia.org/wiki/Server-sent_events
4646
from line 88
8888> This revision of the core protocol defines no client-to-server
8989> *notifications* over Streamable HTTP. The only client-sent notification in
9090> the core protocol, `notifications/cancelled`, is used only on the
91> [stdio](/specification/draft/basic/transports/stdio) transport; on
91> [stdio](/specification/draft/basic/transports/stdio.md) transport; on
9292> Streamable HTTP, closing the SSE response stream is itself the cancellation
9393> signal and no `notifications/cancelled` message is expected (see
9494> \[Cancellation]\[cancellation]). The notification rules above describe the
from line 145
145145
146146Resumable SSE streams via `Last-Event-ID` are not supported.
147147
148[notifications-progress]: /specification/draft/basic/patterns/progress
148[notifications-progress]: /specification/draft/basic/patterns/progress.md
149149
150[notifications-message]: /specification/draft/server/utilities/logging
150[notifications-message]: /specification/draft/server/utilities/logging.md
151151
152[input-required-result]: /specification/draft/schema#inputrequiredresult
152[input-required-result]: /specification/draft/schema.md#inputrequiredresult
153153
154[mrtr]: /specification/draft/basic/patterns/mrtr
154[mrtr]: /specification/draft/basic/patterns/mrtr.md
155155
156[sep-2322]: /seps/2322-MRTR
156[sep-2322]: /seps/2322-MRTR.md
157157
158[subscriptions-listen]: /specification/draft/basic/patterns/subscriptions
158[subscriptions-listen]: /specification/draft/basic/patterns/subscriptions.md
159159
160160## Message Flow
161161
from line 233
233233any further messages for it. See
234234[Cancellation][cancellation] for the full rules.
235235
236[cancellation]: /specification/draft/basic/patterns/cancellation
236[cancellation]: /specification/draft/basic/patterns/cancellation.md
237237
238238## Request Metadata
239239
from line 274
274274server that does not support such clients **MUST** reject a request without
275275the header per [Server Validation](#server-validation).
276276
277[unsupported-version]: /specification/draft/schema#unsupportedprotocolversionerror
277[unsupported-version]: /specification/draft/schema.md#unsupportedprotocolversionerror
278278
279[lifecycle-version]: /specification/draft/basic/versioning#protocol-version-negotiation
279[lifecycle-version]: /specification/draft/basic/versioning.md#protocol-version-negotiation
280280
281281### Standard Request Headers
282282
from line 361
361361`x-mcp-header` annotations, conforming clients **MUST** mirror the
362362designated parameter values into HTTP headers.
363363
364[tool-definitions]: /specification/draft/server/tools#x-mcp-header
364[tool-definitions]: /specification/draft/server/tools.md#x-mcp-header
365365
366366#### Schema Extension
367367
from line 598
598598
599599This error code is allocated from the sub-range the MCP specification
600600reserves for protocol-defined errors. See
601[Error Codes](/specification/draft/basic/index#error-codes).
601[Error Codes](/specification/draft/basic/index.md#error-codes).
602602
603603**Example error response:**
604604
from line 679
679679Servers and clients that need to interoperate with counterparts speaking
680680those protocol versions implement the behavior described in the corresponding
681681revision (for example,
682[2025-11-25: Streamable HTTP](/specification/2025-11-25/basic/transports#streamable-http)),
682[2025-11-25: Streamable HTTP](/specification/2025-11-25/basic/transports.md#streamable-http)),
683683in addition to the version-negotiation fallback described above.
684684
685685### HTTP+SSE Transport (2024-11-05)
from line 689
689689> **Deprecated**: The \[HTTP+SSE transport]\[http-sse] from protocol version
690690> 2024-11-05 has been deprecated since protocol version `2025-03-26` and is
691691> classified as Deprecated under the [feature lifecycle
692> policy](/community/feature-lifecycle#deprecating-a-feature)
692> policy](/community/feature-lifecycle.md#deprecating-a-feature)
693693> ([SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596)).
694694> New implementations **SHOULD NOT** adopt it; existing implementations
695695> **SHOULD** migrate to [Streamable
696> HTTP](/specification/draft/basic/transports/streamable-http). It is eligible
696> HTTP](/specification/draft/basic/transports/streamable-http.md). It is eligible
697697> for removal in a future revision; see the [deprecated features
698> registry](/specification/draft/deprecated).
698> registry](/specification/draft/deprecated.md).
699699
700700Clients and servers can maintain backward compatibility with the
701701deprecated [HTTP+SSE transport][http-sse] (from
from line 726
726726 server running the old HTTP+SSE transport, and should use that
727727 transport for all subsequent communication.
728728
729[lifecycle-compat]: /specification/draft/basic/versioning#backward-compatibility-with-initialization-based-versions
729[lifecycle-compat]: /specification/draft/basic/versioning.md#backward-compatibility-with-initialization-based-versions
730730
specification/draft/basic/versioning Changed · +6 / -6 lines
from line 76
7676## Extension Negotiation
7777
7878Clients and servers can negotiate support for optional
79[extensions](/docs/extensions/overview) beyond the core protocol. Extensions
79[extensions](/docs/extensions/overview.md) beyond the core protocol. Extensions
8080are advertised in the `extensions` field of capabilities, which is a map of
8181extension identifiers to per-extension settings objects. Extension identifiers
8282**MUST** follow the [`_meta` key naming rules](/specification/draft/basic/index#meta),
from line 83
8383with a mandatory prefix.
8484
8585The following is an example of a client that advertises the
86[MCP Apps extension](/extensions/apps/overview) identified as `io.modelcontextprotocol/ui`:
86[MCP Apps extension](/extensions/apps/overview.md) identified as `io.modelcontextprotocol/ui`:
8787
8888```json theme={null}
8989{
from line 98
9898}
9999```
100100
101An example of [Tasks extension](/extensions/tasks/overview) identified as `io.modelcontextprotocol/tasks`:
101An example of [Tasks extension](/extensions/tasks/overview.md) identified as `io.modelcontextprotocol/tasks`:
102102
103103```json theme={null}
104104{
from line 129
129129server's era with transport-specific mechanics, specified in the binding
130130pages:
131131
132* [stdio](/specification/draft/basic/transports/stdio#backward-compatibility):
132* [stdio](/specification/draft/basic/transports/stdio.md#backward-compatibility):
133133 probe with `server/discover` and fall back on any error that is not a
134134 recognized modern error.
135* [Streamable HTTP](/specification/draft/basic/transports/streamable-http#backward-compatibility):
135* [Streamable HTTP](/specification/draft/basic/transports/streamable-http.md#backward-compatibility):
136136 attempt a modern request and inspect the body of a `400 Bad Request`
137137 before falling back.
138138
from line 163
163163| Modern | Legacy | Fails. The server may reject the request with an implementation-defined error, stay silent, or even process an era-ambiguous method under legacy semantics. On stdio, clients **SHOULD** send `server/discover` first to fail deterministically; the client then surfaces an actionable error to the user. |
164164| Dual-era | Modern | Works. The stdio probe returns a `DiscoverResult` (or `UnsupportedProtocolVersionError`); on HTTP, the first modern request succeeds or returns a modern error. The client stays modern. |
165165| Dual-era | Legacy | Works. stdio: the probe returns a non-modern error or times out, and the client falls back to `initialize`. HTTP: the modern request returns a `4xx` without a recognized modern error body, and the client falls back to `initialize` (and possibly further to the deprecated HTTP+SSE transport). |
166| Legacy | Modern | Fails. stdio: the server rejects `initialize` with a JSON-RPC error; the exact code is implementation-defined (`initialize` is an unknown method and the request also lacks the required `_meta` fields). HTTP: the request is missing the required headers and is rejected per [server validation](/specification/draft/basic/transports/streamable-http#server-validation) with `400 Bad Request` (a client on the deprecated HTTP+SSE transport fails at its opening `GET` instead). Legacy clients have no fall-forward mechanism. |
166| Legacy | Modern | Fails. stdio: the server rejects `initialize` with a JSON-RPC error; the exact code is implementation-defined (`initialize` is an unknown method and the request also lacks the required `_meta` fields). HTTP: the request is missing the required headers and is rejected per [server validation](/specification/draft/basic/transports/streamable-http.md#server-validation) with `400 Bad Request` (a client on the deprecated HTTP+SSE transport fails at its opening `GET` instead). Legacy clients have no fall-forward mechanism. |
167167| Legacy | Dual-era | Works. The server answers `initialize` and serves the client according to the negotiated legacy revision. |
168168| Legacy | Legacy | Works according to the legacy revision; out of scope for this document. |
169169
specification/draft/client/elicitation Changed · +12 / -12 lines
from line 333
333333>
334334> **Important**: URL mode elicitation is *not* for authorizing the MCP client's
335335> access to the MCP server (that's handled by [MCP
336> authorization](../basic/authorization)). Instead, it's used when the MCP
336> authorization](/specification/draft/basic/authorization.md)). Instead, it's used when the MCP
337337> server needs to obtain sensitive information or third-party authorization on
338338> behalf of the user. The MCP client's bearer token remains unchanged. The
339339> client's only responsibility is to provide the user with context about the
from line 462
462462
463463### Statefulness
464464
465Elicitations do not require that the server maintain state about users with the [multi round-trip requests](/specification/draft/basic/patterns/mrtr#multi-round-trip-requests) mechanism.
465Elicitations do not require that the server maintain state about users with the [multi round-trip requests](/specification/draft/basic/patterns/mrtr.md#multi-round-trip-requests) mechanism.
466466
467However, if state is stored, servers implementing elicitation **MUST** securely associate this state with individual users following the guidelines in the [security best practices](/docs/draft/tutorials/security/security_best_practices) document. Specifically:
467However, if state is stored, servers implementing elicitation **MUST** securely associate this state with individual users following the guidelines in the [security best practices](/docs/draft/tutorials/security/security_best_practices.md) document. Specifically:
468468
469469* State storage **MUST** be protected against unauthorized access
470* For remote MCP servers, user identification **MUST** be derived from credentials acquired via [MCP authorization](../basic/authorization) when possible (e.g. `sub` claim)
470* For remote MCP servers, user identification **MUST** be derived from credentials acquired via [MCP authorization](/specification/draft/basic/authorization.md) when possible (e.g. `sub` claim)
471471
472472> [!NOTE]
473473>
from line 492
492492### URL Mode Elicitation for OAuth Flows
493493
494494URL mode elicitation enables a pattern where MCP servers act as OAuth clients to third-party resource servers.
495Authorization 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.
495Authorization with external APIs enabled by URL mode elicitation is separate from [MCP authorization](/specification/draft/basic/authorization.md). MCP servers **MUST NOT** rely on URL mode elicitation to authorize users for themselves.
496496
497497#### Understanding the Distinction
498498
499* **MCP Authorization**: Required OAuth flow between the MCP client and MCP server (covered in the [authorization specification](../basic/authorization))
499* **MCP Authorization**: Required OAuth flow between the MCP client and MCP server (covered in the [authorization specification](/specification/draft/basic/authorization.md))
500500* **External (third-party) Authorization**: Optional authorization between the MCP server and a third-party resource server, initiated via URL mode elicitation
501501
502502In external authorization, the server acts as both:
from line 513
513513The critical security requirements are:
514514
5155151. **The third-party credentials MUST NOT transit through the MCP client**: The client must never see third-party credentials to protect the security boundary
5162. **The MCP server MUST NOT use the client's credentials for the third-party service**: That would be [token passthrough](/docs/draft/tutorials/security/security_best_practices#token-passthrough), which is forbidden
5162. **The MCP server MUST NOT use the client's credentials for the third-party service**: That would be [token passthrough](/docs/draft/tutorials/security/security_best_practices.md#token-passthrough), which is forbidden
5175173. **The user MUST authorize the MCP server directly**: The interaction happens outside the MCP protocol, without involving the MCP client
5185184. **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).
519519
from line 522
522522> [!NOTE]
523523>
524524> For additional background, refer to the [token passthrough
525> section](/docs/draft/tutorials/security/security_best_practices#token-passthrough)
525> section](/docs/draft/tutorials/security/security_best_practices.md#token-passthrough)
526526> of the Security Best Practices document to understand why MCP servers cannot
527527> act as pass-through proxies.
528528
from line 617
617617### Identifying the User
618618
619619Servers **MUST NOT** rely on client-provided user identification without server verification, as this can be forged.
620Instead, servers **SHOULD** follow [security best practices](/docs/draft/tutorials/security/security_best_practices).
620Instead, servers **SHOULD** follow [security best practices](/docs/draft/tutorials/security/security_best_practices.md).
621621
622622Non-normative examples:
623623
624624* Incorrect: Treat user input like "I am [[email protected]](mailto:[email protected])" as authoritative
625* Correct: Rely on [authorization](../basic/authorization) to identify the user
625* Correct: Rely on [authorization](/specification/draft/basic/authorization.md) to identify the user
626626
627627### Form Mode Security
628628
from line 634
634634
635635URL 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.
636636
637Typically 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.
637Typically identity verification is done by leveraging the [MCP authorization server](/specification/draft/basic/authorization.md) to identify the user, through a session cookie or equivalent in the browser.
638638
639639For 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:
640640