Servidor MCP

El servidor Bird MCP expone la Bird API como herramientas de Model Context Protocol. Entre los clientes compatibles están Claude Code, Cursor, VS Code, Codex, Claude, ChatGPT y Muse. Pueden enviar por todos los canales que Bird opera, configurar esos canales e inspeccionar tu espacio de trabajo sin copiar comandos cURL. Puedes ejecutarlo de dos formas, y la mayoría prefiere la primera:

1. Alojado (mcp.bird.com): una URL y un inicio de sesión en el navegador. Nada que instalar, sin CLI, sin clave API. Esta es la ruta recomendada.
2. Local sobre stdio (bird mcp): herramientas que se ejecutan en tu máquina dentro del bird CLI, para agentes de shell o para ejecutarlo tú mismo.

El servidor alojado omite estas herramientas exclusivas de stdio:

• auth_signup, auth_verify_email y auth_create_org: estas herramientas crean tu primera credencial, antes de que puedas autenticarte en el servidor alojado.
• compliance_attachments_upload: esta herramienta lee una ruta de archivo local. En el servidor alojado, esa ruta apuntaría al sistema de archivos del servidor y podría subir el archivo incorrecto.

Alojado: conectar a mcp.bird.com

Elige un endpoint

Usa https://mcp.bird.com para la mayoría de las conexiones. Es el endpoint recomendado: la mayoría de los clientes MCP ya buscan y seleccionan herramientas internamente del catálogo completo. Algunos clientes no buscan herramientas internamente o imponen un límite estricto en la cantidad de herramientas que un servidor puede exponer. /dynamic es para esos clientes.

Ambos endpoints alojados usan Streamable HTTP y el mismo inicio de sesión Bird OAuth:

El endpoint dinámico te da acceso a las mismas operaciones alojadas a través de execute. El endpoint estándar y el servidor stdio local mantienen sus herramientas individuales; no listan search ni execute.

No necesitas instalar un binario ni crear un token. Conectar requiere dos pasos, y ambos son obligatorios:

1. Añade el servidor: proporciónale al cliente la URL del endpoint que elegiste.
2. Autentícate: inicia sesión en tu navegador para que el cliente tenga un token que actúe como tú.

Ambos endpoints requieren autenticación. Un cliente que solo tiene la URL recibe un 401 hasta que inicies sesión. Algunos clientes inician la sesión por sí mismos la primera vez que contactan al servidor; otros dejan el servidor como "needs login" y esperan a que hagas clic. Los pasos de tu cliente indican su comportamiento.

Usa el descubrimiento dinámico de herramientas

Si tu cliente rechaza el servidor porque ofrece demasiadas herramientas, conéctate a https://mcp.bird.com/dynamic y completa el inicio de sesión OAuth. Tu cliente lista dos herramientas:

• search encuentra herramientas por nombre o palabras clave de la descripción. Cada coincidencia incluye su nombre, descripción, esquema de entrada y anotaciones que describen si lee o modifica datos.
• execute invoca una herramienta seleccionada con sus argumentos. Puede leer datos, enviar mensajes, modificar registros o eliminarlos, según la herramienta seleccionada.

Por ejemplo, tu agente puede encontrar la herramienta de espacio de trabajo con esta llamada:

{
  "name": "search",
  "arguments": { "query": "workspace_get", "limit": 3 }
}

Después de leer el esquema de entrada devuelto, invoca esa herramienta a través de execute:

{
  "name": "execute",
  "arguments": { "tool": "workspace_get", "arguments": {} }
}

El resultado contiene tu espacio de trabajo actual. También puedes buscar con palabras clave de tarea como send email. La búsqueda devuelve cinco coincidencias por defecto, acepta un limit de uno a 10 y acepta consultas de hasta 500 caracteres. Si el resultado tiene has_more: true, acota tu consulta para encontrar coincidencias más relevantes.

