Documentation

Documentation

mcp-mock speaks the Model Context Protocol in every revision from 2024-11-05 to 2026-07-28 — same transports, same messages, same error codes — with deterministic tools and answers the test controls from the request itself. This page covers the endpoints and the controls; the catalog, the revisions and OAuth have their own pages.

Reference pages

Everything on this page applies to every endpoint. The details live on their own pages.

PageWhat's there
Tools, resources & promptsThe 22 tools with their arguments and failure values, the fake files and URI templates, the three prompts
Spec revisionsWhat differs between revisions, and the 2026-07-28 surface: the _meta envelope, multi round-trip requests, progress, cancellation, subscriptions and tasks
OAuthThe /protected/ endpoints, discovery metadata, the authorization server and its failure switches

Endpoints

Every endpoint lives on the same server, on port 3000 by default.

URLServes
/mcpAny client. Each request is served in the era it opens with: a request carrying the 2026-07-28 _meta envelope as 2026-07-28, an initialize as the legacy revision it negotiates. Use this one unless you need to pin a revision.
/2026-07-28/mcpOnly 2026-07-28, the stateless revision.
/2025-11-25/mcp
/2025-06-18/mcp
/2025-03-26/mcp
Only that legacy revision, over Streamable HTTP.
/2024-11-05/sse
/sse
The deprecated HTTP+SSE transport. The pinned one speaks only 2024-11-05; the root one negotiates any legacy revision.
/protected/…Every endpoint above again, behind OAuth. See OAuth.
/health{ "status": "ok", "version": "0.1.0" }
A pinned endpoint is how you test what your client does when a server only speaks one revision — something that is hard to reproduce against real servers. A legacy client reaching /2026-07-28/mcp gets an UnsupportedProtocolVersionError listing the versions served, exactly as a modern-only server would answer.

The era of a request on /mcp is read from how it opens, never remembered: a request with the _meta envelope, or a modern MCP-Protocol-Version header, is 2026-07-28; anything else is legacy. A legacy request without MCP-Protocol-Version is treated as 2025-03-26, as the spec prescribes, since that header only arrived in 2025-06-18.

Connecting a client

Use your MCP client as you would against any server. These examples use the official TypeScript SDK, the one the mock is tested with.

import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";

const client = new Client({ name: "my-app", version: "1.0.0" });
await client.connect(new StreamableHTTPClientTransport(new URL("http://localhost:3000/mcp")));

const { tools } = await client.listTools();           // 22 tools, always in the same order
const sum = await client.callTool({ name: "add", arguments: { a: 2, b: 3 } });

To make the client speak one particular era, set its version negotiation, and point it at the matching pinned endpoint if you want the server to refuse everything else:

// Modern only: exactly 2026-07-28, no handshake
new Client(info, { versionNegotiation: { mode: { pin: "2026-07-28" } } });

// Legacy only: the initialize handshake, narrowed to one revision
new Client(info, { versionNegotiation: { mode: "legacy" }, supportedProtocolVersions: ["2025-06-18"] });

// 2024-11-05 travels over the deprecated HTTP+SSE transport
await client.connect(new SSEClientTransport(new URL("http://localhost:3000/2024-11-05/sse")));

Clients that connect as legacy by default, like the MCP Inspector, work unchanged against /mcp or any legacy endpoint. On the wire, a 2026-07-28 request is plain JSON-RPC with its envelope in _meta:

curl http://localhost:3000/mcp \
  -H "content-type: application/json" -H "accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2026-07-28" -H "Mcp-Method: tools/call" -H "Mcp-Name: get_weather" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{
        "name":"get_weather","arguments":{"city":"Madrid"},
        "_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28",
                 "io.modelcontextprotocol/clientCapabilities":{}}}}'

# {"jsonrpc":"2.0","id":1,"result":{"content":[…],"structuredContent":{"city":"Madrid","temperature":14,
#   "temperature_unit":"°C","conditions":"thunderstorm","humidity":42,"wind_speed":55,"wind_speed_unit":"km/h"},
#   "resultType":"complete","_meta":{"io.modelcontextprotocol/serverInfo":{"name":"mcp-mock","version":"0.1.0"}}}}

Controlling answers

By default every tool answers with its deterministic data. When a test needs something else, the request itself carries what its answer must be — nothing to register beforehand, nothing remembered afterwards.

ControlOnEffect
_meta["com.mcp-mock/response"]tools/callReplaces the result with the given text, content, structuredContent and isError, for any tool name.
_meta["com.mcp-mock/error"]any requestFails it with the given JSON-RPC code, message and data.
_meta["com.mcp-mock/input-required"]tools/call, 2026-07-28Answers input_required with the given inputRequests and requestState.
_meta["com.mcp-mock/notifications"]subscriptions/listen, resources/subscribeScripts the change notifications the stream delivers.
_meta["com.mcp-mock/task"]tools/call, 2026-07-28Makes a task of the call, for clients that declare the tasks extension.
x-mcp-mock-status headerany HTTP requestForces an HTTP failure from 400 to 599. See Provoking HTTP failures.
_meta travels in every revision and on every transport, and the official SDKs let a test set it per call. The com.mcp-mock/ prefix is mcp-mock.com in reverse DNS, as the spec asks of non-MCP _meta keys. A malformed control is never ignored: it fails the request with -32602 naming the problem.

