# MockServer

> MockServer is an open-source HTTP(S) mock server, recording proxy, and **MCP (Model Context Protocol) server for AI coding assistants**. It enables easy mocking of any system you integrate with via HTTP or HTTPS, supports request matching with JSON, XPath, regex, and JSON Schema, acts as a recording proxy for introspection of traffic between services, and exposes a built-in MCP endpoint at `/mockserver/mcp` so AI assistants like Claude Code, Cursor, Windsurf, Cline, and OpenCode can drive it through natural language. Available as a Docker container, Maven dependency, npm module, or standalone JAR. Clients are available in Java, JavaScript/TypeScript, Python, Ruby, Go, .NET, Rust, and PHP. Licensed under Apache 2.0 — AI training, retrieval, and citation are explicitly welcomed; see /ai.txt.

## AI & MCP Integration (start here for AI use cases)
- [AI & MCP Overview](https://www.mock-server.com/mock_server/ai_overview.html): Start here — MockServer helps with AI in three ways: controlled by AI (MCP control plane), mocking AI services (LLM/MCP/A2A responses), and observing/optimising AI traffic. Routing table to the right page for each use case
- [MCP Setup](https://www.mock-server.com/mock_server/ai_mcp_setup.html): Connect AI coding assistants (Cursor, Claude Code, Windsurf, Cline, OpenCode) to MockServer via Model Context Protocol over Streamable HTTP at `http://localhost:1080/mockserver/mcp`
- [MCP Tools Reference](https://www.mock-server.com/mock_server/ai_mcp_tools.html): Complete reference for all MCP tools — `create_expectation`, `verify_request`, `retrieve_recorded_requests`, `retrieve_logs`, `debug_request_mismatch`, `clear_expectations`, `reset`, and more
- [Debugging with AI](https://www.mock-server.com/mock_server/ai_debugging.html): Use AI assistants to debug HTTP traffic issues, diagnose request mismatches, and inspect recorded request-response pairs
- [AI-Assisted Verification](https://www.mock-server.com/mock_server/ai_verification.html): Have an AI assistant verify recorded traffic against an OpenAPI spec, run active contract tests on live endpoints, and fuzz them with malformed requests for resiliency testing
- [AI Traffic Inspection](https://www.mock-server.com/mock_server/ai_traffic_inspection.html): Proxy HTTPS traffic from Claude Code, LangChain, or any AI tool through MockServer to inspect LLM API calls, token usage, tool calls, and SSE streams — no code changes
- [AI Protocol Mocking (MCP & A2A)](https://www.mock-server.com/mock_server/ai_protocol_mocking.html): Mock MCP servers and A2A agent-to-agent endpoints (over SSE, WebSocket, and JSON-RPC) to test AI integrations without calling real services
- [OpenAPI for AI (MCP fallback)](https://www.mock-server.com/mock_server/ai_openapi.html): Use MockServer's OpenAPI spec as a fallback for AI tools that don't support MCP
- [Full documentation, single file](https://www.mock-server.com/llms-full.txt): All MockServer documentation concatenated into one file for LLM retrieval / training
- [AI policy](https://www.mock-server.com/ai.txt): Crawling, training, and citation policy for AI systems

## Getting Started
- [Getting Started](https://www.mock-server.com/mock_server/getting_started.html): Quick start guide covering starting MockServer, creating expectations, running tests, and verifying requests
- [Running MockServer](https://www.mock-server.com/mock_server/running_mock_server.html): How to run MockServer via Docker, Maven plugin, JUnit, npm, Homebrew, or standalone JAR
- [Testcontainers](https://www.mock-server.com/mock_server/mockserver_testcontainers.html): Run MockServer in your tests with the mockserver-testcontainers module — helpers for DNS, transparent proxy, HTTP/3, init JSON, and a ready-wired client
- [Troubleshooting Matching](https://www.mock-server.com/mock_server/troubleshooting_matching.html): Step-by-step checklist to diagnose why MockServer returns 404 when a request does not match, including common pitfalls and the debug mismatch endpoint
- [Running Tests In Parallel](https://www.mock-server.com/mock_server/running_tests_in_parallel.html): Run tests in parallel against a shared MockServer instance by using unique session IDs in request matchers to isolate each test

## Creating Expectations
- [Creating Expectations](https://www.mock-server.com/mock_server/creating_expectations.html): How to set up request matchers and response actions including literal responses, templated responses, class/closure callbacks, forwards, and errors
- [OpenAPI Expectations](https://www.mock-server.com/mock_server/using_openapi.html): Generate expectations from OpenAPI/Swagger specifications
- [Importing Expectations](https://www.mock-server.com/mock_server/importing_expectations.html): Import expectations from HAR (HTTP Archive), Postman Collection, or Pact v3 contract files via a single PUT /mockserver/import request, with format auto-detection
- [Expectation Initializers](https://www.mock-server.com/mock_server/initializing_expectations.html): Load expectations automatically when MockServer starts using a Java initializer class, JSON file, OpenAPI spec, or Maven plugin initializer
- [Persisting Expectations](https://www.mock-server.com/mock_server/persisting_expectations.html): Persist expectations and recorded proxy traffic to disk so they survive restarts and enable record-and-replay workflows
- [Before & After Actions](https://www.mock-server.com/mock_server/before_and_after_actions.html): Run extra HTTP webhooks or callbacks before or after an expectation's response — to mirror (tee), shadow, fan-out, or gate live traffic against other services
- [WASM Custom Rules](https://www.mock-server.com/mock_server/wasm_rules.html): Use WebAssembly modules as custom body matchers for complex matching logic that runs in a sandboxed WASM interpreter
- [CORS Support](https://www.mock-server.com/mock_server/CORS_support.html): Enable and configure CORS headers for control-plane and mocked responses, with permissive and restrictive policy examples
- [Clock Control](https://www.mock-server.com/mock_server/clock_control.html): Freeze, advance, or reset MockServer's controllable clock for deterministic time-based testing of date-sensitive responses and expectation TimeToLive

## Verification
- [Verifying Requests](https://www.mock-server.com/mock_server/verification.html): Verify that requests were received, including exact counts and sequence verification
- [Pact Contract Import, Export & Verification](https://www.mock-server.com/mock_server/pact_export.html): Import a Pact v3 contract to create stub expectations, export active expectations as a contract, or verify expectations satisfy a contract — the complete contract-testing loop
- [Mock Drift Detection](https://www.mock-server.com/mock_server/drift_detection.html): Detect when real upstream services have drifted from your mock stubs — status code mismatches, added or removed JSON fields, type and header changes; compare two sets of expectations offline with the baseline compare endpoint

## Configuration
- [Configuration Properties](https://www.mock-server.com/mock_server/configuration_properties.html): All configuration properties with defaults, including memory limits, logging, TLS, and performance tuning

## Deployment & Scaling
- [Centralized Deployment](https://www.mock-server.com/mock_server/centralized_deployment.html): Deploy MockServer as a shared instance across multiple teams or CI pipelines, with options for single-node, persistence-only durability, and clustered HA using the Infinispan state backend

## Client Libraries
- [Java Client](https://www.mock-server.com/mock_server/mockserver_clients.html): Java client library (Maven: org.mock-server:mockserver-client-java)
- [JavaScript/TypeScript Client](https://www.npmjs.com/package/mockserver-client): Node.js client (npm: mockserver-client)
- [Python Client](https://pypi.org/project/mockserver-client/): Python client (pip: mockserver-client)
- [Ruby Client](https://rubygems.org/gems/mockserver-client): Ruby client (gem: mockserver-client)
- [Go Client](https://www.mock-server.com/mock_server/mockserver_clients.html#go-mockserver-client): Go client library
- [.NET Client](https://www.mock-server.com/mock_server/mockserver_clients.html#dotnet-mockserver-client): .NET client library
- [Rust Client](https://www.mock-server.com/mock_server/mockserver_clients.html#rust-mockserver-client): Rust client library
- [PHP Client](https://www.mock-server.com/mock_server/mockserver_clients.html#php-mockserver-client): PHP client library
- [Client Capability Matrix](https://www.mock-server.com/mock_server/client_compatibility.html): Feature coverage across all MockServer clients — expectations, verification, LLM/MCP builders, test fixtures, retrieveAsCode, Testcontainers — with idiomatic per-language test snippets

## REST API
- [REST API (OpenAPI Spec)](https://www.mock-server.com/mockserver-openapi.yaml): Full OpenAPI 3.0 specification for MockServer's control plane API
- [REST API on SwaggerHub](https://app.swaggerhub.com/apis/jamesdbloom/mock-server-openapi): Interactive API explorer

## Data Store & File Storage
- [File Storage](https://www.mock-server.com/mock_server/file_storage.html): Store, retrieve, list, and delete named binary or text files in MockServer's in-memory file store to use as response bodies, test fixtures, or certificate payloads
- [CRUD Data Store](https://www.mock-server.com/mock_server/crud_data_store.html): Auto-generate a fully functional REST CRUD API over an in-memory JSON data store using a single PUT /mockserver/crud request, with no expectations required

## Interactive Breakpoints
- [Interactive Breakpoints](https://www.mock-server.com/mock_server/interactive_breakpoints.html): Pause live HTTP exchanges and streaming frames (SSE, gRPC server-streaming, WebSocket, GraphQL subscription) mid-flight, inspect or modify them, and continue, drop, inject, or close via the control-plane REST API

## Chaos Testing & Fault Injection
- [Chaos Testing](https://www.mock-server.com/mock_server/chaos_testing.html): Inject errors, latency, and outages into mocked and proxied responses using declarative chaos profiles for resilience testing
- [Chaos Proxy in Kubernetes](https://www.mock-server.com/mock_server/chaos_testing_kubernetes.html): Deploy MockServer as a chaos proxy in Kubernetes to inject faults into real service-to-service and external API calls using reverse proxy, egress proxy, and sidecar patterns
- [Chaos Orchestrators](https://www.mock-server.com/mock_server/chaos_testing_orchestrators.html): Drive MockServer's service-scoped chaos from Chaos Toolkit, AWS FIS, Azure Chaos Studio, and LitmusChaos via the control-plane endpoint, with a TTL dead-man's switch for safe auto-revert

## Docker
- [Docker Container](https://www.mock-server.com/where/docker.html): Run MockServer as a Docker container with environment variable configuration

## Proxying
- [Proxying Overview](https://www.mock-server.com/proxy/getting_started.html): Use MockServer as a recording proxy to capture and inspect HTTP traffic between services
- [Record & Replay](https://www.mock-server.com/proxy/record_and_replay.html): Record HTTP/HTTPS traffic through the proxy and replay it as mock expectations for offline testing and service virtualization
- [Configuring the System Under Test](https://www.mock-server.com/proxy/configuring_sut.html): Configure your application to proxy through MockServer using port forwarding, HTTP proxy, HTTPS tunnel, or SOCKS proxy
- [Verifying Proxied Requests](https://www.mock-server.com/proxy/verification.html): Verify that proxied requests were received a specific number of times or in a particular order using Java, JavaScript, or the REST API
- [Debugging Proxied Traffic](https://www.mock-server.com/proxy/debugging_proxied_traffic.html): Debug proxied traffic using the dashboard UI or the retrieve and download API, exporting requests as JSON, HAR, or cURL
- [Network Latency Debugging](https://www.mock-server.com/proxy/network_latency_debugging.html): Capture per-request timing (connect, TTFB, total), export HAR with timing breakdowns, flag slow requests, and track latency percentiles via Prometheus
- [Isolate Single Service](https://www.mock-server.com/mock_server/isolating_single_service.html): Use MockServer as a reverse proxy to route one service to a local debug instance while forwarding all other requests to the real environment
- [Transparent Proxy / Sidecar Mode](https://www.mock-server.com/mock_server/service_mesh.html): Run MockServer as a Kubernetes sidecar with transparent proxy interception for service mesh integration
- [Transparent Interception Recipes](https://www.mock-server.com/mock_server/transparent_interception_recipes.html): Recipes for routing traffic to MockServer — Kubernetes sidecars, firewall rules, DNS steering, cloud routes, browser and CI proxies

## TLS / HTTPS
- [TLS Configuration](https://www.mock-server.com/mock_server/HTTPS_TLS.html): Configure TLS/HTTPS including custom certificates, mTLS, and CA certificate chains

## Identity & Authentication
- [Mock an OIDC / OAuth2 Provider](https://www.mock-server.com/mock_server/mock_openid_connect_provider.html): Mock a complete OpenID Connect / OAuth2 identity provider in a single call — discovery, JWKS, token, authorize, userinfo, introspection, revocation, and logout — with tokens that verify against the published JWKS
- [OAuth2 Mocking](https://www.mock-server.com/mock_server/mocking_oauth2.html): Mock OAuth2 authorisation flows
- [Mocking SAML](https://www.mock-server.com/mock_server/mocking_saml.html): Stand up a mock SAML 2.0 Identity Provider — metadata, SP-initiated SSO, Single Logout, configurable signing, and negative-test flags for integration testing
- [Mock a SCIM Provider](https://www.mock-server.com/mock_server/mocking_scim.html): Mock a SCIM 2.0 identity provider — auto-generated Users and Groups CRUD endpoints, filtering, PATCH, and discovery documents for integration testing

## Stateful Behaviour
- [Stateful Scenarios](https://www.mock-server.com/mock_server/stateful_scenarios.html): Model multi-step, stateful API behaviour — state-machine scenarios, sequential / cycling responses, timed and externally-triggered transitions, and cross-protocol correlation, with runnable examples for every client

## LLM & AI Mocking
- [LLM Response Mocking](https://www.mock-server.com/mock_server/llm_response_mocking.html): Mock LLM API responses from OpenAI, Anthropic, Gemini, Bedrock, Azure OpenAI, and Ollama with provider-correct formatting, streaming, conversations, and cost budgets
- [AI Traffic Inspection — Configure Your AI Tool, SDK, or Framework](https://www.mock-server.com/mock_server/ai_traffic_inspection.html#configure-tools): Two connection methods for routing AI traffic through MockServer: transparent HTTPS proxy (any tool, no code change) and base-URL override (LlamaIndex, OpenAI Agents SDK, and other SDKs with a configurable base URL)
- [LLM Cost Optimisation](https://www.mock-server.com/mock_server/ai_optimisation.html): Proxy your AI agent's LLM calls through MockServer, then export a one-click optimisation brief or JSON bundle to cut inference cost — tighter prompts, prompt caching, fewer tool round-trips, and direct HTTP/MCP endpoints

## Testing & Quality
- [Contract Testing](https://www.mock-server.com/mock_server/contract_testing.html): Run OpenAPI contract tests against a live service and use the Pact import, export, and verify endpoints to validate consumer-driven contracts
- [Load Injection](https://www.mock-server.com/mock_server/load_injection.html): Drive API traffic from MockServer using declarative load scenarios — ramp virtual users, vary data across iterations with templates, and assert SLO verdicts over the generated traffic
- [Load Injection Performance](https://www.mock-server.com/mock_server/load_injection_performance.html): How MockServer load injection scales — one instance drives tens of thousands of requests/sec, and many instances in parallel reach hundreds of thousands, with real reproducible benchmarks and the fan-out deployment pattern
- [Examples](https://www.mock-server.com/mock_server/examples.html): Runnable examples across every language and interface — curl, JSON, Java, Node, Python, Ruby, Go, .NET, Rust, PHP, Docker Compose, WASM, and chaos engineering

## Observability
- [Observability](https://www.mock-server.com/mock_server/observability.html): Monitor MockServer with Prometheus metrics and OpenTelemetry traces, including request counters, LLM token/cost metrics, JVM health gauges, and W3C trace context propagation

## Protocols
- [GraphQL Mocking](https://www.mock-server.com/mock_server/graphql_mocking.html): Mock GraphQL queries, mutations, and subscriptions — import a schema or introspection document to auto-generate schema-valid responses, or write explicit expectations with AST-level field matching
- [gRPC Mocking](https://www.mock-server.com/mock_server/grpc_mocking.html): Mock gRPC services using MockServer
- [HTTP/3 (QUIC) Support](https://www.mock-server.com/mock_server/http3.html): Experimental HTTP/3 over QUIC support, enabled via the http3Port property and routed through the full expectation matching pipeline
- [AsyncAPI Broker Mocking](https://www.mock-server.com/mock_server/asyncapi_messaging.html): Mock Kafka and MQTT brokers using AsyncAPI 2.x/3.x specs — publish examples, subscribe to record messages, validate against JSON Schema, all via REST or Java API

## Optional
- [Scalability & Latency](https://www.mock-server.com/mock_server/performance.html): MockServer serving-performance benchmarks — one instance serves 32,000+ requests/sec at sub-millisecond median latency with flat request matching as expectations scale, measured with k6 and JMH, plus tuning guidance
- [Control Plane Auth](https://www.mock-server.com/mock_server/control_plane_authorisation.html): Secure the control plane API with mTLS or JWT authentication
- [Response Templates](https://www.mock-server.com/mock_server/response_templates.html): Use Mustache or Velocity templates for dynamic responses
- [Clearing & Resetting](https://www.mock-server.com/mock_server/clearing_and_resetting.html): Clear specific expectations/logs or reset all state
- [Debugging Issues](https://www.mock-server.com/mock_server/debugging_issues.html): Troubleshoot common issues including request matching failures
- [Dashboard UI](https://www.mock-server.com/mock_server/mockserver_ui.html): Interactive UI for managing expectations and inspecting traffic
- [IDE Extensions](https://www.mock-server.com/mock_server/ide_extensions.html): Install the MockServer VS Code extension or IntelliJ plugin to start/stop, author expectations with schema validation, view drift reports, upload WASM rules, and open the live dashboard without leaving your editor