MCP-server

De Bird MCP-server stelt de Bird API beschikbaar als Model Context Protocol-tools. Ondersteunde clients zijn onder andere Claude Code, Cursor, VS Code, Codex, Claude, ChatGPT en Muse. Ze kunnen berichten versturen op elk kanaal dat Bird ondersteunt, die kanalen configureren en je werkruimte inspecteren zonder cURL-commando's over te nemen. Je kunt het op twee manieren draaien, en de meeste mensen willen de eerste:

1. Gehost (mcp.bird.com): een URL en een browseraanmelding. Niets te installeren, geen CLI, geen API-key. Dit is het aanbevolen pad.
2. Lokaal over stdio (bird mcp): tools die op je machine draaien in de bird CLI, voor shell-agents of om het zelf te draaien.

De gehoste server laat deze stdio-only tools weg:

• auth_signup, auth_verify_email en auth_create_org: deze tools maken je eerste credential aan, voordat je je kunt authenticeren bij de gehoste server.
• compliance_attachments_upload: deze tool leest een lokaal bestandspad. Op de gehoste server zou dat pad verwijzen naar het bestandssysteem van de server en zou het verkeerde bestand geüpload kunnen worden.

Gehost: verbinden met mcp.bird.com

Kies een endpoint

Gebruik https://mcp.bird.com voor de meeste verbindingen. Het is het aanbevolen endpoint: de meeste MCP-clients zoeken en selecteren tools intern al uit de volledige catalogus. Sommige clients zoeken niet intern naar tools, of hanteren een harde limiet op het aantal tools dat een server mag aanbieden. /dynamic is voor die clients.

Beide gehoste endpoints gebruiken Streamable HTTP en dezelfde Bird OAuth-aanmelding:

Het dynamische endpoint geeft je toegang tot dezelfde gehoste operaties via execute. Het standaardendpoint en de lokale stdio-server behouden hun individuele tools; ze vermelden search of execute niet.

Je hoeft geen binary te installeren of een token aan te maken. Verbinden kost twee stappen, en beide zijn vereist:

1. Voeg de server toe: geef de client de endpoint-URL die je gekozen hebt.
2. Authenticeer: meld je aan via je browser zodat de client een token heeft dat als jou handelt.

Beide endpoints vereisen authenticatie. Een client die alleen de URL heeft, ontvangt een 401 totdat je je aanmeldt. Sommige clients starten de aanmelding zelf de eerste keer dat ze de server bereiken; andere parkeren de server als "needs login" en wachten tot je erop klikt. De stappen van je client bepalen het gedrag.

Gebruik dynamische tooldetectie

Als je client de server weigert omdat deze te veel tools aanbiedt, verbind dan met https://mcp.bird.com/dynamic en doorloop de OAuth-aanmelding. Je client toont twee tools:

• search vindt tools op naam of beschrijvingstrefwoorden. Elke match bevat de naam, beschrijving, het inputschema en annotaties die aangeven of de tool gegevens leest of wijzigt.
• execute roept één geselecteerde tool aan met de bijbehorende argumenten. Het kan gegevens lezen, berichten versturen, records wijzigen of verwijderen, afhankelijk van de geselecteerde tool.

Je agent kan bijvoorbeeld de werkruimtetool vinden met deze toolaanroep:

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

Na het lezen van het geretourneerde inputschema roept hij die tool aan via execute:

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

Het resultaat bevat je huidige werkruimte. Je kunt ook zoeken met taaktrefwoorden zoals send email. Zoeken geeft standaard vijf matches, accepteert een limit van één tot en met 10 en accepteert zoekopdrachten tot 500 tekens. Als het resultaat has_more: true bevat, vernauw dan je zoekopdracht om relevantere matches te vinden.

Zoekresultaten voegen geen tools toe aan de catalogus van je client. Namen die in resultaten of herstelinstructies worden genoemd, gaan ook via execute. Uitvoering gebruikt je bestaande rechten; als een operatie meer rechten vereist, kan je client je vragen om ze te autoriseren. Het vinden van een tool verleent geen toegang ertoe.

Dynamische uitvoering retourneert data voor tools die anders widgets tonen. Gebruik het standaardendpoint voor interactieve MCP Apps-widgets. Clients zien één uitvoeringstool, dus goedkeuringsinstellingen per tool gelden voor execute als geheel; controleer de geselecteerde operatie voordat je een aanroep goedkeurt. Dit endpoint voert toolaanroepen uit en draait geen JavaScript of andere aangeleverde code.

Een client verbinden

