MCP Events

MCP Events एक MCP क्लाइंट को पोलिंग के बिना Bird में होने वाली गतिविधियों की जानकारी देता है। आपका क्लाइंट किसी इवेंट को सब्सक्राइब करता है, जैसे मेलबॉक्स में ईमेल आना, और होस्टेड Bird MCP server हर मेल खाते इवेंट को क्लाइंट के callback URL पर पोस्ट करता है। क्लाइंट इवेंट के साथ आपके एजेंट को जगाता है, और एजेंट Bird के टूल्स से उस पर कार्रवाई करता है।

MCP Events webhook डिलीवरी के साथ MCP triggers and events extension को लागू करता है। आपका MCP क्लाइंट प्रोटोकॉल संभालता है: आप इसे mcp.bird.com से कनेक्ट करते हैं और किसी चीज़ पर नज़र रखने को कहते हैं। ChatGPT इसे सपोर्ट करता है।

शुरू करने से पहले

अपने क्लाइंट को https://mcp.bird.com/ पर होस्टेड सर्वर से, या इसके /dynamic endpoint से कनेक्ट करें। /public endpoint और लोकल bird mcp सर्वर MCP Events को सर्व नहीं करते।
ऐसे अकाउंट से साइन इन करें जो webhooks मैनेज कर सके। हर सब्सक्रिप्शन को webhooks:write स्कोप और उसके इवेंट के read स्कोप की ज़रूरत होती है, जो साइन इन करते समय क्लाइंट अनुरोध करता है।
ऐसा क्लाइंट इस्तेमाल करें जो इस extension और इसके webhook डिलीवरी मोड को सपोर्ट करता हो।

जिन इवेंट्स को आप सब्सक्राइब कर सकते हैं

इवेंट	Read स्कोप	फ़िल्टर
`email_mailbox.message_received`	`mailbox:read`	`mailbox_id`, `thread_id`
`email.delivered`	`emails:read`	`broadcast_id`
`sms.received`	`sms:read`	`to`, E.164 फ़ॉर्मेट में आपका कोई नंबर
`whatsapp.received`	`whatsapp:read`	कोई नहीं
`amb.received`	`amb:read`	कोई नहीं

events/list उन इवेंट्स को लौटाता है जिन्हें आपका साइन-इन सब्सक्राइब कर सकता है, हर एक के फ़िल्टर और पेलोड स्कीमा के साथ। फ़िल्टर सब्सक्रिप्शन को एक रिसोर्स तक सीमित करता है: mailbox_id को mbx_… पर सेट करने से केवल उस मेलबॉक्स में आने वाला मेल डिलीवर होता है। बिना फ़िल्टर वाला इवेंट वर्कस्पेस में हर घटना डिलीवर करता है।

जब आप MCP सर्वर के ज़रिए मेलबॉक्स बनाते हैं, तो रिस्पॉन्स उसके मेल को सब्सक्राइब करने का सुझाव देता है, इवेंट और mailbox_id पहले से भरे हुए होते हैं।

सब्सक्रिप्शन कैसे काम करता है

सब्सक्राइब करें। क्लाइंट इवेंट, उसके फ़िल्टर, एक callback URL और अपना signing secret (whsec_…) देकर events/subscribe को कॉल करता है।
सत्यापित करें। कुछ भी बनाने से पहले, हम callback पर एक signed {"type":"verification","challenge":"…"} पोस्ट करते हैं। callback को 4 सेकंड के भीतर एक 2xx से जवाब देना होगा जिसकी JSON बॉडी में challenge की प्रतिध्वनि हो।
प्राप्त करें। हर मेल खाता इवेंट क्लाइंट के secret से signed POST के रूप में callback पर आता है।
नवीनीकरण करें। सब्सक्रिप्शन अपने refreshBefore समय तक चलता है, क्लाइंट के सुझाए गए ttlMs से अधिकतम 24 घंटे और कम से कम 5 मिनट। उन्हीं इवेंट, फ़िल्टर और callback के साथ events/subscribe को दोबारा कॉल करने से यह उसी जगह नवीनीकृत हो जाता है। नया signing secret पुराने की जगह तब लेता है जब callback उसे सत्यापित कर लेता है, और पुराना secret 5 मिनट तक signing जारी रखता है।
समाप्त करें। क्लाइंट events/unsubscribe को कॉल करता है, या नवीनीकरण बंद कर देता है और सब्सक्रिप्शन समाप्त हो जाता है।

उसी साइन-इन से उसी इवेंट, फ़िल्टर और callback के साथ दोबारा सब्सक्राइब करना idempotent है: यह नई सब्सक्रिप्शन बनाने के बजाय आपकी मौजूदा सब्सक्रिप्शन को रिन्यू करता है।

डिलीवरी

हर डिलीवरी एक Standard Webhooks रिक्वेस्ट है:

webhook-id इवेंट की ID रखता है, ताकि क्लाइंट दोहराव को छोड़ सके।
webhook-timestamp और webhook-signature क्लाइंट के सीक्रेट से बॉडी को साइन करते हैं।
X-MCP-Subscription-Id सब्सक्रिप्शन का नाम बताता है, ताकि क्लाइंट बॉडी पढ़ने से पहले अपना सीक्रेट चुन सके।

