本指南展示如何在 Cloudflare 上使用 Streamable HTTP 传输 部署远程 MCP server。你有两种选择:
- 无身份验证 — 任何人可连接并使用 server(无需登录)。
- 带身份验证与授权 — 用户访问 tool 前需登录,你可按用户权限控制 Agent 可调用的 tool。
本指南中的模板使用 Agents SDK 的 createMcpHandler 构建服务器。处理程序是无状态的:每个请求都会通过工厂函数获取一个新的 McpServer,因此服务器无需 Durable Object 或会话。需要跨请求保留的数据应存放在 KV、D1 或 Durable Object 等绑定中。
要迁移现有的 McpAgent 服务器,请参阅迁移到 MCP SDK v2。已弃用的 API 记录在 McpAgent 参考中。
可先部署公开 MCP server ↗(无身份验证),之后再添加用户身份验证与范围授权。若已知 server 需要身份验证,可跳至下一节。
下方按钮将引导你在 Cloudflare 账户中部署示例 MCP server ↗:
部署后,服务器会在你的 workers.dev 子域名上线(例如 remote-mcp-server-authless.your-account.workers.dev/mcp)。你可以立即通过 AI Playground ↗(远程 MCP 客户端)、MCP inspector ↗ 或其他 MCP 客户端连接它。
系统会在你的 GitHub 或 GitLab 账户创建新的 git 仓库,并配置为每次 push 或合并 PR 到 main 分支时自动部署到 Cloudflare。你可克隆该仓库、本地开发,并开始用自定义 tool 定制 MCP server。
可使用 Wrangler CLI 在本地创建 MCP Server 并部署到 Cloudflare。
-
打开终端并运行:
npm create cloudflare@latest -- remote-mcp-server-authless --template=cloudflare/ai/demos/remote-mcp-authlessyarn create cloudflare remote-mcp-server-authless --template=cloudflare/ai/demos/remote-mcp-authlesspnpm create cloudflare@latest remote-mcp-server-authless --template=cloudflare/ai/demos/remote-mcp-authless设置过程中选择:- 对于 Do you want to add an AGENTS.md file to help AI coding tools understand Cloudflare APIs?(是否添加 AGENTS.md 以帮助 AI 编码工具理解 Cloudflare API?),选
No。- 对于 Do you want to use git for version control?(是否使用 git 进行版本控制?),选No。- 对于 Do you want to deploy your application?(是否部署应用?),选No(部署前先测试服务器)。此时 MCP server 已就绪,依赖已安装。
-
进入项目目录:
cd remote-mcp-server-authless -
在项目目录中运行以下命令启动开发 server:
npm start⎔ Starting local server... [wrangler:info] Ready on http://localhost:8788查看命令输出中的本地端口。本例中 MCP server 运行在端口
8788,MCP 端点 URL 为http://localhost:8788/mcp。 -
本地测试 server:
-
在新终端运行 MCP inspector ↗。MCP inspector 是交互式 MCP 客户端,可在浏览器中连接 MCP server 并调用 tool。
npx @modelcontextprotocol/inspector@latest🚀 MCP Inspector is up and running at: http://localhost:5173/?MCP_PROXY_AUTH_TOKEN=46ab..cd3 🌐 Opening browser...MCP Inspector 会在浏览器中启动。也可手动打开浏览器访问
http://localhost:<PORT>。查看命令输出中 MCP Inspector 的本地端口。本例中为端口5173。 -
在 MCP inspector 中输入 MCP server URL(
http://localhost:8788/mcp),选择 Connect(连接)。选择 List Tools(列出工具) 查看 server 暴露的 tool。
-
-
现在可将 MCP server 部署到 Cloudflare。在项目目录运行:
npx wrangler@latest deploy若已将 git 仓库连接到 Worker(含 MCP server),push 变更或合并 PR 到 main 分支即可部署。
MCP 服务器将部署到你的
*.workers.dev子域:https://remote-mcp-server-authless.your-account.workers.dev/mcp。 -
测试远程 MCP server:将已部署 MCP server 的 URL(
https://remote-mcp-server-authless.your-account.workers.dev/mcp)输入运行在http://localhost:5173的 MCP inspector。
你现在拥有 MCP 客户端可连接的远程 MCP server。
将支持 Streamable HTTP 的 MCP 客户端直接连接到已部署的端点。以下示例将服务器添加到 Claude Code:
claude mcp add --transport http math https://remote-mcp-server-authless.your-account.workers.dev/mcp运行 claude mcp list 验证连接。然后让 Claude 使用其中一个工具。例如:
Could you use the math tool to add 23 and 19?Claude 应调用该工具并显示服务器响应。
其他客户端请参阅测试远程 MCP 服务器。
你部署的服务器接受任意客户端。若要要求用户登录,请将服务器置于使用 Workers OAuth Provider ↗ 构建的 OAuth 授权服务器之后:
- 使用
OAuthAuthorizationServer构建授权服务器 Worker。其/authorize页面可直接为用户登录,也可通过 GitHub、Google、Cloudflare Access 或其他身份提供方登录。 - 将 MCP 服务器的
createMcpHandler包装在OAuthResourceServer中;它会通过 Service Binding 向授权服务器检查每个请求所带的令牌。
MCP 客户端会从 MCP 服务器的 401 响应中发现授权服务器,为用户登录,然后携带令牌重试。你的工具可通过 getMcpAuthContext() 读取已登录用户。
完整的两个 Worker 请参阅授权。