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

Your AI Connector توفر خادم MCP رسميًا — وهو نقطة نهاية لبروتوكول سياق النموذج (Model Context Protocol) تسمح لمساعدي الذكاء الاصطناعي مثل Claude Code و Claude Desktop و Cursor وتطبيقاتك الخاصة بالتحكم في حساب Your AI Connector الخاص بك مباشرة. اطلب بلغة بسيطة (“اعرض وكلاء الذكاء الاصطناعي الخاصين بي”، “أضف هذا العميل المحتمل”، “ما هي تكلفة الذكاء الاصطناعي علي هذا الأسبوع؟”) وسيقوم المساعد باستدعاء واجهة برمجة تطبيقات Your AI Connector نيابة عنك.

إنها نفس واجهة برمجة التطبيقات v1 التي تصل إليها باستخدام مفتاح API، والتي يتم المصادقة عليها باستخدام مفتاح API الخاص بك. يقوم خادم MCP بإنشاء أداة واحدة لكل عملية في مواصفات واجهة برمجة التطبيقات المنشورة لدينا، لذا فهي تغطي معظم واجهة برمجة التطبيقات v1، ولكن ليس كلها: جهات الاتصال، والرسائل، والحملات، ووكلاء الذكاء الاصطناعي، والوظائف المخصصة، وقاعدة المعرفة، والمواعيد، والتحليلات، والعلامات، والقوائم، والبث، والصفقات، واتصالات القنوات، والحسابات الفرعية. يمكن سرد الأتمتة وقراءتها، ولكن لا يمكن إنشاؤها أو تعديلها من خلال MCP حتى الآن؛ قم بإنشائها داخل التطبيق. ضمن ما يتم عرضه، لا توجد أذونات لكل أداة ولا يوجد افتراضي للقراءة فقط، لذا فإن مفتاح API هو وسيلة التحكم الكاملة في الوصول.

• نقطة النهاية (Endpoint): https://mcp.youraiconnector.com/mcp
• المصادقة: مفتاح API الخاص بك Your AI Connector (يُرسل كترويسة X-API-Key)
• المتطلبات: خطة تتضمن الوصول إلى API. إنشاء مفتاح API ←

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

Claude Code #

claude mcp add --transport http ai-connector https://mcp.youraiconnector.com/mcp \
  --header "X-API-Key: YOUR_API_KEY"

ثم قم بتشغيل /mcp داخل Claude Code للتأكد من ظهور ai-connector ✓ connected.

بشكل افتراضي، تتم إضافة الخادم في النطاق المحلي (أنت فقط، هذا المشروع). استخدم --scope user لجعله متاحاً في جميع مشاريعك، أو --scope project to commit it to a repo’s .mcp.json لفريقك:

{
  "mcpServers": {
    "ai-connector": {
      "type": "http",
      "url": "https://mcp.youraiconnector.com/mcp",
      "headers": { "X-API-Key": "YOUR_API_KEY" }
    }
  }
}

Claude Desktop #

أضف الخادم كموصل مخصص. يتم إعداده في حساب Claude الخاص بك، لذا فهو يعمل في Claude Desktop وعلى claude.ai على حد سواء (يمكن لحسابات Claude المجانية إضافة موصل مخصص واحد).

1. افتح Customize → Connectors، وانقر على + Add، ثم Add custom connector.
2. امنحه اسماً وأدخل https://mcp.youraiconnector.com/mcp كعنوان URL.
3. ضمن Authentication، اختر No sign in. لا يحتوي خادم MCP على صفحة تسجيل دخول: اختيار خيار تسجيل الدخول يؤدي إلى “Couldn’t register with … sign-in service”.
4. ضمن Request headers، أضف ترويسة باسم X-API-Key مع مفتاح API الخاص بك كقيمة.
5. انقر على Add. ستظهر أدوات Your AI Connector في قائمة الأدوات في محادثة جديدة.

لا يوجد حقل Request headers؟ إصدار Claude Desktop الخاص بك قديم: قم بتحديثه، أو استخدم ملف الإعدادات بدلاً من ذلك. ملف الإعدادات (claude_desktop_config.json، Settings → Developer → Edit Config) يقوم فقط بتشغيل البرامج على جهاز الكمبيوتر الخاص بك ويتجاهل إدخال url، لذا فهو يحتاج إلى جسر mcp-remote الصغير، والذي يتطلب Node.js إصدار 18 أو أحدث:

{
  "mcpServers": {
    "ai-connector": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.youraiconnector.com/mcp",
        "--header",
        "X-API-Key:${AI_CONNECTOR_KEY}"
      ],
      "env": { "AI_CONNECTOR_KEY": "YOUR_API_KEY" }
    }
  }
}

احتفظ بـ X-API-Key:${AI_CONNECTOR_KEY} كما هو مكتوب تماماً، بدون مسافة بعد النقطتين (على نظام Windows، تؤدي المسافة إلى فصل الترويسة)، وضع مفتاحك فقط في env. ثم أغلق Claude Desktop تماماً (على نظام Windows، انقر بزر الماوس الأيمن على أيقونة علبة النظام → Quit) وافتحه مرة أخرى.

ChatGPT #

لا يمكن لـ ChatGPT الاتصال بخادم MCP في الوقت الحالي. نموذج الموصل المخصص الخاص به يوفر فقط OAuth أو بدون مصادقة، بينما يقوم خادم MCP الخاص بـ Your AI Connector بتسجيل الدخول باستخدام مفتاح واجهة برمجة التطبيقات الخاص بك، والذي يتم إرساله كرأس طلب. يفشل اختيار OAuth مع رسالة “تعذر اكتشاف إعدادات OAuth”، ويتم رفض خيار “بدون مصادقة” لأن كل طلب يحتاج إلى المفتاح.

استخدم مساعدًا يسمح لك بتعيين رأس طلب بدلاً من ذلك: Claude Code، Claude Desktop، Cursor أو أي عميل MCP آخر، أو واجهة برمجة تطبيقات Claude.

لا يزال بإمكان ChatGPT قراءة وثائق المساعدة بدون اتصال: راجع وثائق المساعدة مدمجة لملفات llms.txt العامة.

Cursor وعملاء MCP الآخرون #

تستخدم معظم المحررات المتوافقة مع MCP نفس شكل .mcp.json الموضح أعلاه (خادم HTTP مع url وترويسة X-API-Key). أضف خادم ai-connector يشير إلى https://mcp.youraiconnector.com/mcp والصق مفتاح API الخاص بك في الترويسة.

واجهة برمجة تطبيقات Claude (دمجها في تطبيقك الخاص) #

يمكنك توصيل خادم MCP برمجياً باستخدام موصل MCP الخاص بواجهة برمجة تطبيقات Claude، بحيث يمكن للوكيل الذي تبنيه استخدام أدوات Your AI Connector دون الحاجة إلى عميل منفصل:

{
  "model": "claude-opus-4-8",
  "messages": [{ "role": "user", "content": "List my AI agents" }],
  "mcp_servers": [
    {
      "type": "url",
      "name": "ai-connector",
      "url": "https://mcp.youraiconnector.com/mcp",
      "authorization_token": "YOUR_API_KEY"
    }
  ]
}

ما يمكنك القيام به #

ضمن الجزء الذي يعرضه خادم MCP من واجهة برمجة التطبيقات v1، يختار المساعد الأداة المناسبة تلقائيًا:

• وكلاء الذكاء الاصطناعي: العرض، الإنشاء، التحديث، الإيقاف المؤقت/الاستئناف، فحص الإعدادات.
• جهات الاتصال: البحث، الإنشاء، التصنيف، الإضافة إلى القوائم، الاستيراد.
• قاعدة المعرفة / الأسئلة الشائعة: الإضافة، التعديل، الاستيراد الجماعي، الموافقة على اقتراحات الذكاء الاصطناعي.
• الرسائل: قراءة المحادثات، إرسال رسالة إلى جهة اتصال.
• المواعيد: العرض، الحجز، الإلغاء.
• المهام: الإنشاء، الإكمال، العرض.
• التحليلات: إحصائيات الرسائل، استخدام الرصيد، تكلفة الذكاء الاصطناعي.
• القنوات: التحقق من حالة الاتصال، بدء تدفق الاتصال.

السؤال عن حسابات عملائك (الوكالات) #

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

فقط اذكر اسم العميل:

• “كم عدد جهات الاتصال لدى Bella’s Bistro؟”
• “ما هي تكلفة الذكاء الاصطناعي لكل عميل من عملائي هذا الأسبوع؟”
• “ما هي حالة قنوات Northside Dental، وكم عدد الدردشات التي وردت هذا الأسبوع؟”

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

تغيير حساب العميل يعمل بنفس الطريقة. كل إجراء يقبل حساب عميل في واجهة برمجة التطبيقات (API) متاح لعميل مسمى: إعداد وكلاء الذكاء الاصطناعي، وقاعدة المعرفة، والوظائف المخصصة، وقوالب WhatsApp، ونقاط الدخول، واتصالات القنوات، وجهات الاتصال، والعلامات، والبث، والمواعيد، والصفقات والمهام، وإرسال الرسائل. الاستثناءات هي الإجراءات على مستوى الوكالة، والتي تعمل دائمًا على حساب وكالتك الخاص: إدارة حسابات العملاء أنفسهم (الحدود، الميزات، التسعير، الإيقاف المؤقت)، واللقطات (snapshots)، وفريقك، ومفاتيح API. إضافة جهات اتصال إلى قائمة العميل أو إزالتها منها غير متاح لعميل مسمى حتى الآن؛ قم بذلك من مفتاح العميل نفسه أو في حسابه. يسرد دليل وكالة API ما هو مدعوم.

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

اختبار وكيل العميل #

اطلب من المساعد تجربة وكيل العميل (“أرسل ‘هل تقومون بالتوصيل أيام الأحد؟’ إلى وكيل المخبز للعميل X وأرني ما فعله”). يقوم المساعد بإرسال رسالة تجربة (Try Out) باستخدام مفتاح الوكالة الخاص بك و sub_account_id الخاص بالعميل، ثم ينتظر ويقرأ الرد بالإضافة إلى أي إجراءات اتخذها الوكيل. لا حاجة لنسخة من الوكيل. إذا أخبرك المساعد بأنك لا تملك حساب وكالة، فهذا يعني أنه متصل بمفتاح عميل: أعد توصيله باستخدام مفتاح حساب الوكالة الخاص بك. راجع التجربة.

العملاء ذوو حد أدوات محدود #

https://mcp.youraiconnector.com/mcp?tags=SubAccounts,Contacts,Messages

وثائق المساعدة مدمجة #

يوفر خادم MCP للمساعد حسابك وهذه الوثائق. تقرأ ثلاث أدوات وثائق المساعدة مباشرة، بحيث يمكن للمساعد البحث عن كيفية عمل ميزة ما، أو ما الذي تغير مؤخراً، بدلاً من التخمين:

• docs_search: يعثر على الأقسام التي تجيب على سؤال ما ويعيدها مع رابط الصفحة.
• docs_read: يقرأ صفحة واحدة بالكامل، أو قسماً واحداً منها.
• docs_list: يسرد كل صفحة حسب المنطقة.

لا يوجد شيء لإعداده، ولا تلمس أدوات الوثائق بيانات حسابك أبداً. اسأل “كيف تعمل نقاط الدخول؟” أو “ما الجديد في الأتمتة؟” وسيبحث المساعد في الوثائق أولاً. نظراً لأن الأدوات تقرأ موقع المساعدة نفسه، فإن الميزة تصبح معروفة لمساعدك بمجرد نشر دليلها.

يمكن للمساعد غير المتصل عبر MCP قراءة الوثائق أيضاً: وجهه إلى https://docs.youraiconnector.com/llms.txt (فهرس لكل صفحة مساعدة مع رابط لنسخة Markdown الخاصة بكل صفحة) أو https://docs.youraiconnector.com/llms-full.txt (الوثائق بأكملها في ملف Markdown واحد). كلاهما عام، ولا يحتاج إلى مفتاح، ويتم إعادة بنائهما مع كل تغيير في الوثائق.

العثور على مفتاح API الخاص بك أو إنشاؤه #

يوجد مفتاح API الذي يستخدمه هذا الاتصال في الإعدادات ← عمليات التكامل ← مفتاح API — وهو قسم خاص به، منفصل عن Webhooks. راجع الوصول إلى واجهة برمجة التطبيقات لمعرفة الخطوات الدقيقة.

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

• “Connection refused” أو “not found” — العنوان يفتقد إلى /mcp في النهاية. استخدم https://mcp.youraiconnector.com/mcp، وليس https://mcp.youraiconnector.com.
• Needs authentication / 401 — مفتاح API الخاص بك مفقود أو خاطئ. أعد إضافة الخادم باستخدام X-API-Key صالح.
• “Could not discover OAuth settings” (ChatGPT) — يدعم ChatGPT فقط OAuth أو عدم وجود مصادقة للموصلات المخصصة، ويستخدم خادم MCP مفتاح API، لذا لا يمكن لـ ChatGPT الاتصال في الوقت الحالي. راجع ChatGPT.
• “Couldn’t register with … sign-in service” أو “add an OAuth Client ID” (Claude Desktop) — تمت إضافة الموصل المخصص مع خيار تسجيل الدخول. لا يوجد معرف عميل OAuth لإدخاله: قم بإزالة الموصل وأعد إضافته مع Authentication → No sign in ومفتاح API الخاص بك كترويسة طلب X-API-Key، كما في Claude Desktop.
• لا يعرض Claude Desktop أي أدوات بعد تعديل ملف الإعدادات — يتجاهل ملف الإعدادات إدخال "url"؛ استخدم الموصل المخصص أو نموذج mcp-remote في Claude Desktop، وأغلق التطبيق تماماً وأعد فتحه.
• أداة تُرجع 403 — خطتك أو دور فريقك لا يسمح بهذا الإجراء؛ لا يفرض خادم MCP أي شيء إضافي، فهو نفس فحص الأذونات الخاص بـ API.
• أداة غير موجودة — يتم إنشاء قائمة الأدوات مباشرة من API، لذا فهي تتطابق دائماً مع الإصدار الحالي؛ أعد الاتصال للتحديث.
• تحذير أمني أو تحذير شهادة على نطاقك الخاص — توجيه سجل DNS إلينا ليس كافياً بحد ذاته: يجب أيضاً التحقق من النطاق الفرعي في لوحة التحكم قبل أن يتمكن من تقديم اتصال آمن. يمكن لوكالات العلامات البيضاء وضع عنوان MCP على نطاقها الخاص (على سبيل المثال mcp.youragency.com) من بطاقة Custom domain تحت Settings → White Labeling — أضف CNAME لدى مسجل النطاق الخاص بك أولاً، ثم أدخل اسم المضيف في كتلة MCP domain (AI assistants) وانقر على Verify، وهو نفس مسار العمل لنطاقاتك الفرعية الأخرى ذات العلامة التجارية. العنوان ذو العلامة التجارية يستبعد أدوات الوكالة؛ استمر في استخدام العنوان القياسي غير ذي العلامة التجارية لتلك الأدوات. حتى يتم التحقق من عنوانك ذي العلامة التجارية، استخدم العنوان القياسي غير ذي العلامة التجارية: فهو آمن للمشاركة مع العملاء.

الخطوات التالية #

• الوصول إلى واجهة برمجة التطبيقات — لإنشاء أو تدوير المفتاح الذي يستخدمه هذا الاتصال.
• Webhooks — النظير القائم على الدفع لهذا الاتصال القائم على السحب MCP.