Cloudflare MCP Server: 2,500 API endpoints behind three tools

The context budget problem this server was built to dodge

The Cloudflare OpenAPI spec is large enough to break an agent's context window on its own. The README puts the raw spec at roughly 2,000,000 tokens, which it says would consume 977% of a 200K context. Exposing every endpoint as a native MCP tool does not fix that: the README's comparison table lists 2,594 tools at 1,170,523 tokens with full schemas, and still 244,047 tokens when stripped down to required parameters only. That is 122% of a 200K window before the agent has done anything.

The server's answer is code mode, borrowed from Cloudflare's own Code Mode pattern. Instead of shipping 2,594 schemas to the client, it registers three tools and keeps the spec on the server. The README claims about 1,100 tokens for the code mode approach, or 0.5% of a 200K context. Those numbers come from the project's own table, not from independent measurement, and the gap between 244k and 1.1k is the entire pitch.

Who this is for: developers running an MCP-capable agent who need to touch many different Cloudflare products (Workers, KV, R2, D1, Pages, DNS, Firewall, Load Balancers, Stream, Images, AI Gateway, Vectorize, Access, Gateway and others) and who do not want to hand-write a wrapper for each. If you only manage DNS records for one zone, the token argument does not apply to you and the added indirection is pure cost.

Search, execute, and where the spec actually lives

The architecture is two hops. The agent calls search with a JavaScript snippet, which runs against spec.paths on the server and returns matching endpoints. It then calls execute with another snippet that invokes cloudflare.request() against the real Cloudflare API. A third tool, docs, searches Cloudflare's developer documentation and stays available in both modes.

The README's own diagram shows the flow: the agent sends search({code: "..."}), the server executes that code against spec.json and returns matching endpoints; the agent sends execute({code: "..."}), the server executes code against the Cloudflare API and returns the response. The OpenAPI spec never enters the agent's context. Only the code the agent writes and the result it gets back cross the boundary.

This is the part worth pausing on. The agent is not selecting from a menu of typed tools; it is writing JavaScript that the server runs. That is a different trust model from a conventional MCP server, where the worst case is a badly chosen argument to a fixed function. Here the search step is sandboxed against a spec file, but the execute step reaches the live API with whatever credentials you configured. The README does not describe sandboxing, timeouts, or what happens to a snippet that loops.

GraphQL is handled through the same path. The README says the server automatically detects Cloudflare's GraphQL Analytics API endpoints, and gives an example posting a query to /client/v4/graphql through cloudflare.request() with method POST and a body containing query and variables.

Installing the Cloudflare MCP server and running a first call

There is nothing to install locally if you use the hosted endpoint. The README gives one MCP URL, https://mcp.cloudflare.com/mcp, and two ways to authenticate. OAuth is the recommended path: you connect to the URL, get redirected to Cloudflare, authorize, and select permissions. The JSON configuration for an HTTP MCP client looks like this.

{
  "mcpServers": {
    "cloudflare-api": {
      "type": "http",
      "url": "https://mcp.cloudflare.com/mcp"
    }
  }
}

After adding that block and restarting the client, you should be prompted to authorize against Cloudflare and pick scopes. If the client shows three tools named docs, search and execute, code mode is active.

The second path is an API token, which the README recommends for CI/CD and automation. Create a token at https://dash.cloudflare.com/profile/api-tokens with the permissions you need. Both user tokens and account tokens work; for account tokens, include the Account Resources : Read permission so the server can detect your account ID automatically. Configure it as a bearer token alongside the MCP URL.

Once connected, the README's usage section suggests asking the agent in plain language, for example to list Workers or create a KV namespace. Behind the scenes the agent writes a search snippet that walks spec.paths and filters by tag, then an execute snippet calling cloudflare.request(). With a user token you pass account_id explicitly; with an account token the README shows the same call omitting account_id, because the server resolves it.

For anyone self-hosting, the repository is a Wrangler project. The package.json defines dev as wrangler dev, deploy as wrangler deploy --env staging, and deploy:prod as wrangler deploy --env production, with a check script chaining format:check, lint, typecheck and test. The README does not document a self-hosting walkthrough, so treat those scripts as the starting point rather than a guide.

Disabling code mode is a trap you can walk into on purpose

Adding ?codemode=false to the MCP URL switches the server to one tool per endpoint. The README says this registers roughly 2,500 individual tools such as get_workers_scripts and post_d1_database, derives each input schema from the endpoint's path parameters, query parameters and request body, and makes direct API calls with no code execution. Path parameters like account_id are auto-resolved when there is a single account.

