Docs

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 seven {{placeholder}} variables, the override flow, and a fully-worked example.

Browser support

WebMCP is behind chrome://flags/#enable-webmcp-testing as of mid-2026. Which flags to enable, how to verify the runtime, and the status of Firefox and Safari.

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.

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 catalog

Agentic Resource Discovery publisher catalog at /.well-known/ai-catalog.json with one entry derived from the Agent Skill. Synthesize, or merge into an origin catalog. Advertised via a robots.txt Agentmap directive, rel="ai-catalog", and llms.txt. Opt-in (ARD is a v0.9 draft).

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"