---
type: how-to
title: استخدم خادم MCP
summary: اربط وكيل ذكاء اصطناعي بـ Caputchin عبر خادم MCP، وصادقه برمز وصول، وقُد API الإدارة بلغة طبيعية، مع مثال مشروح.
---

يتيح خادم MCP الخاص بـ Caputchin لوكيل ذكاء اصطناعي (Claude، أو Cursor، أو أي عميل [Model Context Protocol](https://modelcontextprotocol.io)) أن يدير حسابك بنداء [API الإدارة](/docs/automation/management-api) نفسه الذي تستخدمه لوحة التحكّم. الخادم غلاف نقل ومصادقة رفيع: يكشف أداة MCP واحدة لكل عملية إدارة ويوكّل كل نداء إلى الـ API. فيستطيع الوكيل فعل كل ما تستطيعه، ما عدا الفوترة، بلغة طبيعية.

## اسكك رمز وصول [#mint-an-access-token]

يصادق الخادم برمز وصول من متغيّر البيئة `CAPUTCHIN_TOKEN`. كلا النوعين يعمل (انظر [مصادقة الـ API](/docs/automation/management-api#mint-an-access-token)):

- [رمز وصول شخصي](/docs/account-management/personal-access-token) للتحكّم بالحساب الكامل، أو
- [رمز وصول فريق](/docs/troops/tokens) لحصر الوكيل بفرق بعينها بالامتياز الأدنى، وهو الافتراضي الأأمن عند تسليم الوصول لوكيل مستقلّ.

انسخ الرمز عند الإنشاء؛ يُعرَض مرة واحدة.

## طريقتان للاتّصال

هناك ناقلان، ويكشفان **الأدوات نفسها** مدعومةً بـ API الإدارة نفسه. اختر بحسب كيف يتّصل عميلك:

| | محلّي (stdio) | مُستضاف (HTTP) |
|---|---|---|
| ما هو | حزمة `@caputchin/mcp`، تعمل على جهازك | نقطة وصول بعيدة عند `api.caputchin.com/mcp` |
| يحتاج العميل إلى | توليد عملية محلّية (stdio) | الاتّصال بخادم MCP بعيد (HTTP) |
| المصادقة | `CAPUTCHIN_TOKEN` في بيئة العملية | ترويسة `Authorization: Bearer` على الاتّصال |
| الأفضل حين | التطوير المحلّي، عميل مكتبي، لا شبكة واردة | وكيل مُستضاف، لا عملية محلّية لتوليدها |

### محلّي: خادم npx‏ (stdio)

يُنشَر الخادم كـ `@caputchin/mcp` على npm. عادةً لا تشغّله يدويًّا؛ تربطه في إعداد عميل MCP خاصتك فيُولَّد عبر stdio، بالرمز في بيئته:

```json
{
  "mcpServers": {
    "caputchin": {
      "command": "npx",
      "args": ["-y", "@caputchin/mcp"],
      "env": { "CAPUTCHIN_TOKEN": "cpt_pat_..." }
    }
  }
}
```

للتحقّق من أنه يعمل، أطلقه مباشرةً؛ يتكلّم MCP عبر stdio ويخرج بخطأ إن كان الرمز مفقودًا:

```bash
CAPUTCHIN_TOKEN=cpt_pat_... npx -y @caputchin/mcp
```

### مُستضاف: نقطة وصول HTTP

للعملاء الذين يتّصلون بخادم MCP بعيد بدل توليد محلّي، يستضيف Caputchin الخادم نفسه عند:

```
https://api.caputchin.com/mcp
```

يصادق برمزك كترويسة `Bearer` على الاتّصال (الاعتماد نفسه، ممرَّرًا عبر HTTP بدل البيئة فقط):

```json
{
  "mcpServers": {
    "caputchin": {
      "url": "https://api.caputchin.com/mcp",
      "headers": { "Authorization": "Bearer cpt_pat_..." }
    }
  }
}
```

يعتمد شكل الإعداد الدقيق على عميل MCP خاصتك؛ ما يهمّ هو الرابط وترويسة `Authorization: Bearer`. لا شيء لتثبيته، ولا عملية محلّية؛ المقايضة أن الرمز يسافر إلى نقطة الوصول المُستضافة لكل طلب بدل البقاء في بيئة عملية محلّية.

## الأدوات

كل أداة مسمّاة `caputchin_<verb>_<noun>` وتقابل عملية إدارة واحدة، مثلًا `caputchin_list_troops`، و`caputchin_create_site`، و`caputchin_rotate_site_secret`، و`caputchin_add_troop_member`، و`caputchin_site_stats`. يكتشف الوكيل المجموعة الكاملة ومعاملات كل أداة تلقائيًّا عبر MCP، فتصف الهدف ويختار الوكيل الأدوات.

## مثال مشروح

مع الخادم مربوطًا في عميلك، تستطيع أن تطلب من الوكيل بلغة عادية:

> "أنشئ مفتاح موقع اسمه shop-frontend في فريقي shop-team، ثم شغّل بوّابة اللعبة له."

يحلّ الوكيل ذلك إلى سلسلة نداءات أدوات: `caputchin_list_troops` لإيجاد معرّف الفريق، و`caputchin_create_site` بذلك `troop_id`، ثم `caputchin_update_site_security` لاشتراط لعبة. كل نداء يصيب API الإدارة تحت رمزك، وعلى Apex يحطّ كلٌّ في [سجلّ تدقيقك](/docs/audit-logs/overview) منسوبًا إلى الرمز، فتكون أفعال الوكيل قابلة للتتبّع كأفعال شخص.

ولأن الوكيل يعمل بكامل امتداد رمزك، آثِر رمز فريق محصورًا متى أمكن، وألغِه لحظة انتهاء المهمّة.

## المرجع الكامل

للقائمة الكاملة للأدوات، لكلٍّ وصف بسطر واحد والصلاحية التي يجب أن يحملها رمزها، انظر [مرجع أدوات MCP](/docs/automation/mcp-tools). تعكس الأدوات API الإدارة واحدةً بواحدة، فـ[مرجع الـ API التفاعلي](/docs/api-reference) هو الوصف الموثوق لمعاملات كل عملية واستجابتها: اقرأ وصف MCP لأداة للملخّص المواجِه للوكيل، ومرجع الـ API للمخطّط الدقيق.

## انظر أيضًا

- [مرجع أدوات MCP](/docs/automation/mcp-tools): كل أداة، ووصفها، والصلاحية التي تحتاجها.
- [أدِر Caputchin من الـ API](/docs/automation/management-api): API عبر HTTP الذي تناديه كل أداة.
- [استخدم Terraform أو OpenTofu](/docs/automation/terraform): سطح البنية التحتية ككود.
- [رمز الوصول الشخصي](/docs/account-management/personal-access-token) و[رموز الفرق](/docs/troops/tokens): الاعتمادات التي يستخدمها الخادم.