Salesman Hal

WebMCP: a practical guide for business websites

WebMCP lets a web page hand an AI agent a list of things it can do, such as “request a quote” or “check opening hours”, so the agent calls them directly instead of guessing its way through buttons and forms. Here’s what it is, how to add it, and how much it matters today.

Updated

What WebMCP is

WebMCP (Web Model Context Protocol) is a JavaScript and HTML interface that lets a web page describe actions an AI agent can take on it. Each action is a tool: a name like request_quote, a plain-language description of what it does, a JSON Schema for the inputs it needs, and a function that runs when the agent calls it.

The agent is one working inside the browser: Gemini in Chrome, an assistant built into another browser, or a browser extension acting for the person at the keyboard. The page registers its tools, the browser passes them to the agent, and when the agent calls one, the page’s own code runs with the visitor’s session, cookies and all.

The specification is a Draft Community Group Report in the W3C’s Web Machine Learning Community Group, edited by engineers from Microsoft and Google. That makes it a serious proposal with two browser makers behind it, but not a W3C standard, and the draft says plainly that it isn’t on the standards track yet. The API has already changed once: early tutorials use navigator.modelContext, while the current draft and Chrome’s docs use document.modelContext.

Why it matters

Browser agents already book tables and fill in forms, but without WebMCP they do it the hard way: take a screenshot or read the page’s HTML, work out which box is which, type, click, and check whether it worked. That’s slow, costs a lot of model tokens, and breaks whenever a layout changes or a date picker behaves oddly. When it fails, the agent tends to move on to a business whose site it can work with, and you never learn you lost the lead.

A tool replaces all that guessing with a contract. The agent knows the action exists, knows exactly what inputs it needs, and gets a clear answer back (“Quote request sent”) instead of inferring success from a thank-you page. For a business, that means the agent is more likely to finish the job on your site.

WebMCP vs. MCP, llms.txt and the rest

WebMCP borrows its idea of tools from the Model Context Protocol (MCP), the standard way AI assistants connect to outside services. The two do different jobs, and most businesses that care about AI agents will want both.

WebMCP MCP server llms.txt
Where it runs In the visitor’s browser, on your page On a server, reached over HTTP A text file on your site
Who uses it An agent in the browser tab Any assistant: ChatGPT, Claude, agents in the cloud Crawlers and assistants reading your site
What it offers Actions, using the visitor’s logged-in session Actions and information, without a browser Information only
How it’s found The agent has to be on the page Discovery files, link tags, registries A fixed URL, /llms.txt

In short, an MCP server answers an assistant wherever it is, including one that never opens a browser. WebMCP helps the agent that has already arrived. Schema.org markup and llms.txt still matter for helping agents understand the business; WebMCP is about letting them act.

Adding tools with HTML

The quickest route is the declarative API: add a few attributes to a form you already have, and the browser turns it into a tool, building the input schema from the form’s fields.

  • toolname and tooldescription on the <form> register it. Remove either and the tool goes away.
  • toolparamdescription on a field explains what goes in it, when the field’s label isn’t enough.
  • toolautosubmit on the form lets the agent submit it. Without it, the browser fills the fields in and the person presses the button themselves.
<form action="/quote" method="post"
      toolname="request_quote"
      tooldescription="Ask for a quote on a plumbing job. A person replies by phone or email within one business day.">
  <input name="name" required
         toolparamdescription="The customer's full name">
  <input name="phone" type="tel" required>
  <textarea name="job" required
            toolparamdescription="What needs doing, and the address"></textarea>
  <button>Get a quote</button>
</form>

To tell the agent how it went, check agentInvoked on the form’s submit event. When an agent submitted the form, prevent the default navigation and pass a promise to respondWith(); whatever it resolves to goes back to the agent.

form.addEventListener('submit', (event) => {
  if (!event.agentInvoked) return; // A person submitted: carry on as normal.

  event.preventDefault();
  event.respondWith(
    sendQuoteRequest(new FormData(form))
      .then(() => 'Quote request sent. Expect a reply within one business day.'),
  );
});