The stated reason to do this is composition: if your MCP client already uses code mode, or you are stacking this server with another code-mode server, the two schemes collide. The README is explicit that this should only be done when necessary, because it pushes token cost from about 1k to about 244k. That is not a small regression; it is the difference between fitting in context and not.

There is a real tension here that the README does not resolve. Disabling code mode removes the code-execution surface, which some security reviewers will prefer, but it reintroduces the exact context problem the server exists to solve. You cannot have both the low token cost and the no-code-execution property. Pick which one you care about before you configure the URL, because changing it later means re-authenticating and re-testing the agent's behaviour from scratch.

Token filtering, scope selection, and the limits the README admits

The clearest documented limitation is authentication: API tokens with Client IP Address Filtering enabled are not currently supported. If your organization issues tokens that way, the API token path is closed to you and you are on OAuth, assuming your client handles the redirect flow.

The OAuth path carries its own risk, and it is a quiet one. Permission selection happens interactively during authorization. An agent that later needs a scope you did not grant will fail at the API call, not at configuration time, and the error surfaces inside a generated code snippet. The README does not document how to inspect or amend granted scopes after the fact.

The broader failure mode is that the agent writes the code. A search snippet that filters spec.paths incorrectly returns nothing useful, and the agent may conclude an endpoint does not exist. An execute snippet with a wrong path or a missing account_id fails against the live API. Because the spec stays server-side, the agent's only view of the API surface is what its own search code returned. The README does not describe validation of generated code, dry-run mode, or a confirmation step before destructive calls. If you are pointing this at production DNS or Workers, that absence matters more than the token savings.

Finally, this is a young project. The package.json still declares version 0.1.0, and the repository lists no releases. Treat the API surface as settled but the operational edges as undocumented.

Cloudflare MCP versus the CLI and hand-written API calls

The obvious alternative is Wrangler and the Cloudflare API directly. Wrangler is a command-line tool with typed subcommands; you read the documentation, pick the command, and run it. The difference is not capability, since both reach the same API, but where the knowledge lives. With Wrangler it lives in your head or in a script you wrote and reviewed. With this MCP server it lives in the agent's generated JavaScript, which you may or may not see depending on your client.

A second alternative is a conventional MCP server that wraps a narrow slice of Cloudflare, for example DNS records only. That server will expose a handful of tools with fixed schemas, cost a few thousand tokens, and never execute arbitrary code. It covers less ground, but every call is a typed function invocation rather than a snippet. The README's own framing supports this split: the 244k token figure for minimal native schemas is only a problem if you need all 2,594 tools. Below a certain breadth, the narrow server wins on predictability.

The honest summary is that code mode is a context optimization that trades token cost for execution trust. If your agent client surfaces the generated code before running it, the trade is reasonable. If it does not, you have handed an agent a general-purpose API client and the README does not tell you how to constrain it.

Licence, maintenance and upgrade cost

The repository is licensed Apache-2.0, which permits commercial and private use, modification and redistribution provided the licence and notices are preserved. That is a permissive licence with an explicit patent grant, and it is the same licence Cloudflare uses across much of its open source. It says nothing about the hosted endpoint at mcp.cloudflare.com, which is a service governed by Cloudflare's own terms, not by the repository licence. Running the code yourself under Apache-2.0 and calling Cloudflare's hosted server are two different legal arrangements; the README does not discuss either.

On maintenance, the repository is not archived and the last push was on 2026-09-10, which is ten days before this writing. The version field in package.json is 0.1.0 and the repository lists no releases, so there is no versioned changelog to diff against. Upgrading means tracking the main branch or the hosted endpoint, and the README documents exactly one behavioural switch, the codemode query parameter. Everything else about the deployed server can change without a version number attached. If you depend on this in automation, pin what you can (the MCP URL, the token scopes) and expect the rest to move.

Editorial conclusion

Adopt it if your agent client supports remote HTTP MCP servers and you want Cloudflare API coverage without paying the context cost of 2,594 tool schemas; the OAuth path at https://mcp.cloudflare.com/mcp is the shortest route in. Skip it if you only touch one or two Cloudflare products, where a handful of hand-written API calls or the Cloudflare CLI is easier to reason about, and skip it if your tokens use Client IP Address Filtering, which the README says is unsupported. Before trusting it with anything destructive, verify three things yourself: whether your client renders the search and execute steps so you can see the generated code, what scope the OAuth consent screen actually granted, and whether a token with Account Resources : Read is needed to auto-detect your account ID.

Frequently asked questions

Official sources

1. cloudflare/mcp on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README