Docs / Revisions

Spec revisions

Five revisions of the Model Context Protocol, each served as its spec defines it. What differs between revisions differs on the wire too — so a client that handles only one of them shows it here, not in production.

At a glance

A few of the differences the mock reproduces. Every message it sends is validated in its test suite against the official schema.json of its revision.

2024-11-052025-03-262025-06-182025-11-252026-07-28
TransportHTTP+SSEStreamable HTTPStreamable HTTPStreamable HTTPStreamable HTTP, stateless
Handshakeinitializeinitializeinitializeinitializenone: _meta on every request, server/discover
JSON-RPC batchesnoyesnonono
Structured content, resource links, titlesnonoyesyesyes
Tool annotationsnoyesyesyesyes
Invalid tool argumentsprotocol errorprotocol errorprotocol errorisError resultisError result
Resource not found-32002-32002-32002-32002-32602
Progress messagenoyesyesyesyes
Elicitation (delete_file)nonononoyes, multi round-trip

The legacy revisions are served without sessions, which the spec allows, so they keep no state between requests. The one piece of state in the whole mock is the open stream of a 2024-11-05 SSE connection, forgotten when it closes.

Legacy revisions

The initialize era, from 2024-11-05 to 2025-11-25.

2025-11-25 — /2025-11-25/mcp

initialize always answers with its own version, as the spec's negotiation prescribes for a version it does not support. Notifications and posted responses get 202; a MCP-Protocol-Version header naming another version gets 400. GET and DELETE answer 405, since there is no server stream and no session to end. Arguments that break a tool's input schema are a tool execution error (isError: true).

2025-06-18 — /2025-06-18/mcp

The same server with two differences of its own: invalid tool arguments are a JSON-RPC -32602 protocol error, as this revision lists them, and an error whose request id cannot be read carries id: null, as JSON-RPC 2.0 and the official SDK server send it.

2025-03-26 — /2025-03-26/mcp

Accepts JSON-RPC batches, as the revision requires: requests are answered with an array of responses in order, a malformed element gets its own error without failing the rest, notifications and responses alone get 202, and initialize is refused inside a batch. The catalog comes in this revision's vocabulary: no outputSchema, structuredContent or resource_link, and title moves into annotations.title.

[
  { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "add", "arguments": { "a": 1, "b": 2 } } },
  { "jsonrpc": "2.0", "id": 2, "method": "prompts/list" }
]
// → [ { "id": 1, "result": … }, { "id": 2, "result": … } ]

2024-11-05 — /2024-11-05/sse

The deprecated HTTP+SSE transport. The first event names the message endpoint, POSTs are answered 202 Accepted, and every response travels on the stream as a message event. Tools come without annotations or titles, which this revision did not have. Plain-text answers and error bodies follow the official SDK's SSE server.

The same transport is also served at the root, /sse and /messages, next to /mcp, as the spec suggests for servers that keep serving 2024-11-05 clients. Over it, initialize negotiates any legacy revision, and the session remembers the one negotiated.

2026-07-28

The stateless revision, at /2026-07-28/mcp and at /mcp. No handshake and no session: each request carries its protocol version and client capabilities in _meta.

_meta key
io.modelcontextprotocol/protocolVersionRequired. "2026-07-28"
io.modelcontextprotocol/clientCapabilitiesRequired. An object, e.g. { "elicitation": { "form": {} } }
io.modelcontextprotocol/clientInfoOptional. { name, version }
io.modelcontextprotocol/logLevelOptional. A logging level

Every result carries resultType and the server identity in _meta["io.modelcontextprotocol/serverInfo"]. server/discover advertises the capabilities, and list results carry cache hints (ttlMs, cacheScope):

{
  "supportedVersions": ["2026-07-28"],
  "capabilities": {
    "tools": { "listChanged": true },
    "resources": { "listChanged": true, "subscribe": true },
    "prompts": { "listChanged": true },
    "extensions": { "io.modelcontextprotocol/tasks": {} }
  },
  "ttlMs": 3600000, "cacheScope": "public", "resultType": "complete",
  "_meta": { "io.modelcontextprotocol/serverInfo": { "name": "mcp-mock", "version": "0.1.0" } }
}

Request validation

