Workflows v2 (Plays) / MCP

Run workflow

Execute an explicitly identified saved workflow against a batch of input records. Never use this for a generic content request. Use executionMode=external_agent for ICP/Dream account-first table-only runs: research and scoring pause for claim-agent-work-order and submit-agent-artifact, then continue via delayed-run recovery. Other graphs containing hosted AI require allowHostedAi=true from a hosted-enabled client; external-only clients are rejected before a hosted run is created. Deterministic graphs need no hosted-AI consent. Each record is one row processed by the DAG end-to-end. Execution is fire-and-forget - the route returns 202 with an execution_id immediately; poll list-workflow-runs or get-workflow-run for status.

tools/callDeterministic operation

Parameters

workspaceIdOptional · string: Optional workspace ID or slug. Required when this credential can access multiple workspaces and no workspace was configured on the client.
workflowIdRequired · string: Workflow UUID to execute.
executionModeOptional · string: external_agent hands ICP scoring and research to claimable Codex work orders. No hosted AI. Supported table-only graphs only.external_agent · pipeline_hosted
runModeOptional · string: See the input schema for this field.pilot · full
pilotLimitOptional · number: Maximum people across the whole source fanout.
resumeExecutionIdOptional · string: Resume a failed connections import from its saved checkpoint. An expired cursor requires a fresh run instead.
cancelExecutionIdOptional · string: Stop an active connections import. An in-flight provider read cannot be recalled.
allowHostedAiOptional · boolean: Explicit consent for hosted AI nodes. Requires a hosted-enabled client.
recordsOptional · array: Array of input records, one per row to process. Shape matches the workflow's expected input schema.

Request example

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "run-workflow",
    "arguments": {
      "workflowId": "00000000-0000-4000-8000-000000000000"
    }
  }
}

Full input schema

Input schema

{
  "type": "object",
  "properties": {
    "workspaceId": {
      "type": "string",
      "minLength": 1,
      "description": "Optional workspace ID or slug. Required when this credential can access multiple workspaces and no workspace was configured on the client."
    },
    "workflowId": {
      "type": "string",
      "description": "Workflow UUID to execute."
    },
    "executionMode": {
      "type": "string",
      "enum": [
        "external_agent",
        "pipeline_hosted"
      ],
      "description": "external_agent hands ICP scoring and research to claimable Codex work orders. No hosted AI. Supported table-only graphs only."
    },
    "runMode": {
      "type": "string",
      "enum": [
        "pilot",
        "full"
      ]
    },
    "pilotLimit": {
      "type": "number",
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum people across the whole source fanout."
    },
    "resumeExecutionId": {
      "type": "string",
      "description": "Resume a failed connections import from its saved checkpoint. An expired cursor requires a fresh run instead."
    },
    "cancelExecutionId": {
      "type": "string",
      "description": "Stop an active connections import. An in-flight provider read cannot be recalled."
    },
    "allowHostedAi": {
      "type": "boolean",
      "description": "Explicit consent for hosted AI nodes. Requires a hosted-enabled client."
    },
    "records": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "additionalProperties": true
      },
      "description": "Array of input records, one per row to process. Shape matches the workflow's expected input schema."
    }
  },
  "required": [
    "workflowId"
  ]
}

See this operation inCLI REST API TypeScript SDK