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

McpAgent(已弃用)

最后更新 查看 MarkdownAgent 设置

McpAgent 创建由 Durable Object 支持的有状态旧版 MCP server。

McpAgent 需要 @modelcontextprotocol/sdk,这是 agents 的可选对等依赖项。请安装与你的 Agents 版本相对应的准确版本:

npm i agents @modelcontextprotocol/[email protected] zod
import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export class MyMCP extends McpAgent {
	server = new McpServer({ name: "Demo", 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) }],
			}),
		);
	}
}
src/index.tsts
import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export class MyMCP extends McpAgent {
    server = new McpServer({ name: "Demo", 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) }],
            }),
        );
    }
}

这意味着每个 MCP 服务器实例都有自己的持久状态,由 Durable Object提供支持,并拥有自己的 SQL 数据库。

无状态 server 可以使用 @modelcontextprotocol/server 定义 工具,并通过 createMcpHandler 提供它们。

但若希望 MCP 服务器:

  • 记住先前的工具调用及其响应
  • 向 MCP 客户端提供游戏,并记住棋盘状态、先前走法与得分
  • 缓存先前外部 API 调用的状态,供后续工具调用复用
  • 执行 Agent 能做的一切,但允许 MCP 客户端与之通信

可使用下方 API 实现。

API 概览

属性/方法 描述
state 当前状态对象(已持久化)
initialState 实例启动时的默认状态
setState(state) 更新并持久化状态
onStateChanged(state) 状态变更时调用
sql 在嵌入式数据库上执行 SQL 查询
server 用于注册工具的 McpServer 实例
props OAuth 身份验证中的用户身份与令牌
elicitInput(options, context) 向用户请求结构化输入
McpAgent.serve(path, options) 创建 Worker 处理函数的静态方法

使用 McpAgent.serve() 部署

McpAgent.serve() 静态方法创建 Worker 处理程序,将请求路由到你的 MCP server:

import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

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

	async init() {
		this.server.tool("square", { n: z.number() }, async ({ n }) => ({
			content: [{ type: "text", text: String(n * n) }],
		}));
	}
}

// Export the Worker handler
export default MyMCP.serve("/mcp");
import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

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

    async init() {
        this.server.tool("square", { n: z.number() }, async ({ n }) => ({
            content: [{ type: "text", text: String(n * n) }],
        }));
    }
}

// Export the Worker handler
export default MyMCP.serve("/mcp");

这是部署 MCP server 的最简方式——约 15 行代码。serve() 方法自动处理 Streamable HTTP 传输。

配合 OAuth 认证

使用 OAuth Provider Library ↗ 时,将 MCP 服务器传入 apiHandlers:

import { OAuthProvider } from "@cloudflare/workers-oauth-provider";

export default new OAuthProvider({
	apiHandlers: { "/mcp": MyMCP.serve("/mcp") },
	authorizeEndpoint: "/authorize",
	tokenEndpoint: "/token",
	clientRegistrationEndpoint: "/register",
	defaultHandler: AuthHandler,
	resourceMetadata: {
		// The URL MCP clients connect to. Use http://localhost:8787/mcp with wrangler dev.
		resource: "https://my-mcp-server.<your-subdomain>.workers.dev/mcp",
	},
});
import { OAuthProvider } from "@cloudflare/workers-oauth-provider";

export default new OAuthProvider({
    apiHandlers: { "/mcp": MyMCP.serve("/mcp") },
    authorizeEndpoint: "/authorize",
    tokenEndpoint: "/token",
    clientRegistrationEndpoint: "/register",
    defaultHandler: AuthHandler,
    resourceMetadata: {
        // The URL MCP clients connect to. Use http://localhost:8787/mcp with wrangler dev.
        resource: "https://my-mcp-server.<your-subdomain>.workers.dev/mcp",
    },
});

数据管辖

为符合 GDPR 与数据驻留要求,可指定 jurisdiction 以确保 MCP server 实例在特定区域运行:

// EU jurisdiction for GDPR compliance
export default MyMCP.serve("/mcp", { jurisdiction: "eu" });
// EU jurisdiction for GDPR compliance
export default MyMCP.serve("/mcp", { jurisdiction: "eu" });

配合 OAuth:

export default new OAuthProvider({
	apiHandlers: {
		"/mcp": MyMCP.serve("/mcp", { jurisdiction: "eu" }),
	},
	// ... other OAuth config
});
export default new OAuthProvider({
    apiHandlers: {
        "/mcp": MyMCP.serve("/mcp", { jurisdiction: "eu" }),
    },
    // ... other OAuth config
});

