mcp-mock
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.

mcp-mock
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 athttps://public.mcp-mock.com/mcpand start in seconds; no download, no signup, no API key.
From the team behind llm-mock.
Quick start
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.Run your own
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.0See 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+)Related MCP server: mock-llm-mcp
Endpoints
Every endpoint is served on the public instance, https://public.mcp-mock.com, and on your own (http://localhost:3000 by default).
URL | Serves |
| Any client. Each request is served in the era it opens with: a request carrying the 2026-07-28 |
| Only 2026-07-28, the stateless revision. |
| Only that legacy revision, over Streamable HTTP. |
| The deprecated HTTP+SSE transport. The pinned one speaks only 2024-11-05; the root one negotiates any legacy revision. |
| Every endpoint above again, behind OAuth. See OAuth. |
|
|
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.
What it serves
Tools
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 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 and prompts
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_reviewandweather_report, the last with the city's weather embedded as a resource.
Controlling answers from the test
Each request carries what its own answer must be: identical requests always get identical answers, and nothing is shared between requests.
Control | Effect |
| Replaces the result with the given |
| Fails it with the given JSON-RPC |
| Answers |
| Scripts the change notifications the stream delivers ( |
| Makes a task of the call ( |
| Forces an HTTP failure from 400 to 599 on any endpoint; |
await client.callTool({
name: "get_weather",
arguments: { city: "Madrid" },
_meta: { "com.mcp-mock/response": { structuredContent: { city: "Madrid", temperature: 40 } } },
});Faithful to each revision
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 |
|
|
|
| none: |
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 |
|
|
Resource not found |
|
|
|
|
|
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.
OAuth
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:
401withWWW-Authenticatepointing 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/authorizeapproves at once and redirects back withcodeandiss;/oauth/tokenhandles the authorization code grant with PKCE S256 and refresh tokens;/oauth/registerhandles Dynamic Client Registration.Tokens must be issued for the very endpoint they are used on, and carry the
mcpscope (403 insufficient_scopeotherwise).To provoke failures: the
mcp-mock:denyscope makes the user deny access, andmcp_mock_expires_inon 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.
Docker
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.0Tag | Points to |
| That exact release. Pin this one in CI so your tests don't change under you. |
| The latest patch release of 0.1. |
| 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.0Configuration
Variable | Default | Meaning |
|
| Port to listen on. |
Not supported yet
stdio, Origin header validation, and sessions on the legacy revisions. Tell us what you need in the Discussions.
Contributing
See CONTRIBUTING.md and the CHANGELOG.
License
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Self-hosted MCP server: 26 deterministic dev, security, and EVM tools.
AI-native mock API server with MCP. Create REST/SOAP mocks from Claude, Cursor, or Windsurf.
Hosted MCP endpoint with realistic fake data for prototyping agents. 12 tools, no setup.
Email inboxes, webhook URLs, mock APIs and 170+ tools for coding agents over one MCP connection.
Related MCP Servers
- AlicenseBqualityDmaintenanceA mock MCP server for testing MCP client implementations and development workflows. Supports tools, prompts, and resources across multiple transport protocols (stdio, HTTP, SSE).1MIT

mock-llm-mcpofficial
AlicenseNot gradedqualityDmaintenanceMCP server to mock OpenAI, Anthropic, and Google Gemini responses for testing AI integrations without real API keys or token spend.MIT- AlicenseNot gradedqualityCmaintenanceServes deterministic MCP protocol fixtures generated from tool contracts, enabling testing of MCP clients, gateways, and agent harnesses without live credentials or external services.MIT
- FlicenseNot gradedqualityFmaintenanceEnables config-driven mocking of MCP servers for AI skill evaluation, dynamically registering tools from a schema and returning configurable static, fixture-based, or LLM-generated responses.-