Hoverfly MCP Server

Hoverfly MCP Server MCP Server

A Model Context Protocol (MCP) server that exposes Hoverfly as a programmable tool for AI assistants like Cursor, Claude, GitHub Copilot, and others supporting MCP. It enables dynamic mocking of third-party APIs to unblock development, automate testing, and simulate unavailable services during integration.

What is an MCP Server?⁠

Characteristics

Available Tools (12)

Tools Details

Tool: add_hoverfly_mock

Creates a new mock API by adding a request-response pair to Hoverfly's simulation.

Make sure to call startHoverfly() first as WebServer. If Hoverfly is not running, this operation will fail.

The input must be a valid RequestResponsePair object with request matchers (like path, method, destination, etc.) and a response containing status, body, and headers.

Example Input: { "request": { "path": [ { "matcher": "exact", "value": "/pages/keyconcepts/templates.html" } ], "method": [ { "matcher": "exact", "value": "GET" } ], "destination": [ { "matcher": "exact", "value": "docs.hoverfly.io" } ], "scheme": [ { "matcher": "exact", "value": "http" } ], "body": [ { "matcher": "exact", "value": "" } ], "query": { "query": [ { "matcher": "exact", "value": "true" } ] } }, "response": { "status": 200, "body": "Response from docs.hoverfly.io/pages/keyconcepts/templates.html", "encodedBody": false, "headers": { "Hoverfly": [ "Was-Here" ] }, "templated": false } }

Input RequestResponsePair Schema: { "type": "object", "properties": { "request": { "type": "object", "properties": { "path": { "type": "array", "items": { "$ref": "#/definitions/matcher" } }, "method": { "type": "array", "items": { "$ref": "#/definitions/matcher" } }, "destination": { "type": "array", "items": { "$ref": "#/definitions/matcher" } }, "scheme": { "type": "array", "items": { "$ref": "#/definitions/matcher" } }, "body": { "type": "array", "items": { "$ref": "#/definitions/matcher" } }, "query": { "type": "object", "properties": { "query": { "type": "array", "items": { "$ref": "#/definitions/matcher" } } } } }, "required": ["path", "method", "destination", "scheme", "body"] }, "response": { "type": "object", "properties": { "status": { "type": "integer" }, "body": { "type": "string" }, "encodedBody": { "type": "boolean" }, "headers": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "templated": { "type": "boolean" } }, "required": ["status", "body", "encodedBody", "headers", "templated"] } }, "required": ["request", "response"], "definitions": { "matcher": { "type": "object", "properties": { "matcher": { "type": "string" }, "value": { "type": "string" } }, "required": ["matcher", "value"] } } }

Tool: clear_hoverfly_mocks

Deletes all mock APIs from Hoverfly's simulation.

Tool: download_hoverfly_simulation

Downloads the current Hoverfly simulation file to the persistent simulation directory. The simulation is always saved to /opt/hoverfly-mcp/simulation-data inside the container. Mount this directory to your host for persistence. The file will be saved with a timestamp for easy identification. Use this to persist your mock configurations for later use or sharing.

Tool: fetch_hoverfly_version

Returns the current version of the Hoverfly instance.

Tool: get_hoverfly_debug_logs

Hoverfly Debug Logs Tool

Use this tool to fetch recent logs from the running Hoverfly instance for advanced debugging and troubleshooting. This is especially useful when:

• You encounter errors while creating a mock API.
• You receive unexpected or incorrect mock responses.
• You suspect issues with templating, matcher configuration, or simulation logic.
• You want to understand why a request was not matched as expected.

How to Use

• When: Use this tool immediately after a failed mock creation, or when you get an unexpected response from a mock API.
• Why: The logs provide detailed insight into Hoverfly's internal processing, including matcher evaluation, templating errors, and simulation execution.
• What: The tool returns the latest log entries from the Hoverfly admin API, which can be used to diagnose and resolve issues.

Parameters

• limit (optional, default: 500): The maximum number of log entries to fetch. Increase this if you need a longer history.

Example

{
  "limit": 500
}

Output

• Returns a JSON object containing a list of log entries, each with timestamp, level, and message fields.

Tip: Use this tool as your first step in debugging any Hoverfly simulation or templating issue!

Tool: get_hoverfly_documentation

Returns Hoverfly documentation for a specific topic. Allowed values: matchers, templating.

Helpful for developers or LLMs building or validating simulation JSON. You can also call this tool to get guidance when facing issues with matchers or templating in your simulation definitions.

Tool: get_hoverfly_status

Returns the current status of the Hoverfly server.

Tool: list_hoverfly_mocks

Lists all request-response pairs (mock APIs) currently active in Hoverfly.

Tool: show_hoverfly_endpoints_info

Returns a canonical list of all key Hoverfly endpoints, including:

• Mock server base URL (for intercepted API calls)
• Admin API and UI (for managing simulations and viewing logs)
• Simulation file endpoint (for viewing or downloading the current simulation)
• Example curl commands for quick testing

This helps developers, tools, or LLMs understand how to interact with Hoverfly after startup.

Tool: start_hoverfly_web_server

Starts the Hoverfly mock server in simulate mode and exposes it on port 8500 for mock server and port 8888 for admin endpoint. Can optionally load simulation from the persistent simulation directory on startup using the loadSimulationOnStartup parameter. If not passed, this parameter defaults to true. The simulation will be loaded from /opt/hoverfly-mcp/simulation-data if available.

Access URLs:

• Admin UI:http://localhost:8888⁠
• Mock Server Endpoint:http://localhost:8500⁠
• View or download the current simulation at:http://localhost:8888/api/v2/simulation⁠

You can:

• Point your API clients to http://localhost:8500 Parameters|Type|Description -|-|- loadSimulationOnStartup|boolean|Whether to load simulation from the persistent simulation directory on startup. If true or not specified, will look for the most recent simulation file in /opt/hoverfly-mcp/simulation-data.

Tool: stop_hoverfly_server

Stops the Hoverfly mock server and clears its state.

Tool: suggest_hoverfly_matchers

Analyzes a single Hoverfly RequestResponsePair JSON and returns matcher suggestions for each request field. The input must be a valid RequestResponsePair object. Each field in the request block will be analyzed and matcher suggestions will be provided. These suggestions can be used to make your matchers more robust and reliable. See the documentation for the expected input format and matcher details.

"method": [{ "matcher": "exact", "value": "GET" }],
"destination": [{ "matcher": "exact", "value": "api.example.com" }],
"path": [{ "matcher": "glob", "value": "/api/*" }]

}, "response": { "status": 200, "body": "{"result":"ok"}", "encodedBody": false, "headers": { "Content-Type": ["application/json"] }, "templated": false } }

Use this MCP Server

{
  "mcpServers": {
    "hoverfly-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/local-directory:/local-directory",
        "kapish88/hoverfly-mcp-server"
      ]
    }
  }
}

Why is it safer to run MCP Servers with Docker?⁠