Installing the WireMock Cloud MCP server directly

This guide walks you through configuring the MCP (Model Context Protocol) server necessary to natively use WireMock Cloud from an MCP-compatible AI tool such as Cursor or Claude Desktop. This enables automatic API discovery, mocking and test abstraction from any codebase as part of prompt-driven development with your chosen AI tool. Additionally, it enables you to skip the complexity of building out new services early on - which can hamper the rapid development by introducing more failure points - and instead use simulated APIs on WireMock to prototype new capabilities with less system overhead.

Most users should install the WireMock Cloud agent skills plugin instead - it bundles this same MCP server connection alongside expert guidance for your agent, with no separate setup step. Use this page if you want the MCP server on its own, without the skills plugin.

Note that while this article documents use with Cursor, Claude Desktop and VSCode specifically, WireMock Cloud’s MCP server will work with any AI-powered tool that supports MCP.

Choosing a server

WireMock Cloud offers two ways to connect an AI tool via MCP:

Remote server (recommended) - a hosted HTTP server at https://mcp.wiremock.cloud/mcp. No local installation is required; your AI tool authenticates with your WireMock Cloud account via an OAuth sign-in in your browser the first time it connects, or with an API token for headless and CI clients that can’t complete a browser sign-in.
Local server - a stdio server launched on your machine by the WireMock CLI (wiremock mcp). Choose this if you need HTTP request authentication with locally stored credentials, or if your network can’t reach mcp.wiremock.cloud directly.

Both expose the same set of MCP tools. Use whichever matches your setup - you only need one.

Option 1: Remote server (recommended)

No prerequisites beyond an existing WireMock Cloud account - if you don’t have one, the OAuth step below will guide you through creating one.

Cursor
VSCode + GitHub Copilot
Claude Code
Claude Desktop
Windsurf

Click this button to install with Cursor:

Or, follow these instructions:

Open Settings->Cursor settings.
Navigate to Tools & Integrations.
Click New MCP Server. This opens mcp.json.
Add the WireMock server:

{
  "mcpServers": {
    "WireMock": {
      "url": "https://mcp.wiremock.cloud/mcp"
    }
  }
}

Save the file. Cursor will show a “needs authentication” indicator next to the server - click Connect to complete an OAuth sign-in in your browser.

Step 2: Confirm your setup

To confirm everything is working correctly, check that you’re logged in to WireMock Cloud by running the following prompt:

Am I logged into WireMock Cloud?

If logged in, you’ll see your account details rather than being prompted to sign in.

In VSCode, open the settings.json file via Settings…->Settings then clicking the Open Settings (JSON) link in the top right.

Add the mcp element to the settings JSON:

{
  "mcp": {
    "servers": {
      "WireMock": {
        "type": "http",
        "url": "https://mcp.wiremock.cloud/mcp"
      }
    }
  }
}

Restart VSCode. VS Code will open a browser window to complete an OAuth sign-in the first time it connects - approve the trust dialog and sign in when prompted.

Step 2: Confirm your setup

Open the Copilot chat window and confirm that the tools icon is present with a number above zero:

To confirm everything is working correctly, check that you’re logged in to WireMock Cloud by running the following prompt:

Who am I logged into WireMock Cloud as?

If logged in, you’ll see your account details rather than being prompted to sign in.

Open your terminal or command prompt.
Add the WireMock MCP server using the Claude CLI, specifying the HTTP transport:

claude mcp add --transport http wiremock https://mcp.wiremock.cloud/mcp

Verify the server was added successfully:

claude mcp list

You should see “wiremock” in the list of configured MCP servers. If it shows “Needs authentication”, run /mcp inside a Claude Code session (or claude mcp login wiremock from the shell) and complete the OAuth sign-in that opens in your browser.

Step 2: Confirm your setup

To confirm everything is working correctly, check that you’re logged in to WireMock Cloud by running the following prompt in Claude Code:

Am I logged into WireMock Cloud?

If logged in, you’ll see your account details.

Open Settings->Connectors.
Click Add custom connector.
Enter the WireMock MCP server URL:

https://mcp.wiremock.cloud/mcp

Click Add. Claude Desktop will open a browser window to complete an OAuth sign-in immediately after the connector is added.

Step 2: Confirm your setup

To confirm everything is working correctly, check that you’re logged in to WireMock Cloud by running the following prompt:

Am I logged into WireMock Cloud?

After confirming it is OK for Claude to use the tool, if logged in, you’ll see your account details rather than being prompted to sign in.

