代码模式：仅用 1000 个 Token 为 AI 代理提供完整 API

摘要

1) 一句话总结

Cloudflare 推出了基于“代码模式”的全新 MCP 服务器，仅需约 1000 个 Token 和两个核心工具（search 和 execute），即可让 AI 代理安全地访问包含 2500 多个端点的完整 Cloudflare API，将 Token 消耗降低了 99.9%。

2) 关键点

核心机制：摒弃了为每个 API 操作定义单独工具的传统做法，采用“代码模式”（Code Mode），让模型基于类型化的 SDK 编写 JavaScript 代码来动态探索和调用 API。
极低的 Token 消耗：覆盖整个 Cloudflare API 仅需约 1000 个 Token。如果不使用该模式，同等规模的 API 将消耗 117 万个 Token（超出当前最先进模型的上下文窗口），该模式将输入 Token 使用量减少了 99.9%。
双工具架构：服务端仅导出两个工具：search()（用于在不加载完整 OpenAPI 规范的情况下过滤和查找端点）和 execute()（用于发起请求、处理分页及在单次执行中链式调用多个操作）。
安全沙盒执行：生成的代码在服务端的动态 Worker 隔离区（轻量级 V8 沙盒）中运行。该环境无文件系统、防止环境变量泄露，且默认禁用外部 fetch 请求。
权限与认证：兼容 OAuth 2.1 规范，通过 Workers OAuth Provider 实现权限范围缩减；同时支持使用 Cloudflare API Token（用户或账户级别）作为不记名令牌（Bearer tokens）进行认证。
开源支持：Cloudflare Agents SDK 中已开源了新的代码模式 SDK，允许开发者在自己的 MCP 服务器中复用此架构。
未来规划：计划推出 MCP Server Portals，允许在单一网关后组合多个 MCP 服务器，提供统一的身份验证和代码模式集成，以保持固定的 Token 消耗。

3) 风险/不足

多服务扩展带来的上下文压力：尽管代码模式解决了单一 API 的上下文成本问题，但当代理需要同时连接多个不同的 MCP 服务器（如 GitHub、数据库等）时，每一个新增的服务器仍会重新带来上下文窗口耗尽的压力（官方正计划通过 Server Portals 解决此问题）。
替代方案的固有局限（对比提及）：
- 客户端代码模式：要求代理端必须具备安全的沙盒访问权限。
- CLI 模式：需要 Shell 环境（并非所有环境都支持），且相比沙盒隔离区会引入更广泛的攻击面。
- 动态工具搜索：需要额外维护和评估搜索功能，且每个被匹配到的工具依然会消耗 Token。

正文

模型上下文协议（MCP）已成为 AI 代理（Agents）使用外部工具的标准方式。但其核心存在一个矛盾：代理需要许多工具来完成有用的工作，然而每增加一个工具，都会占用模型的上下文窗口，导致留给实际任务的空间变小。

为了减少代理使用工具时的上下文窗口消耗，我们首创了“代码模式”（Code Mode）技术。该模式不再将每个操作描述为单独的工具，而是让模型基于类型化的 SDK 编写代码，并在动态 Worker 加载器中安全地执行这些代码。这些代码充当了一个紧凑的执行计划。模型可以探索工具操作、组合多个调用，并仅返回它所需的数据。（Anthropic 在其关于 MCP 代码执行的文章中也独立探索了相同的模式。）

今天，我们推出了一款全新的、覆盖整个 Cloudflare API（从 DNS、Zero Trust 到 Workers 和 R2）的 MCP 服务器，该服务器正是基于代码模式构建的。只需借助 search() 和 execute() 两个工具，该服务器就能通过 MCP 提供对整个 Cloudflare API 的访问，而消耗的 Token 数量仅为 1000 个左右。无论存在多少个 API 端点，其 Token 消耗量始终保持固定。

对于像 Cloudflare API 这样庞大的 API，代码模式将输入 Token 的使用量减少了 99.9%。如果不使用代码模式，同等的 MCP 服务器将消耗 117 万个 Token——这甚至超过了目前最先进基础模型的整个上下文窗口。

您今天就可以开始使用这个全新的 Cloudflare MCP 服务器。同时，我们还在 Cloudflare Agents SDK 中开源了一个新的代码模式 SDK，以便您在自己的 MCP 服务器和 AI 代理中使用相同的方法。

服务端代码模式

这个新的 MCP 服务器在服务端应用了代码模式。服务器不再导出数以千计的工具，而是仅导出两个由代码模式驱动的工具：search() 和 execute()。

为了发现自己能做什么，代理会调用 search()。它会基于 OpenAPI 规范的类型化表示来编写 JavaScript 代码。代理可以按产品、路径、标签或任何其他元数据过滤端点，将数千个端点缩小到它所需的几个。完整的 OpenAPI 规范永远不会进入模型的上下文，代理仅通过代码与其交互。

当代理准备采取行动时，它会调用 execute()。代理编写的代码可以发起 Cloudflare API 请求、处理分页、检查响应，并在单次执行中将多个操作链接在一起。

