MCP Tools
Workflows

run_workflow

Manually run an Active workflow, dispatching a live agent session. Inactive workflows are refused; a Paused schedule does not block manual runs. Returns the run record — check its status to see whether the run started, failed, or was skipped.

Parameters

NameTypeRequiredDefaultDescription
workflow_idstringYes—UUID of the workflow to run immediately. The workflow must be "active" — running an inactive or archived one is rejected, so set the status with `update_workflow` first. Its schedule's state (On or Paused) does not matter for a manual run. The call starts the run and returns straight away; it does not wait for the work to finish.
input_valuesobjectNo—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.

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 an inactive or archived one is rejected, so set the status with `update_workflow` first. Its schedule's state (On or Paused) does not matter for a manual run. 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",
  "$schema": "http://json-schema.org/draft-07/schema#",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "Workflow run UUID."
    },
    "status": {
      "type": "string"
    },
    "link_url": {
      "type": "string",
      "format": "uri",
      "description": "Direct URL to view this run in Marcora."
    },
    "error_reason": {
      "type": [
        "string",
        "null"
      ]
    },
    "trigger_type": {
      "type": "string"
    },
    "error_summary": {
      "type": "string"
    },
    "runner_session_id": {
      "type": "string"
    },
    "workflow_template_id": {
      "type": "string",
      "format": "uuid",
      "description": "Parent workflow UUID."
    }
  }
}

Instructions

Manually run a workflow. Creates a workflow_run and dispatches a Managed Agents session. Returns the run row — check .status to know what happened.

Input roles:

  • workflow_id: UUID string of the workflow to run.
  • input_values: object matching the workflow's declared inputs schema. Call get_workflow first if unsure.

Only an Active workflow can run. An Inactive (or archived) one is refused, and the refusal can reach you as an unreadable protocol error rather than a clear message — so if you are not sure of the status, check it with get_workflow first. If it is Inactive, tell the user so, and set it Active with update_workflow if they want it to run. The schedule has nothing to do with manual runs: a Paused schedule does not stop run_workflow, and an On schedule does not let an Inactive workflow run.

Usage patterns:

  • Always inspect the returned .status:
    • "running" → dispatch succeeded; a real Managed Agents session is live.
    • "failed" → dispatch failed; .error_reason has the cause. Tell the user specifically what went wrong.
    • "skipped" → the runner decided no work was needed (rare for manual runs, common for scheduled).
  • For scheduled runs, prefer creating a trigger via create_workflow's schedule_config — don't loop run_workflow calls.
  • input_values must match workflow.inputs schema. For workflows with no declared inputs, pass {} or omit.
  • The returned id is a UUID string for the workflow_run. Use it as run_id in get_workflow_runs (single-mode) to inspect the run.

Links: present link_url to the user exactly as returned — copy it character for character. Never retype, shorten, or rebuild a link or the IDs inside it.

Scroll to Top