MCP Server 部署到 Cloudflare Workers：从边缘跑 MCP

Cloudflare Workers 是部署 MCP Server 的理想边缘平台--低延迟、按请求付费、快启动。本文给完整路径。

1. 为何选 Workers

部署 MCP Server 的常见选项：

Workers 的优势：全球边缘延迟 + 按请求付费 + KV/D1/R2 配套。

2. stdio vs Streamable HTTP

MCP 有两种传输：

• stdio：本地进程（Host 拉起 server 二进制，通过 stdin/stdout 通信）
• Streamable HTTP：HTTP + SSE（Server 暴露 HTTP endpoint，Host 通过 POST + GET-SSE 调用）

Workers 只能跑 Streamable HTTP--因为 Workers 是 edge runtime，没有 stdin/stdout 进程。

改造方法：用 @modelcontextprotocol/sdk 的 StreamableHTTPServerTransport 替代 StdioServerTransport：

import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

const transport = new StreamableHTTPServerTransport({
  sessionIdGenerator: undefined,  // stateless
});

server.connect(transport);

// Workers fetch handler
export default {
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    return transport.handleRequest(request);
  }
};

3. Edge Runtime 限制

Workers Edge Runtime 不是 Node.js--以下不可用：

• fs（文件系统）
• child_process（子进程）
• setImmediate / process.nextTick
• 任何 Node.js 内置模块（除 fetch / crypto / streams / URL 等 Web 标准）

代码要：

• 只用 Web 标准 API（fetch、crypto.subtle、TransformStream）
• 用 Workers KV / D1 / R2 替代本地存储
• 长任务用 ctx.waitUntil 异步
• 不能 require Node.js 包；用 esbuild 兼容的 npm 包（多数现代 SDK 都兼容）

4. CPU 时间限制

MCP tool call 通常 CPU 密集度低（IO bound）--5ms 多数情况够；复杂计算（爬虫 + 解析）上 Unbound。

5. KV 持久化

Workers KV（边缘 key-value 存储）适合 MCP 场景：

// 读
const counter = await env.MCP_KV.get("rate_limit:user_123", { type: "json" });

// 写
await env.MCP_KV.put("rate_limit:user_123", JSON.stringify({ count: counter + 1 }));

KV 特性：

• Eventual consistency（全球 < 60 秒收敛）
• 单 key ≤ 25MB value
• 适合 rate limit / 缓存 / 偏好设置

不适合强一致场景（用 D1 SQLite）。

6. wrangler.jsonc 配置

{
  "name": "my-mcp-server",
  "main": "src/index.ts",
  "compatibility_date": "2026-08-01",
  "compatibility_flags": ["nodejs_compat"],  // 兼容部分 Node.js API
  "vars": {
    "LOG_LEVEL": "info"
  },
  "kv_namespaces": [
    { "binding": "MCP_KV", "id": "xxx" }
  ],
  "secrets": [
    "GITHUB_CLIENT_SECRET",  // 用 wrangler secret put 设置
    "API_KEY"
  ]
}

secrets 不进 git--用 wrangler secret put GITHUB_CLIENT_SECRET 设置。

7. 部署 + 监控

# 本地开发
wrangler dev

# 部署
wrangler deploy

# 查看日志
wrangler tail

# 设置 secrets
wrangler secret put GITHUB_CLIENT_SECRET

Cloudflare dashboard 提供：

• 请求 / 错误率实时监控
• CPU 时间使用（识别性能问题）
• KV 读写量

配 alerts：5xx 率 > 5% 持续 5 分钟触发报警。

8. 实战踩坑

• nodejs_compat flag：部分 Node.js 包（特别是 zod / pnpm 包）需要这个 flag 才能跑
• 冷启动：首次请求 50-100ms warm-up；用户第一次调 MCP 体验稍慢
• Worker size limit：1MB 压缩后；含 SDK 后通常 200-400KB
• CORS：MCP Host（ChatGPT 网页）从不同域调你的 Worker；需要配置 CORS 允许 * 或 ChatGPT 域

9. 下一步

• 《自己搭一个 MCP Server：从零到发布的完整指南》 - stdio MCP 完整路径
• 《Model Context Protocol 完全指南：MCP 工作机制与实战》 - 协议深入
• 《OpenAI API 错误处理与重试》 - 推理层稳定性

更新记录

• 2026-08-08：首次发布