Los resultados de búsqueda no añaden herramientas al catálogo de tu cliente. Los nombres mencionados en resultados o instrucciones de recuperación también pasan por execute. La ejecución usa tus permisos existentes; si una operación necesita más permisos, tu cliente puede pedirte que los autorices. Encontrar una herramienta no otorga acceso a ella.

La ejecución dinámica devuelve datos para herramientas que de otro modo muestran widgets. Usa el endpoint estándar para widgets interactivos de MCP Apps. Los clientes ven una sola herramienta de ejecución, así que los ajustes de aprobación por herramienta se aplican a execute en su conjunto; revisa la operación seleccionada antes de aprobar una llamada. Este endpoint ejecuta llamadas a herramientas y no ejecuta JavaScript ni otro código proporcionado.

Conecta un cliente

Los ejemplos a continuación usan el endpoint estándar. Para el descubrimiento dinámico, sustituye https://mcp.bird.com/dynamic como la URL del servidor y sigue los mismos pasos de inicio de sesión.

Claude Code

Añade el servidor:

claude mcp add --transport http bird https://mcp.bird.com

claude mcp list ahora reporta bird como ! Needs authentication. Claude Code no abre el navegador por sí solo, así que inicia sesión desde dentro de una sesión:

1. Ejecuta /mcp.
2. Selecciona bird y presiona Enter.
3. Elige Authenticate. Tu navegador abre la pantalla de consentimiento de Bird; apruébala ahí.

El servidor aparece entonces como conectado y las herramientas funcionan. Una ejecución sin interfaz (claude -p) no tiene panel /mcp, así que autentícate primero desde tu shell con claude mcp login bird. Para iniciar sesión de nuevo más tarde, /mcp ofrece Re-authenticate; Clear authentication elimina el token almacenado.

Instalar el bird-ai plugin declara este servidor por ti, lo que reemplaza el comando claude mcp add. La autenticación sigue siendo necesaria porque un plugin puede incluir un servidor pero no puede emitir una concesión. Selecciona /mcp > bird > Authenticate después de instalarlo.

Cursor

En ~/.cursor/mcp.json:

{
  "mcpServers": {
    "bird": {
      "url": "https://mcp.bird.com"
    }
  }
}

Abre Customize en la barra lateral de Cursor y selecciona MCPs. Busca bird, sigue su solicitud de inicio de sesión, aprueba la pantalla de consentimiento de Bird en el navegador y vuelve a Cursor.

OpenCode

El plugin de OpenCode de Bird registra el servidor por ti, junto con las agent skills de Bird:

opencode plugin github:messagebird/bird-ai --global

OpenCode añade cada herramienta de MCP al contexto del modelo, así que el plugin se conecta al endpoint dinámico. Con el modo experimental de código de OpenCode activado (OPENCODE_EXPERIMENTAL_CODE_MODE=1 o OPENCODE_EXPERIMENTAL=1), OpenCode mantiene las herramientas de MCP detrás de su propia búsqueda, y el plugin se conecta al catálogo completo en https://mcp.bird.com.

Para añadir el servidor sin el plugin, coloca esto en opencode.json, en tu proyecto o en ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bird": {
      "type": "remote",
      "url": "https://mcp.bird.com/dynamic"
    }
  },
  "permission": {
    "bird_execute": "ask"
  }
}

Luego inicia sesión, lo que abre tu navegador en la pantalla de consentimiento de Bird:

opencode mcp auth bird

Reinicia OpenCode para cargar el plugin. opencode mcp list muestra bird como conectado una vez que apruebes. El plugin, igual que la entrada permission anterior, hace que OpenCode pregunte antes de cada llamada a execute, porque la herramienta que ejecuta puede modificar tu espacio de trabajo.

VS Code

En .vscode/mcp.json en tu proyecto:

{
  "servers": {
    "bird": {
      "type": "http",
      "url": "https://mcp.bird.com"
    }
  }
}

¿Usas settings.json? Coloca la misma entrada bird bajo mcp.servers. VS Code la mueve a tu mcp.json de usuario, que puedes abrir con MCP: Open User Configuration:

