## 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: ```json { "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](https://github.com/agentcathq/webmcp-react/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: ```json { "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: ```json { "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: ```javascript 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: ```tsx 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`: ```json { "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`

Cursor guides

Connect WebMCP browser tools to Cursor