Code Mode：用约 1000 tokens 让 Agent 掌控整个 API-ByteNews

一句话概括Cloudflare 推出 Code Mode，通过一个全新的 MCP 服务器，将拥有 2500+ endpoints 的完整 Cloudflare API 压缩为仅占约 1000 tokens 的两个工具：search() 和 execute()。这让 AI Agent 能在几乎不占用上下文的前提下，安全、可编程地访问和操作整个 API，相比传统方式节省 99.9% tokens（传统需约 117 万 tokens）。注意啊，这是一个通用能力思路，用在 Agents 的实现中极好。

MCP 与 Code Mode 的核心问题与解决方案

MCP（Model Context Protocol）已成为 AI Agent 调用外部工具的事实标准。
核心问题：Agent 要完成有用任务需要大量工具，但每增加一个工具定义就会消耗上下文 tokens，快速挤占真正任务的空间。
Code Mode 的思路：不再为每个具体操作单独定义工具，而是让模型编写 JavaScript/TypeScript 代码，对着强类型 SDK 或完整 OpenAPI 规范编程。代码本身成为高度压缩的「执行计划」，由服务端沙箱安全执行后，仅返回必要结果。

Cloudflare 此次发布全新的 Cloudflare MCP 服务器，首次将服务器端 Code Mode 应用于整个 Cloudflare API。

效果对比：

传统 MCP 实现：描述全部 2500+ endpoints 需要约 117 万 tokens（1.17 million），已超过最先进大模型的完整上下文窗口。
使用 Code Mode 后：工具定义固定约 1000 tokens，节省 99.9% 输入 tokens。

Cloudflare 已开源 Code Mode SDK（Cloudflare Agents SDK 的一部分），开发者可直接在自己的 MCP Server 或 Agent 中复用。

服务器端 Code Mode：仅用两个工具覆盖整个 API

新 MCP 服务器把 Code Mode 放在服务端，仅暴露两个极简工具：

search()描述：用 JavaScript 代码搜索 Cloudflare 的完整 OpenAPI 规范（所有 $ref 已预先内联展开）。参数：code —— 异步 JS 箭头函数，用于在 spec 对象上查询、过滤。
execute()描述：在沙箱中执行 JS 代码，对 Cloudflare API 发起已鉴权请求。参数：code —— 异步 JS 箭头函数，代码内可调用 cloudflare.request() 客户端。

search()：通过代码在 OpenAPI Spec 上发现能力

Agent 调用 search() 时，服务端传入一个完整的 spec 对象（全部引用已展开）。模型只需编写 JS 代码遍历路径、tag、产品等信息进行筛选。

关键优势：完整 OpenAPI Spec 永远不进入模型上下文，只有代码执行结果返回，从而极大节省 tokens。

search() 到底长什么样？

工具定义（固定不变，只有这一个参数）：

json{ "name": "search", "description": "Search the Cloudflare OpenAPI spec. All $refs are pre-resolved inline.", "inputSchema": { "type": "object", "properties": { "code": { "type": "string", "description": "JavaScript async arrow function to search the OpenAPI spec" } }, "required": ["code"] } }

{
  "name": "search",
  "description": "Search the Cloudflare OpenAPI spec. All $refs are pre-resolved inline.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "code": {
        "type": "string",
        "description": "JavaScript async arrow function to search the OpenAPI spec"
      }
    },
    "required": ["code"]
  }
}

Agent 调用时，只需要传一个字符串——一段异步箭头函数的 JS 代码。

真实调用流程（后文有示例）

Agent 决定要查什么 → 写一段 JS 代码
调用工具：把代码塞进 code 参数
服务器收到 → 在沙箱里执行，spec 对象自动可用
执行结果 → 只返回给 Agent（几行 JSON）

execute()：在沙箱中安全执行 API 操作

json{ "name": "execute", "description": "Execute JavaScript code against the Cloudflare API.", "inputSchema": { "type": "object", "properties": { "code": { "type": "string", "description": "一段异步 JS 箭头函数，里面可以调用 cloudflare.request()" } }, "required": ["code"] } }

{
  "name": "execute",
  "description": "Execute JavaScript code against the Cloudflare API.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "code": {
        "type": "string",
        "description": "一段异步 JS 箭头函数，里面可以调用 cloudflare.request()"
      }
    },
    "required": ["code"]
  }
}

代码在 Dynamic Worker isolate（基于 V8 的轻量级沙箱）中运行，支持：