这两个工具都在动态 Worker 隔离区（Dynamic Worker isolate）内运行生成的代码。这是一个轻量级的 V8 沙盒，没有文件系统，没有可能因提示词注入而泄露的环境变量，并且默认禁用了外部获取（fetch）功能。如果需要，可以通过出站 fetch 处理程序显式控制出站请求。

操作示例：防御 DDoS 攻击

假设用户告诉代理：“保护我的源站免受 DDoS 攻击。”

第一步：搜索正确的端点。 代理首先查阅文档，得知需要在源站前部署 Cloudflare WAF 和 DDoS 保护规则。随后，搜索工具为模型提供一个规范对象（预先解析了所有引用的完整 Cloudflare OpenAPI 规范）。模型编写 JavaScript 代码来寻找区域（zone）上的 WAF 和规则集端点。服务器在 Worker 隔离区运行此代码并返回结果。Cloudflare API 规范有超过 2500 个端点，模型成功将其缩小到所需的 WAF 和规则集端点，而没有任何规范内容进入上下文窗口。模型还可以在调用特定端点之前深入检查其架构（例如查看区域规则集可用的阶段）。
第二步：对 API 执行操作。 代理切换到使用 execute。沙盒获得一个 cloudflare.request() 客户端，可对 Cloudflare API 进行身份验证调用。代理首先检查区域上已存在哪些规则集，发现托管的 DDoS 和 WAF 规则集已存在后，它可以链接调用以检查其规则，并在单次执行中更新敏感度级别。

从搜索规范、检查架构，到列出规则集并获取 DDoS 和 WAF 配置，这整个操作仅需四次工具调用。

Cloudflare MCP 服务器的演进

最初，我们为单个产品提供独立的 MCP 服务器（例如 DNS MCP 服务器、Workers 可观测性 MCP 服务器）。每个服务器导出一组固定的工具来映射 API 操作。当工具集很小时，这种方法很有效，但 Cloudflare API 拥有超过 2500 个端点，任何手动维护的服务器集合都无法跟上这种规模。

新的 Cloudflare MCP 服务器简化了这一切。两个工具，大约 1000 个 Token，即可覆盖 API 中的每个端点。当我们添加新产品时，相同的 search() 和 execute() 代码路径就能发现并调用它们——无需新的工具定义，也无需新的 MCP 服务器。它甚至支持 GraphQL Analytics API。

我们的 MCP 服务器基于最新的 MCP 规范构建，兼容 OAuth 2.1。它使用 Workers OAuth Provider，根据用户连接时批准的权限来缩小 Token 的权限范围。代理只能获得用户明确授予的功能。对于开发者而言，这意味着您可以使用简单的代理循环，同时通过内置的渐进式能力发现，赋予代理访问完整 Cloudflare API 的权限。

上下文缩减方案对比

目前已出现几种减少 MCP 工具 Token 消耗的方法：

客户端代码模式： 这是我们最初的实验。模型基于类型化 SDK 编写 TypeScript，并在客户端的动态 Worker 加载器中运行。其代价是要求代理必须具备安全的沙盒访问权限。
命令行接口（CLI）： CLI 具有自文档化的特点，并在代理探索时揭示功能。但其局限性很明显：代理需要一个 Shell 环境，这并非所有环境都能提供，且相比沙盒隔离区，它引入了更广泛的攻击面。
动态工具搜索： 这种方法会呈现一组与当前任务相关的较小工具集。它缩小了上下文使用量，但需要维护和评估搜索功能，且每个匹配到的工具仍会消耗 Token。
服务端代码模式（本文方案）： 专门针对 MCP 服务器结合了上述优势。无论 API 规模多大，Token 成本固定；无需在代理端进行修改；内置渐进式发现；并在沙盒隔离区内安全执行。代理只需通过代码调用两个工具，其余一切都在服务端完成。

立即开始使用

Cloudflare MCP 服务器现已可用。将您的 MCP 客户端指向服务器 URL，您将被重定向到 Cloudflare 进行授权，并选择授予代理的权限。

对于 CI/CD、自动化场景，或者如果您更喜欢自己管理 Token，可以创建一个具有所需权限的 Cloudflare API Token。用户 Token 和帐户 Token 均受支持，并可作为不记名令牌（Bearer tokens）在 Authorization 标头中传递。

展望未来

代码模式解决了单一 API 的上下文成本问题。但代理很少只与一个服务通信。一个开发者的代理可能需要同时使用 Cloudflare API、GitHub、数据库和内部文档服务器。每一个新增的 MCP 服务器都会带来我们最初面临的上下文窗口压力。

为此，Cloudflare MCP 服务器门户（Server Portals）允许您在单一网关后组合多个 MCP 服务器，并提供统一的身份验证和访问控制。我们正在为您的所有 MCP 服务器构建一流的代码模式集成，并通过内置的渐进式发现和相同的固定 Token 消耗量将它们暴露给代理——无论网关背后有多少个服务。

wsl-docs

探索