Skip to main content

Documentation Index

Fetch the complete documentation index at: https://modelcontextprotocol.io/llms.txt

Use this file to discover all available pages before exploring further.

This document lists changes made to the Model Context Protocol (MCP) specification since the previous revision, 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).
  2. Make MCP stateless: remove the initialize/notifications/initialized handshake. Every request now carries its protocol version, client identity, and client capabilities in _meta (io.modelcontextprotocol/protocolVersion, io.modelcontextprotocol/clientInfo, io.modelcontextprotocol/clientCapabilities). Version mismatches return UnsupportedProtocolVersionError (SEP-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).
  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).
  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).
  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).
  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 inputRequests, a new resultType containing the additional information needed to process the request. Clients respond with inputResponses on the next request providing the requested information. (SEP-2322).

​
Minor changes

  1. Add extensions field to ClientCapabilities and ServerCapabilities to support optional extensions beyond the core protocol.
  2. Document OpenTelemetry trace context propagation conventions for _meta keys (traceparent, tracestate, baggage) (SEP-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).
  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).
  6. Change resource not found error code from -32002 to -32602 (Invalid Params) to align with JSON-RPC specification.

​
Deprecated

Features listed here remain part of the specification but are scheduled for removal under the feature lifecycle and deprecation policy. New implementations should not adopt them. The deprecated features registry tracks every feature currently in the Deprecated state.
  1. Deprecate the Roots, Sampling, and Logging features (SEP-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). Migrate to Streamable HTTP.
  3. Reclassify the includeContext values "thisServer" and "allServers" (soft-deprecated since protocol version 2025-11-25) as Deprecated (SEP-2596). Omit the field or use "none"; these values will be removed no later than the Sampling feature itself.

​
Other schema changes

  1. schema.json now correctly reflects that the Typescript definition of wminimum/maximum/default are number’s and not just integers. This was casued by using the generator using --defaultNumberType integer (PR#2710).

​
Governance and process updates

  1. Adopt a specification feature lifecycle and deprecation policy defining the Active, Deprecated, and Removed feature states, a minimum twelve-month deprecation window, and a registry of deprecated features (SEP-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).

​
Full changelog

For a complete list of all changes that have been made since the last protocol revision, see GitHub.