What Is WebMCP? A Practical Guide to Agent-Ready Websites

Watching an AI agent click through a website is oddly satisfying. It is also slow.

The agent has to inspect the page, decide which button probably does what, type into fields, wait for the interface to change, and inspect it again. A small redesign can break the whole sequence.

That is the problem WebMCP is trying to solve.

WebMCP is a proposed browser API that lets a page publish a set of structured tools for AI agents. Instead of guessing that a purple button means "render model," an agent can discover a tool named render_model, read its description and JSON Schema, and call it with valid arguments.

OpenAI showed the idea in its short video, Build agent-ready sites with WebMCP. Codex opens a 3D modeling studio, adds shapes, changes the model, and captures views from different angles. The page still works as a visual application for the person watching. Codex gets a separate, structured way to operate it.

What the page exposes

An imperative WebMCP tool is a JavaScript object with a few important parts:

• a stable name
• a plain description of the action
• a JSON Schema for the inputs
• an execute function that calls the page's existing logic
• optional annotations, such as whether the action is read-only

The page registers that object through document.modelContext.registerTool(). A compatible browser agent can then discover and invoke it.

The basic lifecycle is short:

1. The page registers the tools that make sense in its current state.
2. The agent asks the browser which tools are available.
3. The agent selects one and sends structured arguments.
4. The browser invokes the page's callback.
5. The callback updates the visible app and returns a compact result.

The browser sits between the agent and the page. The tool runs in the page, where it can reuse the same state and application code as the human interface.

JavaScript tools and annotated forms

WebMCP has two paths.

The imperative API is for actions backed by JavaScript. A design app might expose add_shape, set_material, and capture_view. A support dashboard might expose run_diagnostics.

The declarative API is for ordinary HTML forms. A developer can add toolname, tooldescription, and parameter descriptions to a semantic form. The browser can turn those annotations into a tool while preserving the real labels, validation, focus behavior, and submit handler.

That distinction matters. A search form does not need to be rebuilt as a custom agent integration. A canvas command probably does.

Why this can beat visual clicking

Visual actuation is useful because it works on pages that were never designed for agents. It remains a good fallback. The cost is ambiguity.

A tool gives the agent information the pixels cannot:

• the exact action the site supports
• the required and optional inputs
• the types and allowed values for those inputs
• the current actions available in this page state
• a structured success or error response

The agent can skip several rounds of screenshot inspection and mouse movement. The site also keeps control of its own behavior instead of asking the agent to imitate every human gesture.

The advice from the OpenAI demo

The most useful line in the video is only four words: "Codex is your customer."

The point is practical. Tool descriptions are product copy for a model. Two tools with overlapping names may look different to a developer and identical to an agent. A schema can be valid but still encourage the wrong call. A tool set can expose every internal function and leave the agent less capable than it was with three clear actions.

OpenAI recommends using the tools with Codex, asking for feedback, trimming the set, and improving descriptions until the agent reaches the intended result efficiently. The demo even includes a feedback tool so Codex can report errors while it works.

What WebMCP is not

WebMCP does not give an agent unlimited access to a site. It does not replace login, server authorization, payment confirmation, or input validation. A JSON Schema helps the agent construct an input; it is not a security boundary.

It also does not remove the need for a usable interface. WebMCP is designed as a progressive enhancement. People and unsupported browsers should still be able to complete the task with the page's normal controls.

Nor is it a finished web standard. The WebMCP specification is a Community Group draft, not a W3C Standard or a document on the W3C Standards Track. The API is still under active discussion.

Browser support today

Chrome's WebMCP documentation describes an origin trial beginning with Chrome 149. Local development uses chrome://flags/#enable-webmcp-testing.

Chrome also documents several constraints. The API requires an origin-isolated document. The tools Permissions Policy defaults to self, which keeps cross-origin iframes out unless the page delegates access explicitly. Agents must visit a page before they can discover its tools.

Those limits are part of the design, not incidental setup details. WebMCP is meant for a browser workflow in which the person can see the page and remain involved.

A sensible first tool

Start with one action that already works in the interface. Give it a narrow name, a concrete description, and the smallest input schema that can complete the job. Update the visible page before returning. Unregister the tool when the action stops being valid.

Then try requests that are direct, vague, and slightly misleading. If the agent keeps choosing the right action for the right reason, the tool is useful. If it does not, fix the tool before adding another one.