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

MCP 服务器

最后更新 查看 MarkdownAgent 设置

agents/mcp/server 中的 createMcpHandler 会在 Worker 中提供 MCP SDK v2 服务器。该处理程序是无状态的:每个请求都会创建一个新的服务器,因此无需 Durable Object、协议会话或 WebSocket。

要迁移现有的 McpAgent 服务器,请参阅迁移到 MCP SDK v2。已弃用的 API 记录在 McpAgent 参考中。

安装依赖

npm i agents @modelcontextprotocol/[email protected] zod

@modelcontextprotocol/server 是 agents 的可选 peer dependency,因此包管理器不会自动为你安装。请使用已安装 Agents 版本所要求的确切版本。

createMcpHandler

createMcpHandler 从 MCP SDK v2 server factory 创建可调用的无状态 MCP 请求 handler。从 Worker 对象的 fetch() 导出调用它,或在另一个 handler 内组合它。

import {
    createMcpHandler,
    type CreateMcpHandlerOptions,
    type StatelessMcpHandler,
} from "agents/mcp/server";
import type { McpServerFactory } from "@modelcontextprotocol/server";

function createMcpHandler(
    factory: McpServerFactory,
    options?: CreateMcpHandlerOptions,
): StatelessMcpHandler;

参数

  • factory 创建来自 @modelcontextprotocol/server 的全新 McpServer 或 Server。可以是同步或异步。
  • options 将 Agents Worker 选项与受支持的上游 SDK v2 handler 选项组合在一起。

factory 接收此请求上下文:

interface McpRequestContext {
    era: "modern" | "legacy";
    authInfo?: AuthInfo;
    requestInfo?: Request;
}

零参数 factory 仍然有效。

示例

import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";
import { z } from "zod";

function createServer() {
	const server = new McpServer({
		name: "hello-server",
		version: "1.0.0",
	});

	server.registerTool(
		"hello",
		{
			description: "Return a greeting",
			inputSchema: z.object({ name: z.string().optional() }),
		},
		async ({ name }) => ({
			content: [{ type: "text", text: `Hello, ${name ?? "World"}!` }],
		}),
	);

	return server;
}

export default {
	fetch(request, env, ctx) {
		return createMcpHandler(createServer)(request, env, ctx);
	},
};
src/index.tsts
import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";
import { z } from "zod";

function createServer() {
    const server = new McpServer({
        name: "hello-server",
        version: "1.0.0",
    });

    server.registerTool(
        "hello",
        {
            description: "Return a greeting",
            inputSchema: z.object({ name: z.string().optional() }),
        },
        async ({ name }) => ({
            content: [{ type: "text", text: `Hello, ${name ?? "World"}!` }],
        }),
    );

    return server;
}

export default {
    fetch(request, env, ctx) {
        return createMcpHandler(createServer)(request, env, ctx);
    },
} satisfies ExportedHandler;

传入 factory 本身。不要创建全局 server 实例,也不要直接传入已构造的 SDK v2 server。

CreateMcpHandlerOptions

可用选项如下:

选项 类型 默认值 描述
route string "/mcp" Worker wrapper 处理的精确路径
corsOptions CORSOptions | false 通配 CORS CORS 响应 header,或 false 以移除它们
allowedHostnames string[] Localhost 或 workers.dev 路由 自定义域的可选 Host 限制
allowedOriginHostnames string[] | "*" Localhost、workers.dev 或具体 CORS Origin 浏览器 Origin 限制,或显式交由中间件
authContext McpAuthContext 执行上下文属性 getMcpAuthContext() 返回的应用 props
legacy "stateless" | "reject" "stateless" 旧版兼容或仅无状态拒绝
responseMode "auto" | "json" | "sse" "auto" 无状态请求的响应形态
onerror (error: Error) => void 无 带外错误报告
maxSubscriptions number 1,024 最大并发 listen 流
keepAliveMs number 15,000 listen 流的 keepalive 间隔

SDK v1 transport 选项不适用于此 handler。它会拒绝 transport、storage、sessionIdGenerator、eventStore 与 enableJsonResponse 等选项。

请使用 responseMode: "json" 代替 enableJsonResponse: true。JSON 模式会丢弃最终结果之前发出的 notification。

Factory 生命周期

handler 为每个请求创建一个 MCP server。这遵循草案协议模型:版本、身份与能力随每个请求传递,而不是通过协议会话。