De onderstaande voorbeelden gebruiken het standaardendpoint. Voor dynamische detectie vervang je https://mcp.bird.com/dynamic als server-URL en volg je dezelfde aanmeldstappen.

Claude Code

Voeg de server toe:

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

claude mcp list meldt nu bird als ! Needs authentication. Claude Code opent de browser niet zelf, dus meld je aan vanuit een sessie:

1. Voer /mcp uit.
2. Selecteer bird en druk op Enter.
3. Kies Authenticate. Je browser opent het toestemmingsscherm van Bird; keur het daar goed.

De server verschijnt dan als verbonden en de tools werken. Een headless run (claude -p) heeft geen /mcp-paneel, dus authenticeer eerst vanuit je shell met claude mcp login bird. Om later opnieuw aan te melden biedt /mcp Re-authenticate aan; Clear authentication verwijdert het opgeslagen token.

De bird-ai plugin installeren declareert deze server voor je, wat het claude mcp add-commando vervangt. Authenticatie is nog steeds vereist omdat een plugin een server kan leveren maar geen grant kan uitgeven. Selecteer /mcp > bird > Authenticate na het installeren.

Cursor

In ~/.cursor/mcp.json:

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

Open vervolgens Customize in de Cursor-zijbalk en selecteer MCPs. Zoek bird, volg de aanmeldprompt, keur het toestemmingsscherm van Bird goed in de browser en keer terug naar Cursor.

OpenCode

De OpenCode-plugin van Bird registreert de server voor je, samen met de agent skills van Bird:

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

OpenCode voegt elke MCP-tool toe aan de context van het model, dus de plugin verbindt met het dynamische endpoint. Als de experimentele code-modus van OpenCode aanstaat (OPENCODE_EXPERIMENTAL_CODE_MODE=1, of OPENCODE_EXPERIMENTAL=1), houdt OpenCode MCP-tools achter zijn eigen zoekfunctie, en verbindt de plugin in plaats daarvan met de volledige catalogus op https://mcp.bird.com.

Om de server zonder de plugin toe te voegen, zet je dit in opencode.json, in je project of op ~/.config/opencode/opencode.json:

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

Meld je vervolgens aan, wat je browser opent voor het toestemmingsscherm van Bird:

opencode mcp auth bird

Herstart OpenCode om de plugin te laden. opencode mcp list meldt bird als verbonden zodra je goedkeurt. De plugin laat OpenCode, net als de permission-vermelding hierboven, vóór elke execute-aanroep om bevestiging vragen, omdat de tool die wordt uitgevoerd je werkruimte kan wijzigen.

VS Code

In .vscode/mcp.json in je project:

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

Gebruik je settings.json? Zet dezelfde bird-vermelding onder mcp.servers. VS Code verplaatst die naar je gebruikers-mcp.json, die je opent met MCP: Open User Configuration:

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

VS Code vraagt je de server te vertrouwen als hij voor het eerst start en voert vervolgens zelf de OAuth-flow uit: keur het toestemmingsscherm van Bird goed in het browservenster dat wordt geopend. Als er geen venster verschijnt, start of herstart je bird via de opdracht MCP: List Servers en keur het dan goed. De resulterende machtiging staat onder Accounts > Manage Trusted MCP Servers, waar je ook de toegang van VS Code intrekt.

ChatGPT en Codex

Installeer Bird in ChatGPT of Codex, meld je aan bij je Bird-werkruimte en vraag je agent om berichten te versturen, domeinen en nummers te beheren en bezorging te controleren.

Voeg voor handmatige Codex-configuratie in plaats daarvan dit item toe in ~/.codex/config.toml:

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

Meld je vervolgens aan vanuit je shell, waardoor de browser wordt geopend:

codex mcp login bird

Claude

Bird staat in de connectordirectory van Claude. Open Bird in de directory en klik op Connect to Claude om de aanmelding te starten en het toestemmingsscherm goed te keuren. Zet de connector per gesprek aan via + > Connectors. Dit werkt in Claude op het web en in de desktopapp.

Om de connector handmatig toe te voegen, open je Customize > Connectors, klik je op + en vervolgens op Add custom connector. Plak https://mcp.bird.com en klik op Add. Klik daarna op Connect bij de Bird-connector om de aanmelding te starten en het toestemmingsscherm goed te keuren. Bij Team- en Enterprise-abonnementen voegt een eigenaar de connector eenmalig toe via Organization settings > Connectors, en elk lid klikt nog steeds op Connect onder Customize > Connectors voor een eigen machtiging. Zet de connector per gesprek aan via + > Connectors.

