Perxel MCP Kit

A public template for building a remote MCP server plus its monitoring dashboard, 100% on Cloudflare Workers. Every MCP built from it follows the same checklist: see STANDARD.md.

Source-available under the PolyForm Shield 1.0.0 license (LICENSE): free to use and modify, not to resell or offer as a competing service. This is not open source (OSI).

v1 is tested and supported for Claude only (claude.ai web, Desktop, mobile, Claude Code).

Infrastructure

Read this first. It answers "how many domains, Workers, and what runs where".

At a glance

Per Cloudflare account: one subdomain and one Worker per MCP, plus one shared metrics-proxy Worker (no public URL). No containers, no Pages, no separate dashboard host, no hosted Inspector.

                        ┌──────────── Cloudflare account ─────────────────────────────┐
 Claude ──/mcp────────▶ │  MCP Worker  "<slug>-mcp"   https://<host>                  │
                        │   /mcp  /  /health  OAuth routes                            │
 You (browser) ─/dash─▶ │   /dash  ◀─ Access app (edge sign-in) + JWT re-check        │
   via Access           │     │ service binding METRICS_PROXY (Worker-to-Worker)      │
                        │     ▼                                                       │
                        │  Metrics proxy Worker  "mcp-metrics-proxy"  (no URL)        │
                        │     │ holds the only Analytics Engine read token            │
                        │     ▼                                                       │
                        │  Analytics Engine dataset  mcp_<slug>  (written by /mcp)    │
                        │  KV: OAUTH_KV, CONTENT_KV  ·  Access: sign-in app, /dash app │
                        └─────────────────────────────────────────────────────────────┘
 Your laptop: MCP Inspector (`pnpm dev` / `pnpm inspect`), never deployed.

Hostnames

That's the only hostname. workers_dev and preview_urls are off on both Workers, so nothing is reachable any other way.

Paths on <host>

DASH_PATH is configurable (/dash default, any path like /ops/metrics, or off). It can't be / or shadow an MCP route. If you change it, change the Access app's path to match.

Workers

Why a separate proxy at all: an Analytics Engine token can't be scoped to one dataset. If every MCP Worker held it, one compromised MCP could read every other MCP's metrics. With the proxy, an MCP Worker holds only its own key, which can only read mcp_<slug>.

Cloudflare Access (Zero Trust)

Seats: sign-in users and dashboard viewers share Zero Trust's 50 free users across all MCPs in the account, then about $7/user/month.

What is deliberately not deployed

• MCP Inspector. It's a Node (Express) app, not a static site: its browser UI talks to its own backend (/api/mcp/connect, /api/mcp/send, and an open /api/fetch proxy), so Pages can't host it. Workers can't run it either, and it hardcodes root paths (/assets, /api), so it can't sit under /inspector. Hosting it would take a container plus an Access app, just to expose a generic fetch proxy. Run it locally instead: pnpm dev (against local) or pnpm inspect https://<host>/mcp --allow-remote (against production, on purpose).

• Grafana. Earlier versions ran Grafana in a Cloudflare Container on a separate dashboard host: one more Worker and a container per MCP, cold starts, and a Docker build. A fixed set of panels covers "is this MCP healthy and used", so the dashboard is now part of the MCP Worker. If you really want ad-hoc querying, Grafana is an add-on pointed at the same proxy (give the proxy a URL only for that case).

• Cloudflare Pages. Nothing here is a static site. Cloudflare also steers new projects to Workers (with static assets) rather than Pages.

What wrangler does and doesn't do

Costs (checked 2026-09-30)

• Workers Paid, $5/month per account: covers every MCP and the proxy at small scale (10M requests, 30M CPU-ms included).

• Zero Trust: 50 free seats shared, then about $7/user/month.

• No container cost.

• LLM tokens are paid by the user's Claude subscription, not by the MCP.

Related MCP server: Cloudflare Remote MCP Server (Authless)

What's inside

STANDARD.md          SSOT checklist: protocol, tools, auth, limits, metrics row, monitoring, tests, costs
kit/                 owned by the kit; clones never edit (updated via pnpm kit:update)
  core/              gate, OAuth + Access sign-in, consent page, rate limit, metrics, logs, health,
                     docs page, dashboard (dash.ts), static JSON source + search
  metrics-proxy/     shared Worker holding the only Analytics Engine token; scopes each key to one dataset
  testing/           protocol test, gate tests, eval runner, inspect launcher
  update/            the kit:update script
  setup/             the setup:cloudflare script (Cloudflare account setup from one global API key)
src/tools/           small generic example (one public, one private tool)
mcp.config.ts        example config
evals/               example questions
wrangler.mcp.jsonc   the MCP Worker (one per MCP)
wrangler.proxy.jsonc the metrics proxy (one per account)

