workflows

---

title: Workflows sidebar_label: Workflows (16) sidebar_position: 2 doc_type: reference

Workflows

Overview

List, run, and monitor your automated workflows.

Prerequisites

• API key with the MCP preset and required scopes
• Configured MCP client (see Configuration)

Quick start examples

Run and monitor a workflow

1. List available workflows :

{
  "name": "workflow_list",
  "arguments": {}
}

2. Start the execution :

{
  "name": "workflow_execute",
  "arguments": {
    "workflowId": "uuid-du-workflow"
  }
}

3. Check the execution status :

{
  "name": "workflow_status",
  "arguments": {
    "runId": "uuid-de-lexecution"
  }
}

---

workflow_cancel

[CONTROL] Cancel a running or queued workflow execution.

USE WHEN: • Need to stop a workflow taking too long • Aborting due to detected issues • Freeing resources from stuck execution RETURNS: Success status, previous status, cancellation confirmation FEATURES: • Cancels pending, queued, or running executions • BullMQ job cleanup for queued executions • Optional cancellation reason stored REQUIRES: runId (from workflow_execute); optional: reason RELATED: • workflow_status: Check status before cancelling • workflow_execute: Restart if needed EXAMPLE: "Stop the running workflow" or "Cancel execution X" → this tool

Scope	mcp.workflow.execute
Read-only	No
Destructive	Yes
Idempotent	No

Parameters

Parameter	Type	Required	Description
runId	string	Yes	The workflow run ID to cancel
reason	string	No	Optional reason for cancellation

Response

Field	Type	Description
success	boolean
runId	string
workflowId	string
workflowName	string
previousStatus	string
message	string

Related tools : workflow_status, workflow_execute

---

workflow_create

[WRITE] Create a new workflow definition.

USE WHEN: • Need to programmatically create a new workflow • Building automation pipelines via MCP • Creating workflows from scratch or with pre-defined blocks RETURNS: Workflow ID, name, status, version NOTE: Creates a workflow via CQRS command. The flow definition can include blocks (nodes) and connections (edges). Use workflow_update to modify later. REQUIRES: name; optional: description, flowDefinition, canvasId RELATED: • workflow_update: Modify the workflow after creation • workflow_execute: Run the workflow • workflow_list: List existing workflows • workflow_validate: Validate workflow before execution EXAMPLE: "Create a workflow called Data Sync" → this tool

Scope	mcp.write
Read-only	No
Destructive	No
Idempotent	No

Parameters

Parameter	Type	Required	Description
name	string	Yes	Workflow name
canvasId	string (uuid)	No	Canvas ID to assign the workflow to (uses default canvas if not provided)
description	string	No	Workflow description

Response

Field	Type	Description
workflowId	string
name	string
description	string
status	string
version	number
canvasId	string
createdAt	string

Related tools : workflow_update, workflow_execute, workflow_list, workflow_validate

---

workflow_execute

[EXECUTION] Trigger workflow execution with optional input variables.

USE WHEN: • Ready to run a workflow after validation • Need to execute with custom input variables • Triggering manual or programmatic execution RETURNS: runId, taskId, streamUrl for tracking, initial status (queued) FEATURES: • Durable execution with automatic checkpointing • Crash recovery from last checkpoint • Async by default with SSE streaming support • Resolve by ID or name (case-insensitive) REQUIRES: workflowId OR workflowName; optional: inputs (key-value), async RELATED: • workflow_status: Track execution progress and result • workflow_cancel: Stop if needed • workflow_validate: Check before running EXAMPLE: "Run the daily report workflow" or "Execute with input X=5" → this tool

Scope	mcp.workflow.execute
Read-only	No
Destructive	No
Idempotent	No

Parameters

Parameter	Type	Required	Description
async	boolean	No	Return immediately with task ID (true) or wait for completion (false) (default : true)
inputs	record	No	Input variables for the workflow
workflowId	string (uuid)	No	Workflow ID to execute
workflowName	string	No	Workflow name to execute (alternative to workflowId, case-insensitive)

Response

Field	Type	Description
workflow	object
id	string
name	string
wasResolvedByName	boolean
runId	string
taskId	string
streamUrl	string
status	enum
result	unknown

Example

{
  "name": "workflow_execute",
  "arguments": {
    "workflowId": "uuid-du-workflow"
  }
}

Related tools : workflow_status, workflow_cancel, workflow_validate

---

workflow_export

Export a workflow as portable JSON for backup, transfer, or version control.

USE WHEN:

• Need to back up a workflow definition
• Need to migrate a workflow between environments
• Need to version-control a workflow in Git RETURNS: portable workflow JSON with checksums and metadata.

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
workflowId	string (uuid)	Yes	ID of the workflow to export
format	choice (json, yaml)	No	Export format (default: json)
includeTestCases	boolean	No	Include test cases in export (default: false)

