Connect WebMCP to Claude Desktop and Cursor

This guide shows you how to bridge WebMCP tools from browser tabs to desktop AI agents using @mcp-b/webmcp-local-relay.

 Browser Tab                          Local Machine
┌──────────────────────┐             ┌──────────────────────┐
│                      │  WebSocket  │                      │
│   Website with       ├────────────▶  webmcp-local-relay   │
│   WebMCP tools       │  localhost  │   (MCP server)       │
│                      │             │                      │
└──────────────────────┘             └──────────┬───────────┘
                                               │
                                         stdio │ JSON-RPC
                                               │
                                    ┌──────────▼───────────┐
                                    │                      │
                                    │   Claude / Cursor /  │
                                    │   any MCP client     │
                                    │                      │
                                    └──────────────────────┘

Configure your MCP client

Add the relay server to your MCP client configuration. This works with Claude Desktop, Cursor, Windsurf, Claude Code, or any client that speaks MCP over stdio.

{
  "mcpServers": {
    "webmcp-local-relay": {
      "command": "npx",
      "args": ["-y", "@mcp-b/webmcp-local-relay@latest"]
    }
  }
}

claude mcp add webmcp-local-relay -- npx -y @mcp-b/webmcp-local-relay@latest

For Claude Desktop, you can also download the .mcpb bundle from GitHub Releases and double-click to install. No terminal required.

Add the embed script to your page

The relay discovers tools through a hidden iframe injected by embed.js. Add a single script tag to your page:

<script src="https://cdn.jsdelivr.net/npm/@mcp-b/webmcp-local-relay@latest/dist/browser/embed.js"></script>

If your page already registers tools on document.modelContext, they are picked up automatically. Tools registered after embed.js loads are also discovered through toolchange events and a polling fallback; script order does not control discovery. If you are new to WebMCP, this complete example loads @mcp-b/global, registers a tool, and adds the embed:

<script src="https://cdn.jsdelivr.net/npm/@mcp-b/global@latest/dist/index.iife.js"></script>
<script>
  void document.modelContext
    .registerTool({
      name: 'get_page_title',
      description: 'Get the current page title',
      inputSchema: { type: 'object', properties: {} },
      execute: async () => ({ content: [{ type: 'text', text: document.title }] }),
    })
    .catch(console.error);
</script>
<script src="https://cdn.jsdelivr.net/npm/@mcp-b/webmcp-local-relay@latest/dist/browser/embed.js"></script>

Serve local pages from an HTTP origin such as http://localhost:3000. Do not open them as file: URLs, whose opaque origin cannot be used for descriptor-based tool execution.

Verify the connection

Once the relay is running and your page has loaded embed.js, your AI agent has access to three management tools:

Tool	What it does
`webmcp_list_sources`	Lists connected browser tabs with metadata (tab ID, origin, URL, title, tool count)
`webmcp_list_tools`	Lists all relayed tools with source info
`webmcp_open_page`	Opens a URL in the default browser or refreshes a connected source page by matching origin

Tools also register as first-class MCP tools using their original name. When multiple tabs register a tool with the same name, the relay appends a short tab-ID suffix for disambiguation (e.g. search_ed93, search_a1b2). Ask your agent to list sources or tools to confirm the connection is working. Try webmcp.sh as a test target; it registers tools for SQL queries, entity management, navigation, and more.

webmcp.sh landing page showing registered WebMCP tools — webmcp.sh: a live demo app with WebMCP tools you can relay to any desktop agent

Use a custom port

The relay prefers WebSocket port 9333 on 127.0.0.1. If you need a fixed port, configure both sides: Relay CLI:

npx @mcp-b/webmcp-local-relay --port 9444

Embed script:

<script
  src="https://cdn.jsdelivr.net/npm/@mcp-b/webmcp-local-relay@latest/dist/browser/embed.js"
  data-relay-port="9444"
></script>

An explicit --port selects that exact root port. A compatible relay already using it is shared in client mode; an unrelated process using it causes startup to fail.

Restrict allowed origins

By default, the relay accepts connections from any browser page (*). For production or shared machines, restrict which origins can register tools:

# Single origin
npx @mcp-b/webmcp-local-relay --widget-origin https://myapp.com

# Multiple origins
npx @mcp-b/webmcp-local-relay --widget-origin https://app1.com,https://app2.com

The --widget-origin flag validates the browser’s WebSocket Origin header. The injected widget inherits the host page origin, so browser code cannot replace it with a different value in the handshake. This flag is not local-process authentication; keep the relay bound to loopback unless you provide another trusted boundary.

Handle multiple MCP clients

If a candidate port belongs to a compatible WebMCP relay, a second instance joins it in client mode and proxies tool operations through it. During default discovery, an unrelated service is skipped and the relay tries the next port in 9333–9348; an explicitly selected occupied port fails. If the server relay stops, the client promotes itself back to server mode after a reconnection cycle. This lets multiple MCP clients share the same browser connections without manual configuration.

Troubleshoot common issues

Problem	Fix
`No sources connected`	Confirm the page loaded `embed.js` and the relay process is running
`No tools listed`	Confirm tools are registered on the page. The embed detects changes and polls every two seconds, regardless of script order.
`Tool not found`	The tab reloaded or disconnected. Call `webmcp_list_tools` to refresh
Connection blocked	Verify `--widget-origin` matches the WebSocket origin and the relay port matches `data-relay-port`

After a disconnect, the widget retries the last endpoint once after about 500ms, then scans after 10s, 20s, and 30s. It then enters a dormant state that probes every two minutes; returning to the tab triggers immediate rediscovery. See the relay reference for the complete behavior.

Local Relay Reference for the full CLI options and architecture details
Transports and Bridges for how the relay fits into the WebMCP transport layer
Desktop Agent Relay Tutorial for a step-by-step walkthrough from scratch

How-To Guides

Adoption

Frameworks

Connectivity

Connect WebMCP to Claude Desktop and Cursor

Configure your MCP client

Add the embed script to your page

Verify the connection

Use a custom port

Restrict allowed origins

Handle multiple MCP clients

Troubleshoot common issues

​Configure your MCP client

​Add the embed script to your page

​Verify the connection

​Use a custom port

​Restrict allowed origins

​Handle multiple MCP clients

​Troubleshoot common issues

​Related pages

Configure your MCP client

Add the embed script to your page

Verify the connection

Use a custom port

Restrict allowed origins

Handle multiple MCP clients

Troubleshoot common issues

Related pages