@mcp-b/webmcp-local-relay reference

@mcp-b/webmcp-local-relay connects WebMCP tools running in browser tabs to desktop MCP clients (Claude Desktop, Cursor, Claude Code, Windsurf) via a localhost WebSocket relay and stdio transport.

Package metadata

npm: @mcp-b/webmcp-local-relay
license: MIT
node: >= 22

Architecture

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

The relay has four layers:

Layer	Description
`LocalRelayMcpServer`	MCP server exposing static and dynamic tools over stdio
`RelayBridgeServer`	WebSocket server managing browser connections and routing calls
Widget iframe	Hidden iframe injected by `embed.js` into the host page
Host page	The webpage with WebMCP tools registered on `document.modelContext`

For a conceptual discussion of transports and bridges, see Transports and Bridges.

Installation

Add this JSON block to your MCP client configuration:

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

You can also run the relay directly:

npx @mcp-b/webmcp-local-relay

A .mcpb bundle file is available from GitHub Releases for Claude Desktop (double-click to install). It starts with the zero-configuration defaults: loopback, automatic port discovery, and all page origins allowed.

Minimal example

CLI options

webmcp-local-relay [options]

  --host, -H               Bind host for local websocket relay (default: 127.0.0.1)
  --port, -p               Preferred root port for the local relay cluster (default: 9333)
  --widget-origin          Allowed host page origin(s), comma-separated (default: *)
  --allowed-origin         Deprecated alias for --widget-origin
  --ws-origin              Deprecated alias for --widget-origin
  --label                  Human-readable relay label reported during discovery
  --workspace              Optional workspace name reported during discovery
  --relay-id               Stable relay identifier reported during discovery
  --invoke-timeout         Browser tool invocation timeout in milliseconds (default: 65000)
  --max-payload            Maximum WebSocket payload size in bytes (default: 10000000)
  --help, -h               Show help

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

# Restrict to trusted origins
npx @mcp-b/webmcp-local-relay --widget-origin https://myapp.com,https://other.com

# Label and identify the relay for multi-relay selection
npx @mcp-b/webmcp-local-relay --label "dev" --workspace "myapp" --relay-id "relay-01"

Static management tools

The relay always exposes three management tools:

Tool	Description
`webmcp_list_sources`	Lists connected browser tabs that publish tools, with tab metadata
`webmcp_list_tools`	Lists all relayed tools with source info
`webmcp_open_page`	Opens a URL, or in server mode refreshes a connected source page by matching origin

Dynamic tool registration

Tools registered on webpages are forwarded to the MCP server as first-class tools. Tool names are sanitized to the character set [a-zA-Z0-9_]. When multiple tabs register a tool with the same name, a short tab-ID suffix disambiguates them:

Situation	Tool name
Single provider	`get_issue`
Multiple providers	`search_ed93`, `search_a1b2`

Tools appear and disappear as tabs open, reload, and close. Names are limited to 128 characters. Sanitization, truncation, or tab-prefix collisions receive deterministic _2, _3, and later suffixes.

Multi-round tool limitations

The relay exposes browser tools as ordinary MCP tool calls. If a browser tool returns an MCP input_required result, the relay returns a tool error because it cannot proxy subsequent input rounds. Register multi-round tool flows directly on the upstream McpServer. The relay omits tools that declare execution.taskSupport: 'required'. It exposes tools that declare 'optional' or 'forbidden' as ordinary calls.

Browser embed

Add a script tag to expose a page’s WebMCP tools to the relay:

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

Tools registered on document.modelContext are picked up automatically, including tools registered after the embed loads. The embed listens for toolchange and polls every two seconds as a fallback.

Embed attributes

Attribute	Default	Description
`data-relay-host`	`127.0.0.1`	Loopback relay host: `127.0.0.1`, `localhost`, or IPv6 loopback
`data-relay-port`	`9333`	Relay WebSocket port
`data-relay-id`	(none)	Filter relays during discovery by stable relay identifier
`data-relay-workspace`	(none)	Filter relays during discovery by workspace name
`data-request-timeout`	`60000`	Per-request timeout in milliseconds
`data-auto-connect`	`true`	Start discovery immediately — set to `"false"` to defer until an explicit `webmcp.connect` message
`data-debug`	(none)	Add this attribute (with no value) to enable diagnostic logging in the browser console

