The Quick Answer

Add webmcp-server to your Cursor MCP config and install the bridge extension. The server exposes WebMCP browser tools to Cursor over stdio:

{
  "mcpServers": {
    "webmcp-server": {
      "command": "npx",
      "args": ["webmcp-server"]
    }
  }
}

Save this as .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global access). Then install the WebMCP bridge Chrome extension, activate it on a tab with WebMCP tools, and the tools appear in Cursor's agent chat.

Prerequisites

• Cursor IDE installed (any recent version with MCP support)
• Node.js 18 or later
• A website with WebMCP tools registered via navigator.modelContext (see registering your first WebMCP tool) or webmcp-react
• Chrome or a Chromium-based browser

How the Bridge Works

WebMCP tools run inside the browser. Cursor is a desktop application that communicates with MCP servers over stdio, SSE, or Streamable HTTP. These two environments can't talk to each other directly, so a bridge connects them.

The bridge has two components:

1. The Chrome extension monitors browser tabs for WebMCP tools. When you activate the extension on a tab, it discovers every tool registered via navigator.modelContext and forwards tool calls between the browser and a local WebSocket server.

2. webmcp-server is a lightweight MCP server that runs locally. It accepts WebSocket connections from the extension on one side and speaks stdio to Cursor on the other. When Cursor calls a tool, webmcp-server relays the request through the extension to the browser tab, waits for the result, and returns it to Cursor.

The data flow looks like this: Cursor sends a tool call over stdio to webmcp-server, which forwards it over WebSocket to the Chrome extension, which executes it in the browser tab via navigator.modelContext. The response travels back the same path. All communication stays local — nothing leaves your machine.

Step 1: Install the Chrome Extension

Download the WebMCP bridge extension from the webmcp-react GitHub releases. Unzip the archive and load it as an unpacked extension:

1. Open chrome://extensions in Chrome
2. Enable "Developer mode" (toggle in the top right)
3. Click "Load unpacked" and select the unzipped extension folder

The extension icon appears in your browser toolbar. It won't do anything yet — you need the MCP server running first.

[Screenshot: Chrome extensions page with the WebMCP bridge extension loaded and Developer mode enabled]

Step 2: Configure Cursor

Cursor supports MCP server configuration at two levels: project-scoped (.cursor/mcp.json in your project root) and global (~/.cursor/mcp.json). Project-scoped is better if only certain projects use WebMCP tools. Global is better if you want browser tools available everywhere.

Create or edit the config file:

{
  "mcpServers": {
    "webmcp-server": {
      "command": "npx",
      "args": ["webmcp-server"]
    }
  }
}

Cursor spawns webmcp-server as a child process and communicates with it over stdio. The npx command downloads and caches the package on first run, so there's no separate install step. If you prefer to install it globally first, run npm install -g webmcp-server and change the command to "webmcp-server" with an empty args array.

After saving the config, Cursor picks it up automatically. You can verify by opening Cursor Settings → MCP, where webmcp-server should appear in the server list.

[Screenshot: Cursor Settings MCP panel showing webmcp-server listed and enabled]

Using environment variables for the port

The default WebSocket port is 12315. If that conflicts with another service, set the WEBMCP_BRIDGE_PORT environment variable in the Cursor config:

{
  "mcpServers": {
    "webmcp-server": {
      "command": "npx",
      "args": ["webmcp-server"],
      "env": {
        "WEBMCP_BRIDGE_PORT": "12400"
      }
    }
  }
}

Make sure the extension also uses the same port — you can configure this in the extension's options page.

Step 3: Activate the Extension on a Tab

Navigate to a page that has WebMCP tools registered. Click the extension icon in the toolbar. You'll see three activation modes:

• Off — the extension ignores this tab
• Until Reload — tools from this tab are exposed until the page reloads or you navigate away
• Always On — all pages on this origin are bridged, surviving reloads and new tabs

Pick "Always On" for development, since you'll be reloading frequently. The extension icon shows a green dot when it's connected to webmcp-server and a badge with the number of discovered tools.

If the icon shows a yellow dot, the MCP server isn't reachable. Make sure Cursor is running and has spawned the server (check Cursor Settings → MCP for server status).

