Documentation.
Reference material lives in the public repo under docs/. Everything is also available offline in your local clone.
Topics
Local testing
Run the full cf-webmcp stack on your laptop in two terminals: a static origin server plus the Worker via wrangler dev. Hit every surface end to end.
Deployment
Full proxy vs route-only modes, Bot Management bypass headers, preflight collision detection, the deploy flow from wrangler login to verifying config hash.
Costs
Cloudflare Workers free vs paid tier math for small, medium, and high-traffic sites. R2 storage cost for the fallback widget. What to monitor and what to ignore.
Privacy
What the Worker logs (almost nothing by default), what travels to origin on executor fetches (no visitor cookies), and the GDPR posture for EU deployments.
Upgrade
Schema version handling, tool-name immutability rule, the config hash rotation pattern, and how to update the vendored widget pin without breaking deploys.
Limitations
SPA route changes, multi-language sitemaps, service worker collisions, non-UTF-8 origins, and other v1 edges with documented workarounds where applicable.
Customisation
Replace the /mcp landing page with your own HTML template. Lists the eight {{placeholder}} variables, the override flow, and a fully-worked example.
Browser support
Chrome 149 and later turn WebMCP on for sites that send an origin-trial token in an Origin-Trial header. Without a token, Chrome needs chrome://flags/#enable-webmcp-testing, for local development and testing. Also covers Cloudflare Kitesurf and Browser Run, the tools Permissions Policy, and how to check a page.
Form injection
Stamp declarative WebMCP attributes (toolname, tooldescription, toolparamdescription, toolautosubmit) onto existing forms at the edge from one [[forms]] TOML block.
AGENTS.md
Auto-publish /.well-known/agents.md describing your WebMCP surface to acting agents. Configurable canonical path, with 301 aliases for the two common variants.
API catalog
RFC 9727 Linkset at /.well-known/api-catalog pointing at the WebMCP manifest. Same four merge modes as the other discovery routes.
Agent Skills
SKILL.md at /.well-known/agent-skills/site/SKILL.md plus an index.json discovery wrapper at /.well-known/agent-skills/index.json (Cloudflare Agent Skills Discovery RFC v0.2.0) with a build-time SHA-256 digest. Case-variant 301 aliases for SKILLS.md, skill.md, skills.md.
ARD manifest
Agentic Resource Discovery (ARD v0.91) manifest at /.well-known/ard.json with one entry derived from the Agent Skill. The old path /.well-known/ai-catalog.json answers with a 301 to it. Synthesize, or merge into origin's manifest. Advertised via a robots.txt Agentmap directive, rel="ard", and llms.txt. Opt-in (ARD v0.91 is a proposal).
Reference
- TOML schema (JSON Schema) - drives VSCode autocomplete and validates your config.
- Templates - the three starters with comments.
- W3C WebMCP draft - the upstream spec.
This site eats its own dogfood
This site runs through cf-webmcp. Open /.well-known/webmcp to see the live tool catalogue. Open /mcp to pair a desktop MCP client. View source on any page and look for <link rel="webmcp"> in the <head>.
The HTTP Link header is the pre-parse equivalent of the link tag. Every response carries it, so an agent that only does a HEAD request can still find the manifest:
curl -I https://webmcp.basgr.com/
# ...
# Link: <https://webmcp.basgr.com/.well-known/webmcp>; rel="webmcp"