बॉडी {"eventId", "name", "timestamp", "data", "cursor": null} है, जहाँ data इवेंट का पेलोड है जैसा events/list बताता है। हम कोई रीप्ले करने योग्य इतिहास नहीं रखते, इसलिए cursor हमेशा null होता है।

बॉडी अधिकतम 256 KiB होती है। कोई amb.received इवेंट जो इससे बड़ा होता, उसका मैसेज टेक्स्ट कैरेक्टर सीमा पर काटकर छोटा कर दिया जाता है और वह body_truncated: true रखता है; क्लाइंट पूरा मैसेज amb_get से लाता है। कोई अन्य इवेंट जो इस सीमा से बड़ा होता, भेजा नहीं जाता।

असफल डिलीवरी को लगभग आठ घंटों में आठ बार फिर से प्रयास किया जाता है, ताकि जब इवेंट पहुँचे तब वह आपके एजेंट के लिए पुराना न हो। अगर callback 410 Gone या 413 Content Too Large का जवाब देता है, तो हम उस एक इवेंट को छोड़ देते हैं और सब्सक्रिप्शन बनाए रखते हैं। असफल डिलीवरी कभी सब्सक्रिप्शन को रोकती नहीं: यह तब समाप्त होती है जब इसकी लीज़ खत्म हो जाती है।

सब्सक्रिप्शन कब समाप्त होती है

सब्सक्रिप्शन तब समाप्त होती है जब क्लाइंट अनसब्सक्राइब करता है, जब यह एक्सपायर होती है, या जब कोई इसे Bird में, डैशबोर्ड की Webhooks सूची से या API के ज़रिए डिलीट करता है। डिलीट करने से डिलीवरी तुरंत रुक जाती है, लेकिन क्लाइंट को सूचित नहीं किया जाता: जब तक क्लाइंट के पास सब्सक्रिप्शन है, वह अगले रिन्यूअल पर इसे फिर से बना लेता है और अपने callback को दोबारा वेरिफ़ाई करता है। सब्सक्रिप्शन को स्थायी रूप से रोकने के लिए इसे क्लाइंट से भी हटाएँ।

अगर किसी सब्सक्रिप्शन के पीछे का साइन-इन रद्द कर दिया जाता है, या इवेंट का read scope खो देता है, तो हम उस पर डिलीवरी बंद कर देते हैं, और यह अपनी लीज़ के भीतर एक्सपायर हो जाती है।

अपनी सब्सक्रिप्शन देखें

हर सब्सक्रिप्शन आपके वर्कस्पेस में एक webhook endpoint होता है। डैशबोर्ड की Webhooks सूची में हर सब्सक्रिप्शन अपने क्लाइंट के लोगो, इवेंट और फ़िल्टर के साथ दिखता है, और आप उसे वहीं से हटा सकते हैं। सब्सक्रिप्शन आपके संगठन की webhook endpoint सीमा में गिने जाते हैं।

समस्या निवारण

त्रुटि	इसका मतलब	क्या करें
`-32015` `CallbackEndpointError`	कॉलबैक सत्यापित नहीं हुआ। `data.reason` का मान `connection_refused`, `timeout`, `tls_error`, `http_4xx`, `http_5xx` या `challenge_failed` है।	कॉलबैक को HTTPS पर सार्वजनिक रूप से पहुँचने योग्य बनाएँ, और 4 सेकंड के भीतर `challenge` को echo करवाएँ।
`-32013` with `data.limit: "subscriptions"`	संगठन के पास कोई webhook endpoint शेष नहीं है।	कोई अनावश्यक endpoint हटाएँ, फिर दोबारा सब्सक्राइब करें।
`-32013` with `data.limit: "rate"`	कम समय में बहुत अधिक callback सत्यापन हुए।	प्रतीक्षा करें, फिर वही अनुरोध दोबारा भेजें।
`-32012`	साइन-इन में इवेंट का read scope या `webhooks:write` नहीं है। `data.required` बताता है कि कौन-सा अनुपलब्ध है।	दोबारा साइन इन करें और उसे अनुमति दें।
`-32602`	ऐसा फ़िल्टर जो इवेंट स्वीकार नहीं करता, या callback जो HTTPS नहीं है।	`events/list` द्वारा लौटाए गए फ़िल्टर उपयोग करें।

अगले कदम

अपने AI एजेंट को संदेश रूट करें इनबाउंड संदेशों को Claude Managed Agents या Grok Bot तक एक कनेक्टर के ज़रिए भेजता है, MCP के बिना।
Webhooks & events में सिग्नेचर सत्यापन और इवेंट कैटलॉग शामिल है।
MCP server उन टूल्स की सूची देता है जिनसे आपका एजेंट काम करता है।

इस विषय के लिए दस्तावेज़, गाइड और उदाहरणों के साथ आगे बढ़ें।

इम्प्लीमेंटेशन ब्रीफ़ पाएँ

संबंधित संसाधन