Serveur MCP

Le serveur Bird MCP expose l'Bird API sous forme d'outils Model Context Protocol. Les clients pris en charge incluent Claude Code, Cursor, VS Code, Codex, Claude, ChatGPT et Muse. Ils peuvent envoyer sur tous les canaux gérés par Bird, configurer ces canaux et inspecter votre espace de travail sans copier de commandes cURL. Vous pouvez l'exécuter de deux façons, et la première convient à la plupart des utilisateurs :

1. Hébergé (mcp.bird.com) : une URL et une connexion via le navigateur. Rien à installer, pas de CLI, pas de clé API. C'est le chemin recommandé.
2. Local en stdio (bird mcp) : des outils exécutés sur votre machine dans le bird CLI, pour les agents shell ou pour l'exécuter vous-même.

Le serveur hébergé omet ces outils réservés au stdio :

• auth_signup, auth_verify_email et auth_create_org : ces outils créent votre premier identifiant, avant que vous puissiez vous authentifier auprès du serveur hébergé.
• compliance_attachments_upload : cet outil lit un chemin de fichier local. Sur le serveur hébergé, ce chemin ferait référence au système de fichiers du serveur et pourrait envoyer le mauvais fichier.

Hébergé : se connecter à mcp.bird.com

Choisir un endpoint

Utilisez https://mcp.bird.com pour la plupart des connexions. C'est l'endpoint recommandé : la plupart des clients MCP recherchent et sélectionnent déjà les outils en interne à partir du catalogue complet. Certains clients ne recherchent pas les outils en interne, ou imposent une limite stricte sur le nombre d'outils qu'un serveur peut exposer. /dynamic est destiné à ces clients.

Les deux endpoints hébergés utilisent le Streamable HTTP et la même connexion Bird OAuth :

L'endpoint dynamique vous donne accès aux mêmes opérations hébergées via execute. L'endpoint standard et le serveur stdio local conservent leurs outils individuels ; ils ne listent pas search ni execute.

Vous n'avez pas besoin d'installer un binaire ni de créer un jeton. La connexion se fait en deux étapes, toutes deux obligatoires :

1. Ajouter le serveur : donnez au client l'URL de l'endpoint choisi.
2. S'authentifier : connectez-vous via votre navigateur pour que le client détienne un jeton qui agit en votre nom.

Les deux endpoints exigent une authentification. Un client qui ne possède que l'URL reçoit une 401 tant que vous ne vous êtes pas connecté. Certains clients lancent la connexion eux-mêmes la première fois qu'ils atteignent le serveur ; d'autres enregistrent le serveur comme "needs login" et attendent que vous cliquiez dessus. Les étapes propres à votre client précisent son comportement.

Utiliser la découverte dynamique d'outils

Si votre client rejette le serveur parce qu'il offre trop d'outils, connectez-vous à https://mcp.bird.com/dynamic et terminez la connexion OAuth. Votre client liste deux outils :

• search trouve des outils par nom ou mots-clés de description. Chaque résultat inclut son nom, sa description, son schéma d'entrée et des annotations indiquant s'il lit ou modifie des données.
• execute appelle un outil sélectionné avec ses arguments. Il peut lire des données, envoyer des messages, modifier des enregistrements ou les supprimer, selon l'outil sélectionné.

Par exemple, votre agent peut trouver l'outil workspace avec cet appel d'outil :

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

Après avoir lu le schéma d'entrée renvoyé, il appelle cet outil via execute :

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

Le résultat contient votre espace de travail actuel. Vous pouvez aussi rechercher avec des mots-clés de tâche tels que send email. La recherche renvoie cinq résultats par défaut, accepte un limit de un à 10 et accepte des requêtes jusqu'à 500 caractères. Si le résultat contient has_more: true, affinez votre requête pour trouver des résultats plus pertinents.

