guide · webmcp · updated 29 october 2026
WebMCP, explained: give AI agents tools instead of a page to scrape.
WebMCP is a proposed browser API allowing a site to register tools: each defined by a name, description, input schema, and JavaScript function that an in-browser AI agent can invoke directly. This write-up covers the current draft API, browser support, and the four tools registered here, callable via the panel on this page.
the short answer
What WebMCP is, in one minute.
Today an AI agent that books a table or files a form on your site works from screenshots and the DOM. It guesses which button does what, and it breaks when the layout changes. WebMCP gives the agent a contract instead. Your page calls document.modelContext.registerTool() with a tool such as book_table, a plain-language description and a JSON Schema for its input. The agent reads that list, calls the tool with structured arguments, and your JavaScript does the work inside the visitor's own session.
The spec is a Draft Community Group Report from the W3C Web Machine Learning Community Group, last dated 27 October 2026. Two of its four editors are from Microsoft, and Google runs the Chrome implementation. The name borrows from Anthropic's Model Context Protocol, but nothing here talks to an MCP server: the tools live in the page.
- Agent takes a screenshot
- Model guesses which element is the search box
- Types, waits, takes another screenshot
- Parses results out of the rendered page
- Agent reads the page's tool list
- Calls
search_site({ query }) - Gets structured results back as JSON
where it runs
Browser and agent support, October 2026.
| browser | status | detail | source |
|---|---|---|---|
| Chrome | Origin trial, Chrome 149 to 156 | An extension to Chrome 162 was requested on 28 September 2026. Not shipped by default; the intent estimated Chrome 157. | blink-dev, 28 Sep 2026 |
| Edge | Origin trial from Edge 150 | Separate registration from Chrome's. The trial runs until 30 March 2027. | Microsoft Edge origin trials |
| Firefox | Position: neutral | Mozilla engineers favour the imperative API and co-authored the consequentialHint annotation. | mozilla/standards-positions #1412 |
| Safari | Position: oppose | WebKit treats agents as assistive technology and has asked for a different venue. | WebKit/standards-positions #670 |
| Agents | ChatGPT Desktop, Brave Leo | ChatGPT Desktop is listed as supporting WebMCP; Brave has experimental support in Leo. | implementation-status.md, 29 Sep 2026 |
read this before copying code
Most WebMCP tutorials describe an API that no longer exists.
WebMCP got its first wave of coverage when Chrome opened an early preview in February 2026. The spec has changed a lot since then, and most of the articles that rank for it still show the February version. These are the changes that break copied code, from the spec commit history.
- provideContext() and clearContext() removed.
- unregisterTool() replaced: you unregister by aborting the AbortSignal passed to registerTool().
- navigator.modelContext moved to document.modelContext.
- registerTool() became async and now returns a promise.
- The client argument to execute, and requestUserInteraction() with it, removed.
- getTools() and executeTool() added for in-page agents, plus an AbortSignal on execution.
- consequentialHint and debugging annotations added, with toolactivated and toolcancel events.
- The declarative form API removed from the spec. Chrome still documents and ships it in the trial.
the imperative api
Registering a tool with document.modelContext.
The imperative API is the one in the spec, and by Chrome's account the one most sites use. Feature-detect document.modelContext, call registerTool(), and handle the rejection: it fails with InvalidStateError on a bad or duplicate name and NotAllowedError when a Permissions-Policy blocks the tools feature. This is the search tool registered on every page of this site, trimmed for reading.
if ('modelContext' in document) {
document.modelContext.registerTool({
name: 'search_site',
title: 'Search gautamkhorana.com',
description: 'Full-text search across the guides, blog posts, service pages and free tools. Returns up to five pages with title, URL and a short excerpt.',
inputSchema: {
type: 'object',
properties: { query: { type: 'string', description: 'What to search for, in a few words' } },
required: ['query'],
},
annotations: { readOnlyHint: true },
async execute({ query }, { signal }) {
const results = await searchIndex(query, { signal });
return { results: results.slice(0, 5) };
},
}).catch((err) => console.warn('WebMCP:', err.name));
}| field | what the spec says |
|---|---|
name | 1 to 128 characters: letters, digits, underscore, hyphen and dot. A duplicate or invalid name rejects with InvalidStateError. |
title | Optional label for browser UI. |
description | Required and non-empty. This is what the model reads to decide whether to call the tool. Chrome suggests 500 characters at most. |
inputSchema | Optional JSON Schema object. The browser does not validate input against it before calling execute, so check the input yourself. |
execute | execute(input, { signal }) returns a promise of any JSON-serialisable value. There is no client or agent argument. |
annotations | readOnlyHint, untrustedContentHint, consequentialHint and debugging. All default to false. |
Unregistering, and the other methods
The API provides no unregisterTool(). Instead, pass an AbortSignal at registration and fire it once the tool becomes obsolete. There is no in-place update either: to amend a description, abort the active instance and re-register.
const controller = new AbortController();
await document.modelContext.registerTool(tool, { signal: controller.signal });
// Later, when the tool no longer applies (the cart emptied, the user logged out):
controller.abort();Two more methods exist for agents written in JavaScript inside the page or an iframe: getTools() lists the registered tools, and executeTool(tool, input) runs one. The demo below uses both. Three events fire on document.modelContext: toolchange when the list changes, toolactivated when a call starts and toolcancel when the caller cancels.
The declarative form API
Chrome also lets you turn an existing form into a tool with HTML attributes: toolname and tooldescription on the form, toolparamdescription on its fields, and toolautosubmit if the agent may submit without the visitor pressing the button. In the submit handler, event.agentInvoked tells you an agent sent it, and event.respondWith() returns a result to the agent after you call preventDefault(). But the spec dropped the declarative API on 8 October 2026 "for now", so treat it as a Chrome experiment and build on the imperative API.
<form action="/contact/" method="post"
toolname="send_enquiry"
tooldescription="Fills the enquiry form with name, email and message. The visitor reviews it and presses Send.">
<label for="name">Name</label>
<input id="name" name="name" required
toolparamdescription="Full name of the person sending the enquiry">
<label for="email">Email</label>
<input id="email" name="email" type="email" required>
<button type="submit">Send</button>
</form>live on this page
Call this site's tools from your browser.
Every page on gautamkhorana.com registers four tools: search_site, get_page_info, scroll_to_section and get_contact_options. The panel below acts as a tiny in-page agent. It lists the tools with getTools() and runs them with executeTool(), the same calls a browser agent makes. It needs a browser with WebMCP switched on.
Output appears here.
This browser does not expose document.modelContext. In Chrome or Edge, open chrome://flags/#enable-webmcp-testing, enable it, relaunch and reload this page. The site needs no origin trial token for flagged browsers.
webmcp vs mcp
Same idea, different place to run.
| aspect | mcp server | webmcp |
|---|---|---|
| Where the tools live | On a server you run | In the page's JavaScript, while the tab is open |
| Whose credentials | The server's own keys or OAuth | The visitor's current session in the browser |
| What it offers | Tools, resources and prompts | Tools only |
| Availability | Always on | Only while the page is loaded |
| Network hop | Agent to server | None: the tool runs in the page |
security model
What protects the visitor, and what does not.
- Secure contexts only. On plain http,
document.modelContextdoes not exist; localhost counts as secure for development. - A Permissions-Policy feature called
toolsgates every method. The default is the page itself and same-origin iframes;Permissions-Policy: tools=()switches it off. - Cross-origin use needs three opt-ins:
allow="tools"on the iframe, the tool listing the caller inexposedTo, and the caller listing the frame infromOrigins. - The spec defines no consent prompt. Confirmation is the agent's job, and
consequentialHintis how a site flags actions that need one. - Annotations are hints. The spec warns that a malicious site can omit or misstate them, so agents should not trust them blindly, and neither should you trust tool input: validate it as you would any form post.
testing
Five steps from flag to real visitors.
- Turn the flag on. In Chrome, open chrome://flags/#enable-webmcp-testing, set it to Enabled and relaunch. Edge uses the same flag name in Canary and Dev.
- Inspect in DevTools. The Application panel has a WebMCP pane that lists registered tools, logs each call with its input and output, and can run a tool by hand.
- Drive it with an agent. Google's Model Context Tool Inspector extension lists tools and runs prompts against them with your own Gemini key. But note that the example agent extension in GoogleChromeLabs needs Chrome 155 or later.
- Audit it. Lighthouse has an informational Registered WebMCP tools audit, and warns when a page registers more than 40 tools.
- Ship it to real visitors. Register for the origin trial and add the token as a meta tag or an Origin-Trial header. Chrome and Edge register separately.
my take
Should you ship WebMCP now?
Ship the read-only tools now, and wait on the rest. Search, product lookup and price checks wrap code your page already runs, take an afternoon, and do nothing at all in browsers without the API. That is the work this site has done, and it cost one small inline script.
Hold off on tools that spend money or send messages until the agent side settles. The spec leaves consent to the agent, Safari openly opposes the draft, and the interface endured six breaking revisions between March and October. When implementing mutations, tag them with consequentialHint and enforce server-side or UI confirmation within your own stack.
The primary argument for adopting this now is interface hygiene. Drafting explicit tool descriptions forces clear definitions of what each on-page capability requires and returns. And that clarity is not theoretical: it flows directly into better form design, cleaner structured data, and tighter llms.txt definitions, regardless of which agent standard wins.
common questions
WebMCP FAQ.
What is WebMCP?
WebMCP is a proposed browser API that lets a website register tools that AI agents can call. Each tool has a name, a description, an input schema and a JavaScript function. So an agent working in the browser calls search_flights or add_to_cart directly instead of reading screenshots and guessing where to click. The draft is published by the W3C Web Machine Learning Community Group, with Microsoft among its editors and Google behind the Chrome implementation.
Is WebMCP the same as MCP?
No. They share vocabulary, but they run in different places. MCP (the Model Context Protocol) connects an agent to a server you run, with its own credentials, and offers tools, resources and prompts. WebMCP tools run inside the open web page and use the visitor's existing session, and the spec only covers tools. The explainer describes WebMCP pages as something like in-page MCP servers, and positions WebMCP as a complement to a backend MCP server, not a replacement.
Which browsers support WebMCP?
As of late October 2026, Chrome runs WebMCP as an origin trial from Chrome 149 to 156, with an extension to Chrome 162 requested. Edge runs its own origin trial from Edge 150 until 30 March 2027. Mozilla's published position is neutral and WebKit's is oppose, so Firefox and Safari do not support it. On the agent side, ChatGPT Desktop is listed as supporting it, and Brave Leo has experimental support.
Is navigator.modelContext deprecated?
Yes. The spec moved the API from navigator.modelContext to document.modelContext on 27 May 2026, and Chrome's documentation now uses document.modelContext. But many tutorials from February and March 2026 still show the old object, along with provideContext(), clearContext() and unregisterTool(), all of which have been removed. Feature-detect document.modelContext and nothing else.
How do I enable WebMCP in Chrome?
To test locally, open chrome://flags/#enable-webmcp-testing, enable it, and relaunch Chrome. Open DevTools, switch to the Application panel, and inspect registered tools in the WebMCP pane. And for visitors running standard builds, register your site for the WebMCP origin trial and inject the trial token into your pages.
Does WebMCP help SEO?
Not directly. WebMCP tools are neither crawled nor treated as ranking signals. They dictate how reliably an AI agent executes tasks once on site: searching your catalogue, checking a price, completing a booking. Chrome's own data shows origin trial tokens on about 0.51% of page loads, yet actual tool calls run orders of magnitude lower. So treat this as infrastructure prep, not a traffic acquisition channel.
Do I need user consent before an agent calls a tool?
The spec defines no consent prompt. Confirmation is left to the agent and the browser, and the site signals risk with annotations: readOnlyHint for tools that change nothing, and consequentialHint for actions that are significant or cannot be undone, which agents can use to require a confirmation step. Google's example agent asks before any tool that is not read-only. For anything that spends money or sends a message, keep a human confirmation in your own flow as well.
further reading
make your site agent-ready
Want WebMCP tools on your product?
Every MVP I build registers WebMCP tools at deployment. On mature codebases, I audit which actions warrant exposure, implement them against the latest specification, and validate execution within DevTools alongside a live agent before shipping to production.