# WebMCP 101 Canonical: https://mudpie.ai/101/webmcp/ Updated: 2026-09-20 Curator: Ali Abouelatta (https://mudpie.ai/authors/ali-abouelatta/) 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. ## 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. ### [WebMCP Draft Community Group Report](https://webmachinelearning.github.io/webmcp/) Authority: [Brandon Walderman](https://mudpie.ai/authors/brandon-walderman/), [Khushal Sagar](https://mudpie.ai/authors/khushal-sagar/), [Dominic Farolino](https://mudpie.ai/authors/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. ### [WebMCP overview](https://developer.chrome.com/docs/ai/webmcp) Authority: [Alexandra Klepper](https://mudpie.ai/authors/alexandra-klepper/) **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. ### [When to use WebMCP and MCP](https://developer.chrome.com/docs/ai/webmcp/compare-mcp) Authority: [Alexandra Klepper](https://mudpie.ai/authors/alexandra-klepper/) **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. ### [WebMCP imperative API](https://developer.chrome.com/docs/ai/webmcp/imperative-api) Authority: [Alexandra Klepper](https://mudpie.ai/authors/alexandra-klepper/) **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. ### [WebMCP declarative API](https://developer.chrome.com/docs/ai/webmcp/declarative-api) Authority: [Alexandra Klepper](https://mudpie.ai/authors/alexandra-klepper/) **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. ## 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. ### [WebMCP best practices](https://developer.chrome.com/docs/ai/webmcp/best-practices) Authority: [Alexandra Klepper](https://mudpie.ai/authors/alexandra-klepper/) **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. ### [Build your user's agentic workflows with WebMCP tools](https://developer.chrome.com/docs/ai/webmcp/build-tools) Authority: [Alexandra Klepper](https://mudpie.ai/authors/alexandra-klepper/) **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. ### [Security and human in the loop](https://docs.mcp-b.ai/explanation/design/security-and-human-in-the-loop) Authority: [Miguel Piedrafita](https://mudpie.ai/authors/miguel-piedrafita/) **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. ### [Tool lifecycle and context replacement](https://docs.mcp-b.ai/explanation/architecture/tool-lifecycle-and-context-replacement) Authority: [Miguel Piedrafita](https://mudpie.ai/authors/miguel-piedrafita/) **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. ### [Spec status and limitations](https://docs.mcp-b.ai/explanation/design/spec-status-and-limitations) Authority: [Miguel Piedrafita](https://mudpie.ai/authors/miguel-piedrafita/) **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. ## 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. ### [Join the WebMCP origin trial](https://developer.chrome.com/blog/ai-webmcp-origin-trial) Authority: [Alexandra Klepper](https://mudpie.ai/authors/alexandra-klepper/) **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. ### [WebMCP in OpenAI developer documentation](https://developers.openai.com/codex/webmcp) Authority: [OpenAI](https://mudpie.ai/authors/openai/) **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. ### [Using Site Tools in the ChatGPT desktop app](https://help.openai.com/en/articles/20001423-using-site-tools-in-the-chatgpt-desktop-app) Authority: [OpenAI](https://mudpie.ai/authors/openai/) **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. ### [What is WebMCP?](https://docs.mcp-b.ai/explanation/what-is-webmcp) Authority: [Miguel Piedrafita](https://mudpie.ai/authors/miguel-piedrafita/) **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. ### [Choose your WebMCP runtime](https://docs.mcp-b.ai/how-to/choose-runtime) Authority: [Miguel Piedrafita](https://mudpie.ai/authors/miguel-piedrafita/) **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.