Response

Field	Type	Description
portable	record

Related tools : workflow_import, workflow_export_bulk

---

workflow_export_bulk

Export multiple workflows at once as portable JSON.

USE WHEN:

• Need to back up multiple workflows
• Need to migrate a set of workflows between environments RETURNS: array of portable workflow definitions with count.

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
workflowIds	array	Yes	IDs of workflows to export
includeTestCases	boolean	No	Include test cases in export (default: false)

Response

Field	Type	Description
workflows	array
count	number

Related tools : workflow_export, workflow_list

---

workflow_get

[QUERY] Get detailed workflow definition: blocks, connections, configuration.

USE WHEN: • Need to understand workflow structure before execution • Debugging workflow behavior or connections • Reviewing block configurations RETURNS: Complete definition with blocks (type, position, config), connections, metadata FEATURES: • Resolve by ID or name (case-insensitive) • Optional includeDefinition flag to skip block details • Block type breakdown in summary REQUIRES: workflowId OR workflowName (at least one); optional: includeDefinition RELATED: • workflow_validate: Validate before execution • workflow_execute: Run the workflow • workflow_list: Find workflow by name first EXAMPLE: "Show the compliance workflow definition" → this tool

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
includeDefinition	boolean	No	Include full flow definition with blocks and connections (default : true)
workflowId	string (uuid)	No	Workflow ID to retrieve
workflowName	string	No	Workflow name to retrieve (alternative to workflowId, case-insensitive)

Response

Field	Type	Description
wasResolvedByName	boolean

Related tools : workflow_list, workflow_validate, workflow_execute

---

workflow_get_block_output

[DEBUG] Get output and execution details of a specific workflow block.

USE WHEN: • Debugging why a block failed or produced unexpected output • Inspecting AI block token usage • Understanding block execution timing RETURNS: Block input/output, errors, duration, token usage, execution logs FEATURES: • Token tracking for AI blocks (input/output/total) • Execution logs from workflow_events • Error details with stack traces • Variables produced by the block • Checkpoint and execution_trace fallback REQUIRES: runId, blockId; optional: includeInput, includeLogs RELATED: • workflow_get_variables: Get variable snapshot at this block • workflow_status: Get overall execution result EXAMPLE: "Why did block X fail?" or "Show output of the filter block" → this tool

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
blockId	string	Yes	The block ID to get output for
runId	string	Yes	The workflow run ID (wfr_xxx format or UUID)
includeInput	boolean	No	Include the input that was passed to this block (default : true)
includeLogs	boolean	No	Include execution logs for this block (default : true)

Response

Field	Type	Description
runId	string
workflowId	string
input	number
output	number
variablesProduced	array
tokens	object
total	number
logs	array

Related tools : workflow_get_variables, workflow_status

---

workflow_get_variables

[DEBUG] Get runtime variable values at any point in workflow execution.

USE WHEN: • Debugging data flow between blocks • Understanding what values were available at specific point • Tracking variable changes through execution RETURNS: Variable names, values, types, sources; optional: changed variables from previous block FEATURES: • Checkpoint-based variable snapshots • Block-specific variable state (before that block) • Final state if no blockId specified • Internal variable filtering (__ prefix) • Variable diff from previous block REQUIRES: runId; optional: blockId (for snapshot), includeInternal RELATED: • workflow_get_block_output: Get block input/output details • workflow_status: Get overall execution result EXAMPLE: "What was the value of X?" or "Show variables before filter block" → this tool

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
runId	string	Yes	The workflow run ID (wfr_xxx format or UUID)
blockId	string	No	Specific block ID to get variables for (returns snapshot before that block)
includeInternal	boolean	No	Include internal variables (prefixed with __) (default : false)

Response

Field	Type	Description
runId	string
workflowId	string
status	string
blockId	string
blockType	string
blockIndex	number
variables	array
availableAt	array
changedVariables	array
timestamp	string

Related tools : workflow_get_block_output, workflow_status

---

workflow_import

Import a workflow from portable JSON into the current workspace.

USE WHEN:

• Need to restore a backed-up workflow
• Need to migrate a workflow from another environment
• Need to import a workflow shared via Git RETURNS: import result with workflow ID and status. NOTE: Use dryRun=true to validate before actual import.

Scope	mcp.write
Read-only	No
Destructive	No
Idempotent	No

Parameters

Parameter	Type	Required	Description
workflow	record	Yes	Portable workflow JSON object (from workflow_export)
conflictResolution	choice (fail, update_if_newer, force_update, create_new)	No	How to handle name conflicts (default: fail)
dryRun	boolean	No	Validate without persisting (default: false)
preserveId	boolean	No	Keep original workflow ID (default: false)

Response

Field	Type	Description
success	boolean
workflowId	string
name	string
status	enum
error	string

