# What Is WebMCP? When to Expose Browser Tools to AI Agents

> Source: <https://dev.to/alisa_hester_1/what-is-webmcp-when-to-expose-browser-tools-to-ai-agents-1kd1>
> Published: 2026-10-02 14:58:01+00:00

WebMCP lets a web app declare structured tools that a browser agent can call. As the [WebMCP specification](https://github.com/webmachinelearning/webmcp) defines it, each tool runs inside the page with access to the user's authenticated session and current application state.

That context supports actions tied to what the user already has open, such as updating the current cart, saving a draft on the active support ticket, or creating an issue in the selected workspace.

On September 28, 2026, Shopify added checkout WebMCP tools that can read checkout state; update buyer details, fulfillment, discount codes, declared fields, and payment; and place an order after buyer confirmation. Shopify's [checkout WebMCP changelog](https://shopify.dev/changelog/posts/webmcp-support-for-checkout) notes that its storefront and cart tools were already available.

Cloudflare's [WebMCP beta changelog](https://developers.cloudflare.com/changelog/post/2026-09-28-webmcp-api) says Browser Run extended support to Kitesurf that day and migrated Chrome Lab sessions from the earlier testing API to `document.modelContext`.

WebMCP is still experimental. Its specification is a Draft Community Group Report. The project's [implementation-status page](https://github.com/webmachinelearning/webmcp/blob/main/implementation-status.md) lists origin trials in Chrome 149 and Edge 150, experimental Leo support in Brave, and ChatGPT Desktop support. It does not list Firefox or Safari implementations, so broad browser interoperability is not available.

Use WebMCP for actions tied to the current browser session, an MCP server for capabilities that must run without the page, and browser automation when a site exposes no adequate structured agent interface.

`document.modelContext`.
WebMCP is a browser API for exposing web application actions as structured tools. Each tool defines an action, its accepted inputs, its execution path, and what value, if any, execution returns. Imperative tools can also supply optional risk or debugging hints.

The proposal has two authoring models: [declarative metadata](https://developer.chrome.com/docs/ai/webmcp/declarative-api) on HTML forms and [imperative registration](https://developer.chrome.com/docs/ai/webmcp/imperative-api) through `document.modelContext`.

This contract lets an agent call an action directly rather than infer it from the DOM, accessibility tree, screenshots, labels, or layout. [Chrome's WebMCP guide](https://developer.chrome.com/docs/ai/webmcp) describes the structured path as more reliable and token-efficient than element-by-element navigation.

The website remains the application surface. It keeps the state and business logic, while the browser exposes only the tools the page registers.

A typical flow has five steps:

`null`.
[WebMCP tools run in the page context](https://developer.chrome.com/docs/ai/webmcp), so they can use the session, account, cart, draft, route, or other frontend state already open.

Use the [declarative API](https://developer.chrome.com/docs/ai/webmcp/declarative-api) when the action is already represented by an HTML form. Add a tool name and description to the form, then describe the parameters on the relevant controls.

```
form action: /catalog/search
method: GET
tool name: search_catalog
tool description: Search products by query and maximum price.
auto-submit: enabled

query input
 type: search
 required: yes
 parameter description: Product name or feature to search for.

maximum price input
 type: number
 minimum: 0
 parameter description: Highest acceptable price in US dollars.
```

The declarative API's [`toolautosubmit` attribute](https://developer.chrome.com/docs/ai/webmcp/declarative-api) lets the agent submit the form directly, which suits read-only searches. For payments, deletions, publishing, or permission changes, follow [Chrome's security guidance](https://developer.chrome.com/docs/ai/webmcp/secure-tools) and leave it off so users keep the existing review step.

Declarative tools let people and agents use the same form, validation, and submission path. The team maintains one workflow for both.

Use the [imperative API](https://developer.chrome.com/docs/ai/webmcp/imperative-api) when the action depends on dynamic application logic or cannot be represented cleanly as a form.

```
async function registerSupportDraftTool() {
 if (!("modelContext" in document)) return null;

 const controller = new AbortController();

 await document.modelContext.registerTool({
 name: "save_support_draft",
 description: "Save a draft reply for the support ticket open in the app.",
 inputSchema: {
 type: "object",
 properties: {
 ticketId: {
 type: "string",
 description: "The ID of the open support ticket."
 },
 body: {
 type: "string",
 description: "The reply text to save as a draft."
 }
 },
 required: ["ticketId", "body"]
 },
 annotations: {
 readOnlyHint: false
 },
 execute: async function ({ ticketId, body }) {
 const draft = await saveDraft({ ticketId, body });

 return {
 draftId: draft.id,
 status: "saved",
 reviewRequired: true
 };
 }
 }, {
 signal: controller.signal
 });

 return controller;
}
```

The [imperative API supports unregistration](https://developer.chrome.com/docs/ai/webmcp/imperative-api) through an `AbortSignal`. In a single-page application, abort the existing registration and register a replacement when the route, selected object, or available action changes.

``` js
const supportDraftRegistration = await registerSupportDraftTool();

// When the route, permissions, or state changes:
supportDraftRegistration?.abort();
```

Choose the interface based on where the required state lives and how long the task must run. These layers can also be combined. [Cloudflare's WebMCP beta](https://developers.cloudflare.com/changelog/post/2026-09-28-webmcp-api) shows how a browser-automation client can invoke WebMCP tools when a site exposes them and fall back to DOM, accessibility-tree, or visual interaction when it does not.

| Approach | Best fit | Main advantage | Main tradeoff | 
|---|---|---|---|
| WebMCP | Actions inside the current authenticated page | Reuses live browser state and lets the site define a stable tool contract | Experimental browser support and page-bound availability | 
| DOM or visual browser automation | Sites or workflows without an adequate structured tool interface | Works without cooperation from the product team | Depends on selectors, layout, visual interpretation, or other interface details that can change | 
| MCP server, usually remote for service-level integrations | Remote tools, background work, cross-client access, and service-level integrations | Runs independently of the page and fits MCP's client-server model | Requires a separate integration and may need explicit session or object context | 

[MCP uses a host-client-server architecture](https://modelcontextprotocol.io/docs/learn/architecture). An MCP server can run locally or remotely and expose tools and other capabilities to a host through an MCP client. By contrast, [WebMCP's page-level path](https://developer.chrome.com/docs/ai/webmcp/compare-mcp) does not require an MCP server, although a page tool may still call backend services.

Browser automation covers sites with no WebMCP or API integration, including exploratory work and compatibility testing. Selectors, layouts, and visual cues can change, which makes the automation fragile. [Chrome's comparison](https://developer.chrome.com/docs/ai/webmcp/compare-mcp) explains how WebMCP replaces that inference step with a contract defined by the product team.

Apply the same rule to implementation:

WebMCP is useful when the user has already selected the relevant account, workspace, cart, ticket, document, or draft. The agent can act inside that context instead of reconstructing it through a second authentication and selection flow.

Shopify's [checkout WebMCP implementation](https://shopify.dev/docs/agents/carts-and-checkout/checkout-webmcp) shows the pattern. Its tools operate on the active checkout and cover reading state, updating checkout fields such as contact details, fulfillment, discounts, and payment, and placing the order after buyer confirmation. Cart-item changes remain the job of storefront or cart tools, or the checkout interface.

A WebMCP tool should map to an existing interface action, such as searching the catalog, adding an item, saving a draft, creating an issue, or applying a filter. That shared path preserves a visible fallback and reuses the product's validation and business rules. Actions with no clear interface meaning usually need a narrower contract before agent use.

WebMCP suits workflows where users need to inspect state before or after execution, especially payments, publishing, privacy, and access changes.

Shopify's [checkout tools require confirmation](https://shopify.dev/changelog/posts/webmcp-support-for-checkout) before completion. Apply the same boundary to consequential actions: let the agent prepare the change, while application policy and user approval govern execution.

Tools work best when their names, descriptions, schemas, and return values remove ambiguity. `search_catalog` is better than `interact_with_store`. `save_support_draft` is better than `handle_ticket`.

[Chrome's WebMCP best practices](https://developer.chrome.com/docs/ai/webmcp/best-practices) recommend concise descriptions, focused tools, and dynamic registration based on the current application state. If you need a long prompt to explain what a tool might do, the action is probably too broad.

A WebMCP tool can call the same application function as a button or form. The contract can stay stable as the control's placement or label changes. Keep interface tests for the human path.

Scheduled jobs, long-running processing, webhooks, background orchestration, and tools used from multiple clients belong at the service layer. Use an API or MCP server when the task must run after the page closes or from an IDE, desktop assistant, command line, support platform, or automated workflow.

Keep cross-service orchestration outside the page. It needs explicit authentication, retries, observability, and ownership at the service layer.

Do not expose a destructive or irreversible operation because it is technically possible. Some actions need a review screen, a confirmation token, a second factor, a transaction limit, or no agent path at all.

The [WebMCP implementation-status page](https://github.com/webmachinelearning/webmcp/blob/main/implementation-status.md) still shows limited browser interoperability. Keep the existing interface and API path available so the workflow works outside supported browsers.

*WebMCP makes invocation explicit. The application still owns policy, permissions, and confirmation.*

WebMCP makes tool invocation explicit. Product controls still determine whether an action is authorized and safe.

For imperative tools, [Chrome's security guidance](https://developer.chrome.com/docs/ai/webmcp/secure-tools) covers prompt injection, untrusted tool output, origin boundaries, and confirmation for consequential actions. Optional annotations such as `readOnlyHint`, `untrustedContentHint`, and `consequentialHint` give the agent risk signals; application code enforces the policy.

A practical security baseline includes:

The `tools` Permissions Policy defaults to `self`. An embedding page can delegate it to a cross-origin iframe through the iframe's `allow="tools"` attribute. For cross-origin in-page agents, the registering document must also include the caller's secure origin in `registerTool(..., { exposedTo: [...] })`, and the caller must request the tool owner's origin through `getTools({ fromOrigins: [...] })`. [Chrome's security guidance](https://developer.chrome.com/docs/ai/webmcp/secure-tools) makes clear that these browser boundaries do not replace application authorization.

[Cloudflare's Browser Run documentation](https://developers.cloudflare.com/browser-run/features/webmcp) notes an important beta limitation: Kitesurf does not yet implement the `tools` Permissions Policy or origin-based tool filtering, and tools registered in iframes or popup windows are not exposed through its CDP integration.

Large web applications may have hundreds of actions. Exposing them all can make selection harder and consume more agent context.

[Chrome's Lighthouse audit](https://developer.chrome.com/docs/lighthouse/agentic-browsing/registered-webmcp-tools) flags pages with more than 40 declared tools. Treat 40 as an audit trigger. Most routes should expose far fewer.

Register tools dynamically:

`search_projects` and `create_project`.` rename_project`, `add_member`, and `archive_project`.` summarize_ticket`, `save_reply_draft`, and `change_status`.
[Chrome's best practices](https://developer.chrome.com/docs/ai/webmcp/best-practices) recommend unregistering tools when the user leaves the route or loses access so the agent sees only actions relevant to the current route and permissions.

Start with search, filtering, drafting, or saving a non-public change. Avoid purchases, deletion, publication, and permission changes in the first pilot.

Define the tool name, one-sentence description, input schema, success result, error cases, permission checks, and confirmation rule.

Call the same domain function used by the form or button, keeping one implementation for human and agent paths.

WebMCP requires a secure, origin-isolated document. [Chrome documents](https://developer.chrome.com/docs/ai/webmcp) that pages using `document.domain`, including pages configured with `Origin-Agent-Cluster: ?0`, cannot use the API.

Keep the form or controls functional when `document.modelContext` is unavailable. The [current implementation status](https://github.com/webmachinelearning/webmcp/blob/main/implementation-status.md) is a strong reason to detect support at runtime and add WebMCP as progressive enhancement.

Set the relevant annotations, then follow [Chrome's security guidance](https://developer.chrome.com/docs/ai/webmcp/secure-tools) by enforcing authorization, validation, confirmation, and rate limits in application code.

Run direct tool calls with valid, invalid, stale, unauthorized, and adversarial inputs. Test the normal interface without WebMCP. Chrome also provides [Lighthouse checks](https://developer.chrome.com/docs/lighthouse/agentic-browsing/registered-webmcp-tools) for common tool-definition problems.

Track tool choice, argument validity, task completion, human correction, and fallback to browser navigation. Use completion and correction rates as the decision metrics; tool-call volume measures activity rather than success.

For a fuller measurement model, see [How to Measure Whether AI Coding Agents Use Your Developer Documentation](https://ekline.io/blog/measure-ai-agent-documentation-usage).

Start by identifying the product action, the state it needs, and how long it must remain available. Use WebMCP when the action depends on the current tab. Use an API or MCP server when it must outlive the tab, run in the background, or serve many clients.

Pilot one reversible action on one route, define its success condition, and verify that the existing interface still works when WebMCP is unavailable.