Server MCP

Server Bird MCP mengekspos Bird API sebagai tool Model Context Protocol. Klien yang didukung meliputi Claude Code, Cursor, VS Code, Codex, Claude, ChatGPT, dan Muse. Klien-klien ini dapat mengirim di setiap kanal yang dijalankan Bird, menyiapkan kanal tersebut, dan memeriksa workspace Anda tanpa menyalin perintah cURL. Anda dapat menjalankannya dengan dua cara, dan sebagian besar pengguna menginginkan cara pertama:

1. Hosted (mcp.bird.com): sebuah URL dan sign-in melalui browser. Tidak perlu instalasi, tanpa CLI, tanpa kunci API. Ini adalah jalur yang direkomendasikan.
2. Local over stdio (bird mcp): tool yang berjalan di mesin Anda di dalam bird CLI, untuk agen shell atau menjalankannya sendiri.

Server hosted tidak menyertakan tool khusus stdio berikut:

• auth_signup, auth_verify_email, dan auth_create_org: tool ini membuat kredensial pertama Anda, sebelum Anda dapat melakukan autentikasi ke server hosted.
• compliance_attachments_upload: tool ini membaca path file lokal. Di server hosted, path tersebut akan merujuk ke filesystem server dan bisa mengunggah file yang salah.

Hosted: hubungkan ke mcp.bird.com

Pilih endpoint

Gunakan https://mcp.bird.com untuk sebagian besar koneksi. Ini adalah endpoint yang direkomendasikan: sebagian besar klien MCP sudah mencari dan memilih tool secara internal dari katalog lengkap. Beberapa klien tidak mencari tool secara internal, atau memberlakukan batas keras pada jumlah tool yang boleh diekspos server. /dynamic ditujukan untuk klien tersebut.

Kedua endpoint hosted menggunakan Streamable HTTP dan sign-in Bird OAuth yang sama:

Endpoint dinamis memberi Anda akses ke operasi hosted yang sama melalui execute. Endpoint standar dan server stdio lokal mempertahankan tool individualnya; keduanya tidak mencantumkan search atau execute.

Anda tidak perlu menginstal binary atau membuat token. Menghubungkan memerlukan dua langkah, dan keduanya wajib:

1. Tambahkan server: berikan URL endpoint pilihan Anda ke klien.
2. Autentikasi: sign in melalui browser agar klien menyimpan token yang bertindak sebagai Anda.

Kedua endpoint memerlukan autentikasi. Klien yang hanya memiliki URL menerima 401 sampai Anda sign in. Beberapa klien memulai sign-in sendiri saat pertama kali terhubung ke server; yang lain memarkir server sebagai "needs login" dan menunggu Anda mengkliknya. Langkah-langkah klien Anda menunjukkan perilakunya.

Gunakan penemuan tool dinamis

Jika klien Anda menolak server karena terlalu banyak tool, hubungkan ke https://mcp.bird.com/dynamic dan selesaikan sign-in OAuth. Klien Anda mencantumkan dua tool:

• search mencari tool berdasarkan nama atau kata kunci deskripsi. Setiap hasil mencakup nama, deskripsi, input schema, dan anotasi yang menjelaskan apakah tool tersebut membaca atau mengubah data.
• execute memanggil satu tool yang dipilih beserta argumennya. Tool ini dapat membaca data, mengirim pesan, mengubah record, atau menghapusnya, tergantung tool yang dipilih.

Sebagai contoh, agen Anda dapat menemukan tool workspace dengan pemanggilan tool ini:

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

Setelah membaca input schema yang dikembalikan, agen memanggil tool tersebut melalui execute:

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

Hasilnya berisi workspace Anda saat ini. Anda juga dapat mencari dengan kata kunci tugas seperti send email. Pencarian default menampilkan lima hasil, menerima limit dari satu hingga 10, dan menerima kueri hingga 500 karakter. Jika hasilnya memiliki has_more: true, persempit kueri Anda untuk menemukan hasil yang lebih relevan.

