Skip to main content

​
نظرة عامة

تعرض Twenty خادم MCP بحيث تتمكّن مساعدات الذكاء الاصطناعي — Claude Desktop وClaude Code وCursor وChatGPT وغيرها — من قراءة وكتابة بيانات نظام إدارة علاقات العملاء (CRM) لديك باستخدام اللغة الطبيعية. استخدم عنوان URL لمساحة العمل (عنوان URL الذي تستخدمه للوصول إلى Twenty) كنقطة نهاية MCP. على Twenty Cloud، قد يكون عنوان URL لمساحة العمل هو https://{mycompany}.twenty.com أو نطاق مخصص. الخادم متاح على:

​
طرق المصادقة

لديك طريقتان لمصادقة عميل MCP: OAuth (مُوصى بها) أو مفتاح API.

​
الخيار أ — OAuth (مُوصى به)

باستخدام OAuth، يفتح عميل MCP لديك نافذة متصفح لتسجيل الدخول. لا يتم تخزين أي أسرار في ملفات الإعداد، ويتم تحديث الرموز المميِّزة تلقائيًا.
يتطلب OAuth عميل MCP يدعم مواصفة تفويض MCP. تدعمه Claude Desktop وClaude Code وCursor وChatGPT.
أضِف ما يلي إلى تهيئة عميل MCP لديك، واستبدِل {your-workspace-url} بمضيف مساحة العمل لديك (على سبيل المثال: mycompany.twenty.com):
هذا كل شيء — لا حاجة إلى مفتاح API. عند اتصال العميل للمرة الأولى، سيفعل ما يلي:
  1. اكتشاف بيانات التعريف الخاصة بـ OAuth لدى Twenty عبر /.well-known/oauth-protected-resource و/.well-known/oauth-authorization-server
  2. تسجيل نفسه كعميل OAuth عبر التسجيل الديناميكي للعميل (RFC 7591)
  3. فتح متصفحك لتفويض الوصول
  4. استلام الرموز المميِّزة والاتصال بخادم MCP
تعيد الاتصالات اللاحقة استخدام الرموز المميِّزة المخزنة وتحدِّثها تلقائيًا.

​
الخيار ب — مفتاح API

إذا كان عميل MCP لديك لا يدعم OAuth، أو كنت تفضّل بيانات اعتماد ثابتة، فمرِّر مفتاح API في ترويسة Authorization:
يمنح مفتاح API الخاص بك حق الوصول إلى بيانات مساحة العمل. أبعِده عن أنظمة التحكم في الإصدارات وملفات dotfiles المشتركة.
لإنشاء مفتاح API، انتقل إلى Settings → Developers → API → + Create key. راجع واجهات برمجة التطبيقات للتفاصيل.

​
البدء السريع

​
1. انسخ الإعداد

انتقل إلى Settings → AI → MCP في Twenty. اختر طريقة المصادقة (OAuth أو مفتاح API)، وانسخ مقطع JSON (سيستخدم بالفعل عنوان URL لمساحة العمل لديك)، ثم الصقه في ملف إعدادات عميل MCP لديك.

​
2. الاتصال

أعِد تشغيل عميل MCP لديك (أو أعد تحميل ملف الإعداد). إذا كنت تستخدم OAuth فسيتم توجيهك إلى Twenty لتفويض الوصول. إذا كنت تستخدم مفتاح API فسيكون الاتصال فوريًا.

​
3. ابدأ باستخدامه

اطلب من مساعد الذكاء الاصطناعي التفاعل مع نظام إدارة علاقات العملاء (CRM) لديك:
  • “أرني أحدث 5 شركات تم إنشاؤها”
  • “أنشئ شخصًا جديدًا باسم Jane Doe في Acme Corp”
  • “اعثر على جميع الفرص المفتوحة التي تزيد قيمتها عن 10 آلاف دولار”

​
الأدوات المتاحة

بعد الاتصال، يوفّر خادم MCP أدوات تعكس واجهة برمجة تطبيقات Twenty (API). سير العمل الموصى به هو:
  1. learn_tools — احصل على مخطط الإدخال لأدوات محددة
  2. execute_tool — شغّل أداة
لا تحتاج إلى تذكّر أسماء الأدوات. اسأل مساعد الذكاء الاصطناعي عمّا يمكنه فعله وسيستدعي learn_tools تلقائيًا. تتبع أسماء عمليات السجل قواعد نحوية، لذا يمكن للمساعد إنشاؤها دون استدعاء اكتشاف: find_many_companies، find_one_person، update_one_opportunity. إذا كان الاسم خاطئًا، يُبلّغ learn_tools عنه ضمن notFound إلى جانب الأسماء الأقرب تطابقًا. لأي شيء آخر، يستعرض get_tool_catalog الأدوات المتبقية، فئةً واحدةً في كل مرة. إنه خيار احتياطي: يُرجع استدعاء غير مُرشَّح مئات العمليات، وستُقتطع الاستجابة لدى معظم المساعدين. يسرد /mcp?mode=direct كل أداة مباشرةً ويتطلب عميلاً يحمّل الأدوات عند الطلب.

​
الصلاحيات

ترث اتصالات MCP أذونات المستخدم المُصادَق عليه (OAuth) أو الدور المُعيَّن لمفتاح API. لتقييد ما يمكن لخادم MCP القيام به:
  • OAuth: ينطبق دور المستخدم في مساحة العمل.
  • API Key: عيِّن دورًا لمفتاح API ضمن Settings → Members → Roles. راجع الأذونات.

​
التكوين ذاتي الاستضافة

في حالات الاستضافة الذاتية، استبدِل {your-workspace-url} بعنوان URL الخاص بالخادم لديك. تأكّد من أن قيمة SERVER_URL في بيئتك تطابق عنوان URL العام لمثيل Twenty لديك — إذ يُستخدَم ذلك لإنشاء بيانات تعريف اكتشاف OAuth.
تُشتق نقطة نهاية MCP ونقاط نهاية OAuth وبيانات تعريف الاكتشاف جميعها من هذه القيمة.

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

أخطاء “Unauthorized” أو 401
  • OAuth: أعد التفويض عبر مسح الرموز المميِّزة المخزنة في عميل MCP لديك ثم أعد الاتصال.
  • API Key: تحقّق من أن المفتاح صالح ولم تنتهِ صلاحيته. أعِد توليده إذا لزم الأمر.
عملية OAuth لا تفتح متصفحًا
  • تأكّد من أن عميل MCP لديك يدعم تفويض MCP. ارجع إلى طريقة مفتاح API إذا لم يكن كذلك.
انتهاء مهلة الاتصال
  • تحقّق من إمكانية الوصول إلى عنوان URL لنقطة نهاية MCP من جهازك. بالنسبة لحالات الاستضافة الذاتية، تحقّق من أن الخادم يعمل وأن SERVER_URL مُعيَّن بشكل صحيح.