Hoverfly

You can use the Hoverfly MCP Server to expose Hoverfly as a programmable, mockable proxy for AI assistants and development workflows. This server lets you dynamically create and manage API mocks, persist simulations, and control Hoverfly from an MCP-enabled client or AI assistant. It enables uninterrupted development even when third-party services are offline or slow.

How to use

Connect your MCP client to the Hoverfly MCP Server to start using dynamic API mocks. You can start Hoverfly in simulate mode as a web server, load the most recent simulation automatically on startup, and manage mocks via a set of available tools. You can list, add, or clear mocks, fetch the Hoverfly version, and download the current simulation for persistence.

How to install

Prerequisites you may need if you wish to build from source rather than using a Docker image. Install these on your workstation.

# Prerequisites
java -version  # Ensure you have Java 17 or newer
mvn -version   # Ensure you have Maven 3.6+ 

# Build from source (example flow)
git clone <repository-url>
cd hoverfly-mcp-server
mvn clean package

# Run the produced JAR
java -jar target/hoverfly-mcp-server-<version>.jar

Configuration with Docker (MCP server)

Configure the MCP server to run Hoverfly inside Docker. This example shows how to define the MCP connection so your AI assistant can start and manage Hoverfly as a remote service.

{
  "mcpServers": {
    "hoverfly_mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p", "8500:8500",
        "-p", "8888:8888",
        "-v", "/path/to/your/data:/opt/hoverfly-mcp/simulation-data",
        "docker.io/kapish88/hoverfly-mcp-server"
      ]
    }
  }
}

Persistence and simulation data

Simulation persistence is achieved by mounting a host directory to a fixed path inside the container. To keep data across restarts, mount a writable directory to /opt/hoverfly-mcp/simulation-data. Hoverfly can auto-load the most recent simulation from this directory on startup, if available. If you want a clean start, you can disable auto-load.

To ensure persistence works as expected, provide the host directory path in the Docker volume binding as shown in the configuration example.

Available tools

get_hoverfly_status

Checks if Hoverfly is running and reachable.

start_hoverfly_web_server

Starts Hoverfly in simulate mode as a web server and loads the latest simulation by default from the persistent directory.

stop_hoverfly_server

Stops Hoverfly and clears all active mocks.

fetch_hoverfly_version

Returns the current Hoverfly version.

list_hoverfly_mocks

Lists all active request-response mocks in the current simulation.

add_hoverfly_mock

Adds a new mock API using a JSON RequestResponsePair definition.

clear_hoverfly_mocks

Removes all existing mocks from Hoverfly.

show_hoverfly_endpoints_info

Provides information about key Hoverfly endpoints and example usage.

get_hoverfly_documentation

Returns Hoverfly documentation for a specific topic.

suggest_hoverfly_matchers

Suggests matcher options for a given request-response pair JSON.

get_hoverfly_debug_logs

Fetches recent Hoverfly logs for debugging.

download_hoverfly_simulation

Downloads the current simulation to the persistent directory.