Les résultats de recherche n'ajoutent pas d'outils au catalogue de votre client. Les noms mentionnés dans les résultats ou les instructions de récupération passent aussi par execute. L'exécution utilise vos permissions existantes ; si une opération nécessite plus de permissions, votre client peut vous demander de les autoriser. Trouver un outil ne donne pas accès à celui-ci.

L'exécution dynamique renvoie des données pour les outils qui affichent autrement des widgets. Utilisez l'endpoint standard pour les widgets interactifs MCP Apps. Les clients voient un seul outil d'exécution, donc les paramètres d'approbation par outil s'appliquent à execute dans son ensemble ; vérifiez l'opération sélectionnée avant d'approuver un appel. Cet endpoint exécute des appels d'outils et n'exécute pas de JavaScript ni d'autre code fourni.

Connecter un client

Les exemples ci-dessous utilisent l'endpoint standard. Pour la découverte dynamique, remplacez l'URL du serveur par https://mcp.bird.com/dynamic et suivez les mêmes étapes de connexion.

Claude Code

Ajoutez le serveur :

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

claude mcp list indique maintenant bird comme ! Needs authentication. Claude Code n'ouvre pas le navigateur de lui-même, connectez-vous donc depuis une session :

1. Exécutez /mcp.
2. Sélectionnez bird et appuyez sur Entrée.
3. Choisissez Authenticate. Votre navigateur ouvre l'écran de consentement de Bird ; approuvez-le à cet endroit.

Le serveur s'affiche alors comme connecté et les outils fonctionnent. Une exécution headless (claude -p) n'a pas de panneau /mcp, authentifiez-vous donc d'abord depuis votre shell avec claude mcp login bird. Pour vous reconnecter plus tard, /mcp propose Re-authenticate ; Clear authentication supprime le jeton stocké.

L'installation du plugin bird-ai déclare ce serveur pour vous, ce qui remplace la commande claude mcp add. L'authentification reste nécessaire car un plugin peut fournir un serveur mais ne peut pas émettre de grant. Sélectionnez /mcp > bird > Authenticate après l'installation.

Cursor

Dans ~/.cursor/mcp.json :

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

Ouvrez ensuite Customize dans la barre latérale de Cursor et sélectionnez MCPs. Trouvez bird, suivez son invite de connexion, approuvez l'écran de consentement de Bird dans le navigateur, puis revenez dans Cursor.

OpenCode

Le plugin OpenCode de Bird enregistre le serveur pour vous, avec les agent skills de Bird :

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

OpenCode ajoute chaque outil MCP au contexte du modèle, donc le plugin se connecte à l'endpoint dynamique. Avec le mode code expérimental d'OpenCode activé (OPENCODE_EXPERIMENTAL_CODE_MODE=1, ou OPENCODE_EXPERIMENTAL=1), OpenCode garde les outils MCP derrière sa propre recherche, et le plugin se connecte au catalogue complet sur https://mcp.bird.com à la place.

Pour ajouter le serveur sans le plugin, placez ceci dans opencode.json, dans votre projet ou dans ~/.config/opencode/opencode.json :

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

Connectez-vous ensuite, ce qui ouvre votre navigateur sur l'écran de consentement de Bird :

opencode mcp auth bird

Redémarrez OpenCode pour charger le plugin. opencode mcp list indique bird comme connecté une fois l'approbation faite. Le plugin, comme l'entrée permission ci-dessus, fait en sorte qu'OpenCode demande confirmation avant chaque appel execute, car l'outil exécuté peut modifier votre espace de travail.

VS Code

Dans .vscode/mcp.json de votre projet :

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

Vous utilisez settings.json à la place ? Placez la même entrée bird sous mcp.servers. VS Code la déplace dans votre mcp.json utilisateur, que MCP: Open User Configuration ouvre :

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

