构建一个 Remote MCP server

本指南将向你展示如何在 Cloudflare 上,使用 Streamable HTTP transport(当前 MCP 规范的标准)部署你自己的 remote MCP server。你有两种选择:

不带认证 —— 任何人都可以连接并使用该 server(无需登录)。
启用认证与授权 —— 用户必须先登录才能访问工具,你还可以根据用户权限控制 agent 能够调用哪些工具。

选择合适的方式

Agents SDK 提供多种创建 MCP server 的方式。请按你的用例选择合适的方案:

方式	是否有状态?	是否需要 Durable Objects?	适用场景
createMcpHandler()	否	否	无状态工具,设置最简单
McpAgent	是	是	有状态工具、按 session 的状态、elicitation
原始 WebStandardStreamableHTTPServerTransport	否	否	完全控制、不依赖 SDK

createMcpHandler() 是启动一个无状态 MCP server 最快的方式。当你的工具不需要按 session 的状态时使用。
McpAgent 给你每个 session 一个 Durable Object,内置 state 管理、elicitation 支持,以及 SSE 与 Streamable HTTP 两种 transport。
原始 transport 在你想直接使用 @modelcontextprotocol/sdk、不依赖 Agents SDK helper 时提供完全控制。

部署你的第一个 MCP server

你可以先部署一个不带认证的 public MCP server ↗,之后再加上用户认证与按权限范围的授权。如果你已经知道你的 server 一定需要认证,可以直接跳到下一节。

通过 Dashboard

下面的按钮会引导你完成把一个示例 MCP server ↗ 部署到你 Cloudflare 账户所需的所有步骤:

部署完成后,该 server 会在你的 workers.dev 子域名下上线(例如 remote-mcp-server-authless.your-account.workers.dev/mcp)。你可以立即用 AI Playground ↗(一个 remote MCP 客户端)、MCP inspector ↗ 或其他 MCP 客户端连接到它。

系统会在你的 GitHub 或 GitLab 账户上为你的 MCP server 建立一个新的 git 仓库,并配置为每次推送变更或合并 PR 到 main 分支时自动部署到 Cloudflare。你可以克隆该仓库,在本地开发,然后用你自己的 tools 自定义这个 MCP server。

通过 CLI

你可以使用 Wrangler CLI 在本地创建一个新的 MCP server,并部署到 Cloudflare。

打开终端并运行以下命令: npm yarn pnpm

npm create cloudflare@latest -- remote-mcp-server-authless --template=cloudflare/ai/demos/remote-mcp-authless

yarn create cloudflare remote-mcp-server-authless --template=cloudflare/ai/demos/remote-mcp-authless

pnpm 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?,选择 No。 - 对于 Do you want to use git for version control?,选择 No。 - 对于 Do you want to deploy your application?,选择 No(我们将先在本地测试再部署)。现在,你已经完成 MCP server 的初始化并安装好依赖。 2. 进入项目文件夹: Terminal window

cd remote-mcp-server-authless

在新项目目录下,运行以下命令启动开发服务器: Terminal window

npm start

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

查看命令输出确认本地端口。在本例中,MCP server 运行在 8788 端口,MCP 端点 URL 为 http://localhost:8788/mcp。注意你不能直接在浏览器中打开 /mcp URL 来与 MCP server 交互。/mcp 端点期望一个 MCP 客户端发送 MCP 协议消息,而浏览器默认不会这样做。下一步将演示如何使用 MCP 客户端连接到该 server。 4. 本地测试该 server:

