MCP Events

Met MCP Events kan een MCP-client meekrijgen wat er in Bird gebeurt, zonder te pollen. Je client abonneert zich op een event, zoals een e-mail die binnenkomt in een mailbox, en de gehoste Bird MCP-server stuurt elk overeenkomend event naar een callback-URL die de client beheert. De client wekt je agent met het event, en de agent handelt erop met de tools van Bird.

MCP Events implementeert de MCP triggers and events-extensie met webhooklevering. Je MCP-client regelt het protocol: je verbindt hem met mcp.bird.com en vraagt hem ergens op te letten. ChatGPT ondersteunt dit.

Voordat je begint

Verbind je client met de gehoste server op https://mcp.bird.com/, of het /dynamic-endpoint ervan. Het /public-endpoint en de lokale bird mcp-server bieden geen MCP Events aan.
Log in met een account dat webhooks kan beheren. Elk abonnement vereist de webhooks:write-scope en de read-scope van het event, die de client opvraagt wanneer je inlogt.
Gebruik een client die de extensie en de webhookleveringsmodus ondersteunt.

Events waarop je je kunt abonneren

Event	Read-scope	Filters
`email_mailbox.message_received`	`mailbox:read`	`mailbox_id`, `thread_id`
`email.delivered`	`emails:read`	`broadcast_id`
`sms.received`	`sms:read`	`to`, een nummer van jou in E.164-formaat
`whatsapp.received`	`whatsapp:read`	geen
`amb.received`	`amb:read`	geen

events/list geeft de events terug waarop je aanmelding zich kan abonneren, elk met zijn filters en payload-schema. Een filter beperkt het abonnement tot één resource: mailbox_id ingesteld op mbx_… levert alleen de mail af die in die mailbox binnenkomt. Een event zonder filters levert elk voorval in de werkruimte af.

Nadat je een mailbox aanmaakt via de MCP-server, stelt het antwoord voor om je te abonneren op de mail ervan, met het event en mailbox_id al ingevuld.

Hoe een abonnement werkt

Abonneren. De client roept events/subscribe aan met het event, de filters, een callback-URL en een eigen signing secret (whsec_…).
Verifiëren. Voordat er iets wordt aangemaakt, posten we een ondertekend {"type":"verification","challenge":"…"} naar de callback. De callback moet binnen 4 seconden antwoorden met een 2xx waarvan de JSON-body challenge teruggeeft.
Ontvangen. Elk overeenkomend event komt als een POST binnen op de callback, ondertekend met het secret van de client.
Verlengen. Een abonnement loopt tot zijn refreshBefore-tijd, maximaal 24 uur en minimaal 5 minuten vanaf de door de client voorgestelde ttlMs. events/subscribe opnieuw aanroepen met hetzelfde event, dezelfde filters en callback verlengt het ter plekke. Een nieuw signing secret vervangt het oude zodra de callback het verifieert, en het oude blijft nog 5 minuten ondertekenen.
Beëindigen. De client roept events/unsubscribe aan, of stopt met verlengen en het abonnement verloopt.

Opnieuw abonneren vanuit dezelfde aanmelding met hetzelfde event, dezelfde filters en dezelfde callback is idempotent: het verlengt het abonnement dat je hebt in plaats van een nieuw abonnement aan te maken.

Afleveringen

Elke aflevering is een Standard Webhooks-verzoek:

webhook-id bevat het ID van het event, zodat de client een herhaling kan negeren.
webhook-timestamp en webhook-signature ondertekenen de body met het secret van de client.
X-MCP-Subscription-Id noemt het abonnement, zodat de client het juiste secret kan kiezen voordat het de body leest.

De body is {"eventId", "name", "timestamp", "data", "cursor": null}, waarbij data de payload van het event is zoals events/list die beschrijft. We bewaren geen afspeelbare historie, dus cursor is altijd null.

Een body is maximaal 256 KiB. Een amb.received-event dat groter zou zijn, heeft de berichttekst ingekort op een tekengrens en bevat body_truncated: true; de client haalt het volledige bericht op met amb_get. Elk ander event dat de limiet zou overschrijden, wordt niet verzonden.

Een mislukte aflevering wordt acht keer opnieuw geprobeerd over ongeveer acht uur, zodat een event waar je agent op reageert niet verouderd is wanneer het aankomt. Als de callback antwoordt met 410 Gone of 413 Content Too Large, laten we dat ene event vallen en houden we het abonnement. Mislukte afleveringen pauzeren een abonnement nooit: het eindigt wanneer de lease verloopt.

Wanneer een abonnement eindigt

Een abonnement eindigt wanneer de client zich uitschrijft, wanneer het verloopt, of wanneer iemand het verwijdert in Bird, via de Webhooks-lijst in het dashboard of via de API. Verwijderen stopt afleveringen onmiddellijk, maar de client wordt niet geïnformeerd: zolang de client het abonnement nog heeft, maakt hij het opnieuw aan bij de volgende verlenging en verifieert daarbij de callback opnieuw. Om een abonnement definitief te stoppen, verwijder je het ook uit de client.

Als de aanmelding achter een abonnement wordt ingetrokken, of de read-scope van het event verliest, stoppen we met afleveren en verloopt het abonnement binnen de lease.

Bekijk je abonnementen

Elk abonnement is een webhook-endpoint in je werkruimte. De Webhooks-lijst in het dashboard toont ze allemaal met het logo van de client, het event en de filters, en je kunt ze daar verwijderen. Abonnementen tellen mee voor de webhook-endpointlimiet van je organisatie.

Probleemoplossing

Fout	Wat het betekent	Wat je kunt doen
`-32015` `CallbackEndpointError`	De callback is niet geverifieerd. `data.reason` is `connection_refused`, `timeout`, `tls_error`, `http_4xx`, `http_5xx` of `challenge_failed`.	Maak de callback publiek bereikbaar via HTTPS en laat deze `challenge` binnen 4 seconden echoën.
`-32013` met `data.limit: "subscriptions"`	De organisatie heeft geen webhook-endpoint meer over.	Verwijder een endpoint dat je niet meer nodig hebt en abonneer je opnieuw.
`-32013` met `data.limit: "rate"`	Te veel callback-verificaties in korte tijd.	Wacht en probeer hetzelfde verzoek opnieuw.
`-32012`	De aanmelding mist de read-scope van het event of `webhooks:write`. `data.required` geeft aan welke ontbreekt.	Meld je opnieuw aan en verleen de scope.
`-32602`	Een filter dat het event niet accepteert, of een callback die niet HTTPS is.	Gebruik de filters die `events/list` teruggeeft.

Volgende stappen

Berichten naar je AI-agent routeren stuurt inkomende berichten naar Claude Managed Agents of Grok Bot via een connector, zonder MCP.
Webhooks & events behandelt handtekeningverificatie en de eventcatalogus.
MCP-server beschrijft de tools waarmee je agent werkt.

Ga verder met de documentatie, handleidingen en voorbeelden voor dit onderwerp.

Ontvang een implementatieoverzicht

Gerelateerde bronnen