Server MCP

Il server Bird MCP espone le Bird API come tool Model Context Protocol. I client supportati includono Claude Code, Cursor, VS Code, Codex, Claude, ChatGPT e Muse. Possono inviare su ogni canale gestito da Bird, configurare quei canali e ispezionare il tuo spazio di lavoro senza copiare comandi cURL. Puoi eseguirlo in due modi, e la maggior parte delle persone preferisce il primo:

1. Hosted (mcp.bird.com): un URL e un accesso dal browser. Niente da installare, nessun CLI, nessuna chiave API. È il percorso consigliato.
2. Locale via stdio (bird mcp): tool in esecuzione sulla tua macchina all'interno della bird CLI, per agent shell o per eseguirlo in autonomia.

Il server hosted omette questi tool disponibili solo via stdio:

• auth_signup, auth_verify_email e auth_create_org: questi tool creano la tua prima credenziale, prima che tu possa autenticarti verso il server hosted.
• compliance_attachments_upload: questo tool legge un percorso file locale. Sul server hosted, quel percorso farebbe riferimento al filesystem del server e potrebbe caricare il file sbagliato.

Hosted: connettersi a mcp.bird.com

Scegliere un endpoint

Usa https://mcp.bird.com per la maggior parte delle connessioni. È l'endpoint consigliato: la maggior parte dei client MCP cerca e seleziona già i tool internamente dal catalogo completo. Alcuni client non cercano i tool internamente o impongono un limite rigido al numero di tool che un server può esporre. /dynamic è pensato per quei client.

Entrambi gli endpoint hosted usano Streamable HTTP e lo stesso accesso Bird OAuth:

L'endpoint dinamico ti dà accesso alle stesse operazioni hosted tramite execute. L'endpoint standard e il server locale stdio mantengono i propri tool individuali; non elencano search né execute.

Non devi installare un binario né creare un token. La connessione richiede due passaggi, ed entrambi sono obbligatori:

1. Aggiungi il server: fornisci al client l'URL dell'endpoint che hai scelto.
2. Autenticati: accedi dal browser in modo che il client possieda un token che agisce come te.

Entrambi gli endpoint richiedono l'autenticazione. Un client che ha solo l'URL riceve un 401 finché non effettui l'accesso. Alcuni client avviano l'accesso da soli la prima volta che raggiungono il server; altri parcheggiano il server come "needs login" e attendono che tu faccia clic. I passaggi del tuo client ne identificano il comportamento.

Usare la scoperta dinamica dei tool

Se il tuo client rifiuta il server perché offre troppi tool, connettiti a https://mcp.bird.com/dynamic e completa l'accesso OAuth. Il tuo client elenca due tool:

• search trova tool per nome o parole chiave nella descrizione. Ogni corrispondenza include nome, descrizione, schema di input e annotazioni che indicano se il tool legge o modifica dati.
• execute chiama un tool selezionato con i suoi argomenti. Può leggere dati, inviare messaggi, modificare record o eliminarli, a seconda del tool selezionato.

Per esempio, il tuo agent può trovare il tool workspace con questa chiamata:

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

Dopo aver letto lo schema di input restituito, chiama quel tool tramite execute:

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

Il risultato contiene il tuo spazio di lavoro corrente. Puoi anche cercare con parole chiave di attività come send email. La ricerca restituisce cinque corrispondenze per impostazione predefinita, accetta un limit da uno a 10 e accetta query fino a 500 caratteri. Se il risultato contiene has_more: true, restringi la query per trovare corrispondenze più pertinenti.

I risultati della ricerca non aggiungono tool al catalogo del client. I nomi menzionati nei risultati o nelle istruzioni di ripristino passano anch'essi attraverso execute. L'esecuzione usa i tuoi permessi esistenti; se un'operazione richiede più permessi, il client potrebbe chiederti di autorizzarli. Trovare un tool non concede accesso a esso.

L'esecuzione dinamica restituisce dati per tool che altrimenti mostrano widget. Usa l'endpoint standard per i widget interattivi MCP Apps. I client vedono un unico tool di esecuzione, quindi le impostazioni di approvazione per singolo tool si applicano a execute nel suo insieme; verifica l'operazione selezionata prima di approvare una chiamata. Questo endpoint esegue chiamate a tool e non esegue JavaScript o altro codice fornito.

Collegare un client

