---
title: توصيل عميل ذكاء اصطناعي (MCP)
description: اربط Claude Code وCodex CLI وGemini CLI وCursor وClaude Desktop وclaude.ai وChatGPT أو OpenAI SDKs بنقطة نهاية MCP لإدارة لوحتك مع كامل قائمة الأدوات.
url: https://nexcmp.com/ar/docs/configure-with-ai/mcp-admin/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# توصيل عميل ذكاء اصطناعي (MCP) {#connect-an-ai-client-mcp}

> **أين تجد ذلك في لوحة المشرف:** System › Settings › API & AI agents (`/agent/keys`)، ويُظهر تبويب **Connect an AI** عنوان URL لنقطة النهاية وقصاصة جاهزة للنسخ لكل عميل، معبأة بمفتاح أنشأته للتو.

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

يتيح بروتوكول **Model Context Protocol (MCP)** لعميل الذكاء الاصطناعي استدعاء الأدوات. تخدم لوحتك خادم MCP للمشرف على `https://cloud.example.com/mcp/admin`. قم بتوصيل أداة الذكاء الاصطناعي الخاصة بك به واسأل بلغة واضحة: "ما الذي تبقى لإعداده؟"، "أضف مجموعة Proxmox الخاصة بي"، "أنشئ خططاً بهامش 40%". يستدعي العميل أدوات المشرف أدناه؛ وتتحقق اللوحة من النطاقات، وتسألك قبل أي إجراء محفوف بالمخاطر، وتسجل كل عملية استدعاء.