Navigate to Windsurf Settings > Cascade > Plugins.
Click Manage plugins to access the raw configuration.
Click View raw config to edit the mcp_config.json file (located at ~/.codeium/windsurf/mcp_config.json) and add:
{ "mcpServers": { "WireMock": { "serverUrl": "https://mcp.wiremock.cloud/mcp" } } }
- Save the configuration and press the refresh button in the Plugin Store. Windsurf will prompt you to sign in via OAuth in your browser on first connection.
Step 2: Confirm your setup
To confirm everything is working correctly, check that you’re logged in to WireMock Cloud by running the following prompt in Cascade:
Am I logged into WireMock Cloud?
If logged in, you’ll see your account details rather than being prompted to sign in.

Authenticating with an API token

Clients that can’t complete an interactive browser sign-in - CI pipelines, scripts, or other headless agents - can authenticate to the remote server with a WireMock Cloud API token instead of OAuth. Get your token from the account security page (see Authentication), then send it in the Authorization header using the Token scheme in place of the OAuth sign-in step:

Authorization: Token <your-api-token>

For example, to add the server to Claude Code without an interactive sign-in:

claude mcp add --transport http wiremock https://mcp.wiremock.cloud/mcp --header "Authorization: Token <your-api-token>"

Or in an mcp.json-style configuration (Cursor):

{
  "mcpServers": {
    "WireMock": {
      "url": "https://mcp.wiremock.cloud/mcp",
      "headers": {
        "Authorization": "Token <your-api-token>"
      }
    }
  }
}

Or for VS Code’s settings.json:

{
  "mcp": {
    "servers": {
      "WireMock": {
        "type": "http",
        "url": "https://mcp.wiremock.cloud/mcp",
        "headers": {
          "Authorization": "Token <your-api-token>"
        }
      }
    }
  }
}

Other MCP clients that support custom headers for remote servers use a similar headers field - check your tool’s documentation for the exact configuration key.

Treat your API token like a password - anyone with it can access your WireMock Cloud account through the MCP server. Prefer OAuth sign-in for interactive use, and reserve API tokens for headless or CI environments where a browser isn’t available.

Option 2: Local server

Prerequisites

Node.js 18+ (to install the CLI)
An existing WireMock Cloud account (if you don’t have one, you can sign up during the login step)

Step 1: Install the WireMock CLI

Install the CLI globally using npm:

npm i -g @wiremock/cli

Step 2: Log in to WireMock Cloud

If you already have a WireMock Cloud account, simply log in. Otherwise, the login process will guide you through creating an account:

wiremock login

Step 3: Configure your AI tool

Cursor
VSCode + GitHub Copilot
Claude Code
Claude Desktop
Windsurf

Click this button to install with Cursor:

Or, follow these instructions:

Open Settings->Cursor settings.
Navigate to MCP.
Click Add new MCP server.
In the dialog, configure your server to run this command:

wiremock mcp

Verify Installation by looking for the green status dot next to the MCP server and the list of tool names.

If you have an existing real API integration, you can replace it with a WireMock stub. Generate the mock from documentation, source code, or other external description formats. This enables you to test your app in isolation without depending on live services.

Step 4: Confirm your setup

To confirm everything is working correctly, check that you’re logged in to WireMock Cloud by running the following prompt:

Am I logged into WireMock Cloud?

If logged in, you’ll see your account details rather than being prompted to sign in.

In VSCode, open the settings.json file via Settings…->Settings then clicking the Open Settings (JSON) link in the top right.

Add the mcp element to the settings JSON:

{
  "mcp": {
    "servers": {
      "WireMock": {
        "type": "stdio",
        "command": "wiremock",
        "args": [
          "mcp"
        ]
      }
    }
  }
}

Restart VSCode

Step 4: Confirm your setup

Open the Copilot chat window and confirm that the tools icon is present with a number above zero:

To confirm everything is working correctly, check that you’re logged in to WireMock Cloud by running the following prompt:

Who am I logged into WireMock Cloud as?

If logged in, you’ll see your account details rather than being prompted to sign in.

Open your terminal or command prompt.
Add the WireMock MCP server using the Claude CLI:

claude mcp add wiremock -- wiremock mcp

Verify the server was added successfully:

claude mcp list

You should see “wiremock” in the list of configured MCP servers.

Step 4: Confirm your setup

To confirm everything is working correctly, check that you’re logged in to WireMock Cloud by running the following prompt in Claude Code:

Am I logged into WireMock Cloud?

If logged in, you’ll see your account details:

Open Settings->Developer.
Click Edit Config and open the config file in your preferred editor.
Add the WireMock MCP server to the file. The whole file will look like this if this is the first MCP server installed:

{
  "mcpServers": {
    "wiremock": {
      "command": "wiremock",
      "args": [
        "mcp"
      ]
    }
  }
}

