--- title: "MCP Events" description: "Abonnieren Sie mit Ihrem MCP-Client Bird-Events, z. B. eine neue E-Mail in einer Mailbox oder eine eingehende SMS, und empfangen Sie jedes Event als signierten Webhook auf mcp.bird.com." canonical: "https://bird.com/de-de/dokumentation/ai/mcp-events" --- # MCP Events MCP Events ermöglicht einem MCP-Client, Änderungen in Bird ohne Polling mitzubekommen. Ihr Client abonniert ein Event, z. B. eine eingehende E-Mail in einer Mailbox, und der gehostete [Bird-MCP-Server](/docs/ai/mcp-server) sendet jedes passende Event an eine Callback-URL, die dem Client gehört. Der Client aktiviert Ihren Agenten mit dem Event, und der Agent reagiert darauf mit den Tools von Bird. MCP Events implementiert die [MCP-Erweiterung für Trigger und Events](https://github.com/modelcontextprotocol/experimental-ext-triggers-events) mit Webhook-Zustellung. Ihr MCP-Client übernimmt das Protokoll: Sie verbinden ihn mit `mcp.bird.com` und weisen ihn an, auf etwas zu achten. ChatGPT unterstützt das bereits. ## Bevor Sie beginnen - Verbinden Sie Ihren Client mit dem gehosteten Server unter `https://mcp.bird.com/` oder dessen `/dynamic`-Endpunkt. Der `/public`-Endpunkt und der lokale `bird mcp`-Server unterstützen MCP Events nicht. - Melden Sie sich mit einem Konto an, das Webhooks verwalten kann. Jedes Abonnement benötigt den Scope `webhooks:write` und den Lese-Scope des jeweiligen Events, den der Client bei der Anmeldung anfordert. - Verwenden Sie einen Client, der die Erweiterung und deren Webhook-Zustellmodus unterstützt. ## Events, die Sie abonnieren können | Event | Lese-Scope | Filter | | -------------------------------- | --------------- | ---------------------------------------- | | `email_mailbox.message_received` | `mailbox:read` | `mailbox_id`, `thread_id` | | `email.delivered` | `emails:read` | `broadcast_id` | | `sms.received` | `sms:read` | `to`, eine eigene Nummer im E.164-Format | | `whatsapp.received` | `whatsapp:read` | keine | | `amb.received` | `amb:read` | keine | `events/list` gibt die Events zurück, die Ihre Anmeldung abonnieren kann, jeweils mit den zugehörigen Filtern und dem Payload-Schema. Ein Filter grenzt das Abonnement auf eine einzelne Ressource ein: `mailbox_id` auf `mbx_…` gesetzt liefert nur die E-Mails, die in dieser Mailbox eingehen. Ein Event ohne Filter liefert jedes Vorkommen im Workspace. Nachdem Sie über den MCP-Server eine Mailbox erstellt haben, schlägt die Antwort vor, deren E-Mails zu abonnieren, wobei das Event und `mailbox_id` bereits ausgefüllt sind. ## So funktioniert ein Abonnement 1. **Abonnieren.** Der Client ruft `events/subscribe` mit dem Event, seinen Filtern, einer Callback-URL und einem eigenen Signaturgeheimnis auf (`whsec_…`). 2. **Verifizieren.** Bevor etwas erstellt wird, senden wir einen signierten `{"type":"verification","challenge":"…"}` an den Callback. Der Callback muss innerhalb von 4 Sekunden mit einem `2xx` antworten, dessen JSON-Body `challenge` zurückgibt. 3. **Empfangen.** Jedes passende Event wird als `POST` an den Callback gesendet, signiert mit dem Geheimnis des Clients. 4. **Erneuern.** Ein Abonnement gilt bis zu seinem `refreshBefore`-Zeitpunkt, maximal 24 Stunden und mindestens 5 Minuten ab dem vom Client vorgeschlagenen `ttlMs`. Ein erneuter Aufruf von `events/subscribe` mit demselben Event, denselben Filtern und demselben Callback erneuert es an Ort und Stelle. Ein neues Signaturgeheimnis ersetzt das alte, sobald der Callback es verifiziert, und das alte signiert noch 5 Minuten weiter. 5. **Beenden.** Der Client ruft `events/unsubscribe` auf, oder er erneuert nicht mehr und das Abonnement läuft ab. Erneutes Abonnieren mit derselben Anmeldung, demselben Event, denselben Filtern und demselben Callback ist idempotent: Es verlängert das bestehende Abonnement, anstatt ein neues zu erstellen. ## Zustellungen Jede Zustellung ist ein [Standard Webhooks](https://www.standardwebhooks.com/)-Request: - `webhook-id` enthält die ID des Events, damit der Client ein Duplikat verwerfen kann. - `webhook-timestamp` und `webhook-signature` signieren den Body mit dem Secret des Clients. - `X-MCP-Subscription-Id` benennt das Abonnement, damit der Client sein Secret auswählen kann, bevor er den Body liest. Der Body ist `{"eventId", "name", "timestamp", "data", "cursor": null}`, wobei `data` die Payload des Events ist, wie `events/list` sie beschreibt. Wir speichern keinen wiederholbaren Verlauf, daher ist `cursor` immer `null`. Ein Body ist maximal 256 KiB groß. Ein `amb.received`-Event, das größer wäre, wird im Nachrichtentext an einer Zeichengrenze gekürzt und enthält `body_truncated: true`; der Client ruft die vollständige Nachricht mit `amb_get` ab. Jedes andere Event, das das Limit überschreiten würde, wird nicht gesendet. Eine fehlgeschlagene Zustellung wird achtmal über etwa acht Stunden erneut versucht, sodass ein Event, auf das Ihr Agent reagiert, bei seiner Ankunft nicht veraltet ist. Wenn der Callback `410 Gone` oder `413 Content Too Large` antwortet, verwerfen wir dieses eine Event und behalten das Abonnement bei. Fehlgeschlagene Zustellungen pausieren ein Abonnement nie: Es endet, wenn seine Lease abläuft. ## Wenn ein Abonnement endet Ein Abonnement endet, wenn der Client sich abmeldet, wenn es abläuft oder wenn jemand es in Bird löscht, über die **Webhooks**-Liste im Dashboard oder über die API. Das Löschen stoppt Zustellungen sofort, aber der Client wird nicht benachrichtigt: Solange er das Abonnement noch hält, erstellt er es bei seiner nächsten Verlängerung erneut und verifiziert dabei seinen Callback wieder. Um ein Abonnement endgültig zu beenden, entfernen Sie es auch aus dem Client. Wenn die Anmeldung hinter einem Abonnement widerrufen wird oder den Read-Scope des Events verliert, stellen wir die Zustellung ein und das Abonnement läuft innerhalb seiner Lease ab. ## Ihre Abonnements einsehen Jedes Abonnement ist ein Webhook-Endpoint in Ihrem Workspace. Die **Webhooks**-Liste im Dashboard zeigt jedes Abonnement mit dem Logo des Clients, seinem Event und seinen Filtern an, und Sie können es dort löschen. Abonnements zählen zum Webhook-Endpoint-Limit Ihrer Organisation. ## Fehlerbehebung | Fehler | Bedeutung | Lösung | | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- | | `-32015` `CallbackEndpointError` | Der Callback wurde nicht verifiziert. `data.reason` ist `connection_refused`, `timeout`, `tls_error`, `http_4xx`, `http_5xx` oder `challenge_failed`. | Stellen Sie sicher, dass der Callback über HTTPS öffentlich erreichbar ist und `challenge` innerhalb von 4 Sekunden zurückgibt. | | `-32013` mit `data.limit: "subscriptions"` | Die Organisation hat keinen freien Webhook-Endpoint mehr. | Löschen Sie einen Endpoint, den Sie nicht mehr benötigen, und abonnieren Sie dann erneut. | | `-32013` mit `data.limit: "rate"` | Zu viele Callback-Verifizierungen in kurzer Zeit. | Warten Sie und versuchen Sie dieselbe Anfrage erneut. | | `-32012` | Der Anmeldung fehlt der Read-Scope des Events oder `webhooks:write`. `data.required` nennt den fehlenden Scope. | Melden Sie sich erneut an und erteilen Sie die Berechtigung. | | `-32602` | Ein Filter, den das Event nicht akzeptiert, oder ein Callback, der nicht HTTPS ist. | Verwenden Sie die Filter, die `events/list` zurückgibt. | ## Nächste Schritte - [Nachrichten an Ihren KI-Agenten weiterleiten](/docs/ai/route-messages-to-an-agent) sendet eingehende Nachrichten über einen Connector an Claude Managed Agents oder Grok Bot, ohne MCP. - [Webhooks & Events](/docs/guides/webhooks) behandelt die Signaturverifizierung und den Event-Katalog. - [MCP-Server](/docs/ai/mcp-server) listet die Tools auf, mit denen Ihr Agent arbeitet. ## 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)