WebMCP Cheat Sheet: Complete Guide to the W3C Browser AI Tool API

UI Actuation (Screenshots)

• Screenshots cost ~2,000 tokens each
• Fragile to layout changes
• Slow multi-step interactions
• Agents guess what to do

Backend-only MCP

• No shared UI context with user
• Auth/session must be managed separately
• Can't reuse frontend logic

Agent

An autonomous LLM-based assistant that understands user goals and takes actions on their behalf via chat interfaces.

Model Context Provider

A browser tab navigated to a page that uses the WebMCP API to provide tools to agents.

Tool Definition

A struct with: name, description, inputSchema, execute steps, and a readOnlyHint annotation.

Actuation

An agent interacting with a webpage by simulating user input: clicking, scrolling, typing. WebMCP replaces this.

Browser's Agent

An agent provided by or through the browser itself - built-in, or via a browser extension/plug-in.

Backend Integration

An API integration where an AI platform talks directly to a service's backend without a live UI. WebMCP complements, not replaces, these.

SecureContext

Only available on HTTPS pages. Will not work on HTTP.

SameObject

The same ModelContext instance is always returned per Navigator - it's a singleton.

registerTool(tool)

Registers a single tool with the browser. Throws InvalidStateError if:

• A tool with the same name already exists
• The inputSchema is invalid
• The name or description is an empty string

unregisterTool(name)

Removes the named tool. Throws InvalidStateError if the tool does not exist.

Simple string param

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search term"
    }
  },
  "required": ["query"]
}

Multiple typed params

{
  "type": "object",
  "properties": {
    "productId": { "type": "string" },
    "quantity": { "type": "integer", "minimum": 1 },
    "size": {
      "type": "string",
      "enum": ["S", "M", "L", "XL"]
    }
  }
}

execute callback signature

// input = agent-supplied params (matches inputSchema)
// client = ModelContextClient for user interaction
async (input, client) => {
  // Do work...
  return { result: "data" }; // must return object
}

ToolAnnotations - readOnlyHint

annotations: { readOnlyHint: true }

Model Context (struct)

Tool Definition (struct)

// Requires HTTPS (SecureContext)
navigator.modelContext.registerTool({
  name: "searchProducts",
  description: "Search the product catalog by keyword. Returns a list of matching products with name, price, and availability.",
  inputSchema: {
    type: "object",
    properties: {
      query: {
        type: "string",
        description: "The search keyword or phrase"
      },
      category: {
        type: "string",
        enum: ["all", "clothing", "electronics", "books"],
        description: "Product category to filter by"
      }
    },
    required: ["query"]
  },
  execute: async (input) => {
    // Reuses your existing frontend search logic!
    const results = await productStore.search(input.query, input.category);
    return { products: results, total: results.length };
  },
  annotations: { readOnlyHint: true } // Does not modify state
});

navigator.modelContext.registerTool({
  name: "addToCart",
  description: "Add a product to the user's shopping cart",
  inputSchema: {
    type: "object",
    properties: {
      productId: { type: "string" },
      quantity: { type: "integer", minimum: 1 }
    },
    required: ["productId", "quantity"]
  },
  execute: async (input) => {
    await cart.add(input.productId, input.quantity);
    return { success: true, cartTotal: cart.total };
  }
  // readOnlyHint omitted → defaults to false
});

execute: async (input, client) => {
  // Pause and ask user to confirm
  const confirmed = await client.requestUserInteraction(
    async () => {
      // Show your UI confirmation dialog
      return await showConfirmDialog(
        `Delete ${input.filename}?`
      );
    }
  );

  if (!confirmed) {
    return { cancelled: true };
  }

  await deleteFile(input.filename);
  return { deleted: true };
}

// Register when user logs in
function onUserLogin(user) {
  navigator.modelContext.registerTool({
    name: "getUserOrders",
    description: "Get the current user's order history",
    execute: async () => ({
      orders: await api.getOrders(user.id)
    }),
    annotations: { readOnlyHint: true }
  });
}

// Unregister when user logs out
function onUserLogout() {
  navigator.modelContext.unregisterTool("getUserOrders");
}

