One read of Model Context Protocolmcp-20260814T095811Z
144 pages moved out of 144 read.
Pages moved
144
significant first
Pages read
144
in this capture
Captured
09:58 UTC
Corpus hash
ce1a231d9896
full baseline · corpus-hash
What this read moved
126-144 of 144, page 6 of 6This capture is too large to show at once. Changes 126-144 of 144 are below, significant first; the rest are on the following screens.
specification/2026-07-28/basic/transports/stdio First recorded · 159 lines, first recorded
# stdio ## Sending Messages ## Receiving Messages ## Request Metadata ## Cancellation ## Shutdown ## Unexpected Termination ## Backward Compatibility
The first capture of this source. The page was already there, and this is what it said.
# stdio <div id="enable-section-numbers" /> In the **stdio** transport, the client launches the MCP server as a subprocess. The two ends communicate over the subprocess's standard streams: * The server reads JSON-RPC messages from `stdin` and writes JSON-RPC messages to `stdout`. * Each message is a single JSON-RPC request, notification, or response. * Messages are delimited by newlines, and **MUST NOT** contain embedded newlines. * The server **MAY** write UTF-8 strings to `stderr` for any logging purposes including informational, debug, and error messages. * The client **MAY** capture, forward, or ignore the server's `stderr` output and **SHOULD NOT** assume `stderr` output indicates error conditions. * The server **MUST NOT** write anything to its `stdout` that is not a valid MCP message. * The client **MUST NOT** write anything to the server's `stdin` that is not a valid MCP message. Standard streams are the canonical channel, but nothing in this binding depends on them except the process lifecycle. The wire format (one newline-delimited JSON-RPC message per line over a reliable bidirectional byte stream) works unchanged over Unix domain sockets, TCP connections, or any similar channel. [Custom transports](/specification/2026-07-28/basic/transports#custom-transports) built on such streams **SHOULD** reuse this framing and the message rules on this page; only the subprocess-specific aspects (launch, `stderr`, shutdown by closing the stream, process restart) need channel-specific equivalents. ## Sending Messages The client sends messages by writing JSON-RPC *requests* and *notifications* to the server's `stdin`, one message per line. The client **MUST NOT** write JSON-RPC *responses*. ## Receiving Messages The client reads server messages from `stdout`, one message per line. All messages share this single channel; there are no per-request streams. The server writes three kinds of messages: 1. *Responses* to client requests, correlated by JSON-RPC `id`. 2. *Notifications* that relate to an in-flight request, such as `notifications/progress` and `notifications/message`. 3. *Notifications* delivered for an active [`subscriptions/listen`][subscriptions-listen] request. Clients **MUST** correlate these using the `io.modelcontextprotocol/subscriptionId` field in `_meta`; see [`SubscriptionsListenRequest`][subscriptions-listen-request]. The server **MUST NOT** write JSON-RPC *requests* to `stdout`. Server-to-client interactions are carried in [`InputRequiredResult`][mrtr-input-required] replies; see [Multi Round-Trip Requests][mrtr]. [mrtr]: /specification/2026-07-28/basic/patterns/mrtr [mrtr-input-required]: /specification/2026-07-28/basic/patterns/mrtr#inputrequiredresult [subscriptions-listen]: /specification/2026-07-28/basic/patterns/subscriptions [subscriptions-listen-request]: /specification/2026-07-28/schema#subscriptionslistenrequest ## Request Metadata All request metadata for the stdio transport is carried inline in the JSON-RPC message body. The protocol version, per-request capabilities, and optional client identity live in [`_meta.io.modelcontextprotocol/*`][meta-fields]; the method name and arguments live where JSON-RPC puts them. There is no header layer. [meta-fields]: /specification/2026-07-28/basic/index#meta ## Cancellation To cancel an in-flight request, the client **MUST** send a `notifications/cancelled` notification referencing the request's ID. Because stdio is a single shared bidirectional channel, there is no per-request stream to close. Servers **SHOULD** stop work on a cancelled request as soon as practical and **MUST NOT** send any further messages for it. See [Cancellation][cancellation] for the full rules. [cancellation]: /specification/2026-07-28/basic/patterns/cancellation ## Shutdown The client **SHOULD** initiate shutdown by: 1. Closing the input stream to the child process (the server). 2. Waiting for the server to exit. 3. If the server does not exit within a reasonable time, forcibly terminating the process using the mechanism appropriate for the operating system. On POSIX systems, forced termination typically escalates from [`SIGTERM`][sigterm] to `SIGKILL`. On Windows, where POSIX signals are not available, clients can use [`TerminateProcess`][terminateprocess] or [Job Objects][job-objects]. Servers **SHOULD** exit promptly when their standard input is closed or reads return end-of-file. This is the primary graceful-shutdown signal and the only portable one, so honoring it reduces the need for forced termination. The server **MAY** initiate shutdown by closing its output stream to the client and exiting. ## Unexpected Termination If the server process exits unexpectedly, the client **SHOULD** restart it. Because the protocol is stateless, any in-flight requests are simply lost and the client can retry them against the fresh process. Active [`subscriptions/listen`][subscriptions-listen] streams must also be re-established after restart. [sigterm]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/signal.h.html [terminateprocess]: https://learn.microsoft.com/windows/win32/api/processthreadsapi/nf-processthreadsapi-terminateprocess [job-objects]: https://learn.microsoft.com/windows/win32/procthread/job-objects ## Backward Compatibility A client that supports both modern (per-request-metadata) MCP versions and a legacy version that requires an `initialize` handshake **SHOULD** probe with [`server/discover`][server-discover] before sending any other request, setting its preferred modern version in `_meta`. The probe has three possible outcomes: * The server returns a `DiscoverResult`: the server is modern. Select a mutually supported version from `supportedVersions` and continue. * The server returns a recognized modern JSON-RPC error such as [`UnsupportedProtocolVersionError`][unsupported-version]: the server is modern but does not support the requested version. Use one of the versions in its advertised `supported` list. Do **not** fall back to `initialize`. * The server returns any other error, or does not respond within a reasonable timeout: the server is legacy. Fall back to the `initialize` handshake. The fallback **MUST NOT** be keyed to one specific error code: legacy servers respond to unknown pre-`initialize` requests with implementation-defined errors (commonly `-32601` or `-32602`) or not at all. A client that only supports modern versions does not need to probe, but probing is still **RECOMMENDED**: some legacy servers do not validate that a request arrives after `initialize` and would process an era-ambiguous method (such as `tools/call`) under legacy semantics. Probing yields a deterministic failure instead. See [Versioning: Backward Compatibility][lifecycle-compat] for the era model and a compatibility matrix for implementors. [server-discover]: /specification/2026-07-28/schema#discoverrequest [unsupported-version]: /specification/2026-07-28/schema#unsupportedprotocolversionerror [lifecycle-compat]: /specification/2026-07-28/basic/versioning#backward-compatibility-with-initialization-based-versions
specification/2026-07-28/basic/transports/streamable-http First recorded · 730 lines, first recorded
# Streamable HTTP ## Security & Endpoint ## Sending Messages ## Receiving Messages ## Message Flow ## Cancellation ## Request Metadata ### Protocol Version Header ### Standard Request Headers ### Custom Headers from Tool Parameters #### Schema Extension #### Value Encoding #### Client Behavior #### Server Behavior for Custom Headers ### Case Sensitivity ### Server Validation ## Backward Compatibility ### Earlier Streamable HTTP Revisions ### HTTP+SSE Transport (2024-11-05)
The first capture of this source. The page was already there, and this is what it said.
# Streamable HTTP
<div id="enable-section-numbers" />
<Info>
Streamable HTTP was introduced in protocol version 2025-03-26 as a replacement
for the [HTTP+SSE transport][http-sse] from protocol version 2024-11-05.
</Info>
<Info>
Revision 2026-07-28 changed the behavior of Streamable HTTP. Clients must
ensure they handle backwards compatibility correctly. Changes included:
* Removal of the GET stream endpoint.
* Removal of protocol-level sessions.
See the [changelog](/specification/2026-07-28/changelog) and
[Backward Compatibility](#backward-compatibility) below.
</Info>
In the **Streamable HTTP** transport, the server operates as an independent
process that can handle multiple client connections. At a glance:
* The server exposes a single HTTP endpoint (the **MCP endpoint**) that
accepts POST.
* The client sends every JSON-RPC request or notification as its own HTTP
POST.
* The server answers each request with either a single JSON object or a
[Server-Sent Events][sse] (SSE) stream scoped to that request, carrying
request-related notifications followed by the final response.
* Server-to-client interactions (sampling, elicitation, roots) are embedded
in results as input requests per
[Multi Round-Trip Requests (MRTR)][mrtr] ([SEP-2322][sep-2322]).
* Long-lived change notifications (such as list changes and resource updates)
are delivered on the response stream of a
[`subscriptions/listen`][subscriptions-listen] request.
See [Message Flow](#message-flow) for sequence diagrams of these
interactions.
The server **MUST** provide a single HTTP endpoint path (hereafter referred to
as the **MCP endpoint**) that supports POST. For example, this could be a URL
like `https://example.com/mcp`.
[http-sse]: /specification/2024-11-05/basic/transports#http-with-sse
[sse]: https://en.wikipedia.org/wiki/Server-sent_events
## Security & Endpoint
When implementing Streamable HTTP transport:
1. Servers **MUST** validate the `Origin` header on all incoming connections
to prevent DNS rebinding attacks.
* If the `Origin` header is present and invalid, servers **MUST** respond
with HTTP 403 Forbidden. The HTTP response body **MAY** comprise a
JSON-RPC *error response* that has no `id`.
2. When running locally, servers **SHOULD** bind only to localhost
(127.0.0.1) rather than all network interfaces (0.0.0.0).
3. Servers **SHOULD** implement proper authentication for all connections.
Without these protections, attackers could use DNS rebinding to interact with
local MCP servers from remote websites.
## Sending Messages
Every JSON-RPC message sent from the client **MUST** be a new HTTP POST
request to the MCP endpoint.
1. The client **MUST** use HTTP POST to send JSON-RPC messages.
2. The client **MUST** include an `Accept` header listing both
`application/json` and `text/event-stream` as supported content types.
3. The client **MUST** include the [request metadata headers](#request-metadata)
on each POST request.
4. The body of the HTTP POST **MUST** be a single JSON-RPC *request* or
*notification*. The client **MUST NOT** send JSON-RPC *responses*.
5. If the body is a JSON-RPC *notification*:
* If the server accepts it, the server **MUST** return HTTP status code
`202 Accepted` with no body.
* If the server cannot accept it, it **MUST** return an HTTP error status
code (e.g., `400 Bad Request`). The HTTP response body **MAY** comprise
a JSON-RPC *error response* that has no `id`.
6. If the body is a JSON-RPC *request*, the server **MUST** return either
`Content-Type: application/json` (a single JSON object) or
`Content-Type: text/event-stream` (an SSE response stream). The client
**MUST** support both.
<Note>
This revision of the core protocol defines no client-to-server
*notifications* over Streamable HTTP. The only client-sent notification in
the core protocol, `notifications/cancelled`, is used only on the
[stdio](/specification/2026-07-28/basic/transports/stdio) transport; on
Streamable HTTP, closing the SSE response stream is itself the cancellation
signal and no `notifications/cancelled` message is expected (see
[Cancellation][cancellation]). The notification rules above describe the
transport mechanics for a notification POST; header requirements for
notification POSTs are not defined by this revision.
</Note>
## Receiving Messages
When the server returns an SSE response stream
(`Content-Type: text/event-stream`):
* The server **MAY** send JSON-RPC *notifications* — for example,
[`notifications/progress`][notifications-progress]
or [`notifications/message`][notifications-message] —
before the final response. These notifications **MUST** relate to the
originating client request.
* The server **MUST NOT** send independent JSON-RPC *requests* on this stream.
Server-to-client interactions (sampling, elicitation, list-roots) are
embedded as input requests inside an
[`InputRequiredResult`][input-required-result] per
[MRTR][mrtr] ([SEP-2322][sep-2322]), not delivered as separate requests on
this or any other stream. This is a change from Streamable HTTP in protocol
versions `2025-03-26` through `2025-11-25`, where servers could send such
requests on SSE streams.
* The final JSON-RPC *response* **SHOULD** terminate the stream.
Long-lived notification streams are obtained by sending a
[`subscriptions/listen`][subscriptions-listen]
request. The server's response is itself an SSE stream that stays open and
delivers the change notifications the client opted in to (such as
`notifications/tools/list_changed` or `notifications/resources/updated`).
Request-scoped notifications like `notifications/progress` and
`notifications/message` are **not** delivered on the listen stream — they
flow only on the response stream of the request they relate to.
When initiating an SSE stream, servers **SHOULD** include the
`X-Accel-Buffering: no` header in the HTTP response. This instructs reverse
proxies (such as nginx) to disable response buffering, ensuring that SSE
events are delivered to clients immediately rather than being held in a
buffer. Without this header, proxies may accumulate messages before sending
them to the client, introducing unwanted latency and potentially breaking the
real-time nature of SSE communication.
<Note>
For long-lived streams — in particular the
[`subscriptions/listen`][subscriptions-listen] response stream — servers are
encouraged to periodically emit an SSE comment line (a line beginning with a
colon, e.g. `:\r\n`) as a keep-alive. This keeps the connection from being
closed by intermediaries or client idle timeouts during quiet periods when no
notifications are flowing. Per the [SSE specification][sse], any line beginning
with a colon is a comment that carries no event data; clients must ignore such
lines and must not treat them as malformed input.
</Note>
Resumable SSE streams via `Last-Event-ID` are not supported.
[notifications-progress]: /specification/2026-07-28/basic/patterns/progress
[notifications-message]: /specification/2026-07-28/server/utilities/logging
[input-required-result]: /specification/2026-07-28/schema#inputrequiredresult
[mrtr]: /specification/2026-07-28/basic/patterns/mrtr
[sep-2322]: /seps/2322-MRTR
[subscriptions-listen]: /specification/2026-07-28/basic/patterns/subscriptions
## Message Flow
The following diagrams illustrate the message flows on a single MCP endpoint.
**Requests and responses.** Each request is its own POST; the server chooses
per request whether to respond with a single JSON object or an SSE stream:
```mermaid theme={null}
sequenceDiagram
participant Client
participant Server
note over Client,Server: Simple response
Client->>Server: POST tools/call (JSON-RPC request)
Server-->>Client: 200 OK, application/json<br/>JSON-RPC response
note over Client,Server: Streaming response
Client->>Server: POST tools/call (JSON-RPC request)
note over Server: Opens SSE stream<br/>scoped to this request
Server-->>Client: SSE: notifications/progress
Server-->>Client: SSE: notifications/progress
Server-->>Client: SSE: JSON-RPC response
note over Client,Server: Stream closes
note over Client,Server: Notification
Client->>Server: POST (JSON-RPC notification)
Server-->>Client: 202 Accepted
```
**Server-to-client interactions (MRTR).** When the server needs input from
the client — sampling, elicitation, or roots — it does not send its own
JSON-RPC request. It returns an
[`InputRequiredResult`][input-required-result] containing `inputRequests`,
and the client retries the original request with the matching
`inputResponses` (see [Multi Round-Trip Requests][mrtr]):
```mermaid theme={null}
sequenceDiagram
participant Client
participant Server
Client->>Server: POST tools/call (id: 1)
note over Server: Needs user input or<br/>an LLM completion
Server-->>Client: InputRequiredResult<br/>(inputRequests: elicitation/create)
note over Client: Gathers the requested input
Client->>Server: POST tools/call (id: 2)<br/>(original params + inputResponses)
Server-->>Client: Final result
```
**Change notifications.** Clients that want server-initiated change
notifications open a long-lived stream with
[`subscriptions/listen`][subscriptions-listen]; the response stream stays
open and carries only the notification types the client opted in to:
```mermaid theme={null}
sequenceDiagram
participant Client
participant Server
Client->>Server: POST subscriptions/listen<br/>(notification filter)
Server-->>Client: SSE: notifications/subscriptions/acknowledged
note over Client,Server: Stream stays open
Server-->>Client: SSE: notifications/tools/list_changed
Server-->>Client: SSE: notifications/resources/updated
note over Client,Server: Until the client or server closes the stream
```
## Cancellation
Closing the SSE response stream **MUST** be treated by the server as
cancellation of that request. Because each request has its own response
stream, the transport-level disconnect is unambiguous. The server **SHOULD**
stop work on the cancelled request as soon as practical and **MUST NOT** send
any further messages for it. See
[Cancellation][cancellation] for the full rules.
[cancellation]: /specification/2026-07-28/basic/patterns/cancellation
## Request Metadata
The Streamable HTTP transport mirrors selected JSON-RPC body fields into HTTP
headers so that intermediaries (load balancers, gateways, observability
tooling) can route and inspect requests without parsing the body.
### Protocol Version Header
Every POST request to the MCP endpoint **MUST** include an
`MCP-Protocol-Version` header.
For example: `MCP-Protocol-Version: 2026-07-28`
The header value **MUST** match the
`io.modelcontextprotocol/protocolVersion` field carried in the request body's
`_meta`. If the values do not match, the server **MUST** reject the request
with `400 Bad Request` and a `HeaderMismatch` JSON-RPC error
(see [Server Validation](#server-validation)).
If the server does not implement the requested protocol version (whether the
version is unknown to the server, or is a known version the server has chosen
not to support), it **MUST** respond with `400 Bad Request` and an
[`UnsupportedProtocolVersionError`][unsupported-version]
listing its supported versions. See
[Versioning: Protocol Version Negotiation][lifecycle-version]
for the negotiation flow.
If the server does not implement the requested RPC method, it **MUST** respond
with `404 Not Found` and a JSON-RPC error with code `-32601`
(`Method not found`). The JSON-RPC error body distinguishes this case from a
`404` returned by a legacy [HTTP+SSE][http-sse] server that does not host the
modern MCP endpoint (see [Backward Compatibility](#backward-compatibility)).
A server that supports clients implementing protocol versions earlier than
`2025-06-18` (which did not define the `MCP-Protocol-Version` header) **MAY**
treat a request that omits the header as protocol version `2025-03-26`. A
server that does not support such clients **MUST** reject a request without
the header per [Server Validation](#server-validation).
[unsupported-version]: /specification/2026-07-28/schema#unsupportedprotocolversionerror
[lifecycle-version]: /specification/2026-07-28/basic/versioning#protocol-version-negotiation
### Standard Request Headers
| Header Name | Source Field | Required For |
| ------------ | ----------------------------- | ------------------------------------------------------ |
| `Mcp-Method` | `method` | All requests |
| `Mcp-Name` | `params.name` or `params.uri` | `tools/call`, `resources/read`, `prompts/get` requests |
These headers are **REQUIRED** for compliance.
If the `Mcp-Name` source value cannot be safely represented as a plain ASCII
header value, clients **MUST** encode it using the Base64 sentinel format
described in [Value Encoding](#value-encoding).
**`tools/call` request:**
```http theme={null}
POST /mcp HTTP/1.1
Content-Type: application/json
Cut at 300 lines. The page has the rest.
specification/2026-07-28/basic/versioning First recorded · 181 lines, first recorded
# Versioning and Compatibility ## Terminology ## Protocol Version Negotiation ## Extension Negotiation ## Backward Compatibility with Initialization-Based Versions ### Compatibility Matrix
The first capture of this source. The page was already there, and this is what it said.
# Versioning and Compatibility
<div id="enable-section-numbers" />
This page defines how a client and server agree on what they are speaking:
the protocol version, declared on every request; optional extensions,
negotiated through capabilities; and interoperability with earlier,
handshake-based protocol revisions.
There is no negotiation handshake. Every request carries its protocol
version, and the server accepts or rejects each request independently:
```mermaid theme={null}
sequenceDiagram
participant Client
participant Server
Client->>Server: request (with `_meta`)
alt server supports requested version
Server-->>Client: result
else version unsupported
Server-->>Client: UnsupportedProtocolVersionError
Note over Client,Server: Client retries with a mutually supported version
end
```
## Terminology
This page uses the following terms for interoperability across protocol
revisions:
* **Modern**: protocol versions that convey version, identity, and
capabilities as per-request metadata (revision `2026-07-28` and later).
* **Legacy**: protocol versions that establish a session with an
`initialize` handshake (`2025-11-25` and earlier).
* **Dual-era**: an implementation that supports both modern and legacy
versions.
## Protocol Version Negotiation
Every request declares the protocol version it is using in its
[`_meta`](/specification/2026-07-28/basic/index#meta) field. On HTTP, this is
also carried in the
[`MCP-Protocol-Version` header](/specification/2026-07-28/basic/transports/streamable-http#protocol-version-header).
If the server does not implement the requested version (whether the version
is unknown to the server, or is a known version the server has chosen not to
support), it **MUST** respond with an
[`UnsupportedProtocolVersionError`](/specification/2026-07-28/schema#unsupportedprotocolversionerror)
listing the versions it does support:
```json theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32022,
"message": "Unsupported protocol version",
"data": {
"supported": ["2026-07-28", "2025-11-25"],
"requested": "1900-01-01"
}
}
}
```
The client **SHOULD** select a mutually supported version from the `supported`
list and retry the request, or surface an error to the user if no compatible
version exists.
Servers **MUST** implement
[`server/discover`](/specification/2026-07-28/server/discover). Clients
**MAY** call it before sending any other requests to learn the server's
supported versions up front, but are not required to: a client is free to
invoke any RPC inline and handle `UnsupportedProtocolVersionError` if its
preferred version is not supported.
## Extension Negotiation
Clients and servers can negotiate support for optional
[extensions](/docs/extensions/overview) beyond the core protocol. Extensions
are advertised in the `extensions` field of capabilities, which is a map of
extension identifiers to per-extension settings objects. Extension identifiers
**MUST** follow the [`_meta` key naming rules](/specification/2026-07-28/basic/index#meta),
with a mandatory prefix.
The following is an example of a client that advertises the
[MCP Apps extension](/extensions/apps/overview) identified as `io.modelcontextprotocol/ui`:
```json theme={null}
{
"capabilities": {
"roots": {},
"extensions": {
"io.modelcontextprotocol/ui": {
"mimeTypes": ["text/html;profile=mcp-app"]
}
}
}
}
```
An example of [Tasks extension](/extensions/tasks/overview) identified as `io.modelcontextprotocol/tasks`:
```json theme={null}
{
"capabilities": {
"tools": {},
"extensions": {
"io.modelcontextprotocol/tasks": {}
}
}
}
```
Each extension specifies the schema of its settings object; an empty object
indicates support with no additional settings.
If one party supports an extension but the other does not, the supporting
party **MUST** either revert to core protocol behavior or reject the request
with an appropriate error. Extensions **SHOULD** document their expected
fallback behavior.
## Backward Compatibility with Initialization-Based Versions
A server that wishes to support both [legacy](#terminology) clients (which
expect an `initialize` handshake) and [modern](#terminology) clients (which
use per-request metadata) **MAY** implement both behaviors.
A client that needs to interoperate with both kinds of servers detects the
server's era with transport-specific mechanics, specified in the binding
pages:
* [stdio](/specification/2026-07-28/basic/transports/stdio#backward-compatibility):
probe with `server/discover` and fall back on any error that is not a
recognized modern error.
* [Streamable HTTP](/specification/2026-07-28/basic/transports/streamable-http#backward-compatibility):
attempt a modern request and inspect the body of a `400 Bad Request`
before falling back.
In both cases, a recognized modern JSON-RPC error (such as
[`UnsupportedProtocolVersionError`](/specification/2026-07-28/schema#unsupportedprotocolversionerror))
identifies a modern server: the client retries with a supported version
rather than falling back. Anything else identifies a legacy server.
The era determination is a property of the server, not of an individual
request. Clients **SHOULD** cache the result for the lifetime of the server
process (stdio) or origin (HTTP), and **MAY** persist it across restarts of
the same server configuration, re-probing if the cached assumption later
fails.
A server that supports only [modern](#terminology) versions **SHOULD** name
the protocol versions it supports in any error it returns to an `initialize`
request, on any transport: legacy clients have no fall-forward mechanism, and
this message may be the only diagnostic they can surface to users.
### Compatibility Matrix
The following matrix summarizes the expected outcome of every combination of
client and server era:
| Client | Server | Outcome |
| -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Modern | Modern | Works. `server/discover` is optional; version mismatches surface as `UnsupportedProtocolVersionError` and the client retries with a mutually supported version. |
| 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. |
| 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. |
| 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). |
| 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. |
| Legacy | Dual-era | Works. The server answers `initialize` and serves the client according to the negotiated legacy revision. |
| Legacy | Legacy | Works according to the legacy revision; out of scope for this document. |
A dual-era **server** selects its behavior from how the client opens:
* A request carrying modern per-request `_meta` is served statelessly
according to this revision.
* An `initialize` request selects legacy semantics, scoped to the stdio
process (stdio) or the session (HTTP), as specified by the negotiated
legacy protocol version.
A dual-era server **MAY** serve both eras concurrently on the same endpoint
or process.
specification/2026-07-28/changelog First recorded · 119 lines, first recorded
# Key Changes ## Major changes ## Minor changes ## Deprecated ## Other schema changes ## Governance and process updates ## Process changes ## Full changelog
The first capture of this source. The page was already there, and this is what it said.
# Key Changes
<div id="enable-section-numbers" />
This document lists changes made to the Model Context Protocol (MCP) specification since
the previous revision, [2025-11-25](/specification/2025-11-25).
## Major changes
1. Remove protocol-level sessions and the `Mcp-Session-Id` header from the Streamable HTTP transport. List endpoints (`tools/list`, `resources/list`, `prompts/list`) no longer vary per-connection. Servers that need cross-call state use explicit, server-minted handles passed as ordinary tool arguments ([SEP-2567](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2567)).
2. Make MCP stateless: remove the `initialize`/`notifications/initialized` handshake. Every request now carries its protocol version and client capabilities in `_meta` (`io.modelcontextprotocol/protocolVersion`, `io.modelcontextprotocol/clientCapabilities`). Clients SHOULD identify themselves on each request (`io.modelcontextprotocol/clientInfo`), and servers SHOULD identify themselves in each result's `_meta` (`io.modelcontextprotocol/serverInfo`). Version mismatches return `UnsupportedProtocolVersionError` ([SEP-2575](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575)).
3. Add `server/discover`: servers MUST implement this RPC to advertise their supported protocol versions, capabilities, and identity. Clients MAY call it before any other request for up-front version selection, or use it as a backward-compatibility probe on STDIO ([SEP-2575](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575)).
4. Replace the HTTP GET endpoint and `resources/subscribe`/`resources/unsubscribe` with `subscriptions/listen`: a single long-lived POST-response stream for opted-in server-to-client change notifications. Clients opt in to specific types (`toolsListChanged`, `promptsListChanged`, `resourcesListChanged`, `resourceSubscriptions`); the server acknowledges and tags notifications with `io.modelcontextprotocol/subscriptionId`. Request-scoped notifications such as `notifications/progress` and `notifications/message` continue to flow on the response stream of the request they relate to, not the `subscriptions/listen` stream ([SEP-2575](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575)).
5. Remove `ping`, `logging/setLevel`, and `notifications/roots/list_changed`. Log level is now set per-request via `io.modelcontextprotocol/logLevel` in `_meta`; servers MUST NOT emit `notifications/message` for requests that did not include this field ([SEP-2575](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2575)).
6. Move experimental tasks out of the core protocol and into an official extension (`io.modelcontextprotocol/tasks`). The redesigned extension replaces the blocking `tasks/result` method with polling via `tasks/get` and a new `tasks/update` for client-to-server input, removes `tasks/list`, and allows servers to return task handles unsolicited without per-request opt-in ([SEP-2663](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2663)).
7. 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)).
8. 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)).
9. 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)).
## Minor changes
1. Add `extensions` field to `ClientCapabilities` and `ServerCapabilities` to support optional [extensions](/docs/extensions/overview) beyond the core protocol.
2. Document OpenTelemetry trace context propagation conventions for `_meta` keys (`traceparent`, `tracestate`, `baggage`) ([SEP-414](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/414)).
3. Servers **SHOULD** return tools from `tools/list` in a deterministic order to enable client-side caching and improve LLM prompt cache hit rates.
4. 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)).
5. Require `ttlMs` and `cacheScope` fields on results returned by `tools/list`, `prompts/list`, `resources/list`, `resources/read`, and `resources/templates/list` via a new `CacheableResult` interface. `ttlMs` is a freshness hint (in milliseconds) allowing clients to cache responses and reduce polling; `cacheScope` (`"public"` or `"private"`) controls whether shared intermediaries may cache the response. Both fields complement existing `listChanged` notifications ([SEP-2549](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2549)).
6. Change resource not found error code from `-32002` to `-32602` (Invalid Params) to align with JSON-RPC specification.
7. Authorization servers **SHOULD** include the `iss` parameter in authorization responses per
[RFC 9207](https://datatracker.ietf.org/doc/html/rfc9207), and MCP clients **MUST** validate a
present `iss` against the recorded issuer before redeeming the authorization code
([SEP-2468](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2468)).
8. Require MCP clients to specify an appropriate `application_type` during Dynamic Client
Registration to avoid OpenID Connect redirect URI conflicts
([SEP-837](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/837)).
9. Clarify that client credentials are bound to the authorization server that issued them:
clients **MUST** key persisted credentials by the issuer identifier, **MUST NOT** reuse them
with a different authorization server, and **MUST** re-register when the authorization server
changes ([SEP-2352](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2352)).
10. Loosen `inputSchema` and `outputSchema` to allow any JSON Schema 2020-12 keywords, and
`structuredContent` to allow any JSON value. Add `$ref` resolution requirements and
composition-keyword resource bounds
([SEP-2106](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2106)).
11. Remove the `notifications/elicitation/complete` notification and the
`elicitationId` field of URL mode elicitation requests, both introduced in
`2025-11-25`. Under the
[Multi Round-Trip Requests](/specification/2026-07-28/basic/patterns/mrtr) pattern, the
client learns the outcome of an out-of-band interaction by retrying the original
request, so a server-initiated completion signal — and the identifier used to
correlate it — no longer fit the protocol. Servers needing to correlate an
elicitation across retries encode their own identifier in `requestState`.
12. Define an [error code allocation policy](/specification/2026-07-28/basic/index#error-codes)
partitioning the JSON-RPC server-error range: `-32000` to `-32019` remains
implementation-defined (existing SDK usage is grandfathered), `-32020` to `-32099` is
reserved for the MCP specification. Renumber the error codes introduced in this draft
accordingly — `HeaderMismatch` `-32001` → `-32020`, `MissingRequiredClientCapability`
`-32003` → `-32021`, `UnsupportedProtocolVersion` `-32004` → `-32022` — and add
`HeaderMismatchError` to the schema, which previously existed only in transport prose.
## Deprecated
Features 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.
1. Deprecate the Roots, Sampling, and Logging features
([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)).
These features remain fully functional during the deprecation window but new
implementations should not add support for them. Suggested migrations: pass
directories or files via tool parameters, resource URIs, or server
configuration instead of Roots; integrate directly with LLM provider APIs
instead of Sampling; log to `stderr` (stdio) or use OpenTelemetry instead of
Logging.
2. Reclassify the HTTP+SSE transport (deprecated since protocol version
`2025-03-26`) as Deprecated under the feature lifecycle policy
([SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596)).
Migrate to [Streamable HTTP](/specification/2026-07-28/basic/transports/streamable-http).
3. Reclassify the `includeContext` values `"thisServer"` and `"allServers"`
(soft-deprecated since protocol version `2025-11-25`) as Deprecated
([SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596)).
Omit the field or use `"none"`; these values will be removed no later than
the Sampling feature itself.
4. Deprecate the OAuth 2.0 Dynamic Client Registration Protocol
([RFC7591](https://datatracker.ietf.org/doc/html/rfc7591)) as a client registration
mechanism in favor of
[Client ID Metadata Documents](/specification/2026-07-28/basic/authorization/client-registration#client-id-metadata-documents)
([PR #2858](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2858)).
It remains available for backwards compatibility with authorization servers that do
not support Client ID Metadata Documents.
## Other schema changes
1. `schema.json` now correctly reflects that the Typescript definition of minimum/maximum/default are `number`'s and not just `integers`. This was caused by running the generator using `--defaultNumberType integer` ([PR#2710](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2710)).
## Governance and process updates
1. Adopt a specification
[feature lifecycle and deprecation policy](/community/feature-lifecycle)
defining the Active, Deprecated, and Removed feature states, a minimum
twelve-month deprecation window, and a
[registry of deprecated features](/specification/2026-07-28/deprecated)
([SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596)).
## Process changes
1. Formalize PR-based SEP workflow with markdown files in `seps/` directory, PR-derived numbering, sponsor responsibilities, and status management via PR labels ([SEP-1850](https://github.com/modelcontextprotocol/specification/pull/1850)).
## Full changelog
For a complete list of all changes that have been made since the last protocol revision,
[see GitHub](https://github.com/modelcontextprotocol/specification/compare/2025-11-25...2026-07-28).
specification/2026-07-28/client/elicitation First recorded · 665 lines, first recorded
# Elicitation ## User Interaction Model ## Capabilities ## Protocol Messages ### Elicitation Requests ### Form Mode Elicitation Requests #### Requested Schema #### Example: Simple Text Request #### Example: Structured Data Request ### URL Mode Elicitation Requests #### Example: Request Sensitive Data ## Message Flow ### Form Mode Flow ### URL Mode Flow ## Response Actions ## Implementation Considerations ### Statefulness ### URL Mode Elicitation for Sensitive Data ### URL Mode Elicitation for OAuth Flows #### Understanding the Distinction #### Implementation Pattern ## Error Handling ## Security Considerations ### Safe URL Handling ### Identifying the User ### Form Mode Security #### Phishing
The first capture of this source. The page was already there, and this is what it said.
# Elicitation
<div id="enable-section-numbers" />
The Model Context Protocol (MCP) provides a standardized way for servers to request additional
information from users through the client during interactions. This flow allows clients to
maintain control over user interactions and data sharing while enabling servers to gather
necessary information dynamically.
Elicitation supports two modes:
* **Form mode**: Servers can request structured data from users with optional JSON schemas to validate responses
* **URL mode**: Servers can direct users to external URLs for sensitive interactions that must *not* pass through the MCP client
## User Interaction Model
Elicitation in MCP allows servers to implement interactive workflows by enabling user input
requests to occur *nested* inside other MCP server features.
Implementations are free to expose elicitation through any interface pattern that suits
their needs—the protocol itself does not mandate any specific user interaction
model.
<Warning>
For trust & safety and security:
* Servers **MUST NOT** use form mode elicitation to request sensitive information such as
passwords, API keys, access tokens, or payment credentials
* Servers **MUST** use [URL mode](#url-mode-elicitation-requests) for interactions involving
such sensitive information
"Sensitive information" in this context refers to secrets and credentials that grant access or
authorize transactions. General contact or profile information (such as a name, email address,
or username) is not categorically prohibited; whether to request such data via form mode is at
the discretion of the server and subject to the user's ability to review and decline.
MCP clients **MUST**:
* Provide UI that makes it clear which server is requesting information
* Respect user privacy and provide clear decline and cancel options
* For form mode, allow users to review and modify their responses before sending
* For URL mode, clearly display the target domain/host and gather user consent before navigation to the target URL
</Warning>
## Capabilities
Clients that support elicitation **MUST** declare the `elicitation` capability in
`_meta.io.modelcontextprotocol/clientCapabilities` on each request:
```json theme={null}
{
"_meta": {
"io.modelcontextprotocol/clientCapabilities": {
"elicitation": {
"form": {},
"url": {}
}
}
}
}
```
For backwards compatibility, an empty capabilities object is equivalent to declaring support for `form` mode only:
```jsonc theme={null}
{
"_meta": {
"io.modelcontextprotocol/clientCapabilities": {
"elicitation": {}, // Equivalent to { "form": {} }
},
},
}
```
Clients declaring the `elicitation` capability **MUST** support at least one mode (`form` or `url`).
Servers **MUST NOT** send elicitation requests with modes that are not supported by the client.
## Protocol Messages
### Elicitation Requests
Servers **MAY** request information from a user during the processing of a client request, by sending an [`InputRequiredResult`](/specification/2026-07-28/basic/patterns/mrtr#inputrequiredresult)
containing an `elicitation/create` request.
All elicitation requests **MUST** include the following parameters:
| Name | Type | Options | Description |
| --------- | ------ | ------------- | -------------------------------------------------------------------------------------- |
| `mode` | string | `form`, `url` | The mode of the elicitation. Optional for form mode (defaults to `"form"` if omitted). |
| `message` | string | | A human-readable message explaining why the interaction is needed. |
The `mode` parameter specifies the type of elicitation:
* `"form"`: In-band structured data collection with optional schema validation. Data is exposed to the client.
* `"url"`: Out-of-band interaction via URL navigation. Data (other than the URL itself) is **not** exposed to the client.
For backwards compatibility, servers **MAY** omit the `mode` field for form mode elicitation requests. Clients **MUST** treat requests without a `mode` field as form mode.
### Form Mode Elicitation Requests
Form mode elicitation allows servers to collect structured data directly through the MCP client.
Form mode elicitation requests **MUST** either specify `mode: "form"` or omit the `mode` field, and include these additional parameters:
| Name | Type | Description |
| ----------------- | ------ | -------------------------------------------------------------- |
| `requestedSchema` | object | A JSON Schema defining the structure of the expected response. |
#### Requested Schema
The `requestedSchema` parameter allows servers to define the structure of the expected
response using a restricted subset of JSON Schema.
To simplify client user experience, form mode elicitation schemas are limited to flat objects
with primitive properties only.
The schema is restricted to these primitive types:
1. **String Schema**
```json theme={null}
{
"type": "string",
"title": "Display Name",
"description": "Description text",
"minLength": 3,
"maxLength": 50,
"format": "email",
"default": "[email protected]"
}
```
Supported formats: `email`, `uri`, `date`, `date-time`
2. **Number Schema**
```json theme={null}
{
"type": "number", // or "integer"
"title": "Display Name",
"description": "Description text",
"minimum": 0,
"maximum": 100,
"default": 50
}
```
3. **Boolean Schema**
```json theme={null}
{
"type": "boolean",
"title": "Display Name",
"description": "Description text",
"default": false
}
```
4. **Enum Schema**
Single-select enum (without titles):
```json theme={null}
{
"type": "string",
"title": "Color Selection",
"description": "Choose your favorite color",
"enum": ["Red", "Green", "Blue"],
"default": "Red"
}
```
Single-select enum (with titles):
```json theme={null}
{
"type": "string",
"title": "Color Selection",
"description": "Choose your favorite color",
"oneOf": [
{ "const": "#FF0000", "title": "Red" },
{ "const": "#00FF00", "title": "Green" },
{ "const": "#0000FF", "title": "Blue" }
],
"default": "#FF0000"
}
```
Multi-select enum (without titles):
```json theme={null}
{
"type": "array",
"title": "Color Selection",
"description": "Choose your favorite colors",
"minItems": 1,
"maxItems": 2,
"items": {
"type": "string",
"enum": ["Red", "Green", "Blue"]
},
"default": ["Red", "Green"]
}
```
Multi-select enum (with titles):
```json theme={null}
{
"type": "array",
"title": "Color Selection",
"description": "Choose your favorite colors",
"minItems": 1,
"maxItems": 2,
"items": {
"anyOf": [
{ "const": "#FF0000", "title": "Red" },
{ "const": "#00FF00", "title": "Green" },
{ "const": "#0000FF", "title": "Blue" }
]
},
"default": ["#FF0000", "#00FF00"]
}
```
Clients can use this schema to:
1. Generate appropriate input forms
2. Validate user input before sending
3. Provide better guidance to users
All primitive types support optional default values to provide sensible starting points. Clients that support defaults SHOULD pre-populate form fields with these values.
Note that complex nested structures, arrays of objects (beyond enums), and other advanced JSON Schema features are intentionally not supported to simplify client user experience.
#### Example: Simple Text Request
**Input request (delivered inside [`InputRequiredResult.inputRequests`](/specification/2026-07-28/basic/patterns/mrtr#inputrequests)):**
```json theme={null}
{
"method": "elicitation/create",
"params": {
"mode": "form",
"message": "Please provide your GitHub username",
"requestedSchema": {
"type": "object",
"properties": {
"name": {
"type": "string"
}
},
"required": ["name"]
}
}
}
```
**Client result (returned inside `inputResponses` on the retried request):**
```json theme={null}
{
"action": "accept",
"content": {
"name": "octocat"
}
}
```
#### Example: Structured Data Request
**Input request (delivered inside `InputRequiredResult.inputRequests`):**
```json theme={null}
{
"method": "elicitation/create",
"params": {
"mode": "form",
"message": "Please provide your contact information",
"requestedSchema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Your full name"
},
"email": {
"type": "string",
"format": "email",
"description": "Your email address"
},
"age": {
"type": "number",
"minimum": 18,
"description": "Your age"
}
},
"required": ["name", "email"]
}
Cut at 300 lines. The page has the rest.
specification/2026-07-28/client/roots First recorded · 157 lines, first recorded
# Roots ## User Interaction Model ## Capabilities ## Protocol Messages ### Listing Roots ## Message Flow ## Data Types ### Root #### Project Directory #### Multiple Repositories ## Error Handling ## Security Considerations ## Implementation Guidelines
The first capture of this source. The page was already there, and this is what it said.
# Roots
<div id="enable-section-numbers" />
<Warning>
**Deprecated**: The Roots feature is deprecated as of protocol version
`2026-07-28`
([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)).
Under the [feature lifecycle policy](/community/feature-lifecycle), it remains
in the specification for at least twelve months after this revision's release
before it becomes eligible for removal. New implementations **SHOULD NOT**
adopt it; existing implementations **SHOULD** migrate to passing directories
or files via tool parameters, resource URIs, or server configuration. See the
[deprecated features registry](/specification/2026-07-28/deprecated).
</Warning>
The Model Context Protocol (MCP) provides a standardized way for clients to expose
filesystem "roots" to servers. Roots inform servers about the directories and files the
client considers relevant, so that servers can focus their operations accordingly. They
are informational guidance rather than an access-control mechanism. The protocol does
not enforce that servers stay within roots. Servers can request the list of roots from
supporting clients.
## User Interaction Model
Roots in MCP are typically exposed through workspace or project configuration interfaces.
For example, implementations could offer a workspace/project picker that allows users to
select directories and files the server should have access to. This can be combined with
automatic workspace detection from version control systems or project files.
However, implementations are free to expose roots through any interface pattern that
suits their needs—the protocol itself does not mandate any specific user
interaction model.
## Capabilities
Clients that support roots **MUST** declare the `roots` capability in
`_meta.io.modelcontextprotocol/clientCapabilities` on each request:
```json theme={null}
{
"_meta": {
"io.modelcontextprotocol/clientCapabilities": {
"roots": {}
}
}
}
```
## Protocol Messages
### Listing Roots
To retrieve roots during the processing of a client request, servers send an `InputRequiredResult`
containing a `roots/list` request:
**Input request (delivered inside [`InputRequiredResult.inputRequests`](/specification/2026-07-28/basic/patterns/mrtr#inputrequests)):**
```json theme={null}
{
"method": "roots/list"
}
```
**Client result (returned inside `inputResponses` on the retried request):**
```json theme={null}
{
"roots": [
{
"uri": "file:///home/user/projects/myproject",
"name": "My Project"
}
]
}
```
## Message Flow
```mermaid theme={null}
sequenceDiagram
participant Server
participant Client
Note over Server,Client: Initial Request
Client->>Server: tools/call(id: 1)
Server-->>Client: InputRequiredResult(roots/list)
Client->>Server: tools/call(id: 2, inputResponses{key: roots} + requestState)
```
## Data Types
### Root
A root definition includes:
* `uri`: Unique identifier for the root. This **MUST** be a `file://` URI in the current
specification.
* `name`: Optional human-readable name for display purposes.
Example roots for different use cases:
#### Project Directory
```json theme={null}
{
"uri": "file:///home/user/projects/myproject",
"name": "My Project"
}
```
#### Multiple Repositories
```json theme={null}
[
{
"uri": "file:///home/user/repos/frontend",
"name": "Frontend Repository"
},
{
"uri": "file:///home/user/repos/backend",
"name": "Backend Repository"
}
]
```
## Error Handling
If an error occurs, the client does not need to replay the initial call with an error message
as the server is not waiting for a response with the `InputRequiredResult` pattern.
## Security Considerations
1. Clients **MUST**:
* Only expose roots with appropriate permissions
* Validate all root URIs to prevent path traversal
* Implement proper access controls
* Monitor root accessibility
2. Servers **SHOULD**:
* Handle cases where roots become unavailable
* Respect root boundaries during operations
* Validate all paths against provided roots
## Implementation Guidelines
1. Clients **SHOULD**:
* Prompt users for consent before exposing roots to servers
* Provide clear user interfaces for root management
* Validate root accessibility before exposing
* Monitor for root changes
2. Servers **SHOULD**:
* Check for roots capability before usage
* Respect root boundaries in operations
* Cache root information appropriately
specification/2026-07-28/client/sampling First recorded · 677 lines, first recorded
# Sampling ## User Interaction Model ## Tools in Sampling ## Capabilities ## Protocol Messages ### Creating Messages ### Sampling with Tools ### Multi-turn Tool Loop ## Message Content Constraints ### Tool Result Messages ### Tool Use and Result Balance ## Cross-API Compatibility ### Message Roles ### Tool Choice Modes ### Parallel Tool Use ## Message Flow ## Data Types ### Messages #### Text Content #### Image Content #### Audio Content ### Model Preferences #### Capability Priorities #### Model Hints ### System Prompt ### Context Inclusion ### Sampling Parameters ### Result Fields ## Error Handling ## Security Considerations
The first capture of this source. The page was already there, and this is what it said.
# Sampling
<div id="enable-section-numbers" />
<Warning>
**Deprecated**: The Sampling feature is deprecated as of protocol version
`2026-07-28`
([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)).
Under the [feature lifecycle policy](/community/feature-lifecycle), it remains
in the specification for at least twelve months after this revision's release
before it becomes eligible for removal. New implementations **SHOULD NOT**
adopt it; existing implementations **SHOULD** migrate to integrating directly
with LLM provider APIs. See the [deprecated features
registry](/specification/2026-07-28/deprecated).
</Warning>
The Model Context Protocol (MCP) provides a standardized way for servers to request LLM
sampling ("completions" or "generations") from language models via clients. This flow
allows clients to maintain control over model access, selection, and permissions while
enabling servers to leverage AI capabilities—with no server API keys necessary.
Servers can request text, audio, or image-based interactions and optionally include
context from MCP servers in their prompts.
## User Interaction Model
Sampling in MCP allows servers to implement agentic behaviors, by enabling LLM calls to
occur *nested* inside other MCP server features.
Implementations are free to expose sampling through any interface pattern that suits
their needs—the protocol itself does not mandate any specific user interaction
model.
<Warning>
For trust & safety and security, there **SHOULD** always
be a human in the loop with the ability to deny sampling requests.
Applications **SHOULD**:
* Provide UI that makes it easy and intuitive to review sampling requests
* Allow users to view and edit prompts before sending
* Present generated responses for review before delivery
</Warning>
## Tools in Sampling
Servers can request that the client's LLM use tools during sampling by providing a `tools` array and optional `toolChoice` configuration in their sampling requests. The tool definitions in the `tools` array are scoped to the sampling request — they don't need to correspond to registered tools. This enables servers to implement agentic behaviors where the LLM can call specially designated tools, receive results, and continue the conversation - all within a single sampling request flow.
Clients **MUST** declare support for tool use via the `sampling.tools` capability to receive tool-enabled sampling requests. Servers **MUST NOT** send tool-enabled sampling requests to Clients that have not declared support for tool use via the `sampling.tools` capability.
## Capabilities
Clients that support sampling **MUST** declare the `sampling` capability in
`_meta.io.modelcontextprotocol/clientCapabilities` on each request:
**Basic sampling:**
```json theme={null}
{
"_meta": {
"io.modelcontextprotocol/clientCapabilities": {
"sampling": {}
}
}
}
```
**With tool use support:**
```json theme={null}
{
"_meta": {
"io.modelcontextprotocol/clientCapabilities": {
"sampling": {
"tools": {}
}
}
}
}
```
**With context inclusion support (deprecated):**
```json theme={null}
{
"_meta": {
"io.modelcontextprotocol/clientCapabilities": {
"sampling": {
"context": {}
}
}
}
}
```
<Note>
The `includeContext` parameter values `"thisServer"` and `"allServers"` are
deprecated under the [feature lifecycle
policy](/community/feature-lifecycle#deprecating-a-feature)
([SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596));
they will be removed no later than the Sampling feature itself. Servers
**SHOULD** avoid using these values (e.g. can just omit `includeContext` since
it defaults to `"none"`), and **SHOULD NOT** use them unless the client
declares `sampling.context` capability. See the [deprecated features
registry](/specification/2026-07-28/deprecated).
</Note>
## Protocol Messages
### Creating Messages
To request a language model generation during the processing of a client request, servers send an `InputRequiredResult` containing a `sampling/createMessage` request:
**Input request (delivered inside [`InputRequiredResult.inputRequests`](/specification/2026-07-28/basic/patterns/mrtr#inputrequests)):**
```json theme={null}
{
"method": "sampling/createMessage",
"params": {
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "What is the capital of France?"
}
}
],
"modelPreferences": {
"hints": [
{
"name": "claude-3-sonnet"
}
],
"costPriority": 0.3,
"intelligencePriority": 0.8,
"speedPriority": 0.5
},
"temperature": 0.1,
"systemPrompt": "You are a helpful assistant.",
"includeContext": "thisServer",
"maxTokens": 100
}
}
```
**Client result (returned inside `inputResponses` on the retried request):**
```json theme={null}
{
"role": "assistant",
"content": {
"type": "text",
"text": "The capital of France is Paris."
},
"model": "claude-3-sonnet-20240307",
"stopReason": "endTurn"
}
```
### Sampling with Tools
The following diagram illustrates the complete flow of sampling with tools, including the multi-turn tool loop:
```mermaid theme={null}
sequenceDiagram
participant Server
participant Client
participant User
participant LLM
Client->>Server: tools/call(id:1)
note right of Server: Server needs more info
Server->>Client: InputRequiredResult(<br/>sampling/createMessage<br/>(messages + tools))
Note over Client,User: Human-in-the-loop review
Client->>User: Present request for approval
User-->>Client: Approve/modify
Client->>LLM: Forward request with tools
LLM-->>Client: Response with tool_use<br/>(stopReason: "toolUse")
Client->>User: Present tool calls for review
User-->>Client: Approve tool calls
Client-->>Server: tools/call(id:2, Return tool_use response)
Note over Server: Execute tool(s)
Server->>Server: Run get_weather("Paris")<br/>Run get_weather("London")
Note over Server,Client: Continue with tool results
Server->>Client: InputRequiredResult(<br/>sampling/createMessage<br/>(history + tool_results + tools))
Client->>User: Present continuation
User-->>Client: Approve
Client->>LLM: Forward with tool results
LLM-->>Client: Final text response<br/>(stopReason: "endTurn")
Client->>User: Present response
User-->>Client: Approve
Client-->>Server: tools/call(id:3, Return final response)
Note over Server: Server processes result<br/>(may continue conversation...)
```
To request LLM generation with tool use capabilities, servers include `tools` and optionally `toolChoice` in the request:
**Input request (Server -> Client, delivered inside `InputRequiredResult.inputRequests`):**
```json theme={null}
{
"method": "sampling/createMessage",
"params": {
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "What's the weather like in Paris and London?"
}
}
],
"tools": [
{
"name": "get_weather",
"description": "Get current weather for a city",
"inputSchema": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "City name"
}
},
"required": ["city"]
}
}
],
"toolChoice": {
"mode": "auto"
},
"maxTokens": 1000
}
}
```
**Client result (Client -> Server, returned inside `inputResponses` on the retried request):**
```json theme={null}
{
"role": "assistant",
"content": [
{
"type": "tool_use",
"id": "call_abc123",
"name": "get_weather",
"input": {
"city": "Paris"
}
},
{
"type": "tool_use",
"id": "call_def456",
"name": "get_weather",
"input": {
"city": "London"
}
}
],
"model": "claude-3-sonnet-20240307",
"stopReason": "toolUse"
}
```
### Multi-turn Tool Loop
After receiving tool use requests from the LLM, the server typically:
1. Executes the requested tool uses.
2. Sends a new sampling request with the tool results appended
3. Receives the LLM's response (which might contain new tool uses)
4. Repeats as many times as needed (server might cap the maximum number of iterations, and e.g. pass `toolChoice: {mode: "none"}` on the last iteration to force a final result)
**Follow-up input request (Server -> Client, delivered inside `InputRequiredResult.inputRequests`) with tool results:**
```json theme={null}
{
"method": "sampling/createMessage",
"params": {
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "What's the weather like in Paris and London?"
}
},
{
"role": "assistant",
"content": [
{
Cut at 300 lines. The page has the rest.
specification/2026-07-28/deprecated First recorded · 39 lines, first recorded
# Deprecated Features ## Deprecated ## Removed
The first capture of this source. The page was already there, and this is what it said.
# Deprecated Features <div id="enable-section-numbers" /> This page is the registry of specification features that are currently in the **Deprecated** state under the [feature lifecycle and deprecation policy](/community/feature-lifecycle) ([SEP-2596](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2596)). A Deprecated feature remains part of the specification but is scheduled for removal: new implementations **SHOULD NOT** adopt it, and existing implementations **SHOULD** migrate before the feature's earliest removal. The earliest removal marks when a feature becomes *eligible* for removal; the actual removal is a Core Maintainer decision taken during release preparation and may happen later. This registry is a derived view kept consistent with the per-feature deprecation notices and changelog entries, which are the normative records. ## Deprecated | Feature | Deprecation SEP | Deprecated in | Migration path | Earliest removal | | ---------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------- | | [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 | | [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 | | [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 | | [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 | | `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)) | | [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 | The HTTP+SSE transport and the `includeContext` values were already described as deprecated before the lifecycle policy existed; SEP-2596 reclassifies them as Deprecated under its [transition provisions](/community/feature-lifecycle). ## Removed No features have been removed under this policy yet. When a Deprecated feature is removed, its row moves to this section with a link to the changelog entry recording the removal.
specification/2026-07-28/index First recorded · 138 lines, first recorded
# Specification ## Overview ## Key Details ### Base Protocol ### Features ### Additional Utilities ### Extensions ## Security and Trust & Safety ### Key Principles ### Implementation Guidelines ## Learn More
The first capture of this source. The page was already there, and this is what it said.
# Specification
<div id="enable-section-numbers" />
[Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open protocol that
enables seamless integration between LLM applications and external data sources and
tools. Whether you're building an AI-powered IDE, enhancing a chat interface, or creating
custom AI workflows, MCP provides a standardized way to connect LLMs with the context
they need.
This specification defines the authoritative protocol requirements, based on the
TypeScript schema in
[schema.ts](https://github.com/modelcontextprotocol/specification/blob/main/schema/2026-07-28/schema.ts).
For implementation guides and examples, visit
[modelcontextprotocol.io](https://modelcontextprotocol.io).
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD
NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14)
\[[RFC2119](https://datatracker.ietf.org/doc/html/rfc2119)]
\[[RFC8174](https://datatracker.ietf.org/doc/html/rfc8174)] when, and only when, they
appear in all capitals, as shown here.
## Overview
MCP provides a standardized way for applications to:
* Share contextual information with language models
* Expose tools and capabilities to AI systems
* Build composable integrations and workflows
The protocol uses [JSON-RPC](https://www.jsonrpc.org/) 2.0 messages to establish
communication between:
* **Hosts**: LLM applications that initiate connections
* **Clients**: Connectors within the host application
* **Servers**: Services that provide context and capabilities
MCP takes some inspiration from the
[Language Server Protocol](https://microsoft.github.io/language-server-protocol/), which
standardizes how to add support for programming languages across a whole ecosystem of
development tools. In a similar way, MCP standardizes how to integrate additional context
and tools into the ecosystem of AI applications.
## Key Details
### Base Protocol
* [JSON-RPC](https://www.jsonrpc.org/) message format
* Stateless, self-contained requests
* Per-request capability negotiation
### Features
Servers offer any of the following features to clients:
* **Resources**: Context and data, for the user or the AI model to use
* **Prompts**: Templated messages and workflows for users
* **Tools**: Functions for the AI model to execute
Clients may offer the following features to servers:
* **Elicitation**: Server-initiated requests for additional information from users
### Additional Utilities
* Configuration
* Progress tracking
* Cancellation
* Error reporting
### Extensions
Beyond the core protocol, MCP defines optional [extensions](/extensions/overview)
that add modular, specialized, or experimental functionality. Extensions
are always opt-in and require explicit support from both client and server, negotiated
during initialization. Notable extensions include:
* **[Tasks](/extensions/tasks/overview)**: Asynchronous execution of long-running
operations, with polling, mid-flight input, and durable handles
* **[Skills over MCP](/community/working-groups/skills-over-mcp)**: Rich, structured
instructions for agent workflows, discovered and consumed through MCP
* **[MCP Apps](/extensions/apps/overview)**: Interactive UI elements (charts, forms,
video players) rendered inline within conversations
## Security and Trust & Safety
The Model Context Protocol enables powerful capabilities through arbitrary data access
and code execution paths. With this power comes important security and trust
considerations that all implementors must carefully address.
### Key Principles
1. **User Consent and Control**
* Users must explicitly consent to and understand all data access and operations
* Users must retain control over what data is shared and what actions are taken
* Implementors should provide clear UIs for reviewing and authorizing activities
2. **Data Privacy**
* Hosts must obtain explicit user consent before exposing user data to servers
* Hosts must not transmit resource data elsewhere without user consent
* User data should be protected with appropriate access controls
3. **Tool Safety**
* Tools represent arbitrary code execution and must be treated with appropriate
caution.
* In particular, descriptions of tool behavior such as annotations should be
considered untrusted, unless obtained from a trusted server.
* Hosts must obtain explicit user consent before invoking any tool
* Users should understand what each tool does before authorizing its use
### Implementation Guidelines
While MCP itself cannot enforce these security principles at the protocol level,
implementors **SHOULD**:
1. Build robust consent and authorization flows into their applications
2. Provide clear documentation of security implications
3. Implement appropriate access controls and data protections
4. Follow security best practices in their integrations
5. Consider privacy implications in their feature designs
## Learn More
Explore the detailed specification for each protocol component:
<CardGroup cols={5}>
<Card title="Architecture" icon="sitemap" href="/specification/2026-07-28/architecture" />
<Card title="Base Protocol" icon="code" href="/specification/2026-07-28/basic" />
<Card title="Server Features" icon="server" href="/specification/2026-07-28/server" />
<Card title="Client Features" icon="user" href="/specification/2026-07-28/client" />
<Card title="Contributing" icon="pencil" href="/community/contributing" />
</CardGroup>
specification/2026-07-28/schema First recorded · 1227 lines, first recorded
# Schema Reference ## JSON-RPC ## Common Types ## Errors ## Content ## `completion/complete` ## `elicitation/create` ## `notifications/cancelled` ## `notifications/message` ## `notifications/progress` ## `notifications/prompts/list_changed` ## `notifications/resources/list_changed` ## `notifications/resources/updated` ## `notifications/subscriptions/acknowledged` ## `notifications/tools/list_changed` ## Multi Round-Trip ## `prompts/get` ## `prompts/list` ## `resources/list` ## `resources/read` ## `resources/templates/list` ## `roots/list` ## `sampling/createMessage` ## `server/discover` ## `subscriptions/listen` ## `tools/call` ## `tools/list`
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
The first capture of this source. The page was already there, and this is what it said.
# Schema Reference
<div id="schema-reference" />
## JSON-RPC
<div class="type">
### `JSONRPCErrorResponse`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">JSONRPCErrorResponse</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#jsonrpcerrorresponse-jsonrpc">jsonrpc</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">"2.0"</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#jsonrpcerrorresponse-id">id</a><span class="tsd-signature-symbol">?:</span> <a href="#requestid" class="tsd-signature-type tsd-kind-type-alias">RequestId</a><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#jsonrpcerrorresponse-error">error</a><span class="tsd-signature-symbol">:</span> <a href="#error" class="tsd-signature-type tsd-kind-interface">Error</a><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>A response to a request that indicates an error occurred.</p> </div> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="jsonrpcerrorresponse-jsonrpc" data-typedoc-h="3"><span>jsonrpc: "2.0"</span><a href="#jsonrpcerrorresponse-jsonrpc" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> </section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="jsonrpcerrorresponse-id" data-typedoc-h="3"><span>id?: RequestId</span><a href="#jsonrpcerrorresponse-id" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> </section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="jsonrpcerrorresponse-error" data-typedoc-h="3"><span>error: Error</span><a href="#jsonrpcerrorresponse-error" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> </section>
</div>
<div class="type">
### `JSONRPCMessage`
<div class="tsd-signature"><span class="tsd-kind-type-alias">JSONRPCMessage</span><span class="tsd-signature-symbol">:</span> <a href="#jsonrpcrequest" class="tsd-signature-type tsd-kind-interface">JSONRPCRequest</a> <span class="tsd-signature-symbol">|</span> <a href="#jsonrpcnotification" class="tsd-signature-type tsd-kind-interface">JSONRPCNotification</a> <span class="tsd-signature-symbol">|</span> <a href="#jsonrpcresponse" class="tsd-signature-type tsd-kind-type-alias">JSONRPCResponse</a></div> <div class="tsd-comment tsd-typography"><p>Refers to any valid JSON-RPC object that can be decoded off the wire, or encoded to be sent.</p> </div>
</div>
<div class="type">
### `JSONRPCNotification`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">JSONRPCNotification</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#jsonrpcnotification-method">method</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#jsonrpcnotification-params">params</a><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-symbol">\{</span> <span class="tsd-signature-symbol">\[</span><span class="tsd-kind-index-signature">key</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">]:</span> <span class="tsd-signature-type">any</span> <span class="tsd-signature-symbol">}</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#jsonrpcnotification-jsonrpc">jsonrpc</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">"2.0"</span><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>A notification which does not expect a response.</p> </div> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="jsonrpcnotification-method" data-typedoc-h="3"><span>method: string</span><a href="#jsonrpcnotification-method" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <aside class="tsd-sources"> <p>Inherited from Notification.method</p></aside></section> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="jsonrpcnotification-params" data-typedoc-h="3"><span>params?: \{ \[key: string]: any }</span><a href="#jsonrpcnotification-params" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <aside class="tsd-sources"> <p>Inherited from Notification.params</p></aside></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="jsonrpcnotification-jsonrpc" data-typedoc-h="3"><span>jsonrpc: "2.0"</span><a href="#jsonrpcnotification-jsonrpc" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> </section>
</div>
<div class="type">
### `JSONRPCRequest`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">JSONRPCRequest</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#jsonrpcrequest-method">method</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#jsonrpcrequest-params">params</a><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-symbol">\{</span> <span class="tsd-signature-symbol">\[</span><span class="tsd-kind-index-signature">key</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">]:</span> <span class="tsd-signature-type">any</span> <span class="tsd-signature-symbol">}</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#jsonrpcrequest-jsonrpc">jsonrpc</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">"2.0"</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#jsonrpcrequest-id">id</a><span class="tsd-signature-symbol">:</span> <a href="#requestid" class="tsd-signature-type tsd-kind-type-alias">RequestId</a><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>A request that expects a response.</p> </div> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="jsonrpcrequest-method" data-typedoc-h="3"><span>method: string</span><a href="#jsonrpcrequest-method" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <aside class="tsd-sources"> <p>Inherited from Request.method</p></aside></section> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="jsonrpcrequest-params" data-typedoc-h="3"><span>params?: \{ \[key: string]: any }</span><a href="#jsonrpcrequest-params" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <aside class="tsd-sources"> <p>Inherited from Request.params</p></aside></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="jsonrpcrequest-jsonrpc" data-typedoc-h="3"><span>jsonrpc: "2.0"</span><a href="#jsonrpcrequest-jsonrpc" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> </section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="jsonrpcrequest-id" data-typedoc-h="3"><span>id: RequestId</span><a href="#jsonrpcrequest-id" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> </section>
</div>
<div class="type">
### `JSONRPCResponse`
<div class="tsd-signature"><span class="tsd-kind-type-alias">JSONRPCResponse</span><span class="tsd-signature-symbol">:</span> <a href="#jsonrpcresultresponse" class="tsd-signature-type tsd-kind-interface">JSONRPCResultResponse</a> <span class="tsd-signature-symbol">|</span> <a href="#jsonrpcerrorresponse" class="tsd-signature-type tsd-kind-interface">JSONRPCErrorResponse</a></div> <div class="tsd-comment tsd-typography"><p>A response to a request, containing either the result or error.</p> </div>
</div>
<div class="type">
### `JSONRPCResultResponse`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">JSONRPCResultResponse</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#jsonrpcresultresponse-jsonrpc">jsonrpc</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">"2.0"</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#jsonrpcresultresponse-id">id</a><span class="tsd-signature-symbol">:</span> <a href="#requestid" class="tsd-signature-type tsd-kind-type-alias">RequestId</a><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#jsonrpcresultresponse-result">result</a><span class="tsd-signature-symbol">:</span> <a href="#result" class="tsd-signature-type tsd-kind-interface">Result</a><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>A successful (non-error) response to a request.</p> </div> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="jsonrpcresultresponse-jsonrpc" data-typedoc-h="3"><span>jsonrpc: "2.0"</span><a href="#jsonrpcresultresponse-jsonrpc" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> </section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="jsonrpcresultresponse-id" data-typedoc-h="3"><span>id: RequestId</span><a href="#jsonrpcresultresponse-id" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> </section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="jsonrpcresultresponse-result" data-typedoc-h="3"><span>result: Result</span><a href="#jsonrpcresultresponse-result" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> </section>
</div>
## Common Types
<div class="type">
### `Annotations`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">Annotations</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#annotations-audience">audience</a><span class="tsd-signature-symbol">?:</span> <a href="#role" class="tsd-signature-type tsd-kind-type-alias">Role</a><span class="tsd-signature-symbol">\[]</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#annotations-priority">priority</a><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">number</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#annotations-lastmodified">lastModified</a><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>Optional annotations for the client. The client can use annotations to inform how objects are used or displayed</p> </div> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="annotations-audience" data-typedoc-h="3"><span>audience?: Role\[]</span><a href="#annotations-audience" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>Describes who the intended audience of this object or data is.</p> <p>It can include multiple entries to indicate content useful for multiple audiences (e.g., <code>\["user", "assistant"]</code>).</p> </div></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="annotations-priority" data-typedoc-h="3"><span>priority?: number</span><a href="#annotations-priority" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>Describes how important this data is for operating the server.</p> <p>A value of 1 means "most important," and indicates that the data is
effectively required, while 0 means "least important," and indicates that
the data is entirely optional.</p> </div></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="annotations-lastmodified" data-typedoc-h="3"><span>lastModified?: string</span><a href="#annotations-lastmodified" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>The moment the resource was last modified, as an ISO 8601 formatted string.</p> <p>Should be an ISO 8601 formatted string (e.g., "2025-01-12T15:00:58Z").</p> <p>Examples: last activity timestamp in an open file, timestamp when the resource
was attached, etc.</p> </div></section>
</div>
<div class="type">
### `Cursor`
<div class="tsd-signature"><span class="tsd-kind-type-alias">Cursor</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span></div> <div class="tsd-comment tsd-typography"><p>An opaque token used to represent a cursor for pagination.</p> </div>
</div>
<div class="type">
### `EmptyResult`
<div class="tsd-signature"><span class="tsd-kind-type-alias">EmptyResult</span><span class="tsd-signature-symbol">:</span> <a href="#result" class="tsd-signature-type tsd-kind-interface">Result</a></div> <div class="tsd-comment tsd-typography"><p>A result that indicates success but carries no data.</p> </div>
</div>
<div class="type">
### `Icon`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">Icon</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#icon-src">src</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#icon-mimetype">mimeType</a><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#icon-sizes">sizes</a><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">\[]</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#icon-theme">theme</a><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">"light"</span> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">"dark"</span><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>An optionally-sized icon that can be displayed in a user interface.</p> </div> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="icon-src" data-typedoc-h="3"><span>src: string</span><a href="#icon-src" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>A standard URI pointing to an icon resource. May be an HTTP/HTTPS URL or a <code>data:</code> URI with Base64-encoded image data.</p> <p>Consumers SHOULD take steps to ensure URLs serving icons are from the
same domain as the client/server or a trusted domain.</p> <p>Consumers SHOULD take appropriate precautions when consuming SVGs as they can contain
executable JavaScript.</p> </div></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="icon-mimetype" data-typedoc-h="3"><span>mimeType?: string</span><a href="#icon-mimetype" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>Optional MIME type override if the source MIME type is missing or generic.
For example: <code>"image/png"</code>, <code>"image/jpeg"</code>, or <code>"image/svg+xml"</code>.</p> </div></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="icon-sizes" data-typedoc-h="3"><span>sizes?: string\[]</span><a href="#icon-sizes" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>Optional array of strings that specify sizes at which the icon can be used.
Each string should be in WxH format (e.g., <code>"48x48"</code>, <code>"96x96"</code>) or <code>"any"</code> for scalable formats like SVG.</p> <p>If not provided, the client should assume that the icon can be used at any size.</p> </div></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="icon-theme" data-typedoc-h="3"><span>theme?: "light" | "dark"</span><a href="#icon-theme" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>Optional specifier for the theme this icon is designed for. <code>"light"</code> indicates
the icon is designed to be used with a light background, and <code>"dark"</code> indicates
the icon is designed to be used with a dark background.</p> <p>If not provided, the client should assume the icon can be used with any theme.</p> </div></section>
</div>
<div class="type">
### `InputResponseRequestParams`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">InputResponseRequestParams</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#inputresponserequestparams-_meta">\_meta</a><span class="tsd-signature-symbol">:</span> <a href="#requestmetaobject" class="tsd-signature-type tsd-kind-interface">RequestMetaObject</a><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#inputresponserequestparams-inputresponses">inputResponses</a><span class="tsd-signature-symbol">?:</span> <a href="#inputresponses" class="tsd-signature-type tsd-kind-interface">InputResponses</a><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#inputresponserequestparams-requeststate">requestState</a><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>Common params for any request.</p> </div> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="inputresponserequestparams-_meta" data-typedoc-h="3"><span>\_meta: RequestMetaObject</span><a href="#inputresponserequestparams-_meta" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <aside class="tsd-sources"> <p>Inherited from <a href="#requestparams">RequestParams</a>.<a href="#requestparams-_meta">\_meta</a></p></aside></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="inputresponserequestparams-inputresponses" data-typedoc-h="3"><span>inputResponses?: InputResponses</span><a href="#inputresponserequestparams-inputresponses" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> </section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="inputresponserequestparams-requeststate" data-typedoc-h="3"><span>requestState?: string</span><a href="#inputresponserequestparams-requeststate" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> </section>
</div>
<div class="type">
### `JSONArray`
<div class="tsd-signature"><span class="tsd-kind-type-alias">JSONArray</span><span class="tsd-signature-symbol">:</span> <a href="#jsonvalue" class="tsd-signature-type tsd-kind-type-alias">JSONValue</a><span class="tsd-signature-symbol">\[]</span></div>
</div>
<div class="type">
### `JSONObject`
<div class="tsd-signature"><span class="tsd-kind-type-alias">JSONObject</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-symbol">\{</span> <span class="tsd-signature-symbol">\[</span><span class="tsd-kind-index-signature">key</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">]:</span> <a href="#jsonvalue" class="tsd-signature-type tsd-kind-type-alias">JSONValue</a> <span class="tsd-signature-symbol">}</span></div> <div class="tsd-type-declaration"> <div data-typedoc-h="4">Type Declaration</div> <ul class="tsd-parameters"> <li class="tsd-parameter-index-signature"> <div data-typedoc-h="5"><span class="tsd-signature-symbol">\[</span><span class="tsd-kind-parameter">key</span>: <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">]:</span> <a href="#jsonvalue" class="tsd-signature-type tsd-kind-type-alias">JSONValue</a></div></li></ul></div>
</div>
<div class="type">
### `JSONValue`
<div class="tsd-signature"><span class="tsd-kind-type-alias">JSONValue</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">number</span> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">boolean</span> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">null</span> <span class="tsd-signature-symbol">|</span> <a href="#jsonobject" class="tsd-signature-type tsd-kind-type-alias">JSONObject</a> <span class="tsd-signature-symbol">|</span> <a href="#jsonarray" class="tsd-signature-type tsd-kind-type-alias">JSONArray</a></div>
</div>
<div class="type">
### `LoggingLevel`
<div class="tsd-signature"><span class="tsd-kind-type-alias">LoggingLevel</span><span class="tsd-signature-symbol">:</span><br /> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">"debug"</span><br /> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">"info"</span><br /> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">"notice"</span><br /> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">"warning"</span><br /> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">"error"</span><br /> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">"critical"</span><br /> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">"alert"</span><br /> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">"emergency"</span></div> <div class="tsd-comment tsd-typography"><p>The severity of a log message.</p> <p>These map to syslog message severities, as specified in RFC-5424: <a href="https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1">[https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1](https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1)</a></p> </div> <div class="tsd-comment tsd-typography"> <div class="tsd-tag-deprecated"> <div class="tsd-anchor-link" data-typedoc-h="4">Deprecated</div><p>Deprecated as of protocol version 2026-07-28 (SEP-2577).
Remains in the specification for at least twelve months; see the
deprecated features registry.</p> </div></div>
</div>
<div class="type">
### `MetaObject`
<div class="tsd-signature"><span class="tsd-kind-type-alias">MetaObject</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">Record</span><span class="tsd-signature-symbol">\<</span><span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">,</span> <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">></span></div> <div class="tsd-comment tsd-typography"><p>Represents the contents of a <code>\_meta</code> field, which clients and servers use to attach additional metadata to their interactions.</p> <p>Certain key names are reserved by MCP for protocol-level metadata; implementations MUST NOT make assumptions about values at these keys. Additionally, specific schema definitions may reserve particular names for purpose-specific metadata, as declared in those definitions.</p> <p>Valid keys have two segments:</p> <p><strong>Prefix:</strong></p> <ul> <li>Optional — if specified, MUST be a series of <em>labels</em> separated by dots (<code>.</code>), followed by a slash (<code>/</code>).</li> <li>Labels MUST start with a letter and end with a letter or digit. Interior characters may be letters, digits, or hyphens (<code>-</code>).</li> <li>Implementations SHOULD use reverse DNS notation (e.g., <code>com.example/</code> rather than <code>example.com/</code>).</li> <li>Any prefix where the second label is <code>modelcontextprotocol</code> or <code>mcp</code> is <strong>reserved</strong> for MCP use. For example: <code>io.modelcontextprotocol/</code>, <code>dev.mcp/</code>, <code>org.modelcontextprotocol.api/</code>, and <code>com.mcp.tools/</code> are all reserved. However, <code>com.example.mcp/</code> is NOT reserved, as the second label is <code>example</code>.</li> </ul> <p><strong>Name:</strong></p> <ul> <li>Unless empty, MUST start and end with an alphanumeric character (<code>\[a-z0-9A-Z]</code>).</li> <li>Interior characters may be alphanumeric, hyphens (<code>-</code>), underscores (<code>\_</code>), or dots (<code>.</code>).</li> </ul> </div> <div class="tsd-comment tsd-typography"> <div class="tsd-tag-see"> <div class="tsd-anchor-link" data-typedoc-h="4">See</div><p><a href="/specification/2026-07-28/basic/index#meta">General fields: <code>\_meta</code></a> for more details.</p> </div></div>
</div>
<div class="type">
### `NotificationMetaObject`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">NotificationMetaObject</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#notificationmetaobject-iomodelcontextprotocolsubscriptionid">"io.modelcontextprotocol/subscriptionId"</a><span class="tsd-signature-symbol">?:</span> <a href="#requestid" class="tsd-signature-type tsd-kind-type-alias">RequestId</a><span class="tsd-signature-symbol">;</span><br /> <span class="tsd-signature-symbol">\[</span><span class="tsd-kind-index-signature">key</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">]:</span> <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>Extends <a href="#metaobject" class="tsd-kind-type-alias">MetaObject</a> with additional notification-specific fields. All key naming rules from <code>MetaObject</code> apply.</p> </div> <div class="tsd-comment tsd-typography"> <div class="tsd-tag-see"> <div class="tsd-anchor-link" data-typedoc-h="4">See</div><ul> <li><a href="#metaobject" class="tsd-kind-type-alias">MetaObject</a> for key naming rules and reserved prefixes.</li> <li><a href="/specification/2026-07-28/basic/index#meta">General fields: <code>\_meta</code></a> for more details.</li> </ul> </div></div> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="notificationmetaobject-iomodelcontextprotocolsubscriptionid" data-typedoc-h="3"><span>"io.modelcontextprotocol/subscriptionId"?: RequestId</span><a href="#notificationmetaobject-iomodelcontextprotocolsubscriptionid" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>Identifies the subscription stream a notification was delivered on. The
server MUST include this key on every notification delivered via a <a href="#subscriptionslistenrequest" class="tsd-kind-interface">subscriptions/listen</a> stream, so the
client can correlate the notification with the originating subscription.
The key is absent on notifications not delivered via a subscription
stream (e.g. progress notifications for an in-flight request), which is
why it is optional here.</p> <p>The value is the JSON-RPC ID of the <code>subscriptions/listen</code> request that
opened the stream.</p> </div></section>
</div>
<div class="type">
### `NotificationParams`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">NotificationParams</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#notificationparams-_meta">\_meta</a><span class="tsd-signature-symbol">?:</span> <a href="#notificationmetaobject" class="tsd-signature-type tsd-kind-interface">NotificationMetaObject</a><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>Common params for any notification.</p> </div> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="notificationparams-_meta" data-typedoc-h="3"><span>\_meta?: NotificationMetaObject</span><a href="#notificationparams-_meta" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> </section>
</div>
<div class="type">
### `PaginatedRequestParams`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">PaginatedRequestParams</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#paginatedrequestparams-_meta">\_meta</a><span class="tsd-signature-symbol">:</span> <a href="#requestmetaobject" class="tsd-signature-type tsd-kind-interface">RequestMetaObject</a><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#paginatedrequestparams-cursor">cursor</a><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>Common params for paginated requests.</p> </div> <div class="tsd-comment tsd-typography"> <details class="tsd-tag-example"> <summary class="tsd-anchor-link">Example: List request with cursor<a href="#paginatedrequestparams-example-list-request-with-cursor" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></summary><pre id="paginatedrequestparams-example-list-request-with-cursor"><code class="json"><span class="hl-0">\{</span><br /><span class="hl-0"> </span><span class="hl-1">"\_meta"</span><span class="hl-0">: \{</span><br /><span class="hl-0"> </span><span class="hl-1">"io.modelcontextprotocol/protocolVersion"</span><span class="hl-0">: </span><span class="hl-2">"2026-07-28"</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"io.modelcontextprotocol/clientInfo"</span><span class="hl-0">: \{</span><br /><span class="hl-0"> </span><span class="hl-1">"name"</span><span class="hl-0">: </span><span class="hl-2">"ExampleClient"</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"version"</span><span class="hl-0">: </span><span class="hl-2">"1.0.0"</span><br /><span class="hl-0"> },</span><br /><span class="hl-0"> </span><span class="hl-1">"io.modelcontextprotocol/clientCapabilities"</span><span class="hl-0">: \{}</span><br /><span class="hl-0"> },</span><br /><span class="hl-0"> </span><span class="hl-1">"cursor"</span><span class="hl-0">: </span><span class="hl-2">"eyJwYWdlIjogMn0="</span><br /><span class="hl-0">}</span> </code><button type="button">Copy</button></pre> </details></div> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="paginatedrequestparams-_meta" data-typedoc-h="3"><span>\_meta: RequestMetaObject</span><a href="#paginatedrequestparams-_meta" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <aside class="tsd-sources"> <p>Inherited from <a href="#requestparams">RequestParams</a>.<a href="#requestparams-_meta">\_meta</a></p></aside></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="paginatedrequestparams-cursor" data-typedoc-h="3"><span>cursor?: string</span><a href="#paginatedrequestparams-cursor" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>An opaque token representing the current pagination position.
If provided, the server should return results starting after this cursor.</p> </div></section>
</div>
<div class="type">
### `ProgressToken`
<div class="tsd-signature"><span class="tsd-kind-type-alias">ProgressToken</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">number</span></div> <div class="tsd-comment tsd-typography"><p>A progress token, used to associate progress notifications with the original request.</p> </div>
</div>
<div class="type">
### `RequestId`
<div class="tsd-signature"><span class="tsd-kind-type-alias">RequestId</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">number</span></div> <div class="tsd-comment tsd-typography"><p>A uniquely identifying ID for a request in JSON-RPC.</p> </div>
</div>
<div class="type">
### `RequestMetaObject`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">RequestMetaObject</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#requestmetaobject-progresstoken">progressToken</a><span class="tsd-signature-symbol">?:</span> <a href="#progresstoken" class="tsd-signature-type tsd-kind-type-alias">ProgressToken</a><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#requestmetaobject-iomodelcontextprotocolprotocolversion">"io.modelcontextprotocol/protocolVersion"</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#requestmetaobject-iomodelcontextprotocolclientinfo">"io.modelcontextprotocol/clientInfo"</a><span class="tsd-signature-symbol">?:</span> <a href="#implementation" class="tsd-signature-type tsd-kind-interface">Implementation</a><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#requestmetaobject-iomodelcontextprotocolclientcapabilities">"io.modelcontextprotocol/clientCapabilities"</a><span class="tsd-signature-symbol">:</span> <a href="#clientcapabilities" class="tsd-signature-type tsd-kind-interface">ClientCapabilities</a><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#requestmetaobject-iomodelcontextprotocolloglevel">"io.modelcontextprotocol/logLevel"</a><span class="tsd-signature-symbol">?:</span> <a href="#logginglevel" class="tsd-signature-type tsd-kind-type-alias">LoggingLevel</a><span class="tsd-signature-symbol">;</span><br /> <span class="tsd-signature-symbol">\[</span><span class="tsd-kind-index-signature">key</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">]:</span> <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>Extends <a href="#metaobject" class="tsd-kind-type-alias">MetaObject</a> with additional request-specific fields. All key naming rules from <code>MetaObject</code> apply.</p> </div> <div class="tsd-comment tsd-typography"> <div class="tsd-tag-see"> <div class="tsd-anchor-link" data-typedoc-h="4">See</div><ul> <li><a href="#metaobject" class="tsd-kind-type-alias">MetaObject</a> for key naming rules and reserved prefixes.</li> <li><a href="/specification/2026-07-28/basic/index#meta">General fields: <code>\_meta</code></a> for more details.</li> </ul> </div></div> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="requestmetaobject-progresstoken" data-typedoc-h="3"><span>progressToken?: ProgressToken</span><a href="#requestmetaobject-progresstoken" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>If specified, the caller is requesting out-of-band progress notifications for this request (as represented by <a href="#progressnotification" class="tsd-kind-interface">notifications/progress</a>). The value of this parameter is an opaque token that will be attached to any subsequent notifications. The receiver is not obligated to provide these notifications.</p> </div></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="requestmetaobject-iomodelcontextprotocolprotocolversion" data-typedoc-h="3"><span>"io.modelcontextprotocol/protocolVersion": string</span><a href="#requestmetaobject-iomodelcontextprotocolprotocolversion" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>The MCP Protocol Version being used for this request. Required.</p> <p>For the HTTP transport, this value MUST match the <code>MCP-Protocol-Version</code>
header; otherwise the server MUST return a <code>400 Bad Request</code>. If the
server does not support the requested version, it MUST return an <a href="#unsupportedprotocolversionerror" class="tsd-kind-interface">UnsupportedProtocolVersionError</a>.</p> </div></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="requestmetaobject-iomodelcontextprotocolclientinfo" data-typedoc-h="3"><span>"io.modelcontextprotocol/clientInfo"?: Implementation</span><a href="#requestmetaobject-iomodelcontextprotocolclientinfo" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>Identifies the client software making the request. Clients SHOULD
include this field on every request unless specifically configured not
to do so.</p> <p>The <a href="#implementation" class="tsd-kind-interface">Implementation</a> schema requires <code>name</code> and <code>version</code>; other
fields are optional.</p> <p>The value is self-reported by the client and is not verified by the
protocol. It is intended for display, logging, and debugging. Servers
SHOULD NOT use it to change their behavior, and SHOULD NOT rely on it for
security decisions.</p> </div></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="requestmetaobject-iomodelcontextprotocolclientcapabilities" data-typedoc-h="3"><span>"io.modelcontextprotocol/clientCapabilities": ClientCapabilities</span><a href="#requestmetaobject-iomodelcontextprotocolclientcapabilities" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>The client's capabilities for this specific request. Required.</p> <p>Capabilities are declared per-request rather than once at initialization;
an empty object means the client supports no optional capabilities.
Servers MUST NOT infer capabilities from prior requests.</p> </div></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="requestmetaobject-iomodelcontextprotocolloglevel" data-typedoc-h="3"><span class="deprecated">"io.modelcontextprotocol/logLevel"?: LoggingLevel</span><a href="#requestmetaobject-iomodelcontextprotocolloglevel" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>The desired log level for this request. Optional.</p> <p>If absent, the server MUST NOT send any <a href="#loggingmessagenotification" class="tsd-kind-interface">notifications/message</a>
notifications for this request. The client opts in to log messages by
explicitly setting a level. Replaces the former <code>logging/setLevel</code> RPC.</p> </div> <div class="tsd-comment tsd-typography"> <div class="tsd-tag-deprecated"> <div class="tsd-anchor-link" data-typedoc-h="4">Deprecated</div><p>Deprecated as of protocol version 2026-07-28 (SEP-2577).
Remains in the specification for at least twelve months; see the
deprecated features registry.</p> </div></div></section>
</div>
<div class="type">
### `RequestParams`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">RequestParams</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#requestparams-_meta">\_meta</a><span class="tsd-signature-symbol">:</span> <a href="#requestmetaobject" class="tsd-signature-type tsd-kind-interface">RequestMetaObject</a><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>Common params for any request.</p> </div> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="requestparams-_meta" data-typedoc-h="3"><span>\_meta: RequestMetaObject</span><a href="#requestparams-_meta" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> </section>
</div>
<div class="type">
### `Result`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">Result</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#result-_meta">\_meta</a><span class="tsd-signature-symbol">?:</span> <a href="#resultmetaobject" class="tsd-signature-type tsd-kind-interface">ResultMetaObject</a><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#result-resulttype">resultType</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">;</span><br /> <span class="tsd-signature-symbol">\[</span><span class="tsd-kind-index-signature">key</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">]:</span> <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>Common result fields.</p> </div> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="result-_meta" data-typedoc-h="3"><span>\_meta?: ResultMetaObject</span><a href="#result-_meta" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> </section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="result-resulttype" data-typedoc-h="3"><span>resultType: string</span><a href="#result-resulttype" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>Indicates the type of the result, which allows the client to determine
how to parse the result object.</p> <p>Servers implementing this protocol version MUST include this field.
For backward compatibility, when a client receives a result from a
server implementing an earlier protocol version (which does not include <code>resultType</code>), the client MUST treat the absent field as <code>"complete"</code>.</p> </div></section>
</div>
<div class="type">
### `ResultMetaObject`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">ResultMetaObject</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#resultmetaobject-iomodelcontextprotocolserverinfo">"io.modelcontextprotocol/serverInfo"</a><span class="tsd-signature-symbol">?:</span> <a href="#implementation" class="tsd-signature-type tsd-kind-interface">Implementation</a><span class="tsd-signature-symbol">;</span><br /> <span class="tsd-signature-symbol">\[</span><span class="tsd-kind-index-signature">key</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">]:</span> <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>Extends <a href="#metaobject" class="tsd-kind-type-alias">MetaObject</a> with additional result-specific fields. All key naming rules from <code>MetaObject</code> apply.</p> </div> <div class="tsd-comment tsd-typography"> <div class="tsd-tag-see"> <div class="tsd-anchor-link" data-typedoc-h="4">See</div><ul> <li><a href="#metaobject" class="tsd-kind-type-alias">MetaObject</a> for key naming rules and reserved prefixes.</li> <li><a href="/specification/2026-07-28/basic/index#meta">General fields: <code>\_meta</code></a> for more details.</li> </ul> </div></div> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="resultmetaobject-iomodelcontextprotocolserverinfo" data-typedoc-h="3"><span>"io.modelcontextprotocol/serverInfo"?: Implementation</span><a href="#resultmetaobject-iomodelcontextprotocolserverinfo" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>Identifies the server software producing the response. Servers SHOULD
include this field on every response unless specifically configured not
to do so.</p> <p>The <a href="#implementation" class="tsd-kind-interface">Implementation</a> schema requires <code>name</code> and <code>version</code>; other
fields are optional.</p> <p>The value is self-reported by the server and is not verified by the
protocol. It is intended for display, logging, and debugging. Clients
SHOULD NOT use it to change their behavior, and SHOULD NOT rely on it for
security decisions.</p> </div></section>
</div>
<div class="type">
### `ResultType`
<div class="tsd-signature"><span class="tsd-kind-type-alias">ResultType</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">"complete"</span> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">"input\_required"</span> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">string</span></div> <div class="tsd-comment tsd-typography"><p>Indicates the type of a <a href="#result" class="tsd-kind-interface">Result</a> object, allowing the client to
determine how to parse the response.</p> <p>complete - the request completed successfully and the result contains the final content.
input\_required - the request requires additional input and the result contains an <a href="#inputrequiredresult" class="tsd-kind-interface">InputRequiredResult</a> object with instructions for the client to provide additional input before retrying the original request.</p> </div>
</div>
<div class="type">
### `Role`
<div class="tsd-signature"><span class="tsd-kind-type-alias">Role</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">"user"</span> <span class="tsd-signature-symbol">|</span> <span class="tsd-signature-type">"assistant"</span></div> <div class="tsd-comment tsd-typography"><p>The sender or recipient of messages and data in a conversation.</p> </div>
</div>
## Errors
<div class="type">
### `Error`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">Error</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#error-code">code</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">number</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#error-message">message</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#error-data">data</a><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="error-code" data-typedoc-h="3"><span>code: number</span><a href="#error-code" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>The error type that occurred.</p> </div></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="error-message" data-typedoc-h="3"><span>message: string</span><a href="#error-message" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>A short description of the error. The message SHOULD be limited to a concise single sentence.</p> </div></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="error-data" data-typedoc-h="3"><span>data?: unknown</span><a href="#error-data" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>Additional information about the error. The value of this member is defined by the sender (e.g. detailed error information, nested errors etc.).</p> </div></section>
</div>
<div class="type">
### `HEADER_MISMATCH`
<div class="tsd-signature"><span class="tsd-kind-variable">HEADER\_MISMATCH</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">-32020</span></div> <div class="tsd-comment tsd-typography"><p>Error code returned when the HTTP headers of a request do not match the
corresponding values in the request body, or required headers are
missing or malformed.</p> </div>
</div>
<div class="type">
### `HeaderMismatchError`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">HeaderMismatchError</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#headermismatcherror-jsonrpc">jsonrpc</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">"2.0"</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#headermismatcherror-id">id</a><span class="tsd-signature-symbol">?:</span> <a href="#requestid" class="tsd-signature-type tsd-kind-type-alias">RequestId</a><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#headermismatcherror-error">error</a><span class="tsd-signature-symbol">:</span> <a href="#error" class="tsd-signature-type tsd-kind-interface">Error</a> <span class="tsd-signature-symbol">&</span> <span class="tsd-signature-symbol">\{</span> <span class="tsd-kind-property">code</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">-32020</span> <span class="tsd-signature-symbol">}</span><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>Returned when a server rejects a request because the values in the HTTP
headers do not match the corresponding values in the request body, or
because required headers are missing or malformed. For HTTP, the response
status code MUST be <code>400 Bad Request</code>.</p> </div> <div class="tsd-comment tsd-typography"> <details class="tsd-tag-example"> <summary class="tsd-anchor-link">Example: Header mismatch<a href="#headermismatcherror-example-header-mismatch" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></summary><pre id="headermismatcherror-example-header-mismatch"><code class="json"><span class="hl-0">\{</span><br /><span class="hl-0"> </span><span class="hl-1">"jsonrpc"</span><span class="hl-0">: </span><span class="hl-2">"2.0"</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"id"</span><span class="hl-0">: </span><span class="hl-3">1</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"error"</span><span class="hl-0">: \{</span><br /><span class="hl-0"> </span><span class="hl-1">"code"</span><span class="hl-0">: </span><span class="hl-3">-32020</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"message"</span><span class="hl-0">: </span><span class="hl-2">"Header mismatch: Mcp-Name header value 'foo' does not match body value 'bar'"</span><br /><span class="hl-0"> }</span><br /><span class="hl-0">}</span> </code><button type="button">Copy</button></pre> </details></div> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="headermismatcherror-jsonrpc" data-typedoc-h="3"><span>jsonrpc: "2.0"</span><a href="#headermismatcherror-jsonrpc" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <aside class="tsd-sources"> <p>Inherited from <a href="#jsonrpcerrorresponse">JSONRPCErrorResponse</a>.<a href="#jsonrpcerrorresponse-jsonrpc">jsonrpc</a></p></aside></section> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="headermismatcherror-id" data-typedoc-h="3"><span>id?: RequestId</span><a href="#headermismatcherror-id" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <aside class="tsd-sources"> <p>Inherited from <a href="#jsonrpcerrorresponse">JSONRPCErrorResponse</a>.<a href="#jsonrpcerrorresponse-id">id</a></p></aside></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="headermismatcherror-error" data-typedoc-h="3"><span>error: Error & \{ code: -32020 }</span><a href="#headermismatcherror-error" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> </section>
</div>
<div class="type">
### `InternalError`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">InternalError</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#internalerror-message">message</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#internalerror-data">data</a><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#internalerror-code">code</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">-32603</span><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>A JSON-RPC error indicating that an internal error occurred on the receiver. This error is returned when the receiver encounters an unexpected condition that prevents it from fulfilling the request.</p> </div> <div class="tsd-comment tsd-typography"> <div class="tsd-tag-see"> <div class="tsd-anchor-link" data-typedoc-h="4">See</div><p><a href="https://www.jsonrpc.org/specification#error_object">JSON-RPC 2.0 Error Object</a></p> </div> <details class="tsd-tag-example"> <summary class="tsd-anchor-link">Example: Unexpected error<a href="#internalerror-example-unexpected-error" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></summary><pre id="internalerror-example-unexpected-error"><code class="json"><span class="hl-0">\{</span><br /><span class="hl-0"> </span><span class="hl-1">"code"</span><span class="hl-0">: </span><span class="hl-3">-32603</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"message"</span><span class="hl-0">: </span><span class="hl-2">"Internal error"</span><br /><span class="hl-0">}</span> </code><button type="button">Copy</button></pre> </details></div> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="internalerror-message" data-typedoc-h="3"><span>message: string</span><a href="#internalerror-message" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>A short description of the error. The message SHOULD be limited to a concise single sentence.</p> </div><aside class="tsd-sources"> <p>Inherited from <a href="#error">Error</a>.<a href="#error-message">message</a></p></aside></section> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="internalerror-data" data-typedoc-h="3"><span>data?: unknown</span><a href="#internalerror-data" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>Additional information about the error. The value of this member is defined by the sender (e.g. detailed error information, nested errors etc.).</p> </div><aside class="tsd-sources"> <p>Inherited from <a href="#error">Error</a>.<a href="#error-data">data</a></p></aside></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="internalerror-code" data-typedoc-h="3"><span>code: -32603</span><a href="#internalerror-code" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>The error type that occurred.</p> </div><aside class="tsd-sources"> <p>Overrides <a href="#error">Error</a>.<a href="#error-code">code</a></p></aside></section>
</div>
<div class="type">
### `InvalidParamsError`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">InvalidParamsError</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#invalidparamserror-message">message</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#invalidparamserror-data">data</a><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#invalidparamserror-code">code</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">-32602</span><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>A JSON-RPC error indicating that the method parameters are invalid or malformed.</p> <p>In MCP, this error is returned in various contexts when request parameters fail validation:</p> <ul> <li><strong>Tools</strong>: Unknown tool name or invalid tool arguments</li> <li><strong>Prompts</strong>: Unknown prompt name or missing required arguments</li> <li><strong>Pagination</strong>: Invalid or expired cursor values</li> <li><strong>Logging</strong>: Invalid log level</li> <li><strong>Elicitation</strong>: Server requests an elicitation mode not declared in client capabilities</li> <li><strong>Sampling</strong>: Missing tool result or tool results mixed with other content</li> </ul> </div> <div class="tsd-comment tsd-typography"> <div class="tsd-tag-see"> <div class="tsd-anchor-link" data-typedoc-h="4">See</div><p><a href="https://www.jsonrpc.org/specification#error_object">JSON-RPC 2.0 Error Object</a></p> </div> <details class="tsd-tag-example"> <summary class="tsd-anchor-link">Example: Unknown tool<a href="#invalidparamserror-example-unknown-tool" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></summary><pre id="invalidparamserror-example-unknown-tool"><code class="json"><span class="hl-0">\{</span><br /><span class="hl-0"> </span><span class="hl-1">"code"</span><span class="hl-0">: </span><span class="hl-3">-32602</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"message"</span><span class="hl-0">: </span><span class="hl-2">"Unknown tool: invalid\_tool\_name"</span><br /><span class="hl-0">}</span> </code><button type="button">Copy</button></pre> </details> <details class="tsd-tag-example"> <summary class="tsd-anchor-link">Example: Invalid tool arguments<a href="#invalidparamserror-example-invalid-tool-arguments" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></summary><pre id="invalidparamserror-example-invalid-tool-arguments"><code class="json"><span class="hl-0">\{</span><br /><span class="hl-0"> </span><span class="hl-1">"code"</span><span class="hl-0">: </span><span class="hl-3">-32602</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"message"</span><span class="hl-0">: </span><span class="hl-2">"Invalid arguments for tool calculate: Missing required property 'expression'"</span><br /><span class="hl-0">}</span> </code><button type="button">Copy</button></pre> </details> <details class="tsd-tag-example"> <summary class="tsd-anchor-link">Example: Unknown prompt<a href="#invalidparamserror-example-unknown-prompt" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></summary><pre id="invalidparamserror-example-unknown-prompt"><code class="json"><span class="hl-0">\{</span><br /><span class="hl-0"> </span><span class="hl-1">"code"</span><span class="hl-0">: </span><span class="hl-3">-32602</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"message"</span><span class="hl-0">: </span><span class="hl-2">"Unknown prompt: invalid\_prompt\_name"</span><br /><span class="hl-0">}</span> </code><button type="button">Copy</button></pre> </details> <details class="tsd-tag-example"> <summary class="tsd-anchor-link">Example: Invalid cursor<a href="#invalidparamserror-example-invalid-cursor" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></summary><pre id="invalidparamserror-example-invalid-cursor"><code class="json"><span class="hl-0">\{</span><br /><span class="hl-0"> </span><span class="hl-1">"code"</span><span class="hl-0">: </span><span class="hl-3">-32602</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"message"</span><span class="hl-0">: </span><span class="hl-2">"Invalid cursor"</span><br /><span class="hl-0">}</span> </code><button type="button">Copy</button></pre> </details></div> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="invalidparamserror-message" data-typedoc-h="3"><span>message: string</span><a href="#invalidparamserror-message" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>A short description of the error. The message SHOULD be limited to a concise single sentence.</p> </div><aside class="tsd-sources"> <p>Inherited from <a href="#error">Error</a>.<a href="#error-message">message</a></p></aside></section> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="invalidparamserror-data" data-typedoc-h="3"><span>data?: unknown</span><a href="#invalidparamserror-data" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>Additional information about the error. The value of this member is defined by the sender (e.g. detailed error information, nested errors etc.).</p> </div><aside class="tsd-sources"> <p>Inherited from <a href="#error">Error</a>.<a href="#error-data">data</a></p></aside></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="invalidparamserror-code" data-typedoc-h="3"><span>code: -32602</span><a href="#invalidparamserror-code" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>The error type that occurred.</p> </div><aside class="tsd-sources"> <p>Overrides <a href="#error">Error</a>.<a href="#error-code">code</a></p></aside></section>
</div>
<div class="type">
### `InvalidRequestError`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">InvalidRequestError</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#invalidrequesterror-message">message</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#invalidrequesterror-data">data</a><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#invalidrequesterror-code">code</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">-32600</span><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>A JSON-RPC error indicating that the request is not a valid request object. This error is returned when the message structure does not conform to the JSON-RPC 2.0 specification requirements for a request (e.g., missing required fields like <code>jsonrpc</code> or <code>method</code>, or using invalid types for these fields).</p> </div> <div class="tsd-comment tsd-typography"> <div class="tsd-tag-see"> <div class="tsd-anchor-link" data-typedoc-h="4">See</div><p><a href="https://www.jsonrpc.org/specification#error_object">JSON-RPC 2.0 Error Object</a></p> </div></div> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="invalidrequesterror-message" data-typedoc-h="3"><span>message: string</span><a href="#invalidrequesterror-message" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>A short description of the error. The message SHOULD be limited to a concise single sentence.</p> </div><aside class="tsd-sources"> <p>Inherited from <a href="#error">Error</a>.<a href="#error-message">message</a></p></aside></section> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="invalidrequesterror-data" data-typedoc-h="3"><span>data?: unknown</span><a href="#invalidrequesterror-data" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>Additional information about the error. The value of this member is defined by the sender (e.g. detailed error information, nested errors etc.).</p> </div><aside class="tsd-sources"> <p>Inherited from <a href="#error">Error</a>.<a href="#error-data">data</a></p></aside></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="invalidrequesterror-code" data-typedoc-h="3"><span>code: -32600</span><a href="#invalidrequesterror-code" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>The error type that occurred.</p> </div><aside class="tsd-sources"> <p>Overrides <a href="#error">Error</a>.<a href="#error-code">code</a></p></aside></section>
</div>
<div class="type">
### `MethodNotFoundError`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">MethodNotFoundError</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#methodnotfounderror-message">message</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#methodnotfounderror-data">data</a><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#methodnotfounderror-code">code</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">-32601</span><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>A JSON-RPC error indicating that the requested method does not exist or is not available.</p> <p>In MCP, a server returns this error when a client invokes a method the server does not implement — either a genuinely unknown method, or one gated behind a server capability the server did not advertise (e.g., calling <code>prompts/list</code> when the <code>prompts</code> capability was not advertised).</p> <p>A request that requires a client capability the client did not declare is signalled instead by <a href="#missingrequiredclientcapabilityerror" class="tsd-kind-interface">MissingRequiredClientCapabilityError</a> (<code>-32021</code>).</p> </div> <div class="tsd-comment tsd-typography"> <div class="tsd-tag-see"> <div class="tsd-anchor-link" data-typedoc-h="4">See</div><p><a href="https://www.jsonrpc.org/specification#error_object">JSON-RPC 2.0 Error Object</a></p> </div> <details class="tsd-tag-example"> <summary class="tsd-anchor-link">Example: Prompts not supported<a href="#methodnotfounderror-example-prompts-not-supported" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></summary><pre id="methodnotfounderror-example-prompts-not-supported"><code class="json"><span class="hl-0">\{</span><br /><span class="hl-0"> </span><span class="hl-1">"code"</span><span class="hl-0">: </span><span class="hl-3">-32601</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"message"</span><span class="hl-0">: </span><span class="hl-2">"Prompts not supported"</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"data"</span><span class="hl-0">: \{</span><br /><span class="hl-0"> </span><span class="hl-1">"reason"</span><span class="hl-0">: </span><span class="hl-2">"Server does not support the prompts capability"</span><br /><span class="hl-0"> }</span><br /><span class="hl-0">}</span> </code><button type="button">Copy</button></pre> </details></div> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="methodnotfounderror-message" data-typedoc-h="3"><span>message: string</span><a href="#methodnotfounderror-message" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>A short description of the error. The message SHOULD be limited to a concise single sentence.</p> </div><aside class="tsd-sources"> <p>Inherited from <a href="#error">Error</a>.<a href="#error-message">message</a></p></aside></section> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="methodnotfounderror-data" data-typedoc-h="3"><span>data?: unknown</span><a href="#methodnotfounderror-data" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>Additional information about the error. The value of this member is defined by the sender (e.g. detailed error information, nested errors etc.).</p> </div><aside class="tsd-sources"> <p>Inherited from <a href="#error">Error</a>.<a href="#error-data">data</a></p></aside></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="methodnotfounderror-code" data-typedoc-h="3"><span>code: -32601</span><a href="#methodnotfounderror-code" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>The error type that occurred.</p> </div><aside class="tsd-sources"> <p>Overrides <a href="#error">Error</a>.<a href="#error-code">code</a></p></aside></section>
</div>
<div class="type">
### `MISSING_REQUIRED_CLIENT_CAPABILITY`
<div class="tsd-signature"><span class="tsd-kind-variable">MISSING\_REQUIRED\_CLIENT\_CAPABILITY</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">-32021</span></div> <div class="tsd-comment tsd-typography"><p>Error code returned when a server requires a client capability that was
not declared in the request's <code>clientCapabilities</code>.</p> </div>
</div>
<div class="type">
### `MissingRequiredClientCapabilityError`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">MissingRequiredClientCapabilityError</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#missingrequiredclientcapabilityerror-jsonrpc">jsonrpc</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">"2.0"</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#missingrequiredclientcapabilityerror-id">id</a><span class="tsd-signature-symbol">?:</span> <a href="#requestid" class="tsd-signature-type tsd-kind-type-alias">RequestId</a><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#missingrequiredclientcapabilityerror-error">error</a><span class="tsd-signature-symbol">:</span> <a href="#error" class="tsd-signature-type tsd-kind-interface">Error</a> <span class="tsd-signature-symbol">&</span> <span class="tsd-signature-symbol">\{</span><br /> <span class="tsd-kind-property">code</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">-32021</span><span class="tsd-signature-symbol">;</span><br /> <span class="tsd-kind-property">data</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-symbol">\{</span> <span class="tsd-kind-property">requiredCapabilities</span><span class="tsd-signature-symbol">:</span> <a href="#clientcapabilities" class="tsd-signature-type tsd-kind-interface">ClientCapabilities</a> <span class="tsd-signature-symbol">}</span><span class="tsd-signature-symbol">;</span><br /> <span class="tsd-signature-symbol">}</span><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>Returned when processing a request requires a capability the client did not
declare in <code>clientCapabilities</code>. For HTTP, the response status code MUST be <code>400 Bad Request</code>.</p> </div> <div class="tsd-comment tsd-typography"> <details class="tsd-tag-example"> <summary class="tsd-anchor-link">Example: Missing elicitation capability<a href="#missingrequiredclientcapabilityerror-example-missing-elicitation-capability" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></summary><pre id="missingrequiredclientcapabilityerror-example-missing-elicitation-capability"><code class="json"><span class="hl-0">\{</span><br /><span class="hl-0"> </span><span class="hl-1">"jsonrpc"</span><span class="hl-0">: </span><span class="hl-2">"2.0"</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"id"</span><span class="hl-0">: </span><span class="hl-3">1</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"error"</span><span class="hl-0">: \{</span><br /><span class="hl-0"> </span><span class="hl-1">"code"</span><span class="hl-0">: </span><span class="hl-3">-32021</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"message"</span><span class="hl-0">: </span><span class="hl-2">"Server requires the elicitation capability for this request"</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"data"</span><span class="hl-0">: \{</span><br /><span class="hl-0"> </span><span class="hl-1">"requiredCapabilities"</span><span class="hl-0">: \{</span><br /><span class="hl-0"> </span><span class="hl-1">"elicitation"</span><span class="hl-0">: \{}</span><br /><span class="hl-0"> }</span><br /><span class="hl-0"> }</span><br /><span class="hl-0"> }</span><br /><span class="hl-0">}</span> </code><button type="button">Copy</button></pre> </details></div> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="missingrequiredclientcapabilityerror-jsonrpc" data-typedoc-h="3"><span>jsonrpc: "2.0"</span><a href="#missingrequiredclientcapabilityerror-jsonrpc" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <aside class="tsd-sources"> <p>Inherited from <a href="#jsonrpcerrorresponse">JSONRPCErrorResponse</a>.<a href="#jsonrpcerrorresponse-jsonrpc">jsonrpc</a></p></aside></section> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="missingrequiredclientcapabilityerror-id" data-typedoc-h="3"><span>id?: RequestId</span><a href="#missingrequiredclientcapabilityerror-id" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <aside class="tsd-sources"> <p>Inherited from <a href="#jsonrpcerrorresponse">JSONRPCErrorResponse</a>.<a href="#jsonrpcerrorresponse-id">id</a></p></aside></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="missingrequiredclientcapabilityerror-error" data-typedoc-h="3"><span>error: Error & \{ code: -32021; data: \{ requiredCapabilities: ClientCapabilities }; }</span><a href="#missingrequiredclientcapabilityerror-error" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> </section>
</div>
<div class="type">
### `ParseError`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">ParseError</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#parseerror-message">message</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#parseerror-data">data</a><span class="tsd-signature-symbol">?:</span> <span class="tsd-signature-type">unknown</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#parseerror-code">code</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">-32700</span><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>A JSON-RPC error indicating that invalid JSON was received by the server. This error is returned when the server cannot parse the JSON text of a message.</p> </div> <div class="tsd-comment tsd-typography"> <div class="tsd-tag-see"> <div class="tsd-anchor-link" data-typedoc-h="4">See</div><p><a href="https://www.jsonrpc.org/specification#error_object">JSON-RPC 2.0 Error Object</a></p> </div> <details class="tsd-tag-example"> <summary class="tsd-anchor-link">Example: Invalid JSON<a href="#parseerror-example-invalid-json" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></summary><pre id="parseerror-example-invalid-json"><code class="json"><span class="hl-0">\{</span><br /><span class="hl-0"> </span><span class="hl-1">"code"</span><span class="hl-0">: </span><span class="hl-3">-32700</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"message"</span><span class="hl-0">: </span><span class="hl-2">"Parse error: Invalid JSON"</span><br /><span class="hl-0">}</span> </code><button type="button">Copy</button></pre> </details></div> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="parseerror-message" data-typedoc-h="3"><span>message: string</span><a href="#parseerror-message" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>A short description of the error. The message SHOULD be limited to a concise single sentence.</p> </div><aside class="tsd-sources"> <p>Inherited from <a href="#error">Error</a>.<a href="#error-message">message</a></p></aside></section> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="parseerror-data" data-typedoc-h="3"><span>data?: unknown</span><a href="#parseerror-data" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>Additional information about the error. The value of this member is defined by the sender (e.g. detailed error information, nested errors etc.).</p> </div><aside class="tsd-sources"> <p>Inherited from <a href="#error">Error</a>.<a href="#error-data">data</a></p></aside></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="parseerror-code" data-typedoc-h="3"><span>code: -32700</span><a href="#parseerror-code" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <div class="tsd-comment tsd-typography"><p>The error type that occurred.</p> </div><aside class="tsd-sources"> <p>Overrides <a href="#error">Error</a>.<a href="#error-code">code</a></p></aside></section>
</div>
<div class="type">
### `UNSUPPORTED_PROTOCOL_VERSION`
<div class="tsd-signature"><span class="tsd-kind-variable">UNSUPPORTED\_PROTOCOL\_VERSION</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">-32022</span></div> <div class="tsd-comment tsd-typography"><p>Error code returned when the request's protocol version is not supported
by the server.</p> </div>
</div>
<div class="type">
### `UnsupportedProtocolVersionError`
<div class="tsd-signature"><span class="tsd-signature-keyword">interface</span> <span class="tsd-kind-interface">UnsupportedProtocolVersionError</span> <span class="tsd-signature-symbol">\{</span><br /> <a class="tsd-kind-property" href="#unsupportedprotocolversionerror-jsonrpc">jsonrpc</a><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">"2.0"</span><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#unsupportedprotocolversionerror-id">id</a><span class="tsd-signature-symbol">?:</span> <a href="#requestid" class="tsd-signature-type tsd-kind-type-alias">RequestId</a><span class="tsd-signature-symbol">;</span><br /> <a class="tsd-kind-property" href="#unsupportedprotocolversionerror-error">error</a><span class="tsd-signature-symbol">:</span> <a href="#error" class="tsd-signature-type tsd-kind-interface">Error</a> <span class="tsd-signature-symbol">&</span> <span class="tsd-signature-symbol">\{</span><br /> <span class="tsd-kind-property">code</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">-32022</span><span class="tsd-signature-symbol">;</span><br /> <span class="tsd-kind-property">data</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-symbol">\{</span> <span class="tsd-kind-property">supported</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span><span class="tsd-signature-symbol">\[]</span><span class="tsd-signature-symbol">;</span> <span class="tsd-kind-property">requested</span><span class="tsd-signature-symbol">:</span> <span class="tsd-signature-type">string</span> <span class="tsd-signature-symbol">}</span><span class="tsd-signature-symbol">;</span><br /> <span class="tsd-signature-symbol">}</span><span class="tsd-signature-symbol">;</span><br /><span class="tsd-signature-symbol">}</span></div> <div class="tsd-comment tsd-typography"><p>Returned when the request's protocol version is unknown to the server or
unsupported (e.g., a known experimental or draft version the server has
chosen not to implement). For HTTP, the response status code MUST be <code>400 Bad Request</code>.</p> </div> <div class="tsd-comment tsd-typography"> <details class="tsd-tag-example"> <summary class="tsd-anchor-link">Example: Unsupported protocol version<a href="#unsupportedprotocolversionerror-example-unsupported-protocol-version" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></summary><pre id="unsupportedprotocolversionerror-example-unsupported-protocol-version"><code class="json"><span class="hl-0">\{</span><br /><span class="hl-0"> </span><span class="hl-1">"jsonrpc"</span><span class="hl-0">: </span><span class="hl-2">"2.0"</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"id"</span><span class="hl-0">: </span><span class="hl-3">1</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"error"</span><span class="hl-0">: \{</span><br /><span class="hl-0"> </span><span class="hl-1">"code"</span><span class="hl-0">: </span><span class="hl-3">-32022</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"message"</span><span class="hl-0">: </span><span class="hl-2">"Unsupported protocol version"</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-1">"data"</span><span class="hl-0">: \{</span><br /><span class="hl-0"> </span><span class="hl-1">"supported"</span><span class="hl-0">: \[</span><br /><span class="hl-0"> </span><span class="hl-2">"2026-07-28"</span><span class="hl-0">,</span><br /><span class="hl-0"> </span><span class="hl-2">"2025-11-25"</span><br /><span class="hl-0"> ],</span><br /><span class="hl-0"> </span><span class="hl-1">"requested"</span><span class="hl-0">: </span><span class="hl-2">"1900-01-01"</span><br /><span class="hl-0"> }</span><br /><span class="hl-0"> }</span><br /><span class="hl-0">}</span> </code><button type="button">Copy</button></pre> </details></div> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="unsupportedprotocolversionerror-jsonrpc" data-typedoc-h="3"><span>jsonrpc: "2.0"</span><a href="#unsupportedprotocolversionerror-jsonrpc" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <aside class="tsd-sources"> <p>Inherited from <a href="#jsonrpcerrorresponse">JSONRPCErrorResponse</a>.<a href="#jsonrpcerrorresponse-jsonrpc">jsonrpc</a></p></aside></section> <section class="tsd-panel tsd-member tsd-is-inherited"> <div class="tsd-anchor-link" id="unsupportedprotocolversionerror-id" data-typedoc-h="3"><span>id?: RequestId</span><a href="#unsupportedprotocolversionerror-id" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> <aside class="tsd-sources"> <p>Inherited from <a href="#jsonrpcerrorresponse">JSONRPCErrorResponse</a>.<a href="#jsonrpcerrorresponse-id">id</a></p></aside></section> <section class="tsd-panel tsd-member"> <div class="tsd-anchor-link" id="unsupportedprotocolversionerror-error" data-typedoc-h="3"><span>error: Error & \{ code: -32022; data: \{ supported: string\[]; requested: string }; }</span><a href="#unsupportedprotocolversionerror-error" aria-label="Permalink" class="tsd-anchor-icon"><svg viewBox="0 0 24 24" aria-hidden="true"><use href="assets/icons.svg#icon-anchor" /></svg></a></div> </section>
</div>
## Content
<div class="type">
Cut at 300 lines. The page has the rest.
specification/2026-07-28/server/discover First recorded · 106 lines, first recorded
# Discovery ## Request ## Response ## When to Call ## Data Types ### DiscoverResult
The first capture of this source. The page was already there, and this is what it said.
# Discovery
<div id="enable-section-numbers" />
`server/discover` lets a client query a server's supported protocol versions,
capabilities, and identity before sending any other requests. Servers **MUST**
implement it.
## Request
The request carries no body parameters beyond the standard `_meta`:
```json theme={null}
{
"jsonrpc": "2.0",
"id": "discover-1",
"method": "server/discover",
"params": {
"_meta": {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientInfo": {
"name": "ExampleClient",
"version": "1.0.0"
},
"io.modelcontextprotocol/clientCapabilities": {}
}
}
}
```
## Response
The server replies with its supported protocol versions, capabilities, and
identity. This operation supports [caching](/specification/2026-07-28/server/utilities/caching).
```json theme={null}
{
"jsonrpc": "2.0",
"id": "discover-1",
"result": {
"resultType": "complete",
"supportedVersions": ["2026-07-28"],
"capabilities": {
"tools": {},
"resources": {}
},
"_meta": {
"io.modelcontextprotocol/serverInfo": {
"name": "ExampleServer",
"version": "1.0.0"
}
},
"instructions": "This server provides weather and resource utilities.",
"ttlMs": 3600000,
"cacheScope": "public"
}
}
```
## When to Call
Calling `server/discover` is optional for clients — a client may invoke any
RPC inline and handle
[`UnsupportedProtocolVersionError`](/specification/2026-07-28/schema#unsupportedprotocolversionerror)
if the server does not support the requested version. However, `server/discover`
is useful in two scenarios:
* **Presenting server information.** While a client doesn't need to call
`server/discover` to use the server, it's a convenient way to retrieve the
server's identity, capabilities, and supported versions in a single request.
For example, a client can present the capabilities a server supports from a
single `server/discover` response instead of probing with separate
`tools/list`, `prompts/list`, and `resources/list` requests.
* **stdio backward-compatibility probe.** On stdio, there is no per-request
HTTP status code to drive fallback. A client that supports both modern
(per-request `_meta`) and legacy (`initialize` handshake) servers **SHOULD**
send `server/discover` first; see
[stdio: Backward Compatibility](/specification/2026-07-28/basic/transports/stdio#backward-compatibility)
for the fallback rules.
See [Protocol Version Negotiation](/specification/2026-07-28/basic/versioning#protocol-version-negotiation)
for the full version-selection flow. For HTTP-specific status codes returned for
unknown methods, see the [Protocol Version Header](/specification/2026-07-28/basic/transports/streamable-http#protocol-version-header)
section in Transports.
## Data Types
### DiscoverResult
A discovery result includes:
* `supportedVersions`: Protocol versions the server supports. The client should
choose one of these for subsequent requests.
* `capabilities`: Capabilities the server supports (tools, resources, prompts,
etc.)
* `_meta['io.modelcontextprotocol/serverInfo']`: Name and version of the server
software. Servers **SHOULD** include this field.
* `instructions`: Optional natural-language guidance for LLMs on how to use
this server effectively
<Note>
`serverInfo` is self-reported by the server and is not verified by the
protocol. It is intended for display, logging, and debugging. Clients **SHOULD
NOT** use it to change their behavior, and **SHOULD NOT** rely on it for
security decisions.
</Note>
specification/2026-07-28/server/index First recorded · 29 lines, first recorded
# Overview
The first capture of this source. The page was already there, and this is what it said.
# Overview
Servers provide the fundamental building blocks for adding context to language models via
MCP. These primitives enable rich interactions between clients, servers, and language
models:
* **Prompts**: Pre-defined templates or instructions that guide language model
interactions
* **Resources**: Structured data or content that provides additional context to the model
* **Tools**: Executable functions that allow models to perform actions or retrieve
information
Each primitive can be summarized in the following control hierarchy:
| Primitive | Control | Description | Example |
| --------- | ---------------------- | -------------------------------------------------- | ------------------------------- |
| Prompts | User-controlled | Interactive templates invoked by user choice | Slash commands, menu options |
| Resources | Application-controlled | Contextual data attached and managed by the client | File contents, git history |
| Tools | Model-controlled | Functions exposed to the LLM to take actions | API POST requests, file writing |
Explore these key primitives in more detail below:
<CardGroup cols={3}>
<Card title="Prompts" icon="message" href="/specification/2026-07-28/server/prompts" />
<Card title="Resources" icon="file-lines" href="/specification/2026-07-28/server/resources" />
<Card title="Tools" icon="wrench" href="/specification/2026-07-28/server/tools" />
</CardGroup>
specification/2026-07-28/server/prompts First recorded · 334 lines, first recorded
# Prompts ## User Interaction Model ## Capabilities ## Protocol Messages ### Listing Prompts ### Getting a Prompt ### List Changed Notification ## Message Flow ## Data Types ### Prompt ### PromptMessage #### Text Content #### Image Content #### Audio Content #### Resource Links #### Embedded Resources ## Error Handling ## Implementation Considerations ## Security
The first capture of this source. The page was already there, and this is what it said.
# Prompts
<div id="enable-section-numbers" />
The Model Context Protocol (MCP) provides a standardized way for servers to expose prompt
templates to clients. Prompts allow servers to provide structured messages and
instructions for interacting with language models. Clients can discover available
prompts, retrieve their contents, and provide arguments to customize them.
<Note>
For brevity, the request examples on this page omit the `_meta` request
metadata (`io.modelcontextprotocol/protocolVersion`,
`io.modelcontextprotocol/clientInfo`, and
`io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
the required `_meta` fields; see
[`_meta`](/specification/2026-07-28/basic/index#meta).
</Note>
## User Interaction Model
Prompts are designed to be **user-controlled**, meaning they are exposed from servers to
clients with the intention of the user being able to explicitly select them for use.
This refers to who decides when the prompt is used, not who authors its content. Prompt
content is defined by the server.
Typically, prompts would be triggered through user-initiated commands in the user
interface, which allows users to naturally discover and invoke available prompts.
For example, as slash commands:
<img src="https://mintcdn.com/mcp/UAHvrCg8SwnAZwI3/specification/2026-07-28/server/slash-command.png?fit=max&auto=format&n=UAHvrCg8SwnAZwI3&q=85&s=7ed7762fc5e3b4b32cba2a71ede48000" alt="Example of prompt exposed as slash command" width="293" height="106" data-path="specification/2026-07-28/server/slash-command.png" />
However, implementors are free to expose prompts through any interface pattern that suits
their needs—the protocol itself does not mandate any specific user interaction
model.
## Capabilities
Servers that support prompts **MUST** declare the `prompts` capability in their
[`DiscoverResult`](/specification/2026-07-28/schema#discoverresult):
```json theme={null}
{
"capabilities": {
"prompts": {
"listChanged": true
}
}
}
```
`listChanged` indicates whether the server will emit notifications when the list of
available prompts changes.
Servers that declare the `prompts` capability **MUST** respond to `prompts/list` requests
with the set of prompts currently available to the requesting client. This set **MAY** be
empty and **MAY** change over time (see
[List Changed Notification](#list-changed-notification)), but **MUST NOT** vary
per-connection or as a side effect of other requests on the connection. The set
**MAY** vary by the authorization presented on the request — for example, returning
only the prompts the caller's granted scopes permit — since credentials are
per-request input, not connection state.
## Protocol Messages
### Listing Prompts
To retrieve available prompts, clients send a `prompts/list` request. This operation
supports [pagination](/specification/2026-07-28/server/utilities/pagination) and [caching](/specification/2026-07-28/server/utilities/caching).
**Request:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "prompts/list",
"params": {
"cursor": "optional-cursor-value"
}
}
```
**Response:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"resultType": "complete",
"prompts": [
{
"name": "code_review",
"title": "Request Code Review",
"description": "Asks the LLM to analyze code quality and suggest improvements",
"arguments": [
{
"name": "code",
"description": "The code to review",
"required": true
}
],
"icons": [
{
"src": "https://example.com/review-icon.svg",
"mimeType": "image/svg+xml",
"sizes": ["any"]
}
]
}
],
"nextCursor": "next-page-cursor",
"ttlMs": 600000,
"cacheScope": "public"
}
}
```
### Getting a Prompt
To retrieve a specific prompt, clients send a `prompts/get` request. Arguments may be
auto-completed through [the completion API](/specification/2026-07-28/server/utilities/completion).
**Request:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 2,
"method": "prompts/get",
"params": {
"name": "code_review",
"arguments": {
"code": "def hello():\n print('world')"
}
}
}
```
**Response:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"resultType": "complete",
"description": "Code review prompt",
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "Please review this Python code:\ndef hello():\n print('world')"
}
}
]
}
}
```
Servers **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.
### List Changed Notification
When the list of available prompts changes, servers that declared the `listChanged`
capability **SHOULD** send a notification to clients that have opened a
[`subscriptions/listen`](/specification/2026-07-28/basic/patterns/subscriptions) stream with
`promptsListChanged: true`:
```json theme={null}
{
"jsonrpc": "2.0",
"method": "notifications/prompts/list_changed"
}
```
## Message Flow
```mermaid theme={null}
sequenceDiagram
participant Client
participant Server
Note over Client,Server: Discovery
Client->>Server: prompts/list
Server-->>Client: List of prompts
Note over Client,Server: Usage
Client->>Server: prompts/get
Server-->>Client: Prompt content
opt listChanged
Client->>Server: subscriptions/listen (promptsListChanged: true)
Server--)Client: notifications/subscriptions/acknowledged
Note over Client,Server: Changes
Server--)Client: notifications/prompts/list_changed
Client->>Server: prompts/list
Server-->>Client: Updated prompts
end
```
## Data Types
### Prompt
A prompt definition includes:
* `name`: Unique identifier for the prompt
* `title`: Optional human-readable name of the prompt for display purposes.
* `description`: Optional human-readable description
* `icons`: Optional array of icons for display in user interfaces
* `arguments`: Optional list of arguments for customization
### PromptMessage
Messages in a prompt can contain:
* `role`: Either "user" or "assistant" to indicate the speaker
* `content`: One of the following content types:
<Note>
All content types in prompt messages support optional
[annotations](/specification/2026-07-28/server/resources#annotations) for
metadata about audience, priority, and modification times.
</Note>
#### Text Content
Text content represents plain text messages:
```json theme={null}
{
"type": "text",
"text": "The text content of the message"
}
```
This is the most common content type used for natural language interactions.
#### Image Content
Image content allows including visual information in messages:
```json theme={null}
{
"type": "image",
"data": "base64-encoded-image-data",
"mimeType": "image/png"
}
```
The image data **MUST** be base64-encoded and include a valid MIME type. This enables
multi-modal interactions where visual context is important.
#### Audio Content
Audio content allows including audio information in messages:
```json theme={null}
{
"type": "audio",
"data": "base64-encoded-audio-data",
"mimeType": "audio/wav"
}
```
The audio data MUST be base64-encoded and include a valid MIME type. This enables
multi-modal interactions where audio context is important.
#### Resource Links
Prompt messages **MAY** include links to
[Resources](/specification/2026-07-28/server/resources), to provide additional context or
data without embedding the resource contents directly. In this case, the prompt message
returns a URI that can be fetched by the client:
```json theme={null}
{
"type": "resource_link",
"uri": "file:///project/src/main.rs",
"name": "main.rs",
"description": "Primary application entry point",
"mimeType": "text/x-rust"
}
```
Resource links support the same [Resource annotations](/specification/2026-07-28/server/resources#annotations)
as regular resources to help clients understand how to use them.
#### Embedded Resources
Embedded resources allow referencing server-side resources directly in messages:
```json theme={null}
{
"type": "resource",
"resource": {
"uri": "resource://example",
Cut at 300 lines. The page has the rest.
specification/2026-07-28/server/resources First recorded · 434 lines, first recorded
# Resources ## User Interaction Model ## Capabilities ## Protocol Messages ### Listing Resources ### Reading Resources ### Resource Templates ### List Changed Notification ### Subscriptions ## Message Flow ## Data Types ### Resource ### Resource Contents #### Text Content #### Binary Content ### Annotations ## Common URI Schemes ### https\:// ### file:// ### git:// ### Custom URI Schemes ## Error Handling ## Security Considerations
The first capture of this source. The page was already there, and this is what it said.
# Resources
<div id="enable-section-numbers" />
The Model Context Protocol (MCP) provides a standardized way for servers to expose
resources to clients. Resources allow servers to share data that provides context to
language models, such as files, database schemas, or application-specific information.
Each resource is uniquely identified by a
[URI](https://datatracker.ietf.org/doc/html/rfc3986).
<Note>
For brevity, the request examples on this page omit the `_meta` request
metadata (`io.modelcontextprotocol/protocolVersion`,
`io.modelcontextprotocol/clientInfo`, and
`io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
the required `_meta` fields; see
[`_meta`](/specification/2026-07-28/basic/index#meta).
</Note>
## User Interaction Model
Resources in MCP are designed to be **application-driven**, with host applications
determining how to incorporate context based on their needs.
For example, applications could:
* Expose resources through UI elements for explicit selection, in a tree or list view
* Allow the user to search through and filter available resources
* Implement automatic context inclusion, based on heuristics or the AI model's selection
<img src="https://mintcdn.com/mcp/UAHvrCg8SwnAZwI3/specification/2026-07-28/server/resource-picker.png?fit=max&auto=format&n=UAHvrCg8SwnAZwI3&q=85&s=e2aa63c0e97d97eff5da87bdd3c2260e" alt="Example of resource context picker" width="174" height="181" data-path="specification/2026-07-28/server/resource-picker.png" />
However, implementations are free to expose resources through any interface pattern that
suits their needs—the protocol itself does not mandate any specific user
interaction model.
## Capabilities
Servers that support resources **MUST** declare the `resources` capability:
```json theme={null}
{
"capabilities": {
"resources": {
"listChanged": true,
"subscribe": true
}
}
}
```
The capability supports two optional features:
* `listChanged`: whether the server will emit notifications when the list of available
resources changes.
* `subscribe` : whether the server supports resource-specific update notifications
for resources requested through subscriptions/listen using the resourceSubscriptions
filter.
Servers may advertise either feature independently, together or neither.
Serves that support neither `listChanged` or `subscribe` may omit it:
```json theme={null}
{
"capabilities": {
"resources": {}
}
}
```
Servers that declare the `resources` capability **MUST** respond to `resources/list`
requests with the set of resources currently available to the requesting client. This set
**MAY** be empty and **MAY** change over time (see
[List Changed Notification](#list-changed-notification)), but **MUST NOT** vary
per-connection or as a side effect of other requests on the connection. The set
**MAY** vary by the authorization presented on the request — for example, returning
only the resources the caller's granted scopes permit — since credentials are
per-request input, not connection state.
## Protocol Messages
### Listing Resources
To discover available resources, clients send a `resources/list` request. This operation
supports [pagination](/specification/2026-07-28/server/utilities/pagination) and [caching](/specification/2026-07-28/server/utilities/caching).
**Request:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "resources/list",
"params": {
"cursor": "optional-cursor-value"
}
}
```
**Response:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"resultType": "complete",
"resources": [
{
"uri": "file:///project/src/main.rs",
"name": "main.rs",
"title": "Rust Software Application Main File",
"description": "Primary application entry point",
"mimeType": "text/x-rust",
"icons": [
{
"src": "https://example.com/rust-file-icon.png",
"mimeType": "image/png",
"sizes": ["48x48"]
}
]
}
],
"nextCursor": "next-page-cursor",
"ttlMs": 300000,
"cacheScope": "public"
}
}
```
### Reading Resources
To retrieve resource contents, clients send a `resources/read` request. This operation
supports [caching](/specification/2026-07-28/server/utilities/caching).
**Request:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 2,
"method": "resources/read",
"params": {
"uri": "file:///project/src/main.rs"
}
}
```
**Response:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"resultType": "complete",
"contents": [
{
"uri": "file:///project/src/main.rs",
"mimeType": "text/x-rust",
"text": "fn main() {\n println!(\"Hello world!\");\n}"
}
],
"ttlMs": 60000,
"cacheScope": "private"
}
}
```
Servers **MAY** return multiple resource contents in response to a single
`resources/read` request. For example, a server could return the contents of
several files when a directory resource is read.
Servers **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.
Alternatively, 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.
### Resource Templates
Resource templates allow servers to expose parameterized resources using
[URI templates](https://datatracker.ietf.org/doc/html/rfc6570). Arguments may be
auto-completed through [the completion API](/specification/2026-07-28/server/utilities/completion).
This operation supports [pagination](/specification/2026-07-28/server/utilities/pagination) and [caching](/specification/2026-07-28/server/utilities/caching).
**Request:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 3,
"method": "resources/templates/list",
"params": {
"cursor": "optional-cursor-value"
}
}
```
**Response:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"resultType": "complete",
"resourceTemplates": [
{
"uriTemplate": "file:///{path}",
"name": "Project Files",
"title": "📁 Project Files",
"description": "Access files in the project directory",
"mimeType": "application/octet-stream",
"icons": [
{
"src": "https://example.com/folder-icon.png",
"mimeType": "image/png",
"sizes": ["48x48"]
}
]
}
],
"nextCursor": "next-page-cursor",
"ttlMs": 300000,
"cacheScope": "public"
}
}
```
### List Changed Notification
When the list of available resources changes, servers that declared the `listChanged`
capability **SHOULD** send a notification:
```json theme={null}
{
"jsonrpc": "2.0",
"method": "notifications/resources/list_changed"
}
```
### Subscriptions
Clients subscribe to change notifications for specific resources by sending a
[`subscriptions/listen`][subscriptions-listen] request with the resource URIs listed in
`notifications.resourceSubscriptions`. The server delivers
`notifications/resources/updated` on the resulting stream whenever a watched resource
changes.
```json theme={null}
{
"jsonrpc": "2.0",
"method": "notifications/resources/updated",
"params": {
"_meta": { "io.modelcontextprotocol/subscriptionId": 4 },
"uri": "file:///project/src/main.rs"
}
}
```
See [Subscriptions][subscriptions] for the full protocol mechanics (acknowledgment,
`subscriptionId` correlation, and cancellation).
[subscriptions-listen]: /specification/2026-07-28/schema#subscriptionslistenrequest
[subscriptions]: /specification/2026-07-28/basic/patterns/subscriptions
## Message Flow
```mermaid theme={null}
sequenceDiagram
participant Client
participant Server
Note over Client,Server: Resource Discovery
Client->>Server: resources/list
Server-->>Client: List of resources
Note over Client,Server: Resource Template Discovery
Client->>Server: resources/templates/list
Server-->>Client: List of resource templates
Note over Client,Server: Resource Access
Client->>Server: resources/read
Server-->>Client: Resource contents
Note over Client,Server: Subscribe to changes
Client->>Server: subscriptions/listen (resourceSubscriptions)
Server--)Client: notifications/subscriptions/acknowledged
Note over Client,Server: Resource updated
Server--)Client: notifications/resources/updated
Client->>Server: resources/read
Server-->>Client: Updated contents
```
## Data Types
### Resource
Cut at 300 lines. The page has the rest.
specification/2026-07-28/server/tools First recorded · 793 lines, first recorded
# Tools ## User Interaction Model ## Capabilities ## Protocol Messages ### Listing Tools ### Calling Tools ### Input Required Tool Results ### List Changed Notification ## Message Flow ## Data Types ### Tool #### Tool Names #### x-mcp-header ### Tool Result #### Text Content #### Image Content #### Audio Content #### Resource Links #### Embedded Resources #### Structured Content #### Output Schema ### Schema Examples #### Tool with default 2020-12 schema: #### Tool with explicit draft-07 schema: #### Tool with no parameters: ## Stateful Tools ## Error Handling ## Security Considerations
The first capture of this source. The page was already there, and this is what it said.
# Tools
<div id="enable-section-numbers" />
The Model Context Protocol (MCP) allows servers to expose tools that can be invoked by
language models. Tools enable models to interact with external systems, such as querying
databases, calling APIs, or performing computations. Each tool is uniquely identified by
a name and includes metadata describing its schema.
<Note>
For brevity, the request examples on this page omit the `_meta` request
metadata (`io.modelcontextprotocol/protocolVersion`,
`io.modelcontextprotocol/clientInfo`, and
`io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
the required `_meta` fields; see
[`_meta`](/specification/2026-07-28/basic/index#meta).
</Note>
## User Interaction Model
Tools in MCP are designed to be **model-controlled**, meaning that the language model can
discover and invoke tools automatically based on its contextual understanding and the
user's prompts.
However, implementations are free to expose tools through any interface pattern that
suits their needs—the protocol itself does not mandate any specific user
interaction model.
<Warning>
For trust & safety and security, there **SHOULD** always
be a human in the loop with the ability to deny tool invocations.
Applications **SHOULD**:
* Provide UI that makes clear which tools are being exposed to the AI model
* Insert clear visual indicators when tools are invoked
* Present confirmation prompts to the user for operations, to ensure a human is in the
loop
</Warning>
## Capabilities
Servers that support tools **MUST** declare the `tools` capability:
```json theme={null}
{
"capabilities": {
"tools": {
"listChanged": true
}
}
}
```
`listChanged` indicates whether the server will emit notifications when the list of
available tools changes.
Servers that declare the `tools` capability **MUST** respond to `tools/list` requests
with the set of tools currently available to the requesting client. This set **MAY** be
empty and **MAY** change over time (see
[List Changed Notification](#list-changed-notification)), but **MUST NOT** vary
per-connection or as a side effect of other requests on the connection. The set
**MAY** vary by the authorization presented on the request — for example, returning
only the tools the caller's granted scopes permit — since credentials are
per-request input, not connection state.
Servers **SHOULD** return tools in a deterministic order (i.e., the same ordering across
requests when the underlying set of tools has not changed). Deterministic ordering enables
clients to reliably cache the tool list and improves LLM prompt cache hit rates when tools
are included in model context.
## Protocol Messages
### Listing Tools
To discover available tools, clients send a `tools/list` request. This operation supports
[pagination](/specification/2026-07-28/server/utilities/pagination) and [caching](/specification/2026-07-28/server/utilities/caching).
**Request:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list",
"params": {
"cursor": "optional-cursor-value"
}
}
```
**Response:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"resultType": "complete",
"tools": [
{
"name": "get_weather",
"title": "Weather Information Provider",
"description": "Get current weather information for a location",
"inputSchema": {
"type": "object",
"properties": {
"location": {
"type": "string",
"description": "City name or zip code"
}
},
"required": ["location"]
},
"icons": [
{
"src": "https://example.com/weather-icon.png",
"mimeType": "image/png",
"sizes": ["48x48"]
}
]
}
],
"nextCursor": "next-page-cursor",
"ttlMs": 300000,
"cacheScope": "public"
}
}
```
### Calling Tools
To invoke a tool, clients send a `tools/call` request:
**Request:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": {
"location": "New York"
}
}
}
```
**Response:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"resultType": "complete",
"content": [
{
"type": "text",
"text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy"
}
],
"isError": false
}
}
```
### Input Required Tool Results
Servers **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.
When retrying the request with input responses, clients include `inputResponses` and, if provided by the server, `requestState` in the request parameters:
**Input Required Response:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"resultType": "input_required",
"inputRequests": {
"github_login": {
"method": "elicitation/create",
"params": {
"mode": "form",
"message": "Please provide your GitHub username",
"requestedSchema": {
"type": "object",
"properties": {
"name": { "type": "string" }
},
"required": ["name"]
}
}
}
},
"requestState": "eyJsb2NhdGlvbiI6Ik5ldyBZb3JrIn0..."
}
}
```
**Retry with Input Responses:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": {
"location": "New York"
},
"inputResponses": {
"github_login": {
"action": "accept",
"content": {
"name": "octocat"
}
}
},
"requestState": "eyJsb2NhdGlvbiI6Ik5ldyBZb3JrIn0..."
}
}
```
Note that the JSON-RPC `id` **MUST** be different between the initial request and the retry.
### List Changed Notification
When the list of available tools changes, servers that declared the `listChanged`
capability **SHOULD** send a notification to clients that have opened a
[`subscriptions/listen`](/specification/2026-07-28/basic/patterns/subscriptions) stream with
`toolsListChanged: true`:
```json theme={null}
{
"jsonrpc": "2.0",
"method": "notifications/tools/list_changed"
}
```
## Message Flow
```mermaid theme={null}
sequenceDiagram
participant LLM
participant Client
participant Server
Note over Client,Server: Discovery
Client->>Server: tools/list
Server-->>Client: List of tools
Note over Client,LLM: Tool Selection
LLM->>Client: Select tool to use
Note over Client,Server: Invocation
Client->>Server: tools/call
Server-->>Client: Tool result
Client->>LLM: Process result
opt listChanged
Client->>Server: subscriptions/listen (toolsListChanged: true)
Server--)Client: notifications/subscriptions/acknowledged
Note over Client,Server: Updates
Server--)Client: notifications/tools/list_changed
Client->>Server: tools/list
Server-->>Client: Updated tools
end
```
## Data Types
### Tool
A tool definition includes:
* `name`: Unique identifier for the tool
* `title`: Optional human-readable name of the tool for display purposes.
* `description`: Human-readable description of functionality
* `icons`: Optional array of icons for display in user interfaces
* `inputSchema`: JSON Schema defining expected parameters
* Follows the [JSON Schema usage guidelines](/specification/2026-07-28/basic#json-schema-usage)
* Defaults to 2020-12 if no `$schema` field is present
* **MUST** be a valid JSON Schema object (not `null`)
* For tools with no parameters, use one of these valid approaches:
* `{ "type": "object", "additionalProperties": false }` - **Recommended**: explicitly accepts only empty objects
* `{ "type": "object" }` - accepts any object (including with properties)
* Properties **MAY** include an [`x-mcp-header`](#x-mcp-header) annotation to expose
parameter values as HTTP headers
* `outputSchema`: Optional JSON Schema defining expected output structure
* Follows the [JSON Schema usage guidelines](/specification/2026-07-28/basic#json-schema-usage)
* Defaults to 2020-12 if no `$schema` field is present
* `annotations`: Optional properties describing tool behavior
<Warning>
Cut at 300 lines. The page has the rest.
specification/2026-07-28/server/utilities/caching First recorded · 177 lines, first recorded
# Caching ## Cacheable Results ## Cache Key ## Cacheable Model ### Time-to-Live (TTL) Field #### Freshness Calculation ### Cache Scope Field #### Choosing a Cache Scope ## Interaction with Notifications ## Interaction with Pagination ## Security Considerations
The first capture of this source. The page was already there, and this is what it said.
# Caching
<div id="enable-section-numbers" />
The Model Context Protocol (MCP) supports caching for some results. This allows clients to cache responses and reduce unnecessary re-fetching.
Caching is complementary to [change notifications](#interaction-with-notifications)—both
mechanisms can coexist.
## Cacheable Results
Servers MUST include caching hints on results with `resultType: "complete"` returned by
the following operations:
* `server/discover`
* `tools/list`
* `prompts/list`
* `resources/list`
* `resources/templates/list`
* `resources/read`
Interim results with `resultType: "input_required"` (see
[multi round-trip requests](/specification/2026-07-28/basic/patterns/mrtr)) are not cacheable
and carry no caching hints.
## Cache Key
A cached response is identified by the request method together with the request
parameters that affect the result (for example, the `uri` for `resources/read`, or the
`cursor` for paginated list requests). Clients **MUST NOT** serve a cached response for
a request whose method or parameters differ from the request that produced it.
Results produced by retrying a request through the
[multi round-trip requests](/specification/2026-07-28/basic/patterns/mrtr) mechanism—that
is, requests carrying `inputResponses` or `requestState`—**MUST NOT** be cached,
as they depend on inputs that are not part of the cache key.
## Cacheable Model
Cacheable Results in MCP use two fields to provide caching hints to clients:
* The <b>Time-to-live (TTL) Field</b>,`ttlMs`, is an integer value in milliseconds specifying how long the client MAY consider the result fresh.
* The <b>Cache Scope Field</b>,`cacheScope`, indicates the intended scope of the cached response, either `"public"` or `"private"`.
### Time-to-Live (TTL) Field
The `ttlMs` field is a hint from the server indicating how long, in
milliseconds, the client MAY consider the result fresh. Semantics are
analogous to HTTP `Cache-Control: max-age`.
* If `ttlMs` is `0`, the response **SHOULD** be considered immediately stale. The client
MAY re-fetch every time the result is needed.
* If `ttlMs` is positive, the client **SHOULD** consider the result fresh for that many
milliseconds after receiving the response.
* If `ttlMs` is absent, clients **SHOULD** assume a default of `0` (immediately stale)
and rely on their own caching heuristics or notifications. This should only occur in older server versions.
* If `ttlMs` is negative, clients **SHOULD** ignore it and treat it as `0`.
Servers **MUST** provide a `ttlMs` value that is `>= 0`.
<Note>
TTL is a **freshness hint**, not a guarantee. Servers MAY change the
underlying data before the TTL expires. The TTL tells the client how long it
can reasonably avoid re-fetching, not how long the data is guaranteed to
remain unchanged.
</Note>
#### Freshness Calculation
A client records the local time at which the response was received (`t_received`). The
response is considered **fresh** while:
```
now < t_received + ttlMs
```
Once the TTL expires, the response is **stale** and the client **SHOULD** re-fetch on
next access.
Clients **SHOULD NOT** treat TTL as a polling interval that triggers automatic background
refetches. The TTL is a freshness hint: the client checks freshness when it needs the
data, and re-fetches only if stale. Implementations that do choose to poll **MUST**
apply jitter and backoff.
Clients **MAY** re-fetch before the TTL expires if they have reason to believe the data
has changed (e.g., receiving an unexpected error on a tool call indicating the method was
not found or the parameters were invalid).
Clients **MAY** serve stale responses if errors occur during re-fetching (e.g., network
issues, server downtime).
### Cache Scope Field
The `cacheScope` field controls who may cache a response, analogous to HTTP
`Cache-Control: public` vs `Cache-Control: private`.
| Value | Meaning |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"public"` | The response does not contain user-specific data. Any client, shared gateway, or caching proxy **MAY** store and serve the cached response to any user. |
| `"private"` | The response contains private data that is not meant to be shared between callers. Cached responses **MAY** be reused for the same authorization context. Caches **MUST NOT** be shared across authorization contexts (e.g. a different access token requires a different cache). |
#### Choosing a Cache Scope
* **`"public"`** is appropriate for lists of tools, prompts, and resource templates when
they are identical for all users.
* **`"private"`** is appropriate for `resources/read` results that depend on the
authenticated user, or for filtered list results that vary per user.
## Interaction with Notifications
TTL and server-push notifications are complementary:
* A server **MAY** provide `ttlMs` without advertising `listChanged: true` in its
capabilities. In this case, the client relies entirely on TTL-based freshness.
* A server **MAY** advertise `listChanged: true` **and** provide `ttlMs`. In this case,
the client can use the TTL to avoid unnecessary refetches between notifications, and
the notification acts as an immediate invalidation signal.
When a relevant notification is received while a cached response is still fresh, the
notification **invalidates** the cached response and it should be considered immediately stale.
```mermaid theme={null}
sequenceDiagram
participant Client
participant Server
Client->>Server: tools/list
Server-->>Client: { tools: [...], ttlMs: 300000 }
Note over Client: Cache response, fresh for 5 min
Note over Client: 2 minutes later...
Client->>Client: Need tools list → cache still fresh, use cached
Note over Client: 3 minutes later (TTL expired)...
Client->>Client: Need tools list → cache stale
Client->>Server: tools/list
Server-->>Client: { tools: [...], ttlMs: 300000 }
Note over Server: Tools change before TTL expires
Server-->>Client: notifications/tools/list_changed
Note over Client: Invalidate cache immediately
Client->>Server: tools/list
Server-->>Client: { tools: [...], ttlMs: 300000 }
```
## Interaction with Pagination
When a list result is [paginated](/specification/2026-07-28/server/utilities/pagination), each
page is an independently cacheable response—consistent with how HTTP
`Cache-Control` treats paginated resources.
* Each page response carries its own `ttlMs` value. The freshness clock for each page
starts at the time that page was received.
* Servers **MAY** return different `ttlMs` values on different pages (e.g., a longer TTL
for early pages of a stable list, a shorter TTL for the final page).
* When a cached page expires, the client **SHOULD** re-fetch that page using its cursor.
* There is no cross-page consistency guarantee. If the underlying data changes between
page fetches, clients may observe duplicates or gaps.
* Clients that require a consistent snapshot of the full list **SHOULD** re-fetch from
the beginning (without a cursor).
* If a cursor becomes invalid (e.g., the server returns an error for a previously valid
cursor), the client **SHOULD** discard all cached pages and re-fetch from the
beginning.
Servers **MUST** apply the same `cacheScope` to all response pages for a given list
request. For example, if the first page of a `tools/list` response has
`cacheScope: "private"`, all subsequent pages for that request **MUST** also be
`"private"`.
## Security Considerations
A `cacheScope` of `"public"` indicates that the response does not contain user-specific data and can be safely shared. Servers MUST be aware that responses with a `"public"` `cacheScope` may be shared between callers even if the Result is coming from an authenticated endpoint. For example, the Result from an authenticated `tools/list` call with a `"public"` `cacheScope` may be cached by a client and may be shared outside of the initial requests authorization context. (i.e. different access tokens can leverage the same cache).
Server implementors:
* should ensure that the `cacheScope` correctly reflects the intended visibility of the primitive.
* MUST apply appropriate per-primitive access controls, and MUST NOT rely on
`cacheScope` alone to prevent unauthorized access to primitives.
specification/2026-07-28/server/utilities/completion First recorded · 212 lines, first recorded
# Completion ## User Interaction Model ## Capabilities ## Protocol Messages ### Requesting Completions ### Reference Types ### Completion Results ## Message Flow ## Data Types ### CompleteRequest ### CompleteResult ## Error Handling ## Implementation Considerations ## Security
The first capture of this source. The page was already there, and this is what it said.
# Completion
<div id="enable-section-numbers" />
The Model Context Protocol (MCP) provides a standardized way for servers to offer
autocompletion suggestions for the arguments of prompts and resource templates. When
users are filling in argument values for a specific prompt (identified by name) or
resource template (identified by URI), servers can provide contextual suggestions.
<Note>
For brevity, the request examples on this page omit the `_meta` request
metadata (`io.modelcontextprotocol/protocolVersion`,
`io.modelcontextprotocol/clientInfo`, and
`io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
the required `_meta` fields; see
[`_meta`](/specification/2026-07-28/basic/index#meta).
</Note>
## User Interaction Model
Completion in MCP is designed to support interactive user experiences similar to IDE code
completion.
For example, applications may show completion suggestions in a dropdown or popup menu as
users type, with the ability to filter and select from available options.
However, implementations are free to expose completion through any interface pattern that
suits their needs—the protocol itself does not mandate any specific user
interaction model.
## Capabilities
Servers that support completions **MUST** declare the `completions` capability:
```json theme={null}
{
"capabilities": {
"completions": {}
}
}
```
## Protocol Messages
### Requesting Completions
To get completion suggestions, clients send a `completion/complete` request specifying
what is being completed through a reference type:
**Request:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "completion/complete",
"params": {
"ref": {
"type": "ref/prompt",
"name": "code_review"
},
"argument": {
"name": "language",
"value": "py"
}
}
}
```
**Response:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"resultType": "complete",
"completion": {
"values": ["python", "pytorch", "pyside"],
"total": 10,
"hasMore": true
}
}
}
```
For prompts or URI templates with multiple arguments, clients should include previous completions in the `context.arguments` object to provide context for subsequent requests.
**Request:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "completion/complete",
"params": {
"ref": {
"type": "ref/prompt",
"name": "code_review"
},
"argument": {
"name": "framework",
"value": "fla"
},
"context": {
"arguments": {
"language": "python"
}
}
}
}
```
**Response:**
```json theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"resultType": "complete",
"completion": {
"values": ["flask"],
"total": 1,
"hasMore": false
}
}
}
```
### Reference Types
The protocol supports two types of completion references:
| Type | Description | Example |
| -------------- | ----------------------------------------- | --------------------------------------------------- |
| `ref/prompt` | References a prompt by name | `{"type": "ref/prompt", "name": "code_review"}` |
| `ref/resource` | References a resource URI or URI template | `{"type": "ref/resource", "uri": "file:///{path}"}` |
### Completion Results
Servers return an array of completion values ranked by relevance, with:
* Maximum 100 items per response
* Optional total number of available matches
* Boolean indicating if additional results exist
## Message Flow
```mermaid theme={null}
sequenceDiagram
participant Client
participant Server
Note over Client: User types argument
Client->>Server: completion/complete
Server-->>Client: Completion suggestions
Note over Client: User continues typing
Client->>Server: completion/complete
Server-->>Client: Refined suggestions
```
## Data Types
### CompleteRequest
* `ref`: A `PromptReference` or `ResourceTemplateReference`. For
`ResourceTemplateReference`, `uri` is a URI or URI template.
* `argument`: Object containing:
* `name`: Argument name
* `value`: Current value
* `context`: Object containing:
* `arguments`: A mapping of already-resolved argument names to their values.
### CompleteResult
* `completion`: Object containing:
* `values`: Array of suggestions (max 100)
* `total`: Optional total matches
* `hasMore`: Additional results flag
## Error Handling
Servers **SHOULD** return standard JSON-RPC errors for common failure cases:
* Method not found: `-32601` (Capability not supported)
* Invalid prompt name: `-32602` (Invalid params)
* Missing required arguments: `-32602` (Invalid params)
* Internal errors: `-32603` (Internal error)
## Implementation Considerations
1. Servers **SHOULD**:
* Return suggestions sorted by relevance
* Implement fuzzy matching where appropriate
* Rate limit completion requests
* Validate all inputs
2. Clients **SHOULD**:
* Debounce rapid completion requests
* Cache completion results where appropriate
* Handle missing or partial results gracefully
## Security
Implementations **MUST**:
* Validate all completion inputs
* Implement appropriate rate limiting
* Control access to sensitive suggestions
* Prevent completion-based information disclosure
specification/2026-07-28/server/utilities/logging First recorded · 130 lines, first recorded
# Logging ## User Interaction Model ## Capabilities ## Log Levels ## Requesting Log Messages ### Per-request log level ## Protocol Messages ### Log Message Notifications ## Error Handling ## Implementation Considerations ## Security
The first capture of this source. The page was already there, and this is what it said.
# Logging
<div id="enable-section-numbers" />
<Warning>
**Deprecated**: The Logging feature is deprecated as of protocol version
`2026-07-28`
([SEP-2577](https://github.com/modelcontextprotocol/modelcontextprotocol/pull/2577)).
Under the [feature lifecycle policy](/community/feature-lifecycle), it remains
in the specification for at least twelve months after this revision's release
before it becomes eligible for removal. New implementations **SHOULD NOT**
adopt it; existing implementations **SHOULD** migrate to logging to `stderr`
for stdio transports, or to [OpenTelemetry](https://opentelemetry.io/) for
structured observability. See the [deprecated features
registry](/specification/2026-07-28/deprecated).
</Warning>
The Model Context Protocol (MCP) provides a standardized way for servers to send
structured log messages to clients. Clients control logging verbosity per-request via
`_meta`, with servers sending notifications containing severity levels, optional logger
names, and arbitrary JSON-serializable data.
## User Interaction Model
Implementations are free to expose logging through any interface pattern that suits their
needs—the protocol itself does not mandate any specific user interaction model.
## Capabilities
Servers that emit log message notifications **MUST** declare the `logging` capability:
```json theme={null}
{
"capabilities": {
"logging": {}
}
}
```
## Log Levels
The protocol follows the standard syslog severity levels specified in
[RFC 5424](https://datatracker.ietf.org/doc/html/rfc5424#section-6.2.1):
| Level | Description | Example Use Case |
| --------- | -------------------------------- | -------------------------- |
| debug | Detailed debugging information | Function entry/exit points |
| info | General informational messages | Operation progress updates |
| notice | Normal but significant events | Configuration changes |
| warning | Warning conditions | Deprecated feature usage |
| error | Error conditions | Operation failures |
| critical | Critical conditions | System component failures |
| alert | Action must be taken immediately | Data corruption detected |
| emergency | System is unusable | Complete system failure |
## Requesting Log Messages
### Per-request log level
To receive log messages for a specific request, include
`io.modelcontextprotocol/logLevel` in the request's `_meta`. The server **MUST NOT**
emit `notifications/message` for a request that does not include this field.
When the field is present, the server **MAY** send `notifications/message`
notifications at or above the requested level on the response stream of that
request, before the final response. `notifications/message` is request-scoped:
the server **MUST NOT** deliver it on a
[`subscriptions/listen`](/specification/2026-07-28/basic/patterns/subscriptions)
stream or on any stream other than the one carrying the response to the request
that set the log level.
## Protocol Messages
### Log Message Notifications
Servers send log messages using `notifications/message` notifications:
```json theme={null}
{
"jsonrpc": "2.0",
"method": "notifications/message",
"params": {
"level": "error",
"logger": "database",
"data": {
"error": "Connection failed",
"details": {
"host": "localhost",
"port": 5432
}
}
}
}
```
## Error Handling
If the `io.modelcontextprotocol/logLevel` value carried in a request's `_meta`
is not a recognized [log level](#log-levels), the server **SHOULD** reject that
request with a standard JSON-RPC error:
* Invalid log level: `-32602` (Invalid params)
* Internal errors: `-32603` (Internal error)
## Implementation Considerations
1. Servers **SHOULD**:
* Rate limit log messages
* Include relevant context in data field
* Use consistent logger names
* Remove sensitive information
2. Clients **MAY**:
* Present log messages in the UI
* Implement log filtering/search
* Display severity visually
* Persist log messages
## Security
1. Log messages **MUST NOT** contain:
* Credentials or secrets
* Personal identifying information
* Internal system details that could aid attacks
2. Implementations **SHOULD**:
* Rate limit messages
* Validate all data fields
* Control log access
* Monitor for sensitive content
specification/2026-07-28/server/utilities/pagination First recorded · 109 lines, first recorded
# Pagination ## Pagination Model ## Response Format ## Request Format ## Pagination Flow ## Operations Supporting Pagination ## Implementation Guidelines ## Error Handling
The first capture of this source. The page was already there, and this is what it said.
# Pagination
<div id="enable-section-numbers" />
The Model Context Protocol (MCP) supports paginating list operations that may return
large result sets. Pagination allows servers to yield results in smaller chunks rather
than all at once.
Pagination is especially important when connecting to external services over the
internet, but also useful for local integrations to avoid performance issues with large
data sets.
<Note>
For brevity, the request examples on this page omit the `_meta` request
metadata (`io.modelcontextprotocol/protocolVersion`,
`io.modelcontextprotocol/clientInfo`, and
`io.modelcontextprotocol/clientCapabilities`). Every request **MUST** include
the required `_meta` fields; see
[`_meta`](/specification/2026-07-28/basic/index#meta).
</Note>
## Pagination Model
Pagination in MCP uses an opaque cursor-based approach, instead of numbered pages.
* The **cursor** is an opaque string token, representing a position in the result set
* **Page size** is determined by the server, and clients **MUST NOT** assume a fixed page
size
## Response Format
Pagination starts when the server sends a **response** that includes:
* The current page of results
* An optional `nextCursor` field if more results exist
```json theme={null}
{
"jsonrpc": "2.0",
"id": "123",
"result": {
"resultType": "complete",
"resources": [...],
"nextCursor": "eyJwYWdlIjogM30=",
"ttlMs": 300000,
"cacheScope": "public"
}
}
```
## Request Format
After receiving a cursor, the client can *continue* paginating by issuing a request
including that cursor:
```json theme={null}
{
"jsonrpc": "2.0",
"id": "124",
"method": "resources/list",
"params": {
"cursor": "eyJwYWdlIjogMn0="
}
}
```
## Pagination Flow
```mermaid theme={null}
sequenceDiagram
participant Client
participant Server
Client->>Server: List Request (no cursor)
loop Pagination Loop
Server-->>Client: Page of results + nextCursor
Client->>Server: List Request (with cursor)
end
```
## Operations Supporting Pagination
The following MCP operations support pagination:
* `resources/list` - List available resources
* `resources/templates/list` - List resource templates
* `prompts/list` - List available prompts
* `tools/list` - List available tools
## Implementation Guidelines
1. Servers **SHOULD**:
* Provide stable cursors
* Handle invalid cursors gracefully
2. Clients **SHOULD**:
* Treat a missing `nextCursor` as the end of results
* Support both paginated and non-paginated flows
3. Clients **MUST** treat cursors as opaque tokens:
* Don't make assumptions about cursor format
* Don't attempt to parse or modify cursors
* Don't make any determination based on cursor value other than whether a
non-null value was provided (e.g. an empty string is a valid cursor and
thus **MUST NOT** be treated as the end of results)
## Error Handling
Invalid cursors **SHOULD** result in an error with code -32602 (Invalid params).