Create a new MCP from the template

1. Use the template. On GitHub: Use this template → create your repo (e.g. docs-mcp, shop-mcp), then clone it.

2. Install. pnpm install (Node 22, pnpm 10.22.0).

3. Set mcp.config.ts. slug ([a-z0-9-]; gives the dataset mcp_<slug> with - → _), name, version, description, scopes (every private tool's scope must be listed), and the tools list.

4. Set wrangler.mcp.jsonc. name (<slug>-mcp), the routes pattern and MCP_PUBLIC_URL (same host, e.g. mcp.example.com and https://mcp.example.com), the dataset name, unique rate-limiter namespace_ids, and CONTENT_URL if you use a static source. Copy .dev.vars.example to .dev.vars for local dev.

5. Write tools. Add files in src/tools/ with defineTool from kit/core/tool.ts: name (snake_case), title, description (what it returns, units, freshness, limits), access: "public" | "private" (plus a scope when private), a zod inputSchema, and execute(input, ctx). Keep the token rules from STANDARD.md: list/search tools return compact items only (title, slug, excerpt, URL, category, never full text), full text comes only from a detail tool for one item, every list has a limit (default 5, max 20), no "dump everything" tool. Errors: throw new ToolError("not_found" | "bad_input" | "upstream" | "unavailable", msg); anything else becomes "Internal error".

6. Tests. pnpm typecheck && pnpm test: unit tests per tool, the protocol test (runs against your own config), gate tests (200/401/403), dashboard and proxy tests.

7. Evals. Edit evals/questions.md (one ## question: - tool: lines with JSON args, - expect: lines with facts that must appear), then pnpm eval --url http://localhost:8788/mcp against pnpm dev.

8. Clones never edit kit/. Kit fixes arrive via pnpm kit:update.

Content source (static JSON)

For a site-backed MCP (e.g. an MCP over your own website), the site publishes one JSON file at build time and the MCP reads it:

• The file must be at a public URL (e.g. https://example.com/content.json), set as CONTENT_URL. The Worker has no filesystem, so a file in the repo isn't read at runtime.

• Recommended shape and search rules: STANDARD.md → "Static JSON source".

• In src/, create the source once at module level and pass it to both the tools and /health:

// src/content.ts
import { z } from "zod";
import { createStaticSource } from "../kit/core/static-source.js";
export const content = createStaticSource({
  name: "content",
  url: (env) => env.CONTENT_URL as string,
  kvKey: "content",
  parse: (json) => Content.parse(json), // your zod schema
});

// src/index.ts
export default createWorker(config, { sources: { content } });

• Loading order: fresh memory (about 10 min) → conditional fetch (If-None-Match) → stale memory → CONTENT_KV last-good copy → a clear "unavailable" error. /health loads the source too, so it reports what a tool call would get (memory, fetch, kv-fallback, or empty → 503).

• Content changes show up within about 10 minutes of the site deploy, with no MCP redeploy.

Local development

The local dashboard skips the Access check (MCP_PUBLIC_URL is localhost in .dev.vars). It shows an empty page with a notice unless the proxy runs too: wrangler dev -c wrangler.mcp.jsonc -c wrangler.proxy.jsonc with DASH_PROXY_KEY, CF_API_TOKEN and PROXY_KEYS in .dev.vars (that queries the real Analytics Engine, so use a real read token only when you need to).

Deploy

Never deploy, secret put, or create resources from a dev machine without the owner's approval (STANDARD.md → Dev rules).

One command: pnpm setup:cloudflare

The only input is the account's Global API Key (Cloudflare → My Profile → API Tokens → Global API Key) and the login email, in .dev.vars (gitignored) or the environment:

CF_EMAIL="you@example.com"
CF_GLOBAL_API_KEY="..."

Set name, routes, MCP_PUBLIC_URL and the mcp_<slug> dataset in wrangler.mcp.jsonc, then:

pnpm setup:cloudflare --dry-run     # reads only, prints what it would do
pnpm setup:cloudflare               # does it, deploys, checks /health

Flags: --emails a@x.com,b@x.com (who may sign in and see the dashboard; default: the login email), --policy "<name>" (reuse an existing reusable Access policy by name; default MCP access), --no-deploy.

It is idempotent (looks first, creates only what is missing, safe to re-run) and drives wrangler with the same key, so no wrangler login is needed. It does:

One thing it cannot do: enable Zero Trust on an account for the first time (one click, Zero Trust → Get started, free plan). It stops with that message if it is off. Also: Cloudflare shows a SaaS app's client secret only when the app is created, so if ACCESS_CLIENT_SECRET is ever lost, delete the sign-in Access app and re-run.

The global key is all-powerful: keep it in .dev.vars only, never commit it, and rotate it if it leaks. The Worker never reads it.

Manual steps (what the script automates)

Only needed to understand or repair a setup by hand. Run pnpm exec wrangler login first (it opens a browser).

Once per Cloudflare account (the first MCP does this)

1. Workers Paid plan ($5/month). Don't run production on free (its 10 ms CPU cap per request is a real risk).

2. Analytics Engine read token (dashboard → My Profile → API Tokens → Create: Account → Account Analytics → Read, this account only).

3. Metrics proxy. Set CF_ACCOUNT_ID in wrangler.proxy.jsonc, then:

   pnpm exec wrangler secret put -c wrangler.proxy.jsonc CF_API_TOKEN
   pnpm exec wrangler secret put -c wrangler.proxy.jsonc PROXY_KEYS   # full JSON map, see below
   pnpm exec wrangler deploy -c wrangler.proxy.jsonc

4. Zero Trust team domain (Zero Trust → Settings → team name, <team>.cloudflareaccess.com) goes in every MCP's DASH_ACCESS_TEAM.

Per MCP

1. KV. pnpm exec wrangler kv namespace create OAUTH_KV and ... CONTENT_KV; paste the ids into wrangler.mcp.jsonc.

2. Access sign-in app (Zero Trust → Access → Applications → Add → SaaS → OIDC). Redirect URI https://<host>/callback; add a policy (e.g. email one-time PIN for allowed emails). Note the client ID, client secret, token URL, authorization URL and JWKS URL.

3. Access dashboard app (Add → Self-hosted). Domain <host>, path dash; policy: the emails allowed to see metrics. Copy its Application Audience (AUD) tag into DASH_ACCESS_AUD.

4. Proxy key. Generate one (openssl rand -hex 32), hash it (printf %s '<key>' | shasum -a 256), add "<hash>": "mcp_<slug>" to the proxy's PROXY_KEYS and re-put the whole map (a secret put replaces the value), then set the key on the MCP: pnpm exec wrangler secret put -c wrangler.mcp.jsonc DASH_PROXY_KEY.

5. MCP secrets (pnpm exec wrangler secret put -c wrangler.mcp.jsonc <NAME>): IP_HASH_SALT, COOKIE_ENCRYPTION_KEY (random, openssl rand -hex 32), ACCESS_CLIENT_ID, ACCESS_CLIENT_SECRET, ACCESS_TOKEN_URL, ACCESS_AUTHORIZATION_URL, ACCESS_JWKS_URL, DASH_PROXY_KEY.

6. Deploy. pnpm exec wrangler deploy -c wrangler.mcp.jsonc. The custom domain, DNS record and certificate are created here.

7. Check.

   • https://<host>/health is ok: true (and the source shows fetch).

   • https://<host>/ lists the tools.

   • https://<host>/dash asks for Access sign-in, then shows panels (empty until the first tool calls).

   • In Claude: Settings → Connectors → Add custom connector → https://<host>/mcp. Public tools work at once; a private tool shows a Connect card → Access PIN → Allow → Claude retries.

   • pnpm exec wrangler tail <slug>-mcp for live logs.

Where every value comes from

Public dashboard demo

By default /dash is private (Access, above). To show it off as a live demo with no sign-in, opt in per MCP:

1. wrangler.mcp.jsonc vars: "DASH_PUBLIC": "true" (any other value keeps it private).

2. Delete the dashboard Access app on <host>/dash (Zero Trust → Access → Applications), or /dash still asks for a login. setup:cloudflare skips creating it and warns if it exists.

3. wrangler deploy -c wrangler.mcp.jsonc.

Everything on the dashboard becomes world-readable (call counts, clients, countries, tool names, problems), so only do this for an MCP whose usage you are happy to show. The sign-in app for private tools is unaffected. To go private again, remove the var and re-run pnpm setup:cloudflare.

kit:update

Pulls the latest kit/ from the kit repo without touching the clone's own files (src/, mcp.config.ts, evals/, wrangler configs, package.json):

pnpm kit:update [ref] [--from <local path>]

• Refuses if git status --porcelain kit/ is not empty (commit first).

• Default source is kit.json (repo + ref, tarball from GitHub); --from copies from a local checkout.

• Replaces kit/ entirely, writes kit/VERSION as <ref>@<short sha>, compares kit/deps.json against the clone's package.json and prints any mismatches with the pnpm add command to fix them (never edits package.json automatically), then prints git diff --stat kit/.

• Review the diff, run pnpm typecheck && pnpm test, commit.

• Clone-owned files the kit changed in a release (wrangler configs, package.json scripts) are listed in that release's commit message; copy those changes by hand.

Transferring to another Cloudflare account

See TRANSFER.md.