sortie-mcp

Campaign orchestration MCP server for AI agents — dependency DAGs, parallel fan-out, failure policies, and embedded notes.

Think make for AI agent workflows, where the LLM is the planner that generates and adapts the DAG at runtime.

Install

pip install sortie-mcp

Or with uv:

uv add sortie-mcp

Quick Start

1. Set up PostgreSQL

sortie-mcp requires PostgreSQL 15+ with pgvector.

export DATABASE_URL="postgresql://user:pass@localhost:5432/mydb"
export SORTIE_SCHEMA="sortie"  # default

2. Run the MCP server

sortie-mcp
# or: python -m sortie_mcp.server

The server runs on stdio transport. Configure it in your MCP client:

{
  "sortie": {
    "command": ["sortie-mcp"],
    "env": {
      "DATABASE_URL": "postgresql://..."
    }
  }
}

3. Run the campaign runner

sortie-runner
# or: python -m sortie_mcp.runner

Add to cron for autonomous operation:

*/15 * * * * /path/to/venv/bin/sortie-runner

Architecture

One MCP server, three perspectives:

• Coordinator (e.g. a dispatcher agent): create, list, steer, pause/cancel campaigns
• Worker (specialist agents): get context, add notes, complete/fail steps, spawn subtasks
• Runner (cron): capacity-aware watchdog that dispatches ready steps and consults the planner LLM

Step Types

Type	Description
atomic	Single task executed by one agent
parallel_group	Fan-out: children run concurrently
sequence	Pipeline: each step depends on the previous
for_each	Map: apply a template to each item in a list

Key Features

• DAG splice (spawn_and_continue): agents can split work into subtasks + continuation
• Branch abort (abort_branch): scoped early return from an ancestor step
• Skip cascade: transitive propagation through the dependency graph
• Priority scheduling: urgent / high / normal / low / background
• Advisory dedup: fingerprinting warns the planner of duplicate steps
• Depth limits: spawn_and_continue hidden from agents at max depth
• Embedded notes: pgvector semantic search across campaign findings

Configuration

Env Var	Default	Description
DATABASE_URL	postgresql://localhost/sortie	PostgreSQL connection string
SORTIE_SCHEMA	sortie	Database schema name
SORTIE_MAX_CONCURRENT	4	Max parallel running steps
SORTIE_ZOMBIE_TIMEOUT	30	Minutes before a stuck step is reset
LITELLM_URL	http://localhost:4000	LiteLLM proxy URL (for planner)
LITELLM_KEY		LiteLLM API key
SORTIE_PLANNER_MODEL	qwen3.5:9b	Model for the planner LLM
OPENCLAW_RUNTIME_URL	http://localhost:3000	Agent runtime API

Development

uv sync
uv run pytest
uv run ruff check .
uv run mypy src tests

License

GPL-3.0-or-later. See LICENSE.