لماذا PKCE لـ MCP عندما لا يكون الوكلاء متصفحات؟

يقوم PKCE (مفتاح إثبات تبادل التعليمات البرمجية) بربط رمز التفويض بسر تشفير لمرة واحدة لا يعرفه إلا العميل البادئ. في سياق MCP، لا يعد المهاجم امتدادًا ضارًا للمتصفح؛ إنه عميل مارق أو رمز ترخيص مسروق يطفو في سجل المحطة الطرفية. يعني PKCE أنه لا يمكن استرداد الرمز الذي تم اعتراضه بدون أداة التحقق من الرمز الأصلي. يتطلب OAuth 2.1 PKCE لكل تدفق رمز الترخيص، بما في ذلك العملاء السريين، لذلك يتبع MCP المواصفات فقط.

ما هي وثيقة بيانات تعريف الموارد المحمية؟

مستند PRM هو ملف JSON يتم تقديمه على /.well-known/oauth-protected-resource والذي يخبر عملاء OAuth بمكان وجود خادم التفويض، والنطاق الذي يقبله المورد، ومعرف المورد الذي يجب وضعه في مطالبة aud. أضافت مواصفات ترخيص MCP PRM حتى يكتشف عميل MCP إعداد المصادقة الخاص بك دون تكوين خارج النطاق. يقوم العميل بإحضار PRM، ويتبع عنوان URL لـ Authorization_servers إلى البيانات التعريفية AS، ويقوم بتشغيل رقصة OAuth، ويصل إلى خادم MCP الخاص بك باستخدام رمز حامل صالح.

هل أحتاج إلى تسجيل عميل ديناميكي؟

بالنسبة لخوادم MCP العامة المعرضة للعديد من العملاء، نعم. يتيح تسجيل العميل الديناميكي (RFC 7591) لعميل MCP التسجيل الذاتي على خادم الترخيص الخاص بك، واستلام معرف العميل، وبدء تدفق OAuth في رحلة ذهابًا وإيابًا واحدة. وبدون ذلك، يتعين على كل مستخدم إنشاء تطبيق يدويًا في لوحة التحكم الخاصة بك قبل أن يتمكن من توصيل Claude أو Cursor. بالنسبة لعمليات التكامل الداخلية أو المدرجة في القائمة المسموح بها، لا يزال معرف العميل المتوفر مسبقًا يعمل.

أين يعيش الرمز المميز لحامله أثناء الجلسة؟

في رأس التفويض لكل طلب MCP. HTTP القابل للتدفق يجعل هذا الأمر نظيفًا؛ يحمل كل طلب الرمز المميز، ويقوم خادمك بالتحقق منه في البرامج الوسيطة قبل إرسال استدعاء الأداة. تعمل رموز الوصول قصيرة العمر (من 5 إلى 60 دقيقة) مع رموز التحديث التي يحتفظ بها العميل على تقليل نصف قطر الانفجار من سطر السجل المسرب. لا تقم أبدًا بتضمين الرمز المميز في عنوان URL؛ تقوم السجلات والوكلاء بالتقاط عناوين URL بشكل روتيني.

كيف يمكن مقارنة نطاقات أداة MCP بنطاقات OAuth؟

يعتمد MCP على التفويض المستند إلى الدور: يحمل الرمز المميز نطاقات مثل الأدوات: القراءة، أو الأدوات: الاستدعاء: الآمن، أو الأدوات: الاستدعاء: تدميري، وتعلن التعليقات التوضيحية للأداة الفردية عن النطاقات التي تتطلبها. تقوم النطاقات بتعيين واحد لواحد لنطاقات OAuth، بحيث يمكنك استخدام نفس تصميم النطاق الذي لديك بالفعل لواجهة برمجة تطبيقات REST. القطعة الجديدة عبارة عن تعليقات توضيحية على مستوى الأداة على جانب MCP؛ يجعلون قرار الترخيص مرئيًا في سجل الأداة، وليس فقط في رمز المعالج.

Tutorial

