T
Task Graph Mcp
MCP server for agent task workflows with phases, prompts, gates, and multi-agent coordination
Quick Install
Automated & IDE SetupCopy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.
Manual Client & Custom JSON ConfigExpand JSON ▾
Install Config Generator
Choose your client
💡 Paste into ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
Documentation Overview
Task Graph MCP Server
Agent task workflows that actually work.
When you have AI agents working on complex tasks, things go wrong fast. Agents lose context, skip steps, forget to coordinate. Task Graph solves this with structured workflows: phases to guide work, prompts for automatic guidance, gates to enforce quality, and coordination primitives for multi-agent scenarios—all through the Model Context Protocol.
Why Task Graph?
The problem: You've got complex tasks that need structured execution. Maybe a single agent working through phases, or multiple agents coordinating in parallel. Without proper workflows, agents lose track, skip steps, and produce inconsistent results.
What you get:
- Structured workflows — Phases (explore, implement, review, test) guide agents through work. Transition prompts provide automatic guidance at each step.
- Quality gates — Require tests to pass, code to be committed, or reviews to complete before transitions. Enforce your standards automatically.
- Ready-to-use topologies — Pre-built workflows for solo work, parallel swarms, specialist relays, or hierarchical delegation. Start immediately, customize later.
- Configurable workflows — Define your own states, phases, prompts, and gates. Match your process, not ours.
- Multi-agent coordination — Advisory file locks, DAG dependencies, atomic claiming. No more conflicts or duplicate work.
- Token-efficient — Designed for LLM context limits. Compact queries, minimal round-trips, structured outputs.
- Built-in accounting — Track tokens, cost, and time per task. Know exactly what your agents are spending.
- Zero infrastructure — SQLite with WAL mode. No database server to run. Just point at a file.
Features
| Feature | Description |
|---|---|
| Task Hierarchy | Unlimited nesting with parent/child relationships |
| DAG Dependencies | Typed edges (blocks, follows, contains) with cycle detection |
| Phases | Categorize work type (explore, implement, review, test, deploy) |
| Workflows | Named workflow topologies (solo, swarm, relay, hierarchical) |
| Transition Prompts | Automatic agent guidance on status/phase changes |
| Gates | Exit requirements for status/phase transitions |
| Atomic Claiming | Strict locking with limits and tag-based routing |
| File Coordination | Advisory locks with reasons and change polling |
| Cost Tracking | Token usage and USD cost per task |
| Time Tracking | Automatic accumulation from state transitions |
| Live Status | Real-time "current thought" visible to other agents |
| Full-text Search | FTS5-powered search across tasks and attachments |
| Attachments | Inline content, file references, or media storage |
| Agent Feedback | Inter-agent communication with categorized feedback (conditional on config) |
| Dynamic Overlays | Runtime workflow customization via add/remove overlay tools |
Quick Start
Installation
From crates.io (Recommended)
Pre-built Binaries
Download the latest release for your platform from GitHub Releases:
| Platform | Download |
|---|---|
| Linux (x64) | task-graph-mcp-x86_64-unknown-linux-gnu.tar.gz |
| macOS (Intel) | task-graph-mcp-x86_64-apple-darwin.tar.gz |
| macOS (Apple Silicon) | task-graph-mcp-aarch64-apple-darwin.tar.gz |
| Windows (x64) | task-graph-mcp-x86_64-pc-windows-msvc.zip |
Extract and place the binary in your PATH.
From Source
The binary will be at target/release/task-graph-mcp.
Usage
As an MCP Server
Add to your MCP client configuration:
CLI Options
Configuration
Full reference: See docs/CONFIGURATION.md for complete configuration documentation including workflows, prompts, gates, roles, and tags.
Create .task-graph/config.yaml:
States Configuration
Task states are configurable. Default states: pending, working, completed, failed, cancelled.
To add a ready state for auto-advance:
See SCHEMA.md for full documentation on state definitions.
Dependencies Configuration
Dependency types define how tasks relate to each other. Default types: blocks, follows, contains, duplicate, see-also, relates-to.
| Property | Values | Description |
|---|---|---|
display | horizontal, vertical | Visual relationship (same-level vs parent-child) |
blocks | none, start, completion | What the dependency blocks |
Attachments Configuration
Preconfigured attachment keys provide default MIME types and modes, reducing boilerplate when attaching common content types.
| Property | Values | Description |
|---|---|---|
unknown_key | allow, warn, reject | Behavior for undefined attachment keys |
definitions.<key>.mime | MIME type string | Default MIME type for this key |
definitions.<key>.mode | append, replace | Default mode (append keeps existing, replace overwrites) |
Built-in defaults:
| Key | MIME Type | Mode | Use Case |
|---|---|---|---|
commit | text/git.hash | append | Git commit hashes |
checkin | text/p4.changelist | append | Perforce changelists |
changelist | text/plain | append | Files changed |
meta | application/json | replace | Structured metadata |
note | text/plain | append | General notes |
log | text/plain | append | Log output |
error | text/plain | append | Error messages |
output | text/plain | append | Command/tool output |
diff | text/x-diff | append | Patches and diffs |
plan | text/markdown | replace | Plans and specs |
result | application/json | replace | Structured results |
context | text/plain | replace | Current context/state |
Usage:
Environment variables:
TASK_GRAPH_CONFIG_PATH: Path to configuration file (takes precedence over.task-graph/config.yaml)TASK_GRAPH_DB_PATH: Database file path (fallback if no config file)TASK_GRAPH_MEDIA_DIR: Media directory for file attachments (fallback if no config file)TASK_GRAPH_LOG_DIR: Log directory path (fallback if no config file)
MCP Tools
Worker Management
| Tool | Description |
|---|---|
connect(worker_id?, tags?, workflow?, force?, db_path?, media_dir?, log_dir?, config_path?, overlays?: str[]) | Register a worker. Optional workflow selects named workflow (solo, swarm, relay, hierarchical). Returns worker_id and active paths. |
disconnect(worker_id: worker_str, final_status?: status_str = "pending") | Unregister worker and release all claims/locks. |
list_agents(tags?: str[], file?: filename, task?: task_str, depth?: int, stale_timeout?: int) | List connected workers with filters. |
cleanup_stale(timeout?: int, final_status?: status_str) | Evict stale workers and release their claims. |
add_overlay(worker_id: str, overlay: str) | Add a dynamic workflow overlay to a connected worker. |
remove_overlay(worker_id: str, overlay: str) | Remove a workflow overlay from a connected worker. |
Task CRUD
| Tool | Description |
|---|---|
create(description: str, id?: task_str, parent?: task_str, priority?: int = 5, points?: int, time_estimate_ms?: int, tags?: str[]) | Create a task. Priority 0-10 (higher = more important). |
create_tree(tree, parent?, child_type?, sibling_type?) | Create nested task tree. child_type (default: "contains") for parent→child deps, sibling_type for sibling deps. |
get(task: task_str) | Get task by ID with attachment metadata and counts. |
list_tasks(status?: status_str[], ready?: bool, blocked?: bool, claimed?: bool, owner?: worker_str, parent?: task_str, recursive?: bool, agent?: worker_str, tags_any?: str[], tags_all?: str[], sort_by?: str, sort_order?: str, limit?: int, offset?: int) | Query tasks with filters. Use ready=true for claimable tasks. |
update(worker_id: worker_str, task: task_str, status?: status_str, phase?: str, assignee?: worker_str, title?: str, description?: str, priority?: int, points?: int, tags?: str[], needed_tags?: str[], wanted_tags?: str[], time_estimate_ms?: int, reason?: str, force?: bool, attachments?: object[]) | Update task. Status/phase changes auto-manage ownership and trigger prompts. Include attachments to record commits/changelists. |
delete(worker_id: worker_str, task: task_str, cascade?: bool, reason?: str, obliterate?: bool, force?: bool) | Delete task. Soft delete by default; obliterate=true for permanent. |
scan(task: task_str, before?: int, after?: int, above?: int, below?: int) | Scan task graph in multiple directions. Depth: 0=none, N=levels, -1=all. |
search(query: str, limit?: int = 20, include_attachments?: bool, status_filter?: status_str) | FTS5 search. Supports phrases, prefix*, AND/OR/NOT, title:word. |
rename(worker_id: worker_str, task: task_str, new_id: task_str) | Atomically rename a task ID across all referencing tables. |
Task Claiming
| Tool | Description |
|---|---|
claim(worker_id: worker_str, task: task_str, force?: bool) | Claim a task. Fails if deps unsatisfied, at limit, or lacks tags. Use force to steal. |
Note: Release via update(status="pending"). Complete via update(status="completed"). Status changes auto-manage ownership.
Dependencies
| Tool | Description |
|---|---|
link(from: task_str|task_str[], to: task_str|task_str[], type?: dep_str = "blocks") | Create dependencies. Types: blocks, follows, contains, duplicate, see-also, relates-to. |
unlink(from: task_str|"*", to: task_str|"*", type?: dep_str) | Remove dependencies. Use * as wildcard. |
relink(prev_from: task_str[], prev_to: task_str[], from: task_str[], to: task_str[], type?: dep_str = "contains") | Atomically move dependencies (unlink then link). |
Tracking
| Tool | Description |
|---|---|
thinking(worker_id: worker_str, thought: str, tasks?: task_str[]) | Broadcast live status. Visible to other workers. Refreshes heartbeat. |
task_history(task: task_str, states?: status_str[]) | Get status transition history with time tracking. |
project_history(from?: datetime_str, to?: datetime_str, states?: status_str[], limit?: int = 100) | Project-wide history with date range filters. |
log_metrics(worker_id: worker_str, task: task_str, cost_usd?: float, values?: int[8]) | Log metrics (aggregated). |
get_metrics(task: task_str|task_str[]) | Get metrics for task(s). |
give_feedback(message: str, category?: str, sentiment?: str, agent_id?: str, tool_name?: str, task_id?: str) | Record feedback about tools, workflows, or UX. Enabled by default; rejects writes past size limit (default: 1MB). |
list_feedback() | Read the feedback markdown file. |
File Coordination
| Tool | Description |
|---|---|
mark_file(worker_id: worker_str, file: filename|filename[], task?: task_str, reason?: str) | Mark file(s) to signal intent. Advisory, non-blocking. |
unmark_file(worker_id: worker_str, file?: filename|filename[]|"*", task?: task_str, reason?: str) | Remove marks. Use * for all. |
list_marks(files?: filename[], worker_id?: worker_str, task?: task_str) | Get current file marks. |
mark_updates(worker_id: worker_str) | Poll for mark changes since last call. |
Attachments
| Tool | Description |
|---|---|
attach(task: task_str|task_str[], name: str, content?: str, mime?: mime_str, file?: filename, store_as_file?: bool, mode?: str) | Add attachment. Use file for reference, store_as_file for media storage. |
attachments(task: task_str, name?: str, mime?: mime_str) | Get attachment metadata. Glob patterns supported for name. |
detach(worker_id: worker_str, task: task_str, name: str, delete_file?: bool) | Delete attachment by name. |
Advanced
| Tool | Description |
|---|---|
check_gates(task: task_str) | Check gate requirements before status/phase transition. Returns unsatisfied gates with pass/warn/fail status. |
get_advisory(topic?: str, task?: task_str, worker_id?: worker_str) | Get governance advisory guidance. Without topic: lists all topics. With topic: returns full advisory content with template expansion. |
query(sql: str, params?: str[], limit?: int = 100, format?: str) | Execute read-only SQL. SELECT only. Requires permission. |
get_schema(table?: str, include_sql?: bool) | Get database schema. Returns table names, columns, types, and foreign keys. |
get_prompts(status?: str, phase?: str, task?: task_str, worker_id?: worker_str) | Get workflow prompts. Without params: lists triggers. With status/phase: returns expanded prompts for that transition. |
list_workflows() | List available workflow configurations (solo, swarm, relay, hierarchical, etc.). |
list_skills() | List available bundled skills with descriptions. |
get_skill(name: str) | Get full content of a bundled skill. |
MCP Resources
| URI | Description |
|---|---|
query://tasks/all | Full task graph with dependencies |
query://tasks/ready | Tasks ready to claim |
query://tasks/blocked | Tasks blocked by dependencies |
query://tasks/claimed | All claimed tasks |
query://tasks/agent/{id} | Tasks owned by an agent |
query://tasks/tree/{id} | Task with all descendants |
query://files/marks | All file marks |
query://agents/all | Registered agents |
query://stats/summary | Aggregate statistics |
config://current | All configuration in one response |
config://states | Task state definitions |
config://phases | Phase definitions |
config://dependencies | Dependency type definitions |
config://tags | Tag definitions |
docs://index | List all available documentation files |
docs://search/{query} | Full-text search across documentation |
docs://skills/list | List available skills |
docs://skills/{name} | Get specific skill content |
docs://workflows/list | List available workflows |
docs://workflows/{name} | Get workflow details |
docs://overlays/list | List available overlays |
docs://overlays/{name} | Get overlay details |
docs://{path} | Specific documentation file content |
Task Tree Structure
Create hierarchical tasks with create_tree:
Tree Node Fields
| Field | Description |
|---|---|
title | Task title (required for new tasks) |
description | Task description |
id | Custom task ID (UUID7 generated if omitted) |
ref | Reference existing task by ID (other fields ignored when set) |
priority | Priority 0-10 (default 5) |
points | Story points / complexity estimate |
time_estimate_ms | Estimated duration in milliseconds |
tags | Categorization tags for the task |
needed_tags | Agent must have ALL of these tags to claim (AND) |
wanted_tags | Agent must have AT LEAST ONE of these tags to claim (OR) |
children | Nested child nodes |
Top-Level Parameters
| Parameter | Default | Description |
|---|---|---|
tree | required | Root node of the task tree |
parent | null | Attach tree root to existing parent task |
child_type | "contains" | Dependency type from parent to children |
sibling_type | null | Dependency type between siblings ("follows" for sequential, null for parallel) |
Referencing Existing Tasks
Use ref to integrate existing tasks into a tree structure:
Tag-Based Affinity
Workers declare capabilities via tags when connecting. Tasks can require specific tags to control which workers can claim them.
Example tag categories:
- Model capabilities:
image-in,audio-out,video-in,code,bulk - Access levels:
prod-access,admin,external - Specializations:
rust,python,frontend,database
Note: Roles like coordinator/reviewer/deployer are better represented using phases.
Task requirements:
needed_tags(AND): Agent must have ALL of thesewanted_tags(OR): Agent must have AT LEAST ONE
Workflows and Phases
Phases
Tasks can have a phase to categorize the type of work being performed:
Built-in phases: explore, implement, review, test, security, deploy, triage, diagnose, design, plan, doc, integrate, monitor, optimize
Phases enable:
- Transition prompts — Automatic guidance when entering/exiting phases
- Gates — Requirements that must be satisfied before phase transitions
- Role-based routing — In relay workflows, specialists own specific phases
Named Workflows
Pre-built workflow topologies optimize for different coordination patterns:
| Workflow | Description | Best For |
|---|---|---|
solo | Single agent, full autonomy | Simple tasks, prototyping |
swarm | Parallel generalists, pull-based | High throughput, independent tasks |
relay | Sequential specialists, handoffs | Complex tasks, domain expertise |
hierarchical | Lead/worker delegation | Large projects, team coordination |
push | Push-based task distribution topology | Centralized assignment, load balancing |
kanban | Board-style task management with WIP limits | Continuous flow, visual tracking |
sprint | Time-boxed iteration planning | Scrum teams, fixed cadence |
Select a workflow on connect:
Each workflow provides tailored prompts and coordination guidance. See WORKFLOW_TOPOLOGIES.md for detailed patterns.
Transition Prompts
Agents receive automatic guidance when status or phase changes:
Prompts support template variables: {{current_status}}, {{valid_exits}}, {{current_phase}}, {{valid_phases}}
Gates
Gates are requirements that must be satisfied before status or phase transitions:
Satisfy a gate by attaching evidence:
Enforcement levels: allow (advisory), warn (blocks unless force=true), reject (hard block)
File Coordination
Agents can coordinate file edits using advisory marks with change tracking:
Architecture
- Transport: Stdio — each worker spawns its own server process
- Database: SQLite with WAL mode for concurrent access across processes
- Deployment: Single binary, no external dependencies, works offline
Compared to Alternatives
| Task Graph | Linear task lists | Custom databases | |
|---|---|---|---|
| Workflow phases | ✓ Built-in with prompts | ✗ Manual tracking | DIY |
| Quality gates | ✓ Configurable enforcement | ✗ | DIY |
| Multi-agent safe | ✓ Atomic claims, file locks | ✗ Race conditions | Maybe, DIY |
| Dependency tracking | ✓ DAG with cycle detection | ✗ Manual ordering | DIY |
| MCP native | ✓ First-class | ✗ Wrapper needed | ✗ Wrapper needed |
| Token accounting | ✓ Built-in | ✗ | DIY |
| Setup required | None | None | Database server |
Documentation
| Document | Description |
|---|---|
| CONFIGURATION.md | Complete configuration reference (config.yaml, workflows, prompts, gates, tags) |
| SCHEMA.md | Database schema and state machine documentation |
| DESIGN.md | Architecture and design decisions |
| WORKFLOW_TOPOLOGIES.md | Multi-agent workflow patterns (solo, swarm, relay, hierarchical) |
| EXPORT_IMPORT.md | Data export and import functionality |
| PROCESSES.md | Release process, changelog maintenance |
| GATES.md | Workflow gate conditions and enforcement |
| METRICS.md | Experiment metrics definitions and SQL examples |
License
Apache 2.0
Built for AI agents that need structured workflows and reliable coordination.
Related MCP Servers
Frequently Asked Questions about Task Graph Mcp
AllMCPs Directory Badge
Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.
Badge Style:
Live Dynamic SVG Preview
Markdown (GitHub README)
[](https://allmcps.com/mcp/task-graph-mcp)HTML Embed
<a href="https://allmcps.com/mcp/task-graph-mcp"><img src="https://allmcps.com/api/badge/task-graph-mcp?style=directory" alt="Task Graph Mcp on AllMCPs" /></a>Technical Specs & Signals
CategoryDeveloper Tools
0/4 checks healthy over the last 6h
27Quality signal: Emerging · 27/100How this signal is calculated ▾
Server availabilityNot measured
Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.
Verified ownership8/20
Documentation & tools11/30
Adoption & activity1/15
Community engagement0/10
A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.
Own this project?
This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to get the verified badge and attach your website.
Free dofollow backlink: after claiming, verify your product site and place a dofollow AllMCPs badge — we recheck it stays live.
Claim & get free dofollowShare & Embed
Add our SVG badge (dark/light directory styles) or embeddable widget to your site.