# mockserver — MCP server card for AI agents

Mock, record/replay, verify and chaos-test any HTTP, REST, gRPC or LLM dependency over MCP.

Registry name: `com.mock-server/mockserver` · category: Developer tools · version 9.4.0 · updated 2026-11-20

## Connect
- Docker (stdio): `docker run -i --rm docker.io/mockserver/mockserver:9.4.0`

## Facts
- Repository: https://github.com/mock-server/mockserver-monorepo (5,011 stars)
- Website: https://www.mock-server.com

Before you connect a server: read its repository, and give it only the permissions and keys it needs.

## Links
- AgentGid page: https://agentgid.com/mcp/servers/com-mock-server-mockserver/


## MockServer: fake the services your app calls, by asking

MockServer is a free test tool that stands in for the outside services your app talks to, such as a payment service or an AI model. Its built-in connector lets your AI assistant set up fake answers, record real traffic and check which calls your app made, all in plain words. It runs on your own computer, for example with Docker.

### Where to use it
- Fake a service that is not ready yet: Your app needs a health check or a partner's service that does not exist yet. Ask the assistant for a fake answer and keep building.
- Record a real service, then replay it: Let real traffic pass through once and be recorded, then turn the recording into fakes. Tests then run without the real service.
- Check that your app made the right calls: After a test, ask whether your app called the payment service exactly once, or in the right order.
- Find out why a request got a 404: When a call hits no fake, the assistant shows the closest one and what to change, so you stop guessing.
- Test your AI agent without paying for the model: Fake answers from OpenAI, Anthropic and other model providers, including failures and retries, so agent tests are free and repeatable.
- Check a connector you built yourself: If you build your own MCP server, point this tool at it to check that it answers the protocol's basic calls correctly.

### How to start
- Start MockServer on your computer with Docker (Homebrew, a Java JAR and other ways also work).

```
docker run -d --rm -p 1080:1080 mockserver/mockserver
```

- Add its built-in server to your assistant.

```
claude mcp add mockserver --transport streamable-http http://localhost:1080/mockserver/mcp
```

- Ask for a first fake and call it to check.

```
curl -v http://localhost:1080/api/health
```


### License
MockServer is free and open source under the Apache 2.0 license, also for paid work. It is meant for testing only, never for a live public service.

### Good to know
- Test machines only. Never run it on a live server or on a network that strangers can reach.
- The connector is on by default on every running MockServer. Anyone who can reach its port can drive it, unless you add its login checks or switch it off.
- One tool, stop_server, shuts MockServer down at once, and reset wipes every fake and recording.
- The drift check calls the real model provider with your own key, so it costs money; the docs keep it out of every test run.
- Recordings saved to files hide passwords in headers, but not inside message bodies. Read them before you share them.

Checked 2026-11-10 against: https://github.com/mock-server/mockserver-monorepo/blob/d68a943b88569d0fdfa6ed275ccbc31cde186c75/README.md, https://github.com/mock-server/mockserver-monorepo/blob/d68a943b88569d0fdfa6ed275ccbc31cde186c75/server.json, https://github.com/mock-server/mockserver-monorepo/blob/d68a943b88569d0fdfa6ed275ccbc31cde186c75/SECURITY.md, https://github.com/mock-server/mockserver-monorepo/blob/d68a943b88569d0fdfa6ed275ccbc31cde186c75/LICENSE.md, https://github.com/mock-server/mockserver-monorepo/blob/d68a943b88569d0fdfa6ed275ccbc31cde186c75/changelog.md, https://github.com/mock-server/mockserver-monorepo/blob/d68a943b88569d0fdfa6ed275ccbc31cde186c75/mockserver/mockserver-netty/src/main/java/org/mockserver/netty/mcp/McpToolRegistry.java, https://github.com/mock-server/mockserver-monorepo/blob/d68a943b88569d0fdfa6ed275ccbc31cde186c75/jekyll-www.mock-server.com/mock_server/_includes/mcp_configuration.html, https://github.com/mock-server/mockserver-monorepo/blob/d68a943b88569d0fdfa6ed275ccbc31cde186c75/examples/curl/mcp/README.md, https://www.mock-server.com/, https://www.mock-server.com/mock_server/ai_mcp_setup.html, https://www.mock-server.com/mock_server/ai_mcp_tools.html

### Mistakes to avoid
- Don't: Adding the connector before MockServer is running → Do: Start it first (docker run -d --rm -p 1080:1080 mockserver/mockserver), then add http://localhost:1080/mockserver/mcp (The connector lives inside a running MockServer; there is nothing to connect to otherwise.)
- Don't: Using create_expectation to match headers, cookies or a request body → Do: Use raw_expectation with full MockServer JSON for those matches (create_expectation rejects parameters outside its small input list.)
- Don't: Running detect_llm_drift in every commit's test run → Do: Run it in an opt-in or scheduled job, with a backend key set up on purpose (It calls the real provider with your key, so it costs money and gives changing results.)
- Don't: Committing fixture files from record_llm_fixtures without reading them → Do: Pass redactBodyFields for body fields with secrets, then review the file (Headers are redacted, message bodies are not.)
- Don't: Exposing port 1080 of a shared or cloud machine to the internet → Do: Keep it on localhost or a private test network (MockServer is a test tool with features that are unsafe on an open network.)

### Questions
- Does it cost anything or need an account? No. It is open source under Apache 2.0 and runs on your own machine; the connector needs no sign-in by default.
- Which assistants does it work with? The docs show setups for Cursor, Claude Code, Windsurf, Cline, Continue and OpenCode, plus code libraries such as LangChain.
- Do I need Java? Not with Docker; the image brings its own. The JAR needs Java 17 or newer.
- Can I turn the connector off? Yes. Set MOCKSERVER_MCP_ENABLED=false (or -Dmockserver.mcpEnabled=false); the default is on.

---
AgentGid's catalog is curated: every entry was checked against the maker's official pages (registry, repository, license and pricing pages) on the date shown; a license value shows the quote it stands on wherever AgentGid has one. Usage numbers come from AgentGid's own scan of public repositories set up for AI coding agents. Claims by makers are reported, not tested by AgentGid.