MCP OAuth 2.1 مع PKCE: قم بتأمين خادم الوكيل الخاص بك في 7 خطوات

15 أبريل 2026 | 9 min read

مواصفات 15-03-2026 MCP تجعل OAuth 2.1 + PKCE هو معيار الترخيص لخوادم الوكيل. سبع خطوات للشحن: بيانات تعريف PRM، وتسجيل العميل الديناميكي، وتصميم النطاق، والتحقق من صحة الرمز المميز باستخدام التعليمات البرمجية.

Padlock representing OAuth 2.1 authorization for MCP servers — Photo by FLY:D on Unsplash

تعمل مواصفات 15-03-2026 MCP على تأمين OAuth 2.1 مع PKCE كمعيار ترخيص لـ خوادم MCP البعيدة. مفاتيح API في متغيرات البيئة لا تزال تعمل في اليوم الأول، ولكن التسجيل، يفضل كل من Claude Desktop وCursor وVS Code Copilot وWindsurf الخوادم المدعومة بـ OAuth عندما يكون المستخدمون تصفح عمليات التكامل. إذا كان الخادم الخاص بك لا يزال يطلب حاملًا طويل الأمد في ملف التكوين، فإنك نترك جزءًا من التوزيع على الطاولة.

الجزء الصعب ليس OAuth نفسه؛ إنها المواصفات الخمس الصغيرة التي يتكون منها تدفق مصادقة MCP معًا: OAuth 2.1 (RFC 9700)، PKCE (RFC 7636)، تسجيل العميل الديناميكي (RFC 7591)، مؤشرات الموارد (RFC 8707)، وبيانات تعريف الموارد المحمية. كل واحدة صغيرة. الأسلاك هو المكان الذي تتعثر فيه الفرق. هنا هو الطريق، بالترتيب.

الخطوة 1: تقديم مستند بيانات تعريف الموارد المحمية

يخبر ملف PRM العملاء بمكان وجود خادم التفويض الخاص بك، والنطاقات التي تقبلها، وماذا معرف المورد لوضعه في aud مطالبة. استضافته في /.well-known/oauth-protected-resource على نفس أصل نقطة نهاية MCP الخاصة بك:

ال authorization_servers القائمة هي قفزة الاكتشاف. يقوم العملاء بإحضار PRM الخاص بك، اتبع الإدخال الأول لمستند بيانات تعريف AS، وقم بإنشاء عنوان URL للتفويض من هناك. احتفظ بالقائمة لإدخال واحد ما لم تقم بتشغيل اتحاد؛ العديد من المصدرين يربكون العميل و لا شيء في المواصفات يتطلب ذلك.

الخطوة 2: نشر البيانات التعريفية لخادم التفويض

يقدم موفر الهوية الخاص بك (Auth0، أو Okta، أو Clerk، أو Cloudflare Access، أو Hydra المستضافة ذاتيًا) البيانات الوصفية AS في /.well-known/oauth-authorization-server. يستهلكه عملاء MCP للتعرف على نقاط نهاية التفويض والرمز المميز، وأنواع المنح المدعومة، وموقع JWKS للتحقق من الرمز المميز:

ثلاثة مجالات تتطلب المواصفات: code_challenge_methods_supported يجب أن تشمل S256; grant_types_supported يجب أن تشمل authorization_code و refresh_token; registration_endpoint يجب أن يكون موجودًا إذا كنت تدعم العملاء الديناميكيين. افتقد أي واحد وسيقوم Claude Desktop بوضع علامة على الخادم باعتباره غير متوافق أثناء الإعداد.

الخطوة 3: إنشاء زوج PKCE على العميل

يتكون PKCE من 20 سطرًا من كود العميل ويقتل فئة اعتراض كود التفويض هجوم. أنشئ 32 بايت عشوائيًا، وقم بتشفيرها base64url في أداة التحقق، وSHA-256 أداة التحقق في التحدي، وأرسل التحدي مع طلب التفويض:

