كشف واجهة برمجة تطبيقات REST في APIM كخادم MCP

ينطبق على: المطور | أساسي | الإصدار 2 الأساسي | قياسي | الإصدار 2 القياسي | Premium | Premium v2

في إدارة واجهات برمجة التطبيقات، يمكنك عرض واجهة برمجة تطبيقات REST مدارة في إدارة واجهة برمجة التطبيقات كخادم بروتوكول سياق النموذج (MCP) عن بعد باستخدام بوابة الذكاء الاصطناعي المدمجة الخاصة بها. كشف واحدة أو أكثر من عمليات واجهة برمجة التطبيقات كأدوات يمكن لعملاء MCP استدعاؤها باستخدام بروتوكول MCP.

يدعم إدارة Azure API أيضا التكامل الآمن مع خوادم MCP المتوافقة حاليا - خوادم أدوات مستضافة خارج إدارة API. لمزيد من المعلومات، راجع عرض خادم MCP موجود.

تعرف على المزيد حول:

• دعم خادم MCP في إدارة واجهة برمجة التطبيقات
• قدرات بوابة الذكاء الاصطناعي

القيود

• بالنسبة لخوادم MCP المعرضة في إدارة واجهات برمجة التطبيقات من واجهات برمجة التطبيقات REST المدارة، تدعم إدارة API حاليا أدوات خوادم MCP، لكنها لا تدعم موارد أو أوامر MCP.
• إدارة واجهة برمجة التطبيقات حاليا لا تدعم قدرات خوادم MCP في مساحات العمل.

المتطلبات الأساسية

• إذا لم يكن لديك بالفعل مثيل لإدارة واجهة برمجة التطبيقات، أكمل البدء السريع التالي: إنشاء مثيل إدارة Azure API. يجب أن يكون المثيل في أحد مستويات الخدمة التي تدعم خوادم MCP.

• تأكد من أن جهازك يدير واجهة برمجة تطبيقات متوافقة مع HTTP (أي واجهة برمجة تطبيقات مستوردة كواجهة برمجة تطبيقات REST، بما في ذلك واجهات برمجة التطبيقات المستوردة من موارد Azure) التي تريد عرضها كخادم MCP. لاستيراد نموذج API، راجع استيراد ونشر واجهة برمجة التطبيقات الأولى.

  إشعار

  لا يمكن عرض أنواع واجهات برمجة التطبيقات الأخرى في إدارة واجهة برمجة التطبيقات غير المتوافقة مع HTTP كخوادم MCP.

• إذا قمت بتمكين تسجيل التشخيص عبر Application Insights أو Azure Monitor في النطاق العالمي (جميع واجهات برمجة التطبيقات) لخدمة إدارة واجهة برمجة التطبيقات الخاصة بك، اضبط إعداد عدد بايتات الحمولة إلى log لإعداد الاستجابة الأمامية إلى 0. يمنع هذا الإعداد تسجيل أجسام الاستجابة غير المقصود عبر جميع واجهات برمجة التطبيقات ويساعد في ضمان عمل خادم MCP بشكل صحيح. لتسجيل الحمولات بشكل انتقائي لواجهات برمجة تطبيقات معينة، قم بتكوين الإعداد بشكل فردي في نطاق واجهة برمجة التطبيقات، مما يسمح بالتحكم المستهدف في تسجيل الاستجابة.

• لاختبار خادم MCP، يمكنك استخدام تعليمة Visual Studio برمجية مع إمكانية الوصول إلى GitHub Copilot أو عملاء أو أدوات MCP أخرى مثل MCP Inspector.

كشف واجهة برمجة التطبيقات كخادم MCP

اتبع هذه الخطوات لعرض واجهة برمجة تطبيقات REST المدارة في إدارة واجهة برمجة التطبيقات كخادم MCP:

1. في بوابة Azure، اذهب إلى مثيل إدارة واجهة برمجة التطبيقات الخاصة بك.
2. في القائمة اليمنى، ضمن واجهات برمجة التطبيقات، حدد خوادم> MCP + إنشاء خادم MCP.
3. حدد عرض واجهة برمجة تطبيقات كخادم MCP.
4. في خادم MCP الخلفي:
   1. اختر واجهة برمجة تطبيقات مدارة أو نسخة API لتعرض كخادم MCP.
   2. حدد عملية واجهة برمجة تطبيقات واحدة أو أكثر لعرضها كأدوات. يمكنك تحديد جميع العمليات أو عمليات معينة فقط.

      إشعار

      يمكنك تحديث العمليات التي تعرضها كأدوات لاحقا في شفرة الأدوات في خادم MCP الخاص بك.

