What This Guide Covers
The WebMCP origin trial opened with Chrome 149 on June 2, 2026. This guide explains what the trial includes, how to register your domain, and how to implement your first tool using both the declarative and imperative APIs. No background knowledge of WebMCP is assumed.
What Is the WebMCP Origin Trial
An origin trial is Chrome’s mechanism for testing experimental features on live production websites before a feature becomes a permanent standard. You register your domain, receive a token, embed that token in your HTML, and the feature activates for real visitors using Chrome.
WebMCP (Web Model Context Protocol) is the feature being trialled. It allows your website to register named tools — JavaScript functions or annotated HTML forms — that browser-based AI agents can call directly instead of scraping your DOM.
The trial runs from Chrome 149 through Chrome 156. The hard end date is 17 November 2026. After that your token expires.
What Is New in This Trial
Previous to Chrome 149, WebMCP was only accessible in Chrome Canary behind a flag at chrome://flags. With the origin trial now open, four capabilities are available on production traffic for the first time:
Tool listing. AI agents can call document.modelContext.getTools() to retrieve a structured list of every tool your site exposes, including name, description, input schema, and annotations.
Tool execution. Agents can call document.modelContext.executeTool() to invoke a specific tool and receive a result directly, without any UI interaction.
Permissions policy. You can now control at the server level which origins and iframes are permitted to expose tools, using the model-context HTTP header or a meta tag equivalent.
Cross-origin iframe support. Tools registered inside embedded iframes — including third-party iframes — can now be surfaced to the parent page agent, with origin metadata included in the tool object.
Step 1: Register for the Origin Trial
Go to the Chrome Origin Trials registration page:https://developer.chrome.com/origintrials/#/register_trial/4163014905550602241
Enter your web origin — for example https://yourdomain.com
Check “Match all subdomains of the origin” if you want the token to cover subdomains such as app.yourdomain.com or blog.yourdomain.com.
Check “Third-party matching” only if you are injecting the token via script onto other domains. Most site owners do not need this.
Enter an estimate of daily page views. This does not need to be exact.
Accept the terms and click Register. Your token is generated immediately.
Step 2: Add the Token to Your Site
Paste the following into the head section of every page that will use WebMCP:
<meta http-equiv="origin-trial" content="YOUR_TOKEN_HERE">Alternatively you can deliver it as an HTTP response header:
Origin-Trial: YOUR_TOKEN_HEREThe token is specific to your registered origin. If you registered with subdomain matching, the same token works across all subdomains.
Step 3: Check the Feature Is Active
Before writing any tool code, verify the API is available in the browser:
if ('modelContext' in document) {
console.log('WebMCP is active');
} else {
console.log('WebMCP not available — apply graceful fallback');
}Always include this check. The feature is not available in Firefox or Safari at this stage, and not available in Chrome without a valid token on a registered origin.
Step 4a: Register a Tool Using the Declarative API
The declarative API requires no JavaScript. You add two attributes to an existing HTML form. This is the recommended starting point for most sites.
<form
data-mcp-tool-name="searchProducts"
data-mcp-tool-description="Search the product catalogue by keyword">
<input type="text" name="query" placeholder="Search...">
<button type="submit">Search</button>
</form>The browser reads these attributes and automatically creates a tool from the form. The tool name becomes searchProducts. The input schema is derived from the form fields. When an agent calls this tool, it is equivalent to submitting the form with the provided values.
Use this approach for: search forms, contact forms, newsletter signups, booking forms, and filter interfaces.
Step 4b: Register a Tool Using the Imperative API
For complex logic that cannot be expressed through a form — multi-step flows, custom validation, API calls — use the JavaScript imperative API.
navigator.modelContext.registerTool({
name: 'addToCart',
description: 'Add a product to the shopping cart by product ID and quantity',
inputSchema: {
type: 'object',
properties: {
productId: { type: 'string' },
quantity: { type: 'number' }
},
required: ['productId', 'quantity']
}
}, async (input) => {
const result = await addItemToCart(input.productId, input.quantity);
return `Added ${input.quantity} x ${input.productId} to cart`;
});Important: the provideContext() and clearContext() methods from earlier WebMCP drafts were removed in March 2026. Use registerTool() and unregisterTool() only.
What the Agent Sees
When an agent calls getTools() on a page with the above tools registered, it receives an array like this:
[
{
name: 'searchProducts',
description: 'Search the product catalogue by keyword',
inputSchema: '{"type":"object","properties":{"query":{"type":"string"}}}',
annotations: {
readOnlyHint: true,
untrustedContentHint: false
},
origin: 'https://yourdomain.com'
},
{
name: 'addToCart',
description: 'Add a product to the shopping cart by product ID and quantity',
inputSchema: '{"type":"object","properties":{"productId":{"type":"string"},"quantity":{"type":"number"}},"required":["productId","quantity"]}',
annotations: {
readOnlyHint: false,
untrustedContentHint: false
},
origin: 'https://yourdomain.com'
}
]The readOnlyHint annotation tells the agent whether calling this tool changes state. Set it to true for search and read operations, false for anything that writes, adds, or deletes.
The untrustedContentHint annotation tells the agent the tool output may contain user-generated content and should not be blindly trusted. Set this to true for any tool that returns content written by other users.
Testing Without a Real Agent
Google has published a Model Context Tool Inspector extension for Chrome. Install it, open any page with WebMCP tools registered, and you can call your tools manually and inspect the responses — without needing a connected AI agent.
The official sample apps are available at: https://github.com/GoogleChromeLabs/webmcp-tools
These include a declarative API example (Le Petit Bistro menu), an imperative API example (Pizza Maker), and a React app (travel booking). They are the fastest way to see both APIs working end to end.
Cross-Origin Iframe Tools
If you embed a third-party iframe and that iframe registers WebMCP tools, those tools are now surfaced to the parent page agent in this trial. The tool object includes an origin field showing which domain registered it and a window reference pointing to the iframe’s window object.
To allow iframe tools to be surfaced, your parent page must include the permissions policy header:
Permissions-Policy: model-context=(self "https://trusted-partner.com")To block all iframe tools from being surfaced:
Permissions-Policy: model-context=(self)Graceful Degradation
Your site must continue working normally for users where WebMCP is unavailable. The feature check shown in Step 3 is the minimum. For forms using the declarative API, no additional fallback is needed — the attributes are ignored by browsers that do not support them and the form continues to function normally. For the imperative API, wrap all registerTool calls inside the feature check block.
Trial Constraints to Know
The 0.5% rule. If your feature is detected on more than 0.5% of all Chrome page loads as a rolling 14-day median, the origin trial token is automatically disabled by Chrome. This is a hard limit. If your site receives very high traffic, limit WebMCP to specific pages or user segments initially.
Token expiry. Your token expires on 17 November 2026 or when Chrome 156 ships, whichever comes first. Chrome sends renewal reminders by email to the address you registered with.
Spec is still moving. This is an origin trial, not a final standard. API surface, annotations, and schema format may change before Chrome 156. Subscribe to the W3C Web Machine Learning Community Group mailing list to receive spec update notifications.
Official Resources
WebMCP documentation: https://developer.chrome.com/docs/ai/webmcp
Origin trial registration: https://developer.chrome.com/origintrials/#/register_trial/4163014905550602241
Sample apps: https://github.com/GoogleChromeLabs/webmcp-tools
Chrome DevTools WebMCP panel: available in Chrome DevTools under the Application tab once the trial token is active on your page
W3C Community Group draft: https://www.w3.org/community/webmachinelearning/
Leave a Reply