O que um agente de IA pode fazer na Bird: CLI, MCP, cadastro pelo terminal e controles de gastos

Em setembro, anunciamos que a infraestrutura de comunicações da Bird está aberta a agentes de IA. Este post é a versão desse anúncio para desenvolvedores. Ele apresenta os comandos que um agente executa, aquilo a que ele se conecta, como ele obtém uma conta e os limites que você pode impor a ele, cada um com a página que o documenta.

A CLI

Um agente que pode executar comandos de shell, como o Claude Code, o terminal do Cursor ou um job de CI, deve começar pela CLI: ela usa muito menos tokens por operação do que o MCP. O servidor MCP, descrito a seguir, serve para hosts que chamam ferramentas e não podem executar um shell, e para os MCP Events.

A bird é um único binário feito para ser controlado por um agente. A saída é JSON no stdout, os erros vão para o stderr e o código de saída indica a categoria da falha, para que o agente possa decidir o próximo passo com base no resultado sem interpretar texto.

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

Três flags fazem a maior parte do trabalho de um agente. --example imprime um corpo de requisição válido, --dry-run mostra a requisição sem enviá-la e --idempotency-key torna segura uma nova tentativa quando uma resposta se perde. CLI para agentes descreve o contrato, e a referência da CLI lista cada comando.

O servidor MCP hospedado

Alguns hosts chamam ferramentas e não podem executar um shell, como o Claude Desktop, o ChatGPT ou um aplicativo móvel. Para eles, o servidor MCP da Bird roda em https://mcp.bird.com. Informe essa URL a um cliente MCP e faça login pelo navegador, e o cliente passa a ter um token que age em seu nome. A tela de consentimento mostra as permissões que o cliente solicita, e você pode desmarcar as que o agente não precisa. Você não instala nada nem copia nenhuma chave de API. Os clientes compatíveis incluem Claude Code, Cursor, VS Code, Codex, Claude, ChatGPT e Muse, e a Bird está listada no diretório de conectores do Claude.

O servidor expõe a API da Bird como ferramentas, para que um agente conectado possa enviar mensagens pelos canais que a Bird opera, configurar esses canais e inspecionar seu espaço de trabalho. Um cliente com limite no número de ferramentas pode se conectar a https://mcp.bird.com/dynamic, que lista duas ferramentas: search encontra uma operação e execute a chama. Com os MCP Events, um cliente assina o que acontece no seu espaço de trabalho, como um SMS recebido ou um novo e-mail em uma caixa de correio, para que o agente não precise consultar periodicamente.

Servidor MCP traz os passos para cada cliente. Com a CLI instalada, bird mcp executa um servidor local via stdio. Ele acrescenta as ferramentas de cadastro e uploads de arquivos locais, mas não oferece os MCP Events.

Cadastro pelo terminal

Um agente sem conta pode criar uma pelo terminal, sem sessão no navegador e sem acessar o painel. Ele precisa de acesso a uma caixa de entrada de email, porque o código de login chega por email:

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 cria a organização e o espaço de trabalho dela, e armazena uma credencial que a CLI e o servidor MCP local passam a usar a partir daí. --region escolhe onde a conta e os dados dela ficam, us1 ou eu1. As mesmas três etapas funcionam com curl, para um agente que não tem a CLI. O servidor MCP hospedado não oferece cadastro, porque um cliente precisa de uma credencial antes de se conectar a ele.

Essa primeira credencial é ampla. Ela tem as permissões que o proprietário da nova organização pode delegar, incluindo o faturamento da organização, e o cadastro não mostra nenhuma tela de consentimento para restringi-la. Antes que um agente rode sem supervisão, crie uma chave de API com escopo para ele. Cadastro self-service explica os dois caminhos.

Controles sobre o que um agente pode fazer

Um agente que envia pela Bird tem uma credencial e gasta o seu saldo. Controles de agentes documenta em uma única página o que o limita. Estes são os quatro controles que você deve configurar antes que um agente rode sem supervisão. A lista de destinos permitidos e o limite diário de gastos se aplicam a SMS. Email e WhatsApp não têm nenhum dos dois, então são os escopos da chave e a carteira que limitam um agente nesses canais. A mesma página trata de novas tentativas seguras: envie um cabeçalho Idempotency-Key, ou --idempotency-key na CLI, e uma solicitação repetida é aceita uma única vez.

Chaves de API com escopo. Uma chave de API pertence a um espaço de trabalho e tem os escopos que você atribui a ela, cada um uma área de produto no nível read ou write. Uma chave que só envia SMS tem sms:write, e uma solicitação fora dos escopos dela retorna 403. Uma chave não pode emitir outra chave nem acessar o faturamento.

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

O login precisa ter api_keys:write e os escopos que a chave vai receber. A credencial do cadastro pelo terminal já tem esses escopos, então, depois de bird auth create-org, você executa apenas o segundo comando. Não faça login de novo nesse momento: um novo login substitui a credencial do cadastro. Execute o comando em um shell onde BIRD_API_KEY não esteja definida, porque a CLI dá preferência a essa chave em vez do login, e uma chave não pode emitir chaves.

Depois, entregue ao agente a chave e nada mais amplo. Defina BIRD_API_KEY no ambiente do agente ou envie a chave como bearer token a partir do seu código. Um login fica armazenado na máquina onde foi feito, e um agente nessa máquina sem BIRD_API_KEY passa a usá-lo. Execute o agente em outro lugar ou remova o login com bird auth logout.

Destinos de SMS bloqueados por padrão. Um espaço de trabalho envia SMS para os países da sua lista de destinos permitidos. A lista começa vazia, e Bird adiciona o país de origem da sua organização quando ele está definido. Um envio pela SMS API para qualquer outro país é rejeitado com 422 SMSDestinationNotEnabled antes que um remetente seja definido, então um agente direcionado a um país inesperado é recusado. Os códigos de verificação não usam essa lista. Verify tem a sua própria, em que todos os países começam habilitados, e Voice também tem configurações próprias.

Limites diários de gastos. Cada país de destino de SMS pode ter um limite diário de gastos, na moeda da sua carteira. Quando o gasto do dia com esse país atinge o limite, a Bird recusa novas mensagens para lá até a meia-noite UTC. O limite não é exato: o gasto é contabilizado quando a mensagem é cobrada, então mensagens já aceitas podem fazer o total do dia ultrapassá-lo. Os códigos de verificação enviados pelo SMS contam para o limite. Este comando habilita a Holanda com um limite de 25 EUR por dia, em um espaço de trabalho cuja carteira está em EUR:

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

Para alterar a lista de permitidos ou um limite, é preciso ter o escopo sms_management no nível write. Dê ao agente que envia sms e reserve sms_management para a credencial que configura o espaço de trabalho. Assim, o agente não consegue aumentar os próprios limites.

A carteira pré-paga. Os envios no modelo pré-pago debitam a carteira pré-paga da sua organização. Um envio de SMS que o saldo não consegue cobrir é recusado com 402. Algumas cobranças são liquidadas depois que um envio é aceito (email em um plano pago de Email e tarifas cobradas na entrega), e a recarga automática reabastece a carteira a partir de um cartão salvo. Por isso, leia as regras da carteira antes de tratar o saldo como um limite rígido. As operações de faturamento exigem a permissão de faturamento da organização, que uma chave de API não pode ter. Dê a um agente autônomo uma chave com escopo, e a adição de fundos continua com as pessoas responsáveis pelo orçamento.

Próximos passos

Start building with Bird in minutes.