Hoverfly Cloud AI (Preview)

Intelligent, AI‑driven API simulation. Use natural language via the Model Context Protocol (MCP) to discover, generate, and manage simulations and services—directly from your AI assistant.

Note: Hoverfly Cloud AI is currently in active development. Capabilities are not yet fully fledged and the way it works may change as we improve it. We welcome your feedback here to help shape the feature.

Overview

Hoverfly Cloud AI is an intelligent, AI‑driven way to work with API simulations using natural language. Any MCP‑capable assistant can connect to Hoverfly Cloud as a remote MCP server and translate your plain requests into precise actions.

With Hoverfly Cloud AI you can:

• Ask for new simulations to be generated from your codebase, sample payloads, or API specs

• Create, update, and manage simulations and services without leaving your editor

• Get quick status answers and troubleshoot by asking the assistant what’s going on

Your assistant stays in your environment. It simply calls Hoverfly Cloud’s secure HTTP JSON‑RPC MCP endpoint to perform the work in your account.

Capabilities

Hoverfly Cloud AI exposes MCP tools that map directly to Hoverfly Cloud APIs, so you can:

• Virtualise APIs and build simulations

  • Create, update, list, and delete simulations

  • Generate simulations from OpenAPI/Postman or example requests/responses

• Operate services (your running API simulations)

  • Start services from simulations; update a running service’s simulation

  • Change modes (simulate, capture, spy, passthrough)

  • Apply behaviours such as latency, faults, headers, compression

• Work naturally with AI agents

  • “Create a simulation for new user registration,” “Add a 500ms delay to login,” “What’s the status of my billing API?”

• Generate from your codebase

  • Point at specs or sample payloads; the assistant scaffolds simulations you can refine

• Stay in your development flow

  • Use VS Code/Copilot, Claude Desktop, Cursor, IntelliJ IDEA, or any MCP‑compatible tool

Tip: Tool discovery and access respect your account type and read‑only mode headers.

Use cases

Below are example scenarios that show how natural‑language control accelerates everyday work.

Create and deploy simulations to replace real APIs in a project

Quickly set up mocks that mirror the external APIs your app already calls:

• Open an AI chat in the context of your codebase that consumes real APIs

• Ask the assistant to build Hoverfly simulations matching those dependencies

• Have it add project config to switch between real and simulated APIs

• Ask it to deploy simulations and start services

• Switch your app’s configuration to the simulated endpoints and run a demo

• Refine: use CSV‑backed data for realistic results or inject a specific error to test failure paths

This saves hours of manual setup while letting you test data and error scenarios safely.

Generate simulations from API specifications

Turn OpenAPI (Swagger) or Postman collections into running mocks with a prompt:

• Provide your API spec or Postman collection to the assistant

• Ask the assistant to create and deploy simulations that honour the contract—requests and responses for every endpoint

• Instantly provide a reliable mock so frontend and backend teams can work in parallel

Smart provisioning for test environments

Provision tailored environments for different phases (unit, integration, UAT) using simple commands:

• Organise templates and test data (e.g., CSVs) with a clear folder structure

• Prompt the assistant to analyse the structure and map templates to data

• Ask it to launch a group of services for a named scenario, e.g., “VIP Customer – successful payment”

• When done, instruct it to tear down the group

This gives every team member clean, repeatable environments in seconds.

Document your API simulation assets

Keep documentation current without the busywork:

• Ask the assistant to “document all running API simulation assets”

• It produces concise docs covering endpoints, expected responses, failure modes, and data dependencies

• Share the output as living, up‑to‑date reference material for the team

Set up

Hoverfly Cloud provides a remote MCP server over streamable HTTP at the path /mcp (HTTP JSON‑RPC). This feature is exposed only as a remote MCP server over streamable HTTP; stdio/local transports are not supported.

Connect your MCP client to that URL and include your Hoverfly Cloud API token as a Bearer token on every request.

You’ll need:

• Hoverfly Cloud MCP URL (https://cloud.hoverfly.io/mcp)

• Your Hoverfly Cloud API token. Create and manage tokens from your account page; if you don’t already have one, you can generate one (or more) and revoke them at any time.

VS Code with GitHub Copilot

Configure an MCP HTTP server in your workspace so Copilot can call Hoverfly Cloud tools.

1. Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "hoverfly-cloud": {
      "type": "http",
      "url": "https://cloud.hoverfly.io/mcp",
      "headers": {
        "Authorization": "Bearer <your-hoverfly-cloud-access-token>"
        // Optional: filter to read-only tools while exploring
        // "X-MCP-ReadOnly": "true"
      }
    }
  }
}

1. Restart VS Code (or reload the window) and open Copilot Chat. You should see the server in tool discovery; ask Copilot to “list Hoverfly Cloud tools” or “create a simulation named example1.”

Cursor

Cursor supports MCP servers. Add Hoverfly Cloud as a remote HTTP MCP server:

1. Open Cursor Settings and go to the Model Context Protocol (MCP) section.