Volg voor handmatige ChatGPT-configuratie in plaats daarvan de MCP-app-installatiehandleiding van OpenAI, met https://mcp.bird.com als server-URL en OAuth als authenticatie. Doorloop de browseraanmelding van Bird en gebruik vervolgens Bird in je chat.

Muse

Muse voegt Bird toe als aangepaste connector. Vraag in een Muse-chat om er een in te stellen:

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 antwoordt met een verbindingslink voor deze sessie. Open de link en keur het toestemmingsscherm van Bird goed in de browser. De link werkt alleen voor jou en vervalt met de sessie. Als de link niet meer werkt, vraag Muse dan om een nieuwe.

Factory Droid

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

Voer vervolgens /mcp uit in droid en voltooi de browseraanmelding vanuit de serverbeheerder.

Antigravity

De Antigravity-plugin van Bird registreert de server voor je, samen met de agent skills van Bird:

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

Om de server zonder de plugin toe te voegen, zet je dit in ~/.gemini/config/mcp_config.json, of in .agents/mcp_config.json voor één project. Antigravity leest het adres van een remote server uit serverUrl, dus houd die sleutelnaam aan:

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

Meld je vervolgens aan: open Customizations in de zijbalk (open in de IDE Agent settings met Cmd+, op macOS of Ctrl+, op Windows en Linux) en selecteer Authenticate naast bird. Als bird niet in de lijst staat, herstart Antigravity. Keur het toestemmingsscherm van Bird goed in de browser, kopieer de autorisatiecode die wordt getoond, plak deze in Antigravity en selecteer Submit.

Agent Plugins

De bird-ai plugin declareert deze server in een mcp.json die Agent Plugins volgt. Een host die de specificatie implementeert, leest dat bestand wanneer de plugin wordt geïnstalleerd, dus je hoeft geen serverconfiguratie te schrijven: installeer de plugin en meld je aan.

Elke andere host

Zoek de instelling waarmee je een remote, HTTP of custom MCP-server toevoegt, vaak onder een menu Connectors of Integrations, en geef de URL op. De locatie van het veld verschilt; gebruik de gehoste endpoint-URL van je keuze. Zoek vervolgens de aanmeldoptie van die client: een Connect-, Authorize- of Needs login-knop naast de server, een login-subcommando, of een browservenster dat de client zelf opent. Een client die de tools van Bird toont maar elke aanroep laat mislukken, heeft de URL maar mist nog een grant.

Wat er gebeurt wanneer je je aanmeldt

Je browser opent een toestemmingsscherm van Bird. Meld je aan, kies of je werkruimte- of organisatierechten wilt verlenen en selecteer welke rechten je wilt delegeren. Omdat MCP-clients zichzelf registreren, is de naam van de client zelfopgegeven, dus het scherm markeert deze als not verified by Bird. Controleer of het de client is die je daadwerkelijk hebt gestart voordat je goedkeurt. Daarna verschijnen de tools in de lijst van de agent en wordt het token stilzwijgend vernieuwd, dus dit is een eenmalige stap per client.

De snelste manier om te controleren of het werkt, is de agent whoami te laten aanroepen: het geeft de aangemelde gebruiker terug, dus een echt antwoord betekent dat de grant actief is. Op het dynamische endpoint roep je het aan via execute met tool: "whoami" en lege arguments.

De grant is beperkt tot de doorsnede van wat de client heeft aangevraagd, wat jij hebt goedgekeurd en wat je daadwerkelijk hebt; org:owner- en platform-admin-scopes zijn nooit delegeerbaar. De grant verschijnt in de lijst Connected apps van je profiel, en intrekken daar verbreekt de verbinding met de client onmiddellijk.

Hoe de handshake werkt

Dit heb je niet nodig om een client te verbinden. Het is relevant als je een client debugt die niet wil authenticeren, of als je er zelf een schrijft.

De hosted tier spreekt Streamable HTTP en heeft geen credentials: hij slaat geen secrets op en valideert zelf niets. Elk verzoek draagt je eigen OAuth bearer-token mee, dat Bird's API per verzoek valideert. De server is stateless en regionaal verkeer wordt automatisch gerouteerd, dus de ene URL werkt overal.

De inlogflow gebruikt standaard MCP. Clients verschillen alleen in wat hem triggert: de eerste toolaanroep of het selecteren van Authenticate. Nadat de flow is gestart, vereisen de authenticatiestappen geen extra configuratie:

