{"slug": "open-source-mock-mcp-server-to-test-clients-and-agents-without-real-servers", "title": "Open-source mock MCP server to test clients and agents without real servers", "summary": "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.", "body_md": "**A mock MCP server for integration tests. Point your MCP client at it, keep your code.**\n\nmcp-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.\n\n**⚡ 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.\n\nFrom the team behind [llm-mock](https://github.com/axium-lab/llm-mock).\n\nPoint your client at the free public instance, `https://public.mcp-mock.com/mcp`:\n\n``` js\nimport { Client, StreamableHTTPClientTransport } from \"@modelcontextprotocol/client\";\n\nconst client = new Client({ name: \"my-app\", version: \"1.0.0\" });\nawait client.connect(new StreamableHTTPClientTransport(new URL(\"https://public.mcp-mock.com/mcp\")));\n\nconst result = await client.callTool({ name: \"get_weather\", arguments: { city: \"Madrid\" } });\n// result.structuredContent → { city: \"Madrid\", temperature: 14, conditions: \"thunderstorm\", … }\n// Same call, same bytes, every time, on any machine.\n```\n\nFor CI, offline work, or to pin an exact release, run it yourself and use `http://localhost:3000/mcp` instead:\n\n```\ndocker run --rm -p 3000:3000 ghcr.io/axium-lab/mcp-mock:0.1.0\n```\n\nSee [Docker](#docker) for the available tags. Or from a clone of this repository:\n\n```\nbun install\nbun start            # or, without Bun: npm install && npm run start:node (Node 22.18+)\n```\n\nEvery endpoint is served on the public instance, `https://public.mcp-mock.com`, and on your own (` http://localhost:3000` by default).\n\n| URL | Serves | \n|---|---|\n| `/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. | \n| `/2026-07-28/mcp` | Only 2026-07-28, the stateless revision. | \n| `/2025-11-25/mcp` ,`/2025-06-18/mcp` ,`/2025-03-26/mcp` | Only that legacy revision, over Streamable HTTP. | \n| `/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. | \n| `/protected/…` | Every endpoint above again, behind OAuth. See [OAuth](#oauth) . | \n| `/health` | `{ \"status\": \"ok\", \"version\": \"…\" }` | \n\nA 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.\n\n22 tools, listed in this order on every revision.\n\n**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).\n\n**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).\n\n| Tool | Fails on purpose with | \n|---|---|\n| `get_weather` ,`get_forecast` | `city: \"Atlantis\"` | \n| `geocode` | `address: \"Atlantis\"` | \n| `search_web` | `query: \"error\"` | \n| `get_stock_price` | `symbol: \"XXXX\"` | \n| `convert_currency` | `from` or`to` :`\"XXX\"` | \n| `get_user` | `user_id: \"missing\"` | \n| `get_flight_status` | `flight_number: \"XX000\"` | \n| `read_file` ,`delete_file` | `path: \"/missing\"` | \n| `send_email` | `to: \"bounce@example.com\"` | \n\nArguments 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`.\n\n`delete_file` asks for confirmation through a multi round-trip request on 2026-07-28 (nothing is really deleted).\n\n- **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.\n- **Prompts:**`summarize` ,`code_review` and`weather_report` , the last with the city's weather embedded as a resource.\n\nEach request carries what its own answer must be: identical requests always get identical answers, and nothing is shared between requests.\n\n| Control | Effect | \n|---|---|\n| `_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. | \n| `_meta[\"com.mcp-mock/error\"]` on any request | Fails it with the given JSON-RPC `code` ,`message` and`data` . | \n| `_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. | \n| `_meta[\"com.mcp-mock/notifications\"]` on`subscriptions/listen` or`resources/subscribe` | Scripts the change notifications the stream delivers ( `events` ,`intervalMs` ,`close` ). | \n| `_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. | \n| `x-mcp-mock-status: 503` header | Forces an HTTP failure from 400 to 599 on any endpoint; `429` adds`Retry-After` . | \n\n```\nawait client.callTool({\n  name: \"get_weather\",\n  arguments: { city: \"Madrid\" },\n  _meta: { \"com.mcp-mock/response\": { structuredContent: { city: \"Madrid\", temperature: 40 } } },\n});\n```\n\nWhat differs between revisions differs on the wire too, for example:\n\n|  | 2024-11-05 | 2025-03-26 | 2025-06-18 | 2025-11-25 | 2026-07-28 | \n|---|---|---|---|---|---|\n| Transport | HTTP+SSE | Streamable HTTP | Streamable HTTP | Streamable HTTP | Streamable HTTP, stateless | \n| Handshake | `initialize` | `initialize` | `initialize` | `initialize` | none: `_meta` on every request,`server/discover` | \n| JSON-RPC batches | no | yes | no | no | no | \n| Structured content, resource links, titles | no | no | yes | yes | yes | \n| Invalid tool arguments | protocol error | protocol error | protocol error | `isError` result | `isError` result | \n| Resource not found | `-32002` | `-32002` | `-32002` | `-32002` | `-32602` | \n\nEvery 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.\n\nOn 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.\n\nAuthorization 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:\n\n- `401` with`WWW-Authenticate` pointing at the Protected Resource Metadata (RFC 9728) of each protected endpoint.\n- Authorization server metadata at `/.well-known/oauth-authorization-server` (and as OpenID Connect discovery).\n- `/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.\n- Tokens must be issued for the very endpoint they are used on, and carry the `mcp` scope (`403 insufficient_scope` otherwise).\n- 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.\n\nThe 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.\n\nEvery [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:\n\n```\ndocker pull ghcr.io/axium-lab/mcp-mock:0.1.0\n```\n\n| Tag | Points to | \n|---|---|\n| `0.1.0` | That exact release. Pin this one in CI so your tests don't change under you. | \n| `0.1` | The latest patch release of 0.1. | \n| `latest` | The latest release. | \n\nThe container listens on port 3000 and reports its state to Docker through `/health`. To serve on another port, change both sides:\n\n```\ndocker run --rm -p 8080:8080 -e MCP_MOCK_PORT=8080 ghcr.io/axium-lab/mcp-mock:0.1.0\n```\n\n| Variable | Default | Meaning | \n|---|---|---|\n| `MCP_MOCK_PORT` (or`PORT` ) | `3000` | Port to listen on. | \n\nstdio, `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).\n\nSee [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).", "url": "https://wpnews.pro/news/open-source-mock-mcp-server-to-test-clients-and-agents-without-real-servers", "canonical_source": "https://github.com/axium-lab/mcp-mock", "published_at": "2026-11-18 15:36:50+00:00", "updated_at": "2026-11-18 15:48:15.407579+00:00", "lang": "en", "topics": ["ai-agents", "agent-protocols", "developer-tools", "ai-tools"], "entities": ["Axium Lab", "mcp-mock", "llm-mock", "Model Context Protocol", "public.mcp-mock.com", "Docker", "Bun", "Node 22.18"], "also_reported_by": [], "takeaway": "mcp-mock 0.1.0 serves all MCP revisions from 2024-11-05 to 2026-07-28, including the stateless 2026-07-28 revision, with 22 deterministic tools and request-triggered failures such as city \"Atlantis\" for get_weather, so MCP clients can be integration-tested without a real server.", "recommendation": null, "alternates": {"html": "https://wpnews.pro/news/open-source-mock-mcp-server-to-test-clients-and-agents-without-real-servers", "markdown": "https://wpnews.pro/news/open-source-mock-mcp-server-to-test-clients-and-agents-without-real-servers.md", "text": "https://wpnews.pro/news/open-source-mock-mcp-server-to-test-clients-and-agents-without-real-servers.txt", "jsonld": "https://wpnews.pro/news/open-source-mock-mcp-server-to-test-clients-and-agents-without-real-servers.jsonld"}}