Forcing a result

text is shorthand for a single text block; content is an array of content blocks passed through as given — so a test can also send blocks its client should reject. Use one or the other, not both. Structured content without content is repeated as a JSON text block, as the spec asks of tools that return structured content. The tool name is not checked and its arguments are not validated, and the result is adapted to each revision like the catalog's own (no structuredContent on 2025-03-26, for instance).

// A canned success
await client.callTool({
  name: "get_weather",
  arguments: { city: "Madrid" },
  _meta: { "com.mcp-mock/response": { structuredContent: { city: "Madrid", temperature: 40 } } },
});

// A tool execution error, for a tool that does not even exist
await client.callTool({
  name: "book_hotel",
  arguments: {},
  _meta: { "com.mcp-mock/response": { text: "No rooms left.", isError: true } },
});

Forcing a JSON-RPC error

Works on any request — tools/list, resources/read, prompts/get… — and wins over the method's own answer. code must be an integer and message a string; data is optional and passed through. Notifications are left alone, since JSON-RPC forbids answering them.

await client.listTools({ _meta: { "com.mcp-mock/error": { code: -32603, message: "Boom" } } });
// → {"jsonrpc":"2.0","id":…,"error":{"code":-32603,"message":"Boom"}}   (HTTP 200: errors from methods travel in-band)

Forcing input_required

2026-07-28 only; refused on legacy revisions. inputRequests maps ids to requests, each with a string method, passed through as given — even for capabilities the client did not declare, so a test can check how its client copes. Give at least one of inputRequests or requestState, as the spec requires.

The retry, recognised by its inputResponses or requestState, returns the forced result if the request also carries com.mcp-mock/response, and otherwise returns what the client answered — so the test can assert its client's side of the round trip. See Multi round-trip requests.

Scripting notifications

The catalog never changes on its own, so a test scripts the changes it wants its client to see:

FieldDefaultMeaning
eventsrequiredAn array of "toolsListChanged", "promptsListChanged", "resourcesListChanged" or { "resourceUpdated": "<uri>" }.
intervalMs10Milliseconds before each event, from 0 to 60000.
closefalseWhether the server ends the stream gracefully after the last event.

See Subscriptions for where each revision delivers them.

Forcing a task

{ "durationMs": 2000 } (an integer from 0 to 600000, default 0) turns any tools/call into a task, for clients that declare the io.modelcontextprotocol/tasks extension; for any other client it is -32021. See Tasks.

Provoking HTTP failures

A retry loop, a circuit breaker or a fallback is only tested once the server has actually failed. x-mcp-mock-status makes it fail on demand: any status from 400 to 599, on every endpoint and transport.

curl -i http://localhost:3000/mcp -H "x-mcp-mock-status: 429" \
  -H "content-type: application/json" -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# HTTP/1.1 429 Too Many Requests
# Retry-After: 1
#
# {"jsonrpc":"2.0","id":null,"error":{"code":-32000,"message":"Too Many Requests: rate limit reached."}}

With the TypeScript SDK, pass the header through the transport's request options, or wrap its fetch to add it only on the calls that should fail:

const transport = new StreamableHTTPClientTransport(new URL("http://localhost:3000/mcp"), {
  requestInit: { headers: { "x-mcp-mock-status": "503" } },
});
StatusMessage
429Too Many Requests: rate limit reached. — plus Retry-After: 1, so a backoff that honours it completes within a test's lifetime
500Internal Server Error.
502Bad Gateway.
503Service Unavailable: the server is temporarily unavailable.
504Gateway Timeout.
any otherSimulated HTTP status, provoked via x-mcp-mock-status.
A value outside 400–599 is itself refused with 400 rather than ignored, so a typo never passes silently as a success. Under /protected/ the bearer token is checked first: a request without a valid token is still a 401, as it would be on a real server whose outage sits behind its gateway. Timeouts remain the one failure a header cannot provoke — for those, call simulate_work with a long step_ms.

Docker & configuration

Every release publishes an image to the GitHub Container Registry, for linux/amd64 and linux/arm64. No login is needed to pull it.

docker pull ghcr.io/axium-lab/mcp-mock:0.1.0
TagPoints to
0.1.0That exact release. Pin this one in CI so your tests don't change under you.
0.1The latest patch release of 0.1.
latestThe latest release.

The container listens on port 3000 and reports its state to Docker through /health. To serve on another port, change both sides:

docker run --rm -p 8080:8080 -e MCP_MOCK_PORT=8080 ghcr.io/axium-lab/mcp-mock:0.1.0
VariableDefaultMeaning
MCP_MOCK_PORT (or PORT)3000Port to listen on.

From a clone, bun install && bun start runs it on Bun; without Bun, npm install && npm run start:node runs it on Node 22.18+. In a GitHub Actions job, run it as a service container:

services:
  mcp-mock:
    image: ghcr.io/axium-lab/mcp-mock:0.1.0
    ports: ["3000:3000"]

Not supported yet

The stdio transport, Origin header validation, and sessions on the legacy revisions — which the spec allows a server to go without, so legacy endpoints keep no state between requests. Tell us what you need in the Discussions.