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

Canonical: https://mudpie.ai/webmcp/guides/diagnose-webmcp-flag-versus-origin-trial-failure/
Breadcrumb: [Home](https://mudpie.ai/) / [WebMCP guides](https://mudpie.ai/webmcp/guides/) / [How do you diagnose a tool that works behind a Chrome flag but not in an origin trial?](https://mudpie.ai/webmcp/guides/diagnose-webmcp-flag-versus-origin-trial-failure/)
Author: Ali Abouelatta (https://mudpie.ai/authors/ali-abouelatta/)
Published: 2026-09-19
Updated: 2026-09-19
Research type: guide
Method: Documentation-derived troubleshooting guide using current Chrome WebMCP and origin-trial guidance. No executed benchmark or third-party test is claimed.

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](https://developer.chrome.com/docs/ai/webmcp) and [origin-trial announcement](https://developer.chrome.com/blog/ai-webmcp-origin-trial).

| 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](https://developer.chrome.com/docs/web-platform/origin-trials) 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](https://developer.chrome.com/docs/ai/webmcp/imperative-api) 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.


## Author disclosure

I cofound Lazyweb and publish Mudpie. This is an owner-written publication, not an independent testing organization. Research notes distinguish observations, sourced reporting and editorial judgment.