Hasil pencarian tidak menambahkan tool ke katalog klien Anda. Nama yang disebutkan dalam hasil atau instruksi pemulihan juga melalui execute. Eksekusi menggunakan izin Anda yang sudah ada; jika suatu operasi memerlukan izin tambahan, klien Anda mungkin meminta Anda mengotorisasinya. Menemukan tool tidak memberikan akses ke tool tersebut.

Eksekusi dinamis mengembalikan data untuk tool yang seharusnya menampilkan widget. Gunakan endpoint standar untuk widget interaktif MCP Apps. Klien hanya melihat satu tool eksekusi, jadi pengaturan persetujuan per tool berlaku untuk execute secara keseluruhan; periksa operasi yang dipilih sebelum menyetujui pemanggilan. Endpoint ini mengeksekusi pemanggilan tool dan tidak menjalankan JavaScript atau kode lain yang disediakan.

Hubungkan klien

Contoh di bawah menggunakan endpoint standar. Untuk penemuan dinamis, ganti https://mcp.bird.com/dynamic sebagai URL server dan ikuti langkah sign-in yang sama.

Claude Code

Tambahkan server:

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

claude mcp list sekarang melaporkan bird sebagai ! Needs authentication. Claude Code tidak membuka browser secara otomatis, jadi sign in dari dalam sesi:

1. Jalankan /mcp.
2. Pilih bird dan tekan Enter.
3. Pilih Authenticate. Browser Anda membuka layar persetujuan Bird; setujui di sana.

Server kemudian terbaca sebagai terhubung dan tool-nya berfungsi. Eksekusi headless (claude -p) tidak memiliki panel /mcp, jadi lakukan autentikasi terlebih dahulu dari shell Anda dengan claude mcp login bird. Untuk sign in lagi nanti, /mcp menawarkan Re-authenticate; Clear authentication menghapus token yang tersimpan.

Menginstal plugin bird-ai mendeklarasikan server ini untuk Anda, yang menggantikan perintah claude mcp add. Autentikasi tetap diperlukan karena plugin dapat menyertakan server tetapi tidak dapat menerbitkan grant. Pilih /mcp > bird > Authenticate setelah menginstalnya.

Cursor

Di ~/.cursor/mcp.json:

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

Lalu buka Customize di sidebar Cursor dan pilih MCPs. Temukan bird, ikuti perintah sign-in-nya, setujui layar persetujuan Bird di browser, lalu kembali ke Cursor.

OpenCode

Plugin OpenCode Bird mendaftarkan server untuk Anda, beserta agent skills Bird:

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

OpenCode menambahkan setiap tool MCP ke konteks model, sehingga plugin terhubung ke endpoint dinamis. Dengan mode kode eksperimental OpenCode aktif (OPENCODE_EXPERIMENTAL_CODE_MODE=1, atau OPENCODE_EXPERIMENTAL=1), OpenCode menyimpan tool MCP di balik pencarian internalnya, dan plugin terhubung ke katalog lengkap di https://mcp.bird.com.

Untuk menambahkan server tanpa plugin, masukkan ini di opencode.json, di proyek Anda atau di ~/.config/opencode/opencode.json:

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

Lalu sign in, yang membuka browser Anda untuk layar persetujuan Bird:

opencode mcp auth bird

Mulai ulang OpenCode untuk memuat plugin. opencode mcp list melaporkan bird sebagai terhubung setelah Anda menyetujui. Plugin, seperti entri permission di atas, membuat OpenCode bertanya sebelum setiap panggilan execute, karena tool yang dijalankan dapat mengubah workspace Anda.

VS Code

Di .vscode/mcp.json di proyek Anda:

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

Menggunakan settings.json? Letakkan entri bird yang sama di bawah mcp.servers. VS Code memindahkannya ke mcp.json pengguna Anda, yang dibuka melalui MCP: Open User Configuration:

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

