--- title: "MCP Events" description: "Langganan klien MCP Anda ke event Bird, seperti email baru di kotak masuk atau SMS masuk, dan terima setiap event sebagai webhook bertanda tangan di mcp.bird.com." canonical: "https://bird.com/id-id/dokumentasi/ai/mcp-events" --- # 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](/docs/ai/mcp-server) 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](https://github.com/modelcontextprotocol/experimental-ext-triggers-events) 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 1. **Subscribe.** Client memanggil `events/subscribe` dengan event, filter, callback URL, dan signing secret miliknya sendiri (`whsec_…`). 2. **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. 3. **Receive.** Setiap event yang cocok tiba sebagai `POST` ke callback, ditandatangani dengan secret milik client. 4. **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. 5. **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](https://www.standardwebhooks.com/): - `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](/docs/ai/route-messages-to-an-agent) mengirim pesan masuk ke Claude Managed Agents atau Grok Bot melalui konektor, tanpa MCP. - [Webhooks & events](/docs/guides/webhooks) membahas verifikasi tanda tangan dan katalog event. - [Server MCP](/docs/ai/mcp-server) mencantumkan alat yang digunakan agen Anda untuk bertindak. ## Related resources - [Setting up your coding agent](/learn/basics/setting-up-your-coding-agent) (video) - [What is an MCP server, and how does an agent use one to send messages?](/explained/platform/what-is-an-mcp-server-and-how-does-an-agent-send-messages) (answer) - [Coding agents](/ai) (product) - [Build with AI agents](/learn/paths/agents) (course) [Get an implementation brief](/learn/workspace?topic=agents)