A Cloudflare Worker that sits in front of a website and equips it with WebMCP. One TOML file in, every WebMCP-aware browser sees the site's tools out.
Not affiliated with Cloudflare. The
cf-prefix only reflects that the project runs exclusively on Cloudflare primitives - this is not an official Cloudflare product.
For each request, the Worker does one of two things:
1. Handle a Worker-owned path directly.
| Path | What lives there |
|---|---|
/.well-known/webmcp.json |
Tool-catalogue manifest, machine-readable JSON |
/.well-known/api-catalog |
RFC 9727 Linkset (RFC 9264) pointing at the manifest |
/.well-known/agents.md (+ /AGENTS.md, /agents.md 301 aliases) |
AGENTS.md augmentation block for acting agents |
/.well-known/agent-skills/<slug>/SKILL.md (+ case-variant 301 aliases) |
Anthropic-format Agent Skill, auto-generated from [[tools]] plus publisher hints |
/.well-known/agent-skills/index.json |
Cloudflare Agent Skills Discovery RFC v0.2.0 index with build-time SHA-256 digest |
/llms.txt |
Origin's llms.txt with a WebMCP block merged in |
/robots.txt |
Origin's robots.txt with Disallow: /_webmcp/ merged in |
/mcp |
Landing page: native-API, desktop-pairing, or disabled state |
/_webmcp/exec/<tool> |
Tool execution endpoint (POST) |
/_webmcp/bootstrap.<hash>.js |
In-page tool registration script |
/_webmcp/widget.<hash>.js |
Optional desktop-bridge widget |
/_webmcp/health |
Operational health endpoint |
2. Otherwise, proxy to origin and modify the response on the way back.
- HTTP
Linkheader added to every proxied response (HTML, PDF, image, JSON, anything). One entry per discovery surface:rel="webmcp"to the manifest,rel="api-catalog"to the catalog,rel="agent-skills"to the SKILL.md. An agent doing aHEADrequest finds all three without parsing a body. - On HTML responses only (status 200,
text/html, UTF-8, path not in[injection].exclude_paths), HTMLRewriter injects:- matching
<link>tags into<head>(rel="webmcp",rel="api-catalog",rel="agent-skills"), - one
<script src="/_webmcp/bootstrap.<hash>.js" defer>before</body>that auto-registers the tools vianavigator.modelContext, - W3C declarative form attributes (
toolname,tooldescription,toolparamdescription,toolautosubmit) stamped onto matching<form>elements when a[[forms]]block matches the current path.
- matching
Non-HTML responses (PDFs, images, JSON, CSS, JS, etc.) pass through with their body unchanged but with the Link header added.
The tool catalogue lives in one TOML file. Five server-side executor types (sitemap_filter, rss_feed, dom_extract, http_json, http_get) cover the imperative tool path; [[forms]] blocks cover the declarative-form path. Three deploy templates ship: default, wordpress, woocommerce (Store API).
cf-webmcp publishes the same tool catalogue through multiple complementary surfaces, all driven from the single TOML:
/.well-known/webmcp.json(manifest, machine-readable)<link rel="webmcp">injected into every HTML pageLink: rel="webmcp"HTTP header on every response/llms.txtaugmented with a WebMCP block (idempotent merge with origin's file)/robots.txtaugmented withDisallow: /_webmcp/(idempotent merge)/.well-known/agents.mdfor acting agents, with/AGENTS.mdand/agents.md301-redirecting to it/.well-known/api-catalog(RFC 9727) Linkset entry pointing at the WebMCP manifest. Also advertised in theLinkheader and as<link rel="api-catalog">on every response./.well-known/agent-skills/<slug>/SKILL.mdAnthropic-format Agent Skill with auto-generated tool list + publisher-written hints. Also advertised viarel="agent-skills"in theLinkheader and as a<link>tag./.well-known/agent-skills/index.json(Cloudflare Agent Skills Discovery RFC v0.2.0) wraps the SKILL.md in a spec-compliant index with a build-time SHA-256 digest for integrity verification.links.agent_skills_indexfield added to the manifest./mcplanding page that branches at runtime between native, pair, and disabled states
Plus five executor types (sitemap_filter, rss_feed, dom_extract, http_json, http_get) for the imperative tool path, and a [[forms]] block for the declarative form path.
Note
Every surface above is opt-in. Each one maps to a single boolean in your [features] block. If you disagree with a convention or do not want to publish it, flip the flag off and the route disappears, the link advertisement drops out, and no fingerprint is left. llms.txt is the most widely-debated example: set llms_txt = false and cf-webmcp stops claiming the path entirely. Same applies to agents.md, api-catalog, agent-skills, fallback_widget, form-attribute injection, and the in-page <script> bootstrap. Defaults are "on" because cf-webmcp's value is publishing discovery surfaces; opting out is one TOML edit away. See docs/scope.md for what is in and out of scope at the project level.
git clone https://github.com/basgr/cf-webmcp
cd cf-webmcp
cp templates/default.toml webmcp.toml
cp wrangler.example.toml wrangler.toml
# edit webmcp.toml: set [site], [origin], and tool URLs
# edit wrangler.toml: set the route for your domain
npm install
npm run build
wrangler deployFull reference docs live in docs/:
Getting started
- Deployment - full-proxy vs route-only modes, wrangler config, Bot Management bypass.
- Local testing -
wrangler devagainst the bundledtemplates/example-site/fixture. - Browser support - enabling the WebMCP flag in Chrome and verifying it.
Configuration
- Customisation - overriding the
/mcplanding template, placeholders, runtime state branching. - Form injection - the
[[forms]]block, declarativetoolname/tooldescription/toolparamdescription/toolautosubmitattribute stamping. - AGENTS.md -
/.well-known/agents.mdpublication + 301 aliases. - API catalog (RFC 9727) - the
/.well-known/api-catalogLinkset. - Agent Skills - the
/.well-known/agent-skills/<slug>/SKILL.mdpublication.
Operations
- Costs - Workers, R2, and cache pricing under typical traffic.
- Privacy - what's logged, what's stripped from origin fetches, GDPR posture.
- Upgrade -
schema_versionpolicy, tool-name immutability, breaking-change procedure. - Limitations - SPA story, multi-language sites, service workers, other known edges.
Project
- Scope - what cf-webmcp is and is not. Read this before opening a feature request.
- Suganthan Mohanadasan, "WebMCP: I Made My Website AI Agent Ready" - the implementation guide that informed the publisher-side discovery patterns.
- jasonjmcghee/WebMCP - the fallback widget that bridges desktop MCP clients to WebMCP sites.
- webmachinelearning/webmcp - the W3C draft.
MIT. See LICENSE.