VS Code meminta Anda memercayai server saat pertama kali dimulai, lalu menjalankan alur OAuth sendiri: setujui layar persetujuan Bird di jendela browser yang terbuka. Jika tidak ada jendela yang muncul, mulai atau mulai ulang bird dari perintah MCP: List Servers dan setujui dari sana. Grant yang dihasilkan tercantum di Accounts > Manage Trusted MCP Servers, yang juga tempat Anda mencabut akses VS Code.

ChatGPT dan Codex

Instal Bird di ChatGPT atau Codex, masuk ke workspace Bird Anda, dan minta agen Anda untuk mengirim pesan, mengelola domain dan nomor, serta memeriksa pengiriman.

Untuk penyiapan Codex secara manual, tambahkan entri ini di ~/.codex/config.toml:

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

Lalu masuk dari shell Anda, yang akan membuka browser:

codex mcp login bird

Claude

Bird tercantum di direktori konektor Claude. Buka Bird di direktori dan klik Connect to Claude untuk menjalankan proses masuk dan menyetujui layar persetujuan. Aktifkan konektor per percakapan dari + > Connectors. Ini berfungsi di Claude versi web maupun aplikasi desktop.

Untuk menambahkannya secara manual, buka Customize > Connectors, klik +, lalu Add custom connector. Tempel https://mcp.bird.com dan klik Add. Kemudian klik Connect pada konektor Bird untuk menjalankan proses masuk dan menyetujui layar persetujuan. Pada paket Team dan Enterprise, pemilik menambahkan konektor satu kali dari Organization settings > Connectors, dan setiap anggota tetap mengklik Connect di bawah Customize > Connectors untuk grant mereka sendiri. Aktifkan konektor per percakapan dari + > Connectors.

Untuk penyiapan ChatGPT secara manual, ikuti panduan penyiapan aplikasi MCP dari OpenAI, gunakan https://mcp.bird.com sebagai URL server dan OAuth sebagai autentikasi. Selesaikan proses masuk Bird melalui browser, lalu gunakan Bird di chat Anda.

Muse

Muse menambahkan Bird sebagai konektor kustom. Dalam chat Muse, minta untuk menyiapkannya:

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 membalas dengan tautan koneksi untuk sesi ini. Buka tautan tersebut dan setujui layar persetujuan Bird di browser. Tautan ini hanya berlaku untuk Anda dan kedaluwarsa bersama sesi. Jika tautan berhenti berfungsi, minta Muse membuat tautan baru.

Factory Droid

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

Lalu jalankan /mcp di dalam droid dan selesaikan sign-in melalui browser dari server manager.

Antigravity

Plugin Antigravity Bird mendaftarkan server untuk Anda, beserta agent skills Bird:

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

Untuk menambahkan server tanpa plugin, masukkan ini di ~/.gemini/config/mcp_config.json, atau di .agents/mcp_config.json untuk satu proyek. Antigravity membaca alamat server remote dari serverUrl, jadi pertahankan nama kunci tersebut:

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

Kemudian sign in: buka Customizations di sidebar (di IDE, buka Agent settings dengan Cmd+, di macOS atau Ctrl+, di Windows dan Linux), lalu pilih Authenticate di samping bird. Jika bird tidak tercantum, mulai ulang Antigravity. Setujui layar persetujuan Bird di browser, salin kode otorisasi yang ditampilkan, tempel ke Antigravity, lalu pilih Submit.

Agent Plugins

Plugin bird-ai mendeklarasikan server ini dalam mcp.json yang mengikuti Agent Plugins. Host yang mengimplementasikan spesifikasi ini membaca file tersebut saat plugin diinstal, jadi tidak perlu menulis konfigurasi server: instal plugin dan sign in.

Host lainnya

Cari pengaturan yang menambahkan server MCP remote, HTTP, atau custom, biasanya di menu Connectors atau Integrations, lalu masukkan URL-nya. Lokasi kolom bervariasi; gunakan URL endpoint hosted yang Anda pilih. Lalu temukan mekanisme sign-in pada klien tersebut: kontrol Connect, Authorize, atau Needs login di samping server, subperintah login, atau jendela browser yang dibuka klien secara otomatis. Klien yang menampilkan daftar tool Bird tetapi setiap panggilan gagal berarti sudah memiliki URL tetapi masih memerlukan grant.

