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

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:

• 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

Passaggi successivi

• Instrada i messaggi al tuo agente AI invia i messaggi in entrata a Claude Managed Agents o Grok Bot tramite un connettore, senza MCP.
• Webhook ed eventi tratta la verifica della firma e il catalogo degli eventi.
• Il server MCP elenca gli strumenti con cui il tuo agente opera.