{
  "mcp": {
    "servers": {
      "bird": {
        "type": "http",
        "url": "https://mcp.bird.com"
      }
    }
  }
}

VS Code te pide que confíes en el servidor la primera vez que arranca y luego ejecuta el flujo OAuth por sí mismo: aprueba la pantalla de consentimiento de Bird en la ventana del navegador que abre. Si no aparece ninguna ventana, inicia o reinicia bird desde el comando MCP: List Servers y apruébalo entonces. El permiso resultante aparece en Accounts > Manage Trusted MCP Servers, que también es donde revocas el acceso de VS Code.

ChatGPT y Codex

Instala Bird en ChatGPT o Codex, inicia sesión en tu espacio de trabajo de Bird y pide a tu agente que envíe mensajes, gestione dominios y números, y compruebe la entrega.

Para configurar Codex manualmente, añade esta entrada en ~/.codex/config.toml:

[mcp_servers.bird]
url = "https://mcp.bird.com"

Después inicia sesión desde tu terminal, lo que abre el navegador:

codex mcp login bird

Claude

Bird aparece en el directorio de conectores de Claude. Abre Bird en el directorio y haz clic en Connect to Claude para iniciar sesión y aprobar la pantalla de consentimiento. Activa el conector en cada conversación desde + > Connectors. Esto funciona en Claude en la web y en la aplicación de escritorio.

Para añadirlo manualmente, abre Customize > Connectors, haz clic en + y luego en Add custom connector. Pega https://mcp.bird.com y haz clic en Add. Después haz clic en Connect en el conector Bird para iniciar sesión y aprobar la pantalla de consentimiento. En los planes Team y Enterprise, un propietario añade el conector una vez desde Organization settings > Connectors, y cada miembro sigue haciendo clic en Connect en Customize > Connectors para obtener su propio permiso. Activa el conector en cada conversación desde + > Connectors.

Para configurar ChatGPT manualmente, sigue la guía de configuración de apps MCP de OpenAI, usando https://mcp.bird.com como URL del servidor y OAuth como autenticación. Completa el inicio de sesión en el navegador de Bird y luego usa Bird en tu chat.

Muse

Muse añade Bird como conector personalizado. En un chat de Muse, pídele que configure uno:

Set up a custom connector to the Bird MCP server at https://mcp.bird.com following https://bird.com/docs/ai/mcp-server.md so you can work with my Bird workspace.

Muse responde con un enlace de conexión para esta sesión. Ábrelo y aprueba la pantalla de consentimiento de Bird en el navegador. El enlace solo funciona para ti y expira con la sesión. Si deja de funcionar, pídele a Muse uno nuevo.

Factory Droid

droid mcp add bird https://mcp.bird.com --type http

Luego ejecuta /mcp dentro de droid y completa el inicio de sesión en el navegador desde el administrador de servidores.

Antigravity

El plugin de Antigravity de Bird registra el servidor por ti, junto con las agent skills de Bird:

curl -fsSL https://raw.githubusercontent.com/messagebird/bird-ai/main/antigravity.sh | bash

Para añadir el servidor sin el plugin, coloca esto en ~/.gemini/config/mcp_config.json, o en .agents/mcp_config.json para un solo proyecto. Antigravity lee la dirección de un servidor remoto desde serverUrl, así que conserva ese nombre de clave:

{
  "mcpServers": {
    "bird": {
      "serverUrl": "https://mcp.bird.com"
    }
  }
}

Luego inicia sesión: abre Customizations en la barra lateral (en el IDE, abre Agent settings con Cmd+, en macOS o Ctrl+, en Windows y Linux) y selecciona Authenticate junto a bird. Si bird no aparece en la lista, reinicia Antigravity. Aprueba la pantalla de consentimiento de Bird en el navegador, copia el código de autorización que muestra, pégalo en Antigravity y selecciona Submit.

