Sharing & Scaling

MCP Server

What this actually is

MCP (Model Context Protocol) is a spec for how an AI application — Claude Desktop, Claude Code, or anything else that speaks it — talks to external tools. An MCP server is a small program that exposes a fixed set of callable functions ("tools"), each with a name, a description, and a typed input schema; an MCP client (Claude) launches that program, asks it what tools it has, and calls them when the conversation calls for it.

mockbase-mocks is one such server. It exposes 8 tools — list_mocks, get_mock, create_mock, update_mock, delete_mock, list_request_logs, list_counters, reset_counter — each a thin wrapper around one call to MockBase's own management API (/api/v1/mocks/...), authenticated with your personal API key. There is no MCP-specific backend endpoint and no second schema to keep in sync: every tool does exactly what the matching curl command in Mock as Code does, just invoked by the model instead of typed by you.

It's published on npm as mockbase-mcp-mocks — your MCP client's own npx runs it directly, nothing to clone or install by hand. When your MCP client starts it, it runs as a child process on your machine and talks to the client over stdin/stdout (JSON-RPC messages — the "stdio transport"). It does not open a network port and nothing can connect to it remotely. When a tool is called, the script makes one outbound HTTPS request to https://mockbase.org (or wherever MOCKBASE_API_URL points), waits for the response, and hands it back to the model as text. There is no persistent connection to MockBase, no polling, no background activity between tool calls.

Prerequisites

  • Node.js 18 or later — npx ships with Node, and the script itself uses the global fetch() API, which Node only ships without a flag from v18 onward. Check with node --version; get it from nodejs.org if you don't have it.
  • An MCP client: Claude Desktop or Claude Code are what the steps below cover; any other MCP-compatible client works the same way in principle, since this is a standard stdio server.

Setup, step by step

1. Generate a personal API key

In the dashboard, go to Account → API keys and click Generate. Give it a name you'll recognize later (e.g. "Claude Desktop") — this matters once you have more than one key and need to tell them apart in the list. The plaintext key (starting with mbpat_) is shown exactly once, in a copyable box. Copy it now; if you navigate away without copying it, it's gone for good and you'd need to generate a new one (the server never stores the plaintext, only a hash of it — this is the same reason GitHub, Stripe, etc. only show you a token once).

2. Point your MCP client at it

No download, no install step, no path to find first — your MCP client's npx call fetches mockbase-mcp-mocks from npm on first use and caches it after that.

Claude Desktop. Open Settings → Developer → Edit Config. This opens claude_desktop_config.json in your default editor — its actual location is:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

Merge this into the mcpServers object (if the file already has other servers configured, add "mockbase-mocks" as a sibling key, not a replacement for the whole file):

json
{
  "mcpServers": {
    "mockbase-mocks": {
      "command": "npx",
      "args": ["-y", "mockbase-mcp-mocks"],
      "env": {
        "MOCKBASE_API_URL": "https://mockbase.org",
        "MOCKBASE_API_KEY": "mbpat_your_key_here"
      }
    }
  }
}

