dag-planner-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., "@dag-planner-mcp plan a multi-step project with dependencies and parallel tasks"
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.
dag-planner-mcp
A durable DAG-based task planner exposed as an MCP (Model Context Protocol) server. It lets AI orchestrators (Claude, ADK-based agents, etc.) break a goal into a dependency graph of tasks, execute them in parallel where possible, track state durably, and handle human-in-the-loop approval — all through a clean set of 22 MCP tools.
Table of Contents
Related MCP server: sortie-mcp
Quick start with uvx
The fastest way to run the server is with uvx — no virtual environment or pip install needed:
uvx dag-planner-mcpPass arguments (e.g. HTTP transport) the same way:
uvx dag-planner-mcp --transport streamable-http --host 0.0.0.0 --port 8000With an environment variable:
DATABASE_URL="sqlite:///dag_planner.db" uvx dag-planner-mcpClaude Desktop — one-line config (uvx)
Open claude_desktop_config.json and add:
{
"mcpServers": {
"dag-planner-mcp": {
"command": "uvx",
"args": ["dag-planner-mcp"],
"env": {
"DATABASE_URL": "sqlite:////home/user/data/dag_planner.db"
}
}
}
}No installation step is required — uvx fetches and caches the package automatically on first run.
Install this skill
AI agents (Claude, Copilot, etc.) can pick up ready-made instructions for using this MCP server by installing the bundled skill:
npx skills add Shubhamnegi/dag-planner-mcp --skill use-mcp-toolOr install directly from the skill path:
npx skills add https://github.com/Shubhamnegi/dag-planner-mcp/tree/main/skills/use-mcp-toolWhat the skill provides
File | Purpose |
Core instructions — when/how to use the tool | |
Full installation and client integration guide | |
Runnable code examples (parallel tasks, HITL gates, checkpoints) | |
Common failure cases and fixes | |
Quick sanity check — run after install | |
Complete orchestrator example (stdio + HTTP) |
Requirements
Python ≥ 3.11
DATABASE_URLenvironment variable (defaults tosqlite:///dag_planner.db)
Requirements
Dependency | Version |
Python | ≥ 3.11 |
mcp[cli] | ≥ 1.6.0 |
sqlalchemy | ≥ 2.0 |
pydantic | ≥ 2.0 |
jsonschema | ≥ 4.0 |
aiosqlite | ≥ 0.19 |
Optional (PostgreSQL):
Dependency | Version |
asyncpg | ≥ 0.29 |
Optional (Dashboard):
Dependency | Version |
streamlit | ≥ 1.35 |
graphviz | ≥ 0.20 |
pandas | ≥ 2.0 |
Installation
1. Clone the repository
git clone https://github.com/Shubhamnegi/dag-planner-mcp.git
cd dag-planner-mcp2. Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate # Linux / macOS
.venv\Scripts\activate # Windows3. Install the package
SQLite (dev — no extra dependencies):
pip install -e .PostgreSQL (prod):
pip install -e ".[postgres]"With development/test dependencies:
pip install -e ".[dev]"With Streamlit dashboard:
pip install -e ".[dashboard]"Database Configuration
The server is controlled entirely via the DATABASE_URL environment variable. Tables are created automatically on first start.
SQLite (development)
# Default — creates dag_planner.db in the current directory
export DATABASE_URL="sqlite:///dag_planner.db"
# Absolute path
export DATABASE_URL="sqlite:////home/user/data/dag_planner.db"
# In-memory (testing only — data lost on exit)
export DATABASE_URL="sqlite:///:memory:"No additional setup is required for SQLite.
PostgreSQL (production)
export DATABASE_URL="postgresql://user:password@localhost:5432/dag_planner"Create the database first:
CREATE DATABASE dag_planner;Then start the server — SQLAlchemy will create all tables automatically.
For connection pooling / SSL in production you can pass extra query parameters:
export DATABASE_URL="postgresql://user:password@host:5432/dag_planner?sslmode=require"Environment Variables
Variable | Default | Description |
|
| SQLAlchemy connection URL (SQLite or PostgreSQL) |
|
| Host to bind when using HTTP transport |
|
| Port to bind when using HTTP transport |
Running the server
stdio (recommended for Claude Desktop and most MCP clients)
dag-planner-mcp
# or
python -m dag_planner_mcp.serverThe server reads from stdin and writes to stdout — no port is opened.
Streamable HTTP
dag-planner-mcp --transport streamable-http --host 0.0.0.0 --port 8000The MCP endpoint will be available at:
http://localhost:8000/mcpUsing with Claude Desktop (stdio)
The recommended approach is to use uvx so no manual installation is needed (see Quick start with uvx above).
If you prefer to point at a locally installed binary:
Open the Claude Desktop configuration file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
Add the server under
mcpServers:
{
"mcpServers": {
"dag-planner-mcp": {
"command": "/path/to/.venv/bin/dag-planner-mcp",
"env": {
"DATABASE_URL": "sqlite:////home/user/data/dag_planner.db"
}
}
}
}Replace /path/to/.venv/bin/dag-planner-mcp with the absolute path to the installed script (run which dag-planner-mcp after installation).
Restart Claude Desktop. The 22 DAG planner tools will appear in the tools panel.
Using with other MCP clients (streamable HTTP)
Start the server in HTTP mode:
DATABASE_URL="sqlite:///dag_planner.db" \
dag-planner-mcp --transport streamable-http --host 0.0.0.0 --port 8000Then point your MCP client at:
http://localhost:8000/mcpExample: Cursor IDE
{
"mcpServers": {
"dag-planner-mcp": {
"url": "http://localhost:8000/mcp"
}
}
}Example: Windsurf / Continue / custom agent
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
async with streamablehttp_client("http://localhost:8000/mcp") as (r, w, _):
async with ClientSession(r, w) as session:
await session.initialize()
result = await session.call_tool("create_workflow_run", {"goal": "Analyze AWS costs"})Streamlit Dashboard
A read-only Streamlit dashboard ships in the dashboard/ directory. It reads
directly from the same database as the MCP server (via DATABASE_URL) and
never writes any data.
Pages
Page | Description |
Overview | Summary metric cards, task status bar chart, recent runs |
Workflows | Paginated & searchable list of all workflow runs |
Run Detail | Per-run deep-dive: task table, interactive DAG graph, event log, human approvals |
Task Detail | Full task state including all JSON payloads |
Quick start
# Install with dashboard extras
pip install -e ".[dashboard]"
# Point at the same database your MCP server uses
export DATABASE_URL="sqlite:///dag_planner.db"
# — or for PostgreSQL —
export DATABASE_URL="postgresql://user:password@localhost:5432/dag_planner"
# Launch
streamlit run dashboard/app.pyThe dashboard opens at http://localhost:8501 by default.
DAG visualization requires the
graphvizsystem package in addition to the Python bindings. Install it withbrew install graphviz(macOS) orapt-get install graphviz(Debian/Ubuntu). If the system package is absent the page falls back to a plain adjacency table.
Available MCP Tools
Planning
Tool | Description |
| Create a new workflow run (returns |
| Define the task DAG for a run (validates for cycles) |
| Cancel downstream tasks and graft a new plan branch |
Scheduling
Tool | Description |
| List tasks that are ready and unclaimed |
| Atomically claim a ready task with a time-bounded lease |
State Management
Tool | Description |
| Transition a claimed task to running |
| Mark done; auto-promotes dependent tasks to ready |
| Mark failed with optional retry |
| Block a task awaiting human decision |
| Resume a human-blocked task after decision |
Task I/O
Tool | Description |
| Store working or final output |
| Save an incremental checkpoint |
| Retrieve all payload data for a task |
Query
Tool | Description |
| Full state of a single task |
| List tasks for a run with filters |
| Workflow run state |
| Tasks blocked on human or dependencies |
| All DAG edges for a run |
Validation
Tool | Description |
| Validate output against the task's JSON Schema contract |
| Check a task list for cycles before submitting |
Subagent-safe wrappers
Tool | Description |
| Narrow task view for a subagent |
| Update working output and optional checkpoint |
| Submit final output and complete the task |
| Block task and request a human decision |
Orchestrator Loop Example
import json
from mcp import ClientSession
from mcp.client.stdio import stdio_client
async def run():
async with stdio_client(["dag-planner-mcp"]) as (r, w):
async with ClientSession(r, w) as session:
await session.initialize()
# 1. Create a workflow
res = await session.call_tool("create_workflow_run", {
"goal": "Analyze AWS cost spike and send report"
})
run_id = json.loads(res.content[0].text)["data"]["run_id"]
# 2. Define the task DAG
await session.call_tool("create_plan_graph", {
"run_id": run_id,
"tasks": [
{
"task_key": "fetch_data",
"title": "Fetch cost data",
"description": "Pull last 3 weeks of AWS cost data",
"owner_agent": "data_agent",
"depends_on": [],
"output_contract": {"type": "object", "required": ["cost_data"]}
},
{
"task_key": "analyze",
"title": "Analyze spike",
"description": "Identify top services causing the spike",
"owner_agent": "analyst_agent",
"depends_on": ["fetch_data"],
"output_contract": {"type": "object", "required": ["summary"]}
}
]
})
# 3. Execution loop
while True:
res = await session.call_tool("get_ready_tasks", {"run_id": run_id})
tasks = json.loads(res.content[0].text)["data"]["tasks"]
if not tasks:
break # All done (or blocked)
for task in tasks:
task_id = task["task_id"]
await session.call_tool("claim_task_for_execution", {
"task_id": task_id, "executor_id": "orchestrator-1"
})
await session.call_tool("mark_task_running", {"task_id": task_id})
# ... dispatch to subagent, collect result ...
output = {"summary": "EC2 caused 40% increase"}
await session.call_tool("put_task_output", {
"task_id": task_id, "output": output, "is_final": True
})
await session.call_tool("validate_task_output", {"task_id": task_id})
await session.call_tool("mark_task_completed", {
"task_id": task_id, "final_output": output
})Running Tests
pip install -e ".[dev]"
pytest tests/ -vAll tests use an in-memory SQLite database and require no external services.
Available Tools
24 toolsclaim_task_for_executionC
Claim a ready task for exclusive execution.
Inputs: task_id (required), executor_id (required), claim_duration_seconds.
create_plan_graphC
Create a plan graph (DAG of tasks) for an existing run.
Inputs: run_id (required), tasks (required), activate.
create_workflow_runC
Create a new workflow run in draft status.
Inputs: goal (required), session_id, user_id, metadata.
get_blocked_tasksB
Return all blocked tasks for a run.
Inputs: run_id (required).
get_dag_edgesC
Return all DAG edges for a run.
Inputs: run_id (required).
get_my_taskC
Get task details from the executing agent's perspective.
Inputs: task_id (required), executor_id.
get_ready_tasksC
Return tasks that are ready and not currently claimed.
Inputs: run_id, owner_agent, limit.
get_taskC
Return full state of a single task.
Inputs: task_id (required).
get_task_payload_refsB
Retrieve all payload data (input, output, checkpoint, contract) for a task.
Inputs: task_id (required).
get_workflow_runC
Return workflow run state.
Inputs: run_id (required), include_tasks.
list_tasksC
List tasks for a run with optional filters.
Inputs: run_id (required), status, owner_agent, limit.
mark_task_blocked_humanC
Block a task pending human approval.
Inputs: task_id (required), question (required), options, requested_by.
mark_task_completedB
Mark a task completed and activate dependent tasks.
Inputs: task_id (required), final_output.
mark_task_failedC
Mark a task failed, with optional retry logic.
Inputs: task_id (required), error, retry.
mark_task_runningC
Transition a task to running status.
Inputs: task_id (required), executor_id.
put_task_checkpointC
Save a checkpoint for a running task.
Inputs: task_id (required), checkpoint (required).
put_task_outputC
Store working or final output for a task.
Inputs: task_id (required), output (required), is_final.
replace_plan_branchC
Cancel downstream tasks from anchor and replace with new tasks.
Inputs: run_id (required), anchor_task_id (required), new_tasks (required).
request_human_inputB
Request human input, blocking the task until decided.
Inputs: task_id (required), question (required), options, requested_by.
resume_taskC
Resume a blocked task after human decision.
Inputs: task_id (required), decision, decided_by.
submit_my_outputC
Submit final output and mark task completed.
Inputs: task_id (required), final_output (required).
update_my_progressC
Update working output and optionally checkpoint progress.
Inputs: task_id (required), working_output (required), checkpoint.
validate_dag_acyclicC
Validate that a task list forms an acyclic DAG.
Inputs: tasks (required).
validate_task_outputC
Validate a task's output against its JSON Schema contract.
Inputs: task_id (required), output.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 24 tools
Each tool targets a distinct action or resource, with descriptions clearly differentiating between agent-specific and system operations. Even conceptually similar tools like mark_task_blocked_human and request_human_input serve separate purposes (blocking vs. input request). No ambiguity.
All tools follow a consistent verb_noun pattern using snake_case, with verbs like claim, create, get, list, mark, put, replace, request, resume, submit, update, validate. The naming is predictable and easy to navigate.
24 tools is on the higher side but reasonable for a DAG planner covering run management, task lifecycle, payloads, human-in-the-loop, and validation. Each tool has a distinct role, and the scope justifies the count without overwhelming.
The tool set covers the full lifecycle of creating runs, plans, and managing tasks with state transitions, checkpoints, and human interaction. Minor gaps exist such as no explicit delete or cancel run tool, but core workflows are well-supported.
Maintenance
Related MCP Connectors
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Task management your AI agents can actually run. One line becomes a context-ready task over MCP.
Control plane for autonomous software labor. Agents claim objectives over MCP with audit trail.
Goal and task planning MCP for Codex and AI agents, with evidence-backed completion.
Related MCP Servers
- 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
- AlicenseAqualityDmaintenanceCampaign orchestration MCP server for AI agents — dependency DAGs, parallel fan-out, failure policies, and embedded notes.21GPL 3.0
- FlicenseAqualityDmaintenanceAn agent-native workflow MCP server that enables AI agents to execute text-defined, versionable workflows with checkpointing and state management.10-
- AlicenseNot gradedqualityCmaintenanceA local, model-independent DAG task coordinator for AI coding agents, with a static visual UI, validated state machine, resumable JSON progress, and MCP tools.MIT