Agent Plugins

El plugin bird-ai declara este servidor en un mcp.json que sigue la especificación de Agent Plugins. Un host que implemente la especificación lee ese archivo cuando se instala el plugin, así que no hay configuración de servidor que escribir: instala el plugin e inicia sesión.

Cualquier otro host

Busca el ajuste que añade un servidor MCP remoto, HTTP o personalizado, normalmente en un menú de Conectores o Integraciones, y proporciónale la URL. La ubicación del campo varía; usa la URL del endpoint alojado que hayas elegido. Luego busca la opción de inicio de sesión de ese cliente: un control Connect, Authorize o Needs login junto al servidor, un subcomando login, o una ventana del navegador que el cliente abre por sí mismo. Un cliente que lista las herramientas de Bird pero falla en cada llamada tiene la URL pero aún necesita una concesión de acceso.

Qué ocurre cuando inicias sesión

Tu navegador abre una pantalla de consentimiento de Bird. Inicia sesión, elige si conceder permisos de espacio de trabajo o de organización, y selecciona qué permisos delegar. Como los clientes MCP se registran solos, el nombre del cliente es autodeclarado, así que la pantalla lo marca como not verified by Bird. Confirma que es el cliente que realmente lanzaste antes de aprobar. Después, las herramientas aparecen en la lista del agente y el token se renueva silenciosamente, así que este paso se hace una sola vez por cliente.

La forma más rápida de comprobar que funcionó es hacer que el agente llame a whoami: devuelve el usuario con sesión iniciada, así que una respuesta real significa que la concesión de acceso está activa. En el endpoint dinámico, llámalo a través de execute con tool: "whoami" y arguments vacío.

La concesión de acceso se limita a la intersección de lo que el cliente solicitó, lo que aprobaste y lo que realmente tienes; los ámbitos org:owner y platform-admin nunca son delegables. Aparece en la lista de Connected apps de tu perfil, y revocarla ahí desconecta al cliente de inmediato.

Cómo funciona el handshake

No necesitas esto para conectar un cliente. Es relevante si estás depurando un cliente que no se autentica, o si estás escribiendo uno.

El nivel alojado habla Streamable HTTP y no requiere credenciales: no almacena secretos ni valida nada por sí mismo. Cada solicitud lleva tu propio token bearer de OAuth, que API de Bird valida en cada petición. El servidor no tiene estado y el tráfico regional se enruta automáticamente, así que la misma URL funciona desde cualquier lugar.

El flujo de inicio de sesión usa MCP estándar. Los clientes solo difieren en qué lo desencadena: la primera llamada a una herramienta o seleccionar Authenticate. Una vez que el flujo comienza, los pasos de autenticación no necesitan configuración adicional:

1. El cliente hace una solicitud sin autenticar y recibe 401 con un encabezado WWW-Authenticate que apunta a los metadatos de recurso protegido de Bird según RFC 9728 (/.well-known/oauth-protected-resource).
2. A partir de ahí descubre el servidor de autorización y luego se registra dinámicamente (RFC 7591). El registro dinámico elimina la necesidad de un client ID precompartido o de configuración manual.
3. Tu navegador abre la pantalla de consentimiento de Bird.
4. El cliente intercambia el resultado por un token de acceso (PKCE; se renueva automáticamente) y aparecen las herramientas de Bird.

Local: ejecútalo sobre stdio con el CLI

Ejecuta el servidor local MCP dentro del bird CLI para agentes con acceso a shell o para acceder a archivos en tu máquina. Instala el CLI, ejecuta bird auth login una vez y apunta tu cliente al comando bird mcp.

Tú no ejecutas bird mcp: tu cliente lo lanza y se comunica con él por stdin/stdout. Todo cliente necesita los mismos dos datos: el comando (bird) y el argumento (mcp). Esta vía no requiere inicio de sesión por cliente porque bird auth login ya posee el permiso.

Cursor