在新终端运行 MCP inspector ↗。MCP inspector 是一个交互式 MCP 客户端,允许你从浏览器连接到 MCP server 并调用工具。 Terminal window

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 的本地端口。在本例中,MCP Inspector 在 5173 端口提供服务。 2. 在 MCP inspector 中,输入你的 MCP server URL(http://localhost:8788/mcp),然后选择 Connect。选择 List Tools 查看你的 MCP server 暴露的工具。 5. 现在你可以把你的 MCP server 部署到 Cloudflare。在项目目录下运行: Terminal window

npx wrangler@latest deploy

如果你已经为带 MCP server 的 Worker 接入了 git 仓库,只需推送变更或合并 PR 到 main 分支即可部署。 MCP server 将部署到你的 *.workers.dev 子域名,地址为 https://remote-mcp-server-authless.your-account.workers.dev/mcp。 6. 要测试已部署的 remote MCP server,把它的 URL(https://remote-mcp-server-authless.your-account.workers.dev/mcp)填入运行在 http://localhost:5173 上的 MCP inspector。

至此,你已经拥有了一个 MCP 客户端可以连接的 remote MCP server。

通过本地代理从 MCP 客户端连接

现在你的 remote MCP server 已经在运行,你可以使用 mcp-remote 本地代理 ↗ 把 Claude Desktop 或其他 MCP 客户端连接到它 —— 即使你的 MCP 客户端在客户端侧不支持 remote transport 或授权也可以。这样你可以测试真实 MCP 客户端与你的 remote MCP server 交互的体验。

例如,从 Claude Desktop 连接的步骤:

更新 Claude Desktop 配置,指向你 MCP server 的 URL:

{
  "mcpServers": {
    "math": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://remote-mcp-server-authless.your-account.workers.dev/mcp"
      ]
    }
  }
}

Explain Code 2. 重启 Claude Desktop 以加载该 MCP server。完成后,Claude 就能调用你的 remote MCP server。 3. 要测试,可让 Claude 使用你的某个工具。例如:

Could you use the math tool to add 23 and 19?

Claude 应当调用该工具,并显示由 remote MCP server 返回的结果。

要了解如何在其他 MCP 客户端中使用 remote MCP server,请参阅 Test a Remote MCP Server。

添加认证

前面部署的公开 MCP server 示例允许任何客户端连接并调用工具,无需登录。要为你的 MCP server 加上用户认证,你可以集成 Cloudflare Access 或某个第三方服务作为 OAuth 提供方。你的 MCP server 负责安全的登录流程,并向 MCP 客户端发放 access token,用于发起经过认证的工具调用。用户通过 OAuth 提供方登录,并以按权限范围(scope)的方式授予 AI agent 与你的 MCP server 暴露的工具进行交互的权限。

Cloudflare Access OAuth

你可以配置你的 MCP server,要求通过 Cloudflare Access 进行用户认证。Cloudflare Access 充当身份聚合器,可验证用户邮箱、来自现有 identity providers(如 GitHub 或 Google)的信号,以及 IP 地址或设备证书等其他属性。当用户连接到你的 MCP server 时,会被要求登录配置好的 identity provider,只有通过你的 Access policies 才会被授予访问权限。

详细的部署指南请参阅 Secure MCP servers with Access for SaaS。

第三方 OAuth

你可以将 MCP server 与任意支持 OAuth 2.0 规范的 OAuth provider 集成,包括 GitHub、Google、Slack、Stytch、Auth0、WorkOS 等。

下面的示例演示如何使用 GitHub 作为 OAuth provider。

Step 1 — 创建一个新的 MCP server

运行以下命令创建一个使用 GitHub OAuth 的新 MCP server:

npm yarn pnpm

npm create cloudflare@latest -- my-mcp-server-github-auth --template=cloudflare/ai/demos/remote-mcp-github-oauth

yarn create cloudflare my-mcp-server-github-auth --template=cloudflare/ai/demos/remote-mcp-github-oauth

pnpm create cloudflare@latest my-mcp-server-github-auth --template=cloudflare/ai/demos/remote-mcp-github-oauth

至此,MCP server 已经初始化好,依赖也已安装。进入项目文件夹:

Terminal window


cd my-mcp-server-github-auth

你会注意到,在示例 MCP server 中,如果打开 src/index.ts,主要的差别在于 defaultHandler 被设置为 GitHubHandler:

TypeScript


import GitHubHandler from "./github-handler";


export default new OAuthProvider({

  apiRoute: "/mcp",

  apiHandler: MyMCP.serve("/mcp"),

  defaultHandler: GitHubHandler,

  authorizeEndpoint: "/authorize",

  tokenEndpoint: "/token",

  clientRegistrationEndpoint: "/register",

});

