कस्टम MCP क्लाइंट्स के लिए OAuth

अगर आप अपना खुद का MCP क्लाइंट (CLI, SDK, IDE प्लगइन) बना रहे हैं, तो यह पेज हमारे OAuth इम्प्लीमेंटेशन का वर्णन करता है: कौन-से स्टैंडर्ड्स हम सपोर्ट करते हैं, एंडपॉइंट्स, redirect_uri के नियम, और सामान्य एरर्स को कैसे डीबग करें। Claude.ai और ChatGPT यूज़र्स को इस पेज की ज़रूरत नहीं है — उसकी जगह Quickstart देखें।

हम जो स्टैंडर्ड्स इम्प्लीमेंट करते हैं

mcp-telegram.com उन सभी OAuth स्पेसिफिकेशन्स के साथ पूरी तरह संगत है जिन पर MCP इकोसिस्टम निर्भर करता है — कोई प्रोप्राइटरी एक्सटेंशन नहीं, और क्लाइंट्स में कोई शेयर्ड सीक्रेट हार्डकोडेड नहीं।

RFC 6749 — OAuth 2.0 Authorization Framework — refresh token के साथ बेस authorization code grant
RFC 7591 — Dynamic Client Registration — कोई भी क्लाइंट बिना पूर्व समन्वय के /oauth/register पर खुद को रजिस्टर कर सकता है
RFC 7636 — PKCE (Proof Key for Code Exchange) — पब्लिक क्लाइंट्स के लिए S256 challenge ज़रूरी है
RFC 8252 — OAuth 2.0 for Native Apps — एफ़ेमेरल पोर्ट की फ्लेक्सिबिलिटी के साथ loopback IP redirect URI
RFC 8414 — OAuth 2.0 Authorization Server Metadata — डिस्कवरी दस्तावेज़ /.well-known/oauth-authorization-server पर
RFC 9728 — OAuth 2.0 Protected Resource Metadata — MCP रिसोर्स बाउंड्री की डिस्कवरी

एंडपॉइंट्स

Authorization सर्वर मेटाडेटा (RFC 8414)

डायनेमिक क्लाइंट रजिस्ट्रेशन (RFC 7591)

Authorization एंडपॉइंट

Token एंडपॉइंट

MCP रिसोर्स (Streamable HTTP)

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 रिज़ोल्यूशन इम्प्लीमेंटेशन पर निर्भर करता है।

PKCE अनिवार्य है

हर authorize रिक्वेस्ट पर code_challenge_method=S256 आवश्यक है। Plain मेथड अस्वीकार किया जाता है। अगर आप code_challenge को पूरी तरह छोड़ देते हैं, तो /token एक्सचेंज code_verifier वैलिडेशन पर फेल हो जाएगा।

Token का जीवनकाल

access_token का TTL जान-बूझकर लंबा (10 साल) रखा गया है क्योंकि कुछ MCP क्लाइंट्स refresh_token को विश्वसनीय तरीके से सेव नहीं करते। फिर भी एक refresh_token जारी किया जाता है और हर refresh पर रोटेट होता है (RFC 6819 §5.2.2.3)। यूज़र /my/sessions पर या Telegram से लॉग आउट करके किसी भी समय सभी टोकन रिवोक कर सकता है। यूज़र स्पष्ट रूप से /oauth/revoke (RFC 7009) पर POST करके भी सेशन समाप्त कर सकता है।

सामान्य एरर्स

/oauth/authorize पर HTTP 400 «Invalid redirect_uri»

redirect_uri क्वेरी पैरामीटर इस client_id के लिए रजिस्टर किए गए किसी URI से मैच नहीं कर रहा। loopback क्लाइंट्स के लिए: चेक करें कि scheme + host + path + query बिल्कुल मैच कर रहे हैं (केवल पोर्ट फ्लेक्सिबल है)। HTTPS क्लाइंट्स के लिए: पूरी बाइट-समानता आवश्यक है — ट्रेलिंग स्लैश और URL-एनकोडिंग के अंतर पर ध्यान दें।

HTTP 400 «Unknown client»

client_id हमारे डेटाबेस में मौजूद नहीं है। या तो आपने /oauth/register स्टेप छोड़ दिया, या client_id सेव करने से पहले रजिस्ट्रेशन रिस्पॉन्स खो गया, या यूज़र ने /my/clients के ज़रिए क्लाइंट को रिवोक कर दिया।

क्लाइंट बार-बार «Needs Auth» दिखा रहा है

अगर आपका क्लाइंट access_token सेव करता है लेकिन refresh_token नहीं, तो जब access_token एक्सपायर होगा तो आपको यह दिखेगा। हमारे access tokens का TTL 10 साल है खास तौर पर इसी को कम करने के लिए, लेकिन अगर आपका क्लाइंट टोकन्स को क्लाइंट-साइड पर किसी छोटी विंडो के बाद एक्सपायर कर देता है, तो आपको या तो refresh_token सेव करना होगा या ज़रूरत पर /oauth/revoke + दोबारा auth कॉल करना होगा।

टेस्ट किए गए क्लाइंट्स

हमारे सर्वर के साथ इंटरऑपरेट करने की पुष्टि हो चुकी है। अगर आप कुछ नया बनाते हैं और वह काम करता है, तो हमें PR भेजें ताकि इसे यहाँ जोड़ा जा सके।

Claude.ai web — बिल्ट-इन MCP connector के ज़रिए
ChatGPT Apps — बिल्ट-इन MCP connector के ज़रिए
Hermes Agent — ओपन-सोर्स CLI MCP क्लाइंट (RFC 8252 loopback flow)
Cursor MCP — IDE प्लगइन (RFC 8252 loopback flow)
कोई भी RFC 6749 + RFC 7591 + RFC 7636 + RFC 8252 के अनुरूप क्लाइंट हमारी तरफ से बिना किसी कोड परिवर्तन के काम करना चाहिए।

एक ही 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 का उपयोग करें।