MCP Tools
Workflows

run_workflow

Manually run a workflow, dispatching a live agent session. Returns the run record; check its status to see whether the run started, failed, or was skipped.

Input Schema

{
  "type": "object",
  "required": [
    "workflow_id"
  ],
  "properties": {
    "workflow_id": {
      "type": "string",
      "description": "UUID of the workflow to run immediately. The workflow must be \"active\" — running a draft or archived one is rejected, so set the status with `update_workflow` first. The call starts the run and returns straight away; it does not wait for the work to finish."
    },
    "input_values": {
      "description": "Object holding the actual values for this run, matching the fields the workflow declares in its `inputs`. They are handed to the agent as the run's inputs and it is instructed to use only what you provide, so include every id or value the steps depend on. Defaults to an empty object when omitted, which is correct for workflows that take no inputs."
    }
  }
}

Output Schema

{
  "type": "object",
  "required": [
    "id",
    "workflow_template_id",
    "status",
    "link_url"
  ],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Workflow run UUID. Use as run_id in get_workflow_runs (single mode)."
    },
    "status": {
      "enum": [
        "running",
        "failed",
        "skipped"
      ],
      "type": "string"
    },
    "link_url": {
      "type": "string",
      "format": "uri"
    },
    "error_reason": {
      "type": [
        "string",
        "null"
      ],
      "description": "Failure cause when status is failed, else null."
    },
    "trigger_type": {
      "type": "string",
      "description": "How the run was triggered. manual for this tool."
    },
    "error_summary": {
      "type": "string"
    },
    "runner_session_id": {
      "type": "string"
    },
    "workflow_template_id": {
      "type": "string",
      "format": "uuid"
    }
  }
}

Instructions

Manually run a workflow now. Creates a workflow run and dispatches a Managed Agents session. Inspect the returned status to know what happened.

Status meanings: running = dispatch succeeded, a session is live; failed = dispatch failed, read error_reason for the cause; skipped = the runner decided no work was needed (rare for manual runs).

Parameters:

  • workflow_id (string uuid, required): UUID of the workflow to run
  • input_values (object, optional): Object matching the workflow's declared inputs schema. Pass {} or omit for workflows with no inputs. Call get_workflow first if unsure

Output: The workflow run object.

  • id (string uuid): Workflow run UUID. Use as run_id in get_workflow_runs (single mode) to inspect the run
  • workflow_template_id (string uuid): Parent workflow UUID
  • status (string): running, failed, or skipped
  • trigger_type (string): How the run was triggered (manual here)
  • runner_session_id (string): Managed Agents session ID for the run
  • error_reason (string or null): Failure cause when status is failed, else null
  • error_summary (string): Human-readable error summary
  • link_url (string uri): Direct URL to view this run in Marcora
Scroll to Top