> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mcp-b.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Debug and troubleshoot

> Trace MCP-B initialization, tool registration, local relay, and iframe transport failures.

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:

```js title="Browser console" theme={null}
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](https://developer.chrome.com/docs/devtools/application/webmcp) to inspect schemas, invoke
tools, and review invocation history. For agent-driven browser inspection, use the upstream [Chrome
DevTools MCP WebMCP tool
reference](https://github.com/ChromeDevTools/chrome-devtools-mcp/blob/main/docs/tool-reference.md#webmcp).

## Restore MCP-B initialization

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

```ts title="main.ts" theme={null}
import '@mcp-b/global';
```

For the tool-only polyfill, initialize it explicitly:

```ts title="main.ts" theme={null}
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](/how-to/choose-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:

```ts title="runtime-check.ts" theme={null}
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](/how-to/use-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](/how-to/connect-desktop-agents-with-local-relay#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](/how-to/bridge-tools-across-iframes). See [Transports and
bridges](/explanation/architecture/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](https://developer.chrome.com/docs/lighthouse/agentic-browsing/webmcp-schema-validity),
  then check [Use input schemas and structured
  output](/how-to/use-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](https://developer.chrome.com/docs/ai/webmcp/evals).
* For current native browser requirements and limitations, use the [Chrome WebMCP
  documentation](https://developer.chrome.com/docs/ai/webmcp) instead of copying version or flag
  instructions into your project.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.