The Quick Answer

Install the WebMCP bridge extension, start webmcp-server, and register it as an MCP server in Claude Code:

1. Download the extension from the webmcp-react GitHub releases and load it as an unpacked extension via chrome://extensions
2. Add webmcp-server to Claude Code:

$claude mcp add --transport stdio webmcp-server -- npx webmcp-server

3. Open a tab with WebMCP tools and click the extension icon to activate

The extension reads tools registered via navigator.modelContext in your browser and forwards them over WebSocket to webmcp-server, which exposes them to Claude Code over stdio. Tools appear and disappear dynamically as you navigate between pages.

Prerequisites

• A website with WebMCP tools registered (see registering your first WebMCP tool or adding WebMCP tools with webmcp-react)
• Chrome or a Chromium-based browser
• Node.js 18+ with npx available on your PATH
• Claude Code installed and working

How the Bridge Works

WebMCP tools live inside the browser. They're registered via navigator.modelContext.registerTool() and execute in the page's JavaScript context with access to the DOM, cookies, and authenticated sessions. Claude Code, on the other hand, communicates with MCP servers over stdio — it can't reach into a browser tab directly.

The bridge has two parts that close this gap:

Browser Tab                        Local Machine
┌──────────────────┐              ┌──────────────────┐
│                  │  WebSocket   │                  │
│  Website with    │─────────────▶│  webmcp-server   │
│  WebMCP tools    │  port 12315  │  (MCP server)    │
│                  │              │                  │
└──────────────────┘              └────────┬─────────┘
       ▲                                   │
       │                              stdio│JSON-RPC
  Bridge extension                         │
  reads tools from                ┌────────▼─────────┐
  navigator.modelContext          │                  │
                                  │   Claude Code    │
                                  │                  │
                                  └──────────────────┘

The bridge extension runs in Chrome. It reads the list of tools registered on the active tab via navigator.modelContext and pushes them over a WebSocket connection to the local MCP server.

webmcp-server is a lightweight Node.js process that listens for WebSocket connections from the extension on one side and speaks MCP over stdio on the other. When Claude Code calls a tool, webmcp-server routes the call back through the WebSocket to the extension, which executes the tool in the browser tab and returns the result.

Claude Code supports tools/list_changed notifications, so tools update automatically as you switch tabs, navigate between pages, or activate/deactivate the extension — no restart needed.

Installing the Bridge Extension

Download the latest extension zip from the webmcp-react GitHub releases page. Unzip it to a folder on your machine, then load it into Chrome:

1. Open chrome://extensions
2. Enable Developer mode (toggle in the top-right corner)
3. Click Load unpacked and select the unzipped extension folder
4. Pin the extension to your toolbar for easy access

[Screenshot: Chrome extensions page with Developer mode enabled and the WebMCP Bridge extension loaded, showing the extension icon pinned to the toolbar]

The extension icon appears gray when inactive. It doesn't do anything until you activate it on a specific tab.

Starting webmcp-server

The simplest way to run webmcp-server is through Claude Code's MCP configuration, which launches it automatically. But you can also start it manually to verify it's working:

$npx webmcp-server

This starts the server listening for WebSocket connections on port 12315. You should see output confirming the server is ready. The server stays running until you stop it with Ctrl+C.

If port 12315 conflicts with another process, set a custom port:

$WEBMCP_BRIDGE_PORT=9400 npx webmcp-server

When changing the port, you also need to update the extension's settings to match — open the extension popup and set the same port number. Both sides must agree on the port for the WebSocket connection to establish.

Adding webmcp-server to Claude Code

Register webmcp-server as an MCP server so Claude Code launches and manages it automatically:

$claude mcp add --transport stdio webmcp-server -- npx webmcp-server

This adds it at the user scope, making it available across all projects. To restrict it to the current project instead, add --scope project:

$claude mcp add --transport stdio --scope project webmcp-server -- npx webmcp-server

Alternatively, edit the Claude Code config file directly. For user scope, open ~/.claude.json and add under mcpServers:

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

For project scope, create or edit .mcp.json in your project root:

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

If you're using a custom port, pass it via environment variables:

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

After adding the server, verify it's running:

$claude mcp list

You should see webmcp-server in the list. If you're already in a Claude Code session, the server starts automatically — for more on adding MCP servers to Claude Code, see the dedicated guide.

