# WebMCP vs MCP: what WebMCP is, how to add it to a page and how to check a site for it

> WebMCP lets a page register tools for an agent in the browser; MCP runs on a server. What differs, how to add WebMCP to a page, and how to check a site for it.

- Source: /learn/webmcp-vs-mcp
- Updated: 2026-10-27
- Reading time: 8 minutes
- Tags: WebMCP, MCP, browser agents, Chrome

---
WebMCP and MCP both let an agent call tools, and they run in different places. MCP runs on a server: an agent connects to it and calls its tools, with no browser involved. WebMCP runs in the page: the page registers tools, and an agent in the user's browser calls them while the page is open. WebMCP is a draft, in a Chrome origin trial from Chrome 149.

## What is the difference between WebMCP and MCP?

MCP servers expose tools that a client lists with `tools/list` and calls with `tools/call`, according to the [MCP specification](https://modelcontextprotocol.io/specification/latest/server/tools). WebMCP moves the tool into the page. The [draft](https://webmachinelearning.github.io/webmcp/) says a page using it can be thought of as an MCP server whose tools run in client-side script.

[Chrome's comparison](https://developer.chrome.com/docs/ai/webmcp/compare-mcp) says WebMCP is neither an extension of MCP nor a replacement for it. The table follows that page and the draft.

| Question | MCP | WebMCP |
| --- | --- | --- |
| Where does it run? | On a server | In the page, in the user's browser tab |
| How long does it live? | As long as the server runs | As long as the tab is open |
| How does an agent find the tools? | It connects to a server it knows, or finds a server card | The page registers them during the visit |
| How is it written? | JSON-RPC, often through an SDK | JavaScript, or HTML attributes on a form |
| Who can call it? | Any client, with or without a browser | An agent built into or attached to the browser |
| What is its status? | An open specification, versioned | A draft report that is not on the W3C Standards Track |

Use MCP when the agent has no tab open: a background job, or a server-side agent. Use WebMCP when the user is on the page and the agent should act through it. Chrome suggests both: MCP for business logic and data, WebMCP for the live interface.

Shopify draws the same line. Its Checkout WebMCP docs target agents in the buyer's browser, and point server-side agents to Checkout MCP instead.

## Is WebMCP a standard yet?

No. The [draft of 20 October 2026](https://webmachinelearning.github.io/webmcp/) says it is not a W3C Standard and not on the Standards Track. [Chrome's docs](https://developer.chrome.com/docs/ai/webmcp) tell you to join the origin trial from Chrome 149, or to turn on `chrome://flags/#enable-webmcp-testing` for local work.

The [implementation status page](https://github.com/webmachinelearning/webmcp/blob/main/implementation-status.md) lists an Edge origin trial in Edge 150. For Firefox and Safari it links only standards-position entries.

Details still change between releases. Shopify's docs say Chrome 153 rejects an object as tool arguments and wants a JSON string, and that Chrome 155 is planned to accept objects. Chrome's declarative page says `window.ontoolactivated` and `window.ontoolcancel` are not supported from Chrome 156. Treat any code here as preview code.

## Is it document.modelContext or navigator.modelContext?

Use `document.modelContext`. The draft defines `modelContext` as an attribute on `Document` and does not mention `navigator`. [Chrome's imperative API page](https://developer.chrome.com/docs/ai/webmcp/imperative-api), Shopify's docs and Cloudflare's post all call `document.modelContext`.

So does Lighthouse. Its [v13.4.1 release notes](https://github.com/GoogleChrome/lighthouse/releases) say the WebMCP gatherers were refined to check `document.modelContext`. I found no primary source that uses `navigator.modelContext`. If a guide or snippet does, check it against the draft before you copy it.

## How to add WebMCP to a page

There are 2 APIs. The declarative one turns a form into a tool. The imperative one registers a tool in script.

For the declarative API, add `toolname` and `tooldescription` to the `<form>`. Chrome says removing either one unregisters the tool. `toolparamdescription` on a field describes a parameter, and `toolautosubmit` lets the agent submit the form. This example follows the shape of Chrome's.

```html
<form toolname="search_site" tooldescription="Search this site and list matching pages" action="/search">
  <input name="query" type="search" toolparamdescription="The words to search for">
  <button type="submit">Search</button>
</form>
```

A browser that does not know the attributes ignores them, and the form works as before.

For the imperative API, call `registerTool` with a name, a description, an input schema and an `execute` function. Run it in a module script, because Chrome's examples await the call. The feature test is my addition. Cloudflare's script exits when the browser lacks WebMCP, which is the same idea.

```js
if ('modelContext' in document) {
  await document.modelContext.registerTool({
    name: 'search_site',
    description: 'Search this site and return the titles of matching pages.',
    inputSchema: {
      type: 'object',
      properties: { query: { type: 'string', description: 'The words to search for' } },
      required: ['query'],
    },
    execute: async ({ query }) => {
      const titles = await searchTitles(query); // your own search function
      return titles.join('\n');
    },
  });
}
```

Chrome's [best practices](https://developer.chrome.com/docs/ai/webmcp/best-practices) ask for precise verb names, descriptions that say what a tool does and when to use it, and one function per tool. Pass an `AbortController` signal in the options to unregister a tool. Optional annotations include `readOnlyHint`, `untrustedContentHint` and `consequentialHint`.

Both APIs sit behind the `tools` Permissions Policy. It defaults to `self`, so a cross-origin iframe needs `allow="tools"`. A site can send `Permissions-Policy: tools=()` to turn WebMCP off for a document and its frames.

The draft's security section names the risks: prompt injection, a tool that misstates what it does, and private data leaking through over-wide parameters. It also describes annotations that mark untrusted content and consequential actions. A tool runs with the user's session on your origin, so give it no more reach than the page already has.

## Shopify Checkout and Commerce.com: WebMCP on real stores

On 28 September 2026 Shopify added WebMCP tools to checkout: `get_checkout`, `update_checkout`, `complete_checkout` and `navigate_to_storefront`. The [changelog](https://shopify.dev/changelog/webmcp-support-for-checkout) says they need no new API and no merchant configuration. The [docs](https://shopify.dev/docs/agents/carts-and-checkout/checkout-webmcp) add a condition for agents: sign browser requests with Web Bot Auth, and register the key, because Shopify verifies only registered keys. [Web Bot Auth](/learn/web-bot-auth-explained) explains the signature.

On 21 October 2026 [Cloudflare reported](https://blog.cloudflare.com/webmcp-commerce/) that Commerce.com turned WebMCP on for almost 100,000 storefront domains. Cloudflare injects a script at the edge, merchants can opt out, and the tools run in the shopper's browser session. Commerce.com's own MCP server holds the commerce logic. That is the split the table describes: WebMCP on the page, MCP behind it.

## How to check a site for WebMCP tools

The [WebMCP checker](/tools/webmcp-checker) reads your homepage the way this section describes.

There are 3 ways, and each sees something different.

- **In Chrome.** Turn on the flag and use DevTools. Chrome says DevTools can debug WebMCP tools and validate the JSON Schema. Chrome also lists a Model Context Tool Inspector extension.
- **With Lighthouse.** The agentic browsing category has 3 WebMCP audits. It needs Chrome 150 or later, and the WebMCP audits need the origin trial. The [Lighthouse comparison](/learn/lighthouse-agentic-browsing-vs-agent-readiness) maps them one by one.
- **Over HTTP.** This is what [the webmcp check](/checks/webmcp) does, and it can be repeated with curl.

```sh
URL=https://example.com/
curl -sSL "$URL" | grep -oE 'registerTool\(|<form[^>]*toolname[^>]*>' | sort | uniq -c
```

The scan reads the homepage HTML and no more. It counts `registerTool(` calls and forms with a `toolname`. A call is complete when the 900 characters after it hold a `name`, a `description` and an `inputSchema`, and a form is complete with a `toolname` and a `tooldescription`. The draft defines no manifest file, so there is nothing else to fetch.

A homepage with no form and no `registerTool(` call is out of scope. A homepage with forms and no declared tool is Not used. An incomplete tool earns half the points. The check is an agent convention in the recommended tier.

It cannot see a tool that a script file registers, because it does not fetch scripts. It cannot see a tool registered on another page or after a click. It cannot tell whether a browser exposes the tool or whether `execute` works.

The stored records show both outcomes. On 20 October 2026 the scan found 1 `registerTool(` call on cloudflare.com and no `name`, `description` or `inputSchema` in the 900 characters after it, so it scored half points. That does not show that the tool is incomplete. This site's own record of 25 October 2026 reads Not used: 2 forms, no tool.

To see what your homepage declares, [scan your site](/scan). [Agent tools, not pages](/learn/agent-tools-not-pages) compares WebMCP with server cards and agent skills.