单次代码内完成多个 endpoint 调用、分页、响应检查、链式逻辑等。
沙箱限制：无文件系统、无环境变量（防止 prompt injection 泄露密钥）、默认禁用外部 fetch（仅允许显式配置的 outbound handler）。

实际例子：为源站开启 DDoS 防护

用户指令：“帮我保护我的源站不被 DDoS 攻击。”

Agent 典型流程（仅需约 4 次工具调用）：

发现相关 endpoints（search()）：编写 JS 遍历 spec.paths，过滤含 /zones/ 且涉及 firewall/waf 或 rulesets 的路径，从 2500+ 中快速缩小到十几个关键接口。
深入了解 Schema（再次 search()）：查询 ruleset phases 的 enum 值，得到 ["ddos_l4", "ddos_l7", "http_request_firewall_custom", "http_request_firewall_managed", ...]，从而确定 DDoS 用 ddos_l7、WAF 用 http_request_firewall_managed。深入了解 Schema（再次搜索()）：查询 ruleset phases 的枚举值，得到["ddos_l4"、"ddos_l7"、"http_request_firewall_custom"、"http_request_firewall_managed"等。由此可以确定，在 DDoS 防护中应使用 ddos_l7，而在 WAF 防护中则应使用 http_request_firewall_managed。
执行操作（execute()）：单段代码内先 GET 当前 rulesets → 识别现有 DDoS L7 / WAF managed 配置 → 链式 PATCH entrypoint 调整敏感度、开启规则。

json// Agent 发送的 code 参数内容（完整字符串） async () => { const results = []; for (const [path, methods] of Object.entries(spec.paths)) { if (path.includes('/zones/') && (path.includes('firewall/waf') || path.includes('rulesets'))) { for (const [method, op] of Object.entries(methods)) { results.push({ method: method.toUpperCase(), path, summary: op.summary }); } } } return results; // 或者直接写 results; 也行 }

// Agent 发送的 code 参数内容（完整字符串）
async () => {
  const results = [];
  for (const [path, methods] of Object.entries(spec.paths)) {
    if (path.includes('/zones/') && 
        (path.includes('firewall/waf') || path.includes('rulesets'))) {
      for (const [method, op] of Object.entries(methods)) {
        results.push({ 
          method: method.toUpperCase(), 
          path, 
          summary: op.summary 
        });
      }
    }
  }
  return results;   // 或者直接写 results; 也行
}

服务器返回给 Agent 的结果（大大缩小后的列表，只有 10 条左右）：

json[ { "method": "GET", "path": "/zones/{zone_id}/firewall/waf/packages", "summary": "List WAF packages" }, { "method": "PATCH", "path": "/zones/{zone_id}/firewall/waf/packages/{package_id}", "summary": "Update a WAF package" }, { "method": "GET", "path": "/zones/{zone_id}/rulesets", "summary": "List zone rulesets" }, { "method": "POST", "path": "/zones/{zone_id}/rulesets", "summary": "Create a zone ruleset" }, { "method": "GET", "path": "/zones/{zone_id}/rulesets/phases/{ruleset_phase}/entrypoint", "summary": "Get a zone entry point ruleset" }, // ... 还有几条类似 ]

[
  { "method": "GET",    "path": "/zones/{zone_id}/firewall/waf/packages",              "summary": "List WAF packages" },
  { "method": "PATCH",  "path": "/zones/{zone_id}/firewall/waf/packages/{package_id}", "summary": "Update a WAF package" },
  { "method": "GET",    "path": "/zones/{zone_id}/rulesets",                           "summary": "List zone rulesets" },
  { "method": "POST",   "path": "/zones/{zone_id}/rulesets",                           "summary": "Create a zone ruleset" },
  { "method": "GET",    "path": "/zones/{zone_id}/rulesets/phases/{ruleset_phase}/entrypoint", "summary": "Get a zone entry point ruleset" },
  // ... 还有几条类似
]

一下子从 2500+ 个接口缩小到 10 个，完美!

然后，Agent 像调用普通工具一样调用 execute()，只是把一整段 JS 代码塞进 code 参数里。

最标准的调用方式（Agent 实际发出去的）：

json// Agent 发送的完整工具调用（伪代码，真实系统会转成 JSON） execute({ code: async () => { // 这里写你想让服务器执行的所有操作 const response = await cloudflare.request({ method: "GET", path: "/zones/12345678901234567890123456789012/rulesets" }); // 可以继续写更多操作、判断、返回想要的结果 return response.result; } })

// Agent 发送的完整工具调用（伪代码，真实系统会转成 JSON）
execute({
  code: `async () => {
    // 这里写你想让服务器执行的所有操作
    const response = await cloudflare.request({
      method: "GET",
      path: "/zones/12345678901234567890123456789012/rulesets"
    });
    
    // 可以继续写更多操作、判断、返回想要的结果
    return response.result;
  }`
})

服务器收到后：

把这段代码丢进沙箱运行
自动注入 cloudflare.request() 这个已鉴权的客户端
执行完毕 → 只把 return 的结果发回给 Agent

更详细的示例请参见原文。

此前 Cloudflare 按产品拆分 MCP 服务器（DNS、Workers Observability 等），工具少时可用，但覆盖 2500+ endpoints 几乎不可能手工维护。

由此可见 CodeMode 的优势：

固定低开销：无论 API 多大，工具 token 成本恒定 ~1000 tokens。
自动适配：新产品、新 endpoint 上线后无需更新工具定义或新建服务器，search() 即可自动发现。
全面覆盖：包含 GraphQL Analytics API。
安全鉴权：遵循最新 MCP 规范，使用 OAuth 2.1（Cloudflare Workers OAuth Provider）。连接时跳转 Cloudflare 页面，用户精确选择权限范围，token 自动 downscope。

我们能学习的是啥？

后面可能只需一个简单 Agent loop，即可赋予 Agent 完整 API 能力 + 渐进式能力发现（progressive capability discovery）。

其他「工具上下文压缩」方案对比

客户端 Code Mode模型在客户端写 TS 代码，对 typed SDK 编程，在本地 Dynamic Worker Loader 执行（如 Goose、Anthropic Claude SDK 的 Programmatic Tool Calling）。缺点：Agent 侧需安全沙箱环境。
命令行方式（CLI）MCP 转为自文档化 CLI（如 OpenClaw、Moltworker、MCPorter）。缺点：需 shell 环境，攻击面更大。
动态工具搜索（如 Claude Code）先检索仅暴露相关工具子集。缺点：仍需维护搜索逻辑，且匹配工具仍会消耗 tokens。

服务器端 Code Mode 兼具所有优势：token 开销与 API 规模无关、Agent 无需改造、内建渐进式发现、执行完全沙箱安全。

Agent 的心智模型极其简单：只需学会用代码调用这两个工具，其余复杂度全在服务端。

# 开发者只需要写这个 loop（超级简单，几十行代码）
while True:
    # 第1步：让大模型思考当前情况 + 目标
    thought = llm.think(历史对话 + 当前工具列表)

    # 第2步：大模型决定下一步
    if 需要结束:
        return 最终答案
    else:
        # 这里只会返回两种可能：search() 或 execute()
        tool_call = llm.decide_which_tool_and_what_code_to_run(thought)

    # 第3步：执行工具（服务端自动处理）
    result = run_tool(tool_call)          # search 或 execute

    # 第4步：把结果塞回对话，让大模型继续思考
    历史对话.append(result)

简单说下如何使用 Code Mode SDK 实现上述能力

操作步骤（10-30 分钟就能跑通原型）：

用 Cloudflare 开源的 @cloudflare/codemode SDK（npm install @cloudflare/codemode）使用 Cloudflare 开源的 @cloudflare/codemode SDK（npm install @cloudflare/codemode）
把你所有工具定义成普通函数（用 Zod 或 TypeScript 类型描述就行）
写一个极简 MCP Server，只暴露两个工具。
Agent 只看到这两个工具，用简单 loop 就能调用你的全部功能。

const codemode = createCodeTool({
  tools: { ...myCustomTools, ...otherMcpTools },  // ← 这里放你自己写的全部工具
  executor: myCustomExecutor   // 你自己的沙箱（Node VM、Deno、Docker 都行）
});

优点：工具再多（甚至 5000 个）也无所谓；新工具上线不用改任何代码，Agent 用 search() 自动发现。

未来展望：MCP Server Portals

未来展望：MCP 服务器门户

Agent 常需同时对接多个服务（Cloudflare + GitHub + 数据库等），多个 MCP Server 会累积上下文压力。

Cloudflare 正在推出 MCP Server Portals：把多个 MCP Server 聚合在统一网关后，实现统一鉴权和访问控制，对 Agent 暴露单一入口。未来所有 MCP Server 都将原生集成 Code Mode，无论背后挂多少服务，Agent 仍只看到固定 token 开销 + 一致的渐进式发现体验。

目录CONTENT

Code Mode：用约 1000 tokens 让 Agent 掌控整个 API

实际例子：为源站开启 DDoS 防护

我们能学习的是啥？

评论区