Related tools : workflow_export, workflow_list

---

workflow_list

[DISCOVERY] List available workflows with status, triggers, and metadata.

USE WHEN: • Need to discover available workflows in the workspace • Finding a workflow by name or status RETURNS: List of workflows with IDs, names, status, node counts, last run timestamps FEATURES: • Filter by status (draft, published, archived) • Search by name with ILIKE pattern matching • Pagination support (limit/offset) REQUIRES: optional: status, limit, offset, search RELATED: • workflow_get: Get full definition with blocks and connections • workflow_execute: Run a workflow • workflow_validate: Check before execution EXAMPLE: "What workflows exist?" or "Find the compliance workflow" → this tool

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
limit	number	No	Maximum results (default : 50)
offset	number	No	Pagination offset (default : 0)
search	string	No	Search by name
status	choice (draft, published, archived, all)	No	Filter by status (default : "all")

Response

Field	Type	Description
workflows	array
total	number
hasMore	boolean

Example

{
  "name": "workflow_list",
  "arguments": {}
}

Related tools : workflow_get, workflow_execute, workflow_validate

---

workflow_schedule_create

[MUTATION] Create a scheduled trigger for a workflow.

USE WHEN: • Need to run a workflow on a schedule • Setting up recurring automation (daily, hourly, weekly) • Creating time-based workflow triggers RETURNS: Created schedule ID, next run time, confirmation FEATURES: • Cron: Flexible expression (e.g., "0 9 * * MON-FRI") • Interval: Regular intervals (seconds, minutes, hours, days, weeks) • Specific: Fixed times on specific days • Timezone support (IANA format) • Concurrency control (maxConcurrent) • Timeout configuration REQUIRES: workflowId OR workflowName, name, scheduleType; then type-specific: cronExpression | intervalValue+intervalUnit | specificTimes RELATED: • workflow_schedule_list: View existing schedules • workflow_schedule_trigger: Test-run immediately • workflow_validate: Validate workflow before scheduling EXAMPLE: "Run the report workflow every day at 9am" → this tool with cron "0 9 * * *"

Scope	mcp.write, mcp.workflow.execute
Read-only	No
Destructive	No
Idempotent	No

Parameters

Parameter	Type	Required	Description
name	string	Yes	Schedule name
scheduleType	choice (cron, interval, specific)	Yes	Type of schedule
workflowId	string (uuid)	Yes	Workflow ID to schedule
cronExpression	string	No	Cron expression (for scheduleType=cron). Example: "0 9 * * MON-FRI"
description	string	No	Schedule description
intervalUnit	choice (seconds, minutes, hours, days, weeks)	No	Interval unit (for scheduleType=interval)
intervalValue	number	No	Interval value (for scheduleType=interval)
isEnabled	boolean	No	Whether schedule is active immediately (default : true)
maxConcurrent	number	No	Max concurrent executions (default : 1)
specificTimes	array	No	Specific times (for scheduleType=specific)
timeoutMs	number	No	Execution timeout in ms (default: 5 minutes) (default : 300000)
timezone	string	No	Timezone (IANA format). Default: Europe/Paris (default : "Europe/Paris")
workflowName	string	No	Alternative: workflow name (if ID unknown)

Response

Field	Type	Description
scheduleId	string
name	string
workflowId	string
workflowName	string
scheduleType	string
expression	string
timezone	string
isEnabled	boolean
nextRunAt	string
message	string

Related tools : workflow_schedule_list, workflow_schedule_trigger, workflow_validate

---

workflow_schedule_list

[DISCOVERY] List scheduled workflow triggers with their configuration and run statistics.

USE WHEN: • Need to see scheduled workflows • Checking schedule status (active/paused) • Finding schedules for a specific workflow RETURNS: List of schedules with expressions, next run times, run statistics (total/success/failed) FEATURES: • Filter by workflow ID or status • Cron, interval, and specific time formats • Run statistics and last run status • Pagination support REQUIRES: optional: workflowId, status, limit, offset RELATED: • workflow_schedule_create: Create new schedule • workflow_schedule_trigger: Test-run a schedule now • workflow_list: Find workflow to schedule EXAMPLE: "What schedules exist?" or "When does the daily report run?" → this tool

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
limit	number	No	Maximum results (default : 50)
offset	number	No	Pagination offset (default : 0)
status	choice (active, paused, all)	No	Filter by status (default : "all")
workflowId	string (uuid)	No	Filter by workflow ID

Response

Field	Type	Description
schedules	array
total	number
hasMore	boolean

Related tools : workflow_schedule_create, workflow_schedule_trigger, workflow_list

---

workflow_schedule_trigger

[EXECUTION] Manually trigger a scheduled workflow immediately.

