WebMCP vs MCP: what's the difference?

The short answer

The Model Context Protocol (MCP) is a client–server protocol: an agent host connects to a server you run and calls its tools, reads its resources, and uses its prompts over JSON-RPC. WebMCP is a browser API: a web page registers tools with document.modelContext, and the user's agent — built into the browser or an extension — discovers and calls them in that page, in that user's session.

They share vocabulary on purpose. A WebMCP tool has a name, a description, a JSON Schema inputSchema, and annotations (readOnlyHint, consequentialHint, untrustedContentHint) that mirror MCP's tool annotations. What differs is everything around the tool: who hosts it, who calls it, under what identity, and what the trust boundary is.

Side by side

• Where the tool runs. MCP: on a server you deploy (stdio for local, streamable HTTP for remote). WebMCP: in the page's JavaScript, in the user's browser tab.
• Who is calling. MCP: an agent authenticated to your server with its own credentials or OAuth. WebMCP: the user's own agent, acting as the logged-in user, under the page's origin — no new auth surface.
• Discovery. MCP: the client lists tools with tools/list after connecting. WebMCP: the browser exposes registered tools via getTools(), and the toolchange event fires as the page registers or unregisters them.
• Scope and permissions. MCP: whatever the server allows. WebMCP: same-origin by default, extendable with exposedTo, gated by the tools Permissions Policy, secure contexts only.
• The user in the loop. MCP: the host decides when to confirm. WebMCP: declarative form tools keep the user pressing submit unless the page opts into toolautosubmit; annotations tell the agent when to confirm imperative calls.
• Results. MCP: structured content and resources. WebMCP: whatever execute() returns, stringified; for forms, a SubmitEvent.respondWith() payload or JSON-LD after navigation (per the declarative explainer).

When to use which

Use MCP when the capability lives behind your API and should be reachable without a browser: order lookups from a support agent, catalog search from a shopping assistant, anything you'd already expose to a partner. Commerce protocols like UCP (Universal Commerce Protocol) build on MCP for exactly this — catalog, cart, and checkout as server-side tools.

Use WebMCP when the capability *is* the page: the user is on your site, logged in, halfway through a flow, and their agent should be able to help without scraping the DOM. Filters, comparisons, adding the currently viewed variant to the cart, applying a promo code, booking the slot on screen. You don't need a server, an auth flow, or a new session — you need the page to describe what it can already do.

Most sites end up with both, and the boundaries are natural: MCP for the headless surface, WebMCP for the on-page surface. What they must share is the vocabulary. If your MCP server has search_catalog and your page registers searchProducts, an agent that sees both will treat them as different capabilities — the inspector flags naming drift like that because it is the most common selection error in practice.

What carries over from MCP experience

Everything you know about writing good MCP tools applies: task-shaped names, descriptions that say when and when not, closed schemas with described parameters, annotations that tell the truth about side effects. The failure modes are identical too — over-broad tools, near-duplicate descriptions, instructions to the agent hiding in metadata. The WebMCP inspector grades those the same way an MCP tool review would.

Two things are new. First, lifecycle: a page changes state, so tools should come and go with it — register with an AbortSignal and abort when the UI moves on. Second, the browser is the trust boundary: the spec's security section covers tool poisoning, output injection, misrepresented intent, and privacy leakage through over-parameterization, and gives annotations and input limits as mitigations. Read it once; it changes how you design the schemas.

Related guides

• Writing WebMCP tool descriptions agents select correctly — The description is the only thing an agent reads before choosing. Here's what belongs in it — and what must not.
• WebMCP spec changes and what to update in your code — What moved, what was removed, what was added, and the one-line code change each one asks of you.