ال resource المعلمة (RFC 8707) هي المعلمة التي تفوتها معظم التطبيقات. بدون يمكن إعادة تشغيل الرمز المميز الذي تم سكه لخادم MCP الخاص بك مقابل أي واجهة برمجة تطبيقات أخرى تثق في نفس المصدر؛ معها، aud المطالبة بتثبيت الرمز المميز في معرف المورد الخاص بك ولا يقبله أي شيء آخر.

الخطوة 4: استبدال الرمز بالرموز المميزة

بعد إعادة التوجيه مرة أخرى، يقوم العميل بنشر الرمز بالإضافة إلى أداة التحقق الأصلية إلى الرمز المميز نقطة النهاية. يقوم خادم التفويض بإعادة حساب SHA-256 الخاص بأداة التحقق ومقارنتها التحدي المخزن؛ إذا تطابقت، فستحصل على رمز وصول:

قم بتخزين رمز التحديث في وحدة تخزين آمنة (Keychain، Windows Credential Manager، Linux libsecret) وقم بإسقاط أداة التحقق من مخزن الجلسة بمجرد نجاح التبادل. الوصول الرموز تعيش من 5 إلى 60 دقيقة؛ تعيش الرموز المميزة للتحديث لفترة أطول ولكن يجب أن يتم تدويرها عند الاستخدام.

الخطوة 5: التحقق من الرمز المميز لحامله في كل طلب MCP

HTTP القابل للتدفق يجعل التحقق من الرمز المميز أمرًا بسيطًا: كل طلب HTTP يحمل ملف Authorization header، لذا يتحقق خادم MCP من ذلك في البرامج الوسيطة من قبل إرسال استدعاء الأداة. قم بإحضار JWKS مرة واحدة، وقم بتخزينه مؤقتًا، والتحقق من صحة جهة الإصدار والجمهور و انتهاء الصلاحية في كل مكالمة:

الادعاءات الثلاثة التي تكتشف الأخطاء الحقيقية: iss دبابيس المصدر. aud تثبيت المورد (يمنع إعادة التشغيل عبر الموارد)؛ exp يمسك الرموز التي لا معنى لها. لا تقبل الرموز بدون هذه؛ "لقد قمت بالتحقق من صحة التوقيع" ليس هو نفسه "لقد قمت بالتحقق من صحة الادعاءات."

الخطوة 6: ضع كل أداة على النطاقات التي تعلن عنها التعليقات التوضيحية الخاصة بها

يمنحك تصميم النطاق الناقص OAuth 2.1 وصولاً ثنائيًا: إما أن يتمكن العميل من الاتصال بكل أداة أو لا شيء. يقوم نظام التعليقات التوضيحية MCP بإغلاق هذه الفجوة عن طريق السماح لكل أداة بالإعلان عن نطاقاتها الاحتياجات. يقرأ المعالج التعليقات التوضيحية ونطاقات الرمز المميز في وقت الاستدعاء:

أبقِ النطاقات المدمرة ونطاقات القراءة فقط منفصلة. المستخدم الذي منح tools:read ل تشغيل التقرير الأسبوعي لا ينبغي أن يكون قادرا على التشغيل send_email من نفس المنوال. طلب كلود سطح المكتب وسطح المؤشر النطاقات في شاشة الموافقة، لذلك يحدث الانقسام تجربة المستخدم صادقة بشأن ما يمكن للعميل القيام به.

الخطوة 7: دعم تسجيل العميل الديناميكي

يتيح تسجيل العميل الديناميكي لعميل MCP التسجيل الذاتي على خادم الترخيص الخاص بك دون أن يملأ الإنسان استمارة. يقوم المؤشر أو Claude Desktop POSTs بإرسال طلب تسجيل، يتلقى أ client_id، ويقوم بتشغيل تدفق OAuth على الفور:

هذه هي القطعة التي تنقل خادم MCP الخاص بك من "لصق مفتاح API في ملف التكوين" إلى "انقر فوق "الاتصال في المؤشر" ومنح حق الوصول." يستحق العمل إذا كان الخادم الخاص بك عامًا؛ قابل للتخطي إذا كنت تقوم بالشحن فقط إلى مجموعة صغيرة من العملاء المعروفين.

