Mock MCP Server

MockMCP

Hosted MCP endpoint returning realistic fake data for prototyping agents. Paste one URL, zero setup.

Live at mockmcp.io — https://mockmcp.io/mcp

Built for devs who want to prototype agent workflows without wiring up a backend, writing fixtures, or standing up a local MCP server. 12 pre-built tools covering the scenarios in most agent tutorials.

Try it

# Initialize a session and get back a session id
curl -i -X POST https://mockmcp.io/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"0.1"}}}'

# Use the Mcp-Session-Id header in subsequent calls:
curl -X POST https://mockmcp.io/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: <paste-id-here>" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_users","arguments":{"limit":3}}}'

Connect your client

Claude Code

claude mcp add --transport http mockmcp https://mockmcp.io/mcp

Cursor — add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mockmcp": {
      "url": "https://mockmcp.io/mcp"
    }
  }
}

Claude Desktop — Settings → Connectors → Add custom connector → paste https://mockmcp.io/mcp as the URL.

No mcp-remote proxy required. All three clients speak Streamable HTTP natively.

Tools

All data is seeded from your inputs — same input, same output.

Limits

Free tier, per hashed IP + User-Agent fingerprint:

• 30 requests per minute
• 500 requests per day

Hit the wall? Drop your email at mockmcp.io/waitlist for paid-tier access when it launches.

429 responses carry a structured JSON-RPC error with upgrade_url and retry_after_seconds. Every successful response carries X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and X-RateLimit-Scope headers.

Run locally

npm install
npm run dev

Server listens on http://localhost:3000. MCP endpoint at /mcp. Without Upstash env vars, rate limiting falls back to an in-memory store (per-process, fine for dev).

Stack

• @modelcontextprotocol/sdk — MCP server + Streamable HTTP transport
• Raw Node http — no framework overhead, clean shutdown
• @faker-js/faker — deterministic fake data via seeds
• @upstash/ratelimit + @upstash/redis — sliding-window rate limiting
• zod — tool input validation

Deploy (for forks)

Targets Node 20+. Build + start are pinned via nixpacks.toml; health checks + restart policy via railway.json.

1. Fork this repo, push to GitHub.
2. Railway → New Project → Deploy from GitHub → pick your fork.
3. Add env vars in Railway → Variables:

1. Railway service → Settings → Networking → Custom Domain → paste your domain → follow the DNS instructions.

Health check

GET /health returns {"ok":true}. Railway pings this during deploy.

Waitlist signups

POST /api/waitlist logs a structured JSON line per signup:

{"event":"waitlist_signup","email":"alice@example.com","at":"2026-04-24T19:33:06.396Z"}

Grep them with railway logs | grep waitlist_signup. Storage-free by design — swap in Resend, a Tally forward, or a DB when the paid tier is live.

License

MIT — see LICENSE.