Without WebMCPGuess from the interface
- 01Read the visible page
- 02Find what looks clickable
- 03Click and inspect again
Useful, but sensitive to layout, labels, and page changes.
A practical guide
What is WebMCP?
Buttons are made for eyes and hands. Tools carry meaning: what an action does, which input it accepts, and what came back. That makes browser agents more reliable while keeping the person and the page in the loop.
doessearch_hotels
accepts{ city: "Paris" }
returns12 hotels
Same page
12 hotels shown
01 · The shift
The browser stops guessing and starts using meaning.
Without WebMCP, an agent often has to interpret pixels, hunt for controls, and hope the page changed as expected. With WebMCP, the website publishes a small set of named actions with defined inputs and results.
With WebMCPCall an explicit capability
- 01Discover
search_hotels - 02Send
{ city: "Paris" } - 03Receive a defined result
The same website remains visible. The path through it becomes legible to an agent.
02 · Anatomy of a tool
Five small pieces turn page logic into a capability.
A tool is a contract between the website and the agent. It says what the action is for, what data it accepts, which page function will run, and what the agent receives afterward.
nameA stable identifiersearch_hotelsdescriptionWhen the agent should use itFind available hotels in a cityinputSchemaThe accepted structured input{ city: string }executeThe real page logicsearchHotels(city)resultWhat came back12 matching hotels03 · The lifecycle
The page, browser, and agent each have one job.
- 01
Register
The page publishes a focused tool.
- 02
Discover
The browser exposes it to the agent.
- 03
Invoke
The agent supplies structured arguments.
- 04
Execute
The browser calls the page function.
- 05
Respond
The page updates and returns a result.
The browser is the mediator.
The agent does not receive arbitrary access to the page. It discovers and calls the tools that the website deliberately registers.
04 · Build it yourself
Connect one existing action to registerTool().
If your page already searches, saves, books, edits, or exports, most of the product logic already exists. The best first tool reuses that same function and keeps its result visible in the interface.
const controller = new AbortController();
async function registerHotelTool() {
if (!document.modelContext?.registerTool) return;
await document.modelContext.registerTool({
name: "search_hotels",
description: "Find available hotels in a city",
inputSchema: {
type: "object",
properties: {
city: {
type: "string",
description: "City to search"
}
},
required: ["city"]
},
async execute({ city }) {
const hotels = await searchHotels(city.trim());
renderHotels(hotels); // Update the real page.
return {
content: [{
type: "text",
text: `${hotels.length} hotels found`
}]
};
}
}, { signal: controller.signal });
}
registerHotelTool();
// When this view is removed:
// controller.abort();05 · Two paths
Register application logic today. Let forms describe themselves tomorrow.
The imperative API is the clearest route for custom application behavior. A declarative form API is also being designed so standard HTML can expose meaning with less JavaScript.
Imperative tools
Register a JavaScript function with a name, description, schema, and execution callback.
document.modelContext.registerTool({ … })
Declarative forms
Add tool meaning to a real form while preserving its familiar browser behavior.
<form toolname="search-cars" …>
WebMCP is an evolving web-platform draft. Names and behavior may change; check the current specification before shipping.
06 · Real patterns
The useful unit is not “use this website.” It is one clear job.
The gallery shows the same idea across very different products: expose narrow capabilities, keep the real product visible, and let several tools form a larger workflow.
Commerce
PieterPost
Prepare real mail as a sequence of understandable steps.
- upload asset
- prepare postcard
- create payment link
Media
Webroom
Turn precise editing operations into tools while the canvas stays visible.
- crop image
- remove background
- export result
Productivity
FlatWrite
Let an agent edit, render, share, and export the same open document.
- update document
- render preview
- export PDF
07 · Trust by design
Read freely. Prepare visibly. Confirm consequences.
A good tool surface reflects the risk of the action. Searching can run immediately. A purchase, booking, deletion, or message may need a preview or an explicit human confirmation before it becomes final.
Search, inspect, compare
Draft, calculate, preview
Pay, send, book, delete
- 01
Expose less
Prefer a few narrow tools over one vague action with broad reach.
- 02
Validate twice
Use a strict schema, then validate important assumptions again inside the handler.
- 03
Return facts
Say what actually happened. Do not report success before the underlying action succeeds.
- 04
Keep people oriented
Show previews, progress, results, and failures in the normal interface.
08 · Why it matters
One product can serve people and agents without becoming two products.
Traditional APIs live beside the website. WebMCP adds a semantic surface inside the live page, connected to its current state, signed-in session, and visible interface. The page remains the shared place where the person, agent, and product meet.
Less brittle
Agents use named capabilities instead of depending on the position of a button.
More transparent
The real page can display the inputs, progress, and outcome of a tool call.
Closer to the product
Tools reuse the same functions, permissions, and state as the human interface.
09 · Common questions
The short answers.
Does WebMCP replace a normal API?
No. Server APIs remain useful for system-to-system integration. WebMCP gives agents a structured surface inside a live website and can reuse page state and client-side logic.
Does an agent receive access to the entire page?
No. The website chooses the tools it registers. The browser mediates discovery and invocation.
What happens in a browser without WebMCP?
Nothing should break. Feature-detect the API and keep the normal human interface as the reliable fallback.
Is the specification finished?
Not yet. WebMCP is an active draft. The imperative model is concrete, while parts such as declarative forms are still evolving.
What should I build first?
Choose one useful, bounded action that already works in your page: search a catalogue, save a draft, render a preview, or export a file.
Start small
Give one existing page action a clear name, a narrow input, and an honest result.
That is enough to make your first part of the web understandable to an agent.