MCP Events

MCP Events permite que um cliente MCP acompanhe o que acontece no Bird sem polling. Seu cliente se inscreve em um evento, como um e-mail chegando em uma caixa de entrada, e o servidor Bird MCP hospedado envia cada evento correspondente para uma URL de callback que o cliente possui. O cliente aciona seu agente com o evento, e o agente age sobre ele com as ferramentas do Bird.

MCP Events implementa a extensão de triggers e eventos MCP com entrega por webhook. Seu cliente MCP lida com o protocolo: você o conecta ao mcp.bird.com e pede para ele observar algo. O ChatGPT já oferece suporte.

Antes de começar

• Conecte seu cliente ao servidor hospedado em https://mcp.bird.com/, ou ao seu endpoint /dynamic. O endpoint /public e o servidor local bird mcp não servem MCP Events.
• Faça login com uma conta que possa gerenciar webhooks. Cada inscrição precisa do escopo webhooks:write e do escopo de leitura do seu evento, que o cliente solicita quando você faz login.
• Use um cliente que suporte a extensão e seu modo de entrega por webhook.

Eventos nos quais você pode se inscrever

events/list retorna os eventos aos quais seu login pode se inscrever, cada um com seus filtros e schema de payload. Um filtro restringe a inscrição a um recurso: mailbox_id definido como mbx_… entrega apenas o e-mail que chega naquela caixa de entrada. Um evento sem filtros entrega toda ocorrência no espaço de trabalho.

Depois que você cria uma caixa de entrada pelo servidor MCP, a resposta sugere a inscrição no e-mail dela, com o evento e mailbox_id já preenchidos.

Como funciona uma inscrição

1. Inscrever. O client chama events/subscribe com o evento, seus filtros, uma URL de callback e um segredo de assinatura próprio (whsec_…).
2. Verificar. Antes de criar qualquer coisa, enviamos um {"type":"verification","challenge":"…"} assinado ao callback. O callback precisa responder com um 2xx cujo corpo JSON repita challenge, em até 4 segundos.
3. Receber. Cada evento correspondente chega como um POST ao callback, assinado com o segredo do client.
4. Renovar. Uma inscrição dura até seu horário de refreshBefore, no máximo 24 horas e no mínimo 5 minutos a partir do ttlMs sugerido pelo client. Chamar events/subscribe novamente com o mesmo evento, filtros e callback a renova no lugar. Um novo segredo de assinatura substitui o anterior assim que o callback o verifica, e o anterior continua assinando por 5 minutos.
5. Encerrar. O client chama events/unsubscribe, ou para de renovar e a inscrição expira.

Assinar novamente a partir do mesmo login com o mesmo evento, filtros e callback é idempotente: renova a assinatura que você já tem em vez de criar outra.

Entregas

Cada entrega é uma solicitação Standard Webhooks:

• webhook-id carrega o ID do evento, para que o client possa descartar uma repetição.
• webhook-timestamp e webhook-signature assinam o corpo com o segredo do client.
• X-MCP-Subscription-Id identifica a assinatura, para que o client possa escolher seu segredo antes de ler o corpo.

O corpo é {"eventId", "name", "timestamp", "data", "cursor": null}, onde data é o payload do evento conforme events/list o descreve. Não mantemos histórico reproduzível, então cursor é sempre null.

O corpo tem no máximo 256 KiB. Um evento amb.received que seria maior tem o texto da mensagem cortado em um limite de caractere e inclui body_truncated: true; o client busca a mensagem completa com amb_get. Qualquer outro evento que exceda o limite não é enviado.

Uma entrega que falha é tentada novamente oito vezes ao longo de cerca de oito horas, para que um evento sobre o qual seu agente age não esteja obsoleto quando chegar. Se o callback responder 410 Gone ou 413 Content Too Large, descartamos aquele evento e mantemos a assinatura. Entregas com falha nunca pausam uma assinatura: ela termina quando seu lease expira.

Quando uma assinatura termina

Uma assinatura termina quando o client cancela a inscrição, quando ela expira ou quando alguém a exclui em Bird, na lista Webhooks do painel ou pela API. Excluí-la interrompe as entregas imediatamente, mas o client não é notificado: enquanto ele ainda mantém a assinatura, ele a cria novamente na próxima renovação, verificando seu callback outra vez. Para encerrar uma assinatura definitivamente, remova-a do client também.

Se o login por trás de uma assinatura for revogado, ou perder o escopo de leitura do evento, paramos de entregar a ele, e a assinatura expira dentro do seu lease.

Veja suas assinaturas

Toda assinatura é um endpoint de webhook no seu espaço de trabalho. A lista Webhooks do painel mostra cada uma com o logo do cliente, seu evento e seus filtros, e você pode excluí-la ali. As assinaturas contam para o limite de endpoints de webhook da sua organização.

Solução de problemas

Próximos passos

• Encaminhe mensagens para o seu agente de IA envia mensagens recebidas para Claude Managed Agents ou Grok Bot por meio de um conector, sem MCP.
• Webhooks & events cobre a verificação de assinatura e o catálogo de eventos.
• Servidor MCP lista as ferramentas com as quais seu agente atua.