VS Code vous demande de faire confiance au serveur la première fois qu'il démarre, puis exécute lui-même le flux OAuth : approuvez l'écran de consentement de Bird dans la fenêtre de navigateur qu'il ouvre. Si aucune fenêtre n'apparaît, démarrez ou redémarrez bird depuis la commande MCP: List Servers et approuvez-le à ce moment-là. L'autorisation obtenue figure sous Accounts > Manage Trusted MCP Servers, qui est aussi l'endroit où vous révoquez l'accès de VS Code.

ChatGPT et Codex

Installez Bird dans ChatGPT ou Codex, connectez-vous à votre espace de travail Bird, puis demandez à votre agent d'envoyer des messages, de gérer les domaines et numéros, et de vérifier la livraison.

Pour configurer Codex manuellement, ajoutez cette entrée dans ~/.codex/config.toml :

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

Puis connectez-vous depuis votre terminal, ce qui ouvre le navigateur :

codex mcp login bird

Claude

Bird figure dans le répertoire de connecteurs de Claude. Ouvrez Bird dans le répertoire et cliquez sur Connect to Claude pour lancer la connexion et approuver l'écran de consentement. Activez le connecteur par conversation depuis + > Connectors. Cela fonctionne dans Claude sur le web et dans l'application de bureau.

Pour l'ajouter manuellement, ouvrez Customize > Connectors, cliquez sur +, puis sur Add custom connector. Collez https://mcp.bird.com et cliquez sur Add. Cliquez ensuite sur Connect sur le connecteur Bird pour lancer la connexion et approuver l'écran de consentement. Sur les plans Team et Enterprise, un propriétaire ajoute le connecteur une seule fois depuis Organization settings > Connectors, et chaque membre clique sur Connect sous Customize > Connectors pour obtenir sa propre autorisation. Activez le connecteur par conversation depuis + > Connectors.

Pour configurer ChatGPT manuellement, suivez le guide de configuration d'application MCP d'OpenAI, en utilisant https://mcp.bird.com comme URL du serveur et OAuth comme authentification. Complétez la connexion navigateur de Bird, puis utilisez Bird dans votre conversation.

Muse

Muse ajoute Bird en tant que connecteur personnalisé. Dans un chat Muse, demandez-lui d'en configurer un :

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 répond avec un lien de connexion pour cette session. Ouvrez-le et approuvez l'écran de consentement de Bird dans le navigateur. Le lien ne fonctionne que pour vous et expire avec la session. S'il cesse de fonctionner, demandez à Muse d'en générer un nouveau.

Factory Droid

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

Puis exécutez /mcp dans droid et terminez la connexion via le navigateur depuis le gestionnaire de serveurs.

Antigravity

Le plugin Antigravity de Bird enregistre le serveur pour vous, avec les agent skills de Bird :

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

Pour ajouter le serveur sans le plugin, placez ceci dans ~/.gemini/config/mcp_config.json, ou dans .agents/mcp_config.json pour un seul projet. Antigravity lit l'adresse d'un serveur distant depuis serverUrl : conservez ce nom de clé :

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

