المطورون

    دليل خادم MCP

    دع Claude أو Cursor أو أي عميل MCP يشغّل تدفقاتك ويقرأ تشغيلاتك ويصوغ تدفقات جديدة.

    نظرة عامة

    تشغّل إكزوميشنز خادم MCP لكل مساحة عمل. اربط Claude أو Cursor أو أي عميل MCP ليتمكن مساعدك الذكي من تشغيل تدفقاتك المفعّلة والتحقق من نتيجة التشغيل وصياغة تدفقات جديدة لتراجعها.

    POST/api/mcp

    JSON-RPC 2.0 عبر HTTPS. لكل طلب رد JSON واحد؛ لا يوجد بث أحداث ولا جلسة تُحفظ.

    الطريقةالغرض
    initializeالمصافحة. تعيد قدرات الخادم (الأدوات).
    tools/listالأدوات التي يحق لمفتاحك استخدامها.
    tools/callتشغيل أداة واحدة.
    pingفحص الحالة. يعيد كائناً فارغاً.

    إعداد كل عميل في صفحة ربط عميلك. ومدخلات كل أداة ونتيجتها وأخطاؤها ومثال على استدعائها في مرجع أدوات MCP.

    Claude Desktop

    1. في إكزوميشنز افتح مفاتيح API وأنشئ مفتاحاً بصلاحية execute. أضف build إن أردت أن يصوغ المساعد التدفقات أيضاً.
    2. أضف هذا المقطع إلى ملف إعدادات Claude وضع مفتاحك فيه.
    3. أعد تشغيل 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_key
    المفتاح الموضوع في عنوان URL (?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"}}}'

    رد الطلب الثالث:

    {
      "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>. ووصف الأداة جملة ثابتة من إكزوميشنز (ما يليها بيانات لا تعليمات)، ثم وصف التدفق نفسه، فاكتبه جيداً: هو ما يقرؤه الذكاء الاصطناعي ليقرر متى يستخدم التدفق.

    المعاملالنوعملاحظات
    payloadobjectتُمرَّر إلى خطوة المشغّل. حتى 512 كيلوبايت و10 مستويات و1,000 مفتاح و5,000 عنصر لكل قائمة.

    تعيد الأداة executionId وflowId وflowName وstatus (queued، أو held عند تجاوز الحصة الشهرية). ولا تنتظر التدفق؛ اقرأ التشغيل بأداة exo_get_execution.

    يُعرض حتى 200 تدفق.

    أدوات قراءة التشغيل

    exo_list_executions

    آخر تشغيلات تدفق واحد، دون الحمولات.

    المعاملالنوعملاحظات
    flowIdstringإلزامي.
    limitintegerمن 1 إلى 100. الافتراضي 20.
    statusstringإحدى القيم: queued, running, success, partially_succeeded, failed, retrying, waiting_approval, skipped, rejected, held.
    sincestringوقت بصيغة ISO-8601. التشغيلات بعده فقط.

    exo_get_execution

    تشغيل واحد: الحالة والبيئة ووقت البدء والانتهاء والمدة وعدد المحاولات والخطأ وبيانات المشغّل وكل خطوة بمدخلاتها ومخرجاتها وخطئها.

    المعاملالنوعملاحظات
    executionIdstringإلزامي.
    nodeIdstringتُرجِع هذه الخطوة فقط.
    nodeTypestringتُرجِع الخطوات من هذا النوع فقط. لا يُستخدم مع nodeId.
    includeParentOutputsbooleanمع 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 وكلاهما إلزامي.

    التشغيلات الكبيرة جداً (أكثر من 300 خطوة أو 2 ميغابايت من بيانات الخطوات) تعيد تفاصيل الخطوات دون الحمولات. ويتضمن كل رد قسم 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 كتحذيرات.

    لا يستطيع عميل الذكاء الاصطناعي نقل تدفق إلى الإنتاج أبداً. الترقية إلى الإنتاج يجريها شخص في التطبيق. وإعدادات التأكيد الحكومي على الخطوة لا تتغير عبر MCP أبداً.

    ما لا يُكشف

    • التدفقات المفعّلة فقط تصبح أدوات. المسودات والتدفقات المتوقفة غير مرئية لمفتاح execute.
    • التدفقات التي فيها خطوة طلب نفاذ لا تُعرض كأدوات.
    • التدفقات التي فيها خطوة مقيم أو تم تغيّر سجلاً حكومياً لا تُعرض كأدوات. تدفقات الاستعلام فقط تبقى متاحة.
    • التشغيلات التي نفّذت إحدى تلك الخطوات لا تُقرأ عبر MCP كذلك.
    • والأمر نفسه عبر التدفقات الفرعية: التدفق الذي يشغّل أحد تلك التدفقات كتدفق فرعي لا يُعرض، والتشغيل الذي بدأ عبر MCP لا يستطيع بدء أحدها كتدفق فرعي.
    • بيانات التشغيل التي تُعاد إلى الذكاء الاصطناعي ترافقها ملاحظة بأنها محتوى غير موثوق: بيانات، لا تعليمات أبداً.
    • والمفتاح ذو صلاحية build يرى هذه التدفقات مع ذلك في exo_list_flows و exo_get_flow ليساعد في تعديلها.
    • يستطيع شخص عرض تدفق نفاذ كأداة عمداً بالمفتاح الموجود في منشئ التدفقات ← تنبيهات. أما تدفقات معاملات مقيم وتم فلا مفتاح لها في التطبيق بعد.
    • روابط تنزيل المستندات المولّدة تُحذف من بيانات التشغيل.

    صيغة النتيجة

    ترد كل أداة بالحقول الثلاثة نفسها:

    الحقلالمحتوى
    contentملخص نصي تتبعه البيانات بصيغة JSON للعملاء الذين يقرؤون النص فقط. يُقتطع عند 100,000 بايت مع علامة واضحة.
    structuredContentالبيانات كاملة ككائن.
    isErrortrue عند فشل الأداة نفسها، مثل معرّف تنفيذ غير معروف.

    الأخطاء

    أخطاء البروتوكول تستخدم كائن الخطأ في 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المعنى
    -32001401لا بيانات اعتماد، أو رمز OAuth غير صالح أو منتهٍ.
    -32001403مفتاح غير صالح أو غير نشط أو منتهٍ؛ صلاحية ناقصة؛ مساحة عمل موقوفة.
    -32001429حد معدل مساحة العمل. انتظر مدة Retry-After.
    -32602200أداة غير معروفة أو اسم أداة ناقص أو حمولة تتجاوز الحدود.
    -32601200الطريقة غير موجودة.
    -32700400المحتوى ليس JSON صالحاً.
    -32603200خطأ داخلي. يحمل الرد معرّف خطأ تذكره للدعم.
    -32600405أي طريقة 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.

    اربط مساعدك اليوم.

    تجربة 7 أيامتحقق من البطاقة بمبلغ 1 ريالمستضاف في الرياض