Activating Tools on a Tab

With the extension installed and webmcp-server running, open a browser tab with your WebMCP-enabled website. Click the extension icon to see the activation panel. There are three modes:

• Off — No tools exposed from this tab. The extension ignores it entirely.
• Until Reload — Tools from this tab are forwarded to webmcp-server, but clear on page reload or navigation to a different origin.
• Always On — All pages on this origin are bridged, surviving reloads and new tabs. This is the most convenient mode during development.

[Screenshot: The WebMCP bridge extension popup showing the three activation modes, with "Always On" selected and a list of discovered tools below]

Once activated, the extension icon changes to show a green dot (connected to webmcp-server) and a badge with the number of tools discovered on the page. If the dot is yellow, the extension can't reach webmcp-server — check that the server is running and the ports match.

Tools appear in Claude Code namespaced as tab-{tabId}:{toolName}. For example, a tool named search-flights on tab 42 becomes tab-42:search-flights. This namespacing prevents collisions when multiple tabs expose tools with the same name.

Using WebMCP Tools in Claude Code

Once everything is connected, you can ask Claude Code to use your browser tools directly. Claude Code sees them like any other MCP tool.

For example, if your travel app exposes a search-flights tool:

> Search for flights from SFO to JFK on April 15th using the browser tools

I'll use the search-flights tool from your browser tab to find flights.
[Calls tab-42:search-flights with {origin: "SFO", destination: "JFK", date: "2026-04-15"}]

Found 3 flights:
- United UA 100, departing 7:00 AM — $342
- Delta DL 400, departing 11:30 AM — $389
- JetBlue B6 15, departing 3:15 PM — $318

The tool executes in your browser tab using your authenticated session. If the tool calls an API that requires login cookies, it works because the request originates from your browser context — not from Claude Code's process.

When you navigate away from a page, its tools are automatically removed. Claude Code receives a tools/list_changed notification and updates its tool list. If you navigate back or open a new tab on the same site with "Always On" enabled, the tools reappear.

Combining with other MCP servers

WebMCP tools coexist with any other MCP servers you have configured. You might have a GitHub MCP server for PR management alongside browser tools for interacting with your app's UI. Claude Code sees all tools from all servers and picks the right one based on your prompt.

Common Issues

Extension icon shows yellow dot instead of green

The yellow dot means the extension can't establish a WebSocket connection to webmcp-server. This usually happens because the server isn't running. Check that Claude Code has started it by running claude mcp list and looking for webmcp-server in the output. If you're running it manually, make sure npx webmcp-server is active in a terminal. Also verify that no firewall or VPN is blocking localhost connections on port 12315.

If you changed the port via WEBMCP_BRIDGE_PORT, the extension needs to know about it too — open the extension popup and update the port to match.

Tools not appearing in Claude Code

Work through this checklist in order:

1. Extension activated? Click the extension icon on the tab — it should show "Until Reload" or "Always On", not "Off"
2. Green dot? The icon should show a green dot, confirming the WebSocket connection to webmcp-server
3. Tools registered on the page? Open DevTools console and run navigator.modelContextTesting.listTools() — if this returns an empty array, your page isn't registering tools correctly (see registering your first WebMCP tool)
4. Server connected to Claude Code? Run claude mcp list to verify webmcp-server appears and is connected

npx: command not found when Claude Code starts webmcp-server

Node.js version managers like nvm or fnm add npx to your PATH via shell initialization scripts that don't always run in non-interactive contexts. If Claude Code can't find npx, use the full path to it in your config:

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

Find your npx path with which npx in your terminal and substitute it in the config.

Tool calls fail with "tab disconnected"

This happens when the browser tab that registered the tool has been closed, navigated away, or reloaded (in "Until Reload" mode). The tool listing in Claude Code may be stale until the next tools/list_changed notification arrives. If this happens repeatedly, switch the extension to "Always On" mode for the origin you're developing against — this automatically re-bridges tools after reloads and navigation.

Next Steps

This guide covered bridging existing WebMCP tools to Claude Code. If you haven't built WebMCP tools yet, start with registering your first WebMCP tool for the raw API or adding WebMCP tools with webmcp-react for the React integration. To connect the same tools to Cursor instead, see connecting WebMCP tools to Cursor. For verifying tools are registered correctly before bridging, the Model Context Inspector is a useful debugging companion.