mcp-mock

mcp
Guvenlik Denetimi
Basarisiz
Health Gecti
  • License — License: MIT
  • Description — Repository has a description
  • Active repo — Last push 0 days ago
  • Community trust — 11 GitHub stars
Code Basarisiz
  • network request — Outbound network request in scripts/fetch-schemas.ts
  • exec() — Shell command execution in src/auth/index.ts
  • process.env — Environment variable access in src/config.ts
Permissions Gecti
  • Permissions — No dangerous permissions requested

Bu listing icin henuz AI raporu yok.

SUMMARY

Self-hosted mock MCP server — test your MCP clients and agents with deterministic tools, resources and prompts, without connecting to real services. By Axium Lab.

README.md

mcp-mock: test your MCP integrations without real services

mcp-mock

License: MIT
Public instance
MCP spec
Release

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.

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.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+)

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

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
get_weather, get_forecast city: "Atlantis"
geocode address: "Atlantis"
search_web query: "error"
get_stock_price symbol: "XXXX"
convert_currency from or to: "XXX"
get_user user_id: "missing"
get_flight_status flight_number: "XX000"
read_file, delete_file path: "/missing"
send_email to: "[email protected]"

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 templates weather://{city}, user://{user_id} and file:///{path}, drawn from the same fake world as the tools.
  • Prompts: summarize, code_review and weather_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
_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.
_meta["com.mcp-mock/error"] on any request Fails it with the given JSON-RPC code, message and data.
_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.
_meta["com.mcp-mock/notifications"] on subscriptions/listen or resources/subscribe Scripts the change notifications the stream delivers (events, intervalMs, close).
_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.
x-mcp-mock-status: 503 header Forces an HTTP failure from 400 to 599 on any endpoint; 429 adds Retry-After.
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 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.

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:

  • 401 with WWW-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 with code and iss; /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, and mcp_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.

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

Configuration

Variable Default Meaning
MCP_MOCK_PORT (or PORT) 3000 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

MIT

Yorumlar (0)

Sonuc bulunamadi