指定 jurisdiction: "eu" 时:

  • 所有 MCP 会话数据保留在 EU 内
  • tool 处理的用户数据保留在 EU 内
  • Durable Object 中存储的 state 保留在 EU 内

可用 jurisdiction 包括 "eu"(欧盟)与 "fedramp"(FedRAMP 合规位置)。更多选项请参阅 Durable Objects 数据位置。

休眠支持

McpAgent 实例自动支持 WebSockets Hibernation,使有状态 MCP 服务器在非活跃期休眠同时保留状态。这意味着 Agent 仅在主动处理请求时消耗计算资源,在保持完整上下文与对话历史的同时优化成本。

休眠默认启用,无需额外配置。

流式可恢复性

McpAgent 的 Streamable HTTP 传输可度过 Cloudflare 边缘约 5 分钟的空闲流看门狗,因此在连接不稳定时进行中的工具调用不会丢失:

  • GET(独立监听流) — 配置 EventStore 时,空闲断开通过客户端以 Last-Event-ID 头重连恢复(无需保活)。无 EventStore 时使用注释帧保活(: keepalive,每 25 秒)保持长连接监听器存活。
  • POST(工具响应流) — 始终保活,进行中的工具调用可度过空闲看门狗。配置 EventStore 时 POST 流还可通过 Last-Event-ID 恢复;重连客户端重放遗漏事件直至最终响应。每个 POST 流在写入关闭帧时清除其事件。

DurableObjectEventStore 从 agents/mcp 导出,供在 Agent 或 Durable Object 内嵌 transport 的有状态 WorkerTransport 调用方使用:

import { DurableObjectEventStore } from "agents/mcp";

const eventStore = new DurableObjectEventStore(this.ctx.storage);
import { DurableObjectEventStore } from "agents/mcp";

const eventStore = new DurableObjectEventStore(this.ctx.storage);

RPC 传输

Agent 可以通过 Durable Object 绑定连接到 McpAgent,而无需通过 HTTP 连接。Agent 端的 addMcpServer(name, binding, options) 在 MCP Client 页面中的 RPC 传输一节有说明。本节介绍 McpAgent 端。

只有定义 McpAgent 的 Worker 需要 @modelcontextprotocol/sdk。连接到它的 Agent 不需要。

RPC 传输不支持 OAuth 流程。需要身份验证的连接请使用 Streamable HTTP。

配置绑定

在运行调用方 Agent 的 Worker 中绑定 McpAgent 类:

{
    "durable_objects": {
        "bindings": [
            { "name": "Chat", "class_name": "Chat" },
            { "name": "MyMCP", "class_name": "MyMCP" },
        ],
    },
    "migrations": [
        {
            "new_sqlite_classes": ["MyMCP", "Chat"],
            "tag": "v1",
        },
    ],
}

从调用方读取 props

调用方使用 addMcpServer("my-mcp", env.MyMCP, { props }) 传递用户上下文。使用第三个类型参数声明其结构,并通过 this.props 读取:

import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

export class MyMCP extends McpAgent {
	server = new McpServer({ name: "MyMCP", version: "1.0.0" });

	async init() {
		this.server.tool("whoami", "Get current user info", {}, async () => {
			const userId = this.props?.userId || "anonymous";
			const role = this.props?.role || "guest";

			return {
				content: [{ type: "text", text: `User ID: ${userId}, Role: ${role}` }],
			};
		});
	}
}
import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

type Props = { userId?: string; role?: string };

export class MyMCP extends McpAgent<Env, unknown, Props> {
    server = new McpServer({ name: "MyMCP", version: "1.0.0" });

    async init() {
        this.server.tool("whoami", "Get current user info", {}, async () => {
            const userId = this.props?.userId || "anonymous";
            const role = this.props?.role || "guest";

            return {
                content: [{ type: "text", text: `User ID: ${userId}, Role: ${role}` }],
            };
        });
    }
}

Props 会存储在 Durable Object 存储中,并且在第一次工具调用之前即可使用。

配置 RPC 传输超时

RPC 传输具有可配置的工具响应等待超时。默认情况下,服务器等待工具处理程序响应 60 秒。你可以通过在 McpAgent 中覆盖 getRpcTransportOptions() 来自定义:

