WebMCP · Lesson 1

The third side of the triangle

You know how an agent talks to a server (MCP) and how it drives a browser from outside (CDP). WebMCP is the missing edge: a web page handing its own tools to an agent — from the inside.

You've built two of the three ways an AI agent reaches into the world. MCP connects an agent to an external server over JSON-RPC. CDP lets an agent drive a browser from the outside, imperatively, over a debug socket. WebMCP is the third edge: the web page itself volunteers a set of tools, and an agent running in the browser calls them directly.chrome

The one-sentence mental model

WebMCP lets a page register tools on document.modelContext, and the browser hands those tools to an agent — so the agent calls a function instead of scraping the DOM or faking clicks.spec

1 · Same "tool", three different places

All three protocols share one idea you already own: a tool = a name + description + inputSchema + a handler. What differs is where the tool lives and who the host is.

MCP Agent
▼ JSON-RPC / HTTP
MCP Server
tools live here
CDP Agent
▼ raw WebSocket
Browser
agent drives it from outside
WebMCP Browser (host)
▲ ▼ JS API, same origin
Page Agent
tools live in the page
Same tool concept; the tool moves from a remote server (MCP), to "no tools — the agent pokes the browser" (CDP), to inside the page itself (WebMCP).
The shift that matters

In MCP the tools sit on a separate server you connect to. In WebMCP the tools sit on the page in front of you, and the browser is the host that mediates — there is no separate client process, no transport socket, no JSON-RPC. It's a JavaScript API call, in-process, same-origin.

2 · Both points of view (the whole track in one picture)

This track teaches WebMCP from both ends. Keep this loop in your head — the rest is detail.

① Website PoV — the author (Lesson 2) document.modelContext.registerTool({ name, description, inputSchema, execute })
▼ tool is now visible to agents on this page
② Browser — the host keeps the tool registry · validates input vs inputSchema · mediates trust
▼ agent asks: what can this page do?
③ Consumer PoV — the agent / inspector (Lesson 3) getTools() → sees the tool executeTool(name, input) → runs execute()
▲ result string flows back to the agent
Author registers → browser holds & guards → consumer discovers & calls. One page, one origin, one JS API — no socket in the middle.

3 · Why this exists

Today an agent that wants to "add this to the cart" or "filter to size medium" has to guess: read the DOM, find the right button, synthesize a click (that's the CDP world). It's brittle and it breaks when the page changes. WebMCP lets the site say, explicitly: here is add_to_cart(sku, qty), here is what it takes, call it. The page declares its capabilities instead of the agent reverse-engineering them.explainer

Status — this is young and moving

WebMCP is a W3C Community Group draft (authored by Microsoft + Google) in a Chrome origin trial as of Chrome 149. The API is mid-rename (navigator.modelContext → document.modelContext) and small details still shift. Learn the shape; verify specifics against the primary sources.spec

Check yourself

In WebMCP, where do the tools live?
Who is the "host" that mediates between page and agent in WebMCP?
Compared with MCP, what does WebMCP not use?
Primary source — read this next

The WebMCP guide on Chrome for Developers for the big picture and tooling, and the W3C WebMCP spec for the exact API. Skim both; we'll drive the API by hand in Lessons 2–3.