5. في خادم MCP الجديد:
   1. أدخل اسم العرضوالاسم لخادم MCP في إدارة API.
   2. اختياريا، أدخل وصفا لخادم MCP.
6. في قسم المنتجات، يمكنك اختيار منتج أو أكثر للربط بخادم MCP. ربط خادم MCP بمنتج يسمح لك بإدارة الوصول والاشتراكات لخادم MCP من خلال ذلك المنتج.
7. حدد إنشاء.

• تنشئ البوابة خادم MCP وتكشف عمليات واجهة برمجة التطبيقات كأدوات.
• تسرد شفرة خادم MCP الخادم الجديد MCP. يعرض عمود عنوان URL للخادم نقطة نهاية خادم MCP للاستدعاء للاختبار أو داخل تطبيق عميل.

تكوين النهج لخادم MCP

تكوين نهج APIM واحد أو أكثر للمساعدة في إدارة خادم MCP. تنطبق السياسات على جميع عمليات واجهة برمجة التطبيقات التي تعرض كأدوات في خادم MCP. استخدم هذه السياسات للتحكم في الوصول والمصادقة وغيرها من جوانب الأدوات.

تعرف على مزيد من المعلومات عن تكوين النهج:

• النُهج في API Management
• تحويل واجهة برمجة التطبيقات وحمايتها
• تعيين السياسات وتحريرها
• الوصول الآمن إلى خادم MCP

أنذر

لا تصل إلى جسم الاستجابة باستخدام المتغير context.Response.Body داخل سياسات خادم MCP. يؤدي ذلك إلى تحفيز تخزين الاستجابة، مما يتداخل مع سلوك البث المطلوب من خوادم MCP وقد يسبب تعطلها.

لتكوين السياسات لخادم MCP، اتبع الخطوات التالية:

1. في بوابة Azure، اذهب إلى مثيل إدارة واجهة برمجة التطبيقات الخاصة بك.

2. في القائمة اليمنى، ضمن واجهات برمجة التطبيقات، حدد خوادم MCP.

3. حدد خادم MCP من القائمة.

4. في القائمة اليسرى، ضمن MCP، حدد Policies.

5. في محرر النهج، أضف النهج التي تريد تطبيقها على أدوات خادم MCP أو قم بتحريرها. حدد السياسات بصيغة XML.

   على سبيل المثال، يمكنك إضافة سياسات إلى قسم الوارد لتقييد المكالمات إلى أدوات خادم MCP (في هذا المثال، 5 مكالمات كل 30 ثانية لكل عنوان IP) ولإضافة تتبع مخصص لمعرف الوكيل الخاص بالمتصل.

   <inbound>
       <base />
       <rate-limit-by-key calls="5" renewal-period="30" counter-key="@(context.Request.IpAddress)" remaining-calls-variable-name="remainingCallsPerIP" />
    	<trace source="My MCP" severity="information">
    		<message>My MCP trace info</message>
    		<metadata name="agent-id" value="@(context.Request.Headers.GetValueOrDefault("agent-id", "n/a"))" />
   </inbound>
   

   

إشعار

تقوم إدارة واجهات برمجة التطبيقات بتقييم السياسات المكونة في النطاق العالمي (جميع واجهات برمجة التطبيقات) قبل تقييم السياسات في نطاق خادم MCP.

التحقق من صحة خادم MCP واستخدامه

استخدم وكيل نموذج كبير متوافق (مثل GitHub Copilot أو نواة دلالية أو Copilot Studio) أو عميل اختبار (مثل curl) لاستدعاء نقطة نهاية MCP المستضافة من قبل إدارة الواجهة. تأكد من أن الطلب يتضمن رؤوس أو رموز مميزة مناسبة، وتأكد من التوجيه الناجح والاستجابة من خادم MCP.

تلميح

