Install a Cloudflare Worker mirror

Install is gated by a single MCP scope: directory:write. Generate a NORG MCP API key that carries it, and use that key for the MCP connection you run manage_edge_routing from.

directory:write is the real requirement. The same scope also authorises purge, uninstall and key rotation — there is no narrower install-only scope today, so provision directory:write rather than looking for a least-privilege alternative that does not exist.

In the Cloudflare dashboard go to Account Home → Manage Account → API Tokens → Create Token → Create Custom Token (an account-owned token, which is what the walkthrough below creates). My Profile → API Tokens also works, but only if your own user role covers the whole account — a user token is capped by your role, so if your login only has domain access the account-level grant silently fails at deploy time. See token permissions & zone-only access for the fix. You will add three separate permission policies — two scoped to the single zone you are installing on, one scoped to your entire account (not the zone — that one is easy to miss, see the account-level callout below):

Policy 1 — this zone (matches the walkthrough below):

• Zone: Read — resolve your domain to a Cloudflare zone and verify the token
• DNS: Read — confirm your domain is proxied (orange-clouded)
• Bot Management: Edit — detect whether Bot Fight Mode or "Block AI bots" is blocking the install. Today the install only reads this setting (so Read is all it strictly needs — if either toggle is blocking, you flip it off yourself, see the alert at the top of this page). Granting Edit now future-proofs the token for a planned NORG auto-fix of a blocking toggle, so you will not have to re-scope the token when that ships — Cloudflare's Edit includes read. In the permission picker this one is under App Security, not DNS & Zones, so search bot rather than zone to find it.

Policy 2 — this zone, Edit:

• Workers Routes: Edit — bind the {domain}/* route
• Zone WAF: Edit — create the skip rule that lets AI agents and the health probe past your WAF Managed Rules

Policy 3 — Entire Account, Edit (not the zone):

• Workers Scripts: Edit — upload the worker itself

Picking the right one: Zone WAF: Edit

The install creates a WAF Custom Rule via Cloudflare's Rulesets API (/zones/{zone_id}/rulesets, phase http_request_firewall_custom) so AI agents and the health probe get past your WAF Managed Rules. That needs Zone WAF: Edit — shown as "Zone WAF" in the token permission picker, not the older "Firewall Services" group. Without it the install returns a specific "missing Zone WAF:Edit" error. The rule it creates exempts only AI-agent user agents and this site's own probe requests — never all traffic — and leaves every other rule on your zone alone.

It cannot, however, reach Bot Fight Mode or "Block AI bots" — those are zone toggles outside the WAF. See the alert at the top of this page.

Paste the token into the install call as cf_api_token.

With both credentials ready, call manage_edge_routing through your NORG MCP connection. Install requires both domain and cf_api_token, and is a two-pass, human-confirmed action:

• Pass 1 — preview. The tool defaults to dry_run=true: it runs a read-only preflight (checks your Workers plan, scans for a conflicting {domain}/* route, reads Bot Fight Mode) and returns a preview plus a confirmation_token.
• Pass 2 — apply. Re-call with dry_run=false and that confirmation_token to upload the worker, set its variables, and bind the route.

# Pass 1 — preview (read-only preflight, dry_run defaults to true)
manage_edge_routing(
    action="install",
    domain="example.com",
    cf_api_token="<your-cloudflare-api-token>",
)
# -> returns a preview + confirmation_token (requires human confirmation)

# Pass 2 — apply, carrying the token back
manage_edge_routing(
    action="install",
    domain="example.com",
    cf_api_token="<your-cloudflare-api-token>",
    dry_run=False,
    confirmation_token="<token-from-pass-1>",
)

The worker serves NORG renders only to requests that provably come from an AI operator — the source IP must be in the operator's published ranges, or Cloudflare must mark the request a verified bot — so a curl with a spoofed agent user-agent from your own machine is deliberately passed straight through with no X-Norg-Edge header. Verify with the Site Key health probe instead; a browser user-agent must stay untouched.

# The worker is live on the route (Site Key health probe):
curl -s -H "x-norg-edge-check: <your-site-key>" https://example.com/ | head -c 200
#   {"site_id":"…","version":"…","disabled":false,"ts":…}  -> deployed, routed, key OK
#   (your own page instead of JSON -> the worker is not seeing the request)

# A normal visitor must be untouched (expect NO output):
curl -sI -A "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Chrome/125.0 Safari/537.36" \
  https://example.com/some-page/ | grep -i x-norg-edge

A JSON reply proves the worker is deployed, routed, and holding the right key. Your own page instead of JSON means the worker is not seeing the request — recheck the proxied DNS record and the {domain}/* route. Genuine agents then see X-Norg-Edge: mirror (a NORG render was served) or X-Norg-Edge: stripped (no render yet), and the worker reports a heartbeat to NORG each time it serves one.

Getting a challenge page or a non-200 instead of any of that? See the bot-blocking alert at the top of this page — your own curl looks identical to any other automated request to Bot Fight Mode / "Block AI bots" if either is on.