跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

构建远程 MCP server

最后更新 查看 MarkdownAgent 设置

本指南展示如何在 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

可先部署公开 MCP server ↗(无身份验证),之后再添加用户身份验证与范围授权。若已知 server 需要身份验证,可跳至下一节。

通过仪表板

下方按钮将引导你在 Cloudflare 账户中部署示例 MCP server ↗:

部署到 Workers

部署后,服务器会在你的 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。

通过 CLI

可使用 Wrangler CLI 在本地创建 MCP Server 并部署到 Cloudflare。

  1. 打开终端并运行:

    npm 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 已就绪,依赖已安装。

  2. 进入项目目录:

    cd remote-mcp-server-authless
  3. 在项目目录中运行以下命令启动开发 server:

    npm start
    ⎔ Starting local server...
    [wrangler:info] Ready on http://localhost:8788

    查看命令输出中的本地端口。本例中 MCP server 运行在端口 8788,MCP 端点 URL 为 http://localhost:8788/mcp。

  4. 本地测试 server:

    1. 在新终端运行 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。

    2. 在 MCP inspector 中输入 MCP server URL(http://localhost:8788/mcp),选择 Connect(连接)。选择 List Tools(列出工具) 查看 server 暴露的 tool。

  5. 现在可将 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。

  6. 测试远程 MCP server:将已部署 MCP server 的 URL(https://remote-mcp-server-authless.your-account.workers.dev/mcp)输入运行在 http://localhost:5173 的 MCP inspector。

你现在拥有 MCP 客户端可连接的远程 MCP server。

从 MCP 客户端连接

将支持 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 授权服务器之后:

  1. 使用 OAuthAuthorizationServer 构建授权服务器 Worker。其 /authorize 页面可直接为用户登录,也可通过 GitHub、Google、Cloudflare Access 或其他身份提供方登录。
  2. 将 MCP 服务器的 createMcpHandler 包装在 OAuthResourceServer 中;它会通过 Service Binding 向授权服务器检查每个请求所带的令牌。

MCP 客户端会从 MCP 服务器的 401 响应中发现授权服务器,为用户登录,然后携带令牌重试。你的工具可通过 getMcpAuthContext() 读取已登录用户。

完整的两个 Worker 请参阅授权。

后续步骤

授权

添加授权服务器并让用户登录。

这篇文档对您有帮助吗?