---
title: خادم MCP
description: قم بربط مساعدي الذكاء الاصطناعي (Claude و Cursor و VS Code وغيرها) بـ API تثبيتك عبر نقطة نهاية الـ MCP المضمنة على العنوان /mcp — المصادقة، وإعدادات العميل، والأدوات وقواعد الأمان.
url: https://nexcmp.com/ar/docs/developers/mcp/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# خادم MCP {#mcp-server}

> **أين في البوابة:** API reference › Tools (`https://<your-domain>/apidoc`) يظهر نقطة النهاية ومقتطفات العميل؛ ويتم إنشاء المفاتيح في API keys (`/api-keys`). لا توجد إعدادات في لوحة المشرف: نقطة النهاية هي جزء من اللوحة.

## الوظيفة {#what-it-does}

يسمح **Model Context Protocol (MCP)** لمساعد الذكاء الاصطناعي باستدعاء الأدوات. توفر NexCMP نقطة نهاية MCP على `https://<your-domain>/mcp`. تصبح كل عملية API عامة عبارة عن **أداة** (`vm_list` و `vm_start` و `billing_wallet`، ...)، بحيث يمكن للعميل أن يسأل مساعده "أي من أجهزتي الافتراضية تعمل؟" أو "أوقف الجهاز الافتراضي للتجربة". يعمل المساعد باستخدام مفتاح الـ API وصلاحيات العميل وحده.

