WebMCP - Complete Reference

WebMCP (Web Model Context Protocol) - Complete Reference

Date: 2026-07-31 | Source: Chrome Developers, W3C Web ML Community Group | Status: Experimental (Origin Trial)

---

What is WebMCP?

WebMCP is a proposed browser standard that lets webpages declare structured tools for AI agents to discover and invoke directly - instead of forcing agents to scrape DOM elements or simulate clicks.

Core idea: Your site tells the agent “here are my capabilities, here’s how to use them” via typed JavaScript APIs or HTML annotations. The browser mediates between agent and site.

Key term - Actuation: An agent simulating human mouse clicks and text input to interact with your page. WebMCP replaces actuation with direct tool calls.

---

Status and Availability (July 2026)

Channel	Status
Chrome	Origin trial active (Chrome 149-156)
Chrome local dev	Flag: chrome://flags/#enable-webmcp-testing
Edge	Flag-gated
Firefox/Safari	Watching, no implementation
Spec status	W3C Web ML Community Group draft (not Recommendation)

GitHub: https://github.com/webmachinelearning/webmcp (explainer + spec)
Demos repo: https://github.com/GoogleChromeLabs/webmcp-tools (446 stars)

---

Why WebMCP?

Without WebMCP:

• Agent must inspect DOM, guess element purposes, simulate clicks
• UI changes break agent flows
• No guarantee of correct parameter mapping

With WebMCP:

• Site declares tools with JSON Schema inputs
• Agent calls functions directly
• UI can change without breaking agent interactions
• Developer controls exactly how agents use the site

---

WebMCP vs Standard MCP

Aspect	Standard MCP	WebMCP
Scope	Backend protocol, universal	Browser-native, page-local
Lifecycle	Persistent (server/daemon)	Ephemeral (exists while tab is open)
Transport	JSON-RPC over network	Browser-native, no network round-trip
UI	Headless, external to browser	Live DOM, cookies, session data
Agent view	Agent renders MCP app’s output	Agent operates on your existing UI
Discovery	Agent-specific registration	Tools registered on page during visit

Analogy: MCP = call center (available anywhere, anytime). WebMCP = in-store expert (available only when customer is in the store, but knows all current inventory).

They are partners, not competitors. A typical agentic flow:

1. MCP server handles core business logic and data retrieval
2. WebMCP exposes in-browser actions when user visits your site

---

API Surface

Entry Point

// Current standard (Chrome 150+)
document.modelContext

// Deprecated in Chrome 150
navigator.modelContext // DO NOT USE

Imperative API Methods

Method	Purpose
registerTool(tool, options?)	Register a single tool
getTools(options?)	Discover available tools
executeTool(tool, argsJson, options?)	Execute a tool by input args

Events

Event	Fires when
toolchange	Tool list changes (on document.modelContext)

Tool Descriptor Shape

{
  name: "string",                  // Tool identifier
  description: "string",           // Human+agent-readable purpose
  inputSchema: {                   // JSON Schema object
    type: "object",
    properties: { ... },
    required: [...]
  },
  execute: async (params) => { ... },  // Page-JS callback
  annotations?: {
    readOnlyHint?: boolean,           // Does NOT change state
    untrustedContentHint?: boolean    // Returns UGC/external data
  }
}

---

Imperative API Examples

Registering a Tool

await document.modelContext.registerTool({
  name: "get_order_status",
  description: "Search orders in a given timeframe. Returns order number, shipping status and location.",
  inputSchema: {
    type: "object",
    properties: {
      timeframe: {
        type: "string",
        enum: ["today", "yesterday", "last_7_days", "last_30_days"],
        description: "Timeframe for the order lookup."
      }
    },
    required: ["timeframe"]
  },
  execute: async ({ timeframe }) => {
    // Your API/database logic here
    return "Order #12345 - shipped, arriving tomorrow";
  },
  annotations: {
    readOnlyHint: true,
    untrustedContentHint: false
  }
});