应用数据仍可持久。将跨请求数据存储在 Durable Object、D1、KV 或 R2 中经过认证的句柄后面,而不是 MCP session ID。

使用无状态处理程序进行 Elicitation

通过无状态 handler 的 elicitation 返回 input_required,并通过多轮往返请求(MRTR)完成。每次重试时,SDK 回显最新 requestState,并发送紧邻上一轮输入的响应。它不会累积更早的 inputResponses。用户响应期间 Worker 不会保持挂起。

使用 inputRequired(...) 请求输入。用 acceptedContent(...) 从 context.mcpReq.inputResponses 读取该轮已接受的表单内容。将后续轮次所需的受信任中间值封入完整性保护的 requestState。

两轮工具流程请参阅 无状态 elicitation 示例 ↗。

Origin 校验与 CORS

Workers wrapper 校验每个出现的浏览器 Origin。格式错误、opaque 与非 HTTP Origin 会被以 403 拒绝。无 Origin 的非浏览器 MCP 客户端仍然有效。

默认允许列表包括 localhost 类 Origin、端点的 workers.dev 主机名,以及来自 corsOptions.origin 的具体主机名。handler 还会对 localhost 与 workers.dev 端点应用匹配的 Host 检查。这可在常见 Workers 路由上提供本地 DNS 重绑定保护,而无需单独的 Origin 列表。

自定义域配合通配 CORS 时,请显式设置 allowedHostnames 与 allowedOriginHostnames。若 corsOptions.origin 是具体 URL,handler 会自动推导其 Origin 主机名:

import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";

function createServer() {
	return new McpServer({ name: "my-server", version: "1.0.0" });
}

const handler = createMcpHandler(createServer, {
	allowedHostnames: ["mcp.example.com"],
	corsOptions: {
		origin: "https://app.example.com",
	},
});

export default {
	fetch(request, env, ctx) {
		return handler(request, env, ctx);
	},
};
import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";

function createServer() {
    return new McpServer({ name: "my-server", version: "1.0.0" });
}

const handler = createMcpHandler(createServer, {
    allowedHostnames: ["mcp.example.com"],
    corsOptions: {
        origin: "https://app.example.com",
    },
});

export default {
    fetch(request, env, ctx) {
        return handler(request, env, ctx);
    },
} satisfies ExportedHandler<Env>;

允许列表值为不含 scheme 或端口的主机名。Origin 匹配忽略 scheme 与端口。

仅在受信任中间件于调用 handler 前校验 Origin 时设置 allowedOriginHostnames: "*"。该值会关闭 handler 的 Origin 检查,包括对格式错误与 opaque Origin 的拒绝。MCP HTTP server 必须校验浏览器 Origin。

CORS 响应 header 不是认证。请用 OAuth 或其他认证层保护 MCP 端点。

handler 不会从 request.url 推断 Host 允许列表。若部署接受任意 Host 值,请在调用 handler 前校验它们。Cloudflare Workers 之外的本地 server 应遵循上游 SDK 的 DNS 重绑定指南。

与旧版客户端的兼容性

默认的 legacy: "stateless" 设置接受常规旧版工具、提示和资源。此通道使用 SDK v2 Web 标准传输。

此兼容路径不提供完整会话 transport:

  • 每个 POST 创建新的 server 与 transport。
  • HTTP GET 与 DELETE 返回 405。
  • 不会持久化 MCP session ID。
  • 推送的 elicitation、sampling 与 roots 请求会立即失败。
  • 独立流、可恢复性、replay 与会话删除不可用。
  • 已发布的实验性 task 不通过此路径支持。

对于仅支持无状态请求的端点,请设置 legacy: "reject"。

返回值

createMcpHandler 返回 StatelessMcpHandler。它可调用,并暴露请求与 notification 控制:

interface StatelessMcpHandler {
    (request: Request, env: unknown, ctx: ExecutionContext): Promise<Response>;

    fetch(
        request: Request,
        options?: McpHandlerRequestOptions,
    ): Promise<Response>;

    notify: {
        toolsChanged(): void;
        promptsChanged(): void;
        resourcesChanged(): void;
        resourceUpdated(uri: string): void;
    };
}

type McpHandlerRequestOptions = {
    authInfo?: AuthInfo;
    parsedBody?: unknown;
};

