Debug and troubleshoot

Start at the page registry, then follow the MCP-B transport used by your agent. Use Chrome’s built-in tools for browser-owned WebMCP behavior.

Inspect the page registry

Open the browser console and check the active context:

Browser console

console.log('modelContext:', typeof document.modelContext);

const tools = await document.modelContext?.getTools();
console.table(tools?.map(({ name, description }) => ({ name, description })) ?? []);

If the expected tool is absent, confirm that its registration promise resolved and that its AbortSignal remains active. Duplicate names reject registration. Use Chrome’s WebMCP DevTools panel to inspect schemas, invoke tools, and review invocation history. For agent-driven browser inspection, use the upstream Chrome DevTools MCP WebMCP tool reference.

Restore MCP-B initialization

If document.modelContext is undefined, import the runtime before code registers tools:

main.ts

import '@mcp-b/global';

For the tool-only polyfill, initialize it explicitly:

main.ts

import { initializeWebMCPPolyfill } from '@mcp-b/webmcp-polyfill';

initializeWebMCPPolyfill();

If you load the IIFE build, place its script tag before scripts that register tools. See Choose a runtime if the application imports more than one MCP-B runtime. For a standalone polyfill installation, confirm that the polyfill won initialization by inspecting its private marker:

Browser console

document.modelContext?.__isWebMCPPolyfill === true;

Use this marker only for diagnostics and tests. Application behavior must not depend on it. @mcp-b/global replaces the polyfill context with BrowserMcpServer. To check that runtime, add @mcp-b/webmcp-ts-sdk as a direct dependency and use its guard:

runtime-check.ts

import { isBrowserMcpServer } from '@mcp-b/webmcp-ts-sdk';

console.log(isBrowserMcpServer(document.modelContext));

Trace missing relay tools

Run webmcp_list_sources before webmcp_list_tools. This separates a missing browser connection from an empty page registry.

Symptom	Check
`No sources connected`	Confirm the page loaded `embed.js` and the relay process is running.
Source has no tools	Run `document.modelContext.getTools()` in that tab and check registration errors.
`Tool not found`	The tab may have reloaded. Run `webmcp_list_tools` again to refresh discovery.
Connection blocked	Match `--widget-origin` to the host page origin and `data-relay-port` to the relay port.

Keep the relay bound to loopback. Restrict --widget-origin when a specific site should publish tools. See Connect desktop agents with the local relay for configuration and security boundaries.

Fix iframe and tab transport origins

For @mcp-b/transports, configure both sides of the connection:

Set client targetOrigin to the exact origin of the receiving window.
Add the sending window’s exact origin to server allowedOrigins.
Use the same channelId on both transports.
Confirm the iframe has loaded before the parent connects.

Use exact origins by default. An opaque iframe origin requires targetOrigin="*", which disables parent-side origin validation; use it only with the additional controls described in Bridge tools across iframes. See Transports and bridges for the trust boundary.

Hand off browser and agent failures

For invalid or lossy schemas, run the Lighthouse WebMCP schema validity audit, then check Use input schemas and structured output for MCP-B adapters.
If a tool works in isolation but an agent selects it incorrectly, use Chrome’s WebMCP evals guidance.
For current native browser requirements and limitations, use the Chrome WebMCP documentation instead of copying version or flag instructions into your project.

How-To Guides

Adoption

Frameworks

Connectivity

Inspect the page registry

Restore MCP-B initialization

Trace missing relay tools

Fix iframe and tab transport origins

Hand off browser and agent failures

​Inspect the page registry

​Restore MCP-B initialization

​Trace missing relay tools

​Fix iframe and tab transport origins

​Hand off browser and agent failures

Inspect the page registry

Restore MCP-B initialization

Trace missing relay tools

Fix iframe and tab transport origins

Hand off browser and agent failures