{
  "mcpServers": {
    "bird": {
      "command": "bird",
      "args": ["mcp"]
    }
  }
}

VS Code

En .vscode/mcp.json en tu proyecto:

{
  "servers": {
    "bird": {
      "type": "stdio",
      "command": "bird",
      "args": ["mcp"]
    }
  }
}

Claude Code

claude mcp add bird -- bird mcp

Cómo se autentica el servidor local

El servidor local actúa como tú y reutiliza la sesión almacenada de CLI. bird auth login abre un flujo OAuth en el navegador donde concedes un subconjunto de los permisos de tu espacio de trabajo. El token emitido tiene los mismos límites de permisos que la concesión del servidor alojado. Los ámbitos org:owner y platform-admin no están disponibles. bird mcp lee y renueva la sesión almacenada del archivo de credenciales CLI, cuyo modo es 0600. Como en el servidor alojado, la configuración de tu cliente no contiene BIRD_API_KEY ni ningún otro secreto. Si la sesión no existe, bird mcp se niega a iniciar y te indica que ejecutes bird auth login.

No expones ningún puerto: el servidor se ejecuta en tu máquina, dentro del sandbox del cliente, exactamente mientras el cliente lo necesite. El host API sigue la región de tu sesión automáticamente; --base-url (o BIRD_API_URL) la reemplaza para pruebas en un entorno que no sea producción.

Qué cubren las herramientas

El conjunto de herramientas abarca todos los canales en los que opera Bird, más las tareas de cuenta y configuración asociadas. Está curado en lugar de exponer toda la superficie de API: cada herramienta está limitada a una tarea que un agente realmente realiza, y las operaciones destructivas están anotadas para que los hosts puedan pedir confirmación antes de ejecutarlas.

Email tiene la mayor cantidad de herramientas, porque tiene la mayor superficie que configurar. Los demás canales comparten la misma forma de enviar y consultar.

Mensajería

• Enviar e inspeccionar email: email_send, email_send_batch, email_list y email_get, que devuelve el mensaje con su estado de entrega agregado. Los estados de entrega por destinatario y el registro de eventos son llamadas de herramienta independientes.
• Enviar e inspeccionar SMS: sms_send, sms_send_batch, sms_get, sms_list y sms_list_events, reflejando la misma forma que email. sms_templates_list y sms_templates_get leen el catálogo de plantillas.
• Enviar e inspeccionar WhatsApp: whatsapp_send, whatsapp_get, whatsapp_list, whatsapp_list_events y whatsapp_media. Las plantillas son una superficie de autoría completa dentro de whatsapp_templates_*, con contenido por versión y por idioma.
• Inspeccionar tramos de llamadas de voz: voice_legs_get y voice_legs_list leen tramos de llamada, con estadísticas por país y por código de respuesta en voice_stats_*. voice_session_credentials_create crea la credencial del espacio de trabajo que un cliente SIP o softphone usa para autenticarse.
• Verificar un destinatario: verify_verifications_create envía un código de verificación de un solo uso, verify_verifications_check valida lo que el destinatario envió y verify_verifications_next_channel recurre a otro canal.
• Crear una llamada de voz (preview): voice_calls_create prepara una llamada saliente usando la publicación activa de una secuencia habilitada y no archivada. Una persona revisa y ejecuta la solicitud en el navegador; prepararla no realiza la llamada. Consulta Crear una llamada de voz para permisos e instrucciones de reintento. El servidor local bird mcp requiere una versión de CLI que incluya esta herramienta.

Preparar un canal para enviar

