Coding agents keep hitting the same wall humans do: the frontend they're writing needs an API that doesn't exist yet. The usual agent workarounds are all bad — hardcode JSONPlaceholder (fixed schema, fake writes), generate an MSW handler file (more code to maintain, only exists inside the test process), or scaffold an Express server (now your "mock" has a package.json, a port, and a lifecycle).
Mockbird is a hosted mock REST API service, and it ships a hosted MCP server. Add one URL to your MCP client config and your agent gets eight tools that create and drive real, live mock backends: seeded multi-resource projects, OpenAPI/db.json/Postman/CSV import, record CRUD, custom routes, snapshots. No signup, no API key, no OAuth dance — the connection just works.
# Claude Code
claude mcp add --transport http mockbird https://HOST/mcp
# Cursor / Windsurf / any client that reads mcp.json
{ "mcpServers": { "mockbird": { "url": "https://HOST/mcp" } } }
# VS Code
code --add-mcp '{"name":"mockbird","type":"http","url":"https://HOST/mcp"}'The transport is stateless Streamable HTTP (spec 2025-06-18; older
2025-03-26 and 2024-11-05 clients work too). No session juggling, no SSE requirement, no
server to install — it's the same Cloudflare Worker that serves the mocks. Mockbird is also
listed in the official MCP Registry as
dev.workers.mockbird.mockbird/mockbird.
| Tool | What it does | Needs adminKey? |
|---|---|---|
create_project | New mock API — blog / ecommerce / saas preset or blank. Returns {id, adminKey, baseUrl}. | — |
import_data | OpenAPI 3.x / Swagger 2.0, json-server db.json, Postman Collection v2.x, or CSV → live seeded API. Auto-detected. | — |
add_resource | Add a collection from a template (users, products, …) or explicit typed fields; seeds realistic fake records. | yes |
project_info | Root index: resources, record counts, URLs, export links. Works on demo. | no |
query_records | GET with the full query toolkit: filters, _gte-style operators, search, sort, pagination, select, relations, and failure simulation (mock_status, mock_delay, mock_chaos…). | no |
write_record | POST / PUT / PATCH / DELETE — writes persist. | no |
custom_route | Define /health, /config/:key, catch-all /webhooks/* bins, templated bodies. | yes |
snapshots | Save / restore / list / delete full-dataset snapshots — deterministic fixtures for the tests your agent writes. | yes |
Every tool dispatches through the same code paths as the public HTTP API, so the
request inspector, daily caps, and anonymous per-IP limits apply
identically. The adminKey returned by create_project is shown once —
well-behaved agents save it into the project's .env.
Prompt your agent with something like:
"Create an ecommerce mock API with Mockbird and point this app's
.env at it. Then write a Playwright test that checks the empty-cart
state using a snapshot."A capable agent will: call create_project with preset: "ecommerce"
(one call — products, orders, customers, reviews, all seeded), write
VITE_API_URL=<baseUrl> into .env, call snapshots
with action: "save" after emptying the fixture data it needs, and pin that
scenario in tests via mock_snapshot=<name> in query_records
params — the same snapshot pinning humans use,
no restore races between parallel workers.
The important part: the mock itself stays plain HTTP. The code your agent writes ships with a working URL — you can curl it, open it in a browser, hand it to a teammate, or run CI against it after the agent session ends. The mock isn't trapped inside the agent's tool sandbox.
You can drive the whole thing from curl — useful for debugging what your agent sees:
# list the tools
curl -s -X POST https://HOST/mcp -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# call one: the shared demo project's index
curl -s -X POST https://HOST/mcp -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{
"name":"project_info","arguments":{"project":"demo"}}}'
# query with projection + pagination
curl -s -X POST https://HOST/mcp -H 'content-type: application/json' \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{
"name":"query_records","arguments":{"project":"demo",
"resource":"products","params":{"_limit":2,"select":"name,price"}}}}'All three run against the live server right now — the last one returns two products with
just id, name, price.
Honest answer: agents can already use Mockbird with plain HTTP — that's why
/llms.txt exists, and agent traffic does arrive that way. MCP adds
three things: discovery (the agent finds typed tools with descriptions instead
of reading docs into context), fewer tokens (tool results are trimmed and
capped at 50 KB, with a hint to use select/_limit when truncated), and
fewer mistakes (input schemas encode the gotchas — field types, which calls
need the adminKey — so the agent doesn't learn them by 400ing). If your agent runs fine on raw
HTTP, nothing forces the switch.
Limits, honestly: tool calls share the project's 10,000 requests/day cap and anonymous project creation is limited to 10/IP/day (the MCP server forwards your real client IP for caps — one shared egress IP for a big agent fleet will hit it). Responses are JSON only, no streaming. The server is stateless, so clients that require session-id handshakes fall back to sessionless mode per spec. And the data is mock-grade: this is for building against an API shape, not for storing anything you care about. Full reference in the docs.
More guides: deterministic test data · mock server from an OpenAPI spec · testing loading & error states · free mock API tools compared. Create your API →