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 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 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

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-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

Nächste Schritte

• Nachrichten an Ihren KI-Agenten weiterleiten sendet eingehende Nachrichten über einen Connector an Claude Managed Agents oder Grok Bot, ohne MCP.
• Webhooks & Events behandelt die Signaturverifizierung und den Event-Katalog.
• MCP-Server listet die Tools auf, mit denen Ihr Agent arbeitet.