• Configurar dominios de envío: email_domains_create añade un dominio de envío y devuelve los registros DNS que debes publicar; email_domains_verify los vuelve a verificar; más email_domains_list y email_domains_get.
• Reclamar y registrar remitentes de SMS: sms_senders_create reclama un remitente, sms_senders_requirements informa qué exige un país de él y sms_senders_registrations_create lo registra. El tráfico A2P en EE. UU. pasa por las herramientas de marca, campaña y envío de sms_10dlc_*.
• Aprovisionar números: numbers_available_list busca, numbers_orders_create compra, numbers_cancel devuelve al final del periodo de pago (o de inmediato cuando el número no tiene suscripción) y numbers_release devuelve ahora. whatsapp_numbers_precheck indica si WhatsApp aceptará un número antes de que lo solicites.
• Comprobar que la cuenta puede enviar: las herramientas de trust_* informan los requisitos de la organización que condicionan la compra de un número o el registro de un remitente.

Entregabilidad de email

• Crear plantillas de email: email_templates_create, email_templates_list, email_templates_get, email_templates_update, email_templates_duplicate y email_templates_preview (renderiza un borrador con valores de ejemplo sin enviarlo). Las versiones se gestionan en email_templates_versions_*, donde email_templates_versions_submit congela un borrador y lo convierte en la versión que sirven los envíos, y email_templates_versions_languages_* edita el contenido por idioma de un borrador. Nada de lo que un agente escribe llega a un destinatario hasta que lo envía.
• Gestionar supresiones: email_suppressions_list, email_suppressions_check (¿es seguro enviar a esta dirección?), email_suppressions_add y email_suppressions_remove (anotada como destructiva, porque eliminar una supresión sin motivo daña la reputación del remitente).
• Gestionar IPs dedicadas y pools: email_dedicated_ips_create, email_dedicated_ips_list, email_dedicated_ips_get, email_dedicated_ips_assign (mover una a un pool) y email_dedicated_ips_delete; más email_ip_pools_create, email_ip_pools_list, email_ip_pools_get, email_ip_pools_update y email_ip_pools_delete para los pools a través de los que enrutas los envíos.

Audiencia y configuración

• Gestionar contactos y audiencias: contacts_* y contact_properties_* para las personas a las que envías, audiences_* para las listas a las que envías, y preferences_* para concesiones de consentimiento y cancelaciones de suscripción.
• Aprovisionar Realtime: realtime_apps_* y realtime_apps_keys_* crean las apps y claves con las que se conectan los clientes de Realtime.
• Buscar a alguien: lookup_phone_number y lookup_email informan de lo que Bird sabe sobre una dirección antes de que envíes a ella.
• Inspeccionar la configuración: webhooks_list, workspace_get y whoami (el usuario autenticado: id, email, nombre).

Tu cliente muestra la lista de herramientas activas con nombres, descripciones y esquemas de entrada. Trata esa lista como el inventario de referencia. Una buena primera tarea para probar de principio a fin:

Call whoami to find my email, then send me a test email from onboarding@messagebird.dev and tell me when it's delivered.

¿MCP o el CLI?

Misma superficie, mismo modelo de autenticación, distintos invocadores. Para agentes con acceso a shell (Claude Code, la terminal de Cursor, CI), el CLI es más ligero: salida JSON, códigos de salida semánticos y muchos menos tokens por operación. MCP es para hosts que invocan herramientas en lugar de ejecutar shells, y el endpoint alojado llega a los que no pueden ejecutar un binario en absoluto (Claude Desktop, ChatGPT, móvil). No tienes que decidir de antemano: la URL alojada no requiere instalación, y el bird mcp local ya está disponible una vez que tienes el CLI.

Próximos pasos

• MCP Events: suscribe tu cliente a eventos de Bird, como correo nuevo en un buzón, y recibe cada uno como un webhook firmado.
• Consultar analíticas de email con IA: pregunta sobre entrega, interacción y latencia en lenguaje natural.
• Onboarding con IA: la versión quickstart de esta página, más el corpus de documentación legible por máquina.
• Agent skills: el plugin bird-ai del marketplace, skills más este servidor MCP, instalados en un solo paso.
• CLI para agentes: controla Bird desde agentes con acceso a shell sin MCP: salida JSON, códigos de salida semánticos, inicio de sesión con OAuth.
• Autenticación: claves API, regiones y cómo se autorizan las solicitudes.