import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export class MyMCP extends McpAgent {
	server = new McpServer({ name: "MyMCP", version: "1.0.0" });

	getRpcTransportOptions() {
		return { timeout: 120000 }; // 2 minutes
	}

	async init() {
		this.server.tool(
			"long-running-task",
			"A tool that takes a while",
			{ input: z.string() },
			async ({ input }) => {
				await longRunningOperation(input);
				return {
					content: [{ type: "text", text: "Task completed" }],
				};
			},
		);
	}
}
import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export class MyMCP extends McpAgent<Env> {
    server = new McpServer({ name: "MyMCP", version: "1.0.0" });

    protected getRpcTransportOptions() {
        return { timeout: 120000 }; // 2 minutes
    }

    async init() {
        this.server.tool(
            "long-running-task",
            "A tool that takes a while",
            { input: z.string() },
            async ({ input }) => {
                await longRunningOperation(input);
                return {
                    content: [{ type: "text", text: "Task completed" }],
                };
            },
        );
    }
}

认证与授权

McpAgent 类与 OAuth Provider Library ↗集成。用户通过身份验证连接到 MCP 服务器后,其身份信息和令牌可通过 this.props 获取,你可以据此:

  • 访问用户特定数据
  • 在操作前检查用户权限
  • 根据用户属性定制响应
  • 使用身份验证 token 代表用户向外部服务发起请求

第三个类型参数用于定义 props 的结构:

import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

export class MyMCP extends McpAgent {
	server = new McpServer({ name: "Auth Demo", version: "1.0.0" });

	async init() {
		this.server.tool("whoami", "Get the current user", {}, async () => ({
			content: [{ type: "text", text: `Hello, ${this.props.claims.name}!` }],
		}));

		if (this.props.permissions?.includes("admin")) {
			this.server.tool("adminTool", "Admin only", {}, async () => ({
				content: [{ type: "text", text: "Admin action completed" }],
			}));
		}
	}
}
import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

type AuthContext = {
    claims: { sub: string; name: string; email: string };
    permissions: string[];
};

export class MyMCP extends McpAgent<Env, unknown, AuthContext> {
    server = new McpServer({ name: "Auth Demo", version: "1.0.0" });

    async init() {
        this.server.tool("whoami", "Get the current user", {}, async () => ({
            content: [{ type: "text", text: `Hello, ${this.props.claims.name}!` }],
        }));

        if (this.props.permissions?.includes("admin")) {
            this.server.tool("adminTool", "Admin only", {}, async () => ({
                content: [{ type: "text", text: "Admin action completed" }],
            }));
        }
    }
}

对于无状态服务器,可使用 getMcpAuthContext() 读取相同的 props。请参阅授权。

状态同步 API

McpAgent 类可完整访问 Agent 状态 API:

  • state — 当前已持久化的状态
  • initialState — 实例启动时的默认状态
  • setState — 更新并持久化状态
  • onStateChanged — 对状态变化作出响应
  • sql — 在嵌入式数据库上执行 SQL 查询

例如,以下代码实现记住计数器值、并在调用 add 工具时更新计数器的 MCP 服务器:

import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

export class MyMCP extends McpAgent {
	server = new McpServer({
		name: "Demo",
		version: "1.0.0",
	});

	initialState = {
		counter: 1,
	};

	async init() {
		this.server.resource(`counter`, `mcp://resource/counter`, (uri) => {
			return {
				contents: [{ uri: uri.href, text: String(this.state.counter) }],
			};
		});

		this.server.tool(
			"add",
			"Add to the counter, stored in the MCP",
			{ a: z.number() },
			async ({ a }) => {
				this.setState({ ...this.state, counter: this.state.counter + a });

				return {
					content: [
						{
							type: "text",
							text: String(`Added ${a}, total is now ${this.state.counter}`),
						},
					],
				};
			},
		);
	}

	onStateChanged(state) {
		console.log({ stateUpdate: state });
	}
}
src/index.tsts
import { McpAgent } from "agents/mcp";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";

type State = { counter: number };

export class MyMCP extends McpAgent<Env, State, {}> {
    server = new McpServer({
        name: "Demo",
        version: "1.0.0",
    });

    initialState: State = {
        counter: 1,
    };

    async init() {
        this.server.resource(`counter`, `mcp://resource/counter`, (uri) => {
            return {
                contents: [{ uri: uri.href, text: String(this.state.counter) }],
            };
        });

        this.server.tool(
            "add",
            "Add to the counter, stored in the MCP",
            { a: z.number() },
            async ({ a }) => {
                this.setState({ ...this.state, counter: this.state.counter + a });

                return {
                    content: [
                        {
                            type: "text",
                            text: String(`Added ${a}, total is now ${this.state.counter}`),
                        },
                    ],
                };
            },
        );
    }