Custom relay port:

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

Increase the per-request timeout for tools that chain several slow API calls:

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

The relay allows 65000 ms by default. If the page timeout is higher, start the relay with a slightly larger limit. For the 120000 ms page setting above, use --invoke-timeout 125000. The embed script fetches the sibling widget.html, injects configuration, and loads it as a hidden blob iframe that inherits the host page origin. The iframe opens a WebSocket to the relay on localhost. Self-hosted copies must serve both embed.js and widget.html; cross-origin hosts must allow the widget fetch with CORS. The relay fails closed if that fetch fails. Page code registers tools on document.modelContext. The embed discovers tools through asynchronous getTools() and executes the returned descriptor through the feature-detected, serialized-JSON executeTool() signature supported by the package and current Chrome implementation.

Reconnection and client mode

After a disconnect, the widget retries the last endpoint once after about 500ms, then rescans the relay range after 10s, 20s, and 30s. If no relay responds, it enters a dormant state and probes the configured or cached endpoint every two minutes. Returning to the tab or sending webmcp.connect triggers immediate rediscovery. Port range discovery and browser probing: Unless --port is explicit, the server tries ports 9333–9348 instead of failing on a single port. The chosen port is persisted to ~/.webmcp/relay-port.json for stable restarts. The widget probes the port range sequentially and caches discovered endpoints in sessionStorage. Subprotocol handshake: WebSocket connections negotiate webmcp.v1 as the primary subprotocol and webmcp-discovery.v1 for discovery probes. On connect, the server sends a server-hello message containing the relay’s identity: instanceId, host, port, relayId, and optional label and workspace. Without --relay-id, relayId defaults to the ephemeral instanceId. The browser responds with a hello message carrying tabId, origin, title, and url. The widget requires hello/accepted before it sends tools and closes the socket if no acknowledgement arrives within one second. Heartbeat: The relay server pings connected sources every 15 seconds. Connections are closed after 25 seconds with no response, enabling fast rediscovery after ungraceful relay shutdowns. Multi-relay selection: Use data-relay-id and data-relay-workspace embed attributes to filter relays during discovery. Only relays whose server-hello identity matches the configured filters are accepted. When a candidate port is owned by a compatible WebMCP relay, a second instance joins it in client mode and proxies tool operations through it. A non-relay service is skipped while scanning the default range; 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.

Runtime compatibility

The relay supports pages using:

@mcp-b/global (recommended for the complete MCP-B runtime)
Native Chrome with document.modelContext.getTools() and the serialized-JSON executeTool() signature that this relay requires
@mcp-b/webmcp-polyfill

The browser embed always uses document-first discovery and executes the current descriptor returned by getTools(). It does not depend on the removed name-based compatibility APIs. file: pages report an opaque null origin, which the polyfill’s descriptor execution path rejects. Local integrations therefore need a non-opaque origin such as http://localhost.

Security

Binds to 127.0.0.1 by default (loopback only).
Default allowedOrigins is *, permitting any browser page to connect. Use --widget-origin to restrict which host page origins can register tools.
--widget-origin validates the browser’s WebSocket Origin header. The injected blob iframe inherits the host page origin, so browser connections cannot override it in hello.
--widget-origin is not local-process authentication. An Origin-less browser-protocol client falls back to its claimed hello.origin, while the internal relay-to-relay protocol is outside this browser-origin check. Keep the relay bound to loopback unless you add a separate trusted boundary.
Chrome can require Local Network Access permission before a public site opens the loopback WebSocket. This browser permission is separate from relay configuration.

Exported API

The package exports the following for programmatic use:

Export	Kind	Description
`LocalRelayMcpServer`	Class	MCP server with stdio transport and dynamic tool sync
`LocalRelayMcpServerOptions`	Type	Construction options
`RelayBridgeServer`	Class	WebSocket relay managing browser connections
`RelayBridgeServerOptions`	Type	Bridge server options
`RelayRegistry`	Class	Multi-source tool aggregation and deduplication
`AggregatedTool`	Type	A tool resolved across multiple sources
`SourceInfo`	Type	Metadata about a connected browser tab
`ResolvedInvocation`	Type	Provider selected as an invocation target
`HelloRequiredError`	Class	Thrown when hello handshake is missing
`sanitizeName`	Function	Sanitizes a tool name to `[a-zA-Z0-9_]`
`buildPublicToolName`	Function	Builds a disambiguated public tool name
`extractSanitizedDomain`	Function	Extracts and sanitizes domain from a URL
`parseCliOptions`	Function	Parses CLI arguments
`printHelp`	Function	Prints CLI usage to stderr
`CliOptions`	Type	Parsed CLI option shape

LocalRelayMcpServerOptions accepts serverName (default webmcp-local-relay), serverVersion (default 0.0.0), and at most one of:

Field	Type	Description
`bridge`	`RelayBridgeServer`	Use an existing bridge instance
`bridgeOptions`	`RelayBridgeServerOptions`	Construct and own a bridge instance

RelayBridgeServerOptions:

Field	Type	Default
`host`	`string`	`127.0.0.1`
`port`	`number`	`9333`
`portExplicitlySet`	`boolean`	`false`
`portRangeEnd`	`number`	`9348`
`persistPath`	`string`	`~/.webmcp/relay-port.json`
`allowedOrigins`	`string[]`	`['*']`
`maxPayloadBytes`	`number`	`10000000`
`invokeTimeoutMs`	`number`	`65000`
`label`	`string`	(none)
`workspace`	`string`	(none)
`relayId`	`string`	Generated relay `instanceId`

`LocalRelayMcpServer` members

Member	Returns	Description
`new LocalRelayMcpServer(options?)`	`LocalRelayMcpServer`	Creates a server with an owned or supplied bridge
`bridge`	`RelayBridgeServer`	Underlying browser bridge
`start()`	`Promise<void>`	Starts the bridge and synchronizes dynamic tools
`connect(transport)`	`Promise<void>`	Connects one MCP transport; callable once per instance lifecycle
`startStdio()`	`Promise<void>`	Connects the MCP server through stdio
`stop()`	`Promise<void>`	Closes the MCP transport and bridge
`listDynamicToolNames()`	`string[]`	Returns sorted dynamic tool names

`RelayBridgeServer` members

Member	Returns	Description
`new RelayBridgeServer(options?, registry?)`	`RelayBridgeServer`	Creates a bridge with an optional supplied registry
`registry`	`RelayRegistry`	Registry used by server mode
`mode`	`'server' \| 'client'`	Current operating mode
`port`	`number`	Bound server port or upstream relay port
`listToolsFromRelay()`	`RelayTool[]`	Upstream tools in client mode; empty in server mode
`listSourcesFromRelay()`	`RelaySourceInfo[]`	Upstream sources in client mode; empty in server mode
`getToolSourceMapFromRelay()`	`Record<string, string[]>`	Upstream public-tool-to-source mapping
`start()`	`Promise<void>`	Starts with the configured port strategy
`stop()`	`Promise<void>`	Stops server, client, timers, and pending invocations
`reloadSource(connectionId)`	`void`	Reloads a connected source; server mode only
`invokeTool(toolName, args, options?)`	`Promise<RelayCallToolResult>`	Routes an invocation locally or through the upstream relay

`RelayRegistry` members

Member	Returns	Description
`new RelayRegistry(now?)`	`RelayRegistry`	Creates an in-memory registry with an optional time provider
`upsertSource(connectionId, hello)`	`void`	Creates or updates source metadata
`registerTools(connectionId, tools)`	`void`	Replaces a source’s complete tool set
`removeConnection(connectionId)`	`void`	Removes a source and its tools
`touchConnection(connectionId)`	`void`	Updates the source’s last-seen time
`listSources()`	`SourceInfo[]`	Lists active sources that publish tools
`listTools()`	`AggregatedTool[]`	Lists aggregated tools by public name
`resolveInvocation(options)`	`ResolvedInvocation \| null`	Selects a provider by source, tab, or recency

