McpAgent 创建由 Durable Object 支持的有状态旧版 MCP server。
McpAgent 需要 @modelcontextprotocol/sdk,这是 agents 的可选对等依赖项。请安装与你的 Agents 版本相对应的准确版本:
npm i agents @modelcontextprotocol/[email protected] zodyarn add agents @modelcontextprotocol/[email protected] zodpnpm add agents @modelcontextprotocol/[email protected] zodbun add agents @modelcontextprotocol/[email protected] zodimport { 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) }],
}),
);
}
}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 实现。
| 属性/方法 | 描述 |
|---|---|
state |
当前状态对象(已持久化) |
initialState |
实例启动时的默认状态 |
setState(state) |
更新并持久化状态 |
onStateChanged(state) |
状态变更时调用 |
sql |
在嵌入式数据库上执行 SQL 查询 |
server |
用于注册工具的 McpServer 实例 |
props |
OAuth 身份验证中的用户身份与令牌 |
elicitInput(options, context) |
向用户请求结构化输入 |
McpAgent.serve(path, options) |
创建 Worker 处理函数的静态方法 |
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 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);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",
},
],
}调用方使用 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 传输具有可配置的工具响应等待超时。默认情况下,服务器等待工具处理程序响应 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。请参阅授权。
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 });
}
}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 发送前,客户端必须声明支持对应模式。
在工具处理函数中调用 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 模式用于必须在 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 模式。