Home / Blog / Open-source mock MCP server to test clients and agents…
Tech News

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

Open-source mock MCP server to test clients and agents without real servers
Illustration · Pexels

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

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.

  1. Install dependencies execute bun install or npm install inside the repository checkout directory.
  2. 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 URLServed Revision and Transport Details
/mcpAdapts to client handshake or 2026-07-28 envelope
/2026-07-28/mcpPinned stateless 2026-07-28 Streamable HTTP
/2025-11-25/mcpPinned 2025-11-25 Streamable HTTP revision
/2025-06-18/mcpPinned 2025-06-18 Streamable HTTP revision
/2025-03-26/mcpPinned 2025-03-26 Streamable HTTP revision
/2024-11-05/ssePinned 2024-11-05 deprecated HTTP and SSE
/sseRoot endpoint negotiating any legacy revision over SSE
/healthSystem 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 NameIntentional Failure Trigger
get_weather, get_forecastcity argument set to Atlantis
geocodeaddress argument set to Atlantis
search_webquery argument set to error
get_stock_pricesymbol argument set to XXXX
convert_currencyfrom or to argument set to XXX
get_useruser_id argument set to missing
get_flight_statusflight_number argument set to XX000
read_file, delete_filepath argument set to /missing
send_emailto 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 MechanismInjected 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 headerForces 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

Dillip Chowdary

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

5-min tech signal

Weekday briefing for engineers who skip the noise.

No spam · Unsubscribe anytime

Advertisement

✈️ CareerPilot

Your AI job-search copilot

Match your resume against live Ashby, Greenhouse & Lever openings — fit scores, job-specific resume optimization and email alerts.

Find matching jobs →

Free Tools

Browse all tools →