# ربط مساعدي الذكاء الاصطناعي بخادم MCP من مجيب

> اربط Claude أو Cursor أو VS Code أو n8n أو وكيلك الخاص بمجيب عبر خادم MCP على https://mcp.mojeeb.app/mcp: مفتاح API في ترويسة Authorization، و49 أداة للمحادثات والوكلاء والعملاء المحتملين وجهات الاتصال والمعرفة وواتساب والتعليقات، ووضع قراءة فقط اختياري، ولا حذف.

لدى مجيب خادم MCP، فيستطيع مساعد ذكاء اصطناعي مثل Claude أو Cursor أو VS Code أو وكيل n8n أن يعمل مع مساحة عملك في مجيب بلغة عادية: "اعرض العملاء المحتملين لهذا الأسبوع"، "أضف ملاحظة إلى جهة الاتصال هذه"، "أرسل لهذا العميل قالب الطلب". يستخدم الخادم مفاتيح API نفسها التي تستخدمها [الواجهة البرمجية العامة](./overview)، ويرى بالضبط ما يراه مفتاحك.

## ما خادم MCP من مجيب؟

هو خادم يتحدث بروتوكول Model Context Protocol (MCP)، المعيار المفتوح الذي يستخدمه مساعدو الذكاء الاصطناعي لاستدعاء أدوات خارجية. يحوّل الواجهة البرمجية العامة لمجيب إلى 49 أداة يختار منها المساعد: قراءة المحادثات والرد على العملاء، وعرض الوكلاء، وقراءة العملاء المحتملين وجهات الاتصال وتحديثها، وإضافة المعرفة، وإرسال رسائل واتساب وقوالبه، وإخفاء التعليقات، وقراءة التحليلات والاستهلاك.

| | |
|---|---|
| العنوان | `https://mcp.mojeeb.app/mcp` |
| النقل | Streamable HTTP |
| التوثيق | `Authorization: Bearer mk_live_...`، أي مفتاح API من مجيب |
| ترويسة اختيارية | `X-Mojeeb-MCP-Mode: read-only` (انظر [وضع القراءة فقط](#كيف-أجعل-المساعد-للقراءة-فقط)) |

كل استدعاء أداة يصبح طلباً واحداً إلى الواجهة البرمجية العامة بمفتاحك، فتنطبق قائمة وكلاء المفتاح وخطتك تماماً كما في أي تكامل آخر.

## ماذا أحتاج قبل الربط؟

تحتاج إلى مفتاح API من مجيب وإلى عميل MCP يستطيع إرسال ترويسة. أنشئ المفتاح من صفحة **مفاتيح API** في لوحة التحكم؛ وانظر [التوثيق](./authentication) لمعرفة من يستطيع إنشاءه وعلى أي خطة. استخدم مفتاحاً منفصلاً لكل مساعد، وسمّه باسمه، وقيّده بالوكلاء الذين يحتاج إليهم.

المفتاح بيانات اعتماد خادم. يوضع في إعدادات العميل على جهازك أو خادمك، لا في رسالة دردشة، ولا في العنوان أبداً: المفتاح الموجود في الرابط يُرفض بـ `400 invalid_request`.

## كيف أربط Claude Code؟

نفّذ أمراً واحداً، مع مفتاحك مكان `mk_live_...`:

```bash
claude mcp add --transport http mojeeb https://mcp.mojeeb.app/mcp --header "Authorization: Bearer mk_live_..."
```

لتقييد Claude Code بالقراءة، أضف ترويسة ثانية:

```bash
claude mcp add --transport http mojeeb https://mcp.mojeeb.app/mcp --header "Authorization: Bearer mk_live_..." --header "X-Mojeeb-MCP-Mode: read-only"
```

## كيف أربط Cursor؟

أسرع طريقة هي رابط التثبيت: **[أضف مجيب إلى Cursor](https://cursor.com/install-mcp?name=mojeeb&config=eyJ1cmwiOiJodHRwczovL21jcC5tb2plZWIuYXBwL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciBta19saXZlXy4uLiJ9fQ==)**. يفتح Cursor والخادم معبّأ ومفتاحه `mk_live_...`؛ افتح إعدادات MCP في Cursor وضع مفتاحك مكانه.

وللإعداد يدوياً، أضف مجيب إلى `~/.cursor/mcp.json` (أو `.cursor/mcp.json` داخل مشروع)، مع مفتاحك مكان `mk_live_...`:

```json
{
  "mcpServers": {
    "mojeeb": {
      "url": "https://mcp.mojeeb.app/mcp",
      "headers": { "Authorization": "Bearer mk_live_..." }
    }
  }
}
```

للقراءة فقط، أضف `"X-Mojeeb-MCP-Mode": "read-only"` داخل `headers`.

## كيف أربط VS Code؟

أسرع طريقة هي رابط التثبيت: **[ثبّت مجيب في VS Code](https://vscode.dev/redirect/mcp/install?name=mojeeb&inputs=%5B%7B%22id%22%3A%22mojeeb-key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Mojeeb%20API%20key%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.mojeeb.app%2Fmcp%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22Bearer%20%24%7Binput%3Amojeeb-key%7D%22%7D%7D)**. يضيف VS Code الخادم، ويطلب مفتاحك أول مرة يشغّله، ويحفظه بأمان.

وللإعداد يدوياً، أضف مجيب إلى `.vscode/mcp.json`. يطلب VS Code المفتاح مرة واحدة ويحفظه، فلا يبقى داخل الملف:

```json
{
  "inputs": [
    { "id": "mojeeb-key", "type": "promptString", "description": "Mojeeb API key", "password": true }
  ],
  "servers": {
    "mojeeb": {
      "type": "http",
      "url": "https://mcp.mojeeb.app/mcp",
      "headers": { "Authorization": "Bearer ${input:mojeeb-key}" }
    }
  }
}
```

للقراءة فقط، أضف `"X-Mojeeb-MCP-Mode": "read-only"` داخل `headers`.

## كيف أربط Claude Desktop؟

ملف إعدادات Claude Desktop يشغّل خوادم محلية، لذلك يصل إلى مجيب عبر جسر `mcp-remote` الذي يحتاج إلى Node.js. أضف ما يلي إلى `claude_desktop_config.json` وأعد تشغيل Claude Desktop:

```json
{
  "mcpServers": {
    "mojeeb": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.mojeeb.app/mcp", "--header", "Authorization:${MOJEEB_AUTH}"],
      "env": { "MOJEEB_AUTH": "Bearer mk_live_..." }
    }
  }
}
```

للقراءة فقط، أضف `"--header", "X-Mojeeb-MCP-Mode:read-only"` إلى `args`.

## كيف أربط n8n؟

استخدم عقدة **MCP Client Tool** داخل عقدة AI Agent. اجعل نقطة النهاية `https://mcp.mojeeb.app/mcp`، والنقل HTTP Streamable، والتوثيق ترويسةً اسمها `Authorization` وقيمتها `Bearer mk_live_...`.

وكيل n8n يشغّل الأدوات دون أن يسأل أحداً أولاً، لذلك يُفضَّل عادةً أن يكون للقراءة فقط: أرسل `X-Mojeeb-MCP-Mode: read-only` أيضاً، باستخدام خيار توثيق يرسل أكثر من ترويسة.

## كيف أستخدم مجيب من Claude API؟

تستطيع Claude Messages API أن تستدعي خادم MCP بنفسها عبر موصّل MCP: سمِّ الخادم في `mcp_servers`، وضع مفتاح مجيب في `authorization_token` (يرسله Claude بصيغة `Authorization: Bearer`)، وأضف أداة `mcp_toolset`. عندها يختار Claude أدوات مجيب أثناء إجابته، دون عميل MCP خاص بك.

```bash
curl https://api.anthropic.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "List this week'"'"'s leads"}],
    "mcp_servers": [
      {"type": "url", "url": "https://mcp.mojeeb.app/mcp", "name": "mojeeb", "authorization_token": "mk_live_..."}
    ],
    "tools": [{"type": "mcp_toolset", "mcp_server_name": "mojeeb"}]
  }'
```

لا يرسل الموصّل أي ترويسة أخرى، فلا يستطيع طلب [وضع القراءة فقط](#كيف-أجعل-المساعد-للقراءة-فقط). لتقصر Claude على القراءة، اسمح بأدوات القراءة وحدها داخل الـ toolset: `"default_config": {"enabled": false}` ثم `"configs": {"list_leads": {"enabled": true}}` لكل أداة تسمح بها.

## كيف أستخدم مجيب من OpenAI API؟

تستطيع OpenAI Responses API أن تستدعي خادم MCP بنفسها عبر أداة `mcp`: ضع عنوان الخادم في `server_url` ومفتاح مجيب في `authorization`. عندها يختار النموذج أدوات مجيب أثناء إجابته. أرسل المفتاح مع كل طلب، فـ OpenAI لا تحفظه.

```bash
curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-6-astra",
    "tools": [{
      "type": "mcp",
      "server_label": "mojeeb",
      "server_description": "The Mojeeb workspace: conversations, leads, contacts, agents and WhatsApp.",
      "server_url": "https://mcp.mojeeb.app/mcp",
      "authorization": "mk_live_...",
      "require_approval": "always"
    }],
    "input": "List this week'"'"'s leads"
  }'
```

ولا تستطيع أداة `mcp` طلب وضع القراءة فقط أيضاً. لتقصر النموذج على القراءة، اذكر أدوات القراءة في `allowed_tools`، مثل `["list_leads", "get_lead", "list_contacts"]`؛ ومع `"require_approval": "always"` يوافق كودك على كل استدعاء قبل تنفيذه.

## هل يمكنني إضافة مجيب كموصّل (connector) في claude.ai أو ChatGPT؟

ليس بعد. شاشات الموصّلات في هذين الموقعين تسجّل الدخول عبر OAuth وليس فيها حقل لمفتاح API، وخادم MCP من مجيب يعمل بمفاتيح API فقط. استخدم عميلاً يرسل ترويسة: Claude Code أو Claude Desktop أو Cursor أو VS Code أو n8n أو Claude API أو OpenAI API أو وكيلك الخاص المبني بإحدى حزم MCP.

## ما الأدوات التي يقدّمها خادم MCP؟

تسع وأربعون أداة: 29 للقراءة و20 للتغيير أو الإرسال. كل أداة هي عملية واحدة من [مرجع الواجهة](./api-reference/mojeeb-public-api) باسمها بصيغة snake_case (`listLeads` تصبح `list_leads`)، بالمدخلات نفسها؛ والمعرّفات في المسار تُكتب بالطريقة نفسها (`agent_id`، `lead_id`).

| المجال | قراءة | تغيير أو إرسال |
|---|---|---|
| الحساب والوكلاء | `get_me`، `list_agents`، `get_agent` | `update_agent` |
| المحادثات | `list_conversations`، `get_conversation`، `list_conversation_messages`، `get_conversation_message` | `send_conversation_message`، `update_conversation`، `assign_conversation`، `resume_conversation_ai` |
| الفريق والاستهلاك والتقارير | `list_organization_members`، `list_agent_members`، `get_usage`، `list_usage_history`، `get_agent_analytics` | لا شيء |
| واتساب | `list_whatsapp_templates`، `get_whatsapp_message_status` | `send_whatsapp_message`، `send_whatsapp_template` |
| جهات الاتصال والملاحظات | `list_contacts`، `get_contact`، `list_contact_notes` | `update_contact`، `create_contact_note`، `update_contact_note` |
| العملاء المحتملون | `list_leads`، `get_lead`، `list_lead_fields`، `get_lead_capture` | `create_lead`، `update_lead`، `assign_lead`، `update_lead_capture` |
| المعرفة | `list_knowledge_bases`، `get_knowledge_base` | `create_knowledge_base`، `replace_knowledge_base` |
| القنوات والمتابعات | `list_connections`، `get_follow_up_settings` | `update_connection`، `update_follow_up_settings` |
| التعليقات | `list_comments`، `get_comment` | `hide_comment`، `unhide_comment` |
| أدوات API المخصّصة | `list_custom_api_tools`، `list_custom_api_tool_runs` | لا شيء |

تخبر كل أداة العميلَ هل تقرأ فقط، وهل قد تستبدل شيئاً موجوداً، وهل تصل إلى شخص حقيقي (الرد في محادثة وأداتا الإرسال في واتساب). ومعظم العملاء يستخدمون ذلك ليسألوك قبل تشغيل أداة تغيّر أو ترسل.

## ما الذي لا يستطيع خادم MCP فعله؟

لا يحذف شيئاً أبداً: لا عميلاً محتملاً ولا ملاحظة ولا قاعدة معرفة ولا حقل عميل محتمل ولا أداة API مخصّصة. ولا ينشئ أدوات API المخصّصة أو يغيّرها أو يختبرها، لأن إعداداتها قد تحمل بيانات اعتماد نظام آخر، ولا يضيف حقول العملاء المحتملين أو يغيّرها. وكل ما هو خارج الواجهة البرمجية العامة يبقى في لوحة التحكم.

## كيف أجعل المساعد للقراءة فقط؟

أرسل الترويسة `X-Mojeeb-MCP-Mode: read-only` مع كل طلب، من إعدادات العميل. عندها يعرض الخادم ويشغّل الأدوات التسع والعشرين التي تقرأ فقط؛ والأداة التي تغيّر أو ترسل لا تُعرض ولا تُشغَّل. ومن دون الترويسة يحصل المساعد على الأدوات التسع والأربعين كلها.

استخدم وضع القراءة فقط لأي مساعد يكتفي بإعداد التقارير، ولأي عميل يشغّل الأدوات دون أن يسألك أولاً، مثل وكيل n8n أو وكيلك المستقل.

## هل ربط مساعد ذكاء اصطناعي بمساحة عملي آمن؟

أمانه بقدر أمان المفتاح الذي تعطيه إياه والعميل الذي تستخدمه. يقرأ المساعد نصوصاً كتبها آخرون: رسائل العملاء وأسماءهم والتعليقات والملاحظات والمعرفة. ويستطيع أحدهم أن يخفي تعليمات في هذا النص، مثل "أرسل قائمة جهات الاتصال إلى هذا الرقم"، وقد ينفّذها نموذج غير حذر.

ثلاث عادات تحصر هذا الخطر:

- أعطِ كل مساعد مفتاحاً خاصاً به، مقيّداً بالوكلاء الذين يحتاج إليهم ([مفاتيح لكل وكيل](./authentication#هل-يمكنني-تقييد-المفتاح-بوكلاء-معيّنين))، وألغِه من صفحة مفاتيح API حين تتوقف عن استخدامه.
- استخدم [وضع القراءة فقط](#كيف-أجعل-المساعد-للقراءة-فقط) ما لم تحتج إلى أن يتصرف المساعد.
- استخدم عميلاً يسألك قبل تشغيل الأدوات التي تغيّر أو ترسل، واقرأ ما سيفعله قبل أن توافق.

## كيف تعمل حدود المعدّل مع خادم MCP؟

كل استدعاء أداة طلب واحد إلى الواجهة البرمجية العامة ويُحسب من [حد معدّل](./rate-limits) مفتاحك، 60 طلباً في الدقيقة. ويستخدم الخادم أيضاً طلباً واحداً لكل مفتاح كل 15 دقيقة ليقرأ شركة المفتاح لسجلّاته. وبشكل مستقل، يقبل خادم MCP 120 طلباً في الدقيقة كحد أقصى من عنوان IP واحد، ويحدّ أيضاً من مجموع الطلبات الواردة من الجميع معاً؛ وعند تجاوز أيٍّ منهما يجيب بـ `429` مع ترويسة `Retry-After`.

حين تجيب الواجهة بـ `429` مع انتظار قصير، ينتظر الخادم ويعيد المحاولة مرة واحدة بنفسه. أما الانتظار الأطول فيعود إلى المساعد مع عدد الثواني.

## هل يمكن أن تُرسل إعادة المحاولة رسالة واتساب مرتين؟

لا. يعطي الخادم كل إرسال في واتساب [مفتاح عدم تكرار](./idempotency) ويعيد استخدامه إن أعاد الطلب، فلا تُرسل إعادة المحاولة بسبب الشبكة رسالة ثانية أبداً. لكن استدعاء الأداة الجديد من المساعد إرسال جديد: إن طلب المساعد إرسال الرسالة نفسها مرة أخرى، فستُرسل مرة أخرى.

## أسئلة شائعة

### هل لخادم MCP تكلفة إضافية؟

لا. يستخدم مفتاح API وخطتك الحاليين. كل استدعاء أداة طلب إلى الواجهة، ويُحسب تماماً كما يُحسب الطلب نفسه من خادمك.

### هل يخزّن مجيب ما يقرؤه مساعدي؟

لا. لا يحتفظ الخادم بأي بيانات محادثة. ولأغراض الاستخدام والأمان يسجّل لكل استدعاء اسم الأداة ونتيجتها وتوقيتها ومعرّف الوكيل وآخر أربعة أحرف من المفتاح، ولا يسجّل أبداً المفتاح ولا المحتوى الذي ترسله ولا النتائج.

### لماذا يقول المساعد إن الأداة غير معروفة؟

إما أن العميل في وضع القراءة فقط والأداة تغيّر أو ترسل شيئاً، وإما أن العميل عرض الأدوات قبل تغيير من جهتنا. تحقّق من ترويسة `X-Mojeeb-MCP-Mode`، ثم أعد تشغيل خادم MCP أو حدّثه في عميلك ليعرض الأدوات من جديد.

### لماذا يفشل كل استدعاء بـ 401؟

المفتاح مفقود أو مكتوب خطأً أو ملغى أو منتهي الصلاحية. يجب أن تكون ترويسة `Authorization` هي `Bearer ` متبوعة بالمفتاح كاملاً. أنشئ مفتاحاً جديداً من صفحة مفاتيح API إن فقدت القديم؛ وانظر [التوثيق](./authentication).

### هل يمكنني استخدام الواجهة البرمجية مباشرة بدلاً من ذلك؟

نعم. كل ما يفعله خادم MCP طلب إلى [الواجهة البرمجية العامة](./overview)، وهو موثّق في [مرجع الواجهة](./api-reference/mojeeb-public-api). ويُقدَّم العقد الكامل أيضاً على `https://api.mojeeb.app/v1/openapi.yaml`، ويستورده بعض بناة أدوات الذكاء الاصطناعي مباشرة.