Save the file and fully restart Claude Desktop (quit it, don't just close the window). On startup it reads this file, runs npx -y mockbase-mcp-mocks as a child process for every server listed, and asks each one what tools it has.

Claude Code — no file to hand-edit, one command:

bash
claude mcp add mockbase-mocks \
  --env MOCKBASE_API_URL=https://mockbase.org \
  --env MOCKBASE_API_KEY=mbpat_your_key_here \
  -- npx -y mockbase-mcp-mocks

Everything after the bare -- is the exact command Claude Code will run to start the server; the --env flags before it set the environment variables the server reads on startup.

Running your own MockBase instance instead of the hosted one? Change MOCKBASE_API_URL to that instance's address (e.g. http://localhost:18000 for a local dev backend) — everything else is identical.

Contributing to the server itself, or want a specific version pinned instead of whatever npx resolves as latest? Clone the repository, run npm install inside mcp-servers/mocks, and point command/args at node and that folder's index.js directly instead of at npx — same tools, same behavior.

3. Confirm it's connected

Claude Desktop shows a small tools/hammer icon in the message composer once at least one server is connected; clicking it lists mockbase-mocks and its 8 tools. In Claude Code, run claude mcp list — a working server shows as connected, not failed. If it doesn't show up, see Troubleshooting below before assuming it's a MockBase-side problem.

4. Try it

Ask something like: "List my MockBase mocks", or "Create a MockBase mock that simulates a flaky payments API — GET /charge should succeed most of the time but fail with a 503 about 20% of the time." For the second one, the model would call create_mock with a route roughly like {"method": "GET", "path": "/charge", "status_code": 200, "response_body": {"status": "ok"}, "chaos_error_rate": 0.2, "chaos_error_status": 503} — the same JSON shape as the dashboard and the CLI use, because it's the same API.

Tool reference

Every tool below maps to one HTTP call. Fields not mentioned take the same default the dashboard would use (see the linked schema docs for the full field list on routes).

list_mocks

GET /api/v1/mocks, no arguments. Returns every mock the account owns, with routes replaced by a route_count integer — a mock's full route list can be long, and an agent deciding which mock to look at next doesn't need every route's response body just to pick one. Example result entry:

json
{ "mock_id": "aBcD1234efGh", "name": "Payments API", "route_count": 3, "require_token": false, "subdomain": null, "created_at": "2026-01-01T00:00:00Z" }

get_mock

GET /api/v1/mocks/{mock_id}. Input: mock_id (string, required). Returns the mock in full, routes included — this is what you use once you know which mock you want and need its actual configuration.

create_mock

POST /api/v1/mocks. Input fields, all optional:

FieldTypeDefaultNotes
namestring, ≤120 chars"Untitled Mock"
routesarray of route objects[]See Conditional Matching, Dynamic Templates, Chaos Injection, Counters for what a route can contain
require_tokenbooleanfalseRequires Authorization: Bearer <token> on the mock's own public endpoint
record_target_urlstringnoneRecord & Replay upstream
default_responseobject or omittednoneServed when no route matches
datasetsobject{}Named test-data tables, capped at 10 per mock / 500 rows each
scenariosarray of strings[]Named states this mock can be switched between — see Scenarios
active_scenariostring or omittednoneWhich scenario is live for a request with no X-Mock-Scenario header override

Returns the created mock, including the server-assigned mock_id and its public endpoint shape (https://mockbase.org/mock/<mock_id>/<path>).

Because a personal API key can only belong to a signed-in account, none of the anonymous-session limits (3 mocks, 10 routes) apply to anything created this way. Chaos injection, token protection, and custom subdomains aren't gated behind an account or plan at all, so those were never a concern here; callouts and Record & Replay specifically require a signed-in identity (since they make a real outbound request on the account's behalf), which a personal API key always satisfies.

update_mock

PATCH /api/v1/mocks/{mock_id}. Input: mock_id (required) plus any of the create_mock fields, all still optional — but only the ones you actually pass are changed. The one sharp edge: routes and datasets are whole-value replacements, not merges, exactly like saving the route editor in the dashboard does. Passing routes with 2 entries when the mock currently has 5 deletes the other 3; it does not append. scenarios is a whole-list replacement the same way. Every update is snapshotted automatically first (see Version History), so an update that goes wrong is one restore away from undone.

delete_mock

DELETE /api/v1/mocks/{mock_id}. Input: mock_id. Permanently deletes the mock and everything it accumulated — request logs, stateful CRUD data, counters, version history. Cannot be undone (though version history for a still-existing mock can undo an update; there is no undo for a delete).

list_request_logs

GET /api/v1/mocks/{mock_id}/logs?limit=N. Input: mock_id (required), limit (1–500, default 100). Returns the mock's most recent real traffic — method, path, status code, latency in ms, client IP, headers (sensitive ones like Authorization redacted), query params, request body, and response body — the same data the dashboard's live Request Inspector shows, as a static snapshot rather than a live stream. This is the tool that turns "why does my mock return 404 for that request" into something an agent can actually investigate instead of guessing.

list_counters

GET /api/v1/mocks/{mock_id}/counters. Input: mock_id. Returns every named counter on the mock and its current integer value, e.g. {"hits": 7, "attempts": 2}. Empty object if the mock doesn't use counters.

reset_counter

DELETE /api/v1/mocks/{mock_id}/counters/{name}. Input: mock_id, name. Resets one counter back to zero (removes its key entirely; the next increment starts it back at 1). Succeeds even if the counter didn't exist — there's nothing to confirm before resetting, unlike deleting a mock.

How errors show up

Every tool funnels backend errors through the same path: an HTTP status that isn't 2xx becomes a tool result with isError: true and text in the form "<status>: <detail>" — for example "404: Mock not found." or "402: Callouts is not available on your plan." (a 402 from this server would only happen if an admin ever closes a currently-open feature to your account's tier — a personal API key is always a signed-in identity, so it never hits the anonymous-only gate). The model sees this exactly like it sees any other tool error and can react to it — retry with corrected input, tell you what went wrong, or ask you what to do next. Nothing crashes the connection to the other tools; one failed call doesn't take down the session.

Scope and authority

A key gives whoever (or whatever) holds it the same authority as being logged into the dashboard with that account: create, edit, or delete any mock that account owns, not just ones the agent itself created. It cannot reach another account's mocks, blog posts, docs, billing, or team settings — the backend enforces ownership the same way it does for the dashboard and the CLI, by resolving the key to a user:<id> identity and checking every mock access against that id.

Treat handing an agent this key the same way you'd treat handing it a password: don't paste it into a shared config file, don't commit it, and revoke it from Account → API keys the moment you're done with it or if you ever suspect it leaked. Revocation takes effect on the very next request — there's no cache or delay to wait out.

Troubleshooting

The server doesn't show up / shows as failed. Almost always a config problem, not a MockBase problem: check the JSON in claude_desktop_config.json is actually valid (a trailing comma breaks the whole file silently), that npx is on your PATH (it ships with Node, so this usually means Node itself isn't installed or isn't on PATH), and that you fully restarted the client after editing.

Tool calls fail with "401: ..." — the key is missing, mistyped, or has been revoked. Regenerate one from Account → API keys and update the config.

Tool calls fail with "403: You do not own this mock." — the mock_id you gave belongs to a different account than the one the key authenticates as. Double-check the id with list_mocks first.

npx hangs or the server won't start — confirm node --version is 18 or higher; earlier versions don't have the built-in fetch the script relies on. The very first run also has to download the package, which is slower than every run after — give it a few seconds before assuming it's stuck.

Limitations, as of now

  • Stdio transport only. No remote/HTTP transport, so this always runs as a local child process next to your MCP client — it can't be pointed at from a different machine.
  • No pagination beyond limit. list_request_logs takes a limit (up to 500) but not an offset/cursor; there's no tool for paging through a mock's full history.
  • No API-key management from within the server. You can't create or revoke a personal API key through these tools — that's deliberately dashboard-only, so a compromised key can never be used to mint itself a replacement.
  • No team-workspace switching. A key acts as the personal account it belongs to; managing a team's shared mocks through this server isn't currently supported (use the dashboard for those).