MCP इवेंट्स

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

MCP इवेंट्स, वेबहुक डिलीवरी के साथ MCP ट्रिगर और इवेंट्स एक्सटेंशन को लागू करता है। प्रोटोकॉल आपका MCP क्लाइंट संभालता है: आप उसे mcp.bird.com से जोड़ते हैं और किसी चीज़ पर नज़र रखने को कहते हैं। ChatGPT इसका समर्थन करता है।

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

अपने क्लाइंट को https://mcp.bird.com/ पर होस्ट किए गए सर्वर से, या उसके /dynamic एंडपॉइंट से जोड़ें। /public एंडपॉइंट और लोकल bird mcp सर्वर MCP इवेंट्स उपलब्ध नहीं कराते।
ऐसे खाते से साइन इन करें जो वेबहुक प्रबंधित कर सके। हर सदस्यता के लिए webhooks:write स्कोप और उसके इवेंट का रीड स्कोप चाहिए, जिनका अनुरोध क्लाइंट आपके साइन इन करते समय करता है।
ऐसा क्लाइंट इस्तेमाल करें जो इस एक्सटेंशन और उसके वेबहुक डिलीवरी मोड का समर्थन करता हो।

वे इवेंट्स जिनकी आप सदस्यता ले सकते हैं

इवेंट	रीड स्कोप	फ़िल्टर
`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 पहले से भरे होते हैं।

सदस्यता कैसे काम करती है

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

उसी साइन-इन से उसी इवेंट, फ़िल्टर और कॉलबैक के साथ दोबारा सब्सक्राइब करना 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 से प्राप्त करता है। सीमा से बड़ा होने वाला कोई अन्य इवेंट नहीं भेजा जाता।

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

सदस्यता कब समाप्त होती है

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

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

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

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

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

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

अगले कदम

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

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

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

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