Complete WebMCP Implementation Guide for 2026

WebMCP lets AI agents — ChatGPT, Claude, Gemini, Copilot — read and interact with your website directly. This is a practical, code-first walkthrough of every API surface you need to ship an AI-ready page in 2026.

WebMCP is the client-side protocol that lets a browser expose site capabilities — forms, actions, data — directly to AI agents. Unlike server-side MCP (where the model connects to your backend), WebMCP runs in the page: whatever the user can do in their browser, an agent can do too, under the user's permissions and session. That's the whole unlock.

This guide covers three implementation surfaces: the Declarative API (HTML attributes on existing forms), the Imperative API (navigator.modelContext), and the .well-known/webmcp manifest. Most sites only need the first two.

Step 1 — Audit what you already have

Before writing code, understand which actions on your site matter for agents. Good candidates: search, filter, add-to-cart, submit-contact, book-appointment, sign-up. Bad candidates: hover tooltips, carousel controls, cosmetic animations.

If you want a starting score, run the free audit — it will flag missing toolname attributes, absent .well-known/webmcp, and Imperative API gaps in under 15 seconds.

Step 2 — Declarative API (HTML form attributes)

The Declarative API is the fastest way to ship WebMCP. You add two attributes to an existing HTML <form>:

<form id="contact" toolname="contactSupport" tooldescription="Send a message to our support team. Use this when the user wants help with an order or account issue.">
  <input name="email" type="email" required>
  <textarea name="message" required></textarea>
  <button type="submit">Send</button>
</form>

The toolname is a camelCase identifier (think function name). The tooldescription is a sentence or two that tells the agent when to use this form, not what fields it has — those are inferred from name and type. Good descriptions dramatically improve discoverability.

Handling tool-initiated submissions server-side

When an agent submits the form, browsers set a SubmitEvent.agentInvoked flag. Use it for analytics, abuse detection, or to adjust UX — do not use it for authorization; that's the user's session, not the agent's.

Step 3 — Imperative API: navigator.modelContext

When your action isn't a form (a React modal, a Vue drawer, a custom stepper), use the Imperative API:

navigator.modelContext.registerTool({
  name: "addToCart",
  description: "Add a product to the shopping cart by SKU and quantity.",
  inputSchema: {
    type: "object",
    properties: {
      sku: { type: "string" },
      quantity: { type: "integer", minimum: 1, default: 1 }
    },
    required: ["sku"]
  },
  execute: async ({ sku, quantity }) => {
    const res = await fetch("/api/cart", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ sku, quantity })
    });
    return res.ok ? { success: true } : { success: false };
  }
});

Register tools after the view they belong to mounts, and unregisterTool() on unmount. Otherwise you expose tools the user can't actually see — a bad experience and a subtle abuse vector.

Step 4 — Provide page context

Agents work best when they know where they are. Call provideContext() whenever the route or major state changes:

navigator.modelContext.provideContext({
  type: "page",
  data: {
    route: "/products/running-shoes",
    title: "Men's Running Shoes",
    productCount: 42,
    filters: { size: "10", color: "black" }
  }
});

Step 5 — Ship the manifest

Serve a JSON manifest at https://yourdomain.com/.well-known/webmcp so crawlers (including WebMCP Checker) can discover your capabilities without JavaScript:

{
  "name": "Example Store",
  "description": "Online store for running gear.",
  "version": "1.0.0",
  "tools": [
    { "name": "searchProducts", "description": "Search the catalog." },
    { "name": "addToCart",       "description": "Add a product to the cart." }
  ]
}

Make sure the server returns Content-Type: application/json and doesn't 404 or redirect. That's one of the most common readiness checklist failures.

Step 6 — Test in Chrome Canary

WebMCP is available in Chrome 146 Canary behind a flag (chrome://flags#webmcp) as part of the Early Preview Program. Enable the flag, open DevTools → Application → WebMCP, and confirm your tools show up. Agents that implement the protocol will see the same list.

Common mistakes I see every week

• Vague tool descriptions. "Submit form" teaches the agent nothing. Describe the user intent it fulfills.
• Forgetting to unregister. Stale tools on SPAs cause agents to call actions that no longer exist.
• Server-side trust. Never trust agentInvoked to grant permissions. It's a signal, not a credential.
• Hidden forms. A form that's display:none still registers as a tool. Remove it from the DOM or strip toolname.

Where to go next

If you want one page to hand to your team, our 42-page implementation PDF has React integration, industry playbooks, and a pre-launch checklist. For strategy, start with Agentic Engine Optimization (AEO). For the decision layer, read the WebMCP vs MCP vs NLWeb comparison.

Frequently Asked Questions