MCP Events

MCP Events memungkinkan klien MCP mengetahui apa yang terjadi di Bird tanpa polling. Klien Anda berlangganan ke sebuah event, misalnya email yang masuk ke kotak masuk, dan server Bird MCP yang di-host mengirimkan setiap event yang cocok ke callback URL milik klien. Klien membangunkan agen Anda dengan event tersebut, dan agen bertindak menggunakan tools Bird.

MCP Events mengimplementasikan ekstensi triggers and events MCP dengan pengiriman webhook. Klien MCP Anda menangani protokolnya: Anda menghubungkannya ke mcp.bird.com dan memintanya memantau sesuatu. ChatGPT sudah mendukungnya.

Sebelum Anda mulai

Hubungkan klien Anda ke server yang di-host di https://mcp.bird.com/, atau endpoint /dynamic-nya. Endpoint /public dan server bird mcp lokal tidak melayani MCP Events.
Masuk dengan akun yang dapat mengelola webhook. Setiap langganan memerlukan scope webhooks:write dan scope read dari event-nya, yang diminta oleh klien saat Anda masuk.
Gunakan klien yang mendukung ekstensi dan mode pengiriman webhook-nya.

Event yang dapat Anda langgani

Event	Scope read	Filter
`email_mailbox.message_received`	`mailbox:read`	`mailbox_id`, `thread_id`
`email.delivered`	`emails:read`	`broadcast_id`
`sms.received`	`sms:read`	`to`, salah satu nomor Anda dalam format E.164
`whatsapp.received`	`whatsapp:read`	tidak ada
`amb.received`	`amb:read`	tidak ada

events/list mengembalikan event yang dapat Anda langgani dengan sign-in Anda, masing-masing beserta filter dan skema payload-nya. Filter mempersempit langganan ke satu resource: mailbox_id yang disetel ke mbx_… hanya mengirimkan email yang masuk ke mailbox tersebut. Event tanpa filter mengirimkan setiap kejadian di workspace.

Setelah Anda membuat mailbox melalui server MCP, respons menyarankan untuk berlangganan email-nya, dengan event dan mailbox_id sudah terisi.

Cara kerja langganan

Subscribe. Client memanggil events/subscribe dengan event, filter, callback URL, dan signing secret miliknya sendiri (whsec_…).
Verify. Sebelum membuat apa pun, kami mengirimkan {"type":"verification","challenge":"…"} bertanda tangan ke callback. Callback harus menjawab dengan 2xx yang body JSON-nya menggemakan challenge, dalam waktu 4 detik.
Receive. Setiap event yang cocok tiba sebagai POST ke callback, ditandatangani dengan secret milik client.
Renew. Langganan berlaku hingga waktu refreshBefore-nya, maksimal 24 jam dan minimal 5 menit dari ttlMs yang disarankan client. Memanggil events/subscribe lagi dengan event, filter, dan callback yang sama akan memperbarui langganan yang ada. Signing secret baru menggantikan yang lama setelah callback memverifikasinya, dan secret lama tetap menandatangani selama 5 menit.
End. Client memanggil events/unsubscribe, atau berhenti memperbarui dan langganan kedaluwarsa.

Berlangganan lagi dari sign-in yang sama dengan event, filter, dan callback yang sama bersifat idempoten: langganan Anda yang sudah ada diperbarui, bukan membuat yang baru.

Pengiriman

Setiap pengiriman adalah permintaan Standard Webhooks:

webhook-id membawa ID event, sehingga klien dapat mengabaikan duplikat.
webhook-timestamp dan webhook-signature menandatangani body dengan secret milik klien.
X-MCP-Subscription-Id menyebutkan nama langganan, sehingga klien dapat memilih secret-nya sebelum membaca body.

Body-nya adalah {"eventId", "name", "timestamp", "data", "cursor": null}, di mana data adalah payload event seperti yang dijelaskan events/list. Kami tidak menyimpan riwayat yang dapat diputar ulang, jadi cursor selalu null.

Ukuran body maksimal 256 KiB. Event amb.received yang melebihi batas tersebut akan memotong teks pesan di batas karakter dan menyertakan body_truncated: true; klien mengambil seluruh pesan dengan amb_get. Event lain yang melebihi batas tidak dikirim.

Pengiriman yang gagal dicoba lagi delapan kali selama sekitar delapan jam, sehingga event yang ditindaklanjuti agen Anda tidak basi saat tiba. Jika callback menjawab 410 Gone atau 413 Content Too Large, kami membatalkan satu event tersebut dan mempertahankan langganan. Pengiriman yang gagal tidak pernah menghentikan sementara langganan: langganan berakhir saat masa sewanya habis.

Saat langganan berakhir

Langganan berakhir saat klien berhenti berlangganan, saat kedaluwarsa, atau saat seseorang menghapusnya di Bird, dari daftar Webhooks di dasbor atau melalui API. Menghapusnya langsung menghentikan pengiriman, tetapi klien tidak diberi tahu: selama klien masih menyimpan langganan tersebut, klien akan membuatnya kembali pada pembaruan berikutnya, dengan memverifikasi callback-nya lagi. Untuk menghentikan langganan secara permanen, hapus juga dari klien.

Jika sign-in di balik langganan dicabut, atau kehilangan read scope event tersebut, kami berhenti mengirim ke langganan itu, dan langganan kedaluwarsa dalam masa sewanya.

Lihat langganan Anda

Setiap langganan adalah endpoint webhook di workspace Anda. Daftar Webhooks di dashboard menampilkan masing-masing beserta logo kliennya, event-nya, dan filternya, dan Anda dapat menghapusnya dari sana. Langganan dihitung terhadap batas endpoint webhook organisasi Anda.

Pemecahan masalah

Error	Artinya	Yang harus dilakukan
`-32015` `CallbackEndpointError`	Callback tidak terverifikasi. `data.reason` adalah `connection_refused`, `timeout`, `tls_error`, `http_4xx`, `http_5xx` atau `challenge_failed`.	Pastikan callback dapat diakses publik melalui HTTPS, dan buat callback tersebut mengembalikan `challenge` dalam 4 detik.
`-32013` dengan `data.limit: "subscriptions"`	Organisasi tidak memiliki endpoint webhook tersisa.	Hapus endpoint yang tidak lagi Anda butuhkan, lalu subscribe lagi.
`-32013` dengan `data.limit: "rate"`	Terlalu banyak verifikasi callback dalam waktu singkat.	Tunggu, lalu coba lagi permintaan yang sama.
`-32012`	Proses masuk tidak memiliki read scope event atau `webhooks:write`. `data.required` menyebutkan yang tidak ada.	Masuk lagi dan berikan izin tersebut.
`-32602`	Filter yang tidak diterima event, atau callback yang bukan HTTPS.	Gunakan filter yang dikembalikan `events/list`.

Langkah selanjutnya

Rutekan pesan ke agen AI Anda mengirim pesan masuk ke Claude Managed Agents atau Grok Bot melalui konektor, tanpa MCP.
Webhooks & events membahas verifikasi tanda tangan dan katalog event.
Server MCP mencantumkan alat yang digunakan agen Anda untuk bertindak.

Lanjutkan dengan dokumentasi, panduan, dan contoh untuk topik ini.

Dapatkan ringkasan implementasi

Sumber daya terkait