التحقق من التدفق الكامل من النهاية إلى النهاية

بمجرد وضع القطع في مكانها الصحيح، يبدو استدعاء أداة MCP الكامل مثل أي حامل آخر تم المصادقة عليه طلب HTTP:

إذا رأيت 401 مع WWW-Authenticate: Bearer resource_metadata="...", يعرف العميل مكان اكتشاف إعداد المصادقة الخاص بك وإعادة تشغيل التدفق. هذا الرأس هو المصافحة التي تجعل تحديث الرمز المميز الصامت وإعادة الاتصال ممكنًا بعد الإلغاء.

ضع عنوان URL الخاص بـ PRM في ملف WWW-Authenticate رأس على كل 401 استجابة. العملية التشاورية المتعددة الأطراف المواصفات تجعل هذا تلميح الاكتشاف الأساسي؛ العملاء الذين يرون تراجعًا غير مشروح 401 لمطالبة المستخدم بمفتاح واجهة برمجة التطبيقات (API)، وهو بالضبط التدفق الذي يحاول OAuth 2.1 استبداله.

ورقة الغش في تصميم النطاق

نِطَاق	يغطي	المنحة الافتراضية
`tools:read`	قائمة الأدوات المتاحة، وقراءة الأوصاف	تُمنح دائمًا عند الموافقة
`tools:invoke:safe`	استدعاءات أداة غير فعالة للقراءة فقط (عمليات البحث والتحليل)	تمنح لكل موافقة المستخدم
`tools:invoke:destructive`	تغيير مكالمات الأداة (إرسال بريد إلكتروني، إنشاء طلب)	يتطلب موافقة صريحة لكل جلسة
`resources:read`	الوصول للقراءة فقط إلى الموارد المكشوفة	ممنوحة لكل نمط الموارد
`prompts:read`	سرد وقراءة المطالبات المحددة من قبل الخادم	منحت عند الموافقة

الوجبات السريعة الرئيسية

يتطلب OAuth 2.1 PKCE. ليس من الجميل أن يكون لديك. كل تدفق رمز المصادقة يحمل التحقق والتحدي أو فشل في الامتثال للمواصفات.
بي آر إم في /.well-known/oauth-protected-resource هي نقطة الدخول. يكتشف العملاء إعداد المصادقة الخاص بك من عنوان URL هذا؛ تخطيها ولا يمكن للعملاء التكوين التلقائي.
استخدم resource المعلمة (RFC 8707). تثبيت جمهور الرمز المميز إلى خادم MCP الخاص بك حتى لا يمكن إعادة تشغيل الرمز المميز المسرب مقابل واجهات برمجة التطبيقات الأخرى.
التحقق من صحة المصدر والجمهور وانتهاء الصلاحية والنطاق. الشيكات التوقيع وحدها السماح إعادة التشغيل عبر الموارد من خلال.
تقسيم النطاقات المدمرة. tools:read, tools:invoke:safe، و tools:invoke:destructive منح المستخدمين موافقة UX التي يتوقعونها من أذونات نظام التشغيل.
يؤدي تسجيل العميل الديناميكي إلى فتح عمليات التثبيت بدون تكوين. دفع تكلفة التنفيذ مرة واحدة؛ يستفيد كل عميل MCP جديد إلى الأبد.

خادم MCP المستضاف من Botoi على api.botoi.com/mcp يعمل بنفس النمط. تصفح مستندات إعداد MCP لتكوينات Claude Desktop وClaude Code وCursor وVS Code وWindsurf. لتوقيع JWT والتحقق من استخدامات البرامج الوسيطة المذكورة أعلاه، راجع نقاط نهاية JWT API في المستندات التفاعلية.

FAQ

