Qué puede hacer un agente de IA en Bird: CLI, MCP, registro desde el terminal y controles de gasto

En septiembre anunciamos que la infraestructura de comunicaciones de Bird está abierta a los agentes de IA. Este artículo es la versión para desarrolladores de ese anuncio. Indica los comandos que ejecuta un agente, a qué se conecta, cómo obtiene una cuenta y los límites que puedes imponerle, cada uno con la página que lo documenta.

La CLI

Un agente que puede ejecutar comandos de shell, como Claude Code, el terminal de Cursor o un trabajo de CI, debería empezar con la CLI, porque usa muchos menos tokens por operación que MCP. El servidor MCP, descrito a continuación, es para los hosts que llaman a herramientas y no pueden ejecutar un shell, y para los eventos de MCP.

bird es un único binario diseñado para que lo maneje un agente. La salida es JSON en stdout, los errores van a stderr y el código de salida indica la categoría del fallo, así que un agente puede actuar según el resultado sin analizar texto.

curl -fsSL https://cli.bird.com/install.sh | sh
bird auth login

Tres flags hacen la mayor parte del trabajo para un agente. --example imprime un cuerpo de solicitud válido, --dry-run muestra la solicitud sin enviarla y --idempotency-key permite reintentar con seguridad cuando se pierde una respuesta. CLI para agentes describe el contrato, y la referencia de CLI enumera cada comando.

El servidor MCP alojado

Algunos hosts llaman a herramientas y no pueden ejecutar un shell, como Claude Desktop, ChatGPT o una aplicación móvil. Para ellos, el servidor MCP de Bird funciona en https://mcp.bird.com. Da esa URL a un cliente MCP e inicia sesión en tu navegador, y el cliente obtendrá un token que actúa en tu nombre. La pantalla de consentimiento muestra los permisos que solicita el cliente, y puedes desmarcar los que el agente no necesita. No instalas nada ni copias ninguna clave de API. Entre los clientes compatibles están Claude Code, Cursor, VS Code, Codex, Claude, ChatGPT y Muse, y Bird aparece en el directorio de conectores de Claude.

El servidor expone la API de Bird como herramientas, así que un agente conectado puede enviar por los canales que gestiona Bird, configurarlos e inspeccionar tu espacio de trabajo. Un cliente con un límite de herramientas puede conectarse a https://mcp.bird.com/dynamic, que ofrece dos herramientas: search busca una operación y execute la llama. Con los eventos de MCP, un cliente se suscribe a lo que ocurre en tu espacio de trabajo, como un SMS entrante o un correo nuevo en un buzón, de modo que el agente no tiene que consultarlo periódicamente.

Servidor MCP explica los pasos para cada cliente. Una vez instalada la CLI, bird mcp ejecuta un servidor local por stdio. Añade las herramientas de registro y la subida de archivos locales, pero no ofrece eventos de MCP.

Registro desde una terminal

Un agente que no tiene cuenta puede crearla desde una terminal, sin sesión de navegador y sin visitar el panel. Necesita acceso a una bandeja de entrada de correo, porque el código de inicio de sesión llega por correo electrónico:

bird auth signup you@example.com
bird auth verify-email you@example.com --code 123456
bird auth create-org "Acme" --workspace-name "Production" --region eu1 --onboarding-ticket "YOUR_ONBOARDING_TICKET"

bird auth create-org crea la organización y su espacio de trabajo, y guarda una credencial que la CLI y el servidor MCP local usan a partir de ese momento. --region elige dónde residen la cuenta y sus datos, us1 o eu1. Los mismos tres pasos funcionan con curl, para un agente que no tiene CLI. El servidor MCP alojado no ofrece registro, porque un cliente necesita una credencial antes de poder conectarse a él.

Esa primera credencial es amplia. Tiene los permisos que el propietario de la nueva organización puede delegar, incluida la facturación de la organización, y el registro no muestra ninguna pantalla de consentimiento para restringirla. Antes de que un agente funcione sin supervisión, crea una clave de API con ámbitos limitados para él. Registro autónomo explica paso a paso ambas vías.

Controles sobre lo que puede hacer un agente

