---
title: "MCP Events"
description: "将您的 MCP 客户端订阅 Bird 事件（例如邮箱中的新邮件或入站 SMS），并在 mcp.bird.com 上以签名 webhook 的形式接收每个事件。"
canonical: "https://bird.com/zh-sg/wendang/ai/mcp-events"
---

# MCP Events

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

MCP Events 通过 webhook 投递实现了 [MCP 触发器与事件扩展](https://github.com/modelcontextprotocol/experimental-ext-triggers-events)。您的 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` 已自动填好。

## 订阅的工作方式

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

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

## 投递

每次投递都是一个 [Standard Webhooks](https://www.standardwebhooks.com/) 请求：

- `webhook-id` 携带事件的 ID，客户端可据此丢弃重复投递。
- `webhook-timestamp` 和 `webhook-signature` 使用客户端的密钥对请求体签名。
- `X-MCP-Subscription-Id` 标识订阅，客户端可在读取请求体之前选取对应的密钥。

请求体为 `{"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`，我们会丢弃该事件但保留订阅。失败的投递不会暂停订阅：订阅在租约到期时结束。

## 订阅何时结束

订阅在以下情况下结束：客户端取消订阅、订阅过期，或有人在 Bird 中删除它（通过仪表板的 **Webhooks** 列表或 API）。删除会立即停止投递，但客户端不会收到通知：只要客户端仍持有该订阅，它会在下次续订时重新创建并再次验证回调。要彻底停止订阅，还需从客户端中移除它。

如果订阅背后的登录被撤销，或失去了事件的读取权限，我们会停止向其投递，订阅将在租约内过期。

## 查看你的订阅

每个订阅都是工作区中的一个 webhook 端点。控制面板的 **Webhooks** 列表会显示每个订阅及其客户端的图标、事件和过滤条件，你可以在那里删除它。订阅计入组织的 webhook 端点配额。

## 故障排查

| 错误                                         | 含义                                                                                                                        | 处理方式                                                         |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `-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` 返回的过滤器。                                |

## 后续步骤

- [将消息路由到你的 AI 代理](/docs/ai/route-messages-to-an-agent)通过连接器将入站消息发送到 Claude Managed Agents 或 Grok Bot，无需 MCP。
- [Webhooks 与事件](/docs/guides/webhooks)涵盖签名验证和事件目录。
- [MCP server](/docs/ai/mcp-server) 列出了你的智能体可以使用的工具。

## Related resources

- [Setting up your coding agent](/learn/basics/setting-up-your-coding-agent) (video)
- [What is an MCP server, and how does an agent use one to send messages?](/explained/platform/what-is-an-mcp-server-and-how-does-an-agent-send-messages) (answer)
- [Coding agents](/ai) (product)
- [Build with AI agents](/learn/paths/agents) (course)

[Get an implementation brief](/learn/workspace?topic=agents)