1. De client doet een niet-geauthenticeerd verzoek en krijgt 401 terug met een WWW-Authenticate-header die verwijst naar de RFC 9728 protected-resource metadata van Bird (/.well-known/oauth-protected-resource).
2. Van daaruit ontdekt hij de autorisatieserver en registreert zichzelf dynamisch (RFC 7591). Dynamische registratie maakt een vooraf gedeeld client-ID of handmatige configuratie overbodig.
3. Je browser opent het toestemmingsscherm van Bird.
4. De client wisselt het resultaat in voor een access-token (PKCE; wordt automatisch vernieuwd) en de Bird-tools verschijnen.

Lokaal: draai het over stdio met de CLI

Draai de lokale MCP-server in de bird CLI voor shell-capable agents of toegang tot bestanden op je machine. Installeer de CLI, voer eenmalig bird auth login uit en wijs je client naar het bird mcp-commando.

Je draait bird mcp niet zelf: je client start het op en communiceert ermee via stdin/stdout. Elke client heeft dezelfde twee gegevens nodig: het commando (bird) en het argument (mcp). Dit pad vereist geen inlog per client, omdat bird auth login de grant al heeft.

Cursor

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

VS Code

In .vscode/mcp.json in je project:

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

Claude Code

claude mcp add bird -- bird mcp

Hoe de lokale server zich authenticeert

De lokale server handelt als jij en hergebruikt de opgeslagen login van de CLI. bird auth login opent een OAuth-flow in de browser waarin je een deel van je werkruimtepermissies toekent. Het uitgegeven token heeft dezelfde permissiebeperkingen als de hosted grant. org:owner- en platform-admin-scopes zijn niet beschikbaar. bird mcp leest en vernieuwt de opgeslagen login uit het CLI-credentialsbestand, waarvan de mode 0600 is. Net als bij de hosted tier bevat je clientconfiguratie geen BIRD_API_KEY of ander geheim. Als de login ontbreekt, weigert bird mcp te starten en vraagt je om bird auth login uit te voeren.

Je stelt geen listener open: de server draait op je machine, in de sandbox van de client, precies zolang als de client hem nodig heeft. De API-host volgt automatisch de regio van je login; --base-url (of BIRD_API_URL) overschrijft dit om te testen tegen een niet-productieomgeving.

Wat de tools dekken

De toolset beslaat elk kanaal dat Bird aanbiedt, plus de account- en configuratietaken eromheen. Het is een samengestelde selectie in plaats van het volledige API-oppervlak: elke tool is afgebakend tot een taak die een agent daadwerkelijk uitvoert, en destructieve bewerkingen zijn geannoteerd zodat hosts om bevestiging kunnen vragen voordat ze worden uitgevoerd.

E-mail heeft de meeste tools, omdat het het grootste configuratieoppervlak heeft. De andere kanalen hebben dezelfde verzend-en-lees-opzet.

Berichten

• E-mail verzenden en inspecteren: email_send, email_send_batch, email_list en email_get, die het bericht met de geaggregeerde afleveringsstatus teruggeeft. Afleveringsstatussen per ontvanger en het eventlog zijn afzonderlijke toolaanroepen.
• SMS verzenden en inspecteren: sms_send, sms_send_batch, sms_get, sms_list en sms_list_events, naar het e-mailmodel. sms_templates_list en sms_templates_get lezen de templatecatalogus.
• WhatsApp verzenden en inspecteren: whatsapp_send, whatsapp_get, whatsapp_list, whatsapp_list_events en whatsapp_media. Templates vormen een volledig bewerkingsoppervlak onder whatsapp_templates_*, inclusief content per versie en per taal.
• Gesprekspoten van spraakoproepen inspecteren: voice_legs_get en voice_legs_list lezen gesprekspoten, met statistieken per land en per antwoordcode onder voice_stats_*. voice_session_credentials_create maakt de werkruimte-credential aan die een SIP- of softphoneclient gebruikt om te authenticeren.
• Een ontvanger verifiëren: verify_verifications_create stuurt een eenmalige verificatiecode, verify_verifications_check valideert wat de ontvanger heeft ingediend, en verify_verifications_next_channel valt terug op een ander kanaal.
• Een spraakoproep aanmaken (preview): voice_calls_create bereidt een uitgaande oproep voor met de actieve publicatie van een ingeschakelde, niet-gearchiveerde reeks. Iemand beoordeelt en voert het verzoek uit in de browser; het voorbereiden plaatst de oproep niet. Zie Een spraakoproep aanmaken voor machtigingen en instructies om opnieuw te proberen. De lokale bird mcp-server vereist een CLI-versie die deze tool bevat.

Een kanaal klaarstomen om te verzenden