// ❌ Throws InvalidStateError - name already exists
navigator.modelContext.registerTool({ name: "myTool", ... });
navigator.modelContext.registerTool({ name: "myTool", ... });

// ✅ Correct - unregister first, then re-register
navigator.modelContext.unregisterTool("myTool");
navigator.modelContext.registerTool({ name: "myTool", ... });

const tools = [
  { name: "getProducts", description: "...", execute: getProducts, annotations: { readOnlyHint: true } },
  { name: "addToCart", description: "...", execute: addToCart },
  { name: "checkout", description: "...", execute: startCheckout },
];

tools.forEach(tool =>
  navigator.modelContext.registerTool(tool)
);

What it is

A testing-only companion to navigator.modelContext. It can read back and bulk-replace every tool registered on the current page.

Who uses it

Browser extensions, DevTools panels, and automated test scripts that need to inspect or stub tools without modifying page source.

Production availability

Not exposed in stable Chrome. Only active when the #enable-webmcp-for-testing flag is on in chrome://flags.

Scenario

A user collaborates with a browser agent on a graphic design platform. The agent helps find templates and make design changes while the user retains full review and control. The agent surfaces hidden features (like a print ordering service) the user might not have discovered.

Example Tools

Scenario

A user browses a clothing store. The agent calls getDresses(size) to receive a structured JSON list of products with descriptions and images, filters them by criteria, then calls showDresses(product_ids) to update the UI - far more reliable than screen-scraping.

Example Tools

Agent handles repetitive work; human reviews and approves

Example Tools

Traditional AT Problem

Traditional accessibility trees aren't widely implemented. Assistive technologies struggle to interact with complex web applications via DOM-level interactions.

What WebMCP Provides

Standardized higher-level application actions mapped to meaningful operations (e.g., "add todo item") rather than low-level DOM interactions.

Unified Surface

The same tools available to AI agents are available to accessibility tools - one implementation serves both audiences with no extra work.

vs. OpenAPI

OpenAPI describes HTTP-based APIs for function-calling (ChatGPT Actions, Gemini Function Calling).

WebMCP runs in the browser using JavaScript, not HTTP. Tools execute client-side and can interact with page state directly.

vs. Agent2Agent (A2A)

A2A connects AI agents to each other, providing capability advertisement, long-running interactions, and multimodal I/O.

WebMCP is for connecting AI agents to web applications with a human in the loop. A2A is for fully autonomous agent-to-agent workflows. Different problems, both needed.

Use WebMCP when...

• • User is actively present in tab
• • You want to reuse frontend code
• • Human oversight is required
• • Shared UI context matters

Use Backend MCP when...

• • No browser tab needed
• • Server-to-server workflows
• • Fully autonomous pipelines
• • Always-available tools

Use OpenAPI when...

• • Exposing HTTP REST APIs
• • ChatGPT/Gemini integration
• • Standard web API consumers
• • No frontend code access

Use A2A when...

• • Agent-to-agent communication
• • Long-running agent tasks
• • Multimodal agent I/O
• • No human in the loop

When a website registers tools via WebMCP, it exposes information about its capabilities to the browser.

Browser should prompt users to grant permission and provide visibility into what tools are being exposed.

When an agent wants to use those tools, the site receives untrusted input in parameters and outputs may contain sensitive user data.

Browser mediates this boundary. Users can "always allow" tool calls for trusted site+agent pairs.

navigator.modelContext is decorated with [SecureContext] - it only exists on HTTPS pages.

// On HTTP - undefined
console.log(navigator.modelContext); // undefined

// On HTTPS - works
navigator.modelContext.registerTool(...);

Check window.isSecureContext before calling any WebMCP API to gracefully handle HTTP environments during development.

Only a top-level browsing context (a browser tab) can be a Model Context Provider. iframes are excluded.

Why iframes are excluded

• Maintains a clear security boundary
• Prevents embedded content from exposing tools without the parent page's knowledge
• Embedders manage capabilities of embedded contexts

The Risk

