Workflows Overview

Composite workflows let you chain multiple MCP tools into a single, reusable pipeline defined in plain YAML. Each workflow is a directed acyclic graph (DAG) of steps -- the engine resolves dependencies automatically, runs independent steps in parallel, and exposes the whole pipeline as one tool in list_tools.

Why Use Workflows?

Quick Start

1. Create a Workflow File

Save a YAML file in the workflows/ directory (or examples/workflows/).

# workflows/my-pipeline.yaml
name: my-pipeline
description: Fetch data, transform it, store the result

inputs:
  source_url:
    type: string
    description: URL to fetch raw data from
  format:
    type: string
    description: Target output format (json, csv, parquet)

steps:
  - id: fetch
    tool: http.get
    description: Download raw data
    args:
      url: "${inputs.source_url}"
      timeout: 30

  - id: transform
    tool: transform.convert
    description: Convert to requested format
    depends_on: [fetch]
    args:
      data: "${fetch.output}"
      target_format: "${inputs.format}"
    retry: 2
    on_error: fail

  - id: store
    tool: storage.put
    description: Persist transformed data
    depends_on: [transform]
    args:
      content: "${transform.output}"
      key: "pipeline/${inputs.format}/latest"

output: "${store.output}"

2. Start Argus MCP

Workflows are automatically discovered at server startup. The engine scans:

• workflows/ -- primary directory for your own workflow files
• examples/workflows/ -- example / reference workflows shipped with the project

Each valid workflow YAML becomes a composite tool -- it appears in list_tools alongside regular backend tools.

3. Invoke the Workflow

From any MCP client:

{
  "method": "tools/call",
  "params": {
    "name": "my-pipeline",
    "arguments": {
      "source_url": "https://api.example.com/data",
      "format": "json"
    }
  }
}

The engine handles the rest: dependency resolution, parallel execution, interpolation, retries, and final output assembly.

YAML Reference

Top-Level Fields

Input Parameters

Each key under inputs defines a parameter:

inputs:
  repo:
    type: string             # JSON Schema type
    description: Repository  # Shown to callers
    required: true           # default: true

Step Fields

Output Template

The output field is a string with interpolation references. It determines what value the composite tool returns to the caller.

output: "${transform.output}"

If omitted, the engine returns the output of the last step in the definition.

How the DAG Engine Works

Dependency Resolution

The engine computes a topological ordering of steps, grouping them into levels:

Level 0:  [code-metrics]   [dependency-audit]    [security-scan]
                 │                  │                   │
                 └──────────────────┼───────────────────┘
                                    │
Level 1:                         [merge]

• Level 0 steps have no depends_on -- they all run in parallel.
• Level 1 steps depend on Level 0 -- they wait until all dependencies complete, then execute.

This is computed via topological_order(), which returns List[List[Step]] -- a list of levels, each containing the steps that can run concurrently at that level.

Parallel Execution (Fan-Out / Fan-In)

Steps within the same level execute concurrently using asyncio.gather():

          ┌─── code-metrics ───┐
          │                    │
Input ────┼─── dep-audit ──────┼──── merge ──── Output
          │                    │
          └─── security-scan ──┘

This pattern is called fan-out / fan-in: the pipeline fans out to multiple parallel analyses, then fans in to a single merge step.

Parameter Interpolation

Step arguments support ${...} references:

Interpolation happens recursively -- an argument can mix literal text with multiple references:

args:
  message: "Results for ${inputs.repo}: ${code-metrics.output}"

Conditional Execution

Add a condition to any step. If the expression evaluates to falsy, the step is skipped (status SKIPPED) and subsequent steps see it as completed.

- id: security-scan
  tool: security.scan
  condition: "${inputs.run_security}"
  on_error: skip

Supported condition forms:

Retry and Error Strategies

Each step can define its own error handling:

The retry field specifies how many times to re-attempt a failed step before applying the on_error strategy:

- id: flaky-api
  tool: external.api_call
  retry: 3
  on_error: skip

This retries up to 3 times. If all attempts fail, the step is skipped.

Composite Tools

Every loaded workflow becomes a composite tool -- it appears in the list_tools response with:

When a client calls the composite tool, the engine:

1. Parses the workflow DAG
2. Resolves the topological order
3. Executes levels sequentially, steps within each level in parallel
4. Interpolates arguments between steps
5. Returns the resolved output template (or last step's output)

The call goes through the full middleware chain (Recovery, Audit, Routing), so composite tool invocations are audited and have the same error recovery as regular tool calls.

TUI Integration

The Operations > Workflows tab in the TUI displays all discovered workflows. Three actions are available:

Select a row in the table to see a step-by-step breakdown of the workflow.

Examples

Two example workflows are included in examples/workflows/:

data-pipeline.yaml -- Linear ETL

A simple three-stage pipeline: fetch, transform, store. Demonstrates sequential dependencies, input substitution, and retry.

fetch  →  transform  →  store

multi-tool-analysis.yaml -- Parallel Fan-Out

Runs three independent analyses in parallel, then merges the results. Demonstrates parallel execution, conditional skipping, and fan-in.

code-metrics     ─┐
dependency-audit ─┼─► merge
security-scan    ─┘

Creating Your Own

1. Copy a template -- start from examples/workflows/data-pipeline.yaml or use the New Workflow button in the TUI.
2. Define inputs -- declare what parameters callers must provide.
3. Add steps -- each step needs a unique id and a tool name matching a tool available through your configured backends.
4. Set dependencies -- use depends_on to create the DAG structure. Steps without dependencies run in parallel.
5. Test locally -- use the TUI's Run button for a dry-run, or invoke via an MCP client.
6. Set error handling -- add retry and on_error to steps that may fail transiently.

Validation

The engine validates every workflow at load time:

• Required fields -- name and steps must be present
• Unique IDs -- no duplicate step IDs
• Valid references -- every depends_on entry must match an existing step ID
• Acyclicity -- the dependency graph must be a DAG (no cycles)

Invalid workflows are logged as warnings and skipped -- they won't appear in list_tools.

Module map