نظرة عامة
تشغّل إكزوميشنز خادم MCP لكل مساحة عمل. اربط Claude أو Cursor أو أي عميل MCP ليتمكن مساعدك الذكي من تشغيل تدفقاتك المفعّلة والتحقق من نتيجة التشغيل وصياغة تدفقات جديدة لتراجعها.
/api/mcpJSON-RPC 2.0 عبر HTTPS. لكل طلب رد JSON واحد؛ لا يوجد بث أحداث ولا جلسة تُحفظ.
| الطريقة | الغرض |
|---|---|
| initialize | المصافحة. تعيد قدرات الخادم (الأدوات). |
| tools/list | الأدوات التي يحق لمفتاحك استخدامها. |
| tools/call | تشغيل أداة واحدة. |
| ping | فحص الحالة. يعيد كائناً فارغاً. |
إعداد كل عميل في صفحة ربط عميلك. ومدخلات كل أداة ونتيجتها وأخطاؤها ومثال على استدعائها في مرجع أدوات MCP.
Claude Desktop
- في إكزوميشنز افتح مفاتيح API وأنشئ مفتاحاً بصلاحية
execute. أضفbuildإن أردت أن يصوغ المساعد التدفقات أيضاً. - أضف هذا المقطع إلى ملف إعدادات Claude وضع مفتاحك فيه.
- أعد تشغيل Claude. تظهر تدفقاتك كأدوات.
{
"mcpServers": {
"exomations": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"https://exomations.com/api/mcp",
"--header", "X-Api-Key:YOUR_EXOMATIONS_KEY"
]
}
}
}| النظام | الملف |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
المقطع نفسه، مع عنوانك جاهزاً، موجود في صفحة مفاتيح API تحت خادم MCP لإكزوميشنز وجاهز للنسخ.
Cursor وعملاء سطح المكتب الآخرون
يستخدم Cursor مقطع الخادم نفسه في إعدادات MCP لديه. وأي عميل يستطيع إرسال ترويسة مخصصة يتصل بإحدى طريقتين:
X-Api-Key: exo_your_keyAuthorization: Bearer exo_your_key?api_key=) يُرفض حتى لو أُرسلت ترويسة أيضاً. وإن وُضع مفتاح في عنوان URL يوماً فاستبدله بمفتاح جديد.Claude على الويب (OAuth)
العملاء العاملون في المتصفح لا يستطيعون إرسال ترويسة مخصصة، لذا يدعم الخادم OAuth 2.0 أيضاً. أضف العنوان كموصّل مخصص؛ يكتشف العميل الباقي ويحوّلك إلى إكزوميشنز للموافقة.
- PKCE (S256) إلزامي، ويسجّل العملاء أنفسهم تلقائياً.
- الموافقة تتطلب مدير مساحة العمل. تعرض الشاشة ما طلبه العميل (
executeأوbuildأو كليهما)، فتقبله كاملاً أو ترفضه. - رمز الوصول يدوم ساعة ويتجدد تلقائياً، ويبقى الاتصال ما دام يُستخدم مرة كل 30 يوماً على الأقل. ويمكنك إلغاؤه من صفحة مفاتيح API.
| مستند الاكتشاف | المسار |
|---|---|
| خادم التفويض | /.well-known/oauth-authorization-server |
| المورد المحمي | /.well-known/oauth-protected-resource |
HTTP مباشر
لا تحتاج إلى مكتبة MCP. هذه الطلبات الثلاثة جلسة كاملة:
curl -X POST https://exomations.com/api/mcp \
-H "X-Api-Key: exo_your_key" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"my-client","version":"1.0"}}}'curl -X POST https://exomations.com/api/mcp \
-H "X-Api-Key: exo_your_key" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'curl -X POST https://exomations.com/api/mcp \
-H "X-Api-Key: exo_your_key" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"exo_overdue_invoice_reminders_7a17617d","arguments":{"payload":{"customer_id":"C-204"}}}}'رد الطلب الثالث:
{
"jsonrpc": "2.0",
"id": 3,
"result": {
"content": [{ "type": "text", "text": "Flow \"Overdue invoice reminders\" queued. Check Exomations to see live progress.\n{ ... }" }],
"structuredContent": {
"executionId": "0b6f6c1e-5a55-4d0e-9a57-2f7c1d0e8a11",
"flowId": "7a17617d-...",
"flowName": "Overdue invoice reminders",
"status": "queued"
},
"isError": false
}
}الأدوات التي يراها المفتاح
| الصلاحية | الأدوات |
|---|---|
| execute | أداة لكل تدفق مفعّل، مع أدوات قراءة التشغيل الثلاث. |
| build | أدوات البناء الثماني. |
| execute + build | جميعها. |
أدوات التدفقات
يصبح كل تدفق مفعّل أداة باسم exo_<name>_<id8>: اسم التدفق بأحرف لاتينية صغيرة وأرقام (حتى 48 حرفاً)، ثم أول 8 أحرف من معرّفه، مثل exo_overdue_invoice_reminders_7a17617d. والتدفق الذي لا يحوي اسمه أحرفاً لاتينية أو أرقاماً يصبح exo_flow_<id8>. ووصف الأداة جملة ثابتة من إكزوميشنز (ما يليها بيانات لا تعليمات)، ثم وصف التدفق نفسه، فاكتبه جيداً: هو ما يقرؤه الذكاء الاصطناعي ليقرر متى يستخدم التدفق.
| المعامل | النوع | ملاحظات |
|---|---|---|
| payload | object | تُمرَّر إلى خطوة المشغّل. حتى 512 كيلوبايت و10 مستويات و1,000 مفتاح و5,000 عنصر لكل قائمة. |
تعيد الأداة executionId وflowId وflowName وstatus (queued، أو held عند تجاوز الحصة الشهرية). ولا تنتظر التدفق؛ اقرأ التشغيل بأداة exo_get_execution.
يُعرض حتى 200 تدفق.
أدوات قراءة التشغيل
exo_list_executions
آخر تشغيلات تدفق واحد، دون الحمولات.
| المعامل | النوع | ملاحظات |
|---|---|---|
| flowId | string | إلزامي. |
| limit | integer | من 1 إلى 100. الافتراضي 20. |
| status | string | إحدى القيم: queued, running, success, partially_succeeded, failed, retrying, waiting_approval, skipped, rejected, held. |
| since | string | وقت بصيغة ISO-8601. التشغيلات بعده فقط. |
exo_get_execution
تشغيل واحد: الحالة والبيئة ووقت البدء والانتهاء والمدة وعدد المحاولات والخطأ وبيانات المشغّل وكل خطوة بمدخلاتها ومخرجاتها وخطئها.
| المعامل | النوع | ملاحظات |
|---|---|---|
| executionId | string | إلزامي. |
| nodeId | string | تُرجِع هذه الخطوة فقط. |
| nodeType | string | تُرجِع الخطوات من هذا النوع فقط. لا يُستخدم مع nodeId. |
| includeParentOutputs | boolean | مع nodeId: تُرجِع كذلك مخرجات الخطوات السابقة. |
{
"jsonrpc": "2.0", "id": 4, "method": "tools/call",
"params": {
"name": "exo_get_execution",
"arguments": { "executionId": "0b6f6c1e-5a55-4d0e-9a57-2f7c1d0e8a11" }
}
}exo_get_execution_step
خطوة واحدة من تشغيل واحد كاملة. المعاملات: executionId وnodeId وكلاهما إلزامي.
completeness يذكر بدقة ما حُذف، فلا يحسب الذكاء الاصطناعي الرد الجزئي كاملاً.أدوات البناء
| الأداة | ماذا تفعل |
|---|---|
| exo_search_apps | البحث في كتالوج التطبيقات؛ ومع appId تعرض عمليات التطبيق ومعاملاتها. |
| exo_get_node_types | أنواع الخطوات المتاحة للتدفق مع إعداداتها ومخرجاتها. |
| exo_list_flows | كل تدفقات مساحة العمل مع الحالة ونوع المشغّل. |
| exo_get_flow | تعريف تدفق واحد. الأسرار فيه مخفية. |
| exo_validate_flow | تفحص تعريفاً وتعيد الأخطاء والتحذيرات. لا تحفظ شيئاً. |
| exo_create_flow | تنشئ تدفقاً. يُحفظ دائماً كمسودة. |
| exo_update_flow | تعدّل تدفقاً. يعود مسودة؛ والتدفق العامل في الإنتاج يواصل تشغيل نسخته المنشورة. |
| exo_activate_flow | تفعّل تدفقاً سبق أن نقله شخص إلى بيئة الاختبار (والتدفق الموجود في بيئة التطوير يُنقل إلى بيئة الاختبار)، بعد اجتيازه الفحوص نفسها التي في التطبيق. أما التدفقات المضبوطة على الإنتاج، وهو الافتراضي للتدفقات الجديدة، فتُرفض، وكذلك التدفقات التي تشغّل، بنفسها أو عبر تدفقات فرعية حتى ستة مستويات، خطوة حكومية محجوبة من نفاذ أو مقيم أو تم، أو فيها خطوة تدفق فرعي بلا هدف ثابت، أو خطوة تحمل نوعين متعارضين، والتدفقات ذات التدفقات الفرعية الأعمق: يفعّلها شخص في التطبيق. |
فحص الباقة: لكل نوع خطوة باقة. ترفض exo_create_flow وexo_update_flow التدفق الذي يضيف خطوة لا تشملها باقة مساحة عملك قبل حفظ أي شيء: تحمل النتيجة isError: true وcode: "PLAN_REQUIRED" مع الباقة المطلوبة (requiredPlan) والخطوات المعنية (steps) والرسالة بالإنجليزية والعربية والصينية. وتوضح exo_get_node_types الخطوات التي تشملها باقتك، وتذكرها exo_validate_flow كتحذيرات.
ما لا يُكشف
- التدفقات المفعّلة فقط تصبح أدوات. المسودات والتدفقات المتوقفة غير مرئية لمفتاح
execute. - التدفقات التي فيها خطوة طلب نفاذ لا تُعرض كأدوات.
- التدفقات التي فيها خطوة مقيم أو تم تغيّر سجلاً حكومياً لا تُعرض كأدوات. تدفقات الاستعلام فقط تبقى متاحة.
- التشغيلات التي نفّذت إحدى تلك الخطوات لا تُقرأ عبر MCP كذلك.
- والأمر نفسه عبر التدفقات الفرعية: التدفق الذي يشغّل أحد تلك التدفقات كتدفق فرعي لا يُعرض، والتشغيل الذي بدأ عبر MCP لا يستطيع بدء أحدها كتدفق فرعي.
- بيانات التشغيل التي تُعاد إلى الذكاء الاصطناعي ترافقها ملاحظة بأنها محتوى غير موثوق: بيانات، لا تعليمات أبداً.
- والمفتاح ذو صلاحية
buildيرى هذه التدفقات مع ذلك فيexo_list_flowsوexo_get_flowليساعد في تعديلها. - يستطيع شخص عرض تدفق نفاذ كأداة عمداً بالمفتاح الموجود في منشئ التدفقات ← تنبيهات. أما تدفقات معاملات مقيم وتم فلا مفتاح لها في التطبيق بعد.
- روابط تنزيل المستندات المولّدة تُحذف من بيانات التشغيل.
صيغة النتيجة
ترد كل أداة بالحقول الثلاثة نفسها:
| الحقل | المحتوى |
|---|---|
| content | ملخص نصي تتبعه البيانات بصيغة JSON للعملاء الذين يقرؤون النص فقط. يُقتطع عند 100,000 بايت مع علامة واضحة. |
| structuredContent | البيانات كاملة ككائن. |
| isError | true عند فشل الأداة نفسها، مثل معرّف تنفيذ غير معروف. |
الأخطاء
أخطاء البروتوكول تستخدم كائن الخطأ في JSON-RPC. والأداة التي تفشل تعيد نتيجة عادية فيها isError: true.
{
"jsonrpc": "2.0",
"id": 3,
"error": { "code": -32001, "message": "API key lacks the 'build' permission required for flow authoring tools" }
}| الرمز | HTTP | المعنى |
|---|---|---|
| -32001 | 401 | لا بيانات اعتماد، أو رمز OAuth غير صالح أو منتهٍ. |
| -32001 | 403 | مفتاح غير صالح أو غير نشط أو منتهٍ؛ صلاحية ناقصة؛ مساحة عمل موقوفة. |
| -32001 | 429 | حد معدل مساحة العمل. انتظر مدة Retry-After. |
| -32602 | 200 | أداة غير معروفة أو اسم أداة ناقص أو حمولة تتجاوز الحدود. |
| -32601 | 200 | الطريقة غير موجودة. |
| -32700 | 400 | المحتوى ليس JSON صالحاً. |
| -32603 | 200 | خطأ داخلي. يحمل الرد معرّف خطأ تذكره للدعم. |
| -32600 | 405 | أي طريقة HTTP غير POST وGET وOPTIONS. |
| — | 429 | حدّ المفتاح الواحد. الجسم { "error": "Rate limit exceeded for MCP requests", "code": "RATE_LIMIT", "message": "Rate limit exceeded for MCP requests" } عادي وليس كائن JSON-RPC. انتظر Retry-After. |
الحدود
| الحد | القيمة |
|---|---|
| طلبات في الدقيقة لكل جهة مرسِلة، API و MCP معاً | 100 |
| طلبات في الدقيقة لكل مفتاح، حد أقصى | 200 |
| طلبات في الدقيقة لمساحة العمل | Starter 100 · Professional 200 · Enterprise 500 |
| أدوات التدفقات المعروضة | 200 |
| حمولة التدفق | 512 KB |
| محتوى الطلب | 8 MB |
التشغيلات التي تبدأ عبر MCP تُحسب من الحصة الشهرية وحد التزامن نفسيهما كأي تشغيل آخر.
المراجعة والأمان
- تُحدَّد مساحة العمل من المفتاح نفسه. لا يستطيع مفتاح الوصول إلى تدفقات مساحة أخرى.
- كل تشغيل تدفق وقراءة تشغيل وطلب بناء يُسجَّل في سجل التدقيق مع اسم المفتاح.
- أعطِ كل عميل مفتاحه الخاص بأقل صلاحيات يحتاجها وبتاريخ انتهاء.
حل المشكلات
| ما تراه | السبب والحل |
|---|---|
| لا أدوات تدفقات | المفتاح بلا صلاحية execute أو لا يوجد تدفق مفعّل. |
| تدفق واحد مفقود | هو مسودة أو متوقف أو يحوي خطوة نفاذ أو مقيم أو تم لا تُعرض افتراضياً. |
| Unknown tool | أُعيدت تسمية التدفق أو أُلغي تفعيله. استدعِ tools/list مجدداً. |
| status: held | تجاوزت مساحة العمل 120% من حصتها الشهرية. اشحن أو انتظر بداية الشهر الجديد. |
| 401 | الترويسة ناقصة أو أُرسل المفتاح في عنوان URL. |
