En septembre, nous avons annoncé que l'infrastructure de communication de Bird est ouverte aux agents IA. Cet article en est la version pour les développeurs. Il présente les commandes qu'un agent exécute, ce à quoi il se connecte, comment il obtient un compte et les limites que vous pouvez lui imposer, chacun avec la page qui le documente.
La CLI
Un agent capable d'exécuter des commandes shell, comme Claude Code, le terminal de Cursor ou une tâche de CI, doit commencer par la CLI : elle consomme beaucoup moins de tokens par opération que MCP. Le serveur MCP, décrit ci-dessous, s'adresse aux hôtes qui appellent des outils sans pouvoir exécuter de shell, ainsi qu'aux événements MCP.
bird est un binaire unique conçu pour être piloté par un agent. La sortie est en JSON sur stdout, les erreurs vont sur stderr et le code de sortie indique la catégorie d'échec : un agent peut donc réagir au résultat sans analyser de texte.
curl -fsSL https://cli.bird.com/install.sh | sh
bird auth login
Trois options font l'essentiel du travail pour un agent. --example affiche un corps de requête valide, --dry-run montre la requête sans l'envoyer et --idempotency-key rend une nouvelle tentative sûre lorsqu'une réponse est perdue. CLI pour les agents décrit le contrat, et la référence CLI liste chaque commande.
Le serveur MCP hébergé
Certains hôtes appellent des outils sans pouvoir exécuter de shell, comme Claude Desktop, ChatGPT ou une application mobile. Pour eux, le serveur MCP de Bird est disponible à l'adresse https://mcp.bird.com. Indiquez cette URL à un client MCP et connectez-vous dans votre navigateur : le client détient alors un token qui agit en votre nom. L'écran de consentement affiche les autorisations demandées par le client, et vous pouvez décocher celles dont l'agent n'a pas besoin. Vous n'installez rien et ne copiez aucune clé API. Les clients pris en charge incluent Claude Code, Cursor, VS Code, Codex, Claude, ChatGPT et Muse, et Bird figure dans l'annuaire des connecteurs de Claude.
Le serveur expose l'API Bird sous forme d'outils : un agent connecté peut donc envoyer des messages sur les canaux qu'exploite Bird, configurer ces canaux et inspecter votre espace de travail. Un client limité en nombre d'outils peut se connecter à https://mcp.bird.com/dynamic, qui propose deux outils : search trouve une opération et execute l'appelle. Avec les événements MCP, un client s'abonne à ce qui se passe dans votre espace de travail, comme un SMS entrant ou un nouvel e-mail dans une boîte de réception, sans que l'agent ait à interroger le serveur.
Serveur MCP détaille les étapes pour chaque client. Une fois la CLI installée, bird mcp lance un serveur local via stdio. Il ajoute les outils d'inscription et l'envoi de fichiers locaux, mais ne fournit pas les événements MCP.
Inscription depuis un terminal
Un agent qui n'a pas de compte peut en créer un depuis un terminal, sans session de navigateur ni passage par le tableau de bord. Il doit avoir accès à une boîte e-mail, car le code de connexion arrive par e-mail :
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 crée l'organisation et son espace de travail, puis enregistre un identifiant que la CLI et le serveur MCP local utilisent ensuite. --region choisit où se trouvent le compte et ses données, us1 ou eu1. Les trois mêmes étapes fonctionnent avec curl, pour un agent qui n'a pas de CLI. Le serveur MCP hébergé ne propose pas l'inscription, car un client a besoin d'un identifiant avant de pouvoir s'y connecter.
Ce premier identifiant est large. Il détient les autorisations que le propriétaire de la nouvelle organisation peut déléguer, y compris la facturation de l'organisation, et l'inscription n'affiche aucun écran de consentement pour les restreindre. Avant qu'un agent ne s'exécute sans surveillance, créez pour lui une clé API limitée. L'inscription en libre-service détaille les deux méthodes.
Contrôler ce qu'un agent peut faire
Un agent qui envoie via Bird détient un identifiant et dépense votre solde. Les contrôles des agents documentent sur une seule page ce qui le limite. Voici les quatre contrôles à configurer avant qu'un agent ne s'exécute sans surveillance. La liste des destinations autorisées et la limite de dépense quotidienne s'appliquent aux SMS. L'e-mail et WhatsApp n'ont ni l'une ni l'autre : ce sont alors les portées de la clé et le portefeuille qui limitent un agent. La même page traite des nouvelles tentatives sûres : envoyez un en-tête Idempotency-Key, ou --idempotency-key avec la CLI, et une requête répétée n'est acceptée qu'une fois.
Clés API à portée limitée. Une clé API appartient à un seul espace de travail et porte les portées que vous lui attribuez, chacune correspondant à un domaine produit au niveau read ou write. Une clé qui envoie des SMS et rien d'autre détient sms:write, et une requête hors de ses portées renvoie 403. Une clé ne peut pas émettre d'autre clé ni accéder à la facturation.
bird auth login --scope api_keys:write --scope sms:write # an existing account
bird api-keys create --name "Support agent" --scope sms:write
La connexion doit détenir api_keys:write ainsi que les portées que la clé portera. L'identifiant issu de l'inscription depuis le terminal les détient déjà : après bird auth create-org, exécutez donc uniquement la deuxième commande. Ne vous reconnectez pas à ce moment-là : une nouvelle connexion remplace l'identifiant d'inscription. Exécutez-la dans un shell où BIRD_API_KEY n'est pas défini, car la CLI utilise cette clé en priorité sur une connexion, et une clé ne peut pas émettre de clés.
Donnez ensuite à l'agent la clé, et rien de plus large. Définissez BIRD_API_KEY dans l'environnement de l'agent, ou envoyez la clé comme jeton bearer depuis votre code. Une connexion reste enregistrée sur la machine où elle a été effectuée, et un agent sur cette machine sans BIRD_API_KEY l'utilise. Exécutez l'agent ailleurs, ou supprimez la connexion avec bird auth logout.
Destinations SMS refusées par défaut. Un espace de travail envoie des SMS vers les pays de sa liste des destinations autorisées. Cette liste est vide au départ, et Bird y ajoute le pays d'origine de votre organisation lorsqu'il est défini. Un envoi via l'SMS API vers tout autre pays est rejeté avec 422 SMSDestinationNotEnabled avant la résolution d'un expéditeur : un agent dirigé vers un pays inattendu est donc refusé. Les codes de vérification n'utilisent pas cette liste. Verify a la sienne, où tous les pays sont activés au départ, et Voice a aussi ses propres paramètres.
Limites de dépense quotidiennes. Chaque pays de destination SMS peut avoir une limite de dépense quotidienne, dans la devise de votre portefeuille. Dès que la dépense du jour vers ce pays atteint la limite, Bird refuse les nouveaux messages vers ce pays jusqu'à minuit UTC. La limite n'est pas exacte : la dépense est comptée au moment où un message est facturé, si bien que des messages déjà acceptés peuvent faire dépasser la limite au total du jour. Les codes de vérification envoyés par SMS comptent dans la limite. Cette commande active les Pays-Bas avec une limite de 25 EUR par jour, dans un espace de travail dont le portefeuille est en EUR :
bird sms destinations update --destination "NL=true;25EUR"
Pour modifier la liste des destinations autorisées ou une limite, il faut la portée sms_management au niveau write. Donnez sms à l'agent qui envoie et réservez sms_management à l'identifiant qui configure l'espace de travail : l'agent ne peut alors pas relever ses propres limites.
Le portefeuille prépayé. Les envois en paiement à l’usage sont prélevés sur le portefeuille prépayé de votre organisation. Un envoi SMS que le solde ne peut pas couvrir est refusé avec 402. Certains frais sont réglés après l’acceptation d’un envoi (les e-mails sur un forfait Email payant et les frais facturés à la livraison), et la recharge automatique réapprovisionne le portefeuille à partir d’une carte enregistrée. Lisez donc les règles du portefeuille avant de considérer le solde comme un plafond strict. Les opérations de facturation nécessitent l’autorisation de facturation de l’organisation, qu’une clé API ne peut pas détenir. Donnez une clé à portée limitée à un agent qui fonctionne sans surveillance : l’ajout de fonds reste ainsi entre les mains des personnes responsables du budget.
Pour aller plus loin
- Donner à un agent son propre numéro de téléphone et sa propre boîte de réception : une adresse
inbox.aiet un numéro dédié qui envoient et reçoivent tous les deux. Avant le premier numéro, une personne approvisionne le portefeuille et un propriétaire de l’organisation effectue la vérification d’identité. Le guide indique quelles étapes d’une commande nécessitent une personne. - Bird pour les clients européens : l’entité néerlandaise avec laquelle vous contractez, la région
eu1et l’accord de traitement des données. - Envoyer les codes SMS de Supabase Auth avec Bird : les codes de connexion par téléphone d’un projet Supabase, envoyés via Bird SMS API.
- Configurer votre agent de code : collez une seule invite, et votre agent installe CLI et les skills de Bird.