MCP tool

    exo_create_flow

    Create a new flow. It is always saved as a draft.

    For tools and AI agents: this page as Markdown · the public OpenAPI file

    Description

    The definition is checked before anything is saved: its size (up to 2 MB, 40 levels deep and 20,000 keys), its structure, the platform's staging checks and your plan. If a check fails, nothing is saved and the problems are returned. The flow goes into projectId, or into your workspace's first project. A workspace at its plan's flow limit cannot create more. Government sign-off settings sent by the client are dropped: only a person can switch them on in the app.

    The new flow is a draft. exo_activate_flow refuses flows whose environment is production, which is where every new flow starts, so a person reviews a new flow in the app before it runs.

    Permission

    Needs an API key or OAuth connection with the build permission.

    Input

    NameTypeRequiredDescription
    namestringYesFlow name.
    definitionobjectYesThe flow definition { nodes, edges }.
    descriptionstringNoOptional flow description.
    projectIdstringNoOptional project id. Defaults to your tenant's first project.
    triggerTypestring: webhook, manual, scheduled, form, poll_trigger, email_trigger, voice_call_ended, whatsapp_messageNoOptional trigger type (default 'webhook').

    Returns

    saved: true, flowId, status: "draft" and warnings. When a government sign-off was dropped, governmentConfirmationIgnored lists the steps.

    Plan check

    Each step type belongs to a plan. A create or update that adds a step your workspace's plan does not include is refused before anything is saved, with code: "PLAN_REQUIRED", the plan it needs (requiredPlan), the steps involved (steps) and the message in English, Arabic and Chinese (messages). exo_get_node_types marks which steps your plan includes, and exo_validate_flow reports them as warnings.

    {
      "saved": false,
      "code": "PLAN_REQUIRED",
      "upgradeRequired": true,
      "currentPlan": "starter",
      "requiredPlan": "pro",
      "steps": [
        {
          "nodeId": "sftp_1",
          "type": "sftp",
          "label": "SFTP / FTP Files",
          "family": "advanced_integrations",
          "requiredPlan": "pro"
        }
      ],
      "messages": {
        "en": "Your Starter plan doesn't include these steps: SFTP / FTP Files. They are part of the Professional plan. Nothing was created. Upgrade to Professional, or use steps your plan includes.",
        "ar": "…",
        "zh": "…"
      }
    }

    Errors

    Returned as a normal result with isError: true:

    • `name` is required.
    • `triggerType` must be one of: <types> (default webhook). Nothing was created.
    • `definition` object is required.
    • `definition` rejected: <reason>.
    • Flow NOT created — <n> error(s), <n> warning(s). Fix the errors and retry: <list>
    • Flow NOT created — the definition failed the platform staging verifier: <violations>. Fix these issues and retry.
    • Project "<projectId>" not found in your tenant.
    • Your tenant has no projects yet. Create a project in the Exomations UI first, then retry.
    • Maximum flow limit (<n>) reached for your plan. Delete a flow or upgrade.
    • Flow NOT created — <reason> (step types: <types>). …

    Returned as a JSON-RPC error:

    CodeHTTPMessage
    -32001403API key lacks the 'build' permission required for flow authoring tools

    Messages are shown exactly as the server sends them, in English. A value in angle brackets is filled in at run time.

    Examples

    Example call

    {
      "jsonrpc": "2.0",
      "id": 1,
      "method": "tools/call",
      "params": {
        "name": "exo_create_flow",
        "arguments": {
          "name": "Post new orders",
          "definition": {
            "nodes": [
              {
                "id": "trigger_1",
                "type": "trigger",
                "position": {
                  "x": 0,
                  "y": 0
                },
                "data": {
                  "nodeType": "trigger",
                  "label": "Webhook",
                  "config": {}
                }
              },
              {
                "id": "http_1",
                "type": "http_request",
                "position": {
                  "x": 260,
                  "y": 0
                },
                "data": {
                  "nodeType": "http_request",
                  "label": "Post order",
                  "config": {
                    "url": "https://example.com/orders",
                    "method": "POST",
                    "body": "{{trigger.order_id}}"
                  }
                }
              }
            ],
            "edges": [
              {
                "id": "e1",
                "source": "trigger_1",
                "target": "http_1"
              }
            ]
          }
        }
      }
    }

    Example result

    {
      "jsonrpc": "2.0",
      "id": 1,
      "result": {
        "content": [
          {
            "type": "text",
            "text": "Flow \"Post new orders\" created as a DRAFT (id=7a17617d-3c4e-4f0a-9b1e-2d5c8e0f4a61). A person reviews and activates it in the Exomations app; exo_activate_flow refuses a flow whose environment is production, which is where every new flow starts.\n{ ... }"
          }
        ],
        "structuredContent": {
          "saved": true,
          "flowId": "7a17617d-3c4e-4f0a-9b1e-2d5c8e0f4a61",
          "status": "draft",
          "warnings": []
        },
        "isError": false
      }
    }

    Example values. In content, the text after the summary line is the same data as structuredContent.