Gli esempi seguenti usano l'endpoint standard. Per la scoperta dinamica, sostituisci https://mcp.bird.com/dynamic come URL del server e segui gli stessi passaggi di accesso.

Claude Code

Aggiungi il server:

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

claude mcp list ora mostra bird come ! Needs authentication. Claude Code non apre il browser da solo, quindi accedi dall'interno di una sessione:

1. Esegui /mcp.
2. Seleziona bird e premi Invio.
3. Scegli Authenticate. Il browser apre la schermata di consenso di Bird; approvala lì.

Il server risulta quindi connesso e i tool funzionano. Un'esecuzione headless (claude -p) non ha il pannello /mcp, quindi autenticati prima dalla shell con claude mcp login bird. Per accedere di nuovo in seguito, /mcp offre Re-authenticate; Clear authentication rimuove il token memorizzato.

Installando il plugin bird-ai questo server viene dichiarato al tuo posto, sostituendo il comando claude mcp add. L'autenticazione resta necessaria perché un plugin può fornire un server ma non emettere un grant. Seleziona /mcp > bird > Authenticate dopo averlo installato.

Cursor

In ~/.cursor/mcp.json:

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

Apri quindi Customize nella barra laterale di Cursor e seleziona MCPs. Trova bird, segui la richiesta di accesso, approva la schermata di consenso di Bird nel browser e torna a Cursor.

OpenCode

Il plugin OpenCode di Bird registra il server al posto tuo, insieme alle agent skills di Bird:

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

OpenCode aggiunge ogni tool MCP al contesto del modello, quindi il plugin si connette all'endpoint dinamico. Con la modalità code sperimentale di OpenCode attiva (OPENCODE_EXPERIMENTAL_CODE_MODE=1 o OPENCODE_EXPERIMENTAL=1), OpenCode mantiene i tool MCP dietro la propria ricerca e il plugin si connette al catalogo completo su https://mcp.bird.com.

Per aggiungere il server senza il plugin, inserisci questo in opencode.json, nel tuo progetto o in ~/.config/opencode/opencode.json:

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

Poi accedi: il browser si apre sulla schermata di consenso di Bird:

opencode mcp auth bird

Riavvia OpenCode per caricare il plugin. opencode mcp list indica bird come connesso dopo l'approvazione. Il plugin, come la voce permission qui sopra, fa sì che OpenCode chieda conferma prima di ogni chiamata execute, perché il tool eseguito può modificare il tuo spazio di lavoro.

VS Code

In .vscode/mcp.json nel tuo progetto:

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

Usi settings.json? Inserisci la stessa voce bird sotto mcp.servers. VS Code la sposta nel tuo mcp.json utente, che MCP: Open User Configuration apre:

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

VS Code chiede di considerare attendibile il server al primo avvio, poi esegue il flusso OAuth da solo: approva la schermata di consenso di Bird nella finestra del browser che si apre. Se non compare alcuna finestra, avvia o riavvia bird dal comando MCP: List Servers e approva in quel momento. Il grant risultante è elencato in Accounts > Manage Trusted MCP Servers, da cui puoi anche revocare l'accesso di VS Code.

ChatGPT e Codex

Installa Bird in ChatGPT o Codex, accedi al tuo spazio di lavoro Bird e chiedi al tuo agente di inviare messaggi, gestire domini e numeri e controllare la consegna.

Per configurare Codex manualmente, aggiungi invece questa voce in ~/.codex/config.toml:

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

Poi accedi dalla tua shell, che apre il browser:

codex mcp login bird

Claude

Bird è presente nella directory dei connettori di Claude. Apri Bird nella directory e fai clic su Connect to Claude per eseguire l'accesso e approvare la schermata di consenso. Attiva il connettore per ogni conversazione da + > Connectors. Funziona in Claude sul web e nell'app desktop.

Per aggiungerlo manualmente, apri Customize > Connectors, fai clic su +, poi su Add custom connector. Incolla https://mcp.bird.com e fai clic su Add. Poi fai clic su Connect sul connettore Bird per eseguire l'accesso e approvare la schermata di consenso. Nei piani Team ed Enterprise un proprietario aggiunge il connettore una sola volta da Organization settings > Connectors, e ogni membro fa comunque clic su Connect sotto Customize > Connectors per il proprio grant. Attiva il connettore per ogni conversazione da + > Connectors.