Explain Code

这样可以确保用户被重定向到 GitHub 进行认证。但要让其正常运行,你需要按下面的步骤创建 OAuth client app。

Step 2 — 创建一个 OAuth App

你需要创建两个 GitHub OAuth Apps ↗,把 GitHub 用作 MCP server 的认证提供方 —— 一个用于本地开发,一个用于生产环境。

Step 2.1 — 为本地开发创建一个新的 OAuth App

访问 github.com/settings/developers ↗ 创建一个新的 OAuth App,使用以下设置:
- Application name: My MCP Server (local)
- Homepage URL: http://localhost:8788
- Authorization callback URL: http://localhost:8788/callback
把刚创建的 OAuth app 的 client ID 添加为 GITHUB_CLIENT_ID,生成一个 client secret 并添加为 GITHUB_CLIENT_SECRET,写入项目根目录的 .env 文件,这将用于在本地开发中设置 secret。 Terminal window

touch .env
echo 'GITHUB_CLIENT_ID="your-client-id"' >> .env
echo 'GITHUB_CLIENT_SECRET="your-client-secret"' >> .env
cat .env

运行以下命令启动开发服务器: Terminal window

npm start

你的 MCP server 现在运行在 http://localhost:8788/mcp。 4. 在新终端运行 MCP inspector ↗。MCP inspector 是一个交互式 MCP 客户端,允许你从浏览器连接到 MCP server 并调用工具。 Terminal window

npx @modelcontextprotocol/inspector@latest

在浏览器中打开 MCP inspector: Terminal window

open http://localhost:5173

在 inspector 中,输入你的 MCP server URL:http://localhost:8788/mcp
在右侧主面板中,点击 OAuth Settings 按钮,然后点击 Quick OAuth Flow。你应该会被重定向到 GitHub 的登录或授权页面。授权 MCP Client(即 inspector)访问你的 GitHub 账户后,会被重定向回 inspector。
点击侧边栏的 Connect,你应该会看到 “List Tools” 按钮,点击后会列出你的 MCP server 暴露的工具。

Step 2.2 — 为生产环境创建一个新的 OAuth App

你需要重复 Step 2.1,为生产环境再创建一个 OAuth App。

访问 github.com/settings/developers ↗ 创建一个新的 OAuth App,使用以下设置:

Application name: My MCP Server (production)
Homepage URL: 输入你已部署 MCP server 的 workers.dev URL(例如:worker-name.account-name.workers.dev)
Authorization callback URL: 输入已部署 MCP server 的 workers.dev URL 加 /callback 路径(例如:worker-name.account-name.workers.dev/callback)

使用 Wrangler CLI 添加刚创建的 OAuth app 的 client ID 与 client secret:

Terminal window


npx wrangler secret put GITHUB_CLIENT_ID

Terminal window


npx wrangler secret put GITHUB_CLIENT_SECRET


npx wrangler secret put COOKIE_ENCRYPTION_KEY # add any random string here e.g. openssl rand -hex 32

警告

当你创建第一个 secret 时,Wrangler 会询问是否要创建一个新 Worker。输入 “Y” 以创建新 Worker 并保存该 secret。

设置一个 KV namespace a. 创建 KV namespace: Terminal window

npx wrangler kv namespace create "OAUTH_KV"

b. 用得到的 KV ID 更新 wrangler.jsonc:

{
  "kvNamespaces": [
    {
      "binding": "OAUTH_KV",
      "id": "<YOUR_KV_NAMESPACE_ID>"
    }
  ]
}

把 MCP server 部署到 Cloudflare 的 workers.dev 域名下: Terminal window

npm run deploy

使用 AI Playground ↗、MCP Inspector 或其他 MCP 客户端连接到运行在 worker-name.account-name.workers.dev/mcp 的 server,并通过 GitHub 完成认证。

后续步骤

MCP Tools 为你的 MCP server 添加工具。

授权自定义认证与授权。

Keyboard shortcuts

从零构建 Cloudflare Agent