::: info نقطتا نهاية MCP
`/mcp` هي نقطة نهاية **العميل** (مفاتيح API الخاصة بالعملاء، `vk_`؛ راجع [خادم MCP](https://nexcmp.com/ar/docs/developers/mcp/)). `/mcp/admin` هي نقطة نهاية **المسؤول** الموضحة هنا (مفاتيح المسؤول `ak_` أو OAuth). لا تختلط الجهتان أبداً: أدوات المسؤول غير مرئية على `/mcp`، وتقبل `/mcp/admin` مفاتيح المسؤول فقط.
:::

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

| العنصر | المتطلب |
|---|---|
| نقطة النهاية | `https://cloud.example.com/mcp/admin` على نطاق لوحتك الخاص. انسخ عنوان URL الدقيق من تبويب **Connect an AI**. تعرض نفس الصفحة عنوان URL محلي (`http://127.0.0.1:<port>/mcp/admin`) للأدوات التي تعمل على الخادم نفسه. |
| بيانات الاعتماد | [مفتاح مسؤول API](https://nexcmp.com/ar/docs/configure-with-ai/admin-api-keys/) (`ak_...`) مع النطاقات التي تريدها، **أو** تسجيل الدخول عبر OAuth لموصلات الويب ([موصلات OAuth](https://nexcmp.com/ar/docs/configure-with-ai/oauth-connectors/)). |
| العميل | أي عميل MCP يدعم نقل **Streamable HTTP** وترويسة `Authorization` مخصصة. إصدارات البروتوكول 2025-11-25 و 2025-06-18 و 2025-03-26. |
| الشبكة | إذا وضعت وكيل عكسي (reverse proxy) خاص بك أمام اللوحة، فيجب عليه إعادة توجيه `/mcp/admin`. تتصل موصلات الويب (claude.ai و ChatGPT) من خوادم المزود، لذا يجب أن يكون عنوان URL قابلاً للوصول من الإنترنت. |

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

لا شيء لتثبيته على الخادم. إذا قمت بتقييد المفتاح حسب عنوان IP، فتأكد من أن العنوان الذي يتصل منه عميلك يقع ضمن النطاق. اختبر إمكانية الوصول أولاً:

```bash
curl -i -X POST https://cloud.example.com/mcp/admin
```

استجابة `401` مع ترويسة `WWW-Authenticate: Bearer ... resource_metadata=...` تعني أن نقطة النهاية تعمل وتريد بيانات الاعتماد.

## الربط في NexCMP {#connect-in-nexcmp}

1. إنشاء مفتاح: **System › Settings › API & AI agents › API keys › New key**. للاستخدام الأول، استخدم `admin:read` فقط؛ وأضف نطاقات الكتابة عندما تحتاج إليها. راجع [Admin API keys](https://nexcmp.com/ar/docs/configure-with-ai/admin-api-keys/).
2. افتح تبويب **Connect an AI**. بينما لا يزال مربع حوار "تم إنشاء المفتاح" حديثاً، تحتوي كل قصاصة أدناه بالفعل على مفتاحك الحقيقي. وإلا فستعرض العنصر النائب `ak_YOUR_KEY`.
3. انسخ القصاصة الخاصة بعميلك وقم بتشغيلها أو لصقها كما هو موضح لاحقاً.

![تبويب Connect an AI مع عنوان URL لـ MCP وبطاقة واحدة بها زر نسخ لكل عميل](https://nexcmp.com/ar/docs/images/configure-with-ai/mcp-admin-01-connect.webp)

### Claude Code {#claude-code}

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

ثم ابدأ `claude` واسأل "list the tools from nexcmp" أو "what is left to set up?".

تم التحقق في 30/10/2026 باستخدام Claude Code 2.1: تكتب `claude mcp add --transport http …` الخادم (أضف `-s project` للاحتفاظ به في `.mcp.json` الخاص بالمشروع — يطلب منك Claude Code الموافقة على خوادم المشروع في المرة الأولى). بالنسبة للبرامج النصية، يعمل `claude -p "…" --mcp-config .mcp.json --strict-mcp-config --allowedTools "mcp__nexcmp__*"` بدون موجه الموافقة ويسمح لـ Claude باستخدام أدوات اللوحة فقط.

### Claude Desktop {#claude-desktop}

يتطلب Node.js 18 أو أحدث. أضف هذا إلى `claude_desktop_config.json` (يستخدم جسر `mcp-remote`) وأعد تشغيل Claude Desktop:

```json
{
  "mcpServers": {
    "nexcmp": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://cloud.example.com/mcp/admin", "--header", "Authorization:Bearer ak_XXXX"]
    }
  }
}
```

إذا كان نظامك يعبث بالمسافة في وسيطة الترويسة، ضع القيمة بأكملها في متغيّر بيئي بدلاً من ذلك، تماماً كما هو الحال مع نقطة نهاية العملاء: `"args": [..., "--header", "Authorization:${NEXCMP_AUTH_HEADER}"]` مع `"env": { "NEXCMP_AUTH_HEADER": "Bearer ak_XXXX" }`.

### claude.ai (custom connector) {#claude-ai-custom-connector}

لا حاجة لمفتاح: فهو يسجل الدخول عبر OAuth. في موقع claude.ai افتح إعدادات الموصلات، وأضف موصلاً مخصصاً، والصق `https://cloud.example.com/mcp/admin`، ثم سجل الدخول بحساب مسؤول NexCMP الخاص بك واختر الأذونات على شاشة الموافقة. التفاصيل: [موصلات OAuth](https://nexcmp.com/ar/docs/configure-with-ai/oauth-connectors/).

### ChatGPT (developer mode) {#chatgpt-developer-mode}

لا حاجة لمفتاح. في ChatGPT قم بتشغيل وضع المطور، وأضف موصل MCP مع عنوان URL `https://cloud.example.com/mcp/admin`، واختر OAuth وسجل الدخول بحساب مسؤول NexCMP الخاص بك. التفاصيل: [موصلات OAuth](https://nexcmp.com/ar/docs/configure-with-ai/oauth-connectors/).

### Codex CLI {#codex-cli}

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.nexcmp]
url = "https://cloud.example.com/mcp/admin"
bearer_token_env_var = "NEXCMP_KEY"
```

ثم قم بتصدير المفتاح في الصدفة (shell) التي تبدأ تشغيل Codex:

```bash
export NEXCMP_KEY=ak_XXXX
codex
codex mcp list   # shows nexcmp with "Bearer token" auth
```

::: tip Non-interactive `codex exec`
في `codex exec` (البرامج النصية، وCI) لا يسأل Codex قبل استدعاء الأدوات، ويتخطى الأدوات التي تغير البيانات. أضف `default_tools_approval_mode = "approve"` تحت `[mcp_servers.nexcmp]` للسماح له باستدعائها؛ لا تزال لوحة التحكم تُعيد معاينة وتطلب التأكيد لعمليات الأموال والأمان والحذف. تم التحقق من ذلك باستخدام Codex CLI 0.166 بتاريخ 30/10/2026.
:::

### Gemini CLI {#gemini-cli}

Add to `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "nexcmp": {
      "httpUrl": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}
```

يقوم Gemini CLI بإيقاف تشغيل خوادم MCP في المجلدات التي لا يثق بها. ابدأ تشغيله في مجلد تثق به (أو ثق بالمجلد عندما يطلب ذلك)، ثم تحقق باستخدام `gemini mcp list` — فهو يعرض `nexcmp … Connected`. يمكنك إبقاء المفتاح خارج الملف باستخدام `"Authorization": "Bearer $NEXCMP_KEY"`. تم التحقق باستخدام Gemini CLI 0.66 بتاريخ 30/10/2026.

### Cursor {#cursor}

Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` in a project):

```json
{
  "mcpServers": {
    "nexcmp": {
      "url": "https://cloud.example.com/mcp/admin",
      "headers": { "Authorization": "Bearer ak_XXXX" }
    }
  }
}
```

::: tip إبقاء المفتاح خارج ملفات التكوين
حيثما يدعم العميل ذلك، اقرأ المفتاح من متغيّر بيئي بدلاً من كتابته في الملف: يقوم Codex بذلك افتراضياً (`bearer_token_env_var`)، ويقبل Cursor `"Bearer ${env:NEXCMP_KEY}"`. لا تقم أبداً بإيداع ملف يحتوي على مفتاح.
:::

### OpenAI Agents SDK (Python) {#openai-agents-sdk-python}

```python
from agents.mcp import MCPServerStreamableHttp

nexcmp = MCPServerStreamableHttp(
    params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}},
    name="nexcmp",
)
```

تشغيل كامل (تم التحقق باستخدام `openai-agents` 0.24 بتاريخ 30/10/2026 — أداة قراءة، تليها تغيير في الرصيد أعاد معاينة التأكيد وتم تطبيقه عند الاستدعاء الثاني باستخدام `confirm_token`):

```python
import asyncio
from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async def main():
    async with MCPServerStreamableHttp(params={"url": "https://cloud.example.com/mcp/admin",
            "headers": {"Authorization": "Bearer ak_XXXX"}}, name="nexcmp") as nexcmp:
        agent = Agent(name="admin", model="gpt-5", mcp_servers=[nexcmp],
                      instructions="You operate a hosting panel through the nexcmp tools. Ask me before confirming money actions.")
        result = await Runner.run(agent, "Run system_health and summarise it in one line.")
        print(result.final_output)

asyncio.run(main())
```

### OpenAI Responses API {#openai-responses-api}

مرّر الخادم كأداة من النوع `mcp`. حافظ على `require_approval` في `always` لكي يسألك برنامجك قبل كل استدعاء:

```json
{
  "type": "mcp",
  "server_label": "nexcmp",
  "server_url": "https://cloud.example.com/mcp/admin",
  "headers": { "Authorization": "Bearer ak_XXXX" },
  "require_approval": "always"
}
```

### أي شيء آخر (HTTP عادي) {#anything-else-plain-http}

يمكن للعميل الذي لا يحتوي على MCP استدعاء نفس الأدوات عبر HTTP. تسردها `GET /v1/admin/agent/tools`، وتنفذ `POST /v1/admin/agent/tools/<name>` واحدة منها مع نص JSON للوسيطات، وتُعيد `GET /v1/admin/openapi.json` وصف OpenAPI 3.1 (كل أداة هي عملية واحدة). تحتاج جميعها إلى `Authorization: Bearer ak_...`.

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

1. بدون عميل، اسرد الأدوات:

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

   النتيجة هي رد JSON-RPC مع الأدوات التي تسمح بها نطاقاتك.
2. اطلب من عميلك "run system_health". فهو يُعيد التنبيهات، وحالة البنية التحتية المتصلة، والمدفوعات، والبريد الإلكتروني، والذكاء الاصطناعي، وحالة الترخيص.
3. افتح **API & AI agents › Activity**: يتم سرد الاستدعاءات مع اسم العميل و`mcp`.
4. على الخادم، يطبع `sudo nexcmp status` سطر "MCP admin" الذي يوضح `ready` عندما تستجيب نقطة النهاية (HTTP 401 بدون مفتاح هو الحالة السليمة).

## الأدوات {#tools}

يوفر الخادم 58 أداة. لا يرى العميل سوى الأدوات التي تسمح بها نطاقات مفتاحه: تحتاج أدوات القراءة إلى `admin:read`، وتحتاج أدوات الكتابة إلى نطاقها الخاص. تحصل أدوات الكتابة أيضاً على وسيطة اختياريّة `confirm_token` (راجع [Confirmation](#confirmation-confirm-token)). يتم التحقق من الوسيطات مقابل مخطط كل أداة: تُرفض الوسيطات غير المعروفة أو التي بها خطأ إملائي مع رسالة تذكر أسماءها.

الأسعار بالدولار الأمريكي: أسعار الخطط بالدولار في الساعة (`hourly_usd`)، والأرصدة بالسنتات. يمكن تعيين الأسرار ولكن لا يتم إرجاعها مطلقاً.

### Overview and logs {#overview-and-logs}

| الأداة | الوظيفة | النطاق | Changes data | Asks you |
|---|---|---|---|---|
| `system_health` | التنبيهات التي تحتاج إلى اهتمام، وحالة البنية التحتية، والمدفوعات، والبريد الإلكتروني، والذكاء الاصطناعي، والترخيص، وحالة التحديث. | `admin:read` | No | No |
| `setup_checklist` | ما تم تكوينه وما تبقى: الترخيص، البنية التحتية، المنطقة، قوالب نظام التشغيل، الخطط، المدفوعات، البريد الإلكتروني، العلامة التجارية، الجوانب القانونية، الطلب التجريبي. | `admin:read` | No | No |
| `license_status` | حالة الترخيص وما إذا كان هناك إصدار أحدث من NexCMP متوفر. | `admin:read` | No | No |
| `audit_search` | البحث في سجل التدقيق الخاص بالمشرف وسجل مفاتيح API. | `admin:read` | No | No |

### الإعدادات، العلامة التجارية، النواحي القانونية، والوحدات النمطية {#settings-branding-legal-modules}

| الأداة | الوظيفة | النطاق | Changes data | Asks you |
|---|---|---|---|---|
| `settings_get` | قراءة الإعدادات العامة (`keys` عوامل التصفح؛ اللاحقة `*` تطابق بادئة). | `admin:read` | No | No |
| `settings_update` | تغيير الإعدادات العامة من كائن `values` مسطح. يتم قبول المفاتيح المذكورة بواسطة `settings_get` فقط. | `settings:write` | نعم | عندما يمس مفتاح المدفوعات، أمان تسجيل الدخول، مفاتيح التحكم على مستوى الموقع أو الأسعار |
| `branding_get` | اسم العلامة التجارية، اللون، عملة العرض، اسم البائع، وشعارات الموقع ورمز المفضلة (Favicon). | `admin:read` | No | No |
| `branding_update` | تعيين اسم العلامة التجارية (حتى 60 حرفاً)، اللون (`#rrggbb`)، عملة العرض (`usd` أو `vnd`) واسم البائع. | `settings:write` | نعم | No |
| `branding_logo_set` | تحميل شعار فاتح أو داكن أو رمز مفضلة من رابط https أو base64 (بصيغة PNG أو JPEG أو WEBP أو ICO أو SVG، بحجم يصل إلى 512 كيلوبايت). | `settings:write` | نعم | No |
| `legal_get` | شروط الخدمة وسياسة الخصوصية (باللغتين الإنجليزية والvietnamية) والإعدادات الافتراضية المحايدة. | `admin:read` | No | No |
| `legal_update` | تعيين نص الشروط والخصوصية (markdown بسيط، بدون HTML، بحد أقصى 50 كيلوبايت لكل منهما). السلسلة الفارغة تعيد القيمة الافتراضية. | `settings:write` | نعم | No |
| `modules_get` | الوحدات النمطية الاختيارية المفعّلة وتلك التي يمكن تبديلها. | `admin:read` | No | No |
| `module_set` | تبديل وحدة نمطية اختيارية بين التشغيل والإيقاف (يجب أن يكون `key` واحداً من `settable`). | `settings:write` | نعم | No |

### البريد الإلكتروني والتنبيهات {#email-and-alerts}

| الأداة | الوظيفة | النطاق | Changes data | Asks you |
|---|---|---|---|---|
| `smtp_get` | إعدادات البريد الإلكتروني الصادر (مع إخفاء كلمة المرور) وحالة قائمة الانتظار. | `admin:read` | No | No |
| `smtp_configure` | تعيين خادم SMTP. يتطلب تغيير المضيف أو المنفذ أو الأمان إعادة إدخال كلمة المرور. | `settings:write` (+ `secrets:write` لكلمة المرور) | نعم | No |
| `smtp_test` | إرسال بريد إلكتروني تجريبي حقيقي باستخدام الإعدادات المحفوظة. | `settings:write` | يرسل بريداً إلكترونياً | No |
| `telegram_get` | قنوات إشعارات المشرفين (معرفات المحادثات؛ رموز البوت لا تُعاد أبداً). | `admin:read` | No | No |
| `telegram_configure` | إضافة أو تحديث قناة تنبيهات Telegram (رمز البوت ومعرف المحادثة) وتبديل تنبيهات المشرفين بين التشغيل والإيقاف. | `settings:write` (+ `secrets:write` للرمز) | نعم | No |
| `telegram_test` | إرسال رسالة تجريبية إلى قناة Telegram. | `settings:write` | يرسل رسالة | No |

### المدفوعات والعملة {#payments-and-currency}

| الأداة | الوظيفة | النطاق | Changes data | Asks you |
|---|---|---|---|---|
| `payments_get` | حالة Stripe وPayPal والعملات المشفرة (USDT) والتحويل البنكي، بالإضافة إلى القنوات المفعّلة والرسوم. | `admin:read` | No | No |
| `payment_configure` | تعيين بيانات اعتماد إحدى بوابات الدفع (`stripe` أو `paypal` أو `crypto` أو `bank`). | `billing:write` (+ `secrets:write`) | نعم | دائماً |
| `payment_test` | التحقق من بيانات اعتماد بوابة الدفع المحفوظة لدى المزود. | `billing:write` | No | No |
| `currency_get` | عملة العرض وسعر صرف USD إلى VND (تلقائي أو يدوي). | `admin:read` | No | No |
| `currency_set` | تعيين عملة العرض و/أو سعر الصرف اليدوي (0 يعني تلقائي، وإلا من 15000 إلى 50000). | `billing:write` | نعم | عندما تغير سعر الصرف اليدوي |

### البنية التحتية والمناطق {#infrastructure-and-zones}

| الأداة | الوظيفة | النطاق | Changes data | Asks you |
|---|---|---|---|---|
| `cloudstack_get` | نقطة نهاية CloudStack المحفوظة ومعرفات المناطق والشبكات (مع إخفاء المفاتيح). | `admin:read` | No | No |
| `cloudstack_test` | اختبار نقطة نهاية باستخدام مفتاح API وسر دون حفظ؛ يعرض قائمة المناطق. | `infra:write` (+ `secrets:write`، لأنك تمرر المفاتيح) | No | No |
| `cloudstack_connect` | حفظ اتصال CloudStack. | `infra:write` (+ `secrets:write`) | نعم | دائماً |
| `proxmox_list` | مجموعات Proxmox VE المضافة كمصادر، مع حالتها الصحية. | `admin:read` | No | No |
| `proxmox_add` | إضافة مجموعة Proxmox VE باستخدام رمز API (`user@realm!tokenid`) وسره. | `infra:write` (+ `secrets:write`) | نعم | No |
| `proxmox_test` | الاتصال بمجموعة عن طريق المعرف؛ أول عملية ناجحة تثبت شهادة TLS الخاصة بها. | `infra:write` | نعم | No |
| `proxmox_attach_zone` | بيع مجموعة Proxmox في منطقة موجودة، اختيارياً مع عقدة كنطاق. | `infra:write` | نعم | No |
| `zones_list` | المناطق (المواقع) التي يمكن للعملاء اختيارها. | `admin:read` | No | No |
| `zone_create` | إنشاء منطقة. | `infra:write` | نعم | No |

### الكتالوج والخطط {#catalog-and-plans}

| الأداة | الوظيفة | النطاق | Changes data | Asks you |
|---|---|---|---|---|
| `templates_list` | قوالب نظام التشغيل التي يمكن للعملاء تثبيتها. | `admin:read` | No | No |
| `templates_sync` | استيراد قوالب نظام التشغيل من CloudStack. | `catalog:write` | نعم | No |
| `template_update` | تفعيل أو إخفاء قالب، أو إعادة تسميته، أو تعيين مستخدم تسجيل الدخول أو الترتيب. | `catalog:write` | نعم | No |
| `offerings_list` | عروض خدمات CloudStack (وحدة المعالجة المركزية، والذاكرة، القرص الجذر) لبناء الخطط منها. | `admin:read` | No | No |
| `plans_list` | خطط بسعر لكل ساعة وكل شهر، الحجم، والمنطقة، وعدد الخوادم التي تستخدمها. | `admin:read` | No | No |
| `plan_create` | إنشاء خطة. السعر كـ `hourly_usd`. تحتاج خطط CloudStack إلى `cs_offering_id`؛ بينما تحتاج خطط Proxmox إلى `backend_id`. | `catalog:write` | نعم | No |
| `plan_update` | إعادة تسمية، أو إظهار أو إخفاء، أو تفعيل أو تعطيل، أو إعادة تسعير خططة. تغييرات الحجم على خطة قيد الاستخدام تتطلب نسخة. | `catalog:write` | نعم | عند تغيير السعر |
| `plans_from_offerings` | بناء جدول خطط بداية من العروض (أو أحجام Proxmox) باستخدام تكلفتك ونسبة هامش الربح. يعيد معاينة؛ اطلب مرة أخرى مع `apply=true` لإنشاء الخطط. | `catalog:write` | مع `apply=true` | دائم التشغيل عند التطبيق |
| `quota_defaults_get` | حدود العملاء الافتراضية. | `admin:read` | No | No |
| `quota_defaults_set` | تغيير إعدادات `quota_*`. | `catalog:write` | نعم | No |
| `coupons_list` | دفعات أكواد الخصم والهدايا. | `admin:read` | No | No |
| `coupon_create` | إنشاء دفعة من الأكواد: النوع `money` (القيمة الاسمية بالسنت الأمريكي) أو `percent` (من 1 إلى 100، مع خصم أقصى). | `catalog:write` | نعم | دائماً |

### العملاء والشركاء {#customers-and-resellers}

| الأداة | الوظيفة | النطاق | Changes data | Asks you |
|---|---|---|---|---|
| `customers_search` | البحث عن العملاء بالبريد الإلكتروني، أو الاسم، أو عنوان IP. | `admin:read` | No | No |
| `customer_get` | حساب العميل، ورصيده، وخوادمه، وفواتيره الأخيرة. | `admin:read` | No | No |
| `customer_adjust_balance` | إضافة رصيد (موجب) أو إزالته (سالب) بالسنت الأمريكي. السبب مطلوب. | `billing:write` | نعم | دائماً |
| `customer_block` | حظر عميل، مع إيقاف خوادمه اختيارياً. السبب مطلوب. | `customers:write` | نعم | دائماً |
| `customer_unblock` | إلغاء حظر عميل. | `customers:write` | نعم | No |
| `resellers_list` | الشركاء مع المحفظة والحالة. | `admin:read` | No | No |
| `reseller_get` | موقع الشريك، ومحفظته، ومستخدموه، وبوابات الدفع الخاصة به. | `admin:read` | No | No |

### مزود الذكاء الاصطناعي {#ai-provider}

| الأداة | الوظيفة | النطاق | Changes data | Asks you |
|---|---|---|---|---|
| `ai_provider_get` | المزود المتوافق مع OpenAI المستخدم بواسطة AI Chat للعملاء و AI Agent (المفتاح مخفي). | `admin:read` | No | No |
| `ai_provider_set` | تعيين المزود: عنوان URL الأساسي، النموذج، مفتاح API، النماذج البديلة، جهد الاستدلال، والتفعيل. | `ai:write` (+ `secrets:write` للمفتاح) | نعم | No |
| `ai_provider_test` | طرح سؤال واحد على المزود المحفوظ للتحقق من عمله. | `ai:write` | No | No |

### ملفات التكوين {#configuration-files}

| الأداة | الوظيفة | النطاق | Changes data | Asks you |
|---|---|---|---|---|
| `config_export` | تصدير التكوين بتنسيق YAML (تصبح الأسرار مراجع `secret://`). | `admin:read` | No | No |
| `config_plan` | مقارنة تكوين YAML مع اللوحة النشطة وسرد ما سيتم تغييره. | `admin:read` | No | No |
| `config_apply` | تطبيق تكوين YAML قسمًا بقسم. يتبع كل تغيير قواعد النطاق والتأكيد العادية. | `admin:read` + نطاق كل تغيير | نعم | لكل تغيير |

راجع [Configuration as code](https://nexcmp.com/ar/docs/configure-with-ai/config-as-code/) لمعرفة تنسيق الملف.

## الموجهات {#prompts}

يوفر الخادم أيضاً ثلاثة موجهات جاهزة يمكن للعملاء عرضها كاختصارات:

| الموجه | الوسيط | ما يطلب من الذكاء الاصطناعي فعله |
|---|---|---|
| `initial-setup` | لا يوجد | استدعاء `setup_checklist`، وشرح كل خطوة مفتوحة في جملة واحدة، وطلب المعلومات التي يحتاجها منك، وتنفيذ الخطوة باستخدام الأداة المطابقة، ومعاينة تغييرات الأموال أو الأمان، والإنهاء بـ `system_health`. |
| `add-proxmox` | `endpoint` (اختياري، `https://host:8006`) | طلب رمز API، ثم `proxmox_add`، و`proxmox_test`، وأدوات المنطقة، و`proxmox_attach_zone`؛ ثم اقتراح الخطط باستخدام `plans_from_offerings` وانتظار موافقتك. |
| `launch-pricing` | `margin_pct` (اختياري، الافتراضي 40) | اطلب تكلفك الشهرية لكل vCPU، ولكل غيغابايت من ذاكرة الوصول العشوائي (RAM)، ولكل غيغابايت من القرص، وأظهر جدول معاينة بالتكلفة، والسعر شهرياً، والسعر بالساعة، وأنشئ الخطط بعد موافقتك. |

## التأكيد (`confirm_token`) {#confirmation-confirm-token}

الإجراءات التي تنقل الأموال، أو تحذف البيانات، أو تغيّر بيانات اعتماد الدفع، أو أمان تسجيل الدخول تتطلب خطوتين:

1. الاستدعاء الأول لا يغير شيئاً. تبدأ نتيجة الأداة بعبارة "CONFIRMATION REQUIRED" وتتضمن **معاينة** (ما سيتم استدعاؤه، ولماذا يعتبر حساساً، والقيم الجديدة والحالية) و `confirm_token`.
2. يجب أن يعرض لك العميل المعاينة. وفقط بعد موافقتك، يقوم باستدعاء نفس الأداة مرة أخرى مع نفس الوسائط بالإضافة إلى `confirm_token`.
3. الرمز صالح لمرة واحدة، ولذلك الطلب المحدد فقط، وتنتهي صلاحيته بعد 5 دقائق.

تخبر تعليمات الخادم الذكاء الاصطناعي بمعاملة نتائج الأدوات كبيانات وليس كتعليمات، وألا يكرر الاستدعاء أبداً باستخدام رمز لم تقم بالموافقة عليه. أنت خط الدفاع: اقرأ المعاينة.

::: warning لا تقم بالموافقة التلقائية
يمكن لبعض العملاء الموافقة على كل استدعاء للأداة تلقائياً. بالنسبة لأدوات الكتابة، حافظ على تفعيل الموافقة لكل استدعاء، أو استخدم مفتاحاً للقراءة فقط، حتى لا يتمكن خطأ من الذكاء الاصطناعي من الوصول إلى لوحتك دون ملاحظة.
:::

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

| العنصر | التفاصيل |
|---|---|
| النقل | `POST /mcp/admin` مع رسالة JSON-RPC 2.0؛ الإجابة هي `application/json`. ما يصل إلى 20 رسالة في الدفعة الواحدة. `GET /mcp/admin` تعيد الخطأ 405 (لا يوجد تدفق للخادم)؛ `DELETE /mcp/admin` تنهي الجلسة. |
| المصادقة | `Authorization: Bearer ak_...` (مفتاح يدوي أو رمز وصول OAuth). بيانات الاعتماد المفقودة أو الخاطئة تعطي الرمز 401 مع `WWW-Authenticate: Bearer ... resource_metadata=...`، مما يسمح لعملاء OAuth بدء تسجيل الدخول بأنفسهم. |
| الجلسات | `Mcp-Session-Id` يتم إصدارها بواسطة `initialize`، ومرتبطة بهذا المفتاح وصالحة لمدة 24 ساعة. |
| القدرات | الأدوات والتعليمات. لا توجد موارد. |
| الحجم | جسم الطلب حتى 1 ميجابايت؛ ويتم قطع نتيجة الأداة بعد حوالي 100 كيلوبايت. |
| المصدر | يتم رفض الطلب الذي يحمل رأس `Origin` من موقع آخر (`origin_not_allowed`). لا يرسل عملاء سطر الأوامر وتطبيقات سطح المكتب أي شيء. |
| نفس بوابة REST | يتم إعادة إرسال كل استدعاء للأداة عبر خط أنابيب الطلبات الخاص باللوحة باستخدام مفتاحك، بحيث يتم تطبيق النطاقات، ونطاقات IP، ومعدل الحدود، والتؤكيد، وسجل النشاط تماماً كما هو الحال في طلبات API المباشرة. |

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

- الأداة التي لا يمكنك رؤيتها هي نطاق لم تقم بمنحه. أضف النطاق إلى مفتاح جديد.
- تعيين كلمة مرور أو مفتاح API من خلال عميل ذكاء اصطناعي يعني أن السر يمر عبر ذلك الذكاء الاصطناعي. إذا كنت تفضل ذلك، فاترك `secrets:write` معطلاً وأدخل الأسرار بنفسك في لوحة المشرف، أو استخدم حقل **Secret** في AI Chat (انظر [AI Chat in the admin](https://nexcmp.com/ar/docs/configure-with-ai/ai-chat-in-admin/#secrets)) أو مراجع `secret://` (انظر [Configuration as code](https://nexcmp.com/ar/docs/configure-with-ai/config-as-code/#secrets)).
- لا يتشارك العملاء الجلسات: تبدأ كل عملية اتصال بـ `initialize`.
- قم بإلغاء المفتاح في قسم **API & AI agents** لقطع الاتصال عن عميل الذكاء الاصطناعي فوراً.

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

| العَرَض | السبب | الحل |
|---|---|---|
| 401 `invalid_key` | مفتاح خاطئ أو مقتطع أو ليس لصلاحيات المشرف (على سبيل المثال مفتاح `vk_`) | استخدم مفتاح `ak_`. |
| 401 `key_expired` أو `key_revoked` | انتهت صلاحية المفتاح أو تم إلغاؤه | أنشئ مفتاحاً جديداً. |
| 403 `ip_not_allowed` | عنوان IP الخاص بك خارج نطاقات IP الخاصة بالمفتاح | اتصل من عنوان IP مسموح به. |
| 403 `origin_not_allowed` | استدعت صفحة متصفح على مصدر آخر نقطة النهاية | استخدم عميل سطح مكتب أو CLI. |
| 404 في طلب يحتوي على `Mcp-Session-Id` | الجلسة تنتمي إلى مفتاح آخر أو انتهت صلاحيتها | أرسل `initialize` مرة أخرى. |
| 400 `MCP-Protocol-Version` غير مدعوم | يستخدم العميل إصداراً لا يتعرف عليه الخادم | قم بتحديث العميل؛ المدعومة: 2025-11-25، 2025-06-18، 2025-03-26. |
| قائمة الأدوات قصيرة | نطاقات المفاتيح | أنشئ مفتاحاً بنطاقات أكثر. |
| `insufficient_scope` أثناء المكالمة | الأداة تحتاج إلى نطاق (scope) ثانٍ، على سبيل المثال `secrets:write` | أضف النطاق إلى مفتاح جديد. |
| 429 `rate_limited` | عدد مكالمات في الدقيقة أكبر مما يسمح به المفتاح | انتظر لمدة `Retry-After` أو ارفع الحد على مفتاح جديد. |
| claude.ai أو ChatGPT لا يمكنهما الاتصال | عنوان URL غير قابل للوصول من الإنترنت، أو أن وكيلًا (proxy) يحظر `/mcp/admin` أو `/oauth-admin/` | تحقق من نظام الأسماء النطاقية (DNS) و TLS والوكيل العكسي (reverse proxy). |

لجميع رموز الأخطاء، راجع [Admin API keys](https://nexcmp.com/ar/docs/configure-with-ai/admin-api-keys/#errors).