How do you diagnose a tool that works behind a Chrome flag but not in an origin trial?

Short version: a Chrome flag proves a local test mode. An origin trial proves that a particular origin, browser version, and page delivery path received a valid trial configuration. They are not the same thing.

If a WebMCP tool works with the flag but disappears when you move to an origin trial, do not rewrite the tool first. Check the browser mode, token, response path, and page security gates in that order.

The two modes answer different questions

Chrome’s WebMCP documentation currently describes a local testing flag and an origin-trial path. The local flag is chrome://flags/#enable-webmcp-testing. The WebMCP origin trial is available from Chrome 149, and the announcement describes it as a time-limited early-access program. See the WebMCP documentation and origin-trial announcement.

Check	Local flag	Origin trial	What a failure tells you
Browser state	A developer changes the local browser flag	The browser must support the trial and the origin must be enrolled	A flag pass does not prove trial eligibility
Scope	Local browser profile	Registered origin and page context	A token for another origin is not evidence for this one
Delivery	No trial token is needed	A valid token must reach the page	A missing or expired token can look like an API bug
Deployment	Usually localhost or a controlled preview	Real response headers, redirects, cache, and frame context matter	Production plumbing is part of the test
What to call it	Local debug result	Origin-trial preview result	Name the mode and date

If you do not record the mode, a flag-only pass can be mistaken for a deployed capability.

1. Prove which mode you are actually running

Write down five things before opening the code:

• Chrome version and profile.
• Exact page origin, including the subdomain.
• Whether the flag is enabled.
• Whether the page is top-level, same-origin embedded, or cross-origin embedded.
• Where the origin-trial token is supposed to arrive.

Use a clean browser profile for the comparison if you can. Old flags, cached responses, and extensions make a useful diagnosis look like a mysterious one.

The comparison needs two rows, not one: flag on / trial off and flag off / trial on. If both are enabled, you have not isolated anything.

2. Check the token at the origin boundary

Chrome’s general origin-trial guidance says a trial token is tied to an origin and must be provided on each page where the feature is enabled. It can be delivered through an Origin-Trial response header, a meta tag, or programmatically, depending on the trial and context. The token is public delivery material, not an account credential.

For a deployed page, check the response that the browser actually received. Do not inspect only the source file or the deployment configuration. A redirect can move the page to another origin. A CDN can serve a cached response without the header. A template can add the token to one route while the agent starts on another.

For an iframe, the relevant origin is the context that runs the JavaScript. A token registered for the parent origin is not automatically proof for a different frame origin. In a bug report, record token status, domain, expiry state, and delivery location; leave raw tokens and private logs out of public tickets.

3. Check the other WebMCP gates

The trial token is not the only gate. Chrome’s WebMCP docs say the API is available only in origin-isolated documents. They also describe the tools Permissions Policy: it defaults to self, and a cross-origin iframe needs an explicit allow="tools" permission. The same page notes that document.domain disables WebMCP.

So a valid trial can still produce no tools when:

• the response has enabled a legacy origin configuration;
• the page is in a cross-origin frame without the required permission;
• a parent policy disables tools for the document or its descendants; or
• the page is loading an API revision different from the one your local fixture used.

These are configuration boundaries. Do not “fix” them by making every origin trusted or by removing authentication. Scope the permission to the intended frame and keep server-side authorization in place.

4. Use a small read-only fixture

The Imperative API documentation uses document.modelContext as the page entry point. The safest diagnostic is one owned page with one read-only tool. Record:

1. Does the page expose document.modelContext?
2. Does the tool register?
3. Does the tool appear in the available-tool view?
4. Does a manual invocation return the expected result?
5. Does the same sequence work in flag mode and trial mode?

This fixture tells you which layer failed; it is not a production benchmark.

The decision

Use the flag to debug page code locally. Use the origin trial to test the origin’s real delivery path and enrolled browser channel. If only the flag row passes, keep the feature behind a progressive fallback. If both rows pass, move to the next authorized rollout check.

Method note

This is a documentation-derived troubleshooting guide. No live production benchmark, cross-browser survey, agent-adoption measurement, or third-party action was performed.