open source · MIT

Test your MCP client
against every spec revision

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

Get started

One command to run it, one URL to point your client at.

⚡ One URL, any client

Point your client at /mcp

The 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/.

Run it your way

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.

Point your client, keep your code

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

Built for real integration tests

Not a stub — a faithful server, verified in CI against each revision's official schema and the official SDK.

Five spec revisions

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.

Validated on the wire

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.

22 deterministic tools

Real computations (calculate, hash_text, a real PNG…) and a fake world of weather, stocks, users and flights: same arguments, same bytes.

Failure paths on purpose

Every fake-world tool fails on a documented value — city: "Atlantis", user_id: "missing" — so your error handling gets exercised too.

Control from the test

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.

HTTP failures on demand

x-mcp-mock-status forces any status from 400 to 599, with Retry-After on 429, so retries and fallbacks get tested.

The whole 2026-07-28 surface

Stateless requests, multi round-trip elicitation, progress over SSE, cancellation, subscriptions/listen and the tasks extension.

OAuth, opt-in by URL

Everything under /protected/ needs a token. The mock is its own authorization server: metadata discovery, PKCE, refresh tokens, Dynamic Client Registration.

Stateless

Each request carries what its own answer must be: identical on a laptop, in CI, or behind a load balancer. Snapshot-friendly by design.

Zero setup

One Docker command, or bun install && bun start. A /health endpoint reports the running version.

Spec revisions

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.

RevisionEndpointTransportStatus
2026-07-28/2026-07-28/mcpStreamable HTTP, stateless✅ Supported
2025-11-25/2025-11-25/mcpStreamable HTTP✅ Supported
2025-06-18/2025-06-18/mcpStreamable HTTP✅ Supported
2025-03-26/2025-03-26/mcpStreamable HTTP, batches✅ Supported
2024-11-05/2024-11-05/sseHTTP+SSE (deprecated)✅ Supported
stdio—stdioNot yet