Yang terjadi saat Anda sign in

Browser Anda membuka layar persetujuan Bird. Sign in, pilih apakah akan memberikan izin workspace atau organisasi, dan pilih izin mana yang didelegasikan. Karena klien MCP mendaftarkan dirinya sendiri, nama klien bersifat self-asserted, sehingga layar menandainya sebagai not verified by Bird. Pastikan klien tersebut memang yang Anda jalankan sebelum menyetujui. Setelah itu, tool muncul di daftar agen dan token diperbarui secara otomatis, jadi ini adalah langkah satu kali per klien.

Cara tercepat untuk membuktikan koneksi berhasil adalah meminta agen memanggil whoami: tool ini mengembalikan pengguna yang sign in, jadi jawaban nyata berarti grant sudah aktif. Pada endpoint dinamis, panggil melalui execute dengan tool: "whoami" dan arguments kosong.

Grant dibatasi pada irisan antara yang diminta klien, yang Anda setujui, dan yang Anda miliki; scope org:owner dan platform-admin tidak pernah dapat didelegasikan. Grant muncul di daftar Connected apps pada profil Anda, dan mencabutnya di sana langsung memutus akses klien.

Cara kerja handshake

Anda tidak memerlukan ini untuk menghubungkan klien. Bagian ini berguna jika Anda men-debug klien yang gagal melakukan autentikasi, atau sedang membuat klien sendiri.

Tier hosted menggunakan Streamable HTTP dan tidak menyimpan kredensial: server tidak menyimpan secret apa pun dan tidak memvalidasi apa pun sendiri. Setiap permintaan membawa bearer token OAuth milik Anda, yang divalidasi oleh API Bird pada setiap permintaan. Server bersifat stateless dan lalu lintas regional dirutekan secara otomatis, sehingga satu URL berfungsi dari mana saja.

Alur sign-in menggunakan MCP standar. Perbedaan antar klien hanya pada apa yang memicunya: panggilan tool pertama atau memilih Authenticate. Setelah alur dimulai, langkah-langkah autentikasi tidak memerlukan konfigurasi tambahan:

1. Klien membuat permintaan tanpa autentikasi dan menerima 401 dengan header WWW-Authenticate yang mengarah ke metadata protected-resource RFC 9728 milik Bird (/.well-known/oauth-protected-resource).
2. Dari situ klien menemukan authorization server, lalu mendaftarkan dirinya secara dinamis (RFC 7591). Pendaftaran dinamis menghilangkan kebutuhan akan client ID yang dibagikan sebelumnya atau konfigurasi manual.
3. Browser Anda membuka layar persetujuan Bird.
4. Klien menukar hasilnya dengan access token (PKCE; di-refresh otomatis) dan tool Bird muncul.

Lokal: jalankan melalui stdio dengan CLI

Jalankan server MCP lokal di dalam bird CLI untuk agen yang mendukung shell atau akses ke file di mesin Anda. Instal CLI, jalankan bird auth login sekali, lalu arahkan klien Anda ke perintah bird mcp.

Anda tidak menjalankan bird mcp sendiri: klien Anda yang meluncurkannya dan berkomunikasi dengannya melalui stdin/stdout. Setiap klien membutuhkan dua informasi yang sama: perintah (bird) dan argumen (mcp). Jalur ini tidak memerlukan sign-in per klien karena bird auth login sudah menyimpan grant-nya.

Cursor

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

VS Code

Di .vscode/mcp.json dalam proyek Anda:

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

Claude Code

claude mcp add bird -- bird mcp

Cara server lokal melakukan autentikasi

