web-mcp

 # web-mcp **Decide whether your site should expose WebMCP tools to AI agents, design those tools safely, and refuse the claims about them that no evidence supports.** [](LICENSE) [](docs/sources.md) [](docs/sources.md) [](#use-it-with-any-agent) Works with any coding agent. It is Markdown, not a framework. Most sites should not build WebMCP tools yet. This tells you that, with reasons, and that is a successful run. If you do pass, it writes the tools with you: working code, framework wiring, and a verification loop. ## What WebMCP is, in plain terms WebMCP is a new browser capability that lets your website hand an AI agent a list of actions it can call directly, like `book_appointment` or `search_products`, instead of the agent squinting at a screenshot and clicking around like a person. The agent calls the action on your live page, using your visitor's own logged-in session. That is genuinely useful. It is also pre-standard, off by default in every browser, and has almost no real-world adoption yet. Both halves are true, and most writing about it only tells you one. ## What this does - **Decides whether you should build.** Four fit tests: real actions, action value, a reachable agent, and capacity to maintain an experimental API. Most sites fail at least two. - **Shapes the tools if you should.** Three or four tools on one high-value flow, not your whole site. - **Reviews them for safety.** The annotation contract, the two gates that silently disable everything, and tool output as a prompt-injection surface. - **Stops you overclaiming.** A three-rung claim ladder separating what Chrome documents, what one vendor benchmark measured, and what nobody has evidence for. - **Writes the tools if you pass.** Working `registerTool` code, seven annotated templates, framework wiring for vanilla, React, Vue, Angular and Next. - **Verifies them before you ship.** DevTools, evals, Lighthouse Agentic Browsing, and the two gate checks. - **Tells you what you can measure.** Which is less than you would hope. ## Why it exists Almost every WebMCP article currently in circulation makes at least one of these claims. All of them are wrong. | Circulating claim | Reality | |---|---| | It improves your rankings | No Google, Bing, or Microsoft statement links WebMCP to ranking in either direction | | This is where agent traffic lands | Chrome: *"Clients and browsers must visit a site directly to know if it has callable tools."* No discovery exists | | It increases conversion | Zero case studies. Zero A/B tests. Zero revenue data. From anyone | | Register with a directory to get found | Directories exist. No agent client is documented as reading them | | It uses 89% fewer tokens | A circulating figure with no published methodology | | Biggest shift in technical SEO since structured data | A practitioner's conditional speculation, quoted with the condition removed | This repo carries the sourced version of each, so you can say something accurate instead. ## What is actually true **Chrome's own words:** WebMCP improves *"efficiency, reliability, and task completion"* and is *"more reliable than actuation, which may have numerous steps and leaves each step open to interpretation by the agent."* **One vendor benchmark** measured agents completing tasks faster, cheaper, and with fewer tokens using WebMCP than by driving the screen. It has not been independently replicated, and the publisher sells agentic-commerce infrastructure without disclosing that in the repo. **Nobody has measured conversion.** If someone tells you otherwise, ask for the study. ## Use it with any agent The content is plain Markdown with no runtime dependency. Pick whichever entry point your tool reads. ```bash git clone https://github.com/AgriciDaniel/web-mcp.git ``` | Your tool | What to do | |---|---| | **Codex, Cursor, Copilot, Gemini CLI, opencode, Windsurf, Aider** | Point it at [`AGENTS.md`](AGENTS.md), or copy it to your project root | | **Claude Code** | `cp -r web-mcp/skills/webmcp ~/.claude/skills/` then `/webmcp` | | **ChatGPT, Claude.ai, any chat UI** | Paste [`AGENTS.md`](AGENTS.md) plus the one reference you need | | **Anything else** | Read [`references/`](skills/webmcp/references/) directly. It is documentation that happens to be agent-readable | No install, no package, no build step. Deleting the folder uninstalls it. ## Ask it things like ``` should we build webmcp tools for our booking flow design three tools for our checkout review this registerTool call <paste code> is this claim safe to publish <paste a draft post> what silently disables tool registration ``` ## What is in the box | Path | What it holds | |---|---| | `AGENTS.md` | Universal entry point. Any agent, any runtime | | `skills/webmcp/SKILL.md` | Claude Code skill wrapper around the same content | | `references/method.md` | Fit tests, tool scoping, claim adjudication, measurement plan | | `references/claims-and-maturity.md` | The claim ladder. Read this before publishing anything | | `references/api-reference.md` | Verified WebIDL, both gates, annotation contract, character budgets, Chrome's design rules | | `references/implement.md` | Authoring rules, budgets, error patterns, prepare-then-confirm | | `references/scaffold.md` | Gate pre-flight and per-framework wiring | | `references/verify.md` | DevTools, evals, Lighthouse, and what you cannot measure | | `references/trial.md` | Local flag, origin trial token, who can call your tools | | `references/ecosystem.md` | Which package is official, licence boundaries, naming traps | | `templates/` | Seven annotated, copy-paste tools including prepare-then-confirm | | `scripts/check-templates.sh` | Deterministic check: no deprecated accessor, all annotations set, signal threaded, names in budget | | `scripts/check-tools.mjs` | Executes the templates against a stub document and validates the real tool objects, schemas and budgets | | `evals/` | Five synthetic cases including a poor-fit refusal | | `docs/sources.md` | Every source, its fetch date, and its authority tier | ## Who this is for - **Marketers and founders** being asked whether to "make the site AI-ready" and wanting a real answer. - **Developers** who need the correct API surface, the two gates that fail silently, and the security guidance in one place. - **Anyone about to publish** something about WebMCP who would rather not be wrong in front of their audience. ## How the facts were checked Five parallel research agents verified every claim against primary sources on 2026-09-05. A three-lane adversarial audit re-checked the result on 2026-09-06 and found six errors, including one inverted fact and two of our own inferences presented as vendor guidance. All six were corrected. The corrections are documented in [CHANGELOG.md](CHANGELOG.md) rather than quietly overwritten. Sources are graded in three tiers: normative and first-party, first-party with a commercial interest, and independent practitioner evidence. See [docs/sources.md](docs/sources.md). Where the evidence runs out, it says `no data`. That happens more than you would expect for a technology this widely written about. ## Honest limitations - WebMCP is a **Draft Community Group Report**, not a W3C Standard and not on the standards track. - It is **off by default in every browser.** Chrome and Edge run origin trials. Chrome's ends 2026-11-17. - **WebKit has formally opposed it.** Mozilla is formally neutral. Neither has endorsed it. - **Only ChatGPT Work and Codex can call tools today**, in the ChatGPT desktop browser, gated to specific models, unavailable on Enterprise and Edu. Gemini in Chrome is not live. - **That client sees only imperative, top-level tools.** Declarative form tools are invisible to it. - The templates execute and produce valid tool objects, verified on every change. But no template has been run against a live agent in production, and the eval cases are defined rather than run. - Adoption is small. Real deployments exist, including a live Stripe checkout, but no major brand deployment has been verified. - The eval cases are **defined, not run.** No independent behavioural evaluation has been performed. ## Not affiliated with the WebMCP specification This is an independent readiness and review guide. It is not the standard, not published by the W3C Web Machine Learning Community Group, and not affiliated with Google or Chrome. The specification lives at [webmachinelearning/webmcp](https://github.com/webmachinelearning/webmcp). Chrome's documentation is at [developer.chrome.com/docs/ai/webmcp](https://developer.chrome.com/docs/ai/webmcp). Use those as the source of truth; use this to decide what to do about them. Also: `webmcp.dev` is **not** the standard. It serves a superseded 2025 library, and its disclaimer only exists on GitHub, not on the site. Do not link it. ## Re-verify by 2026-12-01 WebMCP moves weekly. One annotation in the current set was two days old when these sources were captured. Two pages of Chrome's own documentation are three months out of sync with each other. Treat an expired horizon as a blocker, not a warning. ## License MIT. See [LICENSE](LICENSE). Built by [Daniel Agrici](https://github.com/AgriciDaniel).