Un agente que envía a través de Bird tiene una credencial y gasta tu saldo. Controles de agentes documenta en una sola página lo que lo limita. Estos son los cuatro controles que debes configurar antes de que un agente funcione sin supervisión. La lista de destinos permitidos y el límite de gasto diario se aplican a SMS. El correo electrónico y WhatsApp no tienen ninguno de los dos, así que ahí son los ámbitos de la clave y el monedero los que limitan al agente. La misma página explica cómo reintentar de forma segura: envía una cabecera Idempotency-Key, o --idempotency-key en la CLI, y una solicitud repetida se acepta una sola vez.

Claves de API con ámbitos limitados. Una clave de API pertenece a un espacio de trabajo y tiene los ámbitos que le asignas, cada uno un área de producto con nivel read o write. Una clave que solo envía SMS tiene sms:write, y una solicitud fuera de sus ámbitos devuelve 403. Una clave no puede emitir otra clave ni acceder a la facturación.

bird auth login --scope api_keys:write --scope sms:write   # an existing account
bird api-keys create --name "Support agent" --scope sms:write

El inicio de sesión debe tener api_keys:write y los ámbitos que tendrá la clave. La credencial del registro desde la terminal ya los tiene, así que después de bird auth create-org solo ejecutas el segundo comando. No vuelvas a iniciar sesión ahí: un nuevo inicio de sesión sustituye la credencial del registro. Ejecútalo en una shell donde BIRD_API_KEY no esté definida, porque la CLI da prioridad a esa clave frente a un inicio de sesión, y una clave no puede emitir claves.

Después, dale al agente la clave y nada más amplio. Define BIRD_API_KEY en el entorno del agente, o envía la clave como token bearer desde tu código. Un inicio de sesión queda guardado en la máquina donde se ejecutó, y un agente en esa máquina sin BIRD_API_KEY lo usa. Ejecuta el agente en otro lugar, o elimina el inicio de sesión con bird auth logout.

Destinos de SMS denegados por defecto. Un espacio de trabajo envía SMS a los países de su lista de destinos permitidos. La lista empieza vacía, y Bird añade el país de origen de tu organización cuando está definido. Un envío a través de la SMS de API a cualquier otro país se rechaza con 422 SMSDestinationNotEnabled antes de resolver el remitente, así que se deniega el envío de un agente dirigido a un país inesperado. Los códigos de verificación no usan esta lista. Verify tiene la suya, en la que todos los países empiezan habilitados, y Voice también tiene su propia configuración.

Límites de gasto diario. Cada país de destino de SMS puede tener un límite de gasto diario, en la moneda de tu monedero. Cuando el gasto del día en ese país alcanza el límite, Bird rechaza los mensajes nuevos a ese país hasta la medianoche UTC. El límite no es exacto: el gasto se contabiliza cuando se cobra un mensaje, así que los mensajes ya aceptados pueden hacer que el total del día lo supere. Los códigos de verificación enviados por SMS cuentan para el límite. Este comando habilita los Países Bajos con un límite de 25 EUR al día, en un espacio de trabajo cuyo monedero está en EUR:

bird sms destinations update --destination "NL=true;25EUR"

Para cambiar la lista de permitidos o un límite se necesita el ámbito sms_management con nivel write. Dale al agente que envía sms y reserva sms_management para la credencial que configura el espacio de trabajo; así el agente no puede subir sus propios límites.

El monedero prepago. Los envíos de pago por uso se descuentan del monedero prepago de tu organización. Un envío de SMS que el saldo no puede cubrir se rechaza con 402. Algunos cargos se liquidan después de aceptar un envío (el correo electrónico en un plan de Email de pago y las tarifas que se cobran en la entrega), y la recarga automática rellena el monedero desde una tarjeta guardada, así que consulta las reglas del monedero antes de tratar el saldo como un límite estricto. Las operaciones de facturación requieren el permiso de facturación de la organización, que una clave de API no puede tener. Da a un agente desatendido una clave con ámbitos limitados, y añadir fondos seguirá en manos de las personas responsables del presupuesto.

Próximos pasos

Start building with Bird in minutes.