cloudflare-mcp

A smol MCP server for the complete Cloudflare API.

Uses codemode to avoid dumping too much context to your agent.

The Problem

The Cloudflare OpenAPI spec is 2.3 million tokens in JSON format. Even compressed to TypeScript endpoint summaries, it's still ~50k tokens. Traditional MCP servers that expose every endpoint as a tool, or include the full spec in tool descriptions, leak this entire context to the main agent on every request.

This server solves the problem by using code execution in a codemode pattern - the spec lives on the server, and only the results of queries are returned to the agent.

Tools

Two tools where the agent writes code to search the spec and execute API calls. Akin to ACI.dev's MCP server but with added codemode.

| Tool | Description | | --------- | ----------------------------------------------------------------------------- | | search | Write JavaScript to query spec.paths and find endpoints | | execute | Write JavaScript to call cloudflare.request() with the discovered endpoints |

Token usage: Only search results and API responses are returned. The 6MB spec stays on the server.

Agent                         MCP Server
  │                               │
  ├──search({code: "..."})───────►│ Execute code against spec.json
  │◄──[matching endpoints]────────│
  │                               │
  ├──execute({code: "..."})──────►│ Execute code against Cloudflare API
  │◄──[API response]──────────────│

Setup

Create API Token

Create a Cloudflare API token with the permissions you need.

Add to Claude Code

export CLOUDFLARE_API_TOKEN="your-token-here"

claude mcp add --transport http cloudflare-api https://cloudflare-mcp.mattzcarey.workers.dev/mcp \
  --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

Usage

// 1. Search for endpoints
search({
  code: `async () => {
    const results = [];
    for (const [path, methods] of Object.entries(spec.paths)) {
      for (const [method, op] of Object.entries(methods)) {
        if (op.tags?.some(t => t.toLowerCase() === 'workers')) {
          results.push({ method: method.toUpperCase(), path, summary: op.summary });
        }
      }
    }
    return results;
  }`,
});

// 2. Execute API call
execute({
  code: `async () => {
    const response = await cloudflare.request({
      method: "GET",
      path: \`/accounts/\${accountId}/workers/scripts\`
    });
    return response.result;
  }`,
  account_id: "your-account-id",
});

Token Comparison

| Content | Tokens | | ----------------------------- | ---------- | | Full OpenAPI spec (JSON) | ~2,352,000 | | Endpoint summary (TypeScript) | ~43,000 | | Typical search result | ~500 | | API response | varies |

Architecture

src/
├── index.ts      # MCP server entry point
├── server.ts     # Search + Execute tools
├── executor.ts   # Isolated worker code execution
├── truncate.ts   # Response truncation (10k token limit)
└── data/
    ├── types.generated.ts  # Generated endpoint types
    ├── spec.json           # OpenAPI spec for search
    └── products.ts         # Product list

Code execution uses Cloudflare's Worker Loader API to run generated code in isolated workers, following the codemode pattern.

Development

npm i
npm run deploy