DEV Community: Mockd

Give Your AI Agent a Mock Server: mockd as an MCP Tool

Mockd — Sun, 29 Mar 2026 20:58:07 +0000

Here's a scene that plays out a dozen times a day if you use an AI coding agent: you ask it to build something that calls an external API — a payment service, a notification system, an OAuth flow — and it writes beautiful code. Clean types, proper error handling, good structure. Then it stops. It can't actually run any of it, because the API it's calling doesn't exist locally and the agent has no way to spin one up.

So you get code that looks right but hasn't been tested against anything. The agent wrote a Stripe integration without ever seeing a Stripe response. It built a webhook handler without ever receiving a webhook. You're the one who has to close that gap, manually, every time.

I kept hitting this wall, and it's the reason mockd ships with 18 MCP tools built in.

What MCP gives your agent

MCP — Model Context Protocol — is the standard that lets AI agents call external tools programmatically. Instead of just reading and writing files, your agent can interact with services, APIs, and infrastructure through a structured interface.

mockd implements an MCP server that exposes everything an agent needs to create mock endpoints, send test traffic, inspect request logs, verify call counts, and inject failure conditions. All over stdio, no API keys required for local use.

The agent doesn't just develop against a mock server. It provisions and manages the mock server itself.

Setup: two minutes, zero config

Claude Code

Add this to your Claude Code MCP configuration:

{
  "mcpServers": {
    "mockd": {
      "command": "mockd",
      "args": ["mcp"],
      "env": {}
    }
  }
}

Cursor

In Cursor's MCP settings (Settings → MCP Servers), add the same configuration:

{
  "mcpServers": {
    "mockd": {
      "command": "mockd",
      "args": ["mcp"],
      "env": {}
    }
  }
}

This works with any MCP-compatible agent — Claude Code, Cursor, GitHub Copilot, Windsurf, JetBrains AI. The mockd mcp command speaks standard MCP over stdio, so anything that implements the protocol can use it.

One detail worth calling out: mockd mcp automatically starts a background daemon if one isn't already running. You don't need to manually run mockd start first. The agent connects, mockd boots up on port 4280 (mock server) and 4290 (admin API), and everything just works. Pass --data-dir if you want project-level isolation between different codebases.

A real workflow: "Build me a payment service"

Here's what actually happens when you ask an agent to build something against an external API, with mockd connected as an MCP tool.

You: "Build a payment service that integrates with Stripe. It should create charges, handle webhooks, and refund failed payments."

The agent's first move isn't writing application code. It calls manage_mock to create the Stripe endpoints it knows it'll need:

POST /v1/charges → returns a charge object with status: "succeeded"
POST /v1/refunds → returns a refund object
GET /v1/charges/:id → returns charge details
POST /webhook → a local endpoint for receiving Stripe events

Each mock returns realistic response structures — the agent knows what Stripe responses look like and configures the mocks accordingly.

Then it writes the application code. The payment service, the webhook handler, the refund logic. But here's the key difference: it can test every function as it writes it. The code hits http://localhost:4280/v1/charges, gets back a real HTTP response with a real JSON body, and the agent can verify the code actually works.

After writing the code, the agent calls verify_mock to check that the right endpoints were called the expected number of times. It calls get_mock_invocations to inspect the exact request bodies its code sent. It finds a bug — the refund handler is sending charge_id instead of charge in the request body — fixes it, and tests again.

Then it pushes further. It calls set_chaos_config to inject intermittent 500 errors on the charge endpoint, reruns the payment flow, and discovers the retry logic doesn't handle idempotency keys correctly. It fixes that too.

The agent just completed a development loop that would normally require you to set up a Stripe test account, manage API keys, deal with rate limits, and manually inspect webhook payloads. Instead, it did the whole thing itself in a few minutes.

The tools that matter most

mockd exposes 18 MCP tools total. You don't need to memorize them — the agent discovers them automatically through the MCP protocol. But these are the ones that get used constantly:

manage_mock — The workhorse. Create, list, get, update, delete, and toggle mock endpoints. This is how the agent builds out the API surface it needs.

verify_mock — Assert that a mock was called a specific number of times. The agent uses this to confirm its code is actually making the requests it should be.

get_mock_invocations — Retrieve the full request details for every call that hit a specific mock — headers, body, query parameters, timestamps. This is how the agent debugs what its code is actually sending.

get_request_logs — View all traffic that hit the mock server, not just matched requests. Useful when the agent's code is calling an endpoint that doesn't have a mock yet.