إذا استخدمت مفتش MCP لاختبار خادم MCP يديره إدارة API، استخدم الإصدار 0.9.0.

أضف خادم MCP في تعليمة Visual Studio برمجية

في تعليمة Visual Studio برمجية، استخدم GitHub Copilot الدردشة في وضع الوكيل لإضافة خادم MCP واستخدام الأدوات. للحصول على خلفية حول خوادم MCP في تعليمة Visual Studio برمجية، راجع استخدم خوادم MCP في VS Code.

لإضافة خادم MCP في تعليمة Visual Studio برمجية:

1. استخدم الأمر MCP: إضافة خادم من لوحة الأوامر.

2. عند المطالبة، حدد نوع الخادم: HTTP (HTTP أو Server Sent Events).

3. أدخل عنوان URL للخادم لخادم MCP في إدارة واجهة برمجة التطبيقات. على سبيل المثال، https://<apim-service-name>.azure-api.net/<api-name>-mcp/mcp لنقطة نهاية MCP.

4. أدخل معرف الخادم الذي تختاره.

5. حدد ما إذا كنت تريد حفظ التكوين في إعدادات مساحة العمل أو إعدادات المستخدم.

   • إعدادات مساحة العمل - يتم حفظ تكوين الخادم في .vscode/mcp.json ملف متوفر فقط في مساحة العمل الحالية.

   • إعدادات المستخدم - تتم إضافة تكوين الخادم إلى الملف العمومي settings.json الخاص بك وهو متوفر في جميع مساحات العمل. يبدو التكوين مشابها لما يلي:

   

إضافة حقول إلى تكوين JSON لإعدادات مثل عنوان المصادقة. المثال التالي يوضح تكوين مفتاح اشتراك إدارة واجهة برمجة التطبيقات الذي يمرر في رأس كقيمة إدخال. تعرف على المزيد حول تنسيق التكوين

استخدام الأدوات في وضع العامل

بعد إضافة خادم MCP في تعليمة Visual Studio برمجية، يمكنك استخدام الأدوات في وضع الوكيل.

1. في GitHub Copilot الدردشة، اختر وضع Agent واختر زر Tools لرؤية الأدوات المتاحة.

   

2. اختر أداة أو أكثر من خادم MCP لتوفرها في الدردشة.

   

3. أدخل مطالبة في الدردشة لاستدعاء الأداة. على سبيل المثال، إذا حددت أداة للحصول على معلومات حول طلب، يمكنك سؤال العامل عن طلب.

   Get information for order 2
   

   حدد متابعة لمشاهدة النتائج. يستخدم العامل الأداة لاستدعاء خادم MCP وإرجاع النتائج في الدردشة.

   

استكشاف الأخطاء وإصلاحها والمشاكل المعروفة

مشكلة	السبب	الحل
401 Unauthorized خطأ من الواجهة الخلفية	لم تتم إعادة توجيه رأس التفويض	إذا لزم الأمر، استخدم set-header السياسة لإرفاق الرمز يدويا
يعمل استدعاء واجهة برمجة التطبيقات في إدارة واجهة برمجة التطبيقات ولكنه يفشل في العامل	عنوان URL الأساسي غير صحيح أو رمز مميز مفقود	التحقق مرة أخرى من سياسات الأمان ونقطة النهاية
يفشل دفق خادم MCP عند تمكين سجلات التشخيص	يتداخل تسجيل نص الاستجابة أو الوصول إلى نص الاستجابة من خلال السياسة مع نقل MCP	تعطيل تسجيل نص الاستجابة في نطاق جميع واجهات برمجة التطبيقات - راجع المتطلبات الأساسية

المحتوى ذو الصلة

• عينة: تخويل خوادم MCP مع بيانات تعريف الموارد المحمية (PRM)

• عينة: خوادم MCP البعيدة آمنة باستخدام إدارة Azure API (تجريبي)

• <مختبر تفويض العميل c0>MCP

• استخدم الامتداد إدارة Azure API ل VS Code لاستيراد وإدارة واجهات برمجة التطبيقات (APIs

• تسجيل واكتشف خوادم MCP البعيدة في مركز API Azure

• عرض واجهة برمجة تطبيقات REST في إدارة واجهة برمجة التطبيقات كخادم MCP

• كشف خادم MCP الحالي وإدارته