Chrome also fires toolactivated and toolcancel events on document.modelContext, and adds the :tool-form-active and :tool-submit-active CSS pseudo-classes, so you can show the visitor that an agent is filling in the form.

One caution: the declarative API is documented by Chrome and runs in its origin trial, but the specification itself doesn’t include it yet. The W3C draft says a declarative version is being explored separately, so expect these attribute names to change before anything is final.

Adding tools with JavaScript

The imperative API is for actions that aren’t a single form: checking availability, searching a catalogue, building a quote from several steps. Call document.modelContext.registerTool() with:

  • name (required): letters, digits, _, - and ., up to 128 characters, unique on the page;
  • description (required): what the tool does and when to use it;
  • inputSchema: a JSON Schema for the arguments, and optionally an outputSchema;
  • execute (required): the function that does the work and returns the result;
  • title, for a human-friendly label, and annotations (more on those below).
const controller = new AbortController();

await document.modelContext.registerTool({
  name: 'get_opening_hours',
  description: 'Opening hours for each day of the week, in the business’s local time.',
  inputSchema: { type: 'object', properties: {} },
  annotations: { readOnlyHint: true },
  async execute() {
    const response = await fetch('/api/opening-hours');
    return response.text();
  },
}, { signal: controller.signal });

// Later, to take the tool away again:
controller.abort();

To remove a tool, pass an AbortSignal when you register it and abort it later, which is handy in single-page apps where the available actions change from screen to screen. From Chrome 153, unregistering a tool doesn’t break a call that’s already running.

React, Angular and Vue have early helpers (for example useWebMCP in VueUse), and the webmcp-types package adds TypeScript types.

Where support stands

As of November 2026:

Browser or agent Status
Chrome Origin trial from Chrome 149 (announced at Google I/O in May 2026). Off by default; a flag turns it on for local testing.
Edge Origin trial from Edge 150.
Brave Support in its Leo assistant is listed for Brave 1.102.2, expected in early January 2027.
ChatGPT desktop app Listed as supported, in limited cases.
Firefox No implementation. Semrush reports Mozilla’s position as neutral.
Safari No implementation. Semrush reports that Apple’s WebKit team opposes the proposal.

No browser has announced a date for turning WebMCP on for everyone, and Chrome describes the API as subject to change. So today, a tool you add reaches only visitors whose browser is in a trial on your site, or who have turned the feature on themselves.

How to try it

  1. On your own machine: in Chrome 149 or later, open chrome://flags/#enable-webmcp-testing, enable it and relaunch.
  2. See and call your tools: install the Model Context Tool Inspector extension from the Chrome Web Store. It lists the tools on the current page, lets you run them by hand, and can send a natural-language request to a model to see whether it picks the right tool. Chrome DevTools can also debug tools and check that your schemas parse.
  3. For real visitors: register your site for the WebMCP origin trial in Chrome’s Origin Trials console (Edge runs its own) and add the token to your pages, as a meta tag or an Origin-Trial HTTP header:
    <meta http-equiv="origin-trial" content="YOUR_TRIAL_TOKEN">
    A token works only on the origin it was issued for, and trials end, so plan to renew it.

Writing tools agents use well

An agent decides whether and how to use a tool from its name, description and schema alone. Write them for a smart reader who has never seen your site.

  • Name the outcome, not the widget. book_inspection beats submit_form_3.
  • Say what happens next. “A person replies within one business day” or “This books the slot immediately” helps the agent set the user’s expectations and decide whether to ask first.
  • Be strict in the schema. Mark required fields, use enum for fixed choices, give formats for dates and phone numbers, and describe every field whose name isn’t obvious.
  • Return useful text, including errors. “That date is fully booked; the next opening is Thursday at 9am” lets the agent recover. A bare failure makes it give up.
  • Use the annotations. readOnlyHint marks tools that only look things up. consequentialHint marks ones with real effects, such as bookings, payments or messages to people, so the browser or agent can ask the user to confirm first. untrustedContentHint flags results that contain text you don’t control, such as reviews.
  • Keep the set small. A handful of well-described tools for the actions that make you money beats exposing every button on the page.

