Specoria
Menu
TR Free test

InsightsInfrastructure

WebMCP in practice: turning add-to-cart and stock check into tools an agent can call

How a store can expose stock check and add-to-cart as WebMCP tools, keep orders and payment with the shopper, and test it all in Chrome before agents arrive.

By 8 min read
Cut-paper collage of a plaster hand offering a paper shopping bag through a stone arch toward a paper browser window, with a violet ribbon on the bag.
A shop that speaks a clear language lets the agent in without guessing at every door. Illustration: Specoria · generated with AI

A shopper asks the assistant in their browser: "Is the blue rain jacket in medium still in stock? If it is, put one in my cart." Today the agent answers that by reading your product page, picking the size from a dropdown, hunting for the stock line and clicking a button it hopes is "Add to cart". With WebMCP, your page can answer the same request directly: the agent calls check_stock with the variant, gets a structured answer, then calls add_to_cart.

Earlier this month we covered what Shopify shipped and why it matters for other stores. This is the hands-on follow-up. In this article, we look at where WebMCP stands today, how a store can expose two small tools (one that reads, one that writes), where the line between agent and shopper should sit, and how to test it before any real agent visits.

Where WebMCP stands today

WebMCP is a draft from the W3C Web Machine Learning Community Group. The specification says plainly that it is not a W3C Standard nor on the W3C Standards Track. Its editors work at Microsoft and Google, and the explainer was first published on August 13, 2025.

The idea is simple. A page registers "tools", each with a name, a natural language description and an input schema. An agent in the browser discovers those tools, calls one with structured arguments, and your own page code runs it and returns a result. The explainer calls such pages in-page MCP servers.

Support is early and uneven:

  • Chrome opened an origin trial in Chrome 149 (announced June 9, 2026). Origin trials are time-limited, and Chrome Status lists this one through Chrome 156. For local work, Chrome has a flag: chrome://flags/#enable-webmcp-testing.
  • Edge has an origin trial in Edge 150, and ChatGPT Desktop is listed as supported, according to the community group's implementation tracker.
  • Cloudflare Browser Run supports WebMCP in its experimental Lab sessions and its Kitesurf backend. Cloudflare says Lab sessions should not be used for production workloads.
  • Firefox and Safari appear in the tracker only with links to standards position discussions (and, for Firefox, a bug entry), not with an implementation.

The API shape has also moved. Any snippet you copy today, including ours, may need changes before the feature ships.

Two ways to register a tool

Cut-paper collage of a plaster hand holding a paper basket at a stone threshold, while a single violet paper key rests on a blank card beside a closed door.
The agent may carry the basket, but the final key stays in the shopper's hand. Illustration: Specoria · generated with AI

The specification defines one API: the imperative document.modelContext.registerTool(). A declarative API that turns an HTML form into a tool is being explored separately; the explainer says it is not part of the specification at this time. Chrome documents and implements both in its trial, so you can try either, with that caveat.

Imperative. You pass an object with name, description, inputSchema (JSON Schema) and an execute function. Optional annotations tell agents about the tool's behavior: readOnlyHint (only reads data), consequentialHint (significant, real-world or non-reversible, such as booking a flight or transferring money) and untrustedContentHint (output contains data you don't vouch for, such as reviews).

Declarative. You add toolname and tooldescription to a <form>, and toolparamdescription to fields that need explaining. The browser builds the input schema from the form. Without the toolautosubmit attribute, the agent fills the form, the browser focuses the submit button and the person submits it. In your submit handler, e.agentInvoked tells you an agent triggered it, and after preventDefault() you can return a result with e.respondWith().

A worked example: stock check and add to cart

The following is an illustrative example, not production code. Names such as check_stock and /api/stock are ours; adapt them to your store.