Unregistering (via AbortController)

const controller = new AbortController();
await document.modelContext.registerTool(tool, { signal: controller.signal });

// Later...
controller.abort(); // Tool removed from agent's view

Discovering Tools

// Same-origin only
const tools = await document.modelContext.getTools();

// Including cross-origin (must be explicitly exposed)
const allTools = await document.modelContext.getTools({
  fromOrigins: ["https://partner.org"]
});

Executing Tools

const result = await document.modelContext.executeTool(
  tool,
  JSON.stringify({ timeframe: "last_7_days" })
);
console.log(result);

---

Declarative API

Transform HTML forms into tools with annotations:

Basic Form

<form
  toolname="submitSupportRequest"
  tooldescription="Submit a customer support request."
  action="/support/submit">

  <label for="email">Email</label>
  <input type="email" name="email" id="email">

  <select name="category"
    toolparamdescription="Which team should handle this request?">
    <option value="billing">Billing</option>
    <option value="technical">Technical Support</option>
  </select>

  <button type="submit">Submit</button>
</form>

Auto-submit

Add toolautosubmit to trigger submission immediately when agent invokes the tool:

<form toolautosubmit toolname="quick_search" tooldescription="Search products" action="/search">
  <input type="text" name="query">
</form>

Handling Agent-Invoked Submissions

document.querySelector("form").addEventListener("submit", (e) => {
  e.preventDefault();

  // Detect if triggered by agent
  if (e.agentInvoked) {
    if (!myFormIsValid()) {
      e.respondWith(Promise.reject("Invalid input"));
      return;
    }
    e.respondWith(Promise.resolve("Search completed!"));
  }
});

Events

// Tool activated, form pre-filled
window.addEventListener("toolactivated", ({ toolName }) => {
  console.log(`Tool "${toolName}" executed`);
});

// User or agent cancelled
window.addEventListener("toolcancel", ({ toolName }) => {
  console.log(`Tool "${toolName}" cancelled`);
});

CSS Focus Indicators

form:tool-form-active {
  outline: light-dark(blue, cyan) dashed 2px;
}

input:tool-submit-active {
  outline: light-dark(red, pink) dashed 2px;
}

---

Cross-Origin Iframe Model

Permissions Policy

Tools are gated by the tools permission policy:

<!-- Allow this iframe to register/discover tools -->
<iframe src="https://partner.org/widget" allow="tools"></iframe>

Exposing Tools to Specific Origins

// Only tools from these origins can call this tool
await document.modelContext.registerTool(tool, {
  exposedTo: ["https://trusted.com", "https://example.com"]
});

Discovery Across Origins

// From https://example.com, get tools from embedded iframe
const tools = await document.modelContext.getTools({
  fromOrigins: ["https://partner.org"]
});

Key: Cross-origin tools require BOTH:

1. The hosting page allows tools via allow= attribute
2. The tool is explicitly exposedTo the requesting origin

---

Security Model

Browser-Level Protections

Mechanism	Effect
Origin isolation	WebMCP only available in origin-isolated documents
Permissions Policy	tools defaults to self, blocks cross-origin by default
Secure context	HTTPS required
No headless	Requires visible browser tab; no hidden execution

Annotation Hints

Hint	Purpose
readOnlyHint: true	Tool does NOT modify state; agent can skip user confirmation
untrustedContentHint: true	Tool returns user-generated or external content; agent should treat output with suspicion

Prompt Injection Defense

WebMCP mitigates but does not eliminate prompt injection risk:

1. Use untrustedContentHint on tools returning UGC
2. Keep tool descriptions concise (recommended: 500 chars max)
3. Keep tool outputs concise (recommended: 1500 chars max)
4. Require user confirmation for destructive actions via requestUserInteraction()
5. Expose tools only to trusted origins

Character Budgets (Recommended)

