How to Add WebMCP to Your Website: Tools, Security and Testing (2026)

To add WebMCP to a website, your page calls document.modelContext.registerTool() for each task you want AI agents to perform, such as searching products or adding an item to a list. Each tool has a name, a plain-language description, a JSON Schema for its inputs and an execute function that runs your existing page code.

WebMCP is still a draft and works only in browser origin trials, so treat this as prototype work. Every code sample below is copied from the official WebMCP explainer on GitHub, as it stood on 6 November 2026 (last commit 2 November 2026). eSEOspace has not run these samples; check the explainer before you build, because the API is still changing.

Before you start: status check

If you are new to the idea, read what WebMCP is first.

Step 1: Choose what to expose

Good first tools match the tasks visitors already do on your site. For a store, that might be product search, filtering and adding to cart. For a service business, it might be checking availability or starting a quote request.

The explainer's best-practice section gives clear rules:

• "Single responsibility": each tool should do one well-defined job.
• "Mind the tool budget and context window": every tool's name, description and schema uses up the agent's context.
• "Default to static registration for simple apps": a few tools registered on page load is fine. Dynamic registration helps complex, multi-state apps.
• Precise verbs: the explainer suggests names like create-event for an immediate action versus start-event-creation for opening a form.
• "Accept raw user input": let your code convert dates and units, not the model.

Leave out anything that changes money, accounts or personal data until you have a confirmation design. Our WebMCP vs MCP guide helps decide whether a task belongs in the page or on an MCP server.

Step 2: Register a tool

This is the explainer's basic example, copied as published. It registers an add-todo tool and passes an AbortSignal so the tool can be removed later.

const controller = new AbortController();

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 }) {
    // Reuse existing client-side application logic and update UI.
    await addTodoItemToCollection(text);
    
    return {
      content: [
        {
          type: "text",
          text: `Added todo item: "${text}" successfully.`
        }
      ]
    };
  }
}, { signal: controller.signal });

// To unregister the tool later, abort the signal.
// controller.abort();

Note what the execute function does. It calls addTodoItemToCollection, which stands for code your page already has. WebMCP is meant to reuse your front end, not replace it.

An example closer to a store

The explainer's design-site scenario includes a tool that starts a print order. It shows how a tool can hand the person off to checkout instead of paying on their behalf:

await document.modelContext.registerTool({
  name: "order-prints",
  description: "Orders the current design for printing and shipping to the user.",
  inputSchema: {
    type: "object",
    properties: {
      copies: { type: "number", description: "Number of copies between 1 and 1000." },
      pageSize: { type: "string", enum: ["Letter", "Legal", "A4"], default: "Letter" }
    },
    required: ["copies"]
  },
  execute({ copies, pageSize }) {
    initiatePrintCheckout(copies, pageSize);
  }
});

In the explainer's story, the agent runs this tool and the browser moves to "the secure checkout page where Jen can complete the order with a single click." The person, not the agent, finishes the purchase.

Step 3: Add annotations and validation

The WebMCP spec lets each tool carry an annotations object with hints including readOnlyHint, untrustedContentHint and consequentialHint. It also allows an optional title and outputSchema.

Chrome's guide to secure tools, last updated 1 September 2026, explains when to use them:

• "Use the readOnlyHint on tools that don't change state."
• "If a tool returns user-generated content (UGC) or externally sourced data, consider adding the untrustedContentHint to the tool."
• "If executing a tool results in significant actions, such as booking travel or transferring money, set consequentialHint: true so the agent or browser can request user confirmation before execution."

Hints are not enforcement. The explainer says to "Validate strictly in code, loosely in schema." Your execute function "should still validate current inputs, authorization, and preconditions before running." Return clear error messages so the agent can correct itself.

Stripe's WebMCP guide for agent builders shows the same principle from the agent side. Stripe sets consequentialHint on payment submission tools and says: "Don't interpret the hint itself as confirmation."

Step 4: Control who can see your tools

The explainer says that by default, tools "are only exposed to itself, same-origin documents in the same tree, and built-in browser agents." Access is governed by a tools Permissions Policy. Calls to registerTool() are rejected with a NotAllowedError if a Permissions-Policy: tools=() header or an iframe allow attribute turns it off.

To share a tool with a trusted partner's embedded agent, the explainer shows the exposedTo option:

await document.modelContext.registerTool({
  name: "share-location",
  description: "Returns the user's office location.",
  execute() { return { office: "Building 4" }; }
}, { exposedTo: ["https://trusted-partner.example"] });

Chrome's guidance is short: "Only expose your tools to origins that you trust." It also warns that even a read-only tool "can reveal information about a user."

Step 5: Keep tools in sync with the page

When tools change, document.modelContext fires a toolchange event. The explainer shows an in-page agent refreshing its list:

document.modelContext.addEventListener("toolchange", async () => {
  const currentTools = await document.modelContext.getTools();
  updateAgentToolRegistry(currentTools);
});

Two rules from the explainer help here. To change a tool's name, description or schema, unregister it and register it again. And "Synchronize visual UI state": the page should update on screen right after a tool runs, so the person sees what the agent did. WebMCP has no updateTool() method today.

Step 6: Test

1. Turn on local testing. Chrome's WebMCP docs say to enable chrome://flags/#enable-webmcp-testing and relaunch Chrome.
2. Try an inspector. The same docs describe a Model Context Tool Inspector extension that tests your tools with natural language prompts. It calls Gemini, so you need your own Gemini API key.
3. Debug with DevTools MCP. The Chrome DevTools MCP tool reference lists list_webmcp_tools and execute_webmcp_tool. They are off by default and need the --categoryExperimentalWebmcp=true flag. Our Chrome DevTools MCP guide covers setup.
4. Join an origin trial for live traffic. Chrome's origin trial post links the sign-up. Edge runs its own trial.
5. Keep the fallback working. Agents can still use your normal UI, so your forms and buttons must work for people and automation alike.

A launch checklist

• A short list of single-purpose tools, each tied to a real user task
• Clear descriptions and a description on every input field
• readOnlyHint on safe reads, consequentialHint on anything that spends money or books time
• Server-side checks for every action, as you would for any form
• No exposedTo unless you have a named, trusted partner
• On-screen feedback after each tool call
• A note in your privacy policy if tools return personal data
• A calendar reminder to recheck the spec and browser status

Next step

eSEOspace is a web design agency, and our WebMCP development service helps teams pick the right first tools, prototype them on a test build and plan for browser changes. If you also need AI apps to reach your data, see our MCP development service. All work is quoted per project. For how WebMCP sits beside other standards, see the agent protocols hub.

Frequently asked questions