cd /news/ai-agents/open-source-mock-mcp-server-to-test-… · home › topics › ai-agents › article
[ARTICLE · art-171883] src=github.com ↗ pub= topic=ai-agents verified=true sentiment=↑ positive

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.

key 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.

read6 min views8 publishedNov 18, 2026
Open-source mock MCP server to test clients and agents without real servers
Image: Michielbdejong (auto-discovered)

A mock MCP server for integration tests. Point your MCP client at it, keep your code.

mcp-mock speaks the Model Context Protocol 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. 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.

Point your client at the free public instance, https://public.mcp-mock.com/mcp:

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 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, aninitialize 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 .
/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 orto :"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 templatesweather://{city} ,user://{user_id} andfile:///{path} , drawn from the same fake world as the tools.
  • Prompts:summarize ,code_review andweather_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"] ontools/call Replaces the result with the given text ,content ,structuredContent andisError , 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 anddata .
_meta["com.mcp-mock/input-required"] ontools/call (2026-07-28) Answers input_required with the giveninputRequests andrequestState ; the retry returns what your client answered.
_meta["com.mcp-mock/notifications"] onsubscriptions/listen orresources/subscribe Scripts the change notifications the stream delivers ( events ,intervalMs ,close ).
_meta["com.mcp-mock/task"] ontools/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 addsRetry-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 withWWW-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 withcode andiss ;/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, andmcp_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 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 (orPORT ) 3000 Port to listen on.

stdio, Origin header validation, and sessions on the legacy revisions. Tell us what you need in the Discussions.

See CONTRIBUTING.md and the CHANGELOG.

── more in #ai-agents 4 stories · sorted by recency
── more on @axium lab 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/open-source-mock-mcp…] indexed:0 read:6min 2026-11-18 · —