WebMCP: what it is and how to use it

WebMCP is a client side API. A web page uses JavaScript to describe actions it can perform. Each action is a tool with a name, a plain language description, an input schema and an execute function. An AI agent in the browser reads the list of tools and calls them. The agent no longer has to guess which button to click.

The draft describes a page that uses WebMCP as an in-page Model Context Protocol server. The tool runs the same JavaScript your interface already runs. The user sees the page update while the agent works.

WebMCP targets agents that act on a page: filling a form, filtering a list, adding an item to a cart. It does not change how search engines crawl or cite your content. We found no study that links WebMCP to AI search citations.

The Web Machine Learning Community Group publishes the draft on GitHub. The specification page calls it a Draft Community Group Report dated 2 November 2026. It is not a W3C Standard and it is not on the W3C Standards Track. The Chrome team documents the API and runs the origin trial. The API can still change.

Chrome published its WebMCP documentation on 18 May 2026. Its overview page was last updated on 7 October 2026. Both APIs sit behind the tools Permissions Policy. The policy defaults to self, so a cross-origin iframe needs allow="tools".

Use document.modelContext. Early WebMCP articles show navigator.modelContext. The draft moved the modelContext getter from Navigator to Document in a pull request merged on 27 May 2026 (webmcp pull request 184). Discussion on that pull request says Chrome 150 shipped the change and deprecates navigator.modelContext. Chrome's imperative API page, updated on 16 October 2026, uses document.modelContext in its examples.

Old code keeps working in some builds. To support both, detect the new entry point first and fall back to the old one:

const mc = document.modelContext ?? navigator.modelContext;

This is the pattern that the SeenLens check webmcp-entry-point recommends. The check reports a page that registers tools on navigator.modelContext only.

The draft defines registerTool(tool, options). It returns a promise. The promise rejects if a tool with the same name exists, if the name or description is empty, or if a schema is invalid. This example registers a site search tool and removes it when the page no longer needs it:

const mc = document.modelContext ?? navigator.modelContext;
if (mc) {
  const controller = new AbortController();

  await mc.registerTool(
    {
      name: "search-articles",
      description: "Search the articles on this site and return the top matches.",
      inputSchema: {
        type: "object",
        properties: {
          query: { type: "string", description: "Words to search for." },
        },
        required: ["query"],
      },
      annotations: { readOnlyHint: true },
      async execute({ query }) {
        const res = await fetch("/api/search?q=" + encodeURIComponent(query));
        const hits = await res.json();
        return {
          content: [{ type: "text", text: JSON.stringify(hits) }],
        };
      },
    },
    { signal: controller.signal },
  );

  // Later, to remove the tool: controller.abort();
}

• name, description and execute are required. title, inputSchema, outputSchema and annotations are optional.
• inputSchema is a JSON Schema object. The agent uses it to build the arguments.
• annotations carries hints: readOnlyHint, untrustedContentHint, consequentialHint and debugging.
• execute receives the arguments and an options object with an AbortSignal. The draft types its return value as Promise<any>. The draft README returns a content array. Chrome's examples return a plain string.
• Aborting the signal passed in the options removes the tool. Register tools for the current screen only, because a long tool list uses up the agent's context.
• The exposedTo option lists origins that may see a tool. The draft also defines getTools() and executeTool() for agents that run inside the page.

Keep tools small. Name each one after the user's goal. Do not register a tool that spends money or deletes data unless a person confirms the step in the interface.

Yes. Chrome documents attributes that turn an HTML form into a tool without JavaScript. Chrome's declarative API page was last updated on 25 September 2026. The GitHub README says this API is still an exploration and not part of the specification.

<form toolname="search-cars"
      tooldescription="Search cars by make and model"
      action="/search">
  <input type="text" name="make" required
         toolparamdescription="Vehicle make, for example BMW">
  <input type="text" name="model" required
         toolparamdescription="Vehicle model, for example 330i">
  <button type="submit">Search</button>
</form>

When an agent submits the form, SubmitEvent.agentInvoked is true. Call preventDefault() and then event.respondWith(promise) to return a result to the agent without navigating. Annotate only forms that are safe for an agent to submit, such as search or contact forms.

MCP is the Model Context Protocol. An MCP server runs on a backend and serves tools to AI applications. WebMCP puts tools in the page itself. The WebMCP draft says it complements backend protocols such as MCP and does not replace them.

Choose WebMCP when the action depends on what the user sees in the browser. Choose MCP when an agent must work without a browser, such as a nightly job. A site can offer both.

Only Chromium browsers run it, and only as a trial. Chrome 149 and later accept an origin trial token, or you can turn on the testing flag on your own machine. Edge 150 starts an origin trial. The implementation status page lists no Firefox or Safari implementation on 2026-11-06.

Visitors without the API see no change, because the code above checks that modelContext exists first. Use that feature check on every page that registers tools.

The SeenLens scan has three WebMCP checks in its agent readiness dimension. All three are optional improvements. A site with no search or booking function has nothing to expose. Read how the scan works for the scoring.

The fix page Add WebMCP tools lists the steps for each check. For the wider set of agent checks, see the Lighthouse agentic audit fixes.

Scan your page for WebMCP and 35 other checks

• WebMCP draft specification (status, date, ModelContext interface, registerTool, tool fields, exposedTo, Document attribute, checked 2026-11-06).
• WebMCP repository and README (purpose, document.modelContext example, declarative API status, checked 2026-11-06).
• WebMCP implementation status (Chrome 149, Edge 150, agents, Firefox and Safari, checked 2026-11-06).
• WebMCP declarative API explainer (form attributes, agentInvoked, respondWith, checked 2026-11-06).
• Pull request 184: move the modelContext getter to Document (merged 2026-05-27, checked 2026-11-06).
• Chrome: WebMCP overview (origin trial, flag, Permissions Policy, updated 2026-10-07).
• Chrome: WebMCP imperative API (examples, signal, exposedTo, updated 2026-10-16).
• Chrome: WebMCP declarative API (attributes and form example, updated 2026-09-25).
• MCP specification: transports (stdio and Streamable HTTP, revision 2026-07-28).
• MCP specification: authorization (optional, OAuth 2.1 based for HTTP, checked 2026-11-06).