sortie-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@sortie-mcp create a campaign 'data-pipeline' with sequential steps: extract, transform, load"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpOr with uv:
uv add sortie-mcpRelated MCP server: task-orchestrator
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" # default2. Run the MCP server
sortie-mcp
# or: python -m sortie_mcp.serverThe 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.runnerAdd to cron for autonomous operation:
*/15 * * * * /path/to/venv/bin/sortie-runnerArchitecture
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 |
| Single task executed by one agent |
| Fan-out: children run concurrently |
| Pipeline: each step depends on the previous |
| Map: apply a template to each item in a list |
Key Features
DAG splice (
spawn_and_continue): agents can split work into subtasks + continuationBranch abort (
abort_branch): scoped early return from an ancestor stepSkip 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_continuehidden from agents at max depthEmbedded notes: pgvector semantic search across campaign findings
Configuration
Env Var | Default | Description |
|
| PostgreSQL connection string |
|
| Database schema name |
|
| Max parallel running steps |
|
| Minutes before a stuck step is reset |
|
| LiteLLM proxy URL (for planner) |
| LiteLLM API key | |
|
| Model for the planner LLM |
|
| Agent runtime API |
Development
uv sync
uv run pytest
uv run ruff check .
uv run mypy src testsLicense
GPL-3.0-or-later. See LICENSE.
Available Tools
21 toolsabort_branchA
Early return from an ancestor step, skipping the rest of its branch.
Use when you discover that an entire branch of reasoning is pointless — not just your step, but the ancestor that initiated it.
The target step completes with your output (it doesn't fail). The target's parent (the requestor) sees the result and decides what to do next.
Args: target_id: The ancestor step to return from. output: The result for the target step (e.g. "Approach debunked by X"). reason: Why this branch is untenable. Saved as a campaign note. step_id: Your step ID. Inferred from session if omitted.
Returns: List of skipped step IDs.
Inputs: target_id (required), output (required), reason (required), step_id. Returns: object
add_noteA
Record a noteworthy finding during step execution.
Notes are embedded for semantic search across the campaign.
Args: campaign_id: Campaign UUID. content: What you found. Be specific. tags: Optional tags for filtering (e.g. ["finding", "citation"]).
Returns: Note ID and any similar existing notes.
Next: Continue your work. Call complete_step when done.
Inputs: campaign_id (required), content (required), tags. Returns: object
cancel_campaignC
Cancel a campaign. All pending steps are skipped.
Args: id: Campaign UUID.
Inputs: id (required). Returns: object
check_successA
Evaluate whether a campaign has met its typed success contract.
A campaign's success contract (success_metric,
benchmark_command, scope, max_iterations) is set at
creation time by templates like autoresearch. This tool gives
the planner / coordinator a single scalar decision:
met=True— contract satisfied; coordinator should mark the campaigndone.met=False— keep iterating, or escalate if budget exhausted.iterations_used— count of DONE atomic steps on this campaign so far. Useful for comparing againstmax_iterations.metric_value— the most recently recorded metric fromcampaign_notestaggedmetric:<success_metric>(best-effort parse; see below).
How the metric is discovered. The runner / worker agents emit a note of the form::
add_note(campaign_id, f"metric={value}", tags=["metric:<name>"])on every benchmark run. check_success scans the most recent
such note, extracts the float after =, and compares it against
success_metric_threshold if set via steer_campaign(strategy=...).
In v0.3 we only surface the most-recent value — the planner
decides whether it's "good enough". A future revision may wire a
numeric threshold column.
Args: id: Campaign UUID.
Returns:
{met, metric_value, iterations_used, max_iterations, success_metric, notes_checked, reason}
``reason`` is a short string explaining the decision — useful
both for humans looking at logs and for the planner's own
chain-of-thought.A campaign without a success contract returns
{met: False, reason: "no_success_metric_configured"}.
Next: if met is True, call cancel_campaign(id) or
steer_campaign(id, "wrap up"). If False and
iterations_used >= max_iterations, escalate via the
notification channel.
Inputs: id (required). Returns: object
complete_stepA
Mark your step as done with a summary of what you accomplished.
Args:
step_id: Your step ID. Inferred from $SORTIE_STEP_ID if unset.
summary: What you did and what you found. This becomes the step
output visible to downstream steps.
Returns: Confirmation. If the step was already skipped (branch abort),
returns {status: "skipped"} — your output is recorded for audit.
Returns {status: "stale_claim"} if a zombie-reset already
stole your claim — stop working.
Inputs: step_id, summary. Returns: object
create_campaignA
Create a new campaign for long-running, multi-step work.
Args:
goal: What this campaign should accomplish.
name: Short name for display. Auto-generated if omitted.
channel: Discord channel for notifications.
priority: urgent / high / normal / low / background.
max_depth: Max nesting depth for subtasks (default 4).
token_budget: Optional token limit. NULL = unlimited.
dry_run: If true, create in paused status for review.
success_metric: Short metric name emitted by the verifier /
benchmark (e.g. "accuracy_at_1k"). Paired with
benchmark_command. Leave NULL for free-form campaigns.
benchmark_command: Shell / Python invocation that produces a
JSON line with the metric value. Metadata only — the
runner does not execute it; worker steps do.
scope: Freeform identifier narrowing the benchmark
(e.g. "chapter-01", "test_subset_A").
max_iterations: Hard cap on autoresearch-style loops. NULL
means open-ended (planner decides).
Returns: Campaign ID, name, status, next_action_at.
Next: Use get_campaign(id) to check progress, or steer_campaign(id, guidance) to adjust.
Inputs: goal (required), name, channel, priority, +7 more. Returns: object
fail_stepA
Report that you cannot complete your step.
Args:
step_id: Your step ID. Inferred from $SORTIE_STEP_ID if unset.
error: What went wrong and why you can't continue.
Returns: Whether the step can be retried or has failed permanently.
Inputs: step_id, error. Returns: object
get_campaignA
Get full campaign state: goal, strategy, progress, step tree, recent notes.
Sets last_reported_at so next call only returns new activity.
Args: id: Campaign UUID.
Returns: Full campaign state with steps and recent notes.
Inputs: id (required). Returns: object
get_my_contextA
Get campaign context for the step you're executing.
Upstream outputs are returned as previews (head + tail + total
char count) so the context bundle stays small. Call
read_step_output(<id>) when you need the full body of a specific
upstream output.
Args:
step_id: Your step ID. Inferred from $SORTIE_STEP_ID if unset.
Returns: Campaign goal, your task, upstream output previews, notes.
Next: Do your work, then call complete_step(summary) or
fail_step(error).
Inputs: step_id. Returns: object
get_notesB
List notes filtered by tag or step.
Args: campaign_id: Campaign UUID. tags: Filter by tags (OR match). step_id: Filter by step ID.
Returns: Matching notes.
Inputs: campaign_id (required), tags, step_id. Returns: result
get_updatesA
Get delta since last report: completed steps, failures, new notes.
Args: id: Campaign UUID. Omit for updates across all active campaigns.
Returns: Recent completions, failures, and notes.
Inputs: id. Returns: object
heartbeatA
Report that you're still alive and keep your claim + leases fresh.
Long-running agents should call this every few minutes. The runner's
reset_zombies sweep uses heartbeat_at to distinguish healthy
workers from crashed ones. If you hold resource leases (see
requires_locks on your step), the lease expires_at is bumped
by extend_leases_sec from now so the lease reaper won't steal
them out from under you.
Returns {"status": "stale_claim"} if your claim token no longer
matches — this means the zombie reset already repossessed your step.
Stop working immediately if you see that: another runner is
about to pick your step up.
Args:
step_id: Your step ID. Inferred from $SORTIE_STEP_ID if unset.
extend_leases_sec: Seconds of TTL to give every lease you hold.
Default 900 (15 min). Set to 0 for heartbeat-only.
Returns: {"status": "ok" | "stale_claim", "step_id": N}.
Inputs: step_id, extend_leases_sec. Returns: object
list_campaignsA
List campaigns, optionally filtered by status.
Args: status: Filter by status (active/paused/done/failed/cancelled). Omit for all.
Returns: Array of {id, name, status, priority, progress}.
Inputs: status. Returns: result
pause_campaignA
Pause a campaign. Running steps finish but no new ones start.
Args: id: Campaign UUID.
Inputs: id (required). Returns: object
provide_inputA
Provide input to a step that is waiting for a human decision.
Workers call request_input when they need guidance. This tool
unblocks them by supplying the answer and returning the step to
the ready queue.
Args: id: Campaign UUID. step_id: The step waiting for input. answer: Your decision / the information the agent asked for.
Returns: Updated step status.
Inputs: id (required), step_id (required), answer (required). Returns: object
read_step_outputA
Read a range from a step's output (or input) field.
Counterpart to the preview-plus-seek contract in get_my_context:
when an upstream preview is truncated, call this with the
step_id from the preview to pull the full (or a slice of) text.
Args:
step_id: The step whose output you want to read. Does not have
to be your own step — any step in the same campaign's DAG
is readable.
offset: 0-indexed character offset to start from.
limit: Max characters to return (default 8000, capped at 32000
to avoid blowing the agent's context).
field: "output" (default) or "input".
Returns::
{
"step_id": N,
"field": "output",
"content": "...",
"offset": 0,
"limit": 8000,
"total_chars": N,
"has_more": bool, # True if offset+limit < total_chars
}
Inputs: step_id (required), offset, limit, field. Returns: object
request_inputA
Pause your step and ask the coordinator for a decision.
Use when you hit a fork that requires human judgement — e.g. which approach to take, whether to proceed with a risky action, or clarification on ambiguous requirements.
Your step pauses until the coordinator calls provide_input.
When it resumes, the answer will be in your step's input field
(visible via get_my_context).
Args:
step_id: Your step ID. Inferred from $SORTIE_STEP_ID if unset.
question: What you need decided. Be specific.
partial_output: Optional summary of work done so far.
Returns: Confirmation that the step is paused.
Inputs: step_id, question, partial_output. Returns: object
resume_campaignB
Resume a paused campaign.
Args: id: Campaign UUID.
Inputs: id (required). Returns: object
search_notesA
Semantic search across campaign notes.
Args: query: What to search for. campaign_id: Scope to a specific campaign. Omit for all. top_k: Number of results (default 5).
Returns: Ranked results with content and tags. Each entry is
annotated with "mode": "semantic" when cosine ranking was
used, or "mode": "recency" when embeddings were disabled /
unavailable and the server fell back to most-recent-first
listing.
Inputs: query (required), campaign_id, top_k. Returns: result
spawn_and_continueA
Split your work: spawn subtasks and a continuation that resumes after they complete.
Use when you discover you need additional work done before you can finish. The DAG rewires automatically — your downstream dependents will wait for the continuation, not your partial result.
Args: step_id: Your step ID. partial_output: What you've done so far. subtasks: List of {action, agent?} dicts for work that needs doing. continuation: Action description for the step that resumes your work after subtasks complete.
Returns: IDs of created subtasks and the continuation step.
Note: This tool is hidden at max depth — you must complete atomically.
Inputs: step_id (required), partial_output (required), subtasks (required), continuation (required). Returns: object
steer_campaignB
Change campaign direction. Updates strategy for the planner.
Args: id: Campaign UUID. guidance: New direction, constraints, or focus areas.
Returns: Updated strategy.
Inputs: id (required), guidance (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Each tool targets a distinct action in the campaign lifecycle (e.g., create_campaign vs. cancel_campaign, abort_branch vs. spawn_and_continue). While some tools like get_campaign and get_updates overlap in scope, their purposes (full state vs. delta) are clearly differentiated.
All tools follow a consistent verb_noun pattern in snake_case (e.g., abort_branch, create_campaign, complete_step). The naming is predictable and makes the function of each tool immediately understandable.
21 tools is slightly high but justified for a comprehensive workflow orchestration system. Each tool serves a clear purpose in campaign management, step execution, branching, and monitoring. No obvious bloat, though a few tightly related tools (e.g., get_notes, search_notes) could potentially be merged.
The tool set covers the full lifecycle of campaigns and steps: creation, cancellation, pausing, resumption, steering, step execution with branching, input/decision handling, heartbeat monitoring, and comprehensive state retrieval. There are no obvious gaps for the intended domain of long-running multi-step work.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
Open-source Zapier/n8n alternative as an MCP server: agents build, run and debug your workflows.
Work management where AI agents are first-class members: tasks, projects, memory over hosted MCP
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server for AI agents to manage ad campaigns across Google, Meta, LinkedIn, Microsoft, Reddit, TikTok, and more21618 npm21MIT
- AlicenseNot gradedqualityBmaintenanceServer-enforced workflow discipline for AI agents. An MCP server providing persistent work items, dependency graphs, quality gates, and actor attribution. Schemas define what agents must produce — the server blocks the call if they don't. Works with any MCP-compatible client.214MIT
- AlicenseNot gradedqualityDmaintenanceA campaign and task management MCP server for AI coding assistants, enabling dependency tracking, acceptance criteria, testing strategies, and progress monitoring for projects.1MIT
- AlicenseNot gradedqualityCmaintenanceMCP server that enables AI agents to run a deterministic orchestration loop with decomposition, subagent execution, and review feedback across multiple LLM backends.61MIT