零成本将MCP服务器部署到Cloudflare Workers实战指南

本地运行的MCP服务器正在成为团队协作的瓶颈：每台机器都要装Node、配置环境变量，API密钥散落在各人的配置文件里，云端Agent更是无法调用你笔记本上的进程。把MCP服务器搬到Cloudflare Workers上，用Streamable HTTP协议对外提供统一URL，或许是当前最省事的解法。

为什么要把MCP服务器搬到远程

大多数MCP教程教的都是本地模式：Claude Desktop、Cursor、VS Code等客户端spawn一个进程，通过stdin/stdout通信。一个人用没问题，但一旦团队共享就会暴露三个痛点。

• 环境不一致：Node版本不同、缺env变量，每个人一套配置。
• 密钥分散：数据库或第三方API的key被复制到每个人的本地config文件里。
• 云端客户端调不动：跑在云上的agent根本无法spawn你机器上的进程。

Remote MCP走的是Streamable HTTP传输（MCP规范2025-03-26版本引入，取代旧的HTTP+SSE）。客户端只需要一个URL和一个token，密钥留在服务端，要更新就重新部署一次，全团队自动用上新版本。

Cloudflare Workers适合这个场景的原因很直接：免费额度每天10万次请求，冷启动几乎为零，SQLite版Durable Objects也已进入免费计划。每个MCP会话的状态存在独立的Durable Object里。

MCP（Model Context Protocol） 是由 Anthropic 提出并开源的一套标准协议，用于让 AI 应用（如 Claude Desktop、Cursor、VS Code 等客户端）以统一的方式连接外部工具与数据源。它的核心价值在于把「模型能调用什么」从各家私有的插件机制中抽离出来，形成客户端与服务器解耦的生态：服务器只需声明自己提供哪些工具（tools）、资源（resources）和提示（prompts），任何支持 MCP 的客户端都能接入。本地模式下 MCP 服务器以子进程形式运行，通过 stdin/stdout 交换 JSON-RPC 消息；远程模式则把传输层换成 HTTP，使服务器可以部署在云端被多方共享。理解这层客户端/服务器分离的设计，是理解本文为何要「搬家」的前提。

Streamable HTTP 是 MCP 规范在 2025-03-26 版本中引入的传输方式，用来取代早期的 HTTP+SSE 方案。旧方案要求客户端先建立一条长连接 SSE 通道接收服务端推送，再用单独的 POST 端点发送请求，两条通道需要维护会话关联，在无服务器环境和中间代理下容易断连。Streamable HTTP 把两者合并到单一端点：客户端向同一 URL POST JSON-RPC 消息，服务端可以直接返回 JSON，也可以在需要流式推送时把响应体切换为 SSE 流。这种「按需升级为流」的模型对 Cloudflare Workers 这类无状态边缘运行时更友好，也让客户端配置简化为一个 URL 加鉴权头。

五分钟搭起项目骨架

作者用的是wrangler 4.x、Cloudflare的agents包和官方@modelcontextprotocol/sdk，需要Node 20以上。

npm create cloudflare@latest mcp-notes -- --type=hello-world --lang=ts
cd mcp-notes
npm install agents @modelcontextprotocol/sdk zod

npx wrangler kv namespace create NOTES
npx wrangler secret put MCP_TOKEN

接着在wrangler.jsonc里声明Durable Object和KV绑定。这里有个高频踩坑点：免费计划必须用new_sqlite_classes，如果写成旧式的new_classes，部署时会直接报错。

实现工具、输入校验与鉴权

服务端只做两件事：save_note把笔记写进KV，search_notes按关键词检索。核心类继承McpAgent，在init()里注册工具。

几个实战中总结出来的要点：

1. 所有输入用Zod设限（如max(5000)、min(2)）。LLM偶尔会塞进来几十KB的文本，有schema就能在入口拦掉，不会污染KV。
2. 工具描述就是prompt。模型靠description判断要不要调用，写清楚它做什么比写长更重要。
3. 限制返回条数（示例里是10条）。返回太多文本会吃掉context window，token账单是你付的。
4. 静态bearer token足够内部工具使用。如果要对外开放，再换成@cloudflare/workers-oauth-provider做OAuth。

鉴权逻辑放在Worker的fetch入口：比对Authorization头与env.MCP_TOKEN，通过后把/mcp路径交给NotesMCP.serve("/mcp")处理，其余返回404。

Durable Objects 是 Cloudflare Workers 平台上的有状态计算原语：每个对象实例拥有唯一的 ID 和私有的持久化存储，平台保证同一 ID 的请求始终路由到同一个实例，从而提供强一致的会话状态。对 MCP 而言这很关键——远程服务器需要记住某个会话初始化时的能力协商、订阅关系等上下文，而普通 Worker 是无状态且会在全球多节点运行的。早期 Durable Objects 仅支持键值型存储且需付费，后来新增了内建 SQLite 存储（即 new_sqlite_classes 所声明的类型），可通过 this.sql 直接执行 SQL 查询，并纳入了免费计划。本文正是利用这一点，把关键词检索从逐条 KV 读取改为 SQL 的 LIKE 查询。

测试、部署与客户端接入

先在本地跑npx wrangler dev（默认http://localhost:8787），另开终端启动npx @modelcontextprotocol/inspector，transport选Streamable HTTP，URL填http://localhost:8787/mcp，加上Authorization头逐个测工具。确认无误后wrangler deploy，再用curl发一条initialize做冒烟测试。

curl那一步有个容易卡半天的细节：Accept头必须同时包含application/json和text/event-stream。漏掉后者，服务端会返回406，而错误信息不会告诉你是这个原因。

如果客户端只支持stdio（比如某些旧版Claude Desktop），可以用mcp-remote做桥接：

npx mcp-remote https://.../mcp --header "Authorization: Bearer ${TOKEN}"

成本与配额的真实边界

作者团队6人，每天几千次请求，仍在免费额度内。真正需要盯的是KV读取次数——免费计划每天10万次read。上面search_notes里那个逐条get的循环相当耗read，笔记涨到几千条时，作者切换到了Durable Object内的SQLite（this.sql），用LIKE查询替代遍历。

mcp-remote 是一个社区维护的桥接工具，作用是在只支持 stdio 传输的 MCP 客户端与远程 Streamable HTTP 服务器之间做协议转换：它在本地以子进程形式被客户端启动，对客户端表现为标准的 stdio 服务器，同时在内部向远程 URL 发起 HTTP 请求并转发消息。--header 参数用于附加鉴权头，使远程服务端能校验 bearer token。这条路径让尚未支持远程传输的旧版客户端也能接入远程服务器，代价是多一层本地进程和一定的启动延迟。当客户端原生支持 Streamable HTTP 后，就可以去掉这层桥接直接填 URL。

值得照搬的几条实践

• 从1到2个真正有用的工具起步（内部查询、读日志），别一上来就包整个API。
• migrations里务必用new_sqlite_classes，否则免费计划跑不起来。
• 输入用Zod校验，输出限制尺寸，省的是自己的token。
• 第一天就上鉴权：wrangler secret存bearer token，要公开再升级OAuth。
• 先用MCP Inspector测通再连真实客户端，别忘了那个双值Accept头。
• 在dashboard盯KV/DO配额，read涨得快就把搜索迁到SQLite。

按作者的估算，做出第一版只需要一个下午。对想把AI工具从个人玩具变成团队基础设施的开发者来说，这条路径的门槛已经低到值得立刻试一次。