Per configurare ChatGPT manualmente, segui invece la guida di OpenAI alla configurazione delle app MCP, usando https://mcp.bird.com come URL del server e OAuth come autenticazione. Completa l'accesso nel browser di Bird, poi usa Bird nella tua chat.

Muse

Muse aggiunge Bird come connettore personalizzato. In una chat di Muse, chiedi di configurarne uno:

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 risponde con un link di connessione per questa sessione. Aprilo e approva la schermata di consenso di Bird nel browser. Il link funziona solo per te e scade con la sessione. Se smette di funzionare, chiedi a Muse di generarne uno nuovo.

Factory Droid

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

Poi esegui /mcp dentro droid e completa l'accesso via browser dal gestore dei server.

Antigravity

Il plugin Antigravity di Bird registra il server al posto tuo, insieme alle agent skills di Bird:

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

Per aggiungere il server senza il plugin, inserisci questo in ~/.gemini/config/mcp_config.json, o in .agents/mcp_config.json per un singolo progetto. Antigravity legge l'indirizzo di un server remoto da serverUrl, quindi mantieni quel nome di chiave:

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

Quindi accedi: apri Customizations nella barra laterale (nell'IDE, apri Agent settings con Cmd+, su macOS o Ctrl+, su Windows e Linux) e seleziona Authenticate accanto a bird. Se bird non è nell'elenco, riavvia Antigravity. Approva la schermata di consenso di Bird nel browser, copia il codice di autorizzazione mostrato, incollalo in Antigravity e seleziona Submit.

Agent Plugins

Il plugin bird-ai dichiara questo server in un mcp.json conforme ad Agent Plugins. Un host che implementa la specifica legge quel file al momento dell'installazione del plugin, quindi non serve scrivere alcuna configurazione del server: installa il plugin e accedi.

Qualsiasi altro host

Cerca l'impostazione che aggiunge un server MCP remoto, HTTP o personalizzato, spesso sotto un menu Connectors o Integrations, e inserisci l'URL. La posizione del campo varia; usa l'URL dell'endpoint hosted che hai scelto. Poi trova il meccanismo di accesso del client: un controllo Connect, Authorize o Needs login accanto al server, un sottocomando login o una finestra del browser che il client apre da solo. Un client che elenca i tool di Bird ma fallisce ogni chiamata ha l'URL ma necessita ancora di un grant.

Cosa succede quando accedi

Il browser si apre sulla schermata di consenso di Bird. Accedi, scegli se concedere permessi a livello di spazio di lavoro o di organizzazione e seleziona quali permessi delegare. Poiché i client MCP si registrano autonomamente, il nome del client è auto-dichiarato, quindi la schermata lo segnala come not verified by Bird. Conferma che si tratti del client che hai effettivamente avviato prima di approvare. Dopo di che i tool compaiono nella lista dell'agente e il token si rinnova silenziosamente, quindi questo passaggio va fatto una sola volta per client.

Il modo più rapido per verificare che funzioni è far chiamare whoami all'agente: restituisce l'utente autenticato, quindi una risposta reale significa che il grant è attivo. Sull'endpoint dinamico, chiamalo tramite execute con tool: "whoami" e arguments vuoti.

Il grant è limitato all'intersezione tra ciò che il client ha richiesto, ciò che hai approvato e ciò che possiedi effettivamente; gli scope org:owner e platform-admin non sono mai delegabili. Compare nella lista App connesse del tuo profilo, e revocarlo lì disconnette immediatamente il client.

Come funziona l'handshake

Non serve per connettere un client. È utile se stai facendo debug di un client che non si autentica, o se ne stai scrivendo uno.

Il livello hosted parla Streamable HTTP ed è privo di credenziali: non memorizza segreti e non valida nulla autonomamente. Ogni richiesta porta il tuo bearer token OAuth, che Bird API valida per ogni richiesta. Il server è stateless e il traffico regionale viene instradato automaticamente, quindi l'unico URL funziona ovunque.

Il flusso di accesso usa MCP standard. I client differiscono solo per cosa lo attiva: la prima chiamata a un tool o la selezione di Authenticate. Dopo l'avvio del flusso, i passaggi di autenticazione non richiedono configurazione aggiuntiva:

1. Il client effettua una richiesta non autenticata e riceve 401 con un header WWW-Authenticate che punta ai metadati protected-resource RFC 9728 di Bird (/.well-known/oauth-protected-resource).
2. Da lì scopre il server di autorizzazione, quindi si registra dinamicamente (RFC 7591). La registrazione dinamica elimina la necessità di un client ID precondiviso o di configurazione manuale.
3. Il browser apre la schermata di consenso di Bird.
4. Il client scambia il risultato con un access token (PKCE; aggiornato automaticamente) e i tool Bird compaiono.

Locale: eseguirlo via stdio con la CLI

Esegui il server MCP locale all'interno della bird CLI per agent con accesso alla shell o per accedere ai file sulla tua macchina. Installa la CLI, esegui bird auth login una volta, quindi punta il tuo client al comando bird mcp.

Non esegui bird mcp manualmente: il tuo client lo avvia e comunica con esso su stdin/stdout. Ogni client ha bisogno degli stessi due dati: il comando (bird) e l'argomento (mcp). Questo percorso non richiede accesso per ogni client perché bird auth login detiene già il grant.

Cursor

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

VS Code

In .vscode/mcp.json nel tuo progetto:

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

Claude Code

claude mcp add bird -- bird mcp

Come si autentica il server locale

Il server locale agisce come te e riutilizza il login memorizzato della CLI. bird auth login apre un flusso OAuth nel browser in cui concedi un sottoinsieme dei permessi del tuo spazio di lavoro. Il token emesso ha gli stessi limiti di permessi del grant hosted. Gli scope org:owner e platform-admin non sono mai disponibili. bird mcp legge e rinnova il login memorizzato dal file di credenziali CLI, la cui modalità è 0600. Come per il livello hosted, la configurazione del client non contiene BIRD_API_KEY né altri segreti. Se il login manca, bird mcp rifiuta di avviarsi e chiede di eseguire bird auth login.

Non esponi alcun listener: il server gira sulla tua macchina, nella sandbox del client, esattamente per il tempo in cui il client ne ha bisogno. L'host API segue automaticamente la regione del tuo login; --base-url (o BIRD_API_URL) la sovrascrive per testare un ambiente non di produzione.

Cosa coprono i tool

Il set di tool copre ogni canale su cui opera Bird, più le attività di account e configurazione correlate. È una selezione curata, non l'intera superficie API: ogni tool è circoscritto a un'operazione che un agente esegue effettivamente, e le operazioni distruttive sono annotate in modo che gli host possano chiedere conferma prima di eseguirle.

L'email ha il maggior numero di tool, perché ha la superficie di configurazione più ampia. Gli altri canali seguono la stessa struttura invio-e-lettura.

Messaggistica

• Invia e ispeziona email: email_send, email_send_batch, email_list e email_get, che restituisce il messaggio con il suo stato di consegna aggregato. Gli stati di consegna per singolo destinatario e il log degli eventi sono chiamate a tool separate.
• Invia e ispeziona SMS: sms_send, sms_send_batch, sms_get, sms_list e sms_list_events, con la stessa struttura dell'email. sms_templates_list e sms_templates_get leggono il catalogo dei template.
• Invia e ispeziona WhatsApp: whatsapp_send, whatsapp_get, whatsapp_list, whatsapp_list_events e whatsapp_media. I template sono una superficie di authoring completa sotto whatsapp_templates_*, con contenuti per versione e per lingua.
• Ispezionare i leg delle chiamate vocali: voice_legs_get e voice_legs_list leggono i leg delle chiamate, con statistiche per paese e per codice di risposta sotto voice_stats_*. voice_session_credentials_create crea la credenziale dello spazio di lavoro che un client SIP o softphone usa per autenticarsi.
• Verificare un destinatario: verify_verifications_create invia un codice di verifica monouso, verify_verifications_check convalida quanto inviato dal destinatario e verify_verifications_next_channel ripassa a un altro canale.
• Creare una chiamata vocale (anteprima): voice_calls_create prepara una chiamata in uscita usando la pubblicazione attiva di una sequenza abilitata e non archiviata. Una persona esamina ed esegue la richiesta nel browser; la preparazione non effettua la chiamata. Vedi Creare una chiamata vocale per i permessi e le istruzioni per riprovare. Il server locale bird mcp richiede una versione di CLI che includa questo tool.

Preparare un canale per l'invio

• Configurare i domini di invio: email_domains_create aggiunge un dominio di invio e restituisce i record DNS da pubblicare; email_domains_verify li ricontrolla; più email_domains_list e email_domains_get.
• Rivendicare e registrare mittenti SMS: sms_senders_create rivendica un mittente, sms_senders_requirements indica cosa un paese richiede per esso e sms_senders_registrations_create lo registra. Il traffico A2P negli Stati Uniti passa attraverso i tool di brand, campagna e submission di sms_10dlc_*.
• Provisioning numeri: numbers_available_list cerca, numbers_orders_create acquista, numbers_cancel restituisce alla fine del periodo pagato (o subito se il numero non ha un abbonamento) e numbers_release restituisce immediatamente. whatsapp_numbers_precheck indica se WhatsApp accetterà un numero prima che tu lo ordini.
• Verificare che l'account possa inviare: i tool trust_* indicano i requisiti dell'organizzazione necessari per acquistare un numero o registrare un mittente.

Recapitabilità email

• Creare template email: email_templates_create, email_templates_list, email_templates_get, email_templates_update, email_templates_duplicate e email_templates_preview (renderizza una bozza con valori di esempio senza inviare). Le versioni si trovano sotto email_templates_versions_*, dove email_templates_versions_submit congela una bozza e la rende la versione servita dagli invii, e email_templates_versions_languages_* modifica il contenuto per lingua di una bozza. Nulla di ciò che un agente scrive raggiunge un destinatario finché non lo invia.
• Gestire le soppressioni: email_suppressions_list, email_suppressions_check (è sicuro inviare a questo indirizzo?), email_suppressions_add e email_suppressions_remove (annotato come distruttivo, perché rimuovere una soppressione senza motivo danneggia la reputazione del mittente).
• Gestire IP dedicati e pool: email_dedicated_ips_create, email_dedicated_ips_list, email_dedicated_ips_get, email_dedicated_ips_assign (spostarne uno in un pool) e email_dedicated_ips_delete; più email_ip_pools_create, email_ip_pools_list, email_ip_pools_get, email_ip_pools_update e email_ip_pools_delete per i pool attraverso cui instradi gli invii.

Pubblico e configurazione

• Gestire contatti e pubblico: contacts_* e contact_properties_* per le persone a cui invii, audiences_* per le liste a cui invii e preferences_* per le autorizzazioni al consenso e le rinunce.
• Provisioning Realtime: realtime_apps_* e realtime_apps_keys_* creano le app e le chiavi con cui si connettono i client Realtime.
• Ricerca di un destinatario: lookup_phone_number e lookup_email riportano ciò che Bird sa di un indirizzo prima che tu invii.
• Ispezione della configurazione: webhooks_list, workspace_get e whoami (l'utente autenticato: id, email, nome).

Il tuo client mostra l'elenco aggiornato dei tool con nomi, descrizioni e schemi di input. Considera quell'elenco come l'inventario autorevole. Un buon primo compito da provare dall'inizio alla fine:

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

MCP o la CLI?

Stessa superficie, stesso modello di autenticazione, chiamanti diversi. Per gli agenti con accesso alla shell (Claude Code, il terminale di Cursor, CI), la CLI è più snella: output JSON, codici di uscita semantici e molti meno token per operazione. MCP è per gli host che chiamano tool invece di eseguire shell, e l'endpoint hosted raggiunge quelli che non possono affatto eseguire un binario (Claude Desktop, ChatGPT, mobile). Non devi scegliere subito: l'URL hosted non richiede installazione e la bird mcp locale è già disponibile una volta che hai la CLI.

Passaggi successivi

• MCP Events: iscrivere il client agli eventi Bird, come la ricezione di nuova posta in una casella, e ricevere ciascuno come webhook firmato.
• Interroga le analitiche email con l'AI: chiedi informazioni su consegna, engagement e latenza in linguaggio naturale.
• Onboarding AI: la versione quickstart di questa pagina, più il corpus di documentazione leggibile dalle macchine.
• Agent skills: il plugin bird-ai del marketplace, skill più questo server MCP, installati in un solo passaggio.
• CLI per agenti: gestisci Bird da agenti con accesso alla shell senza MCP: output JSON, codici di uscita semantici, login OAuth.
• Autenticazione: chiavi API, regioni e come vengono autorizzate le richieste.