The standard headers mirror the body so intermediaries can route without parsing it: MCP-Protocol-Version, Mcp-Method, and Mcp-Name for tools/call, prompts/get, resources/read and the tasks/* methods. Values that are not plain ASCII travel as =?base64?…?=. Requests are checked in the same order as the official SDK server, and each failure gets the HTTP status and code the spec assigns:

#CheckFailure
1JSON-RPC shape (batches and posted responses refused)400 · -32600
2Era: legacy traffic, like an initialize400 · -32022 listing the versions served
3The _meta envelope400 · -32602
4Header/body agreement (version, Mcp-Method)400 · -32020
5Supported version400 · -32022
6Standard headers present, Mcp-Name matching400 · -32020
7Method exists404 · -32601

Past these checks, errors from the method itself travel in-band with HTTP 200, except those the spec ties to a status — -32021, a missing client capability, is 400. GET and DELETE answer 405, and a session id is ignored and never minted.

Multi round-trip requests

On 2026-07-28 a server that needs input from the user does not call the client back: it answers input_required, and the client retries with the answers. The mock keeps it stateless.

delete_file asks for confirmation with a form elicitation. The official SDK fulfils input_required with your elicitation handler and retries the call by itself:

const client = new Client(info, {
  versionNegotiation: { mode: { pin: "2026-07-28" } },
  capabilities: { elicitation: { form: {} } },
});
client.setRequestHandler("elicitation/create", () => ({ action: "accept", content: { confirm: true } }));

await client.callTool({ name: "delete_file", arguments: { path: "/tmp/old.log" } });
// asked: "Delete /tmp/old.log? This cannot be undone."
// → structuredContent: { path: "/tmp/old.log", deleted: true }
  • Declining, cancelling, or accepting without confirm: true returns isError: true — Deletion cancelled: /tmp/old.log was not deleted.
  • The requestState binds the confirmation to the file, so it cannot be replayed on another path.
  • A client that does not declare form elicitation gets -32021 (MissingRequiredClientCapabilityError, HTTP 400).

To test any other round trip, force one with _meta["com.mcp-mock/input-required"] on any tools/call. Its retry returns what your client answered, unless the request also forces a result with com.mcp-mock/response. See Forcing input_required.

Progress & cancellation

simulate_work really waits between steps, so progress, timeouts and cancellation all have something to act on.

A request with _meta.progressToken gets notifications/progress for each step, then its result:

await client.callTool(
  { name: "simulate_work", arguments: { steps: 2, step_ms: 10 } },
  { onprogress: (p) => console.log(p) },
);
// { progress: 1, total: 2, message: "Step 1 of 2" }
// { progress: 2, total: 2, message: "Step 2 of 2" }
// → structuredContent: { steps: 2, completed: true }

On Streamable HTTP the response turns into an SSE stream only once there is progress to send, so a request that reports none — or an error tied to an HTTP status such as -32021 — still gets a plain JSON response. On the 2024-11-05 transport the notifications travel on the session stream, without message, which that revision did not have.

TransportCancellation
2026-07-28Closing the response stream cancels the request: the server stops and sends nothing more.
2024-11-05 SSEnotifications/cancelled cancels a running request of the same session, which is never answered.
Legacy Streamable HTTPWithout sessions to pair it with a request, notifications/cancelled is accepted and ignored, as the spec allows. A dropped connection is not taken as a cancellation, as those revisions require.

Subscriptions

The catalog never changes on its own, so a test scripts the changes its client should see with _meta["com.mcp-mock/notifications"].

On 2026-07-28, subscriptions/listen opens a long-lived SSE stream. It is acknowledged first with the honored filter — resource subscriptions only for resources that exist — and every message carries the subscription id. Without a script it stays open and quiet, with keep-alive comments; with one it delivers the scripted notifications and, if asked, ends gracefully with the listen response.

const subscription = await client.listen({
  toolsListChanged: true,
  resourceSubscriptions: ["file:///docs/README.md", "file:///missing"],
});
subscription.honoredFilter;
// { toolsListChanged: true, resourceSubscriptions: ["file:///docs/README.md"] }

On the wire, the script travels in the listen request's _meta:

{
  "method": "subscriptions/listen",
  "params": {
    "notifications": { "toolsListChanged": true, "resourceSubscriptions": ["file:///docs/README.md"] },
    "_meta": {
      …the envelope…,
      "com.mcp-mock/notifications": {
        "events": ["toolsListChanged", { "resourceUpdated": "file:///docs/README.md" }],
        "intervalMs": 5,
        "close": true
      }
    }
  }
}
A script that announces something not subscribed is refused, since the server must not send what was not asked for.

On the 2024-11-05 SSE transport, resources/subscribe and resources/unsubscribe work, and the same script on resources/subscribe delivers notifications/resources/updated on the session stream. The legacy Streamable HTTP revisions, without sessions or a GET stream, have nowhere to deliver them and do not offer them.

Tasks

The io.modelcontextprotocol/tasks extension on 2026-07-28, kept stateless: the task id carries the original call, its start and its duration, so any tasks/get can work out the task's state without anything stored.

For clients that declare the extension, simulate_work answers with a task (resultType: "task") instead of blocking, and _meta["com.mcp-mock/task"] makes a task of any tools/call:

// tools/call get_weather { city: "Madrid" }, _meta: { "com.mcp-mock/task": { "durationMs": 2000 } }
// → { resultType: "task", taskId: "task_eyJwYXJhbXMi…", status: "working", statusMessage: "Working: 0%",
//     createdAt: "…", lastUpdatedAt: "…", ttlMs: 3600000, pollIntervalMs: 100 }

// tasks/get { taskId } — two seconds later
// → { status: "completed", result: { structuredContent: { city: "Madrid", … } }, … }
MethodBehaviour
tasks/getworking, then completed with the result the call would have returned, or failed with its JSON-RPC error. A tool execution error completes the task, as the extension requires.
tasks/update, tasks/cancelAcknowledge. Cancellation is cooperative, and a stateless task still finishes, which the extension allows.
subscriptions/listenAccepts taskIds and sends notifications/tasks when each task finishes.
Unknown tasks are -32602, clients without the extension get -32021, and Mcp-Name must carry the task id. Task timestamps are real — the one exception to the mock's determinism; task results are not affected. Every task message is validated against the extension's official schema.