--- title: "MCP Events" description: "Inscreva seu cliente MCP em eventos Bird, como um novo e-mail em uma caixa de entrada ou uma mensagem SMS recebida, e receba cada um como um webhook assinado em mcp.bird.com." canonical: "https://bird.com/pt-br/documentacao/ai/mcp-events" --- # 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](/docs/ai/mcp-server) 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](https://github.com/modelcontextprotocol/experimental-ext-triggers-events) 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 | Evento | Escopo de leitura | Filtros | | -------------------------------- | ----------------- | ------------------------------------ | | `email_mailbox.message_received` | `mailbox:read` | `mailbox_id`, `thread_id` | | `email.delivered` | `emails:read` | `broadcast_id` | | `sms.received` | `sms:read` | `to`, um número seu no formato E.164 | | `whatsapp.received` | `whatsapp:read` | nenhum | | `amb.received` | `amb:read` | nenhum | `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](https://www.standardwebhooks.com/): - `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 | Erro | O que significa | O que fazer | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- | | `-32015` `CallbackEndpointError` | O callback não foi verificado. `data.reason` é `connection_refused`, `timeout`, `tls_error`, `http_4xx`, `http_5xx` ou `challenge_failed`. | Torne o callback acessível publicamente via HTTPS e faça-o ecoar `challenge` em até 4 segundos. | | `-32013` com `data.limit: "subscriptions"` | A organização não tem mais endpoints de webhook disponíveis. | Exclua um endpoint que você não precisa mais e assine novamente. | | `-32013` com `data.limit: "rate"` | Verificações de callback demais em pouco tempo. | Aguarde e tente novamente com a mesma solicitação. | | `-32012` | O login não tem o escopo de leitura do evento ou `webhooks:write`. `data.required` indica qual está faltando. | Faça login novamente e conceda a permissão. | | `-32602` | Um filtro que o evento não aceita, ou um callback que não é HTTPS. | Use os filtros que `events/list` retorna. | ## Próximos passos - [Encaminhe mensagens para o seu agente de IA](/docs/ai/route-messages-to-an-agent) envia mensagens recebidas para Claude Managed Agents ou Grok Bot por meio de um conector, sem MCP. - [Webhooks & events](/docs/guides/webhooks) cobre a verificação de assinatura e o catálogo de eventos. - [Servidor MCP](/docs/ai/mcp-server) lista as ferramentas com as quais seu agente atua. ## 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)