--- title: "MCP Events" description: "Iscrivi il tuo client MCP agli eventi Bird, come una nuova email in una casella di posta o un SMS in entrata, e ricevi ciascuno come webhook firmato su mcp.bird.com." canonical: "https://bird.com/it-it/documentazione/ai/mcp-events" --- # MCP Events MCP Events permette a un client MCP di sapere cosa succede in Bird senza polling. Il tuo client si iscrive a un evento, ad esempio un'email in arrivo in una casella di posta, e il [server Bird MCP](/docs/ai/mcp-server) ospitato invia ogni evento corrispondente a un URL di callback di proprietà del client. Il client attiva il tuo agente con l'evento, e l'agente agisce con gli strumenti di Bird. MCP Events implementa l'[estensione MCP triggers and events](https://github.com/modelcontextprotocol/experimental-ext-triggers-events) con consegna via webhook. Il tuo client MCP gestisce il protocollo: lo colleghi a `mcp.bird.com` e gli chiedi di monitorare qualcosa. ChatGPT lo supporta. ## Prima di iniziare - Collega il tuo client al server ospitato su `https://mcp.bird.com/` o al suo endpoint `/dynamic`. L'endpoint `/public` e il server locale `bird mcp` non servono MCP Events. - Accedi con un account che può gestire i webhook. Ogni iscrizione richiede lo scope `webhooks:write` e lo scope di lettura del suo evento, che il client richiede al momento dell'accesso. - Usa un client che supporta l'estensione e la sua modalità di consegna via webhook. ## Eventi a cui puoi iscriverti | Evento | Scope di lettura | Filtri | | -------------------------------- | ---------------- | ------------------------------------ | | `email_mailbox.message_received` | `mailbox:read` | `mailbox_id`, `thread_id` | | `email.delivered` | `emails:read` | `broadcast_id` | | `sms.received` | `sms:read` | `to`, un tuo numero in formato E.164 | | `whatsapp.received` | `whatsapp:read` | nessuno | | `amb.received` | `amb:read` | nessuno | `events/list` restituisce gli eventi a cui il tuo accesso può iscriversi, ciascuno con i propri filtri e lo schema del payload. Un filtro restringe la sottoscrizione a una singola risorsa: `mailbox_id` impostato su `mbx_…` consegna solo la posta che arriva in quella casella. Un evento senza filtri consegna ogni occorrenza nello spazio di lavoro. Dopo aver creato una casella di posta tramite il server MCP, la risposta suggerisce di iscriversi alla sua posta, con l'evento e `mailbox_id` già compilati. ## Come funziona una sottoscrizione 1. **Sottoscrizione.** Il client chiama `events/subscribe` con l'evento, i suoi filtri, un URL di callback e un signing secret proprio (`whsec_…`). 2. **Verifica.** Prima di creare qualsiasi cosa, inviamo un `{"type":"verification","challenge":"…"}` firmato al callback. Il callback deve rispondere con un `2xx` il cui body JSON ripete `challenge`, entro 4 secondi. 3. **Ricezione.** Ogni evento corrispondente arriva come `POST` al callback, firmato con il secret del client. 4. **Rinnovo.** Una sottoscrizione dura fino al suo tempo `refreshBefore`, al massimo 24 ore e almeno 5 minuti rispetto al `ttlMs` suggerito dal client. Chiamare di nuovo `events/subscribe` con lo stesso evento, gli stessi filtri e lo stesso callback la rinnova sul posto. Un nuovo signing secret sostituisce il precedente una volta che il callback lo verifica, e il vecchio continua a firmare per 5 minuti. 5. **Fine.** Il client chiama `events/unsubscribe`, oppure smette di rinnovare e la sottoscrizione scade. Sottoscrivere di nuovo dallo stesso accesso con lo stesso evento, gli stessi filtri e lo stesso callback è idempotente: rinnova la sottoscrizione esistente anziché crearne un'altra. ## Consegne Ogni consegna è una richiesta [Standard Webhooks](https://www.standardwebhooks.com/): - `webhook-id` contiene l'ID dell'evento, così il client può scartare un duplicato. - `webhook-timestamp` e `webhook-signature` firmano il body con il secret del client. - `X-MCP-Subscription-Id` identifica la sottoscrizione, così il client può selezionare il proprio secret prima di leggere il body. Il body è `{"eventId", "name", "timestamp", "data", "cursor": null}`, dove `data` è il payload dell'evento come descritto da `events/list`. Non conserviamo uno storico riproducibile, quindi `cursor` è sempre `null`. Un body è al massimo 256 KiB. Un evento `amb.received` che supererebbe questa dimensione ha il testo del messaggio troncato a un confine di carattere e include `body_truncated: true`; il client recupera il messaggio completo con `amb_get`. Qualsiasi altro evento che supererebbe il limite non viene inviato. Una consegna non riuscita viene riprovata otto volte nell'arco di circa otto ore, quindi un evento su cui il tuo agente agisce non è obsoleto quando arriva. Se il callback risponde `410 Gone` o `413 Content Too Large`, scartiamo quel singolo evento e manteniamo la sottoscrizione. Le consegne non riuscite non mettono mai in pausa una sottoscrizione: termina quando scade il suo lease. ## Quando una sottoscrizione termina Una sottoscrizione termina quando il client annulla l'iscrizione, quando scade, o quando qualcuno la elimina in Bird, dalla lista **Webhooks** della dashboard o tramite le API. Eliminarla interrompe le consegne immediatamente, ma il client non viene avvisato: finché detiene ancora la sottoscrizione, la ricrea al rinnovo successivo, verificando di nuovo il proprio callback. Per interrompere una sottoscrizione definitivamente, rimuovila anche dal client. Se l'accesso associato a una sottoscrizione viene revocato, o perde lo scope di lettura dell'evento, interrompiamo le consegne e la sottoscrizione scade entro il suo lease. ## Visualizza le tue sottoscrizioni Ogni sottoscrizione è un endpoint webhook nel tuo spazio di lavoro. La lista **Webhooks** nella dashboard mostra ciascuna con il logo del client, il suo evento e i suoi filtri, e puoi eliminarla da lì. Le sottoscrizioni concorrono al limite di endpoint webhook della tua organizzazione. ## Risoluzione dei problemi | Errore | Significato | Cosa fare | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | | `-32015` `CallbackEndpointError` | La verifica del callback è fallita. `data.reason` è `connection_refused`, `timeout`, `tls_error`, `http_4xx`, `http_5xx` o `challenge_failed`. | Rendi il callback raggiungibile pubblicamente tramite HTTPS e fai in modo che restituisca `challenge` entro 4 secondi. | | `-32013` con `data.limit: "subscriptions"` | L'organizzazione non ha più endpoint webhook disponibili. | Elimina un endpoint che non ti serve più, poi sottoscrivi di nuovo. | | `-32013` con `data.limit: "rate"` | Troppe verifiche del callback in poco tempo. | Attendi, poi riprova con la stessa richiesta. | | `-32012` | L'accesso non ha lo scope di lettura dell'evento o `webhooks:write`. `data.required` indica quello mancante. | Accedi di nuovo e concedilo. | | `-32602` | Un filtro non previsto dall'evento, o un callback che non è HTTPS. | Usa i filtri restituiti da `events/list`. | ## Passaggi successivi - [Instrada i messaggi al tuo agente AI](/docs/ai/route-messages-to-an-agent) invia i messaggi in entrata a Claude Managed Agents o Grok Bot tramite un connettore, senza MCP. - [Webhook ed eventi](/docs/guides/webhooks) tratta la verifica della firma e il catalogo degli eventi. - Il [server MCP](/docs/ai/mcp-server) elenca gli strumenti con cui il tuo agente opera. ## 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)