building-mcp-server-on-cloudflare

用途

本技能用于在 Cloudflare Workers 上创建生产可用的 Model Context Protocol（MCP）服务器，包含工具定义、认证与部署。当用户想要构建远程 MCP 服务器、需要通过 MCP 暴露工具、询问 MCP 认证或 OAuth、或希望将 MCP 部署到 Cloudflare Workers 时使用。

前置条件

已启用 Workers 的 Cloudflare 账户
Node.js 18+ 及 npm/pnpm/yarn
Wrangler CLI（npm install -g wrangler）

快速开始

选项 1：公开服务器（无认证）

npm create cloudflare@latest -- my-mcp-server \
  --template=cloudflare/ai/demos/remote-mcp-authless
cd my-mcp-server
npm start

服务器运行于 http://localhost:8788/mcp

选项 2：带认证服务器（OAuth）

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

需要配置 OAuth 应用，参见 references/oauth-setup.md。

核心工作流

第 1 步：定义工具

工具是 MCP 客户端可调用的函数，使用 server.tool() 定义：

import { McpAgent } from "agents/mcp";
import { z } from "zod";

export class MyMCP extends McpAgent {
  server = new Server({ name: "my-mcp", version: "1.0.0" });

  async init() {
    // 带参数的简单工具
    this.server.tool(
      "add",
      { a: z.number(), b: z.number() },
      async ({ a, b }) => ({
        content: [{ type: "text", text: String(a + b) }],
      })
    );

    // 调用外部 API 的工具
    this.server.tool(
      "get_weather",
      { city: z.string() },
      async ({ city }) => {
        const response = await fetch(`https://api.weather.com/${city}`);
        const data = await response.json();
        return {
          content: [{ type: "text", text: JSON.stringify(data) }],
        };
      }
    );
  }
}

第 2 步：配置入口点

公开服务器（src/index.ts）：

import { MyMCP } from "./mcp";

export default {
  fetch(request: Request, env: Env, ctx: ExecutionContext) {
    const url = new URL(request.url);
    if (url.pathname === "/mcp") {
      return MyMCP.serveSSE("/mcp").fetch(request, env, ctx);
    }
    return new Response("MCP Server", { status: 200 });
  },
};

export { MyMCP };

带认证服务器参见 references/oauth-setup.md。

第 3 步：本地测试

# 启动服务器
npm start

# 在另一个终端用 MCP Inspector 测试
npx @modelcontextprotocol/inspector@latest
# 打开 http://localhost:5173，输入 http://localhost:8788/mcp

第 4 步：部署

npx wrangler deploy

服务器可通过 https://[worker-name].[account].workers.dev/mcp 访问。

第 5 步：连接客户端

Claude Desktop（claude_desktop_config.json）：

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

更新配置后重启 Claude Desktop。

工具模式

返回类型

// 文本响应
return { content: [{ type: "text", text: "result" }] };

// 多个内容项
return {
  content: [
    { type: "text", text: "Here's the data:" },
    { type: "text", text: JSON.stringify(data, null, 2) },
  ],
};

使用 Zod 做输入校验

this.server.tool(
  "create_user",
  {
    email: z.string().email(),
    name: z.string().min(1).max(100),
    role: z.enum(["admin", "user", "guest"]),
    age: z.number().int().min(0).optional(),
  },
  async (params) => {
    // params 已完全类型化并校验
  }
);

访问环境/绑定

export class MyMCP extends McpAgent<Env> {
  async init() {
    this.server.tool("query_db", { sql: z.string() }, async ({ sql }) => {
      // 访问 D1 绑定
      const result = await this.env.DB.prepare(sql).all();
      return { content: [{ type: "text", text: JSON.stringify(result) }] };
    });
  }
}

认证

OAuth 保护的服务器参见 references/oauth-setup.md。支持的提供方：GitHub、Google、Auth0、Stytch、WorkOS，以及任何符合 OAuth 2.0 的提供方。

Wrangler 配置

最小 wrangler.toml：

name = "my-mcp-server"
main = "src/index.ts"
compatibility_date = "2024-12-01"

[durable_objects]
bindings = [{ name = "MCP", class_name = "MyMCP" }]

[[migrations]]
tag = "v1"
new_classes = ["MyMCP"]

带绑定（D1、KV 等）：

[[d1_databases]]
binding = "DB"
database_name = "my-db"
database_id = "xxx"

[[kv_namespaces]]
binding = "KV"
id = "xxx"

常见问题

客户端提示“Tool not found”

确认工具名称完全匹配（区分大小写）
确保 init() 在连接前注册工具
检查服务器日志：wrangler tail

连接失败

确认端点路径为 /mcp
若为浏览器客户端，检查 CORS
确认 Worker 已部署：wrangler deployments list

OAuth 重定向错误

回调 URL 必须与 OAuth 应用配置完全一致
检查 GITHUB_CLIENT_ID 和 GITHUB_CLIENT_SECRET 是否已设置
本地开发使用 http://localhost:8788/callback

参考资料

references/examples.md — 官方模板与生产示例
references/oauth-setup.md — OAuth 提供方配置
references/tool-patterns.md — 高级工具示例
references/troubleshooting.md — 错误码与修复