Connectez-vous ensuite : ouvrez Customizations dans la barre latérale (dans l'IDE, ouvrez Agent settings avec Cmd+, sur macOS ou Ctrl+, sur Windows et Linux), puis sélectionnez Authenticate à côté de bird. Si bird n'apparaît pas dans la liste, redémarrez Antigravity. Approuvez l'écran de consentement de Bird dans le navigateur, copiez le code d'autorisation affiché, collez-le dans Antigravity et sélectionnez Submit.

Agent Plugins

Le plugin bird-ai déclare ce serveur dans un mcp.json conforme à Agent Plugins. Un hôte qui implémente la spécification lit ce fichier lors de l'installation du plugin : il n'y a donc aucune configuration de serveur à écrire. Installez le plugin et connectez-vous.

Tout autre hôte

Cherchez le paramètre qui ajoute un serveur MCP distant, HTTP ou personnalisé, souvent sous un menu Connecteurs ou Intégrations, et indiquez-lui l'URL. L'emplacement du champ varie ; utilisez l'URL de l'endpoint hébergé que vous avez choisi. Trouvez ensuite le mécanisme de connexion du client : un bouton Connect, Authorize ou Needs login à côté du serveur, une sous-commande login, ou une fenêtre de navigateur que le client ouvre lui-même. Un client qui liste les outils de Bird mais échoue à chaque appel possède l'URL mais a encore besoin d'une autorisation.

Ce qui se passe quand vous vous connectez

Votre navigateur ouvre un écran de consentement Bird. Connectez-vous, choisissez d'accorder des permissions au niveau de l'espace de travail ou de l'organisation, puis sélectionnez les permissions à déléguer. Comme les clients MCP s'enregistrent eux-mêmes, le nom du client est auto-déclaré : l'écran le signale donc comme not verified by Bird. Vérifiez qu'il s'agit bien du client que vous avez lancé avant d'approuver. Les outils apparaissent ensuite dans la liste de l'agent et le jeton se rafraîchit silencieusement : cette étape n'est nécessaire qu'une seule fois par client.

Le moyen le plus rapide de vérifier que tout fonctionne est de demander à l'agent d'appeler whoami : il renvoie l'utilisateur connecté, donc une vraie réponse signifie que l'autorisation est en place. Sur l'endpoint dynamique, appelez-le via execute avec tool: "whoami" et arguments vide.

L'autorisation est limitée à l'intersection de ce que le client a demandé, de ce que vous avez approuvé et de ce que vous détenez réellement ; les scopes org:owner et platform-admin ne sont jamais délégables. Elle apparaît dans la liste Applications connectées de votre profil, et la révoquer coupe immédiatement l'accès du client.

Fonctionnement de la négociation

Vous n'avez pas besoin de ceci pour connecter un client. C'est utile si vous déboguez un client qui ne s'authentifie pas, ou si vous en écrivez un.

Le niveau hébergé parle Streamable HTTP et ne détient aucun identifiant : il ne stocke pas de secrets et ne valide rien lui-même. Chaque requête porte votre propre jeton bearer OAuth, que API de Bird valide à chaque requête. Le serveur est sans état et le trafic régional est routé automatiquement, donc l'URL unique fonctionne depuis n'importe où.

Le flux de connexion utilise le standard MCP. Les clients diffèrent uniquement par ce qui le déclenche : le premier appel d'outil ou la sélection de Authenticate. Une fois le flux lancé, les étapes d'authentification ne nécessitent aucune configuration supplémentaire :

1. Le client envoie une requête non authentifiée et reçoit 401 avec un en-tête WWW-Authenticate pointant vers les métadonnées de ressource protégée RFC 9728 de Bird (/.well-known/oauth-protected-resource).
2. À partir de là, il découvre le serveur d'autorisation, puis s'enregistre dynamiquement (RFC 7591). L'enregistrement dynamique élimine le besoin d'un identifiant client pré-partagé ou d'une configuration manuelle.
3. Votre navigateur ouvre l'écran de consentement de Bird.
4. Le client échange le résultat contre un jeton d'accès (PKCE ; renouvelé automatiquement) et les outils Bird apparaissent.

Local : exécuter via stdio avec le CLI

Exécutez le serveur MCP local dans le bird CLI pour les agents capables d'utiliser un shell ou pour accéder aux fichiers de votre machine. Installez le CLI, exécutez bird auth login une fois, puis pointez votre client vers la commande bird mcp.

Vous n'exécutez pas bird mcp vous-même : votre client le lance et communique avec lui sur stdin/stdout. Chaque client a besoin des deux mêmes informations : la commande (bird) et l'argument (mcp). Ce mode ne nécessite pas de connexion par client, car bird auth login détient déjà l'autorisation.

Cursor

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

VS Code

Dans .vscode/mcp.json de votre projet :

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

Claude Code

claude mcp add bird -- bird mcp

Authentification du serveur local

Le serveur local agit en tant que vous et réutilise la session stockée du CLI. bird auth login ouvre un flux OAuth dans le navigateur où vous accordez un sous-ensemble de vos permissions d'espace de travail. Le jeton émis est plafonné aux permissions de l'accès hébergé. Les portées org:owner et platform-admin ne sont pas délégables. bird mcp lit et renouvelle la session stockée depuis le fichier d'identifiants CLI, dont le mode est 0600. Comme pour le niveau hébergé, la configuration de votre client ne contient ni BIRD_API_KEY ni autre secret. Si la session est absente, bird mcp refuse de démarrer et vous demande d'exécuter bird auth login.

Vous n'exposez aucun port d'écoute : le serveur tourne sur votre machine, dans le bac à sable du client, exactement le temps dont le client a besoin. L'hôte API suit automatiquement la région de votre session ; --base-url (ou BIRD_API_URL) la remplace pour tester dans un environnement hors production.

Ce que les outils couvrent

Le jeu d'outils couvre tous les canaux sur lesquels Bird opère, ainsi que les tâches de compte et de configuration associées. Il est sélectionné plutôt qu'exposant toute la surface API : chaque outil est limité à une tâche qu'un agent exécute réellement, et les opérations destructives sont annotées pour que les hôtes puissent demander confirmation avant de les lancer.

L'e-mail possède le plus d'outils, car c'est le canal qui a le plus de surface à configurer. Les autres canaux suivent la même structure envoi-et-lecture.

Messagerie

• Envoyer et inspecter des e-mails : email_send, email_send_batch, email_list et email_get, qui renvoie le message avec son statut de livraison agrégé. Les statuts de livraison par destinataire et le journal d'événements sont des appels d'outils distincts.
• Envoyer et inspecter des SMS : sms_send, sms_send_batch, sms_get, sms_list et sms_list_events, sur le même modèle que l'e-mail. sms_templates_list et sms_templates_get consultent le catalogue de modèles.
• Envoyer et inspecter des WhatsApp : whatsapp_send, whatsapp_get, whatsapp_list, whatsapp_list_events et whatsapp_media. Les modèles disposent d'une surface de création complète sous whatsapp_templates_*, incluant le contenu par version et par langue.
• Inspecter les segments d'appel vocal : voice_legs_get et voice_legs_list lisent les segments d'appel, avec des statistiques par pays et par code de réponse sous voice_stats_*. voice_session_credentials_create crée l'identifiant d'espace de travail qu'un client SIP ou softphone utilise pour s'authentifier.
• Vérifier un destinataire : verify_verifications_create envoie un code de vérification à usage unique, verify_verifications_check valide ce que le destinataire a soumis, et verify_verifications_next_channel bascule sur un autre canal.
• Créer un appel vocal (aperçu) : voice_calls_create prépare un appel sortant à partir de la publication active d'une séquence activée et non archivée. Une personne examine et exécute la requête dans le navigateur ; la préparation ne passe pas l'appel. Consultez Créer un appel vocal pour les permissions et les instructions de nouvelle tentative. Le serveur local bird mcp nécessite une version de CLI qui inclut cet outil.

Préparer un canal à l'envoi

• Configurer les domaines d'envoi : email_domains_create ajoute un domaine d'envoi et renvoie les enregistrements DNS à publier ; email_domains_verify les revérifie ; plus email_domains_list et email_domains_get.
• Revendiquer et enregistrer des expéditeurs SMS : sms_senders_create revendique un expéditeur, sms_senders_requirements indique ce qu'un pays exige de lui, et sms_senders_registrations_create l'enregistre. Le trafic A2P aux États-Unis passe par les outils de marque, de campagne et de soumission sms_10dlc_*.
• Provisionner des numéros : numbers_available_list recherche, numbers_orders_create achète, numbers_cancel restitue à la fin de la période payée (ou immédiatement si le numéro n'a pas d'abonnement), et numbers_release restitue maintenant. whatsapp_numbers_precheck indique si WhatsApp acceptera un numéro avant que vous ne le commandiez.
• Vérifier que le compte peut envoyer : les outils trust_* indiquent les exigences de l'organisation qui conditionnent l'achat d'un numéro ou l'enregistrement d'un expéditeur.

Délivrabilité des e-mails

• Créer des modèles d'e-mail : email_templates_create, email_templates_list, email_templates_get, email_templates_update, email_templates_duplicate et email_templates_preview (afficher un aperçu du brouillon avec des valeurs d'exemple sans envoyer). Les versions se trouvent sous email_templates_versions_*, où email_templates_versions_submit fige un brouillon et en fait la version servie par les envois, et email_templates_versions_languages_* modifie le contenu par langue d'un brouillon. Rien de ce qu'un agent rédige n'atteint un destinataire tant qu'il ne le soumet pas.
• Gérer les suppressions : email_suppressions_list, email_suppressions_check (cette adresse est-elle sûre pour l'envoi ?), email_suppressions_add et email_suppressions_remove (annotée comme destructrice, car retirer une suppression sans raison nuit à la réputation de l'expéditeur).
• Gérer les IP dédiées et les pools : email_dedicated_ips_create, email_dedicated_ips_list, email_dedicated_ips_get, email_dedicated_ips_assign (déplacer une IP dans un pool) et email_dedicated_ips_delete ; plus email_ip_pools_create, email_ip_pools_list, email_ip_pools_get, email_ip_pools_update et email_ip_pools_delete pour les pools par lesquels vous acheminez vos envois.

