cf-mcp-bridge

A small, read-only Model Context Protocol (MCP) bridge for Cloudflare, deployed on Cloudflare Workers.

The bridge is intentionally narrow: it exposes a handful of useful Cloudflare account inspection tools instead of wrapping the entire Cloudflare API. The MCP endpoint fails closed unless both the Cloudflare API token and the MCP client secret are configured.

Current tools

• cloudflare_token_status — verify the configured Cloudflare API token

• list_accounts — list accounts visible to the token

• list_zones — list zones/domains, optionally filtered by name

• list_dns_records — inspect DNS records for a zone

• list_workers — list Worker scripts

• list_pages_projects — list Pages projects

• list_r2_buckets — list R2 buckets

• list_tunnels — list active Cloudflare Tunnels and connections

• get_tunnel_status — inspect one Tunnel

All current tools are read-only. There are no DNS mutation, Worker deployment, R2 deletion, cache purge, or Tunnel mutation tools in v0.1.

Related MCP server: seosiri-db-infra-mcp

Architecture

MCP client
   |
   | Authorization: Bearer <MCP_SHARED_SECRET>
   v
Cloudflare Worker /mcp
   |
   | CF_API_TOKEN (Worker secret)
   v
Cloudflare API

GET /health is public and returns only service health. /mcp requires the bearer secret.

The Cloudflare API token never needs to be stored in an MCP client. It stays in the Worker secret store.

Requirements

• Node.js 20+

• A Cloudflare account

• Wrangler authenticated to the Cloudflare account

• A read-only / least-privilege Cloudflare API token

Cloudflare recommends createMcpHandler() for new stateless MCP servers. This project uses the current Streamable HTTP stateless handler rather than the deprecated McpAgent path.

Local development

npm install
cp .dev.vars.example .dev.vars

Fill .dev.vars with local values:

CF_API_TOKEN="..."
CF_ACCOUNT_ID="..."
MCP_SHARED_SECRET="..."

Generate a strong MCP shared secret, for example:

openssl rand -hex 32

Then run:

npm run dev

The MCP endpoint will normally be:

http://localhost:8787/mcp

Health check:

curl http://localhost:8787/health

Test with MCP Inspector

Run the inspector in another terminal:

npx @modelcontextprotocol/inspector@latest

Use the local MCP URL and send this header:

Authorization: Bearer <MCP_SHARED_SECRET>

Then connect and use List Tools.

Deploy to Cloudflare Workers

Authenticate Wrangler if needed:

npx wrangler login

Set the secrets. Do not put real values in wrangler.jsonc or commit them to Git.

npx wrangler secret put CF_API_TOKEN
npx wrangler secret put MCP_SHARED_SECRET
npx wrangler secret put CF_ACCOUNT_ID

CF_ACCOUNT_ID is technically not sensitive, but storing it alongside the other deployment values keeps the repository generic. You may also configure it as a normal Worker variable if you prefer.

Deploy:

npm run deploy

The endpoint will be similar to:

https://cf-mcp-bridge.<your-workers-subdomain>.workers.dev/mcp

Cloudflare API token permissions

Create a dedicated token for this bridge. Do not use the Global API Key.

Only grant permissions for the tools you actually want enabled. The exact Cloudflare permission labels can vary by product and account configuration, but the token should be limited to read access for the relevant resources, such as:

• Account / account information: read

• Zone: read

• DNS: read

• Workers Scripts: read

• Pages: read

• R2: read

• Cloudflare Tunnel: read

Restrict the token to the specific account and zones whenever possible.

If a tool returns a Cloudflare permission error, add only the missing read scope rather than broadening the token to edit access.

Connect from an MCP client

Clients that support remote Streamable HTTP and custom headers can connect directly to /mcp with the bearer secret.

For clients that use a local proxy, mcp-remote can bridge to the remote endpoint. The exact header configuration depends on the client/version; keep MCP_SHARED_SECRET on the local machine and never embed the Cloudflare API token in the client.

Security model

The v0.1 security model is deliberately simple:

1. A dedicated Cloudflare API token is stored only as a Worker secret.

2. The Cloudflare API token should be read-only and resource-scoped.

3. The /mcp endpoint requires an independent bearer secret.

4. If required secrets are missing, /mcp returns 503 instead of starting insecurely.

5. The repository contains no credentials.

6. No destructive MCP tools exist.

For a single-user deployment this is a pragmatic first layer. The next security upgrade is to put the MCP endpoint behind Cloudflare Access / OAuth, so MCP clients authenticate through an identity provider rather than a static shared secret.

Planned v0.2

• Cloudflare Access / OAuth protection

• Audit log reader

• Worker/Pages deployment status and recent failures

• Better pagination for very large accounts

• Explicit output schemas

• Tests against mocked Cloudflare API responses

Write actions should be added only as a separate, deliberately scoped layer, ideally using a second Cloudflare API token with narrowly limited edit permissions.

Useful commands

npm run dev
npm run typecheck
npm run deploy

References

• Cloudflare Agents MCP docs: https://developers.cloudflare.com/agents/model-context-protocol/

• Remote MCP server guide: https://developers.cloudflare.com/agents/model-context-protocol/guides/remote-mcp-server/

• MCP handler API: https://developers.cloudflare.com/agents/model-context-protocol/apis/handler-api/

• Cloudflare API: https://developers.cloudflare.com/api/

License

Private/internal use unless you choose to add a license later.