WebMCP Implementation Guide: Make Your Website Agent-Ready in Chrome 149

WebMCP implementation guide for agent-ready websites

AI agents can now take structured actions on websites that expose WebMCP tools. Chrome 149 shipped the origin trial on June 2, 2026. The W3C Community Group Draft Report followed on June 17. This is not a final standard. The API surface may change. But if you want your website to be agent-ready — meaning agents like ChatGPT, Claude, and Gemini can discover your site's functionality and invoke it — this is how you implement WebMCP today.

I'm writing this as a practical walkthrough. Not a rehash of the Chrome docs. Those live at developer.chrome.com/docs/ai/webmcp and you should read them alongside this. This guide covers what the docs don't: the actual steps, the mistakes you'll make, and how to test before you ship.

What WebMCP is and why it matters

WebMCP is a proposed web standard that lets your website expose tools to AI agents. Think of it as an API, but instead of being for developers, it's for agents. When an agent visits your site, it can discover your tools and invoke them. A support form becomes a tool an agent can fill out for a user. A product search becomes a tool the agent can run automatically. An appointment booking flow becomes something the agent can handle end-to-end.

This matters because the way people find and interact with websites is changing. Users are increasingly delegating tasks to agents instead of browsing themselves. If your site has no agent-readable surface, agents can't help their users interact with you. WebMCP is the bridge — a web MCP server that runs in the browser, not in a separate process.

It's also an origin trial, not a final standard. The API may change before standardization. Treat this as preparation, not certification. You're making your site agent-ready for the current trial. When the spec evolves, you adapt. That's the deal. The result is an agent-friendly website where AI agents can discover and interact with your tools.

The two WebMCP APIs

WebMCP exposes two APIs for registering tools. You can use either or both.

Declarative API: HTML form attributes

The Declarative API works by adding attributes to existing HTML form elements. The browser synthesizes a JSON Schema from the form structure. No JavaScript required for basic tool exposure.

Attributes:

• toolname — the name agents use to reference this tool. Use verb + object: createSupportRequest, not form1.
• tooldescription — natural language description of what the tool does and when to use it. This is what the agent reads to decide whether to invoke your tool.
• toolparamdescription — optional, on individual fields. Adds a description to the JSON Schema when the <label> text alone isn't clear enough for an agent.
• toolautosubmit — optional. Auto-submits the form when an agent invokes the tool. Without it, the user must click Submit manually after the agent fills the form.

When an agent invokes a declarative tool, the browser brings the form into focus, pre-fills the fields, and applies the :tool-form-active CSS pseudo-class so the user sees a visual indicator.

Imperative API: JavaScript registration

The Imperative API uses document.modelContext.registerTool(). You register a tool object with a name, description, input schema, and an execute function. The execute function runs arbitrary JavaScript — typically an API call — and returns a string result to the agent.

This is better for dynamic tools that call your backend API, tools that need complex logic, or tools that don't map to a visible form.

WebMCP vs MCP

Model Context Protocol (MCP) is Anthropic's standard for connecting AI agents to external tools and data sources. WebMCP is the browser-native equivalent. MCP runs as a separate server process — you set up an MCP server, register tools, and agents connect to it. WebMCP runs in the browser. Your website itself exposes the tools. No separate server, no external process.

They complement each other. If you already run an MCP server, WebMCP lets your website do the same thing for browser-based agents. If you don't have an MCP server, WebMCP is the simpler starting point — it's just HTML and JavaScript on pages you already serve.

Step-by-step: declare your first WebMCP tool

Let's walk through implementing a support request form as a WebMCP tool using the Declarative API. This is the simplest starting point — you don't need to write JavaScript for basic tool exposure. Think of this as a WebMCP tutorial you can complete in under an hour.

Step 1: Enable the WebMCP flag in Chrome

For local development, enable WebMCP in your browser:

1. Open Chrome 149 or later
2. Navigate to chrome://flags/#enable-webmcp-testing
3. Set the flag to Enabled
4. Click Relaunch

After relaunch, WebMCP APIs are available on any HTTPS page or localhost. This is for development only. For production, you need an origin trial token (covered below).

Step 2: Add tool attributes to your form

Take an existing form on your site and add toolname and tooldescription:

<form toolname="createSupportRequest"
      tooldescription="Submits a request for customer support. Use this when a user needs help with a product issue, billing question, or account access problem."
      action="/api/support/submit"
      method="POST">

  <div>
    <label for="firstName">First Name</label>
    <input type="text" id="firstName" name="firstName" required>
  </div>

  <div>
    <label for="lastName">Last Name</label>
    <input type="text" id="lastName" name="lastName" required>
  </div>

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

  <div>
    <label for="issueType">Issue Type</label>
    <select id="issueType" name="issueType" required
            toolparamdescription="Determines which support team receives this request.">
      <option value="">-- Select an issue type --</option>
      <option value="bug">Bug or technical issue</option>
      <option value="billing">Billing or payment question</option>
      <option value="account">Account access or login problem</option>
    </select>
  </div>

  <div>
    <label for="description">Describe Your Issue</label>
    <textarea id="description" name="description" rows="5" required
              toolparamdescription="Detailed description of the problem, including any error messages, steps to reproduce, and what you expected to happen."></textarea>
  </div>

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

That's it. The browser synthesizes a JSON Schema from the form structure. Agents can now discover and invoke createSupportRequest. This is a complete WebMCP example — under 30 lines of HTML with two extra attributes.

Step 3: Handle agent-invoked submissions

When an agent fills and submits the form, you need to return a result to the agent. Use the agentInvoked property on the submit event and respondWith() to send the result:

document.querySelector('form').addEventListener('submit', (e) => {
  if (e.agentInvoked) {
    e.preventDefault();

    const formData = new FormData(e.target);
    fetch(e.target.action, {
      method: 'POST',
      body: formData
    })
    .then(res => res.json())
    .then(data => {
      e.respondWith(Promise.resolve(
        `Support request #${data.ticketId} created. A confirmation email has been sent to ${formData.get('email')}.`
      ));
    })
    .catch(err => {
      e.respondWith(Promise.resolve(
        `Error submitting support request: ${err.message}. Please try again or contact support directly.`
      ));
    });
  }
});

The string you pass to respondWith() is what the agent receives as the tool output. Write it as a human-readable message — the agent reads it and decides what to tell the user.

Step 4: Add the CSS pseudo-classes

Add focus indicators so users can see when an agent is interacting with the form:

form:tool-form-active {
  outline: light-dark(blue, cyan) dashed 1px;
  outline-offset: -1px;
}
input:tool-submit-active {
  outline: light-dark(red, pink) dashed 1px;
  outline-offset: -1px;
}

Registering an imperative tool

For tools that call your API instead of filling a form, use the Imperative API. Here's an order status lookup:

if ('modelContext' in document) {
  document.modelContext.registerTool({
    name: 'get_order_status',
    description: 'Search orders in a given timeframe. Returns order number, shipping status, and delivery location. Use this when a customer asks about their order status, delivery date, or tracking.',
    inputSchema: {
      type: 'object',
      properties: {
        timeframe: {
          type: 'string',
          enum: ['today', 'yesterday', 'last_7_days', 'last_30_days', 'last_6_months'],
          description: 'Timeframe for the order lookup. Defaults to last 30 days.'
        }
      },
      required: ['timeframe']
    },
    execute: async ({ timeframe }) => {
      try {
        const response = await fetch(`/api/orders?timeframe=${timeframe}`, {
          credentials: 'include'
        });

        if (!response.ok) {
          return `Unable to fetch orders: server returned ${response.status}. Please try again or contact support.`;
        }

        const orders = await response.json();

        if (!orders || orders.length === 0) {
          return `No orders found in the ${timeframe.replace(/_/g, ' ')} timeframe.`;
        }

        const summary = orders.map(o =>
          `Order #${o.orderNumber}: ${o.status}. Expected delivery: ${o.estimatedDelivery || 'pending'}.`
        ).join('\n');

        return `Found ${orders.length} order(s):\n${summary}`;
      } catch (err) {
        return `Error looking up orders: ${err.message}. Please try again or contact support.`;
      }
    },
    annotations: {
      readOnlyHint: true,
      untrustedContentHint: false
    }
  });
}

Key parts:

• readOnlyHint: true tells agents this tool only reads data. Agents can call it freely without caution.
• untrustedContentHint: false tells agents the output comes from your own system, not user-generated content.
• The execute function returns a string, not an object. Agents read strings. Format your output as readable text.
• Wrap registration in if ('modelContext' in document) so the script doesn't crash on browsers without WebMCP.

To unregister a tool (useful in single-page apps):

const controller = new AbortController();
document.modelContext.registerTool(tool, { signal: controller.signal });
// When navigating away:
controller.abort();

Testing with the WebMCP inspector

Testing is where most implementations fail. You write the tool, you think it works, but you never verify that an agent can actually discover and invoke it.

Install the Model Context Tool Inspector

Google provides a Chrome extension for testing WebMCP tools:

1. Search the Chrome Web Store for "Model Context Tool Inspector" or find the link on developer.chrome.com/docs/ai/webmcp
2. Install the extension
3. It lets you see which tools are registered on the current page, manually call tools, verify JSON Schema, and talk to an agent using natural language

