教程2026-11-10 · 智涌AI

MCP Events 是什么:让 Agent 订阅事件不再轮询

MCP Events 教程头图:左侧大字「MCP Events 订阅事件」与三种投递方式、204 回执、60 秒租期数字卡;右侧终端窗口展示 AI SDK 官方示例的事件目录、订阅校验、收到评论和服务器回 204 的输出流程

MCP 原来只有「问」的方向:Agent 调工具,服务器回结果。部署成没成、有没有新评论、来没来新工单,Agent 只能隔一会儿问一次。MCP 社区正在起草的 Events 扩展补上了反方向:服务器在事情发生时主动通知你。Vercel 已经跟进,Vercel MCP 从 2026-10-30 起可以订阅 deployment.succeeded、deployment.error,AI SDK 也给了收事件的完整示例。这篇讲清它怎么工作、怎么接、哪些地方容易出错。

Events 补的是「服务器找你」这一半

MCP 的工具调用是请求 / 响应:应用请服务器做一件事,服务器做完回结果。Events 反过来,服务器在某件事发生时通知应用,而且连接关掉之后照样能通知。Agent 盯部署、盯评论、盯告警,要的就是这个,不用再写定时轮询的循环。

它目前还是草案。MCP 官方的 experimental-ext-triggers-events 仓库里有一份 2026-02-19 的设计稿,状态写着 Draft proposal。AI SDK 的实现标为 experimental,只实现了其中 Webhook 那一部分。还有一条要先记住:服务器得单独实现这个扩展,支持 MCP 工具不代表支持事件。

三种投递方式怎么选

设计稿给每种事件类型声明它支持哪几种投递方式,没有哪种是必须的:

方式怎么工作适合
Poll(events/poll)客户端带着游标来问,服务器回一批事件、新游标和建议的下次轮询间隔服务器不想保存订阅状态
Push(events/stream)客户端开一个长连接,事件以通知的形式推过来,安静时有心跳带着当前游标本地或长期在线的客户端
Webhook(events/subscribe)客户端登记一个 https 回调地址和自己生成的签名密钥,服务器按 Standard Webhooks 签名后 POST 过来远程服务器、客户端不常驻

Webhook 订阅带有效期:客户端建议一个 ttlMs,服务器批一个 refreshBefore(为 null 表示不过期),客户端要在到期前再调一次 events/subscribe 续上。不续就自动过期,服务器回收资源。下面的例子都走 Webhook。

先跑通官方本地示例

AI SDK 文档里有一份 cookbook(Receive MCP Webhook Events),配套示例在 vercel/ai 仓库的 examples/mcp 下,包含一个会发评论的 MCP 服务器、一个 Webhook 接收端和一个订阅存储。按文档的步骤:

git clone https://github.com/vercel/ai.git
cd ai
pnpm install
pnpm --filter @ai-sdk/mcp... build

# 终端 1:启动带事件的 MCP 服务器
cd examples/mcp
pnpm server:events

# 终端 2:在同一目录跑客户端
pnpm client:events

文档写明的预期输出是:先列出事件目录,再打印订阅 ID 和收到的评论,服务器日志出现 Event acknowledged: 204,然后客户端退订退出。这一步不需要任何模型 API key,两个服务都只绑在本机回环地址上。

客户端代码里的五个动作

示例客户端 examples/mcp/src/events/client.ts 的主流程可以拆成五步:

  1. 先起接收端。用 experimental_createMCPEventWebhook 建好处理函数,再启动 HTTP 服务。服务器在订阅时会立刻往这个地址发校验请求,接收端没起来订阅就会失败。
  2. 发现事件。client.experimental_events.list() 返回事件名、参数结构、负载结构和支持的投递方式;目录分页时跟着 nextCursor 往下翻。
  3. 订阅。调 experimental_events.subscribe,传事件名、参数和投递方式:
const subscription = await client.experimental_events.subscribe({
  name: 'comment.created',
  arguments: { document_id: 'doc_123' },
  delivery: {
    mode: 'webhook',
    url: 'http://127.0.0.1:3003/mcp-events',
    allowInsecureLocalhost: true, // 仅本地演示,生产用 HTTPS
  },
});
  1. 收事件。处理函数里有三个回调:onEvent 收业务事件;onGap 表示有些事件补发不了,需要回源对账或提醒用户;onTerminated 表示服务器结束了订阅,要记下原因。
  2. 续期与退订。长期运行时,保存返回的 refreshBefore,到期前调 experimental_events.refresh({ id })。SDK 不带定时器,调度要自己写。示例服务器每次最多只批 60 秒的租期。

容易误会的一点:client.close() 只是释放连接,不会停止 Webhook 投递。不想再收,要显式 unsubscribe。

接收端:先落盘,再回 204

SDK 的 Webhook 助手会自动应答签名校验,并在调用 onEvent 之前验签。处理成功回 204;回调或存储失败回 503,让服务器重试。几条做法直接决定会不会丢事件:

事件内容是外部数据。cookbook 里给模型的系统提示写的是:把评论当数据,不当指令;那个摘要示例也没给模型任何工具。

不想自己管订阅:交给 Vercel Connect

示例里的文件存储只支持单进程。多实例部署要么自己实现同一套存储接口(共享、持久、按 MCP 服务器和授权主体隔离,更新要原子合并),要么让 Vercel Connect 托管:它负责在上游登记 Webhook、保存订阅、续期和清理,再把事件签名转发给你的应用。Connect 的 MCP Events 支持在 2026-10-15 进入公开测试。

按 cookbook,需要 @vercel/connect@^2.5.0 和 @ai-sdk/mcp@^2.0.74,在 createMCPClient 的 experimental_events 里换成 experimental_connectEventsAdapter,订阅时传 idempotencyKey,ttlMs: null 表示由 Connect 一直续到你主动停止。几个限制要提前知道:团队要开启 MCP Events;托管订阅目前只支持 production 和稳定的自定义环境,不支持 development 和 preview;接收端验签用 @vercel/connect/mcp 的 experimental_verifyMcpEvent,不能用上面那个直连用的 Webhook 助手。

Vercel 自家的 MCP 服务器是第一个现成的事件源:Agent 订阅一次,按团队、项目、环境过滤,后面由 Vercel MCP 管一个会过期的普通 Webhook,续期就延长,没人续就自己过期。这类事件 Webhook 走单独的每团队配额,不占账户 40 个 Webhook 的名额;投递格式是签名的 Standard Webhooks,data 里是 Vercel 原生的 Webhook 负载。

常见坑

完成标准

最后

先把官方本地示例跑通,看清订阅、校验、投递、退订这一圈,再决定自己管存储还是交给 Connect。MCP 本身还不熟的话,先看 MCP 是什么、怎么配;想了解另一种「异步结果」的做法,可以对照 MCP Tasks 上手。

关注公众号「智涌AI速递」

每天的 AI 快讯、实用教程和 AI项目实测,也会同步发到微信公众号。在微信里搜索「智涌AI速递」就能关注;不用微信的话,可以用 RSS 订阅本站。