    onStateChanged(state: State) {
        console.log({ stateUpdate: state });
    }
}

旧版服务器上的引导请求

MCP elicitation ↗ 允许 server 在处理其他请求(如 tool call)时向用户请求输入。旧版路径定义两种模式:

  • Form 模式 通过客户端收集结构化、非敏感数据。
  • URL 模式 将用户引导至带外交互,如第三方授权或支付。

server 发送前,客户端必须声明支持对应模式。

Form 模式

在工具处理函数中调用 this.server.server.elicitInput()。将 extra.requestId 作为 relatedRequestId 传入,使响应返回原始工具调用的流:

const result = await this.server.server.elicitInput(
	{
		mode: "form",
		message: "By how much do you want to increase the counter?",
		requestedSchema: {
			type: "object",
			properties: {
				amount: {
					type: "number",
					title: "Amount",
					minimum: 1,
					maximum: 100,
				},
			},
			required: ["amount"],
		},
	},
	{ relatedRequestId: extra.requestId },
);

if (result.action !== "accept" || !result.content) {
	return { content: [{ type: "text", text: "Counter unchanged." }] };
}

const amount = Number(result.content.amount);
const result = await this.server.server.elicitInput(
    {
        mode: "form",
        message: "By how much do you want to increase the counter?",
        requestedSchema: {
            type: "object",
            properties: {
                amount: {
                    type: "number",
                    title: "Amount",
                    minimum: 1,
                    maximum: 100,
                },
            },
            required: ["amount"],
        },
    },
    { relatedRequestId: extra.requestId },
);

if (result.action !== "accept" || !result.content) {
    return { content: [{ type: "text", text: "Counter unchanged." }] };
}

const amount = Number(result.content.amount);

为向后兼容,表单请求可省略 mode: "form"。schema 支持带基本类型字段的扁平对象。请勿使用表单模式请求密码、API 密钥、访问令牌、支付凭证或其他机密。

URL 模式

URL 模式用于必须在 MCP 客户端外完成的交互。请求包含 message、URL 与唯一 elicitationId:

const elicitationId = crypto.randomUUID();
const result = await this.server.server.elicitInput(
	{
		mode: "url",
		message: "Connect your account to continue.",
		url: `https://example.com/connect?elicitationId=${elicitationId}`,
		elicitationId,
	},
	{ relatedRequestId: extra.requestId },
);

if (result.action !== "accept") {
	return { content: [{ type: "text", text: "Connection cancelled." }] };
}

return {
	content: [
		{
			type: "text",
			text: "Connection page opened. Complete it in your browser.",
		},
	],
};
const elicitationId = crypto.randomUUID();
const result = await this.server.server.elicitInput(
    {
        mode: "url",
        message: "Connect your account to continue.",
        url: `https://example.com/connect?elicitationId=${elicitationId}`,
        elicitationId,
    },
    { relatedRequestId: extra.requestId },
);

if (result.action !== "accept") {
    return { content: [{ type: "text", text: "Connection cancelled." }] };
}

return {
    content: [
        {
            type: "text",
            text: "Connection page opened. Complete it in your browser.",
        },
    ],
};

URL 模式下,accept 表示用户同意打开 URL,不表示带外交互已完成。server 之后可发送 notifications/elicitation/complete,使用相同 elicitationId。

请勿在 url 中放置机密、个人信息或预认证受保护资源 URL。生产 server 应使用 HTTPS。将每个请求绑定到已认证用户,并验证同一用户完成带外流程。

处理响应

两种模式均返回三种 action 之一:

操作 含义
accept 用户提交了表单或同意打开 URL。
decline 用户明确拒绝请求。
cancel 用户关闭请求但未明确选择。

已接受的表单响应包含与 requestedSchema 匹配的 content。URL 响应不包含 content。拒绝和取消响应通常也不包含该字段。

switch (result.action) {
	case "accept":
		// For form mode, validate and process result.content.
		break;
	case "decline":
		return { content: [{ type: "text", text: "Request declined." }] };
	case "cancel":
		return { content: [{ type: "text", text: "Request dismissed." }] };
}
switch (result.action) {
    case "accept":
        // For form mode, validate and process result.content.
        break;
    case "decline":
        return { content: [{ type: "text", text: "Request declined." }] };
    case "cancel":
        return { content: [{ type: "text", text: "Request dismissed." }] };
}

更多人机协同模式请参阅 Human-in-the-loop 模式。

后续步骤

这篇文档对您有帮助吗?