101 · 15 canons

WebMCP

The browser contract, the product decisions behind useful page tools, and the compatibility layers you need while the standard is still moving.

TL;DR WebMCP is a proposed, page-scoped way for websites to expose structured tools to browser agents. Start with the draft, then use Chrome's implementation guidance and MCP-B's runtime docs to understand what works today.

Curated by Ali Abouelatta

Cofounder of Lazyweb (a16z Speedrun). Previously grew subscriptions and built native ads at Duolingo. Writes First1000 (90,000+ subscribers).

Voices in this 101

Reading path 1

Start with the browser contract

Read the proposal before the wrappers. These five sources define what a page can expose, who controls execution, and where WebMCP stops.

01
WebMCP Draft Community Group Report ↗
Brandon Walderman
Microsoft browser engineer and editor of the WebMCP draft.
With Khushal Sagar and Dominic Farolino
TL;DR
The proposed API gives an open page a model context where it can register, unregister and execute tools under browser permissions and user-agent control.
What you'll read
The normative shape of document.modelContext, imperative and declarative tools, execution, permissions policy, security considerations and explicit draft status.
02
WebMCP overview ↗
Alexandra Klepper
Author of Chrome for Developers' WebMCP documentation.
TL;DR
Chrome frames WebMCP as structured page actions that complement the DOM rather than asking an agent to infer every interaction from pixels and markup.
What you'll read
A product-level explanation of the API, availability, origin isolation, permissions policy and the current experiment path in Chrome.
03
When to use WebMCP and MCP ↗
Alexandra Klepper
Author of Chrome for Developers' WebMCP documentation.
TL;DR
WebMCP is ephemeral and bound to a live page; MCP is a persistent service connection. Many serious products need both layers.
What you'll read
A clean architecture comparison across lifecycle, state, discovery, connectivity, UI ownership and the cases where browser and server tools should coexist.
04
WebMCP imperative API ↗
Alexandra Klepper
Author of Chrome for Developers' WebMCP documentation.
TL;DR
The imperative API is the flexible path for dynamic tools whose schemas, availability and execution depend on live application state.
What you'll read
Concrete JavaScript for registration, input schemas, annotations, cancellation, execution and cross-origin iframe controls.
05
WebMCP declarative API ↗
Alexandra Klepper
Author of Chrome for Developers' WebMCP documentation.
TL;DR
Semantic HTML forms can become agent tools without moving the workflow out of the visible, accessible interface.
What you'll read
How tool attributes layer onto forms, how field descriptions become schemas, and where declarative progressive enhancement fits better than JavaScript registration.

Reading path 2

Design tools agents can finish

A registered tool is not a useful tool. This path is about naming, boundaries, recoverable failures, validation and visible user control.

06
WebMCP best practices ↗
Alexandra Klepper
Author of Chrome for Developers' WebMCP documentation.
TL;DR
Expose a small set of distinct, goal-shaped tools with strict validation, useful errors and evals; do not mirror every UI control.
What you'll read
A practical checklist for tool selection, descriptions, schemas, annotations, lifecycle, error recovery, telemetry and evaluation.
07
Build your user's agentic workflows with WebMCP tools ↗
Alexandra Klepper
Author of Chrome for Developers' WebMCP documentation.
TL;DR
Design from the user's end goal and initial state, role-play likely tool sequences, then test variance and recovery before publishing a tool.
What you'll read
A product workflow from goal definition to implementation and evals, with examples of stateful actions and graceful failures.
08
Security and human in the loop ↗
Miguel Piedrafita
Lead contributor to MCP-B and the WebMCP compatibility ecosystem.
TL;DR
Tool availability is not authorization. Sensitive actions still need application checks, clear previews and deliberate user confirmation.
What you'll read
Threat boundaries for browser tools, prompt injection, authentication, authorization and when an agent must hand control back to a person.
09
Tool lifecycle and context replacement ↗
Miguel Piedrafita
Lead contributor to MCP-B and the WebMCP compatibility ecosystem.
TL;DR
Page tools change as navigation and app state change, so the runtime must replace stale context instead of accumulating an ever-growing tool list.
What you'll read
How registrations follow page lifecycle, what makes context stale, and why deterministic replacement matters for agents and debugging.
10
Spec status and limitations ↗
Miguel Piedrafita
Lead contributor to MCP-B and the WebMCP compatibility ecosystem.
TL;DR
WebMCP is still a draft and implementations differ; ship compatibility deliberately and avoid presenting one runtime as universal browser support.
What you'll read
A candid map of standard status, implementation gaps, extensions and the decisions that should stay reversible.

Reading path 3

Make it work across hosts

The standards proposal, Chrome experiment, ChatGPT surface and MCP-B runtime are related but not interchangeable. Read these before promising coverage.

11
Join the WebMCP origin trial ↗
Alexandra Klepper
Author of Chrome for Developers' WebMCP documentation.
TL;DR
Chrome's origin trial is time-limited early access for testing the proposed API, not proof of a stable cross-browser baseline.
What you'll read
The Chrome version, enrollment path, token mechanics, experiment boundaries and the feedback loop behind the trial.
12
WebMCP in OpenAI developer documentation ↗
OpenAI
Builder of ChatGPT, Codex, Site Tools, workspace agents and ChatGPT ads.
TL;DR
ChatGPT Site Tools expose a subset of WebMCP, so support must be checked against OpenAI's documented surface rather than assumed from the draft.
What you'll read
The tool shape ChatGPT recognizes, current limitations, safety behavior and the gap between browser proposal and host implementation.
13
Using Site Tools in the ChatGPT desktop app ↗
OpenAI
Builder of ChatGPT, Codex, Site Tools, workspace agents and ChatGPT ads.
TL;DR
Site Tools depend on the current page, account and model, and the user remains in control when actions need review.
What you'll read
The actual ChatGPT product surface, availability limits, confirmations and the difference between the desktop browser and ordinary Chrome.
14
What is WebMCP? ↗
Miguel Piedrafita
Lead contributor to MCP-B and the WebMCP compatibility ecosystem.
TL;DR
MCP-B explains WebMCP as the browser-facing contract and positions its own packages as compatibility and runtime infrastructure around that contract.
What you'll read
A plain-language explanation of page tools, live browser state, progressive enhancement and the boundary between the proposal and the project.
15
Choose your WebMCP runtime ↗
Miguel Piedrafita
Lead contributor to MCP-B and the WebMCP compatibility ecosystem.
TL;DR
Choose native, polyfill, extension or relay based on the agent host and browser you must support; no one path is the default everywhere.
What you'll read
A decision guide for native APIs, client-side polyfills, browser extensions and desktop relays, including their trust and deployment tradeoffs.