Mockserver

What mockserver does

MockServer provides a single test and development service for replacing, observing, and modifying application dependencies. Through its built-in MCP endpoint at /mockserver/mcp, AI agents can drive MockServer while working on integration tests, local development, or failure scenarios.

The underlying service can return fixed, templated, or callback-generated responses; proxy requests to real services; record traffic for later replay; and verify that expected requests were received. It can also inject latency, dropped connections, and errors to exercise application behavior when dependencies fail.

MockServer accepts connections for HTTP/1.1, HTTPS, HTTP/2, gRPC, gRPC-Web, WebSockets, and raw TCP. It also supports JSON-RPC scenarios for MCP and A2A mocking, AsyncAPI-driven testing with Kafka and MQTT brokers, and chat-completion APIs from OpenAI, Anthropic, Gemini, Bedrock, Azure OpenAI, and Ollama, including streaming responses.

How it works

MockServer listens on a port and identifies the protocol from the initial connection data. Expectations define how incoming requests are matched and which responses should be returned. Matching can use the HTTP method, path, query parameters, headers, cookies, and request body. Body matching supports JSON, XML, JSONPath, XPath, and regular expressions.

The service can operate as a mock, a proxy, or both. Proxy modes include port forwarding, HTTP proxying, HTTPS tunneling, and SOCKS. A live dashboard and REST control plane are available on the same service, allowing clients and test code to configure expectations and inspect activity.

OpenAPI or Swagger definitions can be used to generate mocks instead of defining each expectation manually. Optional clustered state supports multi-instance deployments.

Setup and configuration

A Docker deployment can be started with:

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

The service then listens on port 1080. A Homebrew installation is available on macOS and Linux, and the mockserver command can run the service directly. Other distribution options include a GitHub Container Registry image, Helm, Maven artifacts, a WAR, an npm package for starting and stopping the service, and Testcontainers modules.

The MCP endpoint is available at /mockserver/mcp. The REST control plane uses the same port, and the dashboard is available at /mockserver/dashboard. Client libraries are provided for Java, JavaScript/Node, Python, Ruby, Go, PHP, .NET, and Rust.

Java 17 or newer is required when running the server with a local JVM. The official Docker image includes its own JVM, so container users do not need to install Java separately.

Tools and capabilities

• Create expectations for HTTP and related dependency calls.
• Return fixed, templated, or callback-based responses.
• Record, inspect, modify, and replay proxied traffic.
• Verify that requests matching specified criteria were received.
• Generate mocks from OpenAPI or Swagger specifications.
• Inject latency, connection drops, and errors for chaos testing.
• Mock supported LLM chat-completion APIs, including streaming.

Limitations and notes

MockServer is intended for development and testing only, not production use. Local JVM deployments require Java 17 or newer; the Docker image avoids that separate runtime requirement. HTTP/3 support is experimental. Protocol coverage and behavior depend on the MockServer service configuration and the expectations supplied through its control interfaces.