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

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

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

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

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

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

القيود

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

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

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

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

  إشعار

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

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

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

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

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

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

      إشعار

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

5. في خادم MCP الجديد:
   1. أدخل اسما لخادم MCP في إدارة واجهة برمجة التطبيقات.
   2. اختياريا، أدخل وصفا لخادم MCP.
6. حدد إنشاء.

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

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

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

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

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

أنذر

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

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

1. في مدخل Microsoft Azure، انتقل إلى مثيل APIM.

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

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

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

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

   على سبيل المثال، يمكنك إضافة سياسة لتقييد المكالمات إلى أدوات خادم MCP (في هذا المثال، مكالمة واحدة لكل 60 ثانية في كل جلسة MCP).

   <!-- Rate limit tool calls by Mcp-Session-Id header -->
   <set-variable name="body" value="@(context.Request.Body.As<string>(preserveContent: true))" />
   <choose>
       <when condition="@(
           Newtonsoft.Json.Linq.JObject.Parse((string)context.Variables["body"])["method"] != null 
           && Newtonsoft.Json.Linq.JObject.Parse((string)context.Variables["body"])["method"].ToString() == "tools/call"
       )">
       <rate-limit-by-key 
           calls="1" 
           renewal-period="60" 
           counter-key="@(
               context.Request.Headers.GetValueOrDefault("Mcp-Session-Id", "unknown")
           )" />
       </when>
   </choose>
   

   

إشعار

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

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

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

تلميح

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

إضافة خادم MCP في Visual Studio Code

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

لإضافة خادم MCP في Visual Studio Code:

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 لإعدادات مثل عنوان المصادقة. يوضح المثال التالي تكوين مفتاح اشتراك APIM الذي تم تمريره في رأس كما هو الحال في قيمة الإدخال. تعرف على المزيد حول تنسيق التكوين

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

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

1. في GitHub Copilot chat، حدد Agent mode وحدد الزر Tools لمشاهدة الأدوات المتوفرة.

   

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

   

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

   Get information for order 2
   

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

   

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

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

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

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

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

• مختبر تخويل عميل MCP

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

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

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

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