# 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, and Ruby. 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)
- [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`, `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): Build test assertions in natural language
- [AI Traffic Inspection](https://www.mock-server.com/mock_server/ai_traffic_inspection.html): Record outbound traffic and let an AI assistant explain it
- [AI Protocol Mocking](https://www.mock-server.com/mock_server/ai_protocol_mocking.html): Generate mocks for REST, gRPC, and OAuth2 flows from prompts
- [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/where/running_mock_server.html): How to run MockServer via Docker, Maven plugin, JUnit, npm, Homebrew, or standalone JAR

## 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

## Verification
- [Verifying Requests](https://www.mock-server.com/mock_server/verification.html): Verify that requests were received, including exact counts and sequence verification

## 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

## 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)

## 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

## 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

## 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
- [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

## 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

## Optional
- [Performance Tuning](https://www.mock-server.com/mock_server/performance.html): Optimize MockServer for high-throughput scenarios
- [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
- [gRPC Mocking](https://www.mock-server.com/mock_server/grpc_mocking.html): Mock gRPC services using MockServer
- [OAuth2 Mocking](https://www.mock-server.com/mock_server/mocking_oauth2.html): Mock OAuth2 authorisation flows
- [Dashboard UI](https://www.mock-server.com/mock_server/mockserver_ui.html): Interactive UI for managing expectations and inspecting traffic