set_chaos_config — Inject latency, errors, and connection failures. The agent uses this to test its own error handling and retry logic.

manage_state — Create, read, update, and delete stateful resources. When the agent needs a mock that remembers data between requests — like a user record that persists after creation — this is how.

import_mocks — Import mock endpoints from an OpenAPI spec, Postman collection, or other formats. If the API the agent is integrating with has a spec, this bootstraps the entire mock surface in one call.

Resources: read-only context for the agent

Beyond tools, mockd also exposes MCP resources — read-only data the agent can access for context. There are 5 static resource URIs (mock://config, mock://mocks, mock://logs, mock://state, mock://chaos) and 8 dynamic resource patterns for drilling into specific mocks, invocations, and state entries.

In practice, the agent uses resources to understand the current state of the mock server before making changes. It reads mock://mocks to see what's already configured, checks mock://logs to see recent traffic, and uses that context to make informed decisions about what to create or modify next.

Why this changes the development loop

The fundamental shift is that your AI agent can now iterate on code and its test environment simultaneously. It's not writing code in a vacuum and hoping it works when it hits a real service. It's running a full development loop — write, test, inspect, fix, test again — with a real HTTP server returning real responses.

No rate limits. No API keys. No cost per request. No dependency on staging environments that might be down. No "works on my machine but I can't test the integration" gaps.

The agent gets real HTTP responses, not simulated ones. The code it writes has been tested against actual network calls. When you review the PR, the integration code has already been through dozens of iteration cycles against a mock that behaves like the real thing.

That's the gap I kept running into, and it's the gap that disappears when your agent has a mock server it controls.

What to know

The MCP transport is stdio only right now — local use. There's no remote or SSE transport, so this is a "your machine, your agent" setup. If you're hoping to share a mock server across a team via MCP, that's not how it works yet. The agent also can't change server configuration through MCP. It can create and manage mocks all day, but things like port numbers, TLS settings, and server-level config still require CLI flags or a config file. That's a deliberate boundary, not an oversight.

MCP tool responses can get chatty. If your agent has a small context window and you've got fifty mocks configured, calling manage_mock with action: "list" is going to eat a chunk of that context. Something to keep in mind if you're working with a constrained model. Trim your mocks or use targeted get calls instead of listing everything.

One more thing: mockd mcp auto-starts a background daemon, which is convenient right up until you forget it's running. The daemon doesn't shut down when the MCP session ends. You'll want to run mockd stop when you're done, or you'll find port 4280 still occupied next time you try to start something else there. Ask me how I know.

Get started

Install mockd, add the MCP config to your agent, and point it at a project that talks to external APIs. The agent will figure out the rest.

# Install mockd
curl -fsSL https://get.mockd.io | sh

# Start mockd — the MCP server auto-connects to this
mockd start

For detailed setup instructions, tool reference, and advanced configuration:

MCP Server Guide — Setup, tool reference, and resource URIs for all 18 MCP tools
Why AI Agents Need Mock Servers — The broader case for mock infrastructure in AI development

7 Protocols, 1 Binary, 0 Dependencies

Mockd — Sat, 28 Mar 2026 20:33:04 +0000

Last year I counted the mock tools running on my laptop. WireMock for HTTP (Java, 200MB Docker image). A custom Node script for WebSocket. Mosquitto for MQTT. A Go stub for gRPC. Four tools, four runtimes, four sets of config files, four ports to remember. I spent more time wiring up mock infrastructure than writing the code it was supposed to help me test.

So I built mockd. One binary:

mockd add http --path /api/orders --status 200 \
  --body '{"orders": [{"id": "{{uuid}}", "total": {{faker.price}}}]}'

Created mock: http_c9e4c315168bcfbe / Type: http / Method: GET / Path: /api/orders / Status: 200

curl http://localhost:4280/api/orders

{"orders": [{"id": "7e53e8ca-...", "total": 405.87}]}

HTTP done. Same binary, six more protocols to go.

All 7 protocols

Every protocol follows the same pattern: mockd add <type>, configure, hit the endpoint. No plugins. No extensions. No separate downloads.

GraphQL

mockd add graphql --path /graphql --operation GetUser \
  --response '{"id":"1","name":"{{faker.name}}","email":"{{faker.email}}"}'

Test it: curl -X POST http://localhost:4280/graphql -H 'Content-Type: application/json' -d '{"query":"{ GetUser }"}' returns {"data":{"GetUser":{"email":"alice684@mock.io","id":"1","name":"Charlie Brown"}}}.

gRPC

mockd add grpc --proto service.proto --service greeter.Greeter \
  --rpc-method SayHello --response '{"message": "Hello, {{faker.name}}!"}'

You provide the .proto file, mockd handles reflection and serialization. Port 50051 by default.

WebSocket

mockd add websocket --path /ws/chat \
  --message '{"event":"connected","ts":"{{now}}"}'

MQTT

mockd add mqtt --topic sensors/temp \
  --payload '{"temp":{{random.float 20.0 35.0}},"unit":"C","ts":"{{now}}"}'

Built-in MQTT broker on port 1883. No Mosquitto required.

SSE (Server-Sent Events)

mockd add http --path /events --sse \
  --sse-event 'update:{"ts":"{{now}}","cpu":{{random.int 10 95}}}'

curl -N http://localhost:4280/events streams event:update / data:{"ts":"2026-03-07T18:26:03-06:00","cpu":70}.

SOAP

mockd add soap --path /service --operation GetUser --status 200 \
  --response '<User><Id>1</Id><Name>{{faker.name}}</Name></User>'

Send a SOAP envelope with SOAPAction: GetUser, get back a properly wrapped response.

All together

ID                    TYPE       PATH             METHOD  STATUS  ENABLED
list-users            http       /api/users       GET     200     true
graphql_917e99253...  graphql    /graphql         GQL     -       true
websocket_91720db...  websocket  /ws/chat         WS      -       true
mqtt_4c28d4810103...  mqtt       :1883            MQTT    -       true
http_32897b6a3bd8...  http       /events          GET     -       true
soap_edc045dfba00...  soap       /service         SOAP    -       true
grpc_7a2ea7f56902...  grpc       :50051           gRPC    -       true

Seven protocols. One process. One config file. One set of logs.

Why Go, why single binary

I get asked this a lot. Go was chosen for three reasons:

Static binary. CGO_ENABLED=0 go build produces a single statically-linked executable. No shared libraries, no runtime, no interpreter. Copy it to any Linux/macOS/Windows machine and it runs. Docker image is distroless/static — no shell, no libc.

Goroutines. Each protocol listener runs in its own goroutine. HTTP, gRPC, MQTT, WebSocket — same process, none blocking each other. In Node that's clustering. In Java it's thread pools. In Go it's go serve().

Cross-compilation. GOOS=darwin GOARCH=arm64 go build from a Linux CI runner. Mockd ships six OS/arch binaries from a single GitHub Actions workflow.

The result is a 43MB binary containing all seven protocol servers, 34 faker functions, an admin API, and a request logger. No runtime to download. No plugins to install.

That matters in three places: CI/CD (curl -fsSL https://get.mockd.io | sh && mockd start — two seconds vs. pulling a 200MB Docker image), laptop onboarding ("install mockd" vs. "install Java 17 and Docker Desktop"), and air-gapped networks (a single binary can be SCP'd to a bastion host — try that with node_modules).

Shared internals

The seven protocols share core infrastructure:

Template engine — {{faker.name}}, {{uuid}}, {{now}}, {{random.int 1 100}} — same 34 faker functions across every protocol
Config — one YAML or JSON file defines all mocks across all protocols
Request logging — HTTP, GraphQL, gRPC, WebSocket, MQTT traffic in one unified log
Import — OpenAPI, Postman, HAR, WireMock, cURL, Mockoon, and WSDL formats
Chaos — 10 profiles and 12 fault types apply across HTTP, GraphQL, gRPC, and SOAP
MCP — 18 tools give AI agents programmatic access to everything

How this compares

Tool	Language	Protocols	Size	Runtime
mockd	Go	7 (HTTP, GraphQL, gRPC, WS, MQTT, SSE, SOAP)	43MB binary	None
WireMock	Java	HTTP (extensions for others)	~200MB Docker	JVM
Mockoon	Electron/Node	HTTP, GraphQL	~200MB app	Node
json-server	Node	REST	~2MB (+ Node)	Node
Prism	Node	HTTP (OpenAPI validation)	~50MB (+ Node)	Node
MockServer	Java	HTTP/HTTPS	~200MB Docker	JVM

WireMock is battle-tested with a huge plugin ecosystem. Mockoon has a desktop UI nothing else matches. json-server is dead simple for REST prototyping. Mockd's angle: all seven protocols from one tool, zero runtime dependencies, sub-second startup.

The honest part

43MB is not small. It's smaller than pulling a JVM or Node runtime, but it's not a 5MB CLI tool. Every protocol adds weight — gRPC alone brings in protobuf libraries. I could strip features to shrink the binary, but that defeats the point.

gRPC requires a .proto file. There's no way around this. gRPC is contract-driven — you can't hand-wave the schema like you can with HTTP. No .proto file, no gRPC mock. That's a protocol constraint, not a mockd constraint, but it still adds friction.

The MQTT broker is basic. QoS 0 and 1, topic wildcards, pub/sub. No clustering, no persistence, no QoS 2. For dev/test it's fine. For benchmarking against a real broker, use Mosquitto or EMQX.

SOAP exists because it has to. Banks, insurance, healthcare — I didn't add SOAP because I enjoy XML. I added it because developers at those companies deserve mock tooling that isn't "install a 2008 Java web server."

Install

brew install getmockd/tap/mockd
# or
curl -fsSL https://get.mockd.io | sh

Start the server and start adding mocks. Every protocol. One binary. Zero dependencies.

Learn more

Quickstart guide — create your first mock in under 60 seconds
All 7 protocols — full documentation for each protocol
Import from OpenAPI — convert existing API specs to mocks
Chaos engineering — fault injection across all protocols

Your AI Coding Agent Needs a Dev Environment Too

Mockd — Sat, 28 Mar 2026 03:01:16 +0000

I've been watching how AI coding agents actually work — not the demos, the real day-to-day usage — and something keeps standing out: we've optimized the wrong things.

Agents have great editors now. They can read files, write files, run tests, search codebases, manage git. The tooling around code manipulation is genuinely impressive.

What they can't do — what nobody seems to talk about — is run a development loop against the services their code depends on. And if you've built anything nontrivial in the last decade, that's where most real development happens.

The development loop problem

When you build a feature that talks to an external API — Stripe for payments, your team's user service, a third-party data provider — you need that service running and responding while you develop. You write code, test it, see what the API returns, adjust, test again. Tight loop.

AI agents do this loop too. Except faster. A lot faster.

A developer might hit an API endpoint 20–30 times while building a payment integration. They know the API, they've read the docs, they debug by reading error messages and adjusting carefully.

An AI agent doing the same work might hit that endpoint 200–400 times. It generates code, tests it, reads the response, adjusts, generates new code, tests again. Each iteration is cheap in human terms — it costs tokens, not hours — but each iteration still needs a real response from a real service.

And that's where everything falls apart.

What happens when agents hit real services

Three problems, in order of how much they'll derail your afternoon:

Rate limits. Stripe's test mode allows 25 requests per second. That sounds generous until an AI agent burns through it in a tight iteration loop, gets rate-limited, spends 400 tokens parsing the 429 response, backs off, retries, gets limited again, and eventually asks you what went wrong. Your agent just hit a wall that has nothing to do with the code it's writing.

Cost. Not every API has a free test mode. Third-party data providers, AI inference APIs, communication platforms — many charge per request even in sandbox environments. An agent making 200 exploratory calls during a feature build adds up fast. And unlike a developer who reads docs and makes targeted calls, agents are exploratory by nature. They try things. They test edge cases. That exploration has a dollar sign attached when it hits real services.

Availability. The API you depend on is maintained by a team in another timezone. They pushed a breaking change to staging at 3 PM their time — 7 AM yours. Your agent starts working at 8 AM and immediately hits 500 errors on every call. It doesn't know the staging environment is broken. It thinks its code is wrong. It spends 45 minutes rewriting perfectly good code to "fix" an error that isn't its fault.

Developers recognize these situations instinctively. We check Slack, we ping the other team, we context-switch to something else. Agents don't have that instinct. They see a broken response and conclude they need to write different code.

The gap in your local dev stack

We've actually solved most of the "AI agent needs local infrastructure" problem:

Filesystem? Agents have one.
Terminal? Built in.
Database? SQLite, Docker, your local Postgres — pick one.
Git? First-class support in every agent.
Editor/IDE integration? That's... what they are.

What we haven't solved: the services this application talks to over the network.

Your app makes HTTP requests to a user service. It connects to a WebSocket for real-time updates. It calls a gRPC service for search. It authenticates through an OAuth provider. Those services are remote, someone else owns them, and they may or may not be running right now.

That gap — the space between "my agent can edit code" and "my agent can develop against a real system" — is the bottleneck nobody's addressing. Your agent has every tool it needs to write code, and no way to verify that code works against the services it's designed to talk to.

Mock servers as agent infrastructure

I'll be direct: this is the reason I built mockd.

Not because mock servers are a new concept. WireMock has been around since 2011. json-server since 2013. The idea of returning fake responses from a local server isn't novel.

What's new is the role. Mock servers aren't just test utilities anymore. They're development infrastructure that makes AI agents productive. The same way a local database makes a developer productive — it's always there, it's fast, it's yours — a local mock server makes an agent productive against external service dependencies.

When you point an AI agent at a project that has a mock server running, the agent can:

Make unlimited API calls with zero rate limits
Get sub-millisecond responses instead of network-latency responses
Work against services that don't exist yet (the other team hasn't built them)
Work at 3 AM when staging is down for maintenance
Work in complete isolation from other developers and their agents
Hit intentional error responses you've configured, not accidental ones from broken staging

This isn't a test-time convenience. It's a development-time necessity.

Self-provisioning infrastructure

Here's where it gets interesting. With MCP (Model Context Protocol), an agent doesn't just develop against mock servers — it can manage them.

MCP is a standard protocol that lets AI agents call external tools programmatically. mockd exposes 18 MCP tools for creating endpoints, importing API specs, managing state, and inspecting request logs. Any MCP-compatible agent — Claude Code, Cursor, GitHub Copilot — can use them.

The workflow:

Agent reads the OpenAPI spec for the service you depend on
Agent calls mockd's import_mocks tool to create endpoints from the spec
Agent develops against those endpoints as if they're the real service

No human writes configuration. No human runs CLI commands. The agent provisions its own development infrastructure and immediately starts building.

This is a fundamentally different relationship between developer tools and AI. The tool isn't something the developer configures for the agent. The tool is something the agent configures for itself.

The cost math

Let's make this concrete.

A team of 10 engineers, each with an AI agent doing 4 hours of assisted development per day. Each agent averages 150 API calls to external service dependencies during that time.

Against real services:

Cost factor	Calculation	Daily cost
Metered API calls	10 agents x 150 calls x $0.01/call	$15
Rate-limit delays	~5 min/day/agent of wasted time	50 min lost
Staging downtime	10% availability issues = blocked agents	~2 hrs/day team-wide
Agent token waste	Debugging non-code errors (429s, 500s, timeouts)	Hard to quantify, but real

Against local mock servers:

Cost factor	Value
API calls	$0.00
Rate-limit delays	0 ms
Availability issues	0 (it's running on your machine)
Agent token waste	Near zero

The mock server isn't a nice-to-have optimization. It's the difference between your agent spending tokens on your feature and spending tokens fighting infrastructure it doesn't control.

This is just the beginning

Local mock servers for AI development is a bigger topic than one post can cover. Two things I haven't addressed yet: why "return 200 OK with some JSON" isn't enough (your agent needs realistic service behavior to build production-ready code), and how this scales when you have multiple teams with multiple agents all developing in parallel.

If you want to try this now:

# Install mockd
curl -fsSL https://get.mockd.io | sh

# Start the server
mockd start

# Create a mock endpoint
mockd add http --method GET --path /api/users \
  --status 200 \
  --body '[{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]'

Your agent now has an API it can develop against. No rate limits, no costs, no downtime.

Learn more

Quickstart guide — install mockd and create your first mock in under 60 seconds
All features — MCP server, AI mock generation, 7 protocols, recording proxy, and more
All 7 protocols — HTTP, gRPC, GraphQL, WebSocket, MQTT, SSE, SOAP
Cloud tunnel — share local mocks via a public URL with one command

DEV Community: Mockd

Give Your AI Agent a Mock Server: mockd as an MCP Tool

What MCP gives your agent

Setup: two minutes, zero config

Claude Code

Cursor

A real workflow: "Build me a payment service"

The tools that matter most

Resources: read-only context for the agent

Why this changes the development loop

What to know

Get started

7 Protocols, 1 Binary, 0 Dependencies

All 7 protocols

GraphQL

gRPC

WebSocket

MQTT

SSE (Server-Sent Events)

SOAP

All together

Why Go, why single binary

Shared internals

How this compares

The honest part

Install

Learn more

Links

Your AI Coding Agent Needs a Dev Environment Too

The development loop problem

What happens when agents hit real services

The gap in your local dev stack

Mock servers as agent infrastructure

Self-provisioning infrastructure

The cost math

This is just the beginning

Learn more

Links