2. Add a new HTTP server with:

• URL: https://cloud.hoverfly.io/mcp

• Header: Authorization: Bearer <your-hoverfly-cloud-API-token>

• (Optional) Header: X-MCP-ReadOnly: true to only expose read‑only tools

1. Save and restart Cursor if needed.

2. Ask the assistant to “list tools from Hoverfly Cloud,” then try a simple action like “create a simulation named demo…”.

Note: Cursor must connect using a remote MCP server over streamable HTTP. If your version exposes an “transport” option, choose HTTP/streamable (sometimes called “http-first”). UI labels may vary by Cursor version.

Claude Desktop

Claude Desktop supports MCP servers. Add Hoverfly Cloud as an HTTP server:

1. Open Claude Desktop settings and go to Model Context Protocol.

2. Add a new HTTP server with:

   • URL: https://cloud.hoverfly.io/mcp

   • Header: Authorization: Bearer <your-hoverfly-cloud-access-token>

   • (Optional) Header: X-MCP-ReadOnly: true to only expose read‑only tools

3. Save and restart Claude Desktop.

4. Ask Claude to “list tools from Hoverfly Cloud.” Then try “create a simulation named demo with this JSON…”

Note: Exact UI labels may vary by Claude Desktop version. Refer to Anthropic’s MCP documentation if your version uses a per‑service JSON file instead of a settings UI—the same URL and headers apply.

IntelliJ IDEA

IntelliJ IDEA (JetBrains AI Assistant) can connect to remote MCP servers using the NPX‑based wrapper described in JetBrains’ documentation. This approach lets you access a remote MCP server over streamable HTTP by proxying it locally.

References:

• Supported transport mechanisms

• Workaround for remote servers (NPX wrapper)

Steps:

1. Open Settings and navigate to the AI Assistant MCP servers configuration.

2. Add a server named “hoverfly-cloud” using the NPX wrapper to reach the remote HTTP endpoint. A working configuration looks like:

{
  "mcpServers": {
    "hoverfly-cloud": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://cloud.hoverfly.io/mcp",
        "--transport",
        "http-first",
        "--header",
        "Authorization:${MCP_AUTH_HEADER}"
      ],
      "env": {
        "MCP_AUTH_HEADER": "Bearer <your-hoverfly-cloud-access-token>"
      }
    }
  }
}

1. Apply and restart the IDE if prompted.

2. Use the assistant panel to discover and call tools (e.g., list simulations, create a service from a simulation).

Other MCP‑compatible tools

Any MCP client that supports remote MCP servers over streamable HTTP can connect with:

• URL: https://cloud.hoverfly.io/mcp

• Headers:

  • Authorization: Bearer <your-hoverfly-cloud-access-token>

  • Optional X-MCP-ReadOnly: true to discover and call read‑only tools only

If your client supports MCP Resources, Hoverfly Cloud also publishes helpful resources (for example, the Hoverfly Simulation JSON Schema) that your AI can load for validation and better reasoning.

Troubleshooting

• Unauthorized: Ensure your Authorization header is present and the token is valid. Tokens are required on every call.

• Tools not listed: Your account type or read‑only mode may filter tools. Remove X-MCP-ReadOnly to see the full set (if allowed by your account).

---

If you’d like help connecting a specific MCP client, contact Hoverfly Cloud Support with your client name and version and we’ll assist.

Appendix: MCP tool reference

The Hoverfly Cloud MCP server exposes the following tools. Tool visibility and access may be limited by your account type and by read‑only mode.

Auth

• auth_current_user (read‑only)

  • Returns the authenticated user profile.

Services (running API simulations)

• list_services (read‑only)

  • List services you can see; supports paging and sorting.

• get_service (read‑only)

  • Get details for a service by name.

• create_service

  • Start a new service from a simulation (inline JSON or by name/owner).

• update_service_simulation

  • Replace the simulation on a running service (inline JSON or by name/owner).

• update_service_mode

  • Change mode: simulate, capture, spy, or passthrough.

• update_service_behaviors

  • Apply behaviours (e.g., latency, fault injection, headers, compression).

• delete_service

  • Delete a service by name.

Simulations (saved simulations)

• list_simulations (read‑only)

  • List simulations; supports paging and sorting.

• get_simulation (read‑only)

  • Fetch a simulation by name (optionally specify owner).

• create_simulation

  • Create a simulation: provide name and content JSON. Optional: findAndReplaceMatchers, dataSources, callbacks.

• update_simulation

  • Update a simulation: same shape as create; PUT semantics.

• delete_simulation

  • Delete a simulation by name (optionally specify owner).

Notes

• Authentication: Include Authorization: Bearer <token> on every call.

• Read‑only mode: Send X-MCP-ReadOnly: true to only discover and call read‑only tools.

• Resources: If your MCP client supports “resources”, Hoverfly Cloud can publish helpful docs like the Hoverfly Simulation JSON Schema to aid validation and prompting.