构建单工具 Code Mode MCP server

使用 codeMcpServer() 包装现有 Model Context Protocol (MCP) 服务器。MCP 客户端收到一个 code 工具，而不是每个上游工具。

code 工具包含上游工具的生成类型定义。模型编写的 JavaScript 可调用多个工具、处理结果并返回一个聚焦值。

前置条件

需要 Cloudflare Workers 项目与现有 McpServer。

包装 server

安装 Code Mode 与 MCP 依赖：
npm i @cloudflare/codemode agents @modelcontextprotocol/sdk zod
yarn add @cloudflare/codemode agents @modelcontextprotocol/sdk zod
pnpm add @cloudflare/codemode agents @modelcontextprotocol/sdk zod
bun add @cloudflare/codemode agents @modelcontextprotocol/sdk zod

添加 Worker Loader 绑定与 nodejs_compat 兼容性标志：

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "name": "codemode-mcp-server",
  "main": "src/server.ts",
  // Set this to today's date
  "compatibility_date": "2026-08-17",
  "compatibility_flags": [
    "nodejs_compat"
  ],
  "worker_loaders": [
    {
      "binding": "LOADER"
    }
  ]
}

name = "codemode-mcp-server"
main = "src/server.ts"
# Set this to today's date
compatibility_date = "2026-08-17"
compatibility_flags = ["nodejs_compat"]

[[worker_loaders]]
binding = "LOADER"

创建 upstream server 并传给 codeMcpServer()：

src/server.jsjs

import { DynamicWorkerExecutor } from "@cloudflare/codemode";
import { codeMcpServer } from "@cloudflare/codemode/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { createMcpHandler } from "agents/mcp";
import { z } from "zod";

function createOrderServer() {
	const server = new McpServer({
		name: "orders",
		version: "1.0.0",
	});

	server.registerTool(
		"get_order",
		{
			description: "Get an order by ID",
			inputSchema: {
				orderId: z.string().describe("Order ID"),
			},
		},
		async ({ orderId }) => ({
			structuredContent: {
				id: orderId,
				status: "processing",
			},
			content: [
				{
					type: "text",
					text: JSON.stringify({ id: orderId, status: "processing" }),
				},
			],
		}),
	);

	return server;
}

export default {
	async fetch(request, env, ctx) {
		const upstream = createOrderServer();
		const executor = new DynamicWorkerExecutor({ loader: env.LOADER });
		const server = await codeMcpServer({
			server: upstream,
			executor,
		});

		return createMcpHandler(server, { route: "/mcp" })(request, env, ctx);
	},
};

src/server.tsts

import { DynamicWorkerExecutor } from "@cloudflare/codemode";
import { codeMcpServer } from "@cloudflare/codemode/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { createMcpHandler } from "agents/mcp";
import { z } from "zod";

function createOrderServer() {
	const server = new McpServer({
		name: "orders",
		version: "1.0.0",
	});

	server.registerTool(
		"get_order",
		{
			description: "Get an order by ID",
			inputSchema: {
				orderId: z.string().describe("Order ID"),
			},
		},
		async ({ orderId }) => ({
			structuredContent: {
				id: orderId,
				status: "processing",
			},
			content: [
				{
					type: "text",
					text: JSON.stringify({ id: orderId, status: "processing" }),
				},
			],
		}),
	);

	return server;
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const upstream = createOrderServer();
		const executor = new DynamicWorkerExecutor({ loader: env.LOADER });
		const server = await codeMcpServer({
			server: upstream,
			executor,
		});

		return createMcpHandler(server, { route: "/mcp" })(
			request,
			env,
			ctx,
		);
	},
} satisfies ExportedHandler<Env>;

部署 Worker：
npx wrangler deploy
yarn wrangler deploy
pnpm wrangler deploy
在 MCP client 中连接到 https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/mcp。确认 server 暴露名为 code 的单个 tool。

模型可在 code tool 内使用生成的 codemode 命名空间：

async () => {
	const order = await codemode.get_order({ orderId: "order-123" });
	return { id: order.id, status: order.status };
};

上游工具返回 structuredContent 时，Code Mode 直接暴露该值。仅文本的内容会拼接，并在可能时解析为 JSON。上游 MCP 错误变为模型代码可捕获的异常。混合文本与二进制内容保留 MCP 结果结构。

若提供自定义 description，在生成 TypeScript 声明应出现处使用 {{types}}。在 SDK 应插入基于第一个上游 MCP 工具的示例调用处使用 {{example}}。两个占位符均为可选。

保护上游操作

codeMcpServer() 不为每个上游工具调用提供持久审批。它在外层 code 工具内从内部调用上游处理程序。

在产生副作用前于每个上游处理程序强制执行授权与任何每操作审批。不要在工具结果中包含凭证。

DynamicWorkerExecutor 默认阻止外部 fetch() 与 connect()。生成的代码仅能通过上游 MCP 工具到达外部系统。

限制结果

模型代码可在返回前选择、映射、聚合或分页上游数据。防止大型中间结果进入模型上下文。

发布方将最终 MCP 响应限制在约 6,000 估算 token。更大响应会被截断并含 --- TRUNCATED --- 标记。这不减少上游工具已执行的工作。

要发布带独立 search 与 execute 工具的 OpenAPI 服务，请参阅构建 search-and-execute MCP 服务器。