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-05 | 2025-03-26 | 2025-06-18 | 2025-11-25 | 2026-07-28 | |
|---|---|---|---|---|---|
| Transport | HTTP+SSE | Streamable HTTP | Streamable HTTP | Streamable HTTP | Streamable HTTP, stateless |
| Handshake | initialize | initialize | initialize | initialize | none: _meta on every request, server/discover |
| JSON-RPC batches | no | yes | no | no | no |
| Structured content, resource links, titles | no | no | yes | yes | yes |
| Tool annotations | no | yes | yes | yes | yes |
| Invalid tool arguments | protocol error | protocol error | protocol error | isError result | isError result |
| Resource not found | -32002 | -32002 | -32002 | -32002 | -32602 |
Progress message | no | yes | yes | yes | yes |
Elicitation (delete_file) | no | no | no | no | yes, 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/protocolVersion | Required. "2026-07-28" |
io.modelcontextprotocol/clientCapabilities | Required. An object, e.g. { "elicitation": { "form": {} } } |
io.modelcontextprotocol/clientInfo | Optional. { name, version } |
io.modelcontextprotocol/logLevel | Optional. 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:
| # | Check | Failure |
|---|---|---|
| 1 | JSON-RPC shape (batches and posted responses refused) | 400 · -32600 |
| 2 | Era: legacy traffic, like an initialize | 400 · -32022 listing the versions served |
| 3 | The _meta envelope | 400 · -32602 |
| 4 | Header/body agreement (version, Mcp-Method) | 400 · -32020 |
| 5 | Supported version | 400 · -32022 |
| 6 | Standard headers present, Mcp-Name matching | 400 · -32020 |
| 7 | Method exists | 404 · -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: truereturnsisError: true— Deletion cancelled: /tmp/old.log was not deleted. - The
requestStatebinds the confirmation to the file, so it cannot be replayed on another path. - A client that does not declare form elicitation gets
-32021(MissingRequiredClientCapabilityError, HTTP400).
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.
| Transport | Cancellation |
|---|---|
| 2026-07-28 | Closing the response stream cancels the request: the server stops and sends nothing more. |
| 2024-11-05 SSE | notifications/cancelled cancels a running request of the same session, which is never answered. |
| Legacy Streamable HTTP | Without 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
}
}
}
}
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", … } }, … }
| Method | Behaviour |
|---|---|
tasks/get | working, 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/cancel | Acknowledge. Cancellation is cooperative, and a stateless task still finishes, which the extension allows. |
subscriptions/listen | Accepts taskIds and sends notifications/tasks when each task finishes. |
-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.