A mock Model Context Protocol server for integration tests, faithful enough that the official SDKs cannot tell it from a real one — from 2024-11-05 to 2026-07-28. Deterministic tools, and any answer, error or HTTP failure forced from the request itself. Point your client at it, keep your code.
$docker run --rm -p 3000:3000 ghcr.io/axium-lab/mcp-mock:0.1.0
One command to run it, one URL to point your client at.
/mcpThe root endpoint serves any client without configuration: a modern 2026-07-28 request is served as 2026-07-28, a legacy initialize as the revision it negotiates. No session, no handshake to set up.
URLhttp://localhost:3000/mcp
Need to pin a revision? Each one has its own endpoint, like /2026-07-28/mcp or /2024-11-05/sse, and everything is served again behind OAuth under /protected/.
Multi-arch image on GHCR (linux/amd64, linux/arm64), or from source with Bun — or Node 22.18+.
# Docker — pin the exact release in CI
docker run --rm -p 3000:3000 ghcr.io/axium-lab/mcp-mock:0.1.0
# From source
git clone https://github.com/axium-lab/mcp-mock.git
cd mcp-mock
bun install
bun start # or: npm install && npm run start:node
The documentation covers every endpoint and control. Then the tools, resources & prompts, what changes between spec revisions, and the OAuth flow.
The official @modelcontextprotocol/client SDK talks to mcp-mock exactly as it talks to a real server. No request interception, no fake transport.
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")), // the only change
);
const result = await client.callTool({ name: "get_weather", arguments: { city: "Madrid" } });
// result.structuredContent → { city: "Madrid", temperature: 14, conditions: "thunderstorm", … }
// Same call, same bytes, every time, on any machine.
When a test needs a specific answer, the request carries it in _meta — for any tool name, adapted to each revision's format:
await client.callTool({
name: "get_weather",
arguments: { city: "Madrid" },
_meta: { "com.mcp-mock/response": { structuredContent: { city: "Madrid", temperature: 40 } } },
});
And when it needs the server to fall over, a header does it — on any endpoint and transport:
curl -i http://localhost:3000/mcp -H "x-mcp-mock-status: 429" …
# HTTP/1.1 429 Too Many Requests
# Retry-After: 1
Not a stub — a faithful server, verified in CI against each revision's official schema and the official SDK.
2024-11-05, 2025-03-26, 2025-06-18, 2025-11-25 and 2026-07-28, each with its own transport, handshake, vocabulary and error codes. Pin one to see how your client copes.
Every message the mock sends is checked against the official schema.json of its revision, and every endpoint is exercised through the official TypeScript SDK.
Real computations (calculate, hash_text, a real PNG…) and a fake world of weather, stocks, users and flights: same arguments, same bytes.
Every fake-world tool fails on a documented value — city: "Atlantis", user_id: "missing" — so your error handling gets exercised too.
Force a result, a JSON-RPC error, an input_required, a task or a notification script in _meta. Nothing to register, nothing to clean up.
x-mcp-mock-status forces any status from 400 to 599, with Retry-After on 429, so retries and fallbacks get tested.
Stateless requests, multi round-trip elicitation, progress over SSE, cancellation, subscriptions/listen and the tasks extension.
Everything under /protected/ needs a token. The mock is its own authorization server: metadata discovery, PKCE, refresh tokens, Dynamic Client Registration.
Each request carries what its own answer must be: identical on a laptop, in CI, or behind a load balancer. Snapshot-friendly by design.
One Docker command, or bun install && bun start. A /health endpoint reports the running version.
Every revision the official SDKs speak, each on its own pinned endpoint, and all of them at /mcp. What differs between them differs on the wire too — see Revisions.
| Revision | Endpoint | Transport | Status |
|---|---|---|---|
| 2026-07-28 | /2026-07-28/mcp | Streamable HTTP, stateless | ✅ Supported |
| 2025-11-25 | /2025-11-25/mcp | Streamable HTTP | ✅ Supported |
| 2025-06-18 | /2025-06-18/mcp | Streamable HTTP | ✅ Supported |
| 2025-03-26 | /2025-03-26/mcp | Streamable HTTP, batches | ✅ Supported |
| 2024-11-05 | /2024-11-05/sse | HTTP+SSE (deprecated) | ✅ Supported |
| stdio | — | stdio | Not yet |