调用 handler

从 Worker 对象的 fetch() 导出调用 handler:

import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";

function createServer() {
	return new McpServer({ name: "my-server", version: "1.0.0" });
}

const handler = createMcpHandler(createServer);

export default {
	fetch(request, env, ctx) {
		return handler(request, env, ctx);
	},
};
import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";

function createServer() {
    return new McpServer({ name: "my-server", version: "1.0.0" });
}

const handler = createMcpHandler(createServer);

export default {
    fetch(request, env, ctx) {
        return handler(request, env, ctx);
    },
} satisfies ExportedHandler<Env>;

不要将可调用对象直接导出为 Worker 的 default export。Wrangler 会将函数 default export 视为 WorkerEntrypoint 类。

当另一框架或认证层已解析或校验请求数据时,使用 fetch():

import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";

function createServer() {
	return new McpServer({ name: "my-server", version: "1.0.0" });
}

const handler = createMcpHandler(createServer);

// Replace with your own token verification.
async function verifyToken(token) {
	if (token !== "dev-token") return undefined;
	return { token, clientId: "dev-client", scopes: ["mcp:read"] };
}

export default {
	async fetch(request) {
		const token = request.headers.get("Authorization")?.replace(/^Bearer /, "");
		const authInfo = token ? await verifyToken(token) : undefined;
		if (!authInfo) return new Response("Unauthorized", { status: 401 });

		// Middleware that already read the body can pass it on, so the handler
		// does not read it again.
		const parsedBody =
			request.method === "POST" ? await request.clone().json() : undefined;

		return handler.fetch(request, { authInfo, parsedBody });
	},
};
import { McpServer, type AuthInfo } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";

function createServer() {
    return new McpServer({ name: "my-server", version: "1.0.0" });
}

const handler = createMcpHandler(createServer);

// Replace with your own token verification.
async function verifyToken(token: string): Promise<AuthInfo | undefined> {
    if (token !== "dev-token") return undefined;
    return { token, clientId: "dev-client", scopes: ["mcp:read"] };
}

export default {
    async fetch(request) {
        const token = request.headers.get("Authorization")?.replace(/^Bearer /, "");
        const authInfo = token ? await verifyToken(token) : undefined;
        if (!authInfo) return new Response("Unauthorized", { status: 401 });

        // Middleware that already read the body can pass it on, so the handler
        // does not read it again.
        const parsedBody =
            request.method === "POST" ? await request.clone().json() : undefined;

        return handler.fetch(request, { authInfo, parsedBody });
    },
} satisfies ExportedHandler<Env>;

authInfo 会传给 server factory 与请求处理程序。handler 不会从请求 header 推导它,也不会验证 access token。parsedBody 可避免重新解析上游中间件已消费的 JSON 正文。

发布列表与 resource 变更

notify 方法向匹配的已打开 subscriptions/listen 流发布带类型的变更事件:

方法 MCP 通知
notify.toolsChanged() notifications/tools/list_changed
notify.promptsChanged() notifications/prompts/list_changed
notify.resourcesChanged() notifications/resources/list_changed
notify.resourceUpdated(uri) notifications/resources/updated

在没有匹配订阅打开时调用 notifier 是 no-op。

为 notification 保留同一个 handler

Notification 路由属于 handler 实例。在每次 Worker fetch() 调用内构造新 handler 适用于普通工具、prompt、resource 与 MRTR elicitation。它无法通知由更早 handler 实例拥有的 subscriptions/listen 流。

使用 notify 或 subscriptions/listen 时,请在模块作用域中只创建一次处理程序,然后从 Worker 对象导出中调用它。此 Worker 还具有由 ADMIN_TOKEN 密钥保护的管理路由,可通知已订阅的客户端重新获取工具列表:

import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";

function createServer() {
	return new McpServer({ name: "my-server", version: "1.0.0" });
}

// Create the handler once, so notifications reach its open streams.
const handler = createMcpHandler(createServer);

export default {
	async fetch(request, env, ctx) {
		const url = new URL(request.url);

		if (url.pathname === "/admin/tools-changed" && request.method === "POST") {
			if (
				request.headers.get("Authorization") !== `Bearer ${env.ADMIN_TOKEN}`
			) {
				return new Response("Unauthorized", { status: 401 });
			}
			handler.notify.toolsChanged();
			return new Response(null, { status: 204 });
		}

		return handler(request, env, ctx);
	},
};
import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler } from "agents/mcp/server";