[Screenshot: WebMCP bridge extension popup showing activation modes and a green connection dot with tool count badge]

Step 4: Use Browser Tools in Cursor

Open Cursor's agent chat (Cmd+L or Ctrl+L) and ask it to perform an action that matches one of your WebMCP tools. For example, if your page registers a search-flights tool:

Search for flights from SFO to JFK on March 15

Cursor's agent sees the tool in its available tools list (namespaced as tab-{tabId}:search-flights) and calls it. The request goes through the bridge to the browser, executes in the page context, and the result comes back to Cursor.

You can also see available tools by typing /tools in Cursor's chat or checking the "Available Tools" section. WebMCP tools appear alongside any other MCP tools you have configured.

Tools are dynamic — they appear when the page loads and disappear when the tab closes or the extension deactivates. If you add a new tool to your website code, reload the page and the extension picks it up automatically.

Adding WebMCP Tools to Your Site

If you haven't added WebMCP tools to your website yet, you have two options.

Plain JavaScript — call navigator.modelContext.registerTool() directly. This works in any website without dependencies:

navigator.modelContext.registerTool({
  name: "get-cart-total",
  description: "Get the current shopping cart total and item count",
  execute: async () => {
    const cart = getCartState();
    return { total: cart.total, items: cart.itemCount };
  }
});

See registering your first WebMCP tool for the full API including input schemas, annotations, and user interaction requests.

React apps — use the webmcp-react library for a hook-based API with Zod schema support and automatic cleanup:

import { useMcpTool } from "webmcp-react";
import { z } from "zod";

function CartTools() {
  useMcpTool({
    name: "get-cart-total",
    description: "Get the current shopping cart total and item count",
    handler: async () => {
      const cart = getCartState();
      return { content: [{ type: "text", text: JSON.stringify(cart) }] };
    },
  });
  return null;
}

See adding WebMCP tools to a React app for setup instructions, the provider, and advanced patterns.

Common Issues

webmcp-server shows as "failed" in Cursor Settings

This usually means the npx command can't be found. Cursor inherits a limited shell environment — if Node.js was installed via nvm, fnm, or a similar version manager, the npx binary might not be on the default PATH. Fix this by using the full path to npx:

{
  "mcpServers": {
    "webmcp-server": {
      "command": "/Users/you/.nvm/versions/node/v22.0.0/bin/npx",
      "args": ["webmcp-server"]
    }
  }
}

On Linux, the path is typically ~/.nvm/versions/node/v22.0.0/bin/npx (or $HOME/.nvm/...). Find your npx path by running which npx in a terminal. Alternatively, install webmcp-server globally and use the absolute path to the binary.

Extension icon shows yellow dot (server not found)

The extension can't reach webmcp-server on its WebSocket port. Check these in order:

1. Cursor is running and the MCP server is enabled (Cursor Settings → MCP → verify green status)
2. The port isn't blocked by a firewall or occupied by another process — run lsof -i :12315 to check
3. If you set a custom WEBMCP_BRIDGE_PORT in Cursor's config, make sure the extension uses the same port in its options page

Tools not appearing in Cursor's agent chat

If the extension shows a green dot and a tool count badge but Cursor doesn't list the tools, try these steps:

1. Open Cursor Settings → MCP and click the refresh icon next to webmcp-server to force a reconnect
2. Check MCP Logs in Cursor's Output panel (View → Output → select "MCP Logs") for error messages
3. Make sure the extension is activated on the correct tab — tools only bridge from tabs where the extension is set to "Until Reload" or "Always On"

Tools disappear after page reload

This is expected behavior if the extension is set to "Until Reload" mode. Switch to "Always On" for persistent bridging during development. With "Always On", the extension re-discovers tools automatically after each page reload.

Next Steps

With Cursor connected to your browser tools, explore these related guides:

• Register your first WebMCP tool — deep dive into navigator.modelContext, input schemas, annotations, and requestUserInteraction for confirmation flows
• Add WebMCP tools to a React app — use webmcp-react for hook-based registration with Zod schemas and automatic lifecycle management
• Connect WebMCP tools to Claude Code — the same bridge works with Claude Code using claude mcp add instead of .cursor/mcp.json