Limits and risks

  • No discovery. Chrome’s docs note that an agent has to visit a page to learn what tools it has. WebMCP doesn’t help an assistant find you; it helps the one that’s already there. That’s why it pairs with an MCP server and discovery files.
  • Built for a person in the loop. The API is aimed at local browser sessions where someone is watching, not at agents running unattended in the cloud.
  • Your code, the visitor’s session. Tools run with whatever the logged-in visitor can do, so treat every input as untrusted, validate on the server as you would for a form, and rate-limit anything that sends messages or creates bookings.
  • Hints are only hints. The draft warns that a malicious site can misdescribe its tools or leave off the annotations, and that browser extensions can list and call tools too. Agents and browsers have to decide how much to trust what a page says about itself.
  • Secure pages only. WebMCP works only over HTTPS. Same-origin frames can register tools; a cross-origin frame needs allow="tools" on its <iframe>.
  • A moving target. The API has already been renamed once and the declarative part isn’t in the spec yet. Keep your tool code small and in one place so it’s cheap to update.

What to do now

  1. List the five or ten actions that matter. For most businesses that’s the contact or quote form, booking, search and maybe checkout or a support request.
  2. Fix them for people first. Clear labels, sensible field names, real validation and readable error messages make a form easier for every kind of agent, with or without WebMCP, and you need them before any tool description is worth writing.
  3. Add attributes to your most important form and test it with the flag and the Tool Inspector. It’s a small, reversible change.
  4. Join the origin trial if you want trial visitors to see your tools now, and put a reminder in the calendar for when the token expires.
  5. Make sure agents can find and reach you without a browser too: an MCP server, discovery files, robots.txt rules that let AI agents in, and structured data. Our free AI-readiness scan checks all of these, WebMCP included.

How Salesman Hal handles WebMCP

Hal gives your business a hosted MCP server, with tools to answer questions about the business, search your pages, check open booking times, send inquiries and quote requests into your existing forms, and book meetings on your calendar. The WordPress plugin and the Cloudflare Worker also add a small script that registers those same tools with WebMCP, so an agent in the browser sees them on every page, and the script carries Hal’s Chrome origin-trial token. Read-only tools are marked readOnlyHint; anything that reaches a real person is marked consequentialHint. In browsers without WebMCP, the script does nothing.

See how Hal works

FAQ

Is WebMCP the same as MCP?

No. They share the idea of tools, but an MCP server runs on a server and any assistant can connect to it, while WebMCP tools live in a web page and only an agent in the browser, on that page, can call them.

Does WebMCP help SEO or AI search rankings?

There’s no evidence that any search engine or AI assistant ranks sites on WebMCP. Its value is that agents which reach your site can actually complete an action there. Being found still comes down to content, structured data, crawler access and discovery files.

Do I need to rebuild my site?

No. The declarative API is a few attributes on forms you already have, and the JavaScript API adds tools alongside your existing code. Visitors without a WebMCP browser see no change.

Is it safe to let agents submit my forms?

About as safe as letting people submit them, provided you keep the same server-side checks: validation, spam protection and rate limits. Leave toolautosubmit off where you want the person to press the button themselves, and mark consequential tools so agents ask before acting.

navigator.modelContext or document.modelContext?

The current draft and Chrome’s docs use document.modelContext. Earlier versions used navigator.modelContext, so older tutorials and code may need updating. Checking for both costs one line.

When will it be on for everyone?

No browser has announced a date. Chrome and Edge are in origin trials, Brave has support on the way, and Firefox and Safari have no implementation.

Sources

Further reading

Let AI agents book you, in any browser or none.

Hal adds an MCP server and WebMCP tools to your site in about ten minutes. Free during early access.

Or run the free AI-readiness scan first.