Skip to main content

​
Inspect registered tools

Open the browser console and check whether navigator.modelContext is available: 
console.log('modelContext:', typeof navigator.modelContext);
console.log('modelContextTesting:', typeof navigator.modelContextTesting);
If both return "object", the runtime is loaded. List registered tools: 
const tools = await navigator.modelContextTesting.listTools();
console.log('Registered tools:', tools.map(t => t.name));

​
Execute a tool manually

Call any registered tool from the console to verify it works in isolation: 
const result = await navigator.modelContextTesting.executeTool(
  'my_tool',
  '{"query": "test"}'
);
console.log('Result:', result);
If the tool returns an error, the problem is in the tool’s execute function, not in the transport or agent connection.

​
Use Chrome DevTools MCP for debugging

@mcp-b/chrome-devtools-mcp includes a built-in debug-webmcp prompt that diagnoses connection and registration issues. See Use Chrome DevTools MCP for setup. Once configured, ask your MCP client: 
Use the debug-webmcp prompt with url=http://localhost:3000
The agent will check whether @mcp-b/global is loaded, list discovered tools, and report any connection failures.

​
Use the Model Context Tool Inspector

The Chrome team publishes a Model Context Tool Inspector extension. Install it from the Chrome Web Store, then open its side panel on any page to see registered tools and execute them with JSON input.
The inspector requires the experimental navigator.modelContextTesting API. Enable “WebMCP for testing” in chrome://flags on Chrome 146.0.7672.0 or higher.

​
Detect native vs. polyfill

Determine which implementation is active: 
if (!navigator.modelContext) {
  console.log('No modelContext — polyfill not loaded');
} else if (navigator.modelContextTesting?.constructor.name.includes('WebModelContext')) {
  console.log('Polyfill detected');
} else {
  console.log('Native API');
}

​
Common failures

The polyfill has not loaded, or it loaded after your code ran.
1

Verify the import exists

Confirm your entry point includes import '@mcp-b/global' or import { initializeWebMCPPolyfill } from '@mcp-b/webmcp-polyfill'.
2

Check import order

The polyfill import must run before any code that calls navigator.modelContext. Move it to the top of your entry file.
3

For script tags, check load order

Place the @mcp-b/global script tag before any script that registers tools.

​
Chrome flags not enabled (native API)

If you are testing the native browser API without the polyfill, enable the experimental flag. Navigate to chrome://flags, search for “Experimental Web Platform features”, set it to Enabled, and relaunch Chrome. Alternatively, launch from the command line: 
google-chrome --enable-experimental-web-platform-features http://localhost:3000
See Browser Support and Flags for platform-specific commands.

​
Tools not appearing in the agent

1

Verify tools are registered

Run navigator.modelContextTesting.listTools() in the console. If the list is empty, your registerTool calls have not executed yet.
2

Check transport connection

If you use a browser extension or local relay, confirm it is running and connected. For the local relay, run webmcp_list_sources from your MCP client.
3

Check registration timing

Tools must be registered before the client queries them. If your tools register asynchronously (after a fetch or user action), the client may have already queried and found nothing. Register tools as early as possible.

​
Schema validation errors

The inputSchema must be valid JSON Schema with type: 'object' at the top level: 
// Wrong — missing type
inputSchema: {
  properties: { query: { type: 'string' } }
}

// Correct
inputSchema: {
  type: 'object',
  properties: { query: { type: 'string' } },
  required: ['query']
}

​
Duplicate tool names

Calling registerTool with a name that is already registered throws an error. To replace a tool, call unregisterTool with the existing name first, then register the new version. Use unique, descriptive names like search_products or search_docs to avoid collisions across components.

​
Local relay not discovered

SymptomFix
No sources connectedConfirm the page loaded embed.js and the relay process is running on the expected port (default: 9333).
No tools listedConfirm tools are registered on navigator.modelContext before embed.js queries them. If tools register after page load, verify your runtime emits toolschanged events.
Tool not foundThe tab may have reloaded or disconnected. Call webmcp_list_tools again to refresh.
Connection blockedVerify --widget-origin matches your host page origin, and the relay port matches the data-relay-port attribute on the embed script.
See Connect Desktop Agents with Local Relay for full setup instructions.

​
Transport origin mismatch

When using @mcp-b/transports with TabServerTransport or iframe transports, the targetOrigin and allowedOrigins settings must match. Set targetOrigin to the exact origin of the receiving window (for example, https://myapp.com). Set allowedOrigins on the server side to accept messages only from trusted origins. Using "*" disables origin checking and is appropriate only during development. See Transports and Bridges for how origin validation works across transport types.

​
WebMCP not detected (Chrome DevTools MCP)

The list_webmcp_tools tool returns “WebMCP not detected” when the current page has not loaded @mcp-b/global or has no tools registered.
1

Confirm the page uses @mcp-b/global

Check the page source or network tab for the @mcp-b/global import.
2

Navigate and re-check

WebMCP auto-reconnects on navigation. After navigating to a page with tools, call list_webmcp_tools again.
3

Check the console for errors

Use list_console_messages in your MCP client to see if tool registration threw an error.