Model Context Protocol (MCP) 规范定义了客户端与服务器之间通信的两种标准传输机制 ↗:
- stdio — 通过标准输入和标准输出通信,适用于本地 MCP 连接。
- Streamable HTTP — 远程 MCP 连接的标准传输方式,于 2025 年 3 月引入 ↗。它使用单个 HTTP 端点进行双向消息传递。
使用 Agents SDK 构建的 MCP 服务器通过 createMcpHandler 处理 Streamable HTTP 传输。
使用 createMcpHandler 创建支持 Streamable HTTP 传输的 MCP 服务器。
你可以使用「部署到 Cloudflare」按钮创建远程 MCP 服务器。
使用 createMcpHandler 创建 MCP 服务器。在 GitHub 上查看完整示例 ↗。
import { createMcpHandler } from "agents/mcp/server";
import { McpServer } from "@modelcontextprotocol/server";
import { z } from "zod";
function createServer() {
const server = new McpServer({
name: "My MCP Server",
version: "1.0.0",
});
server.registerTool(
"hello",
{
description: "Returns a greeting message",
inputSchema: { name: z.string().optional() },
},
async ({ name }) => {
return {
content: [{ text: `Hello, ${name ?? "World"}!`, type: "text" }],
};
},
);
return server;
}
export default {
fetch(request, env, ctx) {
return createMcpHandler(createServer)(request, env, ctx);
},
};import { createMcpHandler } from "agents/mcp/server";
import { McpServer } from "@modelcontextprotocol/server";
import { z } from "zod";
function createServer() {
const server = new McpServer({
name: "My MCP Server",
version: "1.0.0",
});
server.registerTool(
"hello",
{
description: "Returns a greeting message",
inputSchema: { name: z.string().optional() },
},
async ({ name }) => {
return {
content: [{ text: `Hello, ${name ?? "World"}!`, type: "text" }],
};
},
);
return server;
}
export default {
fetch(request, env, ctx) {
return createMcpHandler(createServer)(request, env, ctx);
},
} satisfies ExportedHandler;要启用 OAuth,请使用 Workers OAuth Provider ↗ 中的 OAuthResourceServer 包装处理程序。对于没有有效 token 的请求,它会返回 401,并指向 MCP 客户端应访问的授权服务器。有关授权服务器和完整设置,请参阅授权。
import {
OAuthResourceServer,
insufficientScope,
} from "@cloudflare/workers-oauth-provider";
import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler, getMcpAuthContext } from "agents/mcp/server";
import { env } from "cloudflare:workers";
function createServer() {
const server = new McpServer({ name: "my-mcp-server", version: "1.0.0" });
const props = getMcpAuthContext()?.props;
server.registerTool(
"whoami",
{ description: "Return the signed-in user" },
async () => ({
content: [{ type: "text", text: props.userId }],
}),
);
return server;
}
const mcpHandler = createMcpHandler(createServer);
export default new OAuthResourceServer({
resourceMetadata: {
resource: env.MCP_SERVER_URL, // tokens for any other resource are rejected
authorization_servers: [env.AUTH_SERVER_URL],
},
requiredScopes: ["mcp:read"],
validateToken: (env) => env.AUTH_SERVER.validateToken,
handler: {
fetch(request, env, ctx) {
// requiredScopes is advertised, not enforced: check it here.
if (!ctx.auth.scope.includes("mcp:read")) {
return insufficientScope(ctx.auth, ["mcp:read"]);
}
return mcpHandler(request, env, ctx);
},
},
});import {
OAuthResourceServer,
insufficientScope,
type AuthorizationServerBinding,
} from "@cloudflare/workers-oauth-provider";
import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler, getMcpAuthContext } from "agents/mcp/server";
import { env } from "cloudflare:workers";
type AuthProps = { userId: string };
interface Env {
AUTH_SERVER: AuthorizationServerBinding<AuthProps>;
}
function createServer() {
const server = new McpServer({ name: "my-mcp-server", version: "1.0.0" });
const props = getMcpAuthContext()?.props as AuthProps;
server.registerTool(
"whoami",
{ description: "Return the signed-in user" },
async () => ({
content: [{ type: "text", text: props.userId }],
}),
);
return server;
}
const mcpHandler = createMcpHandler(createServer);
export default new OAuthResourceServer<Env, AuthProps>({
resourceMetadata: {
resource: env.MCP_SERVER_URL, // tokens for any other resource are rejected
authorization_servers: [env.AUTH_SERVER_URL],
},
requiredScopes: ["mcp:read"],
validateToken: (env) => env.AUTH_SERVER.validateToken,
handler: {
fetch(request, env, ctx) {
// requiredScopes is advertised, not enforced: check it here.
if (!ctx.auth.scope.includes("mcp:read")) {
return insufficientScope(ctx.auth, ["mcp:read"]);
}
return mcpHandler(request, env, ctx);
},
},
});无状态处理程序没有 MCP 会话。必须在多个请求之间保留的数据,应以经过身份验证的用户作为键存储在 Durable Object、D1、KV 或 R2 中,而不是使用 MCP 会话 ID。
要迁移现有的 McpAgent 服务器,请参阅迁移到 MCP SDK v2。已弃用的 API 记录在 McpAgent 参考中。
使用支持 Streamable HTTP 连接的客户端测试 MCP 服务器。
请按照测试远程 MCP 服务器中的说明,使用 Claude Code、Cursor、Windsurf 或其他 MCP 客户端进行测试。