Malicious web developers could craft tools to expose content the user would not normally see, or manipulate agent behavior through carefully crafted tool descriptions and responses.

This is an open question in the spec - actively under investigation by the W3C community group.

The Concern

Data output from one app's tools could be passed as input to another app's tools. While legitimate cross-origin workflows exist, this requires careful browser mediation.

Browser Responsibility

The browser must clearly indicate which web applications are being invoked and with what data, so users can intervene in cross-origin tool chains.

Input Validation

• Always validate agent-supplied inputs against your inputSchema
• Treat input as untrusted (like user input from a form)
• Sanitize strings before using in queries or HTML

Sensitive Data

• Only return data the user has permission to see
• Don't expose PII in tool responses unnecessarily
• Use requestUserInteraction for destructive operations

Auth & State

• Verify user is authenticated before registering sensitive tools
• Unregister tools when user logs out
• Mark read-only tools with readOnlyHint: true

The Concept

Register tools via HTML elements instead of JavaScript registerTool() calls. Tools would be derived from HTML forms and their associated elements.

<!-- Conceptual future syntax -->
<form webmcp-tool="searchProducts"
      webmcp-description="Search for products">
  <input name="query" type="text">
</form>

Always-Available PWA Tools

A PWA with an app manifest could declare tools available "offline" - before the PWA is launched. When an agent calls the tool, the host system auto-launches the PWA and navigates to the appropriate page.

No UI Required

Some tools may not require a browser UI at all. A to-do app could expose an "add item" tool that runs without showing a window - showing only a notification when triggered.

Integration Point

Could combine with the web app launch handler API for seamless background tool execution.

Current Limitation

Tools are only discoverable once a page is navigated to. An agent can't know what tools a site offers without loading it first.

Future: Manifest-Based Discovery

Declarative tool definitions in the app manifest would let agents discover a site's capabilities via a simple HTTP GET - without full page navigation. Agents would still navigate to use tools.

Main Thread Performance

Tool calls run on the main thread. When agents request many tool calls in sequence or tools are computationally expensive, this may cause performance issues. Under investigation.

Permission Model Details

The exact UX for browser permission prompts - when to ask, how to phrase it, what granularity of "always allow" - needs further community input and browser vendor coordination.

iframe Capabilities

How should embedders (parent pages) manage capabilities provided to embedded iframes? The current proposal limits this to top-level contexts but future work may define delegation models.

Current Status

Draft Community Group Report - 9 March 2026. NOT a W3C Standard, nor on the W3C Standards Track. Under incubation.

Editors

Governing Body

W3C Web Machine Learning Community Group. License: W3C Community Contributor License Agreement (CLA). First published: August 13, 2025.

MCP-B (WebMCP by MiguelsPizza)

Open-source project with similar motivation. Extends MCP with tab transports for in-page communication and extension transports for cross-extension communication. Enables tool caching and cross-site tool composition.

github.com/MiguelsPizza/WebMCP

Acknowledged as directly related prior art by the W3C spec.

OpenAPI

Standard for describing HTTP APIs. Used by ChatGPT Actions and Gemini Function Calling. Unlike WebMCP, OpenAPI tools are backend HTTP services - no browser required.

Relationship: complementary - OpenAPI for server-side, WebMCP for client-side

Agent2Agent (A2A)

Protocol for AI agent-to-agent communication. Provides capability advertisement, long-running interactions, and multimodal I/O. Addresses agent orchestration, not web app integration.

Relationship: different problem - A2A for agent mesh, WebMCP for human+agent web workflows

Why Align with MCP?

• Any MCP-compatible agent works with minimal translation
• Developers can reuse code between WebMCP and backend MCP
• Browser can evolve MCP compatibility independently
• Web-platform security policies can be applied

Why Not Static Manifests?

• Would limit WebMCP to installed PWAs only
• A new manifest format still needs implementation
• Cannot execute code or update tools dynamically
• Dynamic registration is a critical developer capability

Why Top-Level Only?

• Clear, understandable security boundary
• Prevents iframe-based capability leakage
• Embedders manage iframe capabilities
• Simpler mental model for users and developers