Web MCP

WebMCP Implementation Guide

WebMCP lets web pages expose structured tools to AI agents running in the browser. Instead of building separate backend MCP servers, you reuse existing client-side code — the tools live where your UI lives.

  User + Agent
       |
  [ Browser ]
       |
  document.modelContext.registerTool()
       |
  [ Your Web Page JS ]

Two Approaches

Both approaches can coexist on the same page.

Quick Start — Imperative Tool

await document.modelContext.registerTool({
  name: "add-todo",
  description: "Add a new item to the user's active todo list",
  inputSchema: {
    type: "object",
    properties: {
      text: { type: "string", description: "The text content of the todo item" }
    },
    required: ["text"]
  },
  async execute({ text }) {
    await addTodoItemToCollection(text);
    return {
      content: [{
        type: "text",
        text: `Added todo item: "${text}" successfully.`
      }]
    };
  }
});

Quick Start — Declarative Form Tool

<form toolname="support_request"
      tooldescription="Submit a request for customer support."
      toolautosubmit>
  <label for="name">Name</label>
  <input type="text" name="name">

  <label for="issue">Issue type</label>
  <select name="issue"
    toolparamdescription="Determines what team handles the request.">
    <option value="returns">Return my purchase</option>
    <option value="shipping">Check package status</option>
    <option value="technical">Get website help</option>
  </select>

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

The browser auto-generates a JSON Schema tool definition from the form structure. The agent can fill and submit it.

Setup (Chrome 149+, Edge 150+)

Origin trial: Register at the Chrome origin trial page for WebMCP (feature ID 4163014905550602241). Edge also runs an origin trial (ID 0b76fe60-b266-458e-a285-04e375c0c31a).

Local development: Navigate to chrome://flags/#enable-webmcp-testing, set to Enabled, relaunch Chrome.

Testing extension: Install the Model Context Tool Inspector for manual tool invocation and schema validation.

Other implementations: ChatGPT Desktop has full support; Brave has experimental support in Leo AI chat. Firefox and Safari are still reviewing the proposal (not yet implemented).

Architecture

WebMCP is entirely client-side — no server, no transport protocol, no daemon:

• Ephemeral — tools exist only while the page is open in a browser tab
• DOM-aware — tools operate within the browser's DOM with access to session data, cookies, and elements
• Browser-mediated — the browser mediates between agent and tool execution
• Origin-isolated — tools are visible only to same-origin documents by default

The lifecycle: Registration -> Agent Discovery -> Structured Invocation -> Browser-Mediated Execution -> Response.

When to Use WebMCP vs Backend MCP

The recommendation is to use both as complementary technologies.

Reference Guide

Common Patterns

Dynamic Tool Registration/Unregistration

Register tools when they become relevant, unregister when they're not:

const controller = new AbortController();

// Register when user navigates to checkout
document.modelContext.registerTool(checkoutTool, {
  signal: controller.signal
});

// Unregister when user leaves checkout
controller.abort();

Tool with Read-Only Annotation

await document.modelContext.registerTool({
  name: "get_cart_items",
  description: "Returns the current shopping cart contents and total price.",
  annotations: { readOnlyHint: true },
  inputSchema: { type: "object", properties: {} },
  async execute() {
    const items = getCartState();
    return { content: [{ type: "text", text: JSON.stringify(items) }] };
  }
});

Handling Untrusted Content

await document.modelContext.registerTool({
  name: "get_reviews",
  description: "Fetches user reviews for a product.",
  annotations: { untrustedContentHint: true },
  inputSchema: {
    type: "object",
    properties: {
      productId: { type: "string", description: "Product identifier" }
    },
    required: ["productId"]
  },
  async execute({ productId }) {
    const reviews = await fetchReviews(productId);
    return { content: [{ type: "text", text: JSON.stringify(reviews) }] };
  }
});

Cross-Origin Tool Exposure

await document.modelContext.registerTool({
  name: "partner_data",
  description: "Returns shared data for trusted partner integration.",
  async execute() { return { data: "shared" }; }
}, {
  exposedTo: ["https://trusted-partner.example"]
});

Character Budget Recommendations

Security Checklist

Before deploying WebMCP tools:

1. Mark tools returning user-generated content with untrustedContentHint: true
2. Mark read-only tools with readOnlyHint: true
3. Only expose tools to trusted origins via exposedTo
4. Validate strictly in code, loosely in schema — add descriptive error messages
5. Don't over-parameterize — request only data the tool genuinely needs
6. Use clear, unambiguous tool names (distinguish "create" from "start-creation-process")
7. Stay within character budgets
8. Test with the Model Context Tool Inspector extension

Demo Repositories

• Pizza Maker — imperative API
• React Flight Search — React integration
• French Bistro — declarative form tools

Specification Status

WebMCP is a Draft Community Group Report (W3C Web Machine Learning Community Group, 26 August 2026). The imperative API is stable and implemented in Chrome 149+ and Edge 150+. The declarative API section of the main spec is currently "entirely a TODO" — it's specified separately in declarative-api-explainer.md, and Chrome implements a loose, trial version of it. Service Worker integration is under discussion.

Key open questions: multimodal I/O, streaming support, output schema contracts, user consent management during tool execution (requestUserInteraction()).

Spec: https://webmachinelearning.github.io/webmcp/ GitHub: https://github.com/webmachinelearning/webmcp