قيادة betool من Claude (خادم MCP)

تُتيح betool خادم MCP (Model Context Protocol): يمكن لعميل MCP خارجي — Claude Code أو Claude Desktop أو أي تطبيق متوافق — أن يقرأ تهيئة مؤسستك ويقترح تغييرات بلغة طبيعية (إنشاء/تعديل pipeline، دور، مهمّة، تقييم…). وكأنّه مساعد يهيّئ betool معك، ومحكوم بالكامل.

طريقتان للاتصال، بنفس نقطة النهاية https://platform.betool.ai/mcp:

• مفتاح API لـ MCP في ترويسة Authorization — الأبسط مع Claude Code؛
• OAuth 2.1 + PKCE — للتطبيقات الخارجية، دون التعامل مع أي سرّ.

ما يستطيع Claude فعله

• القراءة: جرد النماذج، مخطّط pipeline وعقده، عقود تهيئة العقد، الأدوار/المهام، الأدوات المتاحة، قاعدة المعرفة.
• قراءة بياناتك: قواعد البيانات بدون كود في مؤسستك — القواعد والجداول والأعمدة والصفوف. يكتشفها العميل بنفسه؛ ولا يمكن تقييد مفتاح بمجموعة فرعية من القواعد.
• الاقتراح: عبر أداة proposals.create، اقتراح تغيير معلّق — تقبله أو ترفضه في الواجهة.
• كتابة البيانات (النطاق الكامل): إنشاء صف في إحدى قواعدك أو تحديثه أو حجزه، بعد موافقتك الصريحة في المحادثة. وخلافًا للتهيئة، لا تُدار كتابة البيانات بالإصدارات — فلا يمكن استعادتها.
• التحدّث إلى نماذجك (النطاق الكامل): إجراء محادثة متعدّدة الأدوار مع نموذج فتحته صراحةً للوكلاء الخارجيين — انظر أدناه.

يكتشف Claude العقد الدقيق لكل عقدة (الحقول، القيم المسموح بها) قبل الاقتراح: لا تخمين ولا تهيئة غير صالحة.

إنشاء مفتاح MCP

مقصور على مديري المؤسسة: المفتاح يحمل سلطة على المؤسسة بأكملها.

1. في betool، افتح الإعدادات ← MCP.
2. سمِّ المفتاح واختَر نطاقه:
   • قراءة فقط — يقرأ التهيئة وبيانات قواعدك، ويعيد قراءة المحادثات المفتوحة عبر هذه القناة، ولا يقترح شيئًا؛
   • قراءة + اقتراحات (موصى به) — يقرأ ويقدّم اقتراحات توافق عليها داخل betool؛
   • كامل — يمكنه أيضًا حلّ اقتراحاته والكتابة في قواعد بياناتك والتحدّث إلى نماذجك، بعد موافقتك في محادثة العميل.
3. يُعرَض المفتاح الخام مرة واحدة فقط — انسخه فورًا (لا يمكن قراءته مجدّدًا أبدًا). يمكنك إبطال مفتاح في أي وقت.

النطاقات الثلاثة نفسها متاحة مع OAuth؛ وهناك تختارها في شاشة الموافقة.

ربط Claude Code

أضِف خادم MCP الخاص بـ betool إلى Claude Code (يوضَع المفتاح في ترويسة Authorization):

claude mcp add betool \
  --transport http \
  --header "Authorization: Bearer <your-mcp-key>" \
  https://platform.betool.ai/mcp

ثم اطلب من Claude، بلغة طبيعية: «افحص pipeline X الخاص بي واقترح خطوة تلخّص التذكرة قبل الإرسال». يقرأ Claude التهيئة، ويؤلّف اقتراحًا، وتتحقّق منه أنت في betool.

التحدّث إلى نماذجك

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

أربع أدوات: conversation.open يفتح محادثة أو يستعيدها، وconversation.send يرسل دورًا ويعيد الجواب، وconversation.poll يجلب جوابًا استغرق وقتًا، وconversation.history يعيد قراءة المحادثة. وهذه المحادثة سياق betool كأي سياق آخر: تظهر ضمن محادثاتك، ويرى النموذج الأدوار السابقة، وتعيد أنت قراءة كل شيء في الواجهة.

لا يضيع الجواب أبدًا: إذا عمل النموذج مدةً أطول من الانتظار المسموح، أعاد الاستدعاء تذكرة واستمرّ الدور على الخادم — بل ينجو من إعادة النشر. ثم يقرأ التطبيق الجواب عبر conversation.poll. وإعادة إرسال الرسالة لا تُسرّع شيئًا — وما دام الدور قيد التنفيذ فإنّ الإرسال يُرفض.

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

النموذج القائم يعمل من دون أي تعديل. فهذه القناة تضع المفاتيح نفسها التي تضعها محادثة عادية: تصل الرسالة في user_message، والحدث هو on_message معتاد — فتظل مرشِّحاتك واختيارات وكلائك تعمل كما هي. وإذا كان النموذج المقصود مكتوبًا لمدخل آخر (يقرأ telegram.text أو هدفًا أو متغيّر صفحة…)، فيمكن للتطبيق أن يقدّم تلك المفاتيح بنفسه عبر variables: فتدخل المسار في الموضع نفسه الذي كان المدخل الآخر سيضعها فيه. أما ما لا يمكنه تزويره فهو هوية الدور — مَن تحدّث وعبر أي قناة: هذه المفاتيح يضعها الخادم، وأي محاولة تُرفض ويُبلَّغ عنها في الجواب.