Restart Claude Desktop.

Step 4: Confirm your setup

To confirm everything is working correctly, check that you’re logged in to WireMock Cloud by running the following prompt:

Am I logged into WireMock Cloud?

After confirming it is OK for Claude to use the tool, if logged in, you’ll see your account details rather than being prompted to sign in.

Navigate to Windsurf Settings > Cascade > Plugins.
Click Manage plugins to access the raw configuration.
Click View raw config to edit the mcp_config.json file (located at ~/.codeium/windsurf/mcp_config.json) and add:
{ "mcpServers": { "wiremock": { "command": "wiremock", "args": ["mcp"] } } }
- Save the configuration and press the refresh button in the Plugin Store.
Step 4: Confirm your setup
To confirm everything is working correctly, check that you’re logged in to WireMock Cloud by running the following prompt in Cascade:
Am I logged into WireMock Cloud?
If logged in, you’ll see your account details rather than being prompted to sign in.

Troubleshooting

If your agent shows an “unknown client” (or similar “invalid client”) error while trying to complete the OAuth sign-in for the remote MCP server, your agent has a cached OAuth client registration that the WireMock Cloud MCP server no longer recognizes. Clearing your agent’s stored credentials for the WireMock MCP server and signing in again resolves this.

Clear the stored credentials and sign in again:

claude mcp logout wiremock
claude mcp login wiremock

On versions of Claude Code older than 2.1.186 (which don’t have mcp logout), remove and re-add the server instead:

claude mcp remove wiremock
claude mcp add --transport http wiremock https://mcp.wiremock.cloud/mcp

Then run /mcp inside a session and authenticate again.

Clear the stored credentials and sign in again:

codex mcp logout wiremock
codex mcp login wiremock

Delete the server to clear its cached credentials:

/mcp delete wiremock

Then re-add it as described in Installing the agent skills plugin (or reconfigure it manually) and complete the OAuth sign-in again when prompted.

Next Steps

With WireMock MCP successfully installed, you can begin creating and using mocks in your development workflow:

Generate a new feature and mock a new API

Develop a new feature in your application that calls a fresh API. Quickly generate a WireMock stub for this API, and then wire it up to your app while in development mode.

Swap an existing API connection for a mock

If you have an existing real API integration, you can replace it with a WireMock Cloud mock. Generate the mock from documentation, source code, or other external description formats. This enables you to test your app in isolation without depending on live services.

Concepts

Tutorials

How-to Guides

Reference

Installing the WireMock Cloud MCP server directly

Choosing a server

Option 1: Remote server (recommended)

Step 2: Confirm your setup

Step 2: Confirm your setup

Step 2: Confirm your setup

Step 2: Confirm your setup

Step 2: Confirm your setup

Authenticating with an API token

Option 2: Local server

Prerequisites

Step 1: Install the WireMock CLI

Step 2: Log in to WireMock Cloud

Step 3: Configure your AI tool

Step 4: Confirm your setup

Step 4: Confirm your setup

Step 4: Confirm your setup

Step 4: Confirm your setup

Step 4: Confirm your setup

Troubleshooting

Next Steps

Generate a new feature and mock a new API

Swap an existing API connection for a mock

​Choosing a server

​Option 1: Remote server (recommended)

​Step 2: Confirm your setup

​Step 2: Confirm your setup

​Step 2: Confirm your setup

​Step 2: Confirm your setup

​Step 2: Confirm your setup

​Authenticating with an API token

​Option 2: Local server

​Prerequisites

​Step 1: Install the WireMock CLI

​Step 2: Log in to WireMock Cloud

​Step 3: Configure your AI tool

​Step 4: Confirm your setup

​Step 4: Confirm your setup

​Step 4: Confirm your setup

​Step 4: Confirm your setup

​Step 4: Confirm your setup

​Troubleshooting

​”Unknown client” error during OAuth sign-in

​Next Steps

​Generate a new feature and mock a new API

​Swap an existing API connection for a mock

Choosing a server

Option 1: Remote server (recommended)

Step 2: Confirm your setup

Step 2: Confirm your setup

Step 2: Confirm your setup

Step 2: Confirm your setup

Step 2: Confirm your setup

Authenticating with an API token

Option 2: Local server

Prerequisites

Step 1: Install the WireMock CLI

Step 2: Log in to WireMock Cloud

Step 3: Configure your AI tool

Step 4: Confirm your setup

Step 4: Confirm your setup

Step 4: Confirm your setup

Step 4: Confirm your setup

Step 4: Confirm your setup

Troubleshooting

”Unknown client” error during OAuth sign-in

Next Steps

Generate a new feature and mock a new API

Swap an existing API connection for a mock