Stock check (read only, imperative). Register one tool on product pages:

  • name: "check_stock"
  • description: "Returns whether a product variant is in stock and the most units one order can include."
  • inputSchema: an object with one required string, sku, described as "The variant SKU shown on this page."
  • annotations: { readOnlyHint: true }
  • execute: async ({ sku }) => { ... } checks that sku belongs to a variant on this page, calls your existing stock endpoint and returns something short, such as { sku, inStock: true, maxQuantity: 4 }.

Add to cart (write, declarative). Your product page already has an add-to-cart form, so annotate it:

  • <form action="/cart/add" method="post" toolname="add_to_cart" tooldescription="Adds the selected variant to the shopper's cart. Does not place an order.">
  • <select name="variant" toolparamdescription="Size and color of the item">
  • <input name="quantity" type="number" min="1" max="10" toolparamdescription="Number of units, 1 to 10">

Adding to a cart is reversible, so toolautosubmit is a reasonable choice here. In the submit handler, answer the agent with the new cart line and total through e.respondWith(), and update the cart on screen at the same time. The explainer asks for exactly that: the visible page should reflect what a tool did, because the shopper and the agent share the same tab.

The WebMCP best practices add two rules: one job per tool, and raw input ("medium", "blue") rather than internal IDs.

Keep orders and payment with the shopper

The most important design decision is which tools you do not register.

  • No tool places an order or takes payment on its own. Stop at "add to cart" and "go to checkout". If you ever add an order tool, set consequentialHint: true and keep the final step on your page, where the person confirms the items and total. One of the explainer's own examples does this: a print-ordering tool takes the shopper to a secure checkout page where they complete the order themselves. Shopify's checkout tools follow the same rule; we covered how in our earlier article.
  • Don't treat annotations as a lock. The specification says agents cannot rely only on what a site asserts about its tools, and the explainer still lists a way for a tool to ask the user for confirmation as an open question. Annotations are a signal. The guarantee has to come from your checkout.
  • Validate in code, not only in the schema. The explainer recommends validating "strictly in code, loosely in schema": check inputs, authorization and preconditions inside execute, and return a clear error the agent can act on. Your server should apply the same checks it applies to a human's request, since the tool runs with the shopper's session.
  • Limit the rate. Put cart and stock endpoints behind the same rate limits you use for people, plus a per-session cap on cart writes. When a limit is hit, the explainer suggests returning an informative error or telling the agent to ask the user to finish in the page.
  • Return data, not instructions. If a tool returns reviews or other text you didn't write, set untrustedContentHint. Chrome's security guidance ties this hint to indirect prompt injection and suggests short outputs: about 1,500 characters per tool result and 500 per description.

How to test it

  1. Turn on the flag chrome://flags/#enable-webmcp-testing for local development, or register for the origin trial to test on your live domain.
  2. Open DevTools, Application, WebMCP. The pane lists available tools as an agent sees them, logs every call with its input and output, and lets you run a tool by hand with Run tool. Schema violations show up in the output pane.
  3. Call tools from the console with document.modelContext.executeTool() to test logic without any model in the loop.
  4. Test with a model. Chrome's Model Context Tool Inspector extension sends natural language prompts to a model that can call your tools. Check the failure modes Chrome lists: the wrong tool, the right tools in the wrong order, or the right tool with the wrong arguments (shoes instead of a t-shirt).
  5. Test the limits on purpose: an unknown SKU, a quantity of 50, a sold-out variant, repeated calls in a few seconds. Each should return a clear error and leave the cart unchanged.
  6. Keep the page path working. Most agents today still read and click. A tool should never be the only way to do something.

The bottom line

WebMCP gives agents a way to do what your page already does without guessing at buttons. For most stores, the sensible first step is small: one read-only stock tool and one add-to-cart tool, tested in Chrome's origin trial, with orders and payment left firmly on your checkout page. It is a draft in a trial, so build it as an experiment you can remove, not as a dependency.

Specoria's agent simulator lists the WebMCP tools registered on the pages it visits and adds safety notes, without calling them, and shows step by step where agents stop on your store whether or not it exposes tools. Start with a free readiness test.

Sources