Audience et configuration

• Gérer les contacts et les audiences : contacts_* et contact_properties_* pour les personnes à qui vous envoyez, audiences_* pour les listes auxquelles vous envoyez, et preferences_* pour les accords de consentement et les désinscriptions.
• Provisionner Realtime : realtime_apps_* et realtime_apps_keys_* créent les applications et les clés avec lesquelles les clients Realtime se connectent.
• Rechercher quelqu'un : lookup_phone_number et lookup_email indiquent ce que Bird sait d'une adresse avant que vous ne lui envoyiez un message.
• Inspecter la configuration : webhooks_list, workspace_get et whoami (l'utilisateur connecté : id, e-mail, nom).

Votre client affiche la liste des outils disponibles avec leurs noms, descriptions et schémas d'entrée. Considérez cette liste comme l'inventaire de référence. Une bonne première tâche à tester de bout en bout :

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

MCP ou le CLI ?

Même surface, même modèle d'authentification, appelants différents. Pour les agents capables d'exécuter un shell (Claude Code, le terminal de Cursor, la CI), le CLI est plus léger : sortie JSON, codes de sortie sémantiques et bien moins de tokens par opération. MCP s'adresse aux hôtes qui appellent des outils au lieu d'exécuter des shells, et l'endpoint hébergé atteint ceux qui ne peuvent pas du tout exécuter un binaire (Claude Desktop, ChatGPT, mobile). Vous n'avez pas à choisir à l'avance : l'URL hébergée ne nécessite aucune installation, et le bird mcp local est déjà là une fois le CLI installé.

Étapes suivantes

• MCP Events : abonnez votre client aux événements Bird, comme un nouveau message dans une boîte de réception, et recevez chacun sous forme de webhook signé.
• Interroger les statistiques e-mail avec l'IA : posez des questions sur la livraison, l'engagement et la latence en langage naturel.
• Onboarding IA : la version de démarrage rapide de cette page, plus le corpus de documentation lisible par les machines.
• Agent skills : le plugin bird-ai du marketplace, les skills plus ce serveur MCP, installés en une seule étape.
• CLI pour les agents : pilotez Bird depuis des agents shell sans MCP : sortie JSON, codes de sortie sémantiques, connexion OAuth.
• Authentification : clés API, régions et autorisation des requêtes.