تُتيح 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 — للتطبيقات الخارجية، دون التعامل مع أي سرّ.
لا يُطبَّق شيء دون موافقة صريحة. يمرّ كل تغيير عبر اقتراح. مع نطاق قراءة + اقتراحات توافق عليه بزرّ قبول وتطبيق داخل betool. ومع نطاق كامل يمكن للتطبيق أن يحلّ اقتراحاته بنفسه — بعد موافقتك في محادثته الخاصة؛ وهو المكافئ الآلي لذلك الزرّ، مقصور على هذا النطاق ومُدقَّق كسائر الأمور. اختر قراءة + اقتراحات إذا أردت أن يحدث التحقّق داخل betool، ولا مكان غيره.
ما يستطيع Claude فعله
- القراءة: جرد النماذج، مخطّط pipeline وعقده، عقود تهيئة العقد، الأدوار/المهام، الأدوات المتاحة، قاعدة المعرفة.
- قراءة بياناتك: قواعد البيانات بدون كود في مؤسستك — القواعد والجداول والأعمدة والصفوف. يكتشفها العميل بنفسه؛ ولا يمكن تقييد مفتاح بمجموعة فرعية من القواعد.
- الاقتراح: عبر أداة
proposals.create، اقتراح تغيير معلّق — تقبله أو ترفضه في الواجهة. ويشمل ذلك أيضاً إنشاء نموذج وإطلاق benchmark (انظر ما يمكن اقتراحه). - كتابة البيانات (النطاق الكامل): إنشاء صف في إحدى قواعدك أو تحديثه أو حجزه، بعد موافقتك الصريحة في المحادثة. وخلافًا للتهيئة، لا تُدار كتابة البيانات بالإصدارات — فلا يمكن استعادتها.
- التحدّث إلى نماذجك (النطاق الكامل): إجراء محادثة متعدّدة الأدوار مع نموذج فتحته صراحةً للوكلاء الخارجيين — انظر أدناه.
يكتشف Claude العقد الدقيق لكل عقدة (الحقول، القيم المسموح بها) قبل الاقتراح: لا تخمين ولا تهيئة غير صالحة.
أسرار التهيئة (سرّ HMAC، رمز، كلمة مرور) لا تصل إليه أبدًا: يُعيدها models.inspect_pipeline والاقتراحات مُخفاة. والاقتراح الذي يُعيد تهيئةً كما قرأها يحتفظ بالسرّ المحفوظ، دون أن يكون الذكاء الاصطناعي قد رآه.
الأدوات المُتاحة
تُجمَّع الأدوات حسب العائلة. يكتشفها العميل بنفسه عند الاتصال؛ ولا تظهر أدوات موصِّل ما إلا إذا كانت مؤسستك تستخدمه.
| العائلة | الأدوات | الدور |
|---|---|---|
models | list_models، lookup_model، list_groups، inspect_pipeline، list_contexts، get_pipeline_trace، get_exchange_metadata، automation_health، get_entry_endpoints | جرد النماذج، وقراءة pipeline وعمليات تنفيذه، وحالة الأتمتة المتوقّفة |
pipeline | list_node_kinds، lookup_node_contract، lookup_module، list_all_tools، list_config_options، list_schemas، validate | عقود العقد، وخيارات التهيئة، والتحقّق من مخطّط قبل الاقتراح |
agents | list_roles، lookup_role، list_missions، lookup_mission | أدوار وكلائك ومهامّهم |
benchmarks | list، get، list_check_kinds، list_runs، get_run، run_status | سيناريوهات التقييم ونتائج تشغيلها |
knowledge | search | البحث في قاعدة المعرفة الخاصة بك |
database_query / database_manage | القراءة؛ create_row، update_row، claim_row | قواعدك بدون كود (الكتابة: النطاق الكامل) |
conversation | open، send، poll، history | التحدّث إلى نموذج (انظر أدناه) |
proposals | create، describe_kind، apply، reject | اقتراح تغيير، وقراءة عقده، وحسمه (apply / reject: النطاق الكامل) |
عنوان URL لمدخل النموذج، جاهز للّصق. تُعيد models.get_entry_endpoints عنوان URL العام الكامل لكل مستقبِل مُعلَن على عقدة Start في نموذج (webhook وارد، callback لمنصّة مراسلة…) — ما يكفي لإرساله إلى شريك دون البحث عن المسار في الواجهة.
ما يمكن اقتراحه
يمرّ كل تعديل في التهيئة عبر proposals.create(kind, payload). وقبل كتابة payload، يقرأ العميل عقده الدقيق عبر proposals.describe_kind(kind). الأنواع (kinds) المتاحة:
| النوع (Kind) | الأثر بعد القبول |
|---|---|
model_create | ينشئ نموذجاً (عملية) — تسميته ووصفه ومجموعته |
model_update | يعدّل البيانات الوصفية لنموذج موجود |
pipeline_edit | يحرّر مخطّط نموذج (إضافة العقد والروابط وتعديلها وحذفها) |
pipeline_publish | ينشر الحالة الحالية لنموذج، بعد التحقّق السابق للنشر |
pipeline_plan | يسلسل تحريرات ثم نشراً على النموذج نفسه، بقبول واحد، وبشكل ذرّي |
role_update / mission_update | ينشئ أو يعدّل دوراً / مهمّة لوكيل |
knowledge_update | ينشئ أو يحدّث بطاقة نصّية في قاعدة المعرفة |
knowledge_document_replace | يستبدل ملف مستند في قاعدة المعرفة، في مكانه: المُعرِّف نفسه، والرابط العام نفسه |
database_schema_edit | يعدّل بنية قاعدة بدون كود (القواعد، الأعمدة) |
benchmark_create / benchmark_update / benchmark_delete | يدير سيناريوهات التقييم |
benchmark_run | يُطلِق تشغيل benchmark — مُقترَح، لأنّ التشغيل يستهلك أرصدة |
credit_topup | شحن يدوي لرصيد — مقصور على المؤسسة المشغِّلة للمنصّة، ويُصادَق عليه من المؤسسة المشحون رصيدها |
إنشاء عملية من البداية إلى النهاية = عدّة موافقات. ينشئ model_create النسخة؛ ثم يوصل pipeline_edit عقدة Start الخاصة بها (مع مستقبِلاتها) وعقدها؛ ثم يضعها pipeline_publish في الخدمة. ويظلّ إنشاء النسخة وتوصيلها قرارين بشريّين منفصلين.
إنشاء مفتاح MCP
مقصور على مديري المؤسسة: المفتاح يحمل سلطة على المؤسسة بأكملها.
- في betool، افتح « Paramètres de l'organisation » ← MCP.
- سمِّ المفتاح واختَر نطاقه:
- قراءة فقط — يقرأ التهيئة وبيانات قواعدك، ويعيد قراءة المحادثات المفتوحة عبر هذه القناة، ولا يقترح شيئًا؛
- قراءة + اقتراحات (موصى به) — يقرأ ويقدّم اقتراحات توافق عليها داخل betool؛
- كامل — يمكنه أيضًا حلّ اقتراحاته والكتابة في قواعد بياناتك والتحدّث إلى نماذجك، بعد موافقتك في محادثة العميل.
- يُعرَض المفتاح الخام مرة واحدة فقط — انسخه فورًا (لا يمكن قراءته مجدّدًا أبدًا). يمكنك إبطال مفتاح في أي وقت.
النطاقات الثلاثة نفسها متاحة مع 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.
لا تلصق الأسرار بنصّ صريح في المحادثة أبدًا. نطاق وصول Claude محدود بـ نطاق المفتاح، ويُسجَّل كل استدعاء أداة ضمن « Paramètres de l'organisation » ← MCP ← سجل استدعاءات الأدوات (المادة 15 من GDPR).
التحدّث إلى نماذجك
القراءة والاقتراح تعنيان تهيئة betool. ويمكن لذكاء اصطناعي خارجي أن يستخدمها أيضًا: أن يجري محادثة حقيقية مع أحد نماذجك، دورًا بعد دور، كأي زائر في محادثتك. وهذا مفيد لاختبار مساعدك بواسطة ذكاء اصطناعي آخر، أو لوضع betool خلف وكيل شريك، أو لتمكين أداة داخلية من الاستفسار عن أحد عملياتك بلغة طبيعية.
أربع أدوات: conversation.open يفتح محادثة أو يستعيدها، وconversation.send يرسل دورًا ويعيد الجواب، وconversation.poll يجلب جوابًا استغرق وقتًا، وconversation.history يعيد قراءة المحادثة. وهذه المحادثة سياق betool كأي سياق آخر: تظهر ضمن محادثاتك، ويرى النموذج الأدوار السابقة، وتعيد أنت قراءة كل شيء في الواجهة.
النموذج هو من يأذن، وليس المفتاح. يجب إعلان المستقبِل وكيل خارجي على عقدة Start الخاصة بالنموذج: فبدون هذا الإعلان يُرفض الاستدعاء، حتى بمفتاح نطاقه كامل. النماذج المُنشأة بعد هذا الإصدار تعلنه تلقائيًا (الطريق المعتاد هو الطريق الأسهل)؛ أما الأقدم فيجب إضافته إليها، ويمكن إزالته من أي نموذج. فالقرار للنموذج لا للمفتاح — وعلى المستقبِل أن يكون موجودًا في النسخة المنشورة، أي التي تعمل فعلًا. ولأنّ الدور قد يُحدث آثارًا حقيقية — رسالة تُرسَل، سجلّ يُنشَأ — فإنه يستهلك أرصدة المؤسسة ويُسجَّل في سجل التدقيق كأي استدعاء أداة.
لا يضيع الجواب أبدًا: إذا عمل النموذج مدةً أطول من الانتظار المسموح، أعاد الاستدعاء تذكرة واستمرّ الدور على الخادم — بل ينجو من إعادة النشر. ثم يقرأ التطبيق الجواب عبر 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، دون أن يتعامل أحد مع سرّ. ولا شيء تُعدّه مسبقًا: لا عميل تُصرّح به، ولا معرّف تطلبه منّا.
من ناحية المستخدم، المسار ثلاث شاشات:
- في التطبيق، أضِف خادم MCP
https://platform.betool.ai/mcp. - يفتح متصفّحك شاشة موافقة من betool: تذكر التطبيق الذي يطلب الوصول، والمؤسسة المعنيّة، وأين ستكون العودة. تحقّق من هذه الثلاثة — خصوصًا إن كنت تنتمي إلى عدّة مؤسسات.
- اختر النطاق الذي تمنحه، ثم السماح. لا يحصل التطبيق أبدًا على أكثر مما تحدّده، حتى لو طلب أكثر.
لا يمكن السماح لتطبيق إلا لمدير المؤسسة. فربط تطبيق يُنشئ سلطة دائمة على المؤسسة بأكملها — وهو تمامًا ما يمثّله مفتاح MCP. لذلك لا يستطيع عضو ذو حقوق محدودة أن يتجاوز قيوده من هذا الباب.
للمُدمِجين، الاكتشاف تلقائي بالكامل ومتوافق مع المعايير: استدعاء غير موثَّق لـ /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). وإذا قُدّم رمز تحديث مستهلَك سابقًا مرّة ثانية — وهي العلامة المميّزة لرمز مسروق — يُبطَل التخويل بأكمله ويلزم المستخدم أن يسمح من جديد.
التطبيقات المتصلة: العرض والفصل
ضمن « Paramètres de l'organisation » ← MCP، يسرد قسم التطبيقات المتصلة ما هو مرتبط بمؤسستك: اسم التطبيق، والنطاق الممنوح، ومَن سمح به، وتاريخ آخر استخدام. وزرّ فصل يقطع الوصول فورًا — كل رموز ذلك التطبيق، ولمؤسستك وحدها.
قد يكون التطبيق نفسه مرتبطًا بعدّة مؤسسات: وفصله عندك لا يمسّ أحدًا غيرك. ويمكن للتطبيق أيضًا أن يفصل نفسه.
النطاق والعزل
- بشكل افتراضي يعمل المفتاح على مؤسستك وحدها — تُفرَض المؤسسة الهدف من جانب الخادم؛ ولا تمرّر أبدًا معرّف مؤسسة كوسيط.
- قد تستهدف مفاتيح المورّد (مؤسسة الـ backoffice) مؤسسة أخرى، بموافقتها الصريحة ومع تدقيق كامل — وهو أمر مفيد لحالة استخدام مورّد متعدّد المستأجرين.
سجل التدقيق
يكتب كل استدعاء أداة (خارجي عبر MCP وكذلك داخلي) سطر تدقيق: مَن، وأي أداة، وأي قناة، وأي نطاق، والنتيجة، وزمن الاستجابة. متاح ضمن « Paramètres de l'organisation » ← MCP (قسم سجل استدعاءات الأدوات)، محصور بدقة في مؤسستك.
اطّلع أيضًا
- واجهة برمجة تطبيقات الإدارة (Admin API) — أتمتة betool من أنظمتك الخاصة.
- الأمن والامتثال — نموذج حوكمة الاقتراحات.