Cloudflare MCP Server：让 AI 代理用 1,000 个 Token 调用整个 Cloudflare API

痛点场景

你正在用 AI 代理自动化运维——检查 CDN 命中率、批量更新 DNS 记录、部署 Workers 脚本。传统方式下，你需要为每个操作单独配置工具：Workers 要一个工具、R2 要一个工具、D1 数据库要一个工具……Cloudflare 有 2,500 多个 API 端点，全部塞进提示词？光是工具列表就超过 100 万 Token，直接爆掉模型的上下文窗口。

Cloudflare MCP Server 解决了这个问题——它用一种叫 Code Mode 的创新技术，把整个 Cloudflare API 压缩进 不到 1,000 个 Token，直接减少 99.9% 的 Token 消耗。

技术背景：为什么 MCP 协议存在 Token 困境

MCP（Model Context Protocol） 已经成为 AI 代理连接外部工具的标准协议。但它有一个根本矛盾：工具越多，上下文窗口消耗越大，留给实际任务的"思考空间"就越少。

以 Cloudflare API 为例：

• 原始 OpenAPI 规范直接塞进提示词：约 200 万 Token（超上下文窗口 977%）
• 普通 MCP 模式（完整 schema）：约 117 万 Token（超 585%）
• 普通 MCP 模式（仅必需参数）：约 24.4 万 Token（超 122%）
• Code Mode 模式：仅约 1,100 Token（仅占上下文的 0.5%）

这个数字对比来自 Cloudflare 官方博客，使用 tiktoken 测量。

核心设计：Code Mode 三工具架构

Cloudflare MCP Server 暴露给 AI 的工具只有 3 个，却能覆盖全部 2,500+ Cloudflare API 端点：

1. search() — 智能发现

模型用 JavaScript 代码查询 OpenAPI 规范文档，过滤出当前任务所需的端点。不需要把整个规范都塞进上下文。

// 示例：查找所有与 WAF 规则相关的端点
async () => {
  const spec = await codemode.spec();
  return Object.entries(spec.paths)
    .filter(([path]) => path.includes("/rulesets"))
    .map(([path, operations]) => ({
      path,
      methods: Object.keys(operations)
    }));
};

2. execute() — 安全执行

模型编写 JavaScript 代码，在隔离的 Cloudflare Worker 沙箱中执行真实的 API 调用。中间结果不进入模型上下文，只有最终结果返回。

// 示例：获取 WAF 规则列表
async () => {
  const response = await codemode.request({
    method: "GET",
    path: `/zones/${zoneId}/rulesets`
  });
  return response.result.map({ id, name, phase });
};

3. docs — 文档查询

快速查阅特定端点的使用方法。

使用方式：零配置连接

方式一：OAuth 授权（推荐）

无需申请 API Token，直接在 MCP 客户端中填入公共 URL：

https://mcp.cloudflare.com/mcp

首次使用时，会跳转到 Cloudflare 授权页面，选择需要的权限范围即可。

方式二：API Token

适合 CI/CD 自动化场景：

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

支持在 Cursor、Claude Desktop、Cline 等主流 MCP 客户端中直接配置。

禁用 Code Mode（可选）

如果你的 MCP 客户端已经内置 Code Mode 能力，或需要为每个端点单独注册工具，可以添加 ?codemode=false 参数：

https://mcp.cloudflare.com/mcp?codemode=false

此时每个 API 端点都会作为独立工具注册（约 2,594 个工具）。

技术架构

项目使用 TypeScript 开发，部署在 Cloudflare Workers 平台上：

• 框架：Hono（轻量 Web 框架）+ Wrangler 部署
• MCP 协议：@modelcontextprotocol/server SDK
• 代码执行：Cloudflare Dynamic Worker Loader（隔离沙箱）
• 认证：Workers OAuth Provider（支持用户 OAuth 和 API Token 两种方式）
• 类型安全：Zod 数据验证 + TypeScript 类型推导
• 测试：Vitest + @cloudflare/vitest-pool-workers（在 Workers 环境中运行单元测试）
• 代码质量：oxlint linting + oxfmt 格式化 + 完整类型检查

根目录包含：

• src/ — 核心逻辑（mcp-handler.ts、server.ts、openapi.ts、spec-processor.ts 等）
• scripts/ — 辅助脚本（如 R2 数据初始化）
• tests/ — 完整测试套件
• wrangler.jsonc — Workers 部署配置

上手门槛

维度	评估
使用门槛	极低：配置 MCP URL 即可，无需任何部署
自部署门槛	中等：需要 Node.js 环境 + Wrangler CLI + Cloudflare 账号
认证复杂度	低：支持 OAuth 交互式授权，零配置上手

局限性

1. 网络依赖：公共端点 mcp.cloudflare.com 需要能访问 Cloudflare
2. 不支持 IP 白名单 Token：Cloudflare API Token 开启了 Client IP 地址过滤的不兼容
3. 代码沙箱限制：执行的是 JavaScript 代码，非 Python 或其他语言
4. 非本地部署：公共端点由 Cloudflare 托管，不适合需要完全私有化部署的场景

行业意义

Cloudflare 选择将如此核心的基础设施能力开源，背后有几层含义：

Token 经济学的范式转变：Code Mode 证明了"让模型写代码调用工具"比"列举大量工具"高效得多。这种思路已被 Anthropic 在 Code Execution with MCP 中独立验证，显示出该方向的正确性。

开源 Code Mode SDK：Cloudflare 将 Code Mode SDK 单独开源，开发者可以用它为任何大型 API 构建类似的 Token 高效 MCP 服务器。

MCP 生态的关键节点：Cloudflare API 是全球最常用的基础设施 API 之一，它的 MCP 支持将使大量 AI 代理应用能够安全、便捷地管理 Cloudflare 资源。

指标	数据
GitHub Stars	882
Fork 数	120
主要语言	TypeScript
许可证	Apache-2.0
仓库创建时间	2026-01-29
最新推送	2026-09-25

---

本报告由 PIFS 自动化分析系统生成