OAuth لعملاء MCP المخصّصين

إذا كنت تبني عميل MCP خاصاً بك (CLI أو SDK أو إضافة IDE)، فهذه الصفحة تشرح تطبيقنا لـ OAuth: المعايير التي ندعمها، نقاط النهاية، قواعد redirect_uri، وكيفية تشخيص الأخطاء الشائعة. مستخدمو Claude.ai و ChatGPT لا يحتاجون هذه الصفحة — استخدم البدء السريع بدلاً منها.

المعايير التي نطبّقها

موقع mcp-telegram.com متوافق تماماً مع مواصفات OAuth التي تعتمد عليها منظومة MCP — دون أي امتدادات خاصة، ودون أسرار مشتركة مدمجة داخل العملاء.

RFC 6749 — OAuth 2.0 Authorization Framework — منح authorization code الأساسي مع refresh tokens
RFC 7591 — Dynamic Client Registration — أي عميل يمكنه تسجيل نفسه عبر /oauth/register دون تنسيق مسبق
RFC 7636 — PKCE (Proof Key for Code Exchange) — يُشترط تحدّي S256 للعملاء العموميين
RFC 8252 — OAuth 2.0 for Native Apps — عناوين redirect URI من نوع loopback IP مع مرونة في المنفذ المؤقت
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)

تدفّق authorization code مع PKCE

تدفّق قياسي وفق 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 (السرّ اختياري للعملاء العموميين الذين يستخدمون PKCE، لكن لا ضرر من استلامه).

ولّد زوج PKCE

ولّد code_verifier عشوائياً بطول 43–128 حرفاً، ثم احسب 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 (TTL لمدة 10 سنوات — راجع قسم عمر الـ Token أدناه) و refresh_token. استخدم access_token عبر الترويسة Authorization: Bearer ... في طلبات /mcp.

قواعد مطابقة redirect_uri

نتبع RFC 8252 §7.3 و §8.4 بصرامة. تعتمد خوارزمية المطابقة على ما إذا كان عنوان URI المسجَّل هو عنوان loopback IP حرفي.

Loopback (http://127.0.0.1 أو http://[::1])

إذا سجّلت عنوان URI من نوع loopback، فإن redirect_uri أثناء التفويض يجب أن يطابق الـ scheme والـ host والـ path والـ query تماماً — لكن المنفذ يمكن أن يختلف. هذا مطلوب بموجب RFC 8252 §7.3 لأن العملاء الأصليين يربطون منفذاً مؤقتاً يخصّصه نظام التشغيل وقد يتغيّر بين كل تشغيل وآخر.

العنوان المسجَّل http://127.0.0.1:36201/callback يطابق وقت التفويض 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 — loopback لـ IPv4 و IPv6 معرّفان مختلفان

HTTPS (https://your-domain.example/...)

مطابقة بايت ببايت مطلوبة، بما في ذلك path و query والمنفذ (RFC 6749 §3.1.2). لا توجد أي مرونة.

localhost (غير مُستحسن)

نتعامل مع http://localhost كاسم مضيف عادي — مطابقة تامّة مطلوبة، ولا مرونة في المنفذ. توصي RFC 8252 §8.3 باستخدام عناوين IP الحرفية (127.0.0.1 / [::1]) بدلاً من localhost لأن حلّ DNS يعتمد على التنفيذ.

PKCE إلزامي

يجب تمرير code_challenge_method=S256 في كل طلب authorize. الطريقة Plain مرفوضة. وإذا حذفت code_challenge كلياً، فسيفشل التبادل على /token عند التحقّق من code_verifier.

عمر الـ Token

تم تعيين TTL لـ access_token طويلاً عمداً (10 سنوات) لأن بعض عملاء MCP لا يحفظون refresh_token بشكل موثوق. مع ذلك يتم إصدار refresh_token وتدويره عند كل تحديث (RFC 6819 §5.2.2.3). يمكن للمستخدم إلغاء جميع الـ tokens في أي وقت من /my/sessions أو عبر تسجيل الخروج من Telegram. كما يمكنه إرسال POST صريح إلى /oauth/revoke (RFC 7009) لإنهاء الجلسة.

الأخطاء الشائعة

HTTP 400 «Invalid redirect_uri» على /oauth/authorize

معامل redirect_uri لا يطابق أيّاً من عناوين URI المسجَّلة لهذا client_id. لعملاء 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. لقد جعلنا TTL لـ access tokens لدينا 10 سنوات تحديداً للتخفيف من هذا، لكن إذا كان عميلك يُنهي صلاحية الـ token من جانبه بعد فترة أقصر، فعليك إمّا حفظ refresh_token، أو استدعاء /oauth/revoke وإعادة المصادقة عند الحاجة.

عملاء تم اختبارهم

تم التأكّد من توافقهم مع خادمنا. إذا بنيت شيئاً جديداً ونجح، أرسل لنا PR لإضافته هنا.

Claude.ai web — عبر MCP connector المدمج
ChatGPT Apps — عبر MCP connector المدمج
Hermes Agent — عميل MCP مفتوح المصدر يعمل من CLI (تدفّق loopback وفق RFC 8252)
Cursor MCP — إضافة IDE (تدفّق loopback وفق RFC 8252)
أي عميل متوافق مع RFC 6749 + RFC 7591 + RFC 7636 + RFC 8252 ينبغي أن يعمل دون أي تعديلات في الكود من جانبنا.

حسابات Telegram متعددة على اتصال OAuth واحد

اعتباراً من الإصدار v2.32.0، يمكن لاتصال OAuth واحد أن يحمل عدة هويات Telegram والتبديل بينها باستدعاء أداة واحد — دون دورة Disconnect/Connect ودون تسجيل عميل جديد.

اعرض الحسابات المرتبطة

استدعِ telegram-accounts-list. سترى حسابك الـ primary المرتبط بـ OAuth مُعلَّماً بـ ⭐ إن كان نشطاً، إضافةً إلى أي حسابات ثانوية أضفتها.

اربط حساباً آخر

استدعِ telegram-accounts-add مع تسمية اختيارية (مثل "testing"). تُعيد الأداة عنوان URL لمرة واحدة (مدة الصلاحية 10 دقائق) — افتحه على أي جهاز وامسح رمز QR بحساب Telegram الذي تريد إضافته.

بدّل الحساب النشط

استدعِ telegram-accounts-switch مع identifier=label أو @username أو account_id أو 'primary'. سيستخدم استدعاء أداة telegram-* التالي ذلك الحساب فوراً. دون إعادة اتصال.

افصل حساباً ثانوياً

استدعِ telegram-accounts-remove identifier=… على حساب ثانوي. لن يتم تسجيل خروج حساب Telegram نفسه — فقط الربط هنا يُفصل. لا يمكن إزالة الـ primary بهذه الطريقة؛ استخدم تدفّق Disconnect الخاص بعميلك لتسجيل الخروج الكامل.

كل اتصال OAuth معزول تماماً: الحسابات التي تربطها عبر Hermes غير مرئية لـ Claude.ai أو ChatGPT، حتى وإن كانت هويّة Telegram ذاتها. لربط حسابات مختلفة بعملاء MCP مختلفين، سجّل كل عميل بشكل منفصل واستخدم telegram-accounts-add داخل جلسته الخاصة.