Verify tool registration

1. Navigate to your page with the WebMCP tool
2. Open the inspector extension
3. You should see your registered tool(s) listed
4. Check that the tool name and description appear correctly
5. Verify the input schema matches what you defined
6. Confirm annotations (readOnlyHint, untrustedContentHint) are set

Manual tool call

1. Click on the tool in the inspector
2. Provide input parameters as JSON
3. Execute the tool
4. Verify the output matches expectations

Example input for createSupportRequest:

{
  "firstName": "Jane",
  "lastName": "Doe",
  "email": "jane@example.com",
  "issueType": "billing",
  "description": "I was charged twice for my June subscription."
}

Natural language test

Use the inspector's chat feature to test agent discovery:

• Type "I need help with a billing issue" — the agent should invoke createSupportRequest
• Type "Search for wireless headphones under $200" — the agent should invoke your product search tool
• Type "Book a consultation for next Tuesday" — the agent should invoke your appointment booking tool

If the agent doesn't invoke your tool, the problem is almost always the description. It's either too vague or doesn't explain when to use the tool.

Verify in DevTools

Open the Console and check registered tools programmatically:

const tools = await document.modelContext.getTools();
console.log(tools);

You should see an array of tool objects with name, description, inputSchema, and annotations.

Chrome 149 origin trial: production setup

For production, you need an origin trial token so WebMCP is available to all visitors on your domain, not just browsers with the flag enabled.

1. Go to developer.chrome.com/origin-trials
2. Register your domain for the WebMCP origin trial
3. You'll receive a token
4. Add it as a meta tag:

   <meta http-equiv="origin-trial" content="YOUR_TOKEN_HERE">
   

5. Or add it as an HTTP header:

   Origin-Trial: YOUR_TOKEN_HERE
   

Without the token, only browsers with the flag enabled will see your tools.

Verify origin isolation

WebMCP requires origin isolation. Check that your site does NOT do any of the following:

1. Does not set document.domain anywhere in your JavaScript
2. Does not send the header Origin-Agent-Cluster: ?0
3. Does not use Origin-Agent-Cluster: ?0 in any meta tag

If any of these are present, WebMCP APIs will be disabled and document.modelContext calls will throw SecurityError.

Quick verification — run this in DevTools Console:

document.modelContext.registerTool({
  name: 'test_tool',
  description: 'Test',
  execute: async () => 'ok'
}).then(() => console.log('WebMCP is working!'))
  .catch(err => console.error('WebMCP error:', err.message));

If you see "WebMCP is working!" the APIs are available. If you see a SecurityError, fix origin isolation first.

llm.txt: why it complements WebMCP

WebMCP lets agents invoke tools on your site. llm.txt helps agents discover and understand your site in the first place. They solve different parts of the same problem.

llm.txt is a plain-text file at your site root that gives AI agents context about what your site does, what content is available, and what actions are possible. Think of it as a machine-readable README for your website. An agent that arrives at your site can read llm.txt to understand your business before it looks for WebMCP tools.

A minimal llm.txt:

# Acme Tools

We sell hand tools and power tools for DIY and professional use.

## What we offer
- Product catalog: https://acmetools.com/products
- Support: https://acmetools.com/support
- Order tracking: https://acmetools.com/orders

## Actions available
- Search products by keyword, category, and price
- Submit support requests
- Look up order status by timeframe

## Notes
- All prices in USD
- Free shipping on orders over $50
- Support response time: 24 hours

If you want the full llm.txt setup walkthrough — template, generator, validation, and how it fits with schema and robots.txt — read the llm.txt guide for AI agent discoverability or get the agent-ready website toolkit which includes an llm.txt template, generator walkthrough, and audit checklist.

Common mistakes

I've seen these repeatedly in WebMCP implementations. All of them are fixable.

1. Vague tool descriptions

The tool description is the only thing the agent reads to decide whether to invoke your tool. "Submit a form" is useless. "Submits a request for customer support. Use this when a user needs help with a product issue, billing question, or account access problem." is useful.

The formula: what the tool does + when to use it + what it returns.

2. Missing llm.txt

Agents need to discover your site before they can discover your tools. llm.txt is the discovery layer. WebMCP is the interaction layer. Skip llm.txt and agents may never find your tools.

3. Not testing with the inspector

You wrote the tool. It looks right. But does the agent actually see it? Can it invoke it? Does the schema match? You won't know until you install the inspector extension and test. This is the step everyone skips and the step that catches every bug.

4. Negative language in descriptions

Agents process the action verb, not the negation. "Don't use this tool for weather queries" can register as "use for weather." Describe what the tool does, not what it doesn't do.

