MCP tool
cascades_trigger_workflow
Run a saved cascade for an applicant — i.e. start a decision. POSTs to /api/v1/workflows/:id/trigger and returns the created execution, which starts in status "pending" (the run is async). After calling this, poll cascades_get_execution with the returned execution id until status is terminal (completed / failed / cancelled / awaiting_review). execution_mode defaults to "test", which also works on draft cascades; "live" requires a production-approved account and an active cascade and is otherwise rejected.
REST operation
This tool makes one call:
POST
/api/v1/workflows/{id}/trigger
— see triggerWorkflow in the API reference for the full response schema and error codes.
The server adds the Idempotency-Key header itself.
Input schema
| Argument | Type | Description |
|---|---|---|
workflow_id
required
|
integer |
Workflow id. Only workflows owned by the token's account resolve; a foreign or deleted id returns `404`. |
payload
|
object |
The decision input. Put the subject under `applicant`; arbitrary nested fields are allowed and become the execution's `input_context`. Defaults to `{}` when omitted. |
execution_mode
|
string |
`test` uses synthetic vendor data and never bills; `live` requires production access and an active cascade.
One of:
test live |
external_reference
|
string |
Your correlation id for this run. Echoed on the execution and on every webhook event. |
environment
|
string |
Target environment: "prod" (default) or "dev".
One of:
dev prod |
Example
What the model sends, and the JSON the tool returns (the REST response, verbatim).
{
"name": "cascades_trigger_workflow",
"arguments": {
"workflow_id": 157,
"execution_mode": "test",
"payload": {
"applicant": {
"first_name": "Sandrx",
"last_name": "Bowkey"
}
}
}
}{
"data": {
"id": 4821,
"object": "execution",
"workflow_id": 157,
"status": "pending",
"execution_mode": "test",
"created_at": "2026-09-09T17:04:11Z"
}
}