MCP Events

MCP Events permite que un cliente MCP se entere de lo que ocurre en Bird sin hacer polling. Tu cliente se suscribe a un evento, como la llegada de un correo a un buzón, y el servidor Bird MCP alojado envía cada evento coincidente a una URL de callback que el cliente posee. El cliente despierta a tu agente con el evento, y el agente actúa sobre él con las herramientas de Bird.

MCP Events implementa la extensión de triggers y eventos de MCP con entrega por webhook. Tu cliente MCP se encarga del protocolo: lo conectas a mcp.bird.com y le pides que vigile algo. ChatGPT lo soporta actualmente.

Antes de empezar

• Conecta tu cliente al servidor alojado en https://mcp.bird.com/, o a su endpoint /dynamic. El endpoint /public y el servidor local bird mcp no sirven MCP Events.
• Inicia sesión con una cuenta que pueda gestionar webhooks. Cada suscripción necesita el scope webhooks:write y el scope de lectura de su evento, que el cliente solicita cuando inicias sesión.
• Usa un cliente que soporte la extensión y su modo de entrega por webhook.

Eventos a los que puedes suscribirte

events/list devuelve los eventos a los que tu inicio de sesión puede suscribirse, cada uno con sus filtros y esquema de payload. Un filtro limita la suscripción a un solo recurso: mailbox_id con valor mbx_… entrega solo el correo que llega a ese buzón. Un evento sin filtros entrega cada ocurrencia en el espacio de trabajo.

Después de crear un buzón a través del servidor MCP, la respuesta sugiere suscribirse a su correo, con el evento y mailbox_id ya completados.

Cómo funciona una suscripción

1. Suscribirse. El cliente llama a events/subscribe con el evento, sus filtros, una URL de callback y un secreto de firma propio (whsec_…).
2. Verificar. Antes de crear nada, enviamos un {"type":"verification","challenge":"…"} firmado al callback. El callback debe responder con un 2xx cuyo cuerpo JSON repita challenge, en un máximo de 4 segundos.
3. Recibir. Cada evento coincidente llega como un POST al callback, firmado con el secreto del cliente.
4. Renovar. Una suscripción dura hasta su tiempo refreshBefore, como máximo 24 horas y como mínimo 5 minutos a partir del ttlMs sugerido por el cliente. Llamar a events/subscribe de nuevo con el mismo evento, filtros y callback la renueva en el mismo lugar. Un nuevo secreto de firma reemplaza al anterior una vez que el callback lo verifica, y el anterior sigue firmando durante 5 minutos.
5. Finalizar. El cliente llama a events/unsubscribe, o deja de renovar y la suscripción expira.

Suscribirse de nuevo desde la misma sesión con el mismo evento, filtros y callback es idempotente: renueva la suscripción que ya tienes en lugar de crear otra.

Entregas

Cada entrega es una solicitud Standard Webhooks:

• webhook-id lleva el ID del evento, para que el cliente pueda descartar una repetición.
• webhook-timestamp y webhook-signature firman el cuerpo con el secreto del cliente.
• X-MCP-Subscription-Id identifica la suscripción, para que el cliente pueda elegir su secreto antes de leer el cuerpo.

El cuerpo es {"eventId", "name", "timestamp", "data", "cursor": null}, donde data es el payload del evento tal como lo describe events/list. No guardamos historial reproducible, así que cursor siempre es null.

Un cuerpo tiene como máximo 256 KiB. Un evento amb.received que superaría ese tamaño tiene el texto del mensaje recortado en un límite de carácter e incluye body_truncated: true; el cliente obtiene el mensaje completo con amb_get. Cualquier otro evento que exceda el límite no se envía.

Una entrega fallida se reintenta ocho veces a lo largo de unas ocho horas, de modo que un evento sobre el que actúa tu agente no esté obsoleto cuando llega. Si el callback responde 410 Gone o 413 Content Too Large, descartamos ese único evento y mantenemos la suscripción. Las entregas fallidas nunca pausan una suscripción: esta termina cuando se agota su tiempo de concesión.

Cuándo termina una suscripción

Una suscripción termina cuando el cliente cancela la suscripción, cuando expira, o cuando alguien la elimina en Bird, desde la lista de Webhooks del panel o a través de la API. Eliminarla detiene las entregas de inmediato, pero el cliente no recibe aviso: mientras aún conserve la suscripción, la vuelve a crear en su siguiente renovación, verificando de nuevo su callback. Para detener una suscripción de forma definitiva, elimínala también del cliente.

Si la sesión detrás de una suscripción se revoca, o pierde el alcance de lectura del evento, dejamos de entregar eventos y la suscripción expira dentro de su tiempo de concesión.

Consulta tus suscripciones

Cada suscripción es un endpoint de webhook en tu espacio de trabajo. La lista Webhooks del panel muestra cada una con el logo de su cliente, su evento y sus filtros, y puedes eliminarla desde ahí. Las suscripciones cuentan para el límite de endpoints de webhook de tu organización.

Solución de problemas

Próximos pasos

• Enruta mensajes a tu agente de IA envía mensajes entrantes a Claude Managed Agents o Grok Bot a través de un conector, sin MCP.
• Webhooks y eventos cubre la verificación de firma y el catálogo de eventos.
• Servidor MCP enumera las herramientas con las que actúa tu agente.