MCP Events

MCP Events 让 MCP 客户端无需轮询即可了解 Bird 中发生的事件。您的客户端订阅一个事件（例如邮件到达邮箱），托管的 Bird MCP 服务器会将每个匹配的事件发送到客户端拥有的回调 URL。客户端使用该事件唤醒您的代理，代理再通过 Bird 的工具对其进行处理。

MCP Events 通过 webhook 投递实现了 MCP 触发器与事件扩展。您的 MCP 客户端负责处理协议：将其连接到 mcp.bird.com，然后让它监听某个事件。ChatGPT 已支持该功能。

开始之前

将您的客户端连接到托管服务器 https://mcp.bird.com/，或其 /dynamic 端点。/public 端点和本地 bird mcp 服务器不提供 MCP Events 服务。
使用具有 webhook 管理权限的账号登录。每个订阅都需要 webhooks:write 作用域以及对应事件的读取作用域，客户端会在您登录时请求这些权限。
使用支持该扩展及其 webhook 投递模式的客户端。

事件	读取作用域	筛选条件
`email_mailbox.message_received`	`mailbox:read`	`mailbox_id`、`thread_id`
`email.delivered`	`emails:read`	`broadcast_id`
`sms.received`	`sms:read`	`to`，您的一个 E.164 格式号码
`whatsapp.received`	`whatsapp:read`	无
`amb.received`	`amb:read`	无

events/list 返回当前登录可订阅的事件，包括每个事件的过滤器和载荷结构。过滤器将订阅范围缩小到单个资源：将 mailbox_id 设为 mbx_… 时，只会投递到达该邮箱的邮件。没有过滤器的事件会投递工作区中的所有匹配项。

通过 MCP 服务器创建邮箱后，响应会建议订阅该邮箱的邮件，其中事件和 mailbox_id 已自动填好。

订阅。 客户端调用 events/subscribe，传入事件、过滤器、回调 URL 以及客户端自己的签名密钥（whsec_…）。
验证。 在创建任何内容之前，我们会向回调发送一个签名的 {"type":"verification","challenge":"…"}。回调必须在 4 秒内返回一个 2xx，其 JSON 正文需回显 challenge。
接收。 每个匹配的事件以 POST 的形式发送到回调，使用客户端的密钥签名。
续订。 订阅持续到其 refreshBefore 时间，最长 24 小时，最短为客户端建议的 ttlMs 起 5 分钟。使用相同的事件、过滤器和回调再次调用 events/subscribe 即可原地续订。新的签名密钥在回调验证通过后替换旧密钥，旧密钥会继续签名 5 分钟。
结束。 客户端调用 events/unsubscribe，或停止续订，订阅随即过期。

使用同一登录、相同的事件、过滤器和回调再次订阅是幂等的：它会续订现有订阅，而不是创建新的订阅。

每次投递都是一个 Standard Webhooks 请求：

请求体为 {"eventId", "name", "timestamp", "data", "cursor": null}，其中 data 是 events/list 所描述的事件载荷。我们不保留可重放的历史记录，因此 cursor 始终为 null。

请求体最大为 256 KiB。如果 amb.received 事件超出该限制，消息文本会在字符边界处截断，并附带 body_truncated: true；客户端可通过 amb_get 获取完整消息。其他超出限制的事件不会被发送。

投递失败后会在约八小时内重试八次，因此事件到达时不会过时。如果回调返回 410 Gone 或 413 Content Too Large，我们会丢弃该事件但保留订阅。失败的投递不会暂停订阅：订阅在租约到期时结束。

错误	含义	处理方式
`-32015` `CallbackEndpointError`	回调验证失败。`data.reason` 为 `connection_refused`、`timeout`、`tls_error`、`http_4xx`、`http_5xx` 或 `challenge_failed`。	确保回调地址可通过 HTTPS 公开访问，并在 4 秒内回显 `challenge`。
`-32013`，附带 `data.limit: "subscriptions"`	组织已无剩余 webhook 端点配额。	删除不再需要的端点，然后重新订阅。
`-32013` 带有 `data.limit: "rate"`	短时间内回调验证次数过多。	等待后使用相同请求重试。
`-32012`	当前登录缺少事件的读取权限范围或 `webhooks:write`。`data.required` 指出了缺少的权限。	重新登录并授予该权限。
`-32602`	事件不支持该过滤器，或回调地址不是 HTTPS。	使用 `events/list` 返回的过滤器。

继续查看此主题的文档、指南和示例。