WebMCP is an experimental browser API that lets websites expose structured tools to AI agents through document.modelContext. Learn how it works, its security boundaries, browser support, and how it differs from MCP.
Why this matters #
WebMCP is a Draft Community Group Report from the W3C Web Machine Learning Community Group, not a formal W3C standard. Its imperative API lets pages register JavaScript tools through document.modelContext.registerTool(). Chrome's origin trial also implements a declarative API that turns annotated HTML forms into tools, although that part of the normative draft remains incomplete. WebMCP runs in a live browser context and is separate from the server-oriented Model Context Protocol.
WebMCP is an experimental browser API that lets a website expose structured tools to AI agents through document.modelContext
. Instead of reverse-engineering a page from pixels, DOM structure, and click targets, an agent can discover named actions with typed inputs and invoke them through the browser.
The current specification is a Draft Community Group Report dated July 21, 2026. That status matters: WebMCP is a serious proposal with a Chrome origin trial, but it is not a finished W3C standard or a stable cross-browser feature.
The Problem WebMCP Tries to Solve #
A human can look at a search form, infer what it does, enter a query, and interpret the results. An AI agent has to reconstruct the same interaction from markup, accessibility data, screenshots, or browser automation. That reconstruction is brittle. A changed label, hidden control, or asynchronous state transition can break the flow.
WebMCP gives the page a second interface for the same capability:
- The human gets the normal visual interface.
- The agent gets a named tool, a description, a JSON Schema input contract, and a structured result.
- The website keeps its existing validation, authentication, and business logic.
This is progressive enhancement for agent interaction. The visual page remains the product; WebMCP adds a browser-mediated action surface.
How the Imperative API Works #
The imperative API registers a JavaScript tool on document.modelContext
:
if (document.modelContext) {
const controller = new AbortController();
await document.modelContext.registerTool(
{
name: 'search_posts',
title: 'Search posts',
description: 'Search published posts by keyword and return up to five matches.',
inputSchema: {
type: 'object',
properties: {
query: {
type: 'string',
description: 'The topic or phrase to search for.'
}
},
required: ['query']
},
annotations: {
readOnlyHint: true,
untrustedContentHint: false
},
async execute({ query }) {
return JSON.stringify(searchLocalIndex(query).slice(0, 5));
}
},
{ signal: controller.signal }
);
// Abort when the tool should no longer be available.
// controller.abort();
}
The page controls the implementation. The browser controls discovery and invocation. The current draft defines getTools()
and a toolchange
event for in-page discovery. Chrome’s origin-trial documentation also exposes executeTool()
so an in-page agent can invoke a discovered tool.
Registration is dynamic. Passing an AbortSignal
lets the page remove a tool when its route, state, or component changes. That is safer than leaving an action registered after the corresponding interface has disappeared.
Cross-origin access is closed by default. A page must explicitly expose a tool to secure origins with the exposedTo
registration option, and a caller must request tools from those origins. Cross-origin iframes also require the tools
Permissions Policy.
The Declarative API Turns Forms Into Tools #
Chrome’s origin-trial documentation also defines a declarative path for HTML forms:
<form
toolname="createSupportRequest"
tooldescription="Submit a customer support request."
>
<label for="issue">What went wrong?</label>
<textarea
id="issue"
name="issue"
required
toolparamdescription="A concise description of the support issue."
></textarea>
<button type="submit">Send request</button>
</form>
The browser derives a tool schema from the form and its controls. When an agent invokes the tool, Chrome can focus the visible form and populate its fields, leaving the user to submit it. Developers can opt into automatic submission with toolautosubmit
, handle agent-triggered submissions through SubmitEvent.agentInvoked
, and return a result with respondWith()
.
There is an important standards nuance here. Chrome documents and demos the declarative API, but the normative declarative section in the July 21 Draft Community Group Report is still marked TODO. Implementation availability and specification completeness are not the same thing.
Try the interactive progressive-enhancement demo. Its accessible search form works in every modern browser, while its agent panel exposes the equivalent tool contract and simulates an invocation when the native API is unavailable.
Annotations Are Hints, Not Security Controls #
readOnlyHint
and untrustedContentHint
help an agent reason about a tool:
readOnlyHint: true
says the tool is intended not to change state.untrustedContentHint: true
says the output may contain user-generated or externally sourced content.
Neither field is enforced proof. A dishonest or buggy tool can claim to be read-only while changing data. A supposedly trusted output can still contain malicious instructions. The current specification explicitly identifies prompt injection, tool poisoning, output injection, intent misrepresentation, and privacy leakage as threat classes.
The right boundary is ordinary application security:
- Recheck authorization inside the operation.
- Validate inputs in code instead of trusting the schema alone.
- Keep tools narrow and expose the minimum data required.
- Require visible user review or confirmation for consequential actions.
- Treat authenticated read access as sensitive, even when it does not mutate data.
- Mark external and user-generated output as untrusted.
- Keep tool names, descriptions, parameters, and outputs concise.
WebMCP can execute within the user’s active browsing context. That is its main advantage and its main risk. Existing session state removes the need to create a second authentication system, but it does not grant an agent broader authority than the user should have in that moment.
What WebMCP Is Not #
WebMCP is easy to confuse with adjacent agent infrastructure. Four boundaries keep the concept precise:
It is not an MCP server. WebMCP is a browser API. MCP is a JSON-RPC protocol with stdio and Streamable HTTP transports.It is not a static discovery manifest. The current proposal discovers tools from a live browsing context./.well-known/webmcp
is not defined by the draft.It is not a headless website API. The browser must visit the page for its tools to become available.It is not a safety layer. Tool metadata helps an agent choose, but the website still owns authorization, validation, consent, and error handling.
A product can use WebMCP and MCP together. For example, the browser surface can expose actions tied to the current page while an MCP server exposes account-wide or background operations. They are complementary interfaces with different lifecycles and trust boundaries.
WebMCP vs. MCP #
| WebMCP | Model Context Protocol | |
|---|---|---|
| Interface | Browser API on document.modelContext |
JSON-RPC protocol |
| Runtime | A live page and browsing context | A separate local or remote server |
| Discovery | The client visits a page and reads available tools | The client connects to a configured server |
| Transport | Browser-mediated, no separate protocol transport required | stdio or Streamable HTTP |
| Authentication | Uses the web application’s active session and controls | The server defines its authentication model |
| Best fit | Page-scoped actions and visible user flows | Background, account-wide, local, or service-level tools |
The API name is another useful date marker. Early previews and polyfills used navigator.modelContext
. The current draft defines document.modelContext
, and Chrome says the navigator surface is deprecated in Chrome 150. Tutorials using the older name target an earlier implementation.
What I Learned Implementing WebMCP on chudi.dev #
My first chudi.dev implementation used the @mcp-b/global
polyfill and its navigator.modelContext
surface. It registered three read-only tools for searching posts, listing posts, and returning author context. I also added a separate /.well-known/webmcp
manifest backed by HTTP routes.
That experiment exposed a distinction my original article blurred: the browser tools and the HTTP manifest are two independent action surfaces. The former follows an early WebMCP implementation. The latter is custom server-side discovery. Calling both “WebMCP” makes the architecture sound more standardized than it is.
It also showed why version labels belong beside experimental code. The older WebMCP + SvelteKit implementation guide is evidence of a working polyfill integration, not evidence that its exact API matches the July 21 draft. A current implementation should use a compatibility adapter or migrate to document.modelContext
, then test both the enhanced path and the normal site with WebMCP unavailable.
Browser Support and Production Readiness #
Chrome documents a WebMCP origin trial beginning in Chrome 149. Developers can also test locally by enabling chrome://flags/#enable-webmcp-testing
and use the WebMCP Inspector extension to inspect registered tools. Chrome’s current documentation says the browser must visit the website directly to discover its tools and that headless mode is not supported.
That is enough for experiments, demos, and controlled trials. It is not enough to make WebMCP a required dependency for a public product. Production code should:
- Feature-detect
document.modelContext
. - Preserve the complete human workflow without WebMCP.
- Register only tools that are valid for the current page state.
- Remove stale tools with
AbortSignal
. - Validate and authorize every call inside the implementation.
- Test expected tasks, incorrect tool selection, malformed input, cancellation, and sensitive-data exposure.
- Track the dated specification and Chrome implementation separately.
Why WebMCP Matters #
Structured content helps an AI system understand a website. Structured tools help an agent use it. That difference matters for search, support, scheduling, account management, and commerce flows where a wrong click can cost more than a poor summary.
In Agent Commerce Readiness, I argued that machine-readable checkout infrastructure reduces the need for agents to guess through a purchase flow. WebMCP applies the same principle to general web interaction. It also extends the logic behind answer engine optimization: make meaning explicit where interpretation is expensive.
The practical stance is neither “ignore it until standardization” nor “rebuild around it now.” Use WebMCP as an optional enhancement, keep its authority narrow, test it against real tasks, and label every implementation with the browser and draft version it targets.
· Frequently asked
FAQ #
Is WebMCP a W3C standard yet?
No. The current document is a Draft Community Group Report published by the W3C Web Machine Learning Community Group. It is not on the formal W3C Recommendation track and can still change substantially.
Does WebMCP require MCP?
No. A WebMCP tool is registered and executed in a browser context. It does not require an MCP server or MCP transport. A browser or extension may adapt WebMCP tools for an MCP-speaking agent, but that bridge is an implementation choice rather than a WebMCP requirement.
Which browsers support WebMCP?
WebMCP is not a stable cross-browser feature. Chrome documents an origin trial beginning in Chrome 149 and a local testing flag. Chrome 150 deprecates navigator.modelContext in favor of document.modelContext. Production sites should feature-detect the API and preserve their normal human interface as the fallback.
Is /.well-known/webmcp part of the WebMCP specification?
No. The current proposal discovers tools from a page's live browsing context. The explainer records static manifest discovery as an alternative that was considered, not as part of the current API. A site may publish its own manifest or HTTP tool layer, but it should label that layer separately.
How is a WebMCP tool different from a regular JavaScript function?
A registered tool includes a name, natural-language description, JSON Schema input definition, execution callback, and optional annotations. That metadata makes the action discoverable to an agent. The metadata is descriptive, however, and the tool implementation must still enforce authorization, validation, and business rules.
· Sources & further reading
Sources & Further Reading #
Sources
WebMCP Draft Community Group Report webmachinelearning.github.ioPrimary source for the current API, draft status, permissions model, and security considerations.Get started with WebMCP developer.chrome.comOfficial hub for Chrome's trial, both APIs, security guidance, testing, and browser limitations.Model Context Protocol transports modelcontextprotocol.ioPrimary source for the JSON-RPC, stdio, and Streamable HTTP comparison with WebMCP.
Further reading
I Built a Private MCP Server to Give Claude Memory Across Sessions. Here Is What Broke. /blog/mcp-server-persistent-memory-claudeI shipped a private MCP server bridging my knowledge base into claude.ai via OAuth 2.1: the architecture, two bugs the smoke test missed, and the isolation pattern.I Added WebMCP to SvelteKit: 90 Min, 3 Files. /blog/webmcp-sveltekit-implementationBuild WebMCP into SvelteKit apps using navigator.modelContext. Learn polyfill setup, tool schemas, and verification in 2026.How to Use Claude Opus 5: A Failure-Tested Guide /blog/how-to-use-claude-opus-5Learn how to use Claude Opus 5 with failure replay, effort sweeps, deterministic checks, and a scheduled regression worker.Agent Commerce Readiness: Preparing for ACP, Shared Payment Tokens, and Link Wallets /blog/agent-commerce-readiness-acp-payment-tokens-link-walletsStripe shipped agent commerce in April 2026. Most sites are not ready to accept transactions from AI agents. The four surfaces operators need to add, the security model behind shared payment tokens, and a working receivable endpoint stub.The 95% Model Sometimes Lies About Finishing. Anthropic's System Card Documents Both. /blog/fable-5-system-card-capability-and-fabricationFable 5 hits 95.0% SWE-bench Verified. The same System Card documents fabricated status reports and unverbalized early-stops. Both halves matter.
What do you think? #
I post about this stuff on LinkedIn every day and the conversations there are great. If this post sparked a thought, I'd love to hear it.