Why does document.modelContext return undefined?

Either WebMCP is off in that browser, or the page isn’t secure. Turn on chrome://flags/#enable-webmcp-testing for your own browser, or add an origin trial token for visitors. Chrome only offers WebMCP on HTTPS pages and localhost.

My tools work in the inspector but not for visitors. Why?

The flag only changes your own browser. For visitors, the page needs a valid WebMCP origin trial token, as a meta tag or an Origin-Trial header.

Chrome says "invocation failed" when a tool runs. What does that mean?

Your execute function threw an error, and Chrome shows a generic message in place of the real one. Catch errors inside execute and return them as a result with isError: true and a message the agent can read.

Guides

Why aren’t my WebMCP tools detected?

Check three things first: the tools are registered on document.modelContext (Chrome doesn't have navigator.modelContext), the page is on HTTPS, and WebMCP is on in the browser you tested with. If those are fine, Chrome may have refused the registration, the tools may be registered too late, or a Content Security Policy may be blocking the script.

Updated 24 September 2026

Check it yourself first

With the WebMCP flag on, open the page over HTTPS and run this in the DevTools console:

document.modelContext                   // undefined: WebMCP is off, or the page isn't secure
await document.modelContext.getTools()  // []: nothing is registered yet

If the list is empty, catch the error from your registration to see Chrome's reason:

try {
  await document.modelContext.registerTool(tool);
} catch (err) {
  console.error("registerTool refused", tool.name, err.message);
}

Causes and fixes

1. The tools are registered on navigator.modelContext

How to tell: Your code calls navigator.modelContext.registerTool(), usually copied from an early example.

Fix: Use document.modelContext. Chrome doesn't have navigator.modelContext, so agents never see tools registered there.

2. The page isn’t on HTTPS

How to tell: The page loads over http://, or the certificate is invalid.

Fix: Serve it over HTTPS with a valid certificate. Chrome only offers WebMCP on secure pages. On HTTP, document.modelContext is undefined.

3. WebMCP is off in the browser you tested with

How to tell: document.modelContext is undefined even on HTTPS.

Fix: Turn on chrome://flags/#enable-webmcp-testing and relaunch. For visitors, the page needs an origin trial token.

4. Chrome refused the registration

How to tell: registerTool() throws an error, for example because a description is missing, a name is used twice, or inputSchema is a string.

Fix: Give every tool a description, pass inputSchema as an object, and register each name once. In React, an effect that runs twice or a component that mounts twice will register a tool twice.

5. Registration happens too late, or only after a click

How to tell: Tools appear only after a slow API call, a login or a user action.

Fix: Register as soon as the page loads and fetch data inside execute. Agents look for tools soon after the page loads. Test WebMCP waits up to 10 seconds for the first one.

6. A Content Security Policy blocks the script

How to tell: The console shows a CSP violation for the script that registers the tools.

Fix: Allow that script in your script-src. A nonce or hash is safer than 'unsafe-inline'.

7. The tools live in a cross-origin iframe

How to tell: A widget or embed registers tools from a different origin than the page.

Fix: Add allow="tools" to the iframe. An iframe from another origin needs it; one from the same origin doesn't.

8. The page sets document.domain

How to tell: Your code, or a library, assigns document.domain.

Fix: Remove it. Chrome turns WebMCP off on pages that set document.domain.

9. Bot protection serves a different page

How to tell: A scanner finds no tools, but the page works in your browser. Firewalls and bot managers can show automated browsers a challenge page.

Fix: Check the page title and final URL in the Test WebMCP report to see what the scan loaded. Let the scanner through, or test in your own browser with the inspector.

Detected, but marked broken

A tool can register and still fail when it's called. Test WebMCP calls every read-only tool and marks it broken if it throws, times out, or returns error text like "Search failed (500)". A tool that runs but finds nothing for a made-up query doesn't count against you. Add an example to each property in the schema and the scan tests with that value.

Common questions

Why does document.modelContext return undefined?: Either WebMCP is off in that browser, or the page isn’t secure. Turn on chrome://flags/#enable-webmcp-testing for your own browser, or add an origin trial token for visitors. Chrome only offers WebMCP on HTTPS pages and localhost.
My tools work in the inspector but not for visitors. Why?: The flag only changes your own browser. For visitors, the page needs a valid WebMCP origin trial token, as a meta tag or an Origin-Trial header.
Chrome says "invocation failed" when a tool runs. What does that mean?: Your execute function threw an error, and Chrome shows a generic message in place of the real one. Catch errors inside execute and return them as a result with isError: true and a message the agent can read.

Scan your page to see what Chrome finds on it. Each failed check in the report comes with a fix.