Cosa può fare un agente AI su Bird: CLI, MCP, registrazione da terminale e controlli sulla spesa

A settembre abbiamo annunciato che l'infrastruttura di comunicazione di Bird è aperta agli agenti AI. Questo articolo è la versione per sviluppatori di quell'annuncio. Indica i comandi che un agente esegue, a cosa si collega, come ottiene un account e i limiti che puoi imporgli, ciascuno con la pagina che lo documenta.

La CLI

Un agente in grado di eseguire comandi shell, come Claude Code, il terminale di Cursor o un job di CI, dovrebbe partire dalla CLI: per ogni operazione usa molti meno token di MCP. Il server MCP, descritto più avanti, serve agli host che chiamano strumenti ma non possono eseguire una shell, e per gli Events di MCP.

bird è un singolo binario pensato per essere pilotato da un agente. L'output è JSON su stdout, gli errori vanno su stderr e il codice di uscita indica la categoria dell'errore, così un agente può decidere in base al risultato senza analizzare testo.

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

Tre flag svolgono gran parte del lavoro per un agente. --example stampa un corpo di richiesta valido, --dry-run mostra la richiesta senza inviarla e --idempotency-key rende sicuro un nuovo tentativo quando una risposta va persa. CLI per agenti descrive il contratto e il riferimento di CLI elenca ogni comando.

Il server MCP ospitato

Alcuni host chiamano strumenti ma non possono eseguire una shell, come Claude Desktop, ChatGPT o un'app mobile. Per questi, il server MCP di Bird è disponibile su https://mcp.bird.com. Fornisci quell'URL a un client MCP e accedi dal browser: il client riceve un token che agisce per tuo conto. La schermata di consenso mostra le autorizzazioni richieste dal client e puoi deselezionare quelle che non servono all'agente. Non installi nulla e non copi alcuna chiave API. Tra i client supportati ci sono Claude Code, Cursor, VS Code, Codex, Claude, ChatGPT e Muse, e Bird è presente nella directory dei connettori di Claude.

Il server espone l'API di Bird come strumenti, così un agente connesso può inviare sui canali gestiti da Bird, configurarli e ispezionare il tuo spazio di lavoro. Un client con un limite al numero di strumenti può collegarsi a https://mcp.bird.com/dynamic, che elenca due strumenti: search trova un'operazione e execute la chiama. Con gli Events di MCP, un client si iscrive a ciò che accade nel tuo spazio di lavoro, come un SMS in arrivo o una nuova email in una casella, così l'agente non deve interrogare periodicamente il servizio.

Server MCP riporta i passaggi per ogni client. Una volta installata la CLI, bird mcp avvia un server locale su stdio. Aggiunge gli strumenti di registrazione e il caricamento da file locali, ma non fornisce gli Events di MCP.

Registrazione da terminale

Un agente senza account può crearne uno da terminale, senza sessione del browser e senza passare dalla dashboard. Deve avere accesso a una casella email, perché il codice di accesso arriva via 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 crea l'organizzazione e il suo spazio di lavoro, e salva una credenziale che da quel momento usano la CLI e il server MCP locale. --region sceglie dove risiedono l'account e i suoi dati, us1 o eu1. Gli stessi tre passaggi funzionano con curl, per un agente che non ha la CLI. Il server MCP ospitato non offre la registrazione, perché un client ha bisogno di una credenziale prima di potersi connettere.

Questa prima credenziale è ampia. Contiene i permessi che il proprietario della nuova organizzazione può delegare, fatturazione dell'organizzazione inclusa, e la registrazione non mostra alcuna schermata di consenso per restringerla. Prima che un agente lavori senza supervisione, crea per lui una chiave API con ambiti limitati. Registrazione self-service descrive entrambi i percorsi.

Controlli su ciò che un agente può fare

