How to Add WebMCP Tools to Your Website
How a site owner adds WebMCP tools as of 19 November 2026: origin trial tokens, the testing flag, document.modelContext.registerTool, annotations, the Permissions Policy tools feature, security risks, feature detection and which flows to expose.
- WebMCP lets a page register JavaScript tools through document.modelContext.registerTool(tool, options), but as of 19 November 2026 the specification is a Draft Community Group Report, not a W3C Standard.
- blink-dev approved a WebMCP experiment for M149 to M156 inclusive on 18 May 2026 and the Chrome origin trial opened in Chrome 149, while Edge lists its trial with an expiry of 30 March 2027, so production use means trial tokens, not general availability.
- A WebMCP tool is unregistered by aborting the AbortSignal passed in registerTool options, because the specification defines no unregisterTool method.
- A site can switch WebMCP off for a document and its frames with the response header Permissions-Policy: tools=(), which the specification says is enforced before page scripts run.
- The WebMCP specification warns that nothing guarantees a tool's declared intent matches its behaviour, so a site should make each description match exactly what execute does.
A site owner adds WebMCP tools by calling document.modelContext.registerTool() from page JavaScript, on an HTTPS page, in a browser that has the feature enabled. As of 19 November 2026 that means an origin trial or a local flag, because the specification is a Draft Community Group Report from the W3C Web Machine Learning Community Group, not a W3C Standard. The pillar frames whether a pilot is worth it, and the WebMCP reference holds the contract. This article is the sequence: how to turn it on, what to register, what to lock down and what not to expose.
Among browsers, only Chrome and Edge run WebMCP as of 19 November 2026, both through origin trials (an opt-in mechanism, so by our reading neither turns it on by default); ChatGPT Desktop is a listed agent client, not a browser. The table uses the WebMCP implementation-status page and the vendor pages, all read on that date.
| Client | State on 19 November 2026 | Source |
|---|---|---|
| Chrome | Origin trial opened in Chrome 149; blink-dev approved an experiment for "M149 to M156 inclusive" on 18 May 2026 | blink-dev intent, Chrome blog of 9 June 2026 |
| Edge | Origin trial live in Edge 150; trial listed with expiry 30 March 2027 | Edge origin-trial page, implementation-status |
| Brave | Leo AI chat support listed for Brave 1.102.2, expected 5 January 2027, so not in a stable release yet | implementation-status, brave-browser#55232 |
| ChatGPT Desktop | Listed as "Supported"; an agent client, not a browser | implementation-status |
| Firefox, Safari | No status; standards-position threads only | mozilla/standards-positions#1412, WebKit/standards-positions#670 |
No primary source we read confirms a general-availability milestone for Chrome, so do not plan a launch date around one. The older corpus entry of 9 September 2026 describes Brave as having experimental support; the implementation-status page now shows it as pending. For the wider product picture see the agentic browsers reference.
Sign up for each vendor's trial and serve that vendor's token on your pages (the general origin-trial mechanism, not a WebMCP-specific instruction), or enable the about:flags#enable-webmcp-testing flag for local development. The Chrome blog of 9 June 2026 says "In Chrome 149, you can sign up for the WebMCP origin trial." The Edge trial page says the trial allows sites to register tools for use by agents hosted by the site or in Chrome.
Origin-trial tokens are per browser vendor, so a Chrome token does not enable Edge. That is the general origin-trial model as described in secondary guides, not a WebMCP-specific statement from a primary source. Budget for two registrations and two renewal dates. Trials expire, so a page must work when the token lapses.
You call registerTool(tool, options) with a tool object and an options object. The README (fetched 19 November 2026) says the tool has a name, a description, a JSON Schema inputSchema and an execute callback. The draft's ModelContextTool dictionary also lists title, outputSchema and annotations. The snippet is illustrative and uses only members from those sources; the tool and its endpoint are invented.
// Illustrative only: names and the /api/stock endpoint are placeholders.
if ('modelContext' in document) {
const controller = new AbortController();
try {
document.modelContext.registerTool(
{
name: 'check_stock',
title: 'Check stock',
description: 'Returns whether a product SKU is in stock. Does not change anything.',
inputSchema: {
type: 'object',
properties: { sku: { type: 'string' } },
required: ['sku'],
},
annotations: { readOnlyHint: true },
execute: async ({ sku }) => {
const res = await fetch('/api/stock?sku=' + encodeURIComponent(sku));
return await res.json();
},
},
{ signal: controller.signal },
).catch(() => {
// registerTool returns a promise that rejects (NotAllowedError) if a Permissions Policy blocks the feature; keep the normal UI.
});
} catch (err) {
// Synchronous errors, for example a malformed tool object; keep the normal UI.
}
}
The options also take exposedTo, a list of cross-origin origins the tool is shared with; the README documents that member, so confirm it against the current draft before relying on it. The README also documents getTools(), executeTool() and a toolchange event.
You abort the signal you passed in the options, because there is no unregisterTool method. The 13 November 2026 draft defines registerTool, getTools and executeTool only. In the snippet above, controller.abort() removes check_stock. Tie that call to the state that makes a tool valid, for example sign-out or leaving a checkout step, so an agent never sees a tool the page can no longer honour.
The annotations are hints to the agent client, not enforcement. The draft's ToolAnnotations list readOnlyHint, untrustedContentHint, consequentialHint and debugging. Section 6.4.4 says untrustedContentHint signals that a payload requires heightened security handling; output that includes user-generated content is one example. Section 6.4.5 says consequentialHint signals a consequential action so agents can require user confirmation, for example before a money transfer.
Set them honestly, because a client that ignores them gives you no protection. Whether a given agent honours them is a property of that client, and we found no published list.
The Permissions Policy feature tools controls it, with a default allowlist of 'self'. It gates registerTool(), getTools() and executeTool(). A cross-origin iframe needs allow="tools" on its frame element before its scripts can register tools. To opt out entirely, section 6.4.1 says to deliver the header below, which makes the feature unavailable to the document and its descendant frames before page scripts run, including injected or compromised scripts.
# Response header value to add in your own server or CDN config (illustrative)
Permissions-Policy: tools=()
To confirm it on your own domain, request a page with curl -sI and look for that header.
Pair this with the other site-side mechanism, Web Bot Auth: signing says who is calling, while WebMCP says what a page offers (our inference).
Four risks follow from the draft's section 6.3, and exposure makes each one your site's problem. The prompt-injection mechanics are in prompt injection against browser agents, and the checklists are in the agentic security checklist and prompt injection design patterns.
- Tool poisoning. Hostile text in tool metadata, such as a description written by a third party, steers the agent.
- Output injection. Return values that include user-generated content, such as reviews, can carry instructions. That is the case
untrustedContentHintexists for. - Implementation as target. The agent's path through a tool may be validated differently from the UI path, so an input you would block in a form may pass through
execute. - Misrepresented intent. Section 6.3.2 says "There is no guarantee that a WebMCP tool's declared intent matches its actual behavior." Its example is a tool described as "finalizing" a cart that actually completes a purchase.
Section 6.4.2 gives tool names a nominal 128-character limit and says other input limits are still under evaluation (Issue #73). It says the name restriction "would not fully solve prompt injection attacks". Validate every argument server-side as you would any public endpoint.
Check for document.modelContext before registering and make the page fully usable without it. The check in the snippet above does that: when the property is missing (on an unsupported browser, or on plain HTTP because the interface is [SecureContext]), nothing is registered. If the feature is disabled by tools=() or a trial token has lapsed, registration may fail instead: the promise registerTool() returns rejects, which is why the call has a .catch() (and sits in a try/catch for synchronous errors) and the normal UI remains. Do not branch your layout on it.
Do not rely on the declarative route. The README says a form-based API is being explored, and the explainer (fetched 19 November 2026) proposes attributes (toolname, tooldescription, toolautosubmit, toolparamdescription) while marking its schema algorithms "TBD". It says "Chromium is implementing a loose version of this", so treat it as a prototype. Note that toolautosubmit would let an agent submit without the user checking first.
Expose read-only flows first, such as search, availability and order status, then add consequential ones only behind explicit confirmation. This is ChangeGamer's inference, not a published recommendation. Read-only tools carry a readOnlyHint and do the least damage if misused, and a tool that changes state should carry consequentialHint, so a client can ask the person first. Leave out flows where the cost of a wrong call is large and you cannot verify the caller. The README treats confirmation prompting as an open design question, so do not assume the client will do it for you.
ChangeGamer registers none, as verified in the repository on 19 November 2026. The string modelContext appears only in content files, with no registration in worker/ or public/. Its _headers file sends Permissions-Policy: geolocation=(), camera=(), microphone=(), browsing-topics=() and omits tools, so the 'self' default applies.
ChangeGamer's backlog deferred WebMCP on 16 September 2026 as "not-yet-honest", with one precondition: someone must decide that shipping browser-side tools justifies the extra JavaScript, given that the site's own position is that agents should consume its Markdown and JSON variants instead of driving the DOM. Some third-party guides report that the API moved from navigator.modelContext to document.modelContext in mid-2026; that is a secondary report only, but it shows how quickly API naming goes stale in a draft.
Frequently asked questions
- Does WebMCP work in Firefox or Safari?
- No status exists for either as of 19 November 2026. The WebMCP implementation-status page lists only a standards-position thread for Firefox (mozilla/standards-positions#1412) and one for Safari (WebKit/standards-positions#670), so a site must treat both as having no support.
- Is the HTML form-based declarative WebMCP API available?
- Not as part of the specification. The WebMCP README (fetched 19 November 2026) says a declarative form-based API is being explored and is not part of the specification at this time. A separate explainer proposes attributes such as toolname and tooldescription, but its schema algorithms are marked TBD.
- Does a WebMCP tool need HTTPS?
- Yes. The WebMCP interface is marked [SecureContext] in the draft specification of 13 November 2026, so document.modelContext exists only on HTTPS pages and plain HTTP pages must fall back to ordinary interaction.
- Can a WebMCP tool run without a user watching?
- Partly. The WebMCP README lists human-in-the-loop workflows as the goal but says tools can also be used for task completion in headless scenarios; fully autonomous workflows with no browser UI are a non-goal, and the README says user prompting and elicitation is an open question that has not been designed yet.
This guide is free and stays free. The reference corpus behind it — machine-readable contracts, verified primary sources, continuously refreshed — is the paid product: a €5 starter key unlocks every premium reference for one agent via API; a €25 corpus license delivers the full corpus as RAG / fine-tuning data with an explicit AI-use grant; the €150 enterprise license adds commercial redistribution rights.