Server lokal bertindak sebagai Anda dan menggunakan kembali login tersimpan dari CLI. bird auth login membuka alur OAuth di browser tempat Anda memberikan sebagian izin workspace Anda. Token yang diterbitkan memiliki batas izin yang sama dengan grant hosted. Cakupan org:owner maupun platform-admin tidak tersedia. bird mcp membaca dan memperbarui login tersimpan dari file kredensial CLI, yang mode-nya 0600. Seperti pada tier hosted, konfigurasi klien Anda tidak memiliki BIRD_API_KEY atau rahasia lainnya. Jika login tidak ditemukan, bird mcp menolak untuk memulai dan menyuruh Anda menjalankan bird auth login.

Anda tidak mengekspos listener: server berjalan di mesin Anda, di dalam sandbox klien, selama klien membutuhkannya. Host API mengikuti region login Anda secara otomatis; --base-url (atau BIRD_API_URL) menimpanya untuk pengujian terhadap lingkungan non-produksi.

Apa saja yang dicakup tool

Rangkaian tool mencakup setiap channel yang dijalankan Bird, ditambah tugas akun dan konfigurasi di sekitarnya. Tool ini dikurasi, bukan seluruh permukaan API: setiap tool dicakupkan ke tugas yang benar-benar dilakukan agen, dan operasi destruktif dianotasi agar host dapat bertanya sebelum menjalankannya.

Email memiliki tool paling banyak, karena memiliki permukaan konfigurasi paling luas. Channel lain mengikuti pola kirim-dan-baca yang sama.

Pesan

• Kirim dan inspeksi email: email_send, email_send_batch, email_list, dan email_get, yang mengembalikan pesan beserta status pengiriman agregatnya. Status pengiriman per penerima dan log peristiwa adalah panggilan tool terpisah.
• Kirim dan inspeksi SMS: sms_send, sms_send_batch, sms_get, sms_list, dan sms_list_events, mengikuti pola email. sms_templates_list dan sms_templates_get membaca katalog template.
• Kirim dan inspeksi WhatsApp: whatsapp_send, whatsapp_get, whatsapp_list, whatsapp_list_events, dan whatsapp_media. Template adalah permukaan penulisan lengkap di bawah whatsapp_templates_*, termasuk konten per versi dan per bahasa.
• Inspeksi leg panggilan suara: voice_legs_get dan voice_legs_list membaca leg panggilan, dengan statistik per negara dan per kode respons di voice_stats_*. voice_session_credentials_create membuat kredensial workspace yang digunakan klien SIP atau softphone untuk autentikasi.
• Verifikasi penerima: verify_verifications_create mengirim kode verifikasi sekali pakai, verify_verifications_check memvalidasi apa yang dikirimkan penerima, dan verify_verifications_next_channel beralih ke kanal lain.
• Buat panggilan suara (pratinjau): voice_calls_create menyiapkan panggilan keluar menggunakan publikasi aktif dari sequence yang diaktifkan dan tidak diarsipkan. Seseorang meninjau dan menjalankan permintaan di browser; menyiapkan tidak berarti melakukan panggilan. Lihat Buat panggilan suara untuk izin dan instruksi coba lagi. Server bird mcp lokal memerlukan versi CLI yang menyertakan tool ini.

Menyiapkan kanal untuk mengirim

• Siapkan domain pengirim: email_domains_create menambahkan domain pengirim dan mengembalikan record DNS yang perlu dipublikasikan; email_domains_verify memeriksanya ulang; ditambah email_domains_list dan email_domains_get.
• Klaim dan daftarkan pengirim SMS: sms_senders_create mengklaim pengirim, sms_senders_requirements melaporkan apa yang diminta suatu negara darinya, dan sms_senders_registrations_create mendaftarkannya. Trafik A2P AS berjalan melalui tool brand, campaign, dan submission sms_10dlc_*.
• Penyediaan nomor: numbers_available_list mencari, numbers_orders_create membeli, numbers_cancel mengembalikan di akhir periode berbayar (atau langsung jika nomor tidak memiliki langganan), dan numbers_release mengembalikan sekarang. whatsapp_numbers_precheck melaporkan apakah WhatsApp akan menerima nomor sebelum Anda memesannya.
• Periksa apakah akun bisa mengirim: tool trust_* melaporkan persyaratan organisasi yang menjadi syarat untuk membeli nomor atau mendaftarkan pengirim.

