Inspect registered tools
Open the browser console and check whetherdocument.modelContext is available:
"object", the runtime is loaded. List registered tools:
Execute a tool manually
Call any registered tool from the console to verify it works in isolation:execute function, not in the transport or agent connection.
Use Chrome DevTools MCP for debugging
The upstreamchrome-devtools-mcp package 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:
@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. Use a current Chrome
channel that exposes “WebMCP for testing” in chrome://flags.Detect native vs. polyfill
Determine which implementation is active:Common failures
document.modelContext is undefined
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
document.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 tochrome://flags, search for “Experimental Web Platform features”, set it to Enabled, and relaunch Chrome. Alternatively, launch from the command line:
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
TheinputSchema must be valid JSON Schema with type: 'object' at the top level:
Duplicate tool names
CallingregisterTool with a name that is already registered throws an error. To replace a tool, abort the previous registration signal 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
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)
Thelist_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.