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 { installWebMCP } from '@mcp-b/webmcp-polyfill';

installWebMCP();

The polyfill installs nothing on insecure pages or in browsers older than Chrome 126, Firefox 126, or Safari 18, so document.modelContext stays undefined there. 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. The standalone polyfill has no public runtime marker. @mcp-b/global replaces the core 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));

Pass tool error details to agents

When a tool throws, the polyfill reports only the generic Tool execution failed to the caller, including callers that reach the tool through the local relay. To give the agent details, return a result with isError: true and a text content item instead of throwing. See Use input schemas and structured output for a validation example.

Trace missing relay tools

Run webmcp_list_sources before webmcp_list_tools. This separates a missing browser connection from an empty page registry. If a source has no tools, inspect that tab’s page registry as shown above. For other relay symptoms, see Troubleshoot common issues.

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

Pass tool error details to agents

Trace missing relay tools

Fix iframe and tab transport origins

Hand off browser and agent failures

​Inspect the page registry

​Restore MCP-B initialization

​Pass tool error details to agents

​Trace missing relay tools

​Fix iframe and tab transport origins

​Hand off browser and agent failures

Inspect the page registry

Restore MCP-B initialization

Pass tool error details to agents

Trace missing relay tools

Fix iframe and tab transport origins

Hand off browser and agent failures