Field	Limit
Tool name	30 chars
Tool description	500 chars
Parameter description	150 chars
Tool output	1500 chars

---

Framework Integrations

Framework	Status	Package
React	Experimental	usewebmcp (npm)
Angular	Experimental	Built into Angular AI

React example via hook:

import { useWebMCP } from "usewebmcp";

function OrderStatus() {
  useWebMCP({
    name: "get_order_status",
    description: "Get shipping status for an order.",
    inputSchema: { type: "object", properties: { orderId: { type: "string" } } },
    execute: async ({ orderId }) => {
      const res = await fetch(`/api/orders/${orderId}`);
      return await res.text();
    }
  });

  return <div>...</div>;
}

---

Debugging and Testing

Extension

Install Model Context Tool Inspector (Chrome Web Store):

• Lists all registered tools on a page
• Call tools manually from the UI
• View JSON Schema and parsed inputs
• See structured output/errors

Chrome DevTools

1. Flag: chrome://flags/#enable-webmcp-testing
2. Open console, call document.modelContext.getTools()
3. Monitor toolchange events

Demos to Study

Demo	Purpose
pizza-maker	Imperative API, layer toggling
react-flightsearch	Imperative + React hooks
french-bistro	Declarative API, HTML forms
page-agent	Cross-origin tool discovery
coffee-shop, hotel-chain, smart-home	Various use cases

Repo: https://github.com/GoogleChromeLabs/webmcp-tools/tree/main/demos

---

Use Cases

Strong Candidates

Scenario	Example Tools
Shopping/cart	search_products(), add_to_wishlist(), get_order_history()
Booking/travel	search_hotels(), filter_results(), book_room()
Forms/wizards	submit_claim(), add_timesheet_entry()
Filtering	filter_listings(), apply_search_criteria()
Support flows	start_warranty_claim(), populate_product_details()

Patterns to Follow

• Each tool = single function (no overlapping purposes)
• Register tools when available, unregister when stale
• Start with read-only tools; add writes gradually
• Require confirmation for irreversible actions
• Validate strictly in code, loosely in schema

---

Best Practices

1. Plan before coding: Map critical user journeys, define tools per journey
2. Clear naming: Verbs that describe exact behavior (create_event vs start_event_creation)
3. Positive descriptions: Describe what the tool DOES, not what it doesn’t
4. Minimize agent computation: Accept raw input; don’t ask agent to do math or string transforms
5. Use specific types: enum over vague strings; natural labels over IDs
6. Graceful failures: Handle rate limits; return meaningful errors for retry
7. Sync UI and tools: Update interface after tool completes so agent can verify state
8. Test via evals: Create evaluation tests, not hard-coded unit tests

---

Limitations

Limitation	Detail
Requires browsing context	No headless execution; tab must be open
Single browser for now	Chromium-only; no Firefox/Safari support
Tool discoverability	Agent must visit page to find tools (no global registry)
Spec instability	Active development; APIs subject to change
Complex UI overhead	May need refactoring to expose tools cleanly

---

References

Resource	URL
Chrome Docs	https://developer.chrome.com/docs/ai/webmcp
Imperative API	https://developer.chrome.com/docs/ai/webmcp/imperative-api
Declarative API	https://developer.chrome.com/docs/ai/webmcp/declarative-api
Security	https://developer.chrome.com/docs/ai/webmcp/secure-tools
Best Practices	https://developer.chrome.com/docs/ai/webmcp/best-practices
Use Cases	https://developer.chrome.com/docs/ai/webmcp/use-cases
vs MCP	https://developer.chrome.com/docs/ai/webmcp/compare-mcp
GitHub explainer	https://github.com/webmachinelearning/webmcp
Demos	https://github.com/GoogleChromeLabs/webmcp-tools
Origin trial	https://developer.chrome.com/origintrials/#/register_trial/4163014905550602241
Chrome Status	https://chromestatus.com/feature/5117755740913664