Un agente che invia tramite Bird possiede una credenziale e spende il tuo saldo. Controlli per gli agenti documenta in una sola pagina che cosa lo limita. Questi sono i quattro controlli da impostare prima che un agente lavori senza supervisione. La lista di destinazioni consentite e il limite di spesa giornaliero si applicano a SMS. Email e WhatsApp non hanno né l'una né l'altro, quindi lì un agente è limitato dagli ambiti della chiave e dal wallet. La stessa pagina tratta i nuovi tentativi sicuri: invia un'intestazione Idempotency-Key, oppure --idempotency-key nella CLI, e una richiesta ripetuta viene accettata una sola volta.

Chiavi API con ambiti limitati. Una chiave API appartiene a un solo spazio di lavoro e porta gli ambiti che le assegni, ciascuno un'area di prodotto a livello read o write. Una chiave che invia SMS e nient'altro ha sms:write, e una richiesta fuori dai suoi ambiti restituisce 403. Una chiave non può emettere un'altra chiave e non può accedere alla fatturazione.

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

L'accesso deve avere api_keys:write e gli ambiti che la chiave porterà. La credenziale della registrazione da terminale li ha già, quindi dopo bird auth create-org esegui solo il secondo comando. Non accedere di nuovo lì: un nuovo accesso sostituisce la credenziale della registrazione. Eseguilo in una shell in cui BIRD_API_KEY non è impostata, perché la CLI usa quella chiave al posto di un accesso, e una chiave non può emettere chiavi.

Poi dai all'agente la chiave e nulla di più ampio. Imposta BIRD_API_KEY nell'ambiente dell'agente, oppure invia la chiave come bearer token dal tuo codice. Un accesso resta salvato sulla macchina in cui è stato eseguito, e un agente su quella macchina senza BIRD_API_KEY lo usa. Esegui l'agente altrove, oppure rimuovi l'accesso con bird auth logout.

Destinazioni SMS negate per impostazione predefinita. Uno spazio di lavoro invia SMS ai paesi presenti nella sua lista di destinazioni consentite. La lista parte vuota, e Bird aggiunge il paese di origine della tua organizzazione quando è impostato. Un invio tramite SMS API verso qualsiasi altro paese viene rifiutato con 422 SMSDestinationNotEnabled prima che venga risolto un mittente, quindi un agente indirizzato verso un paese inatteso viene bloccato. I codici di verifica non usano questa lista. Verify ha la sua, in cui ogni paese parte abilitato, e anche Voice ha impostazioni proprie.

Limiti di spesa giornalieri. Ogni paese di destinazione SMS può avere un limite di spesa giornaliero, nella valuta del tuo wallet. Quando la spesa del giorno verso quel paese raggiunge il limite, Bird rifiuta nuovi messaggi verso di esso fino alla mezzanotte UTC. Il limite non è esatto: la spesa viene conteggiata quando un messaggio viene addebitato, quindi i messaggi già accettati possono portare il totale del giorno oltre il limite. I codici di verifica inviati da SMS contano ai fini del limite. Questo comando abilita i Paesi Bassi con un limite di 25 EUR al giorno, in uno spazio di lavoro il cui wallet è in EUR:

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

Per modificare la lista consentita o un limite serve l'ambito sms_management a livello write. Dai all'agente che invia sms, riserva sms_management alla credenziale che configura lo spazio di lavoro, e l'agente non potrà alzare i propri limiti.

Il portafoglio prepagato. Gli invii a consumo attingono al portafoglio prepagato della tua organizzazione. Un invio SMS che il saldo non riesce a coprire viene rifiutato con 402. Alcuni addebiti vengono regolati dopo che un invio è stato accettato (l'email con un piano Email a pagamento e le tariffe addebitate alla consegna), e la ricarica automatica rifornisce il portafoglio da una carta salvata. Per questo, leggi le regole del portafoglio prima di considerare il saldo un limite rigido. Le operazioni di fatturazione richiedono il permesso di fatturazione dell'organizzazione, che una chiave API non può avere. Se dai a un agente non supervisionato una chiave con ambiti limitati, l'aggiunta di fondi resta a chi gestisce il budget.

Dove andare dopo

Start building with Bird in minutes.