Open-source mock MCP server to test clients and agents without real servers Axium Lab, the team behind llm-mock, released mcp-mock 0.1.0, an open-source mock Model Context Protocol server that emulates every MCP spec revision from 2024-11-05 through 2026-07-28 so developers can test MCP clients and agents without a real server. The mock exposes 22 tools with deterministic, hash-derived responses and lets a test force any answer, error or HTTP failure from the request itself, and it runs free at public.mcp-mock.com/mcp or locally via the Docker image ghcr.io/axium-lab/mcp-mock:0.1.0 on port 3000. Pinned endpoints such as /2026-07-28/mcp and /2024-11-05/sse let developers reproduce clients that only speak one revision, a case the project says is hard to test against real servers. A mock MCP server for integration tests. Point your MCP client at it, keep your code. mcp-mock speaks the Model Context Protocol https://modelcontextprotocol.io faithfully enough that the official SDKs cannot tell it from a real server, in every spec revision from 2024-11-05 to 2026-07-28. Its tools return deterministic, believable data, and a test can force any answer, error or HTTP failure from the request itself, with nothing to register beforehand. ⚡ Zero install : a free public instance runs at public.mcp-mock.com https://public.mcp-mock.com/health . Point your MCP client at https://public.mcp-mock.com/mcp and start in seconds; no download, no signup, no API key. From the team behind llm-mock https://github.com/axium-lab/llm-mock . Point your client at the free public instance, https://public.mcp-mock.com/mcp : js import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client"; const client = new Client { name: "my-app", version: "1.0.0" } ; await client.connect new StreamableHTTPClientTransport new URL "https://public.mcp-mock.com/mcp" ; 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. For CI, offline work, or to pin an exact release, run it yourself and use http://localhost:3000/mcp instead: docker run --rm -p 3000:3000 ghcr.io/axium-lab/mcp-mock:0.1.0 See Docker docker for the available tags. Or from a clone of this repository: bun install bun start or, without Bun: npm install && npm run start:node Node 22.18+ Every endpoint is served on the public instance, https://public.mcp-mock.com , and on your own http://localhost:3000 by default . | URL | Serves | |---|---| | /mcp | Any 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/mcp | Only 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 oauth . | | /health | { "status": "ok", "version": "…" } | A pinned endpoint is how you test what your client does when a server only speaks one revision, which is hard to reproduce against real servers. 22 tools, listed in this order on every revision. Real computations: echo , add , calculate a safe arithmetic parser , transform text , text stats , sort list , convert units , hash text , date diff , color swatch a real PNG and simulate work waits between steps; for progress, timeouts, cancellation and tasks . Fake world: data derived from a hash of the normalized arguments, so the same call always returns the same data and different calls return different, internally consistent data metric and imperial agree, currency conversions round-trip, a 3-day forecast is the start of the 7-day one . | Tool | Fails on purpose with | |---|---| | get weather , get forecast | city: "Atlantis" | | geocode | address: "Atlantis" | | search web | query: "error" | | get stock price | symbol: "XXXX" | | convert currency | from or to : "XXX" | | get user | user id: "missing" | | get flight status | flight number: "XX000" | | read file , delete file | path: "/missing" | | send email | to: "bounce@example.com" | Arguments are normalized before hashing and matching: " madrid " and "Madrid" are the same city. Results use every content type: text, structured content with an output schema, image , resource link and embedded resource . delete file asks for confirmation through a multi round-trip request on 2026-07-28 nothing is really deleted . - Resources: file:///etc/app/config.json , file:///docs/README.md , file:///data/report.csv , file:///images/logo.png a binary blob , and the templates weather://{city} , user://{user id} and file:///{path} , drawn from the same fake world as the tools. - Prompts: summarize , code review and weather report , the last with the city's weather embedded as a resource. Each request carries what its own answer must be: identical requests always get identical answers, and nothing is shared between requests. | Control | Effect | |---|---| | meta "com.mcp-mock/response" on tools/call | Replaces the result with the given text , content , structuredContent and isError , for any tool name. Adapted to each revision's format. | | meta "com.mcp-mock/error" on any request | Fails it with the given JSON-RPC code , message and data . | | meta "com.mcp-mock/input-required" on tools/call 2026-07-28 | Answers input required with the given inputRequests and requestState ; the retry returns what your client answered. | | meta "com.mcp-mock/notifications" on subscriptions/listen or resources/subscribe | Scripts the change notifications the stream delivers events , intervalMs , close . | | meta "com.mcp-mock/task" on tools/call 2026-07-28 | Makes a task of the call durationMs , for clients that declare the tasks extension. | | x-mcp-mock-status: 503 header | Forces an HTTP failure from 400 to 599 on any endpoint; 429 adds Retry-After . | await client.callTool { name: "get weather", arguments: { city: "Madrid" }, meta: { "com.mcp-mock/response": { structuredContent: { city: "Madrid", temperature: 40 } } }, } ; What differs between revisions differs on the wire too, for example: | | 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 | | Invalid tool arguments | protocol error | protocol error | protocol error | isError result | isError result | | Resource not found | -32002 | -32002 | -32002 | -32002 | -32602 | Every message the mock sends is validated in its test suite against the official schema.json of its revision, and every endpoint is exercised through the official TypeScript SDK as the client. On 2026-07-28 the mock also serves multi round-trip requests, progress over SSE, cancellation by closing the stream, subscriptions/listen , and the tasks extension io.modelcontextprotocol/tasks . Legacy revisions are served without sessions, which the spec allows, so they keep no state between requests. Authorization is opt-in by URL: everything under /protected/ requires a bearer token, and everything else stays open. The mock is its own authorization server, on the same origin: - 401 with WWW-Authenticate pointing at the Protected Resource Metadata RFC 9728 of each protected endpoint. - Authorization server metadata at /.well-known/oauth-authorization-server and as OpenID Connect discovery . - /oauth/authorize approves at once and redirects back with code and iss ; /oauth/token handles the authorization code grant with PKCE S256 and refresh tokens; /oauth/register handles Dynamic Client Registration. - Tokens must be issued for the very endpoint they are used on, and carry the mcp scope 403 insufficient scope otherwise . - To provoke failures: the mcp-mock:deny scope makes the user deny access, and mcp mock expires in on the token endpoint issues tokens that expire when you want. The official SDK's OAuth flow runs end to end against it. Codes and tokens are signed with a fixed, public key and are not single-use: this is a test double, not an authorization server for real users. Every release https://github.com/axium-lab/mcp-mock/releases 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 | Tag | Points to | |---|---| | 0.1.0 | That exact release. Pin this one in CI so your tests don't change under you. | | 0.1 | The latest patch release of 0.1. | | latest | The 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 | Variable | Default | Meaning | |---|---|---| | MCP MOCK PORT or PORT | 3000 | Port to listen on. | stdio, Origin header validation, and sessions on the legacy revisions. Tell us what you need in the Discussions https://github.com/axium-lab/mcp-mock/discussions . See CONTRIBUTING.md https://github.com/axium-lab/mcp-mock/blob/main/CONTRIBUTING.md and the CHANGELOG https://github.com/axium-lab/mcp-mock/blob/main/CHANGELOG.md .