function createServer() {
    return new McpServer({ name: "my-server", version: "1.0.0" });
}

// Create the handler once, so notifications reach its open streams.
const handler = createMcpHandler(createServer);

export default {
    async fetch(request, env, ctx) {
        const url = new URL(request.url);

        if (url.pathname === "/admin/tools-changed" && request.method === "POST") {
            if (request.headers.get("Authorization") !== `Bearer ${env.ADMIN_TOKEN}`) {
                return new Response("Unauthorized", { status: 401 });
            }
            handler.notify.toolsChanged();
            return new Response(null, { status: 204 });
        }

        return handler(request, env, ctx);
    },
} satisfies ExportedHandler<Env>;

Notification 是 isolate 本地的。在一个 Worker isolate 中发布的 notification 不会到达另一个 isolate 中运行的订阅流。

认证上下文

若要要求 OAuth,请使用 @cloudflare/workers-oauth-provider 中的 OAuthResourceServer 包装处理程序。它会在调用处理程序前,使用你的授权服务器验证访问令牌。请参阅授权以构建授权服务器。

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);
		},
	},
});
src/index.tsts
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);
        },
    },
});

资源服务器会将通过 completeAuthorization() 存储的 props 作为 ctx.props 传递;getMcpAuthContext() 会在服务器内部返回这些属性:

interface McpAuthContext {
    props: Record<string, unknown>;
}

getMcpAuthContext() 在服务器工厂中同样可用,因此你可以根据登录用户注册工具。如果由自己的代码而非 OAuthResourceServer 验证请求,请使用 authContext 选项传递用户身份:

import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler, getMcpAuthContext } from "agents/mcp/server";
import { z } from "zod";

function createServer() {
	const server = new McpServer({ name: "my-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 ?? "anonymous" }],
		}),
	);

	// Only admins see this tool.
	if (props?.role === "admin") {
		server.registerTool(
			"deleteUser",
			{ description: "Delete a user", inputSchema: { userId: z.string() } },
			async ({ userId }) => ({
				content: [{ type: "text", text: `Deleted ${userId}` }],
			}),
		);
	}

	return server;
}

// Replace with your own session or token check.
async function authenticate(request) {
	if (request.headers.get("Authorization") === "Bearer dev-token") {
		return { userId: "user-123", role: "admin" };
	}
	return undefined;
}

export default {
	async fetch(request, env, ctx) {
		const props = await authenticate(request);
		if (!props) return new Response("Unauthorized", { status: 401 });

		return createMcpHandler(createServer, { authContext: { props } })(
			request,
			env,
			ctx,
		);
	},
};
import { McpServer } from "@modelcontextprotocol/server";
import { createMcpHandler, getMcpAuthContext } from "agents/mcp/server";
import { z } from "zod";

type Props = { userId: string; role: "admin" | "member" };

function createServer() {
    const server = new McpServer({ name: "my-server", version: "1.0.0" });
    const props = getMcpAuthContext()?.props as Props | undefined;

    server.registerTool(
        "whoami",
        { description: "Return the signed-in user" },
        async () => ({
            content: [{ type: "text", text: props?.userId ?? "anonymous" }],
        }),
    );

    // Only admins see this tool.
    if (props?.role === "admin") {
        server.registerTool(
            "deleteUser",
            { description: "Delete a user", inputSchema: { userId: z.string() } },
            async ({ userId }) => ({
                content: [{ type: "text", text: `Deleted ${userId}` }],
            }),
        );
    }

    return server;
}

// Replace with your own session or token check.
async function authenticate(request: Request): Promise<Props | undefined> {
    if (request.headers.get("Authorization") === "Bearer dev-token") {
        return { userId: "user-123", role: "admin" };
    }
    return undefined;
}

export default {
    async fetch(request, env, ctx) {
        const props = await authenticate(request);
        if (!props) return new Response("Unauthorized", { status: 401 });

        return createMcpHandler(createServer, { authContext: { props } })(
            request,
            env,
            ctx,
        );
    },
} satisfies ExportedHandler<Env>;

Props 通常包含上游访问令牌。请勿记录或返回这些令牌。

相关资源

这篇文档对您有帮助吗?