--- title: "MCP Events" description: "Abonnez votre client MCP aux événements Bird, comme un nouvel e-mail dans une boîte aux lettres ou un SMS entrant, et recevez chacun sous forme de webhook signé sur mcp.bird.com." canonical: "https://bird.com/fr-fr/documentation/ai/mcp-events" --- # 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](/docs/ai/mcp-server) 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](https://github.com/modelcontextprotocol/experimental-ext-triggers-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 | Événement | Scope de lecture | Filtres | | -------------------------------- | ---------------- | --------------------------------------- | | `email_mailbox.message_received` | `mailbox:read` | `mailbox_id`, `thread_id` | | `email.delivered` | `emails:read` | `broadcast_id` | | `sms.received` | `sms:read` | `to`, un de vos numéros au format E.164 | | `whatsapp.received` | `whatsapp:read` | aucun | | `amb.received` | `amb:read` | aucun | `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](https://www.standardwebhooks.com/) : - `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 | Erreur | Signification | Action à effectuer | | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | | `-32015` `CallbackEndpointError` | Le callback n'a pas été vérifié. `data.reason` est `connection_refused`, `timeout`, `tls_error`, `http_4xx`, `http_5xx` ou `challenge_failed`. | Rendez le callback accessible publiquement via HTTPS, et faites-lui renvoyer `challenge` en moins de 4 secondes. | | `-32013` avec `data.limit: "subscriptions"` | L'organisation n'a plus d'endpoint webhook disponible. | Supprimez un endpoint dont vous n'avez plus besoin, puis abonnez-vous à nouveau. | | `-32013` avec `data.limit: "rate"` | Trop de vérifications de callback en peu de temps. | Attendez, puis réessayez la même requête. | | `-32012` | La session manque du scope de lecture de l'événement ou de `webhooks:write`. `data.required` indique celui qui manque. | Reconnectez-vous et accordez-le. | | `-32602` | Un filtre que l'événement n'accepte pas, ou un callback qui n'est pas HTTPS. | Utilisez les filtres que `events/list` renvoie. | ## Étapes suivantes - [Acheminer les messages vers votre agent IA](/docs/ai/route-messages-to-an-agent) envoie les messages entrants à Claude Managed Agents ou Grok Bot via un connecteur, sans MCP. - [Webhooks & events](/docs/guides/webhooks) couvre la vérification de signature et le catalogue d'événements. - [Serveur MCP](/docs/ai/mcp-server) répertorie les outils avec lesquels votre agent agit. ## 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)