---
title: "WebMCP"
description: "Browser-native, page-scoped tools for agents, including the current W3C Community Group API and the older webmcp.dev library."
url: "https://agentsurface.dev/docs/protocols/webmcp"
lastVerified: 2026-09-25
lastModified: 2026-09-25T05:46:01.000Z
---
## Summary [#summary]
WebMCP lets a web page expose structured tools to an agent that is already visiting the page. The current specification is a W3C Community Group draft, not a W3C Standard. Its imperative API is `document.modelContext`; Chrome also documents a declarative form-based API. Chrome's origin trial starts in Chrome 149, and local development can use `chrome://flags/#enable-webmcp-testing`.
WebMCP is not remote MCP in a browser. The specification deliberately does not prescribe the Model Context Protocol wire format: a browser may bridge page tools to MCP, function calling, or another agent runtime. Use remote MCP for server-side capabilities that must be callable without visiting a page; use WebMCP when the page's current DOM, session, and user-visible state are the useful execution context.
* Current API: `document.modelContext.registerTool(...)`
* Scope: tools exposed by the active page and permitted frames
* Transport: browser-defined; the WebMCP specification does not require MCP JSON-RPC
* Status: Draft Community Group Report, dated 2026-09-17
* Chrome: origin trial from Chrome 149; no cross-browser commitment yet
## Minimal Imperative Tool [#minimal-imperative-tool]
```ts
const registration = new AbortController();
await document.modelContext.registerTool(
{
name: "cart_add_item",
description:
"Adds the selected product to the current user's cart. Use only after the user has chosen a variant and quantity.",
inputSchema: {
type: "object",
required: ["variantId", "quantity"],
properties: {
variantId: { type: "string" },
quantity: { type: "integer", minimum: 1, maximum: 20 },
},
},
annotations: {
readOnlyHint: false,
untrustedContentHint: false,
},
execute: async ({ variantId, quantity }, { signal }) => {
const response = await fetch("/api/cart/items", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ variantId, quantity }),
signal,
});
if (!response.ok) {
throw new Error(`Cart update failed with ${response.status}`);
}
return { status: "added", variantId, quantity };
},
},
{ signal: registration.signal },
);
// Remove the capability when the page state no longer supports it.
registration.abort();
```
Keep the registered tool set synchronized with the page state. A checkout tool should disappear when the cart is empty; a destructive tool should not remain registered merely because the component that created it unmounted incorrectly.
## Declarative Form Tools [#declarative-form-tools]
Chrome's [declarative API](https://developer.chrome.com/docs/ai/webmcp/declarative-api) turns a plain `
```
Each field needs a `name` attribute so the browser can include it in the generated schema. Describe each field with `toolparamdescription`; without it, the browser falls back to the field's associated `