Chatroostकस्टम MCP क्लाइंट्स के लिए OAuth
अगर आप अपना खुद का MCP क्लाइंट (CLI, SDK, IDE प्लगइन) बना रहे हैं, तो यह पेज हमारे OAuth इम्प्लीमेंटेशन का वर्णन करता है: कौन-से स्टैंडर्ड्स हम सपोर्ट करते हैं, एंडपॉइंट्स, redirect_uri के नियम, और सामान्य एरर्स को कैसे डीबग करें। Claude.ai और ChatGPT यूज़र्स को इस पेज की ज़रूरत नहीं है — उसकी जगह Quickstart देखें।
हम जो स्टैंडर्ड्स इम्प्लीमेंट करते हैं
mcp-telegram.com उन सभी OAuth स्पेसिफिकेशन्स के साथ पूरी तरह संगत है जिन पर MCP इकोसिस्टम निर्भर करता है — कोई प्रोप्राइटरी एक्सटेंशन नहीं, और क्लाइंट्स में कोई शेयर्ड सीक्रेट हार्डकोडेड नहीं।
एंडपॉइंट्स
PKCE के साथ authorization code फ्लो
स्टैंडर्ड RFC 6749 §4.1 + RFC 7636 फ्लो। कोई सरप्राइज नहीं — अगर आपकी OAuth लाइब्रेरी «authorization code + PKCE» को हैंडल करती है, तो यह काम करेगा।
अपने क्लाइंट को रजिस्टर करें
POST /oauth/register पर { redirect_uris: ["http://127.0.0.1:«port»/callback"], client_name: "your-client-name" } भेजें। सर्वर client_id + client_secret लौटाता है (secret पब्लिक PKCE क्लाइंट्स के लिए ऑप्शनल है, लेकिन इसे रिसीव करने में कोई नुकसान नहीं)।
PKCE पेयर जनरेट करें
एक रैंडम 43–128 कैरेक्टर का code_verifier जनरेट करें, फिर code_challenge = BASE64URL(SHA256(code_verifier)) कैलकुलेट करें। verifier को स्टेप 4 के लिए लोकली स्टोर रखें।
ब्राउज़र में /oauth/authorize खोलें
यूज़र को /oauth/authorize?response_type=code&client_id=...&redirect_uri=...&state=...&code_challenge=...&code_challenge_method=S256 पर रीडायरेक्ट करें। सर्वर एक QR कोड दिखाता है; यूज़र उसे Telegram ऐप में स्कैन करके प्रमाणीकरण करता है।
authorization code प्राप्त करें
QR स्कैन के बाद, सर्वर आपके redirect_uri पर ?code=...&state=... के साथ रीडायरेक्ट करता है। वेरिफाई करें कि state पैरामीटर वही है जो आपने भेजा था।
code को token से बदलें
POST /oauth/token पर grant_type=authorization_code, code, redirect_uri, code_verifier, client_id भेजें। आपको access_token मिलेगा (10-साल का TTL — नीचे Token Lifetime देखें) और एक refresh_token। /mcp रिक्वेस्ट्स पर access_token को Authorization: Bearer ... की तरह इस्तेमाल करें।
redirect_uri मैचिंग के नियम
हम RFC 8252 §7.3 और §8.4 का सख्ती से पालन करते हैं। मैचिंग अल्गोरिदम इस पर निर्भर करता है कि रजिस्टर किया गया URI loopback IP लिटरल है या नहीं।
Loopback (http://127.0.0.1 या http://[::1])
अगर आपने loopback URI रजिस्टर किया है, तो authorize के समय redirect_uri का scheme, host, path और query बिल्कुल मैच होना चाहिए — लेकिन पोर्ट अलग हो सकता है। यह RFC 8252 §7.3 के अनुसार आवश्यक है क्योंकि नेटिव क्लाइंट्स OS-असाइन्ड एफ़ेमेरल पोर्ट को बाइंड करते हैं जो हर रन के बीच बदल सकता है।
- रजिस्टर्ड http://127.0.0.1:36201/callback authorize-time http://127.0.0.1:50000/callback से मैच करता है ✅
- रजिस्टर्ड http://127.0.0.1:36201/callback http://127.0.0.1:50000/different-path से मैच नहीं करता — path बिल्कुल सही होना चाहिए
- रजिस्टर्ड http://[::1]:36201/cb http://127.0.0.1:36201/cb से मैच नहीं करता — IPv4 और IPv6 loopback अलग-अलग आइडेंटिफायर हैं
HTTPS (https://your-domain.example/...)
बाइट-दर-बाइट सटीक मैच आवश्यक है, जिसमें path, query और पोर्ट शामिल हैं (RFC 6749 §3.1.2)। कोई फ्लेक्सिबिलिटी नहीं।
localhost (अनुशंसित नहीं)
हम http://localhost को एक सामान्य hostname मानते हैं — सटीक मैच आवश्यक है, पोर्ट में कोई फ्लेक्सिबिलिटी नहीं। RFC 8252 §8.3 localhost के बजाय IP लिटरल्स (127.0.0.1 / [::1]) उपयोग करने की सलाह देता है क्योंकि DNS रिज़ोल्यूशन इम्प्लीमेंटेशन पर निर्भर करता है।
सामान्य एरर्स
टेस्ट किए गए क्लाइंट्स
हमारे सर्वर के साथ इंटरऑपरेट करने की पुष्टि हो चुकी है। अगर आप कुछ नया बनाते हैं और वह काम करता है, तो हमें PR भेजें ताकि इसे यहाँ जोड़ा जा सके।
एक ही OAuth कनेक्शन पर कई Telegram खाते
v2.32.0 से एक ही OAuth कनेक्शन कई Telegram पहचानों को रख सकता है और एक टूल कॉल से उनके बीच स्विच कर सकता है — कोई Disconnect/Connect चक्र नहीं, कोई नया क्लाइंट पंजीकरण नहीं।
जुड़े खातों की सूची देखें
telegram-accounts-list को कॉल करें। आप अपना primary (OAuth-बद्ध) खाता देखेंगे जो सक्रिय होने पर ⭐ से चिह्नित होगा, साथ ही आपने जोड़े गए कोई भी द्वितीयक खाते भी।
एक और खाता जोड़ें
एक वैकल्पिक लेबल (जैसे "testing") के साथ telegram-accounts-add को कॉल करें। टूल एक एक-बार उपयोग वाला URL लौटाता है (TTL 10 मिनट) — इसे किसी भी डिवाइस पर खोलें और जिस Telegram खाते को जोड़ना चाहते हैं उसके साथ QR स्कैन करें।
सक्रिय खाता बदलें
identifier=label, @username, account_id या 'primary' के साथ telegram-accounts-switch को कॉल करें। अगला telegram-* टूल कॉल तुरंत उस खाते का उपयोग करेगा। कोई पुनः-कनेक्ट नहीं।
एक द्वितीयक खाता हटाएँ
किसी द्वितीयक खाते पर telegram-accounts-remove identifier=… को कॉल करें। Telegram खाता स्वयं लॉग आउट नहीं होता — केवल यहाँ की बाइंडिंग हटती है। primary को इस तरह नहीं हटाया जा सकता; पूर्ण रूप से साइन आउट करने के लिए अपने क्लाइंट के Disconnect फ़्लो का उपयोग करें।
प्रत्येक OAuth कनेक्शन अलग-थलग है: आप Hermes के माध्यम से जो खाते जोड़ते हैं वे Claude.ai या ChatGPT को दिखाई नहीं देते, भले ही यह वही Telegram पहचान हो। विभिन्न खातों को विभिन्न MCP क्लाइंट्स से जोड़ने के लिए, प्रत्येक क्लाइंट को अलग से पंजीकृत करें और उसके अपने सत्र के भीतर telegram-accounts-add का उपयोग करें।