Open-source mock MCP server to test clients and agents without real servers
Axium Lab launched mcp-mock 0.1.0 to let engineers test Model Context Protocol clients across six spec revisions using deterministic tools and built-in OAuth.
By Dillip Chowdary • Nov 19, 2026 • Source: github.com

At a glance
- Product
- mcp-mock
- Developer
- Axium Lab
- Initial version
- 0.1.0
- License
- MIT
- Default port
- 3000
- Supported specs
- 2024-11-05 to 2026-07-28
In this post
Axium Lab released mcp-mock, an open-source test server designed to emulate Model Context Protocol implementations across every specification revision from 2024-11-05 to 2026-07-28 without requiring real downstream dependencies. According to github.com's report, the utility mirrors official server behaviors accurately enough that standard software development kits cannot distinguish it from a live production target. The project operates from the engineering team responsible for llm-mock, providing engineers with consistent deterministic data alongside zero-setup cloud sandboxes.
This architectural breakdown examines the runtime modes, revision routing, built-in synthetic tools, error injection primitives, and integrated authorization mechanisms shipped in initial release 0.1.0. It serves software engineers, agent architects, and continuous integration teams seeking to validate client applications against strict protocol boundaries. Teams can eliminate brittle external test environments by adopting reproducible mock fixtures that behave identically across local development machines and shared automated testing pipelines.
01Zero-install public endpoints and local runtime options
Axium Lab deployed a zero-install public testing node reachable at public.mcp-mock.com to eliminate local configuration overhead. Development teams can point client transports directly at the public uniform resource locator without downloading binaries, registering user accounts, or provisioning application programming interface keys. Connecting an official StreamableHTTPClientTransport instance allows test callers to invoke synthetic tools like get_weather and immediately receive identical, deterministic structured payloads across every test execution.
Local execution paths satisfy developers operating within isolated enterprise networks, pinned continuous integration runners, or offline laptop environments. Operators can pull container images from the GitHub Container Registry or bootstrap source clones with runtime tooling. The repository supports native execution across modern JavaScript ecosystems using either Bun or Node 22.18 and higher versions.
- Install dependencies execute bun install or npm install inside the repository checkout directory.
- Launch server start the runtime daemon using bun start or npm run start:node to bind port 3000.
02Dedicated revision routing across protocol eras
The software hosts parallel endpoints to isolate modern stateless specifications from legacy stream transports. Developers can route traffic to /mcp for adaptive negotiation, which processes requests bearing 2026-07-28 meta envelopes under current standards while directing handshake requests to legacy pathways. Teams evaluate edge-case behaviors by directing connections to pinned uniform resource locators that enforce single-revision limits against client negotiations.
| Endpoint URL | Served Revision and Transport Details |
|---|---|
| /mcp | Adapts to client handshake or 2026-07-28 envelope |
| /2026-07-28/mcp | Pinned stateless 2026-07-28 Streamable HTTP |
| /2025-11-25/mcp | Pinned 2025-11-25 Streamable HTTP revision |
| /2025-06-18/mcp | Pinned 2025-06-18 Streamable HTTP revision |
| /2025-03-26/mcp | Pinned 2025-03-26 Streamable HTTP revision |
| /2024-11-05/sse | Pinned 2024-11-05 deprecated HTTP and SSE |
| /sse | Root endpoint negotiating any legacy revision over SSE |
| /health | System telemetry returning status ok and version string |
Every served transmission undergoes strict schema validation against official specifications during automated testing suites. The 2026-07-28 endpoint supports multi round-trip interactions, streaming cancellation signals, subscription event delivery, and the tasks extension without persistent server memory. Legacy revisions discard conversational state between discrete queries, fulfilling spec-compliant stateless allowances across test environments.
03Twenty-two synthetic tools and failure fixtures
Advertisement
Tech Pulse Daily
Get tomorrow's pulse first
Join engineers who read Tech Pulse before stand-up. Free, weekday mornings.
The mock engine registers twenty-two default tools spanning computational routines and stateful synthetic fixtures. Deterministic tools include add, text_stats, convert_units, sort_list, hash_text, date_diff, and a color_swatch generator producing binary image buffers. Calls normalize string inputs before running hashing functions, ensuring mixed capitalization or extraneous whitespace across arguments like Madrid resolve to the same underlying synthetic entities.
| Tool Name | Intentional Failure Trigger |
|---|---|
| get_weather, get_forecast | city argument set to Atlantis |
| geocode | address argument set to Atlantis |
| search_web | query argument set to error |
| get_stock_price | symbol argument set to XXXX |
| convert_currency | from or to argument set to XXX |
| get_user | user_id argument set to missing |
| get_flight_status | flight_number argument set to XX000 |
| read_file, delete_file | path argument set to /missing |
| send_email | to argument set to bounce@example.com |
Synthetic fixtures extend beyond functional calls into prompt templates and mock file system resources. Available templates provide summarize, code_review, and weather_report routines that embed contextual weather data directly into prompt payloads. Static resources simulate text documents, comma-separated metric tables, configuration files, and binary image files under uniform resource identifiers like file:///etc/app/config.json.
04Per-request control envelopes and status injection
Engineers override default mock responses directly inside client payload metadata without registering pre-test mocks on the server. Injecting custom keys into the request meta dictionary instructs the server to return specific text, structured schemas, or error responses for any tool target. This per-call control eliminates race conditions between parallel test threads because mock parameters stay completely contained within discrete hypertext requests.
| Control Mechanism | Injected Testing Behavior |
|---|---|
| _meta["com.mcp-mock/response"] | Overrides tool results with custom structured content |
| _meta["com.mcp-mock/error"] | Forces JSON-RPC error codes and exception messages |
| _meta["com.mcp-mock/input-required"] | Returns multi-turn input prompts on 2026-07-28 |
| _meta["com.mcp-mock/notifications"] | Delivers timed subscription notifications before closing |
| _meta["com.mcp-mock/task"] | Emulates long-running task flows for task extensions |
| x-mcp-mock-status header | Forces HTTP error codes from 400 through 599 |
Simulating network failures occurs through explicit transport header injection rather than external proxy manipulation. Adding the x-mcp-mock-status header triggers targeted gateway failures, while error code 429 automatically returns standard rate-limiting headers. Tool operations like delete_file trigger confirmation prompts across multi round-trip requests on 2026-07-28 without modifying real backend data.
05Native OAuth testing and multi-architecture containers
Secured validation workflows run against paths routed under the /protected/ prefix, which demand standard bearer tokens for access. The software acts as an integrated authorization server on the same domain, publishing RFC 9728 protected resource metadata alongside OpenID Connect discovery endpoints. Calling /oauth/authorize handles authorization code grants with PKCE S256 validation, returning tokens signed with fixed keys that require the mcp scope.
Container images publish to the GitHub Container Registry under tag 0.1.0, tracking latest minor releases across both linux/amd64 and linux/arm64 system architectures. The runtime listens on port 3000 by default and exposes container health metrics through the /health route. Operators can remap host ports and environment variables like MCP_MOCK_PORT to bind custom listener configurations.
Note: Axium Lab does not yet support stdio transport, Origin header validation, or persistent session tracking on legacy protocol revisions.
Frequently asked questions
What specification revisions does mcp-mock support?
It supports all Model Context Protocol revisions published between 2024-11-05 and 2026-07-28, including legacy Streamable HTTP and HTTP with Server-Sent Events.
How can developers trigger mock tool errors without configuration?
Developers pass predetermined trigger arguments such as Atlantis for weather calls, XXXX for stock queries, or inject explicit error envelopes using the _meta payload property.
Does mcp-mock require setting up an external identity provider for OAuth testing?
No, mcp-mock contains a built-in authorization server that implements RFC 9728 metadata, PKCE S256 code exchanges, and token endpoints on the same origin.
Sources
Author
Dillip Chowdary
Writes Tech Bytes coverage of AI, engineering, and the tools that actually ship. Editor of Tech Pulse Daily.
Related on Tech Bytes
Advertisement