• Verzenddomeinen instellen: email_domains_create voegt een verzenddomein toe en geeft de DNS-records terug die je moet publiceren; email_domains_verify controleert ze opnieuw; plus email_domains_list en email_domains_get.
• SMS-afzenders claimen en registreren: sms_senders_create claimt een afzender, sms_senders_requirements rapporteert wat een land ervan vereist, en sms_senders_registrations_create registreert de afzender. Amerikaans A2P-verkeer loopt via de sms_10dlc_*-tools voor merk, campagne en indiening.
• Nummers inrichten: numbers_available_list zoekt, numbers_orders_create koopt, numbers_cancel geeft terug aan het einde van de betaalperiode (of direct als het nummer geen abonnement heeft), en numbers_release geeft direct terug. whatsapp_numbers_precheck meldt of WhatsApp een nummer accepteert voordat je het bestelt.
• Controleren of het account überhaupt kan verzenden: de trust_*-tools rapporteren de organisatievereisten die het kopen van een nummer of het registreren van een afzender blokkeren.

E-mailafleverbaarheid

• E-mailtemplates opstellen: email_templates_create, email_templates_list, email_templates_get, email_templates_update, email_templates_duplicate en email_templates_preview (een concept renderen met voorbeeldwaarden zonder te verzenden). Versies staan onder email_templates_versions_*, waar email_templates_versions_submit een concept bevriest en het de versie maakt die verzendingen gebruiken, en email_templates_versions_languages_* de taalspecifieke inhoud van een concept bewerkt. Niets wat een agent schrijft bereikt een ontvanger totdat het wordt ingediend.
• Suppressies beheren: email_suppressions_list, email_suppressions_check (is het veilig om naar dit adres te sturen?), email_suppressions_add en email_suppressions_remove (gemarkeerd als destructief, omdat het verwijderen van een suppressie zonder reden de afzenderreputatie schaadt).
• Dedicated IP's en pools beheren: email_dedicated_ips_create, email_dedicated_ips_list, email_dedicated_ips_get, email_dedicated_ips_assign (verplaats er een naar een pool) en email_dedicated_ips_delete; plus email_ip_pools_create, email_ip_pools_list, email_ip_pools_get, email_ip_pools_update en email_ip_pools_delete voor de pools waar je verzendingen doorheen routeert.

Doelgroep en configuratie

• Contacten en doelgroepen beheren: contacts_* en contact_properties_* voor de mensen naar wie je verstuurt, audiences_* voor de lijsten waar je naar verstuurt, en preferences_* voor toestemmingen en opt-outs.
• Realtime inrichten: realtime_apps_* en realtime_apps_keys_* maken de apps en sleutels aan waarmee de Realtime-clients verbinding maken.
• Iemand opzoeken: lookup_phone_number en lookup_email geven aan wat Bird over een adres weet voordat je ernaar verstuurt.
• Configuratie inspecteren: webhooks_list, workspace_get en whoami (de ingelogde gebruiker: id, e-mail, naam).

Je client toont de actuele toollijst met namen, beschrijvingen en invoerschema's. Beschouw die lijst als de gezaghebbende inventaris. Een goede eerste taak om end-to-end te proberen:

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

MCP of de CLI?

Hetzelfde oppervlak, hetzelfde auth-model, andere aanroepers. Voor shell-capabele agents (Claude Code, Cursor's terminal, CI) is de CLI compacter: JSON-output, semantische exitcodes en veel minder tokens per bewerking. MCP is voor hosts die tools aanroepen in plaats van shells draaien, en het gehoste endpoint bereikt ook de hosts die helemaal geen binary kunnen uitvoeren (Claude Desktop, ChatGPT, mobiel). Je hoeft niet vooraf te kiezen: de gehoste URL vereist geen installatie, en de lokale bird mcp is er al zodra de CLI geïnstalleerd is.

Volgende stappen

• MCP Events: abonneer je client op Bird-events, zoals nieuwe mail in een mailbox, en ontvang elk event als een ondertekende webhook.
• E-mailanalytics opvragen met AI: stel vragen over bezorging, engagement en latentie in gewone taal.
• AI-onboarding: de quickstartversie van deze pagina, plus het machineleesbare docs-corpus.
• Agent skills: de bird-ai-marketplace-plugin, skills plus deze MCP-server, in één stap geïnstalleerd.
• CLI voor agents: bestuur Bird vanuit shell-agents zonder MCP: JSON-output, semantische exitcodes, OAuth-login.
• Authenticatie: API-keys, regio's en hoe verzoeken worden geautoriseerd.