What is WebMCP? A practical introduction, with code
WebMCP lets a web page give AI agents typed, described tools instead of making them guess at buttons: what it is, how the API works and where it runs.
For twenty years the contract between a website and its visitor has been visual: you draw a form, a person reads the labels and fills it in. AI agents that browse on someone's behalf inherit that contract by accident. They screenshot the page, read the accessibility tree, guess which of the four "Add to cart" buttons is the real one, and simulate clicks. It works often enough to be exciting and fails often enough to be unshippable for anything that matters.
WebMCP is the web platform's answer. It is a proposed standard, incubated in the W3C Web Machine Learning Community Group and driven by the Chrome and Edge teams, that lets a page say to an agent: here are the things you can do on this page, here is what each one needs, call them directly. No scraping, no simulated clicks. The page's own JavaScript runs, the page's own UI updates, and the user watches it happen.
If you know the Model Context Protocol, the mental model is exactly what the name suggests: your web page becomes an in-browser MCP server. Same vocabulary (tools, descriptions, JSON Schema inputs), but instead of a separate backend the agent talks to, the tools live in the tab the user already has open, with the user's session, state and login.
The 30-second version
await document.modelContext.registerTool({
name: 'add-todo',
description: "Add a new item to the user's active todo list",
inputSchema: {
type: 'object',
properties: {
text: { type: 'string', description: 'The text content of the todo item' },
},
required: ['text'],
},
async execute({ text }) {
await addTodoItemToCollection(text) // your existing app code
return { content: [{ type: 'text', text: `Added "${text}".` }] }
},
})
That's the whole imperative API in one call. A tool has a name, a natural-language description, a JSON Schema inputSchema, and an execute callback that receives arguments matching that schema. The browser exposes the tool to whatever agent is attached to the tab — the browser's built-in assistant, an extension, or an agent embedded in the page — and mediates the call.
Notice what the page didn't have to do: stand up an API, replicate auth, or describe its UI. It reused a function it already had.
Why not just MCP?
MCP is a backend integration. An AI platform connects to your server and calls tools there. That's the right shape for a lot of things, but for interactive web apps it has three problems the WebMCP explainer calls out directly:
- Disintermediation. The agent bypasses your UI entirely. The user never sees your product; the platform does.
- Duplicated state and auth. Whatever the user was doing in the tab — their cart, their filters, their session — has to be reconstructed server-side before the agent can act on it.
- A second codebase. You write and maintain a server that mirrors your front-end's capabilities.
WebMCP keeps the human interface primary and layers the agent interface on top of it. The explainer is explicit that it's a complement to MCP, not a replacement: server-side actions with no UI still belong in a backend integration.
The API, piece by piece
Everything hangs off document.modelContext. (Early previews and older blog posts use navigator.modelContext; the spec has since settled on document.modelContext, and current polyfills keep the old name only as a deprecated alias.)
Register a tool, unregister with an AbortSignal
const controller = new AbortController()
await document.modelContext.registerTool(
{
name: 'search-products',
description: 'Search the catalogue by free-text query. Returns up to 20 products with id, name and price.',
inputSchema: {
type: 'object',
properties: { q: { type: 'string', description: 'Search query' } },
required: ['q'],
},
annotations: { readOnlyHint: true },
async execute({ q }, { signal }) {
const res = await fetch(`/api/search?q=${encodeURIComponent(q)}`, { signal })
return res.json()
},
},
{ signal: controller.signal },
)
// Later, e.g. when the user navigates away from the catalogue:
controller.abort() // the tool disappears from the agent's list
Two things worth noticing. The execute callback gets an options object with its own signal, so if the user hits the stop button in the agent UI mid-call, you can cancel the underlying fetch. And registration itself is tied to an AbortSignal, which is the intended way to manage tool lifecycle: register what's relevant to the current page state, tear it down when it isn't.
Annotations
annotations is a small set of hints borrowed from MCP that tell the agent (and the browser) what kind of action this is:
| Hint | Meaning |
|---|---|
readOnlyHint | The tool only reads. Safe to call speculatively. |
consequentialHint | The tool does something the user would care about — places an order, sends a message. Agents should confirm first. |
untrustedContentHint | The result contains content from third parties (reviews, comments) that the model should not treat as instructions. |
Annotate your mutating tools. It's the cheapest way to keep an eager agent from checking out a cart it was only supposed to look at.
React to the page changing
Tools can come and go as the app changes state. Anything listening — an in-page agent, a devtools panel — hears about it:
document.modelContext.addEventListener('toolchange', async () => {
const tools = await document.modelContext.getTools()
console.log('Tools now available:', tools.map(t => t.name))
})
Be the agent: getTools() and executeTool()
The same interface lets a page discover and run tools. This is how "author-provided" agents work — a chat widget you embed on your own site, or one running in an iframe you've granted access to:
const tools = await document.modelContext.getTools()
const search = tools.find(t => t.name === 'search-products')
const result = await document.modelContext.executeTool(search, { q: 'running shoes' })
getTools() returns descriptors (name, description, inputSchema, plus the origin and owner window). By default it only shows same-origin tools; cross-origin frames must opt in with exposedTo on the registering side and fromOrigins on the calling side. It's also the easiest way to test your own tools in a console before any agent is involved.
The declarative API: forms as tools
A lot of the web is forms, and a lot of forms already encode exactly the structure an agent needs — field names, types, required flags. The declarative half of WebMCP lets you expose one with attributes instead of JavaScript:
<form
toolname="search-cars"
tooldescription="Perform a car make/model search"
toolautosubmit
>
<input type="text" name="make" toolparamdescription="The vehicle's make (e.g. BMW, Ford)" required>
<input type="text" name="model" toolparamdescription="The vehicle's model (e.g. 330i, F-150)" required>
<button type="submit">Search</button>
</form>
The browser compiles the form into a tool whose input schema has make and model as required strings. toolautosubmit lets the agent submit without waiting for the user; leave it off and the browser fills the form in, focuses the submit button and hands control back to the person — a nice default for anything with consequences.
To return a structured result instead of navigating, handle the submit event:
form.addEventListener('submit', (event) => {
if (!event.agentInvoked) return // a human submitted it; do the normal thing
event.preventDefault()
event.respondWith(searchCars(new FormData(form))) // resolves to the tool's result
})
Where WebMCP runs today (September 2026)
- Chrome — origin trial live since Chrome 149. For local development flip
chrome://flags/#enable-webmcp-testing. - Edge — origin trial live in Edge 150.
- ChatGPT Desktop — supported.
- Brave — experimental support in Leo.
- Firefox and Safari — standards positions requested, no implementation yet.
The spec is a Community Group draft and details still move (how declarative tools show up in getTools(), output schemas, streaming). But the core — registerTool with name / description / inputSchema / execute, getTools, executeTool, toolchange — has been stable enough that a small ecosystem has formed around it: webmcp-types on npm, polyfills that make document.modelContext exist in every browser (we cover those in the next post), and framework integrations (Angular has experimental support).
Nothing stops you shipping WebMCP as a progressive enhancement right now. Browsers without it ignore the calls; browsers with it get a better agent experience.
A realistic integration
Here's a compact, complete example for a store: three tools that map to a user journey, registered once, with the mutating one annotated.
const mc = document.modelContext
if (mc) {
mc.registerTool({
name: 'search-products',
description: 'Search the catalogue by free-text query. Returns up to 20 products with id, name, price and availability.',
inputSchema: {
type: 'object',
properties: { q: { type: 'string', description: 'What the user is looking for, in their words' } },
required: ['q'],
},
annotations: { readOnlyHint: true },
execute: ({ q }) => api.search(q),
})
mc.registerTool({
name: 'get-product',
description: 'Fetch one product by id, including variants, price and stock.',
inputSchema: {
type: 'object',
properties: { productId: { type: 'string', description: 'Product id from search-products' } },
required: ['productId'],
},
annotations: { readOnlyHint: true },
execute: ({ productId }) => api.product(productId),
})
mc.registerTool({
name: 'add-to-cart',
description: 'Add a product to the shopping cart. Use get-product first to pick a valid variant. Returns the updated cart.',
inputSchema: {
type: 'object',
properties: {
productId: { type: 'string', description: 'Product id' },
variantId: { type: 'string', description: 'Variant id (size/colour). Required if the product has variants.' },
qty: { type: 'integer', minimum: 1, description: 'Quantity, default 1' },
},
required: ['productId'],
},
annotations: { consequentialHint: true },
async execute({ productId, variantId, qty = 1 }) {
const product = await api.product(productId)
if (!product) throw new Error(`Unknown product "${productId}". Call search-products to find a valid id.`)
if (product.variants.length && !variantId)
throw new Error(`This product has variants: ${product.variants.map(v => v.id).join(', ')}. Pass one as variantId.`)
const cart = await store.addToCart(productId, variantId, qty)
renderCart(cart) // keep the visible UI in sync — the user is watching
return cart
},
})
}
Errors are sentences, not codes. That's deliberate: when a tool fails, the message is what the model reads to decide what to try next. "Invalid input" gives it nothing; "This product has variants: … pass one as variantId" lets it recover in one step.
What happens after you ship it
This is the part nobody talks about. Once your tools are live, agents will start calling them, and you will have almost no idea how it's going. Browser analytics measure page views and clicks — an agent calling add-to-cart through document.modelContext fires neither. Did anyone call the tool? With what arguments? Did it throw? Did they make it to checkout, or drop out at the variant error you never knew was confusing?
That gap is why we built AgentStats. One script tag or npm i @agentstats/sdk wraps every registerTool call so you see each tool call, its arguments (with the keys you choose redacted client-side), duration and outcome, grouped into sessions and funnels — and a readiness score that flags the vague descriptions and unannotated mutating tools before an agent trips over them.
<script src="https://YOUR-INSTANCE/sdk/v1.js" data-key="al_pub_…" async></script>
Add it before you register tools and nothing else changes. Or paste your getTools() output into the inspector first and see how your tools score with no install at all.
Further reading
- WebMCP explainer — the canonical overview, use cases and best practices
- WebMCP specification — the Community Group draft
- Declarative API explainer
- Chrome's WebMCP docs — origin trial, demos, security guidance
- Model Context Protocol — the backend protocol WebMCP shares its vocabulary with