::: tip هل تريد تكوين NexCMP نفسه باستخدام الذكاء الاصطناعي؟
هذه الصفحة مخصصة لنقطة نهاية MCP لل**عميل** (`/mcp`). للسماح لمساعد الذكاء الاصطناعي بتكوين لوحتك الخاصة كمسؤول، راجع [تكوين باستخدام الذكاء الاصطناعي](https://nexcmp.com/ar/docs/configure-with-ai/mcp-admin/) (نقطة النهاية `/mcp/admin`، مفاتيح المسؤول `ak_`).
:::

## المتطلبات {#requirements}

| العنصر | المتطلب |
|---|---|
| الخادم | لا شيء للتثبيت: يتم خدمة نقطة النهاية بواسطة اللوحة ويمكن الوصول إليها أينما كانت اللوحة. يجب أن يقوم الوكيل العكسي الخاص بك بتوجيه `/mcp` إلى اللوحة. |
| العميل | [مفتاح API](https://nexcmp.com/ar/docs/developers/api-keys/) (`vk_...`) يتضمن النطاقات التي يحتاجها المساعد. |
| العميل | عميل MCP يدعم نقل **Streamable HTTP** وترويسة `Authorization` مخصصة: Claude Code، وClaude Desktop (من خلال جسر `mcp-remote`)، وCursor، وVS Code مع وضع وكيل Copilot وما شابه ذلك. |
| إصدارات البروتوكول | 2025-11-25 و2025-06-18 و2025-03-26. |

## تجهيز البنية التحتية {#prepare-the-infrastructure}

لا شيء، سوى التأكد من أن `https://<your-domain>/mcp` غير محظور بواسطة جدار حماية أو قاعدة وكيل. يتم رفض عميل MCP المستند إلى المتصفح من أصل آخر ما لم يتم السماح بهذا الأصل؛ بينما لا ترسل عميلات سطر الأوامر وتطبيقات سطح المكتب رأس `Origin` وتعمل كما هي.

## الاتصال (جانب العميل) {#connect-customer-side}

1. أنشئ مفتاح واجهة برمجة تطبيقات في البوابة (**API keys › Create key**) مع النطاقات التي تريد أن يستخدمها المساعد فقط، وفترة صلاحية قصيرة، وتقييد عنوان IP إن أمكن.
2. أضف الخادم إلى عميلك. استبدل `cloud.example.com` والمفتاح.

   **Claude Code**

   ```bash
   claude mcp add --transport http cloud https://cloud.example.com/mcp \
     --header "Authorization: Bearer vk_XXXX"
   ```

   **Cursor** (`~/.cursor/mcp.json` أو `.cursor/mcp.json`؛ اضبط `CLOUD_API_KEY` في بيئة التشغيل التي يبدأ منها Cursor):

   ```json
   {
     "mcpServers": {
       "cloud": {
         "url": "https://cloud.example.com/mcp",
         "headers": { "Authorization": "Bearer ${env:CLOUD_API_KEY}" }
       }
     }
   }
   ```

   **Claude Desktop** (يحتاج Node.js 18+؛ `claude_desktop_config.json`)، من خلال جسر `mcp-remote`:

   ```json
   {
     "mcpServers": {
       "cloud": {
         "command": "npx",
         "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp", "--header", "Authorization:${CLOUD_AUTH_HEADER}"],
         "env": { "CLOUD_AUTH_HEADER": "Bearer vk_XXXX" }
       }
     }
   }
   ```

   اكتب الرأس بدون مسافة بعد النقطتين واضع القيمة بأكملها في متغيّر البيئة، كما هو موضح أعلاه.

3. أعد تشغيل العميل واطلب منه سرد أدواتك.


تحقق من الاتصال بدون عميل:

```bash
curl -s https://cloud.example.com/mcp \
  -H "Authorization: Bearer vk_XXXX" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

## How it works {#how-it-works}

| العنصر | التفاصيل |
|---|---|
| نقطة النهاية | `POST /mcp` مع رسالة JSON-RPC 2.0؛ الإجابة هي `application/json`. `GET /mcp` يرد بـ 405 (لا يوجد تدفق من الخادم إلى العميل)؛ `DELETE /mcp` ينهي الجلسة. |
| المصادقة | فقط `Authorization: Bearer vk_...` (يتم رفض رموز الجلسة وملفات تعريف الارتباط ومفاتيح المسؤول باستخدام الرمز 401 مع رأس `WWW-Authenticate: Bearer`). |
| الجلسة | يتم إصدار `Mcp-Session-Id` بواسطة `initialize`، وهو مرتبط بهذا المفتاح وصالح لمدة 24 ساعة؛ وبحد أقصى 16 جلسة لكل مفتاح. |
| الأدوات | واحدة لكل عملية في API العام مرئية للمفتاح. اسم الأداة هو أمر CLI مع استخدام `_` بدلاً من المسافات والشرطات (يصبح `vm firewall add` هو `vm_firewall_add`) ويطابق OpenAPI `operationId`. يتم إدراج الأداة فقط عندما يمتلك المفتاح نطاقها وتكون الوحدة مفعلة. |
| القدرات | الأدوات فقط (بدون موارد أو مطالبات). |
| الحجم | حجم طلب الجسم يصل إلى 1 ميجابايت؛ ونص نتيجة الأداة يصل إلى حوالي 100 كيلوبايت (يتم اقتطاع الباقي مع ملاحظة)؛ وتستغرق المكالمة بحد أقصى 55 ثانية. |

### قواعد الأمان {#safety-rules}

- **نفس بوابة REST.** يمر كل `tools/call` عبر خط أنابيب الطلبات الخاص باللوحة نفسها: النطاق، والموقع، وتقييد عنوان IP، وحد معدل الطلبات، وعدم التكرار، وفقرات التحقق من الملكية (الرمز 404 لموارد الأشخاص الآخرين) وحصص الاستخدام كلها مطبقة. لا يمكن لـ MCP منح أي شيء لا يملكه المفتاح.
- **التأكيد.** الأدوات التي تكلف أموالاً أو تحذف أو تعيد بيانات الاعتماد (تذاكر وحدة التحكم، أو kubeconfig، أو أسرار S3 أو SSH، أو إعادة تعيين كلمة المرور، أو المفاتيح الجديدة) تتطلب وسيطة `confirm: true`. يخبر وصف الأداة المساعد بتمريرها فقط بعد موافقة المستخدم، لذا لا يمكن لأي تعليمة مخفية في صفحة ويب أو سجل تشغيلها من تلقاء نفسها.
- **عدم التكرار (Idempotency).** تقبل الأدوات مدفوعة الثمن `idempotency_key`؛ وإذا تم حذفه، يتم اشتقاق مفتاح ثابت من اسم الأداة والوسيطات، بحيث لا يمكن لإعادة محاولة متطابقة أن تخصم المبلغ مرتين.
- **غير معروضة كأدوات:** نقاط نهاية البث (دردشة AI Agent)، وتذاكر SSH أو وحدة التحكم لمرة واحدة عبر WebSocket، والتنزيلات الثنائية، وننقاط نهاية تطبيق VPN (`/v1/ext/*`).
- **غير ممكن أبداً:** لا يسمح API أبداً بعمليات شحن الرصيد، أو تغيير كلمات المرور، أو حذف الحساب أو إنشاء مفاتيح، لذلك لا يمكن لأي مساعد القيام بذلك.

### الحدود {#limits}

| الحد | القيمة الافتراضية |
|---|---|
| استدعاءات الأدوات لكل مفتاح | 60 في الدقيقة |
| طلبات MCP لكل مفتاح | 240 في الدقيقة |
| بالإضافة إلى حدود المفتاح والحساب العادية | راجع [REST API](https://nexcmp.com/ar/docs/developers/api/#rate-limits) |

عند تجاوز الحد، يستجيب نقطة النهاية برمز HTTP 429 مع خطأ JSON-RPC و`Retry-After`.

## التحقق {#verify}

1. يقوم أمر `curl` أعلاه بإرجاع نتيجة JSON-RPC مع قائمة `tools`. تظهر فقط الأدوات التي تتطابق مع نطاقات المفتاح.
2. اسأل العميل لديك "list my VMs": يقوم المساعد باستدعاء `vm_list` وعرض النتيجة.
3. في البوابة يتحرك وقت **Last used** الخاص بالمفتاح، وتظهر عمليات الكتابة في **Key usage log**.

## الحدود والملاحظات {#limits-notes}

- **تسجيل الدخول عبر المتصفح (OAuth).** تصف صفحة المرجع أيضاً تسجيل الدخول عبر المتصفح للعملاء الذين يدعمون مصادقة MCP OAuth. في نسخة NexCMP المثبتة، الطريقة المدعومة والمختبرة هي مفتاح API (أو `cmp login` لـ CLI).
- **مواقع الموزعين** لا تعرض قسم MCP؛ ويستخدم عملاؤهم نطاق الموزع لـ API.
- **أقل امتياز.** أنشئ مفتاحاً مخصصاً لكل مساعد مع نطاقات القراءة أولاً؛ وأضف نطاقات الكتابة فقط عند الحاجة.
- قم بإلغاء المفتاح في **API keys** لقطع وصول المساعد على الفور.

## استكشاف الأخطاء وإصلاحها {#troubleshooting}

| العَرَض | السبب | الحل |
|---|---|---|
| 401 مع `WWW-Authenticate: Bearer` | لا يوجد مفتاح، أو مفتاح خاطئ، أو رمز جلسة | أرسل `Authorization: Bearer vk_...`. |
| 403 حول `Origin` | صفحة متصفح على أصل (Origin) آخر | استخدم جهاز سطح مكتب أو عميل CLI؛ أو اطلب من المسؤول السماح بالأصل (`mcp_allowed_origins`). |
| 404 في طلب يحتوي على `Mcp-Session-Id` | الجلسة تنتمي إلى مفتاح آخر أو انتهت صلاحيتها | قم بتشغيل `initialize` مرة أخرى. |
| 405 على `GET /mcp` | المتوقع: الخادم لا يحتوي على تدفق أحداث | استخدم POST فقط (تقوم العناوين بهذا تلقائياً). |
| قائمة الأدوات قصيرة | نطاقات المفاتيح أو الوحدات النمطية | أضف نطاقات إلى المفتاح؛ وقم بتفعيل الوحدة النمطية. |
| تستجيب الأداة بأنها تحتاج `confirm: true` | أداة مدفوعة، أو محذوفة، أو حساسة | يجب على المساعد تعيين `confirm` بعد موافقتك. |
| 429 | حد معدل MCP أو المفتاح | انتظر حتى `Retry-After`. |
| العميل غير قادر على الاتصال برأس (header) | العميل بدون دعم الرؤوس المخصصة | استخدم جسر `mcp-remote`. |