Tools, Not Clicks: make any website agent-ready with WebMCP

An agent trying to buy something on your site today takes a screenshot, guesses which rectangle is the button, clicks, screenshots again, and hopes. WebMCP — the W3C standard built by Google and Microsoft — replaces that with typed tools your page registers and your own code executes, so the UI stays in sync with whatever the agent just did.

This is the retrofit procedure for a site that already exists.

It starts by correcting the mistake almost every article makes. The API is document.modelContext, not navigator.modelContext. Write the wrong one and you get undefined, conclude the browser lacks support, and ship nothing.

What it covers. Inventorying actions rather than pages. Grouping tools by page state so the always-on set stays small enough that a model still picks correctly. The exact registerTool signature, the AbortSignal lifecycle, the result shape, and what throws InvalidStateError. Naming that distinguishes doing from starting. Descriptions written as routing decisions. Errors written as instructions the model can retry from.

The security chapter is the part most implementations skip. untrustedContentHint on anything returning text other people wrote, because a seller can put "ignore previous instructions" in a product description. consequentialHint on anything that spends or publishes. And a list of what should never become a tool at all.

Two runnable scripts. A drop-in runtime that detects the API on either surface, handles Permissions-Policy rejection, and mirrors every tool onto the page so agents that cannot speak WebMCP yet can still call them today. And a headless-Chrome probe that injects a spec-shaped document.modelContext before your bundle boots — the only way to verify the native path, since stable Chrome does not expose the API and the testing flag has no documented command-line name.

Plus a linter that reads a tool inventory and fails CI on empty descriptions, duplicate names, undescribed parameters, a missing consequentialHint on something that clearly spends money, and a tool count past the point where selection accuracy falls over.

Written from a production WebMCP integration, not from the spec alone. Every browser support claim, error condition and API signature was verified against the W3C explainer and Chrome's own documentation rather than repeated from secondary sources.