لماذا PKCE لـ MCP عندما لا يكون الوكلاء متصفحات؟: يقوم PKCE (مفتاح إثبات تبادل التعليمات البرمجية) بربط رمز التفويض بسر تشفير لمرة واحدة لا يعرفه إلا العميل البادئ. في سياق MCP، لا يعد المهاجم امتدادًا ضارًا للمتصفح؛ إنه عميل مارق أو رمز ترخيص مسروق يطفو في سجل المحطة الطرفية. يعني PKCE أنه لا يمكن استرداد الرمز الذي تم اعتراضه بدون أداة التحقق من الرمز الأصلي. يتطلب OAuth 2.1 PKCE لكل تدفق رمز الترخيص، بما في ذلك العملاء السريين، لذلك يتبع MCP المواصفات فقط.
ما هي وثيقة بيانات تعريف الموارد المحمية؟: مستند PRM هو ملف JSON يتم تقديمه على /.well-known/oauth-protected-resource والذي يخبر عملاء OAuth بمكان وجود خادم التفويض، والنطاق الذي يقبله المورد، ومعرف المورد الذي يجب وضعه في مطالبة aud. أضافت مواصفات ترخيص MCP PRM حتى يكتشف عميل MCP إعداد المصادقة الخاص بك دون تكوين خارج النطاق. يقوم العميل بإحضار PRM، ويتبع عنوان URL لـ Authorization_servers إلى البيانات التعريفية AS، ويقوم بتشغيل رقصة OAuth، ويصل إلى خادم MCP الخاص بك باستخدام رمز حامل صالح.
هل أحتاج إلى تسجيل عميل ديناميكي؟: بالنسبة لخوادم MCP العامة المعرضة للعديد من العملاء، نعم. يتيح تسجيل العميل الديناميكي (RFC 7591) لعميل MCP التسجيل الذاتي على خادم الترخيص الخاص بك، واستلام معرف العميل، وبدء تدفق OAuth في رحلة ذهابًا وإيابًا واحدة. وبدون ذلك، يتعين على كل مستخدم إنشاء تطبيق يدويًا في لوحة التحكم الخاصة بك قبل أن يتمكن من توصيل Claude أو Cursor. بالنسبة لعمليات التكامل الداخلية أو المدرجة في القائمة المسموح بها، لا يزال معرف العميل المتوفر مسبقًا يعمل.
أين يعيش الرمز المميز لحامله أثناء الجلسة؟: في رأس التفويض لكل طلب MCP. HTTP القابل للتدفق يجعل هذا الأمر نظيفًا؛ يحمل كل طلب الرمز المميز، ويقوم خادمك بالتحقق منه في البرامج الوسيطة قبل إرسال استدعاء الأداة. تعمل رموز الوصول قصيرة العمر (من 5 إلى 60 دقيقة) مع رموز التحديث التي يحتفظ بها العميل على تقليل نصف قطر الانفجار من سطر السجل المسرب. لا تقم أبدًا بتضمين الرمز المميز في عنوان URL؛ تقوم السجلات والوكلاء بالتقاط عناوين URL بشكل روتيني.
كيف يمكن مقارنة نطاقات أداة MCP بنطاقات OAuth؟: يعتمد MCP على التفويض المستند إلى الدور: يحمل الرمز المميز نطاقات مثل الأدوات: القراءة، أو الأدوات: الاستدعاء: الآمن، أو الأدوات: الاستدعاء: تدميري، وتعلن التعليقات التوضيحية للأداة الفردية عن النطاقات التي تتطلبها. تقوم النطاقات بتعيين واحد لواحد لنطاقات OAuth، بحيث يمكنك استخدام نفس تصميم النطاق الذي لديك بالفعل لواجهة برمجة تطبيقات REST. القطعة الجديدة عبارة عن تعليقات توضيحية على مستوى الأداة على جانب MCP؛ يجعلون قرار الترخيص مرئيًا في سجل الأداة، وليس فقط في رمز المعالج.

ابدأ البناء مع botoi

أكثر من 150 نقطة نهاية API للبحث ومعالجة النصوص وتوليد الصور وأدوات المطورين. باقة مجانية، بدون بطاقة ائتمان.

عرض وثائق API تصفح جميع الأدوات