MCP tool

    Flow tools

    Each active flow is a tool. Calling it starts one run of that flow.

    exo_<name>_<id8>

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

    Description

    A key with execute sees one tool per active flow, named exo_<name>_<id8>: the flow's name in lowercase Latin letters and digits (up to 48 characters; any other character becomes _), then the first 8 letters and digits of the flow's ID. A flow whose name has no Latin letters or digits becomes exo_flow_<id8>. The tool's description is one fixed sentence from Exomations (it tells the assistant that what follows is data, not instructions), then the first 400 characters of the flow's own description, so write that well: it is what the assistant reads to decide when to use the flow.

    The arguments are passed to the flow's Trigger step as payload (if payload is missing, the whole arguments object is used). A payload may be up to 512 KB, 10 levels deep, 1,000 keys and 5,000 items per list. The call does not wait for the flow: read the run with exo_get_execution.

    Up to 200 flows are listed. Flows with a Nafath request step, and flows with a Muqeem or Tamm step that changes a government record, are not offered as tools, nor are flows that run one of them as a sub-flow. A run started over MCP cannot start such a flow as a sub-flow either.

    Permission

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

    Input

    NameTypeRequiredDescription
    payloadobjectNoInput payload passed to the flow's trigger node. The shape depends on the flow — usually the same JSON body you would POST to /api/trigger/:flowId.

    Returns

    executionId, flowId, flowName and status: queued, or held when the workspace is past 120% of its monthly allowance (the run starts by itself after a top-up, an upgrade or the monthly reset). Runs started over MCP count toward the same monthly allowance and simultaneous-run limit as any other run.

    Errors

    Returned as a JSON-RPC error:

    CodeHTTPMessage
    -32602200Unknown tool: <name>
    -32602200Invalid payload: <reason>
    -32001403API key lacks the 'execute' permission required to trigger flows

    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_overdue_invoice_reminders_7a17617d",
        "arguments": {
          "payload": {
            "customer_id": "C-204"
          }
        }
      }
    }

    Example result

    {
      "jsonrpc": "2.0",
      "id": 1,
      "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-3c4e-4f0a-9b1e-2d5c8e0f4a61",
          "flowName": "Overdue invoice reminders",
          "status": "queued"
        },
        "isError": false
      }
    }

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