构建远程 MCP server

本指南展示如何在 Cloudflare 上使用 Streamable HTTP 传输（当前 MCP 规范标准）部署远程 MCP server。你有两种选择：

无身份验证 — 任何人可连接并使用 server（无需登录）。
带身份验证与授权 — 用户访问 tool 前需登录，你可按用户权限控制 Agent 可调用的 tool。

选择方案

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

方案	有状态？	需要 Durable Objects？	适用场景
`createMcpHandler()`	否	否	无状态 tool、最简单部署
`McpAgent`	是	是	有状态工具、按会话状态、elicitation
原生 `WebStandardStreamableHTTPServerTransport`	否	否	完全控制、不依赖 SDK

createMcpHandler() 是启动无状态 MCP 服务器最快的方式。工具不需要按会话状态时使用。
McpAgent 为每个会话提供一个 Durable Object，内置状态管理、elicitation 支持，以及 SSE 与 Streamable HTTP 传输。
原生传输 若希望直接使用 @modelcontextprotocol/sdk 而不依赖 Agents SDK 辅助，可完全自主控制。

部署你的第一个 MCP server

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

通过仪表板

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

部署后，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。

通过 CLI

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

打开终端并运行：
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?（是否添加 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。

说明
无法在浏览器中直接打开 /mcp URL 与 MCP server 交互。/mcp 端点期望 MCP 客户端发送 MCP 协议消息，浏览器默认不会这样做。下一步将演示如何用 MCP 客户端连接。
本地测试 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。
现在可将 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。

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

远程 MCP server 运行后，可使用 mcp-remote 本地代理 ↗ 将 Claude Desktop 或其他 MCP 客户端连接到它——即使客户端不支持远程传输或客户端侧授权。这样可测试真实 MCP 客户端与远程 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"
			]
		}
	}
}

重启 Claude Desktop 以加载 MCP Server。完成后 Claude 即可调用远程 MCP server。
测试时可让 Claude 使用你的某个 tool，例如：
```
Could you use the math tool to add 23 and 19?
```
Claude 应调用 tool 并显示远程 MCP server 返回的结果。

有关如何将远程 MCP server 与其他 MCP 客户端配合使用，请参阅测试远程 MCP Server。

添加身份验证

先前部署的公开 MCP server 示例允许任意客户端无登录连接并调用 tool。要为 MCP server 添加用户身份验证，可集成 Cloudflare Access 或第三方 OAuth 提供商。MCP server 处理安全登录流程并颁发 access token，MCP 客户端可用其进行已认证 tool 调用。用户通过 OAuth 提供商登录，并授权 AI Agent 在 scoped 权限下与 MCP server 暴露的 tool 交互。

Cloudflare Access OAuth

可将 MCP 服务器配置为通过 Cloudflare Access 要求用户身份验证。Cloudflare Access 作为身份聚合器，验证用户邮箱、现有身份提供商（如 GitHub 或 Google）的信号，以及 IP 地址或设备证书等属性。用户连接 MCP 服务器时，会提示登录已配置的身份提供商，仅通过 Access 策略后才授予访问。

分步部署指南请参阅使用 Access for SaaS 保护 MCP server。

第三方 OAuth

可将 MCP 服务器与任何支持 OAuth 2.0 规范的 OAuth 提供商连接，包括 GitHub、Google、Slack、Stytch、Auth0、WorkOS 等。

以下示例演示如何使用 GitHub 作为 OAuth 提供商。

步骤 1 — 创建新 MCP server

运行以下命令创建带 GitHub OAuth 的 MCP server：

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 已就绪，依赖已安装。进入项目目录：

cd my-mcp-server-github-auth

在示例 MCP server 中，打开 src/index.ts 可见主要区别：defaultHandler 设为 GitHubHandler：

import GitHubHandler from "./github-handler";

export default new OAuthProvider({
	apiRoute: "/mcp",
	apiHandler: MyMCP.serve("/mcp"),
	defaultHandler: GitHubHandler,
	authorizeEndpoint: "/authorize",
	tokenEndpoint: "/token",
	clientRegistrationEndpoint: "/register",
});

这确保用户被重定向到 GitHub 进行身份验证。要使其生效，还需在下列步骤中创建 OAuth 客户端应用。

步骤 2 — 创建 OAuth 应用

需创建两个 GitHub OAuth 应用 ↗ 作为 MCP server 的身份验证提供商——一个用于本地开发，一个用于生产。

步骤 2.1 — 为本地开发创建 OAuth 应用

前往 github.com/settings/developers ↗ 创建 OAuth 应用，设置如下：
- 应用名称：My MCP Server (local)
- 主页 URL：http://localhost:8788
- 授权回调 URL：http://localhost:8788/callback
将刚创建 OAuth 应用的 client ID 设为 GITHUB_CLIENT_ID，生成 client secret 并设为 GITHUB_CLIENT_SECRET，写入项目根目录 .env 文件，用于本地开发设置 secret。
```
touch .env
echo 'GITHUB_CLIENT_ID="your-client-id"' >> .env
echo 'GITHUB_CLIENT_SECRET="your-client-secret"' >> .env
cat .env
```
运行以下命令启动开发 server：
```
npm start
```
MCP server 现运行于 http://localhost:8788/mcp。
在新终端运行 MCP inspector ↗。MCP inspector 是交互式 MCP 客户端，可在浏览器中连接 MCP server 并调用 tool。
```
npx @modelcontextprotocol/inspector@latest
```
在浏览器中打开 MCP inspector：
```
open http://localhost:5173
```
在 inspector 中输入 MCP server URL：http://localhost:8788/mcp
右侧面板点击 OAuth Settings（OAuth 设置），再点击 Quick OAuth Flow（快速 OAuth 流程）。

应被重定向到 GitHub 登录或授权页。授权 MCP 客户端（inspector）访问 GitHub 账户后，会重定向回 inspector。
在侧边栏点击 Connect（连接），应看到 List Tools（列出工具） 按钮，可列出 MCP server 暴露的 tool。

步骤 2.2 — 为生产创建 OAuth 应用

需重复步骤 2.1 为生产创建 OAuth 应用。

前往 github.com/settings/developers ↗ 创建 OAuth 应用，设置如下：

应用名称：My MCP Server (production)
主页 URL：输入已部署 MCP 服务器的 workers.dev URL（例如 worker-name.account-name.workers.dev）
授权回调 URL：输入已部署 MCP 服务器 workers.dev URL 的 /callback 路径（例如 worker-name.account-name.workers.dev/callback）

将刚创建 OAuth 应用的 client ID 与 client secret 通过 Wrangler CLI 添加：

npx wrangler secret put GITHUB_CLIENT_ID

npx wrangler secret put GITHUB_CLIENT_SECRET

npx wrangler secret put COOKIE_ENCRYPTION_KEY

COOKIE_ENCRYPTION_KEY 可使用任意随机字符串，例如 openssl rand -hex 32 的输出。

设置 KV 命名空间

a. 创建 KV 命名空间：

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 域：
```
npm run deploy
```
使用 AI Playground ↗、MCP Inspector 或其他 MCP 客户端连接运行于 worker-name.account-name.workers.dev/mcp 的 server，并使用 GitHub 身份验证。