USE WHEN: • Need to run a scheduled workflow now for testing • Urgent execution outside normal schedule • Verifying schedule configuration works RETURNS: runId for tracking, schedule and workflow details FEATURES: • Immediate execution bypassing schedule timing • Does not affect regular schedule (next run unchanged) • Resolve by schedule ID or name • Full execution tracking via runId REQUIRES: scheduleId OR scheduleName RELATED: • workflow_status: Track execution with returned runId • workflow_schedule_list: Find schedule to trigger • workflow_execute: Direct workflow execution (not via schedule) EXAMPLE: "Run the daily report now" → this tool

Scope	mcp.workflow.execute
Read-only	No
Destructive	No
Idempotent	No

Parameters

Parameter	Type	Required	Description
scheduleId	string	Yes	Schedule ID to trigger
scheduleName	string	No	Alternative: schedule name (if ID unknown)

Response

Field	Type	Description
success	boolean
scheduleId	string
scheduleName	string
workflowId	string
workflowName	string
runId	string
triggeredAt	string
message	string

Related tools : workflow_status, workflow_schedule_list, workflow_execute

---

workflow_status

[MONITORING] Get current status and result of a workflow execution.

USE WHEN: • Tracking a running workflow • Checking if execution completed • Retrieving final result or error RETURNS: Status (pending/running/completed/failed/cancelled), result, duration, errors, progress FEATURES: • Real-time progress percentage • Current block tracking • Execution duration calculation • Error details on failure REQUIRES: runId (from workflow_execute) RELATED: • workflow_get_variables: Debug variable values at any point • workflow_get_block_output: Get specific block output • workflow_cancel: Stop running execution EXAMPLE: "Check if workflow is done" or "Get execution result" → this tool

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
runId	string (uuid)	Yes	The workflow run ID to check

Response

Field	Type	Description
runId	string
workflowId	string
workflowName	string
status	enum
progress	number
currentNode	string
result	unknown
error	string
startedAt	string
completedAt	string
duration	number

Related tools : workflow_get_variables, workflow_get_block_output, workflow_cancel

---

workflow_update

[WRITE] Update an existing workflow definition.

USE WHEN: • Need to modify workflow blocks, connections, or metadata • Changing workflow name, description, or status • Publishing or archiving a workflow RETURNS: Updated workflow ID, name, status, new version OCC: Provide expectedVersion to detect concurrent modifications. If another user modified the workflow, a version conflict error is returned. REQUIRES: workflowId; optional: name, description, flowDefinition, status, expectedVersion RELATED: • workflow_get: Get current workflow state before updating • workflow_create: Create a new workflow • workflow_validate: Validate updated workflow EXAMPLE: "Update workflow to add a new condition block" → this tool

Scope	mcp.write
Read-only	No
Destructive	No
Idempotent	No

Parameters

Parameter	Type	Required	Description
workflowId	string (uuid)	Yes	ID of the workflow to update
description	string	No	New workflow description
expectedVersion	number	No	Expected version for OCC conflict detection
name	string	No	New workflow name
status	choice (draft, published, archived)	No	New workflow status

Response

Field	Type	Description
workflowId	string
name	string
status	string
version	number
updatedAt	string

Related tools : workflow_get, workflow_create, workflow_validate

---

workflow_validate

[VALIDATION] Pre-flight validation of workflow before execution.

USE WHEN: • Before running a workflow to catch issues early • After modifying workflow structure • Debugging why workflow fails to start RETURNS: isValid, canExecute, issues list with severity/code/suggestions, structure summary FEATURES: • Block configuration validation (required fields, formats) • Circular dependency detection • External reference validation (agents, entities, subflows) • Variable usage analysis (undefined, unused) • Trigger and output block checks REQUIRES: workflowId OR workflowName; optional: checkReferences, checkCycles, checkVariables RELATED: • workflow_execute: Run if validation passes • workflow_get: Review structure if issues found EXAMPLE: "Validate before running" or "Check workflow for errors" → this tool

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
checkCycles	boolean	No	Check for circular dependencies in the flow (default : true)
checkReferences	boolean	No	Validate external references (agents, entities, subflows) (default : true)
checkVariables	boolean	No	Analyze variable usage and detect issues (default : true)
workflowId	string (uuid)	No	Workflow ID to validate
workflowName	string	No	Workflow name to validate (alternative to workflowId)

Response

Field	Type	Description
workflowId	string
workflowName	string
isValid	boolean
canExecute	boolean
summary	object
errorCount	number
warningCount	number
infoCount	number
issues	array
references	array
structure	object
blockCount	number
connectionCount	number
hasTrigger	boolean
hasOutput	boolean
hasCycles	boolean

Related tools : workflow_execute, workflow_get

---

Troubleshooting

Code	Message	Solution
404	Workflow not found	Check the ID with workflow_list.

Need help?

Contact us: Support and contact.