5. Asking agents to do math

If the user says "11:00 to 15:00," accept it as a string. Don't force the agent to convert it to 240 minutes. Accept raw user input and handle the logic in your execute function.

6. Overlapping tools

Two tools that both "search products" cause agent confusion. Merge them or make the distinction clear in the description. Start with 1-3 tools and add only when needed.

7. No error handling

If your API fails, return a helpful string. Do not throw, return null, or return "Error". The agent reads the error and decides whether to retry or tell the user. "Unable to fetch orders: server returned 500. Please try again in a moment." is useful. "Error" is not.

WebMCP protocol: what's next

The W3C Community Group Draft Report was published June 17, 2026. Microsoft, Google, and the Web Machine Learning Community Group are developing the spec. The origin trial in Chrome 149 is the first browser implementation. Other browsers will follow if the trial goes well.

The API surface — toolname, tooldescription, toolparamdescription, toolautosubmit attributes for declarative; document.modelContext.registerTool for imperative — may change. Monitor the W3C draft and the Chrome docs for updates.

This is why the positioning is "prepare for the agent-ready web," not "certified agent-ready." You're implementing against a draft standard. The work isn't wasted — the concepts (tool discovery, description quality, testing) transfer regardless of API changes. But don't promise your users permanent compatibility.

FAQ

How do I implement WebMCP on my website?

Start with the Declarative API. Add toolname and tooldescription attributes to an existing HTML form on your site — the browser synthesizes a JSON Schema from the form structure, no JavaScript required. For tools that call your backend API, use document.modelContext.registerTool() with an input schema and an execute function. Enable the chrome://flags/#enable-webmcp-testing flag for local development, and register for the Chrome 149 origin trial for production. Test with the Model Context Tool Inspector extension before you ship.

The full step-by-step walkthrough is in the Step-by-step: declare your first WebMCP tool section above.

What is the WebMCP declarative API?

The Declarative API lets you expose tools by adding HTML attributes to existing form elements: toolname, tooldescription, toolparamdescription, and toolautosubmit. The browser synthesizes a JSON Schema from the form structure. No JavaScript is required for basic tool exposure. When an agent invokes a declarative tool, the browser brings the form into focus, pre-fills the fields, and applies the :tool-form-active CSS pseudo-class as a visual indicator.

How do I use WebMCP in Chrome?

Open Chrome 149 or later, navigate to chrome://flags/#enable-webmcp-testing, set the flag to Enabled, and relaunch. WebMCP APIs are then available on any HTTPS page or localhost. For production, register your domain for the WebMCP origin trial at developer.chrome.com/origin-trials, add the token as a <meta http-equiv="origin-trial"> tag or Origin-Trial HTTP header, and verify origin isolation (do not set document.domain or Origin-Agent-Cluster: ?0).

Do I need JavaScript to use WebMCP?

No. The declarative API works with plain HTML form attributes — toolname, tooldescription, toolparamdescription, and toolautosubmit. The browser synthesizes the JSON Schema and handles tool discovery without any JavaScript. You only need JavaScript for the imperative API (document.modelContext.registerTool) when you want tools that call your backend API, need complex logic, or do not map to a visible form. See the agent-ready website toolkit FAQ for more.

How do I test WebMCP with the inspector?

Install the Model Context Tool Inspector Chrome extension from the Chrome Web Store. Navigate to your page with the WebMCP tool, open the inspector, and verify your tools are listed with correct names, descriptions, input schemas, and annotations. Then run a manual tool call with JSON input and check the output. Finally, use the inspector's chat feature to test agent discovery with natural language prompts. If the agent does not invoke your tool, the problem is almost always the description being too vague.

The full testing walkthrough is in the Testing with the WebMCP inspector section above.

What's the difference between MCP and WebMCP?

Model Context Protocol (MCP) is Anthropic's standard for connecting AI agents to external tools and data sources. It runs as a separate server process that agents connect to. WebMCP is the browser-native equivalent — your website itself exposes the tools via HTML attributes and JavaScript. No separate server, no external process. They complement each other: if you already run an MCP server, WebMCP lets your website do the same thing for browser-based agents. If you don't have an MCP server, WebMCP is the simpler starting point.

The complete toolkit

This guide covers the implementation steps. If you want the complete pack — copy-paste HTML templates for support forms, product search, and appointment booking, imperative JavaScript templates for order status and availability checks, a 25-item audit checklist, a tool description copywriting guide with 8 rules and before/after examples, and Chrome 149 testing instructions with debug steps — the agent-ready website toolkit has all of it.

The checkers tell you if your site is ready. The toolkit helps you make it ready.