--- title: "MCP Events" description: "Suscribe tu cliente MCP a eventos de Bird, como un nuevo correo en un buzón o un SMS entrante, y recibe cada uno como un webhook firmado en mcp.bird.com." canonical: "https://bird.com/es-es/documentacion/ai/mcp-events" --- # 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](/docs/ai/mcp-server) 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](https://github.com/modelcontextprotocol/experimental-ext-triggers-events) 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 | Evento | Scope de lectura | Filtros | | -------------------------------- | ---------------- | ------------------------------------- | | `email_mailbox.message_received` | `mailbox:read` | `mailbox_id`, `thread_id` | | `email.delivered` | `emails:read` | `broadcast_id` | | `sms.received` | `sms:read` | `to`, un número tuyo en formato E.164 | | `whatsapp.received` | `whatsapp:read` | ninguno | | `amb.received` | `amb:read` | ninguno | `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](https://www.standardwebhooks.com/): - `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 | Error | Qué significa | Qué hacer | | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | | `-32015` `CallbackEndpointError` | El callback no se verificó. `data.reason` es `connection_refused`, `timeout`, `tls_error`, `http_4xx`, `http_5xx` o `challenge_failed`. | Haz que el callback sea accesible públicamente a través de HTTPS y que responda con `challenge` en un máximo de 4 segundos. | | `-32013` con `data.limit: "subscriptions"` | La organización no tiene endpoints de webhook disponibles. | Elimina un endpoint que ya no necesites y vuelve a suscribirte. | | `-32013` con `data.limit: "rate"` | Demasiadas verificaciones de callback en poco tiempo. | Espera y reintenta la misma solicitud. | | `-32012` | El inicio de sesión no tiene el scope de lectura del evento o `webhooks:write`. `data.required` indica cuál falta. | Inicia sesión de nuevo y concédelo. | | `-32602` | Un filtro que el evento no acepta, o un callback que no es HTTPS. | Usa los filtros que devuelve `events/list`. | ## Próximos pasos - [Enruta mensajes a tu agente de IA](/docs/ai/route-messages-to-an-agent) envía mensajes entrantes a Claude Managed Agents o Grok Bot a través de un conector, sin MCP. - [Webhooks y eventos](/docs/guides/webhooks) cubre la verificación de firma y el catálogo de eventos. - [Servidor MCP](/docs/ai/mcp-server) enumera las herramientas con las que actúa tu agente. ## 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)