MockServer MCP Server: Setup for Claude Code, Cursor and Other Apps

• Creates a mock that answers a matching request

  Sets up a mock response for requests that match a method and path. Use the raw version for header or query matching.

  Try: “Create a mock that returns 200 OK for GET /api/health.”

  Write · create_expectation

• Forwards matching requests to another host

  Creates a rule that passes matching requests on to a host you name, so you can proxy a real service.

  Try: “Forward all /v1/* requests to api.example.com.”

  Write · create_forward_expectation

• Builds mocks from an OpenAPI spec

  Creates mocks for the operations and response codes in an OpenAPI spec, and reports where the spec breaks the OpenAPI rules.

  Try: “Mock every endpoint in this OpenAPI spec.”

  Write · create_expectation_from_openapi

• Turns recorded real traffic into mocks

  Converts traffic recorded through the forwarding proxy into active mocks. A preview option shows the result first.

  Try: “Turn the traffic you recorded into mocks, preview first.”

  Write · create_expectations_from_recorded_traffic

• Creates a mock in the full JSON format

  For mocks the simple tool cannot express, you pass the whole JSON definition yourself, including templates, callbacks and overrides.

  Try: “Add this raw expectation JSON.”

  Write · raw_expectation

• Lists the active mocks

  Shows active mocks in full JSON with their IDs, optionally filtered by method or path.

  Try: “List all active expectations for /api/users.”

  Read · list_expectations

• Shows if MockServer is running and on which ports

  Tells you whether MockServer is up and which ports it listens on.

  Try: “Is MockServer up, and on which ports?”

  Read · get_status

• Checks a request arrived a set number of times

  After your code has run, asserts that a request matching your method, path or other criteria reached MockServer exactly as many times as you expect.

  Try: “Verify GET /api/health was called exactly twice.”

  Read · verify_request

• Checks requests arrived in order

  Asserts that the requests you list reached MockServer in that exact order, which catches calls made out of sequence.

  Try: “Verify login was called before profile.”

  Read · verify_request_sequence

• Lists the requests MockServer received

  Pulls back the requests MockServer has seen so far, which you can narrow by method and path, to inspect what your code actually sent.

  Try: “Show the requests received for /api/orders.”

  Read · retrieve_recorded_requests

• Lists recorded request and response pairs

  Returns each request MockServer recorded together with the response it sent back.

  Try: “Show the request and response pairs from the last test.”

  Read · retrieve_request_responses

• Reads MockServer's log messages

  Returns matching, mismatch, action and error log entries, which you can narrow to one request by its correlation ID.

  Try: “Show the logs for the failed request.”

  Read · retrieve_logs

• Explains why a request matched no mock

  Shows, field by field, why a request did not match each active mock.

  Try: “Why did POST /api/login not match any mock?”

  Read · debug_request_mismatch

• Lists requests that got a 404 and why

  Returns recent unmatched requests with the closest mocks and hints for fixing each mismatch.

  Try: “Which requests returned 404 in my last test run, and why?”

  Read · explain_unmatched_requests

• Explains how one received request was handled

  For one request by correlation ID, says which mock would serve it now and why earlier mocks were passed over.

  Try: “Explain how request abc-123 was handled.”

  Read · explain_request

• Suggests patches so mocks would match

  For each recent unmatched request, suggests a JSON patch to its closest mocks that would make them match.

  Try: “Suggest fixes for the mocks that missed.”

  Read · suggest_expectation_fix

• Finds mocks that can never match

  Flags mistakes such as a mock shadowed by an earlier one, zero times or time to live, and bad path formats.

  Try: “Lint my expectations.”

  Read · lint_expectations

• Shows non-default settings and where they came from

  Lists each setting changed from its default, its value and whether it came from a property, file, environment variable or runtime.

  Try: “Which MockServer settings differ from the defaults?”

  Read · diagnose_config

• Explains why a forward or proxy failed

  Returns recent failed forwards with the status and cause behind each 502.

  Try: “Why did forwarding to the upstream fail?”

  Read · explain_forward_failure

• Tries a response template without saving it

  Dry-runs a Velocity, Mustache or JavaScript template against a sample request and returns the rendered result or error.

  Try: “Test this Velocity template with a sample request.”

  Write · test_template

• Switches between mock, spy and capture modes

  Sets SIMULATE (mocks only), SPY (mocks plus recording unmatched requests) or CAPTURE (forward and record everything).

  Try: “Switch MockServer to SPY mode.”

  Write · set_operating_mode

• Turns recorded traffic into active mocks

  Promotes recorded proxy traffic into mocks in one step, hiding secrets and merging repeated calls by default.

  Try: “Promote the recordings to mocks.”

  Write · promote_recordings

• Checks recorded traffic against an OpenAPI spec

  Validates each recorded request and response against the spec and reports conformance per pair.

  Try: “Check my recorded traffic against this OpenAPI spec.”

  Read · verify_traffic_against_openapi

• Tests a running service against its OpenAPI spec

  Sends example requests built from the spec to a service you point it at and checks the responses conform.

  Try: “Run a contract test against http://localhost:8080 with this spec.”

  Network · run_contract_test

• Sends bad inputs to a service from its spec

  Sends malformed and edge-case requests built from the spec and reports which ones the service did not handle well.

  Try: “Run a resiliency test against my service.”

  Network · run_resiliency_test

• Checks another MCP server follows the protocol

  Runs the protocol handshake and core calls against an MCP endpoint over Streamable HTTP.

  Try: “Check that my MCP server at http://localhost:3000/mcp is correct.”

  Network · run_mcp_contract_test

• Adds failures to calls to one upstream host

  Registers, removes or clears a chaos profile per upstream host, with an optional time limit so it undoes itself.

  Try: “Make api.example.com return errors 30% of the time for 5 minutes.”

  Write · manage_service_chaos

• Mocks an AI model's reply

  Creates a mock reply formatted for a provider such as OpenAI or Anthropic, with text, tool calls and usage.

  Try: “Mock an OpenAI reply that says "Paris".”

  Write · mock_llm_completion

• Mocks a multi-turn AI conversation

  Builds a scripted conversation where each turn matches on the conversation so far and returns a set reply.

  Try: “Mock a three-turn support chat.”

  Write · create_llm_conversation

• Mocks an AI provider that fails then recovers

  Makes the first N requests fail with the statuses you give, then succeed, to test retry and failover code.

  Try: “Fail twice with 429 then succeed.”

  Write · mock_llm_failover

• Mocks hostile AI output for security tests

  Sets up a fake AI reply that carries a prompt injection, jailbreak, data-exfiltration request or broken content, so you can check your agent does not fall for it.

  Try: “Mock a prompt-injection reply to test my agent.”

  Write · mock_adversarial_llm_response

• Saves recorded AI traffic to a fixture file

  Snapshots AI traffic recorded through the proxy into a secret-free file for repeatable replay. It writes a file.

  Try: “Record the LLM traffic to fixtures.json.”

  Write · record_llm_fixtures

• Loads mocks from a JSON file

  Reads a fixture file and adds its expectations as active mocks.

  Try: “Load the mocks from fixtures.json.”

  Write · load_expectations_from_file

• Checks an agent called a tool

  Asserts, from recorded AI requests, that an agent called a named tool, optionally with matching arguments, a set number of times.

  Try: “Verify the agent called search_docs once.”

  Read · verify_tool_call

• Checks AI replies match a JSON Schema

  Validates the structured output of recorded AI responses against a schema.

  Try: “Check recorded replies match this schema.”

  Read · verify_structured_output

• Checks recorded AI spend is within budget

  Sums the token usage in recorded AI responses, prices it, and compares it with a USD budget.

  Try: “Is the recorded AI cost under $0.50?”

  Read · verify_cost_budget

• Summarizes an agent run from recorded traffic

  Reports message counts, the ordered tool calls and their results from recorded AI requests.

  Try: “Summarize what the agent did in that run.”

  Read · explain_agent_run

• Compares two recorded agent runs

  Shows what changed between two runs at the prompt level: additions, removals, edits and tool-call differences.

  Try: “Diff the two latest agent runs.”

  Read · diff_agent_runs

• Exports a cost-saving brief from AI traffic

  Turns captured AI traffic into a Markdown brief or JSON with signals such as repeated prompts and bloated tool lists.

  Try: “Export an optimisation report for the agent traffic.”

  Read · export_optimisation_report

• Checks if a real AI provider's replies changed shape

  Replays a saved recording against the live provider and reports structural changes. It needs an AI provider key configured on the server.

  Try: “Check the saved cassette for drift against the live API.”

  Network · detect_llm_drift

• Turns your mocks into MCP tool definitions

  Generates tool definitions from current mocks so an agent can discover the mocked endpoints as tools.

  Try: “List the mocked endpoints as tools.”

  Read · list_mock_tools

• Retrieves data with full control over format

  Fetches recorded data with full control: choose the type, output format and correlation ID yourself.

  Try: “Retrieve active expectations as Java code.”

  Read · raw_retrieve

• Verifies requests with the full JSON format

  Runs a verification from the complete verification JSON you supply, for checks the simpler verify tools cannot express.

  Try: “Verify using this verification JSON.”

  Read · raw_verify

• Removes mocks or recorded requests

  Clears mocks and, or, recorded requests that match your criteria.

  Try: “Clear the mocks for /api/users.”

  Delete · clear_expectations

• Wipes all mocks, recorded requests and logs

  Clears every expectation, recorded request and log in the MockServer instance.

  Try: “Reset MockServer.”

  Delete · reset

• Shuts MockServer down

  Shuts the MockServer process down, so the MCP address stops answering until you start it again.

  Try: “Stop MockServer.”

  Write · stop_server

Watch out for

• It can wipe mocks and stop the server

  The delete tools (clear_expectations and reset) only remove mocks, recorded requests and logs inside the MockServer you connect to, and stop_server shuts that instance down. Nothing outside MockServer is deleted, but use an instance meant for testing. github.com

• The endpoint is open unless you turn on auth

  Control-plane authorization defaults to off and the bind address defaults to empty. Do not expose port 1080 to networks you do not trust, or enable authorization. github.com

• Test tools send requests to services you name

  The contract, resiliency and MCP test tools call the target you give them, so point them only at services you own. github.com

• Recording can capture real traffic

  Spy and capture modes forward and store real requests. Promoting recordings redacts secrets, but review fixtures before you commit them. github.com

Security advisories