HelloRequiredError exposes the rejected source’s read-only connectionId. Tool definition utilities exported at the package root:

Export	Kind	Description
`ToolSchema`	Zod schema	Validates a tool descriptor
`InboundToolSchema`	Zod schema	Validates an incoming tool from the browser
`NormalizedToolSchema`	Zod schema	Normalized tool shape after processing
`CallToolResultSchema`	Zod schema	Validates a tool execution result
`CallToolRequestParamsSchema`	Zod schema	Validates call-tool request params
`ToolAnnotationsSchema`	Zod schema	Validates tool annotation hints
`RelayInvokeArgsSchema`	Zod schema	Validates relayed invocation arguments
`DEFAULT_TOOL_INPUT_SCHEMA`	const	Default `{ type: 'object', properties: {} }`
`normalizeInboundTool`	Function	Normalizes a raw inbound tool descriptor
`RelayTool`	Type	Normalized relay-side tool shape
`RelayCallToolResult`	Type	Result type for a relayed tool call
`RelayToolAnnotations`	Type	Annotation hints for relayed tools
`RelayInvokeArgs`	Type	Type for `RelayInvokeArgsSchema` output

Message schema types and Zod schemas for the browser-relay protocol:

Export	Kind
`BrowserToRelayMessage` / `BrowserToRelayMessageSchema`	Type + Zod
`RelayToBrowserMessage` / `RelayToBrowserMessageSchema`	Type + Zod
`RelayClientToServerMessage` / `RelayClientToServerMessageSchema`	Type + Zod
`RelayServerToClientMessage` / `RelayServerToClientMessageSchema`	Type + Zod
`ServerHelloMessage` / `ServerHelloMessageSchema`	Type + Zod
`RelayHelloAcceptedMessage` / `RelayHelloAcceptedMessageSchema`	Type + Zod
`RelayHelloRejectedMessage` / `RelayHelloRejectedMessageSchema`	Type + Zod
`RelayDescriptor` / `RelayDescriptorSchema`	Type + Zod
`RelaySourceInfo` / `RelaySourceInfoSchema`	Type + Zod

Troubleshooting

Problem	Fix
`No sources connected`	Ensure the page loaded `embed.js` and the relay process is running
`No tools listed`	Ensure tools are registered on the page. The embed listens for changes and polls every two seconds, so load order does not matter.
`Tool not found`	Tab reloaded or disconnected — call `webmcp_list_tools` again to refresh
Connection blocked	Verify `--widget-origin` matches the WebSocket origin (for example, `https://myapp.com`) and the relay port matches `data-relay-port`
`Host response timeout:`	The host page took longer than the per-request timeout (default 60s) to respond. Increase via `data-request-timeout="<ms>"` on the embed script tag

Connect Desktop Agents with Local Relay (how-to guide)
Desktop Agent Relay (tutorial)
@mcp-b/global (runtime reference)
Transports and Bridges (explanation)

Packages

WebMCP platforms and agents

Core runtime

React

Tooling

@mcp-b/webmcp-local-relay reference

Architecture

Installation

Minimal example

CLI options

Static management tools

Dynamic tool registration

Multi-round tool limitations

Browser embed

Embed attributes

Reconnection and client mode

Runtime compatibility

Security

Exported API

`LocalRelayMcpServer` members

`RelayBridgeServer` members

`RelayRegistry` members

Troubleshooting

​Architecture

​Installation

​Minimal example

​CLI options

​Static management tools

​Dynamic tool registration

​Multi-round tool limitations

​Browser embed

​Embed attributes

​Reconnection and client mode

​Runtime compatibility

​Security

​Exported API

​LocalRelayMcpServer members

​RelayBridgeServer members

​RelayRegistry members

​Troubleshooting

​Related

Architecture

Installation

Minimal example

CLI options

Static management tools

Dynamic tool registration

Multi-round tool limitations

Browser embed

Embed attributes

Reconnection and client mode

Runtime compatibility

Security

Exported API

`LocalRelayMcpServer` members

`RelayBridgeServer` members

`RelayRegistry` members

Troubleshooting

Related