MCP Events

MCP Events permet à un client MCP de suivre ce qui se passe dans Bird sans interrogation périodique. Votre client s'abonne à un événement, par exemple un e-mail qui arrive dans une boîte aux lettres, et le serveur Bird MCP hébergé envoie chaque événement correspondant à une URL de rappel appartenant au client. Le client réveille votre agent avec l'événement, et l'agent agit dessus avec les outils de Bird.

MCP Events implémente l'extension MCP triggers and events avec une livraison par webhook. Votre client MCP gère le protocole : vous le connectez à mcp.bird.com et lui demandez de surveiller quelque chose. ChatGPT le prend en charge.

Avant de commencer

• Connectez votre client au serveur hébergé à l'adresse https://mcp.bird.com/, ou à son endpoint /dynamic. L'endpoint /public et le serveur bird mcp local ne servent pas MCP Events.
• Connectez-vous avec un compte autorisé à gérer les webhooks. Chaque abonnement nécessite le scope webhooks:write et le scope de lecture de son événement, que le client demande lors de la connexion.
• Utilisez un client qui prend en charge l'extension et son mode de livraison par webhook.

Événements auxquels vous pouvez vous abonner

events/list renvoie les événements auxquels votre connexion peut s'abonner, chacun avec ses filtres et son schéma de payload. Un filtre restreint l'abonnement à une seule ressource : mailbox_id défini sur mbx_… ne livre que le courrier arrivant dans cette boîte. Un événement sans filtre livre chaque occurrence dans l'espace de travail.

Après avoir créé une boîte mail via le serveur MCP, la réponse suggère de s'abonner à son courrier, avec l'événement et mailbox_id déjà renseignés.

Fonctionnement d'un abonnement

1. S'abonner. Le client appelle events/subscribe avec l'événement, ses filtres, une URL de callback et un secret de signature qui lui est propre (whsec_…).
2. Vérifier. Avant de créer quoi que ce soit, nous envoyons un {"type":"verification","challenge":"…"} signé au callback. Le callback doit répondre par un 2xx dont le corps JSON reprend challenge, dans un délai de 4 secondes.
3. Recevoir. Chaque événement correspondant arrive sous forme de POST au callback, signé avec le secret du client.
4. Renouveler. Un abonnement dure jusqu'à son heure refreshBefore, au maximum 24 heures et au minimum 5 minutes à partir de la valeur ttlMs suggérée par le client. Appeler events/subscribe à nouveau avec le même événement, les mêmes filtres et le même callback le renouvelle sur place. Un nouveau secret de signature remplace l'ancien une fois que le callback l'a vérifié, et l'ancien continue de signer pendant 5 minutes.
5. Terminer. Le client appelle events/unsubscribe, ou cesse de renouveler et l'abonnement expire.

Se réabonner depuis la même connexion avec le même événement, les mêmes filtres et la même URL de callback est idempotent : cela renouvelle l'abonnement existant au lieu d'en créer un autre.

Livraisons

Chaque livraison est une requête Standard Webhooks :

• webhook-id contient l'identifiant de l'événement, ce qui permet au client d'ignorer un doublon.
• webhook-timestamp et webhook-signature signent le corps avec le secret du client.
• X-MCP-Subscription-Id identifie l'abonnement, ce qui permet au client de choisir son secret avant de lire le corps.

Le corps est {"eventId", "name", "timestamp", "data", "cursor": null}, où data est le payload de l'événement tel que events/list le décrit. Nous ne conservons pas d'historique rejouable, donc cursor vaut toujours null.

Un corps fait au maximum 256 Kio. Un événement amb.received qui dépasserait cette taille voit son texte de message tronqué à une limite de caractère et contient body_truncated: true ; le client récupère le message complet avec amb_get. Tout autre événement qui dépasserait la limite n'est pas envoyé.

Une livraison en échec est réessayée huit fois sur environ huit heures, de sorte qu'un événement sur lequel votre agent agit n'est pas périmé quand il arrive. Si le callback répond 410 Gone ou 413 Content Too Large, nous abandonnons cet événement unique et conservons l'abonnement. Les livraisons en échec ne suspendent jamais un abonnement : il prend fin à l'expiration de son bail.

Fin d'un abonnement

Un abonnement prend fin quand le client se désabonne, quand il expire, ou quand quelqu'un le supprime dans Bird, depuis la liste Webhooks du tableau de bord ou via API. Le supprimer arrête les livraisons immédiatement, mais le client n'en est pas informé : tant qu'il détient encore l'abonnement, il le recrée lors de son prochain renouvellement, en vérifiant à nouveau son callback. Pour arrêter définitivement un abonnement, supprimez-le aussi côté client.

Si la connexion associée à un abonnement est révoquée, ou perd le scope de lecture de l'événement, nous cessons de lui livrer des événements, et il expire dans les limites de son bail.

Voir vos abonnements

Chaque abonnement est un endpoint webhook dans votre espace de travail. La liste Webhooks du tableau de bord affiche chacun avec le logo de son client, son événement et ses filtres, et vous pouvez le supprimer depuis cette liste. Les abonnements sont décomptés de la limite d'endpoints webhook de votre organisation.

Dépannage

Étapes suivantes

• Acheminer les messages vers votre agent IA envoie les messages entrants à Claude Managed Agents ou Grok Bot via un connecteur, sans MCP.
• Webhooks & events couvre la vérification de signature et le catalogue d'événements.
• Serveur MCP répertorie les outils avec lesquels votre agent agit.