Deliverabilitas email

• Tulis template email: email_templates_create, email_templates_list, email_templates_get, email_templates_update, email_templates_duplicate, dan email_templates_preview (render draf dengan nilai contoh tanpa mengirim). Versi berada di bawah email_templates_versions_*, di mana email_templates_versions_submit membekukan draf dan menjadikannya versi yang dilayani oleh pengiriman, dan email_templates_versions_languages_* mengedit konten per bahasa dari sebuah draf. Tidak ada yang ditulis agen yang sampai ke penerima sampai dikirimkan.
• Kelola supresi: email_suppressions_list, email_suppressions_check (apakah alamat ini aman untuk dikirim?), email_suppressions_add, dan email_suppressions_remove (ditandai destruktif, karena menghapus supresi tanpa alasan merusak reputasi pengirim).
• Kelola IP dan pool khusus: email_dedicated_ips_create, email_dedicated_ips_list, email_dedicated_ips_get, email_dedicated_ips_assign (pindahkan satu ke dalam pool), dan email_dedicated_ips_delete; ditambah email_ip_pools_create, email_ip_pools_list, email_ip_pools_get, email_ip_pools_update, dan email_ip_pools_delete untuk pool yang Anda gunakan untuk merutekan pengiriman.

Audiens dan konfigurasi

• Kelola kontak dan audiens: contacts_* dan contact_properties_* untuk orang yang Anda kirimi pesan, audiences_* untuk daftar tujuan pengiriman, dan preferences_* untuk pemberian izin dan opt-out.
• Provisikan Realtime: realtime_apps_* dan realtime_apps_keys_* membuat aplikasi dan kunci yang digunakan klien Realtime untuk terhubung.
• Cari tahu tentang seseorang: lookup_phone_number dan lookup_email melaporkan apa yang Bird ketahui tentang suatu alamat sebelum Anda mengirim ke alamat tersebut.
• Periksa konfigurasi: webhooks_list, workspace_get, dan whoami (pengguna yang masuk: id, email, nama).

Klien Anda menampilkan daftar tool aktif beserta nama, deskripsi, dan skema input. Anggap daftar itu sebagai inventaris resmi. Tugas pertama yang baik untuk dicoba secara menyeluruh:

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

MCP atau CLI?

Permukaan sama, model autentikasi sama, pemanggil berbeda. Untuk agen yang mampu mengakses shell (Claude Code, terminal Cursor, CI), CLI lebih ringan: output JSON, kode keluar semantik, dan token per operasi jauh lebih sedikit. MCP ditujukan untuk host yang memanggil tool alih-alih menjalankan shell, dan endpoint hosted menjangkau host yang sama sekali tidak bisa menjalankan biner (Claude Desktop, ChatGPT, mobile). Anda tidak perlu memilih dari awal: URL hosted tidak perlu instalasi, dan bird mcp lokal sudah tersedia begitu CLI terpasang.

Langkah selanjutnya

• MCP Events: daftarkan klien Anda ke event Bird, seperti email baru di kotak masuk, dan terima setiap event sebagai webhook bertanda tangan.
• Kueri analitik email dengan AI: tanyakan tentang pengiriman, keterlibatan, dan latensi dalam bahasa sehari-hari.
• Onboarding AI: versi panduan cepat dari halaman ini, ditambah korpus dokumentasi yang dapat dibaca mesin.
• Agent skills: plugin marketplace bird-ai, skills ditambah server MCP ini, dipasang dalam satu langkah.
• CLI untuk agen: kendalikan Bird dari agen berbasis shell tanpa MCP: output JSON, kode keluar semantik, login OAuth.
• Autentikasi: kunci API, region, dan cara permintaan diotorisasi.