إذا صمت النموذج فانظر إلى توجيهه. فالنموذج الذي يخدم عدة قنوات يتفرّع عادةً بحسب المدخل (filter input.entry_kind == chat_widget…): ودورٌ يصل بمدخل « الوكيل الخارجي » لا يطابق أي فرع، فلا يجيب أحد — دون أن يظهر أي خطأ. مرِّر as_entry_kind لتُوجَّه كما لو كنت تلك القناة. فهذا يغيّر مفتاح التوجيه وحده: يبقى واصف القناة وسجل التدقيق يقولان إنّ الدور جاء من ذكاء اصطناعي خارجي، وتظل قدرات القناة الحقيقية سارية.

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

ربط تطبيق خارجي (OAuth 2.1)

المفتاح في الترويسة يناسب Claude Code. أمّا العملاء الآخرون — Claude Desktop، ChatGPT، محرّر شيفرة، تطبيقك الخاص — فيتّصلون عبر OAuth 2.1 + PKCE، دون أن يتعامل أحد مع سرّ. ولا شيء تُعدّه مسبقًا: لا عميل تُصرّح به، ولا معرّف تطلبه منّا.

من ناحية المستخدم، المسار ثلاث شاشات:

1. في التطبيق، أضِف خادم MCP https://platform.betool.ai/mcp.
2. يفتح متصفّحك شاشة موافقة من betool: تذكر التطبيق الذي يطلب الوصول، والمؤسسة المعنيّة، وأين ستكون العودة. تحقّق من هذه الثلاثة — خصوصًا إن كنت تنتمي إلى عدّة مؤسسات.
3. اختر النطاق الذي تمنحه، ثم السماح. لا يحصل التطبيق أبدًا على أكثر مما تحدّده، حتى لو طلب أكثر.

للمُدمِجين، الاكتشاف تلقائي بالكامل ومتوافق مع المعايير: استدعاء غير موثَّق لـ /mcp يعيد 401 يحمل ترويسة WWW-Authenticate مع عنوان بيانات التعريف لدينا (RFC 9728)، والتي تشير بدورها إلى التخويل، وتبادل الرموز، والتسجيل الديناميكي للعميل (RFC 7591)، والإبطال (RFC 7009). PKCE S256 إلزامي، ورموز الوصول تدوم ساعة واحدة، ورمز التحديث يتغيّر مع كل استخدام.

# ما يفعله العميل من تلقاء نفسه — مفيد للتحقّق من الطرفية.
curl -i -X POST https://platform.betool.ai/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'
# -> 401 + WWW-Authenticate: Bearer ... resource_metadata="..."

curl -s https://platform.betool.ai/.well-known/oauth-authorization-server

الرمز صالح لـ betool وحدها: إن استُخدم في مكان آخر فسيُرفَض (RFC 8707). وإذا قُدّم رمز تحديث مستهلَك سابقًا مرّة ثانية — وهي العلامة المميّزة لرمز مسروق — يُبطَل التخويل بأكمله ويلزم المستخدم أن يسمح من جديد.

التطبيقات المتصلة: العرض والفصل

ضمن الإعدادات ← MCP، يسرد قسم التطبيقات المتصلة ما هو مرتبط بمؤسستك: اسم التطبيق، والنطاق الممنوح، ومَن سمح به، وتاريخ آخر استخدام. وزرّ فصل يقطع الوصول فورًا — كل رموز ذلك التطبيق، ولمؤسستك وحدها.

قد يكون التطبيق نفسه مرتبطًا بعدّة مؤسسات: وفصله عندك لا يمسّ أحدًا غيرك. ويمكن للتطبيق أيضًا أن يفصل نفسه.

النطاق والعزل

• بشكل افتراضي يعمل المفتاح على مؤسستك وحدها — تُفرَض المؤسسة الهدف من جانب الخادم؛ ولا تمرّر أبدًا معرّف مؤسسة كوسيط.
• قد تستهدف مفاتيح المورّد (مؤسسة الـ backoffice) مؤسسة أخرى، بموافقتها الصريحة ومع تدقيق كامل — وهو أمر مفيد لحالة استخدام مورّد متعدّد المستأجرين.

سجل التدقيق

يكتب كل استدعاء أداة (خارجي عبر MCP وكذلك داخلي) سطر تدقيق: مَن، وأي أداة، وأي قناة، وأي نطاق، والنتيجة، وزمن الاستجابة. متاح ضمن الإعدادات ← MCP، محصور بدقة في مؤسستك.

قريبًا

• تحكّم دقيق، أداةً بأداة، في السطح المُتاح عبر MCP.
• بثّ من الخادم إلى العميل (SSE) لإشعارات الخادم.

اطّلع أيضًا

• واجهة برمجة تطبيقات الإدارة (Admin API) — أتمتة betool من أنظمتك الخاصة.
• الأمن والامتثال — نموذج حوكمة الاقتراحات.