> ## Documentation Index
> Fetch the complete documentation index at: https://taskgraph-ai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Tools

> The TaskGraph MCP server: how its Model Context Protocol tools expose task management to Claude Code and other MCP clients.

This document provides an overview of the MCP (Model Context Protocol) interface for the TaskGraph application. The MCP interface is defined in the `mcp-server/` directory and exposes the application's core functionalities as a set of tools that can be called remotely.

## Core Concepts

The MCP interface is built on top of the `fastmcp` library and registers a set of tools that correspond to the core functionalities of the TaskGraph application. These tools are defined in the `mcp-server/src/tools/` directory and are registered with the MCP server in `mcp-server/src/tools/index.js`.

Each tool is defined with a name, a description, and a set of parameters that are validated using the `zod` library. The `execute` function of each tool calls the corresponding core logic function from `scripts/modules/task-manager.js`.

## Configurable Tool Loading

To optimize LLM context usage, you can control which TaskGraph MCP tools are loaded using the `TASKGRAPH_TOOLS` environment variable. This is particularly useful when working with LLMs that have context limits or when you only need a subset of tools.

### Configuration Modes

#### Core Tools (Default, Lean Mode)

Loads only 7 essential tools for daily development. Ideal for minimal context usage.

**Core tools included:**

* `get_tasks` - List all tasks
* `next_task` - Find the next task to work on
* `get_task` - Get detailed task information
* `set_task_status` - Update task status
* `add_note` - Log a progress note on a task or subtask, as written (no AI call)
* `parse_prd` - Generate tasks from PRD
* `expand_task` - Break down tasks into subtasks

```json theme={null}
{
  "mcpServers": {
    "taskgraph-ai": {
      "command": "npx",
      "args": ["-y", "taskgraph-ai"],
      "env": {
        "TASKGRAPH_TOOLS": "core"
      }
    }
  }
}
```

You can also use `"lean"` as an alias for `"core"`. If `TASKGRAPH_TOOLS` is not set, core tools are loaded by default.

#### Standard Tools

Loads 16 commonly used tools. Balances functionality with context efficiency.

**Standard tools include all core tools plus:**

* `update_subtask` - Have the AI write notes onto a subtask
* `initialize_project` - Set up new projects
* `analyze_project_complexity` - Analyze task complexity
* `expand_all` - Expand all eligible tasks
* `add_subtask` - Add subtasks manually
* `remove_task` - Remove tasks
* `add_task` - Create new tasks
* `complexity_report` - View complexity analysis
* `dependency_analysis` - Bottlenecks, critical path and why a task is blocked

```json theme={null}
{
  "mcpServers": {
    "taskgraph-ai": {
      "command": "npx",
      "args": ["-y", "taskgraph-ai"],
      "env": {
        "TASKGRAPH_TOOLS": "standard"
      }
    }
  }
}
```

#### Custom Tool Selection

Specify exactly which tools to load using a comma-separated list. Tool names are case-insensitive and support both underscores and hyphens.

```json theme={null}
{
  "mcpServers": {
    "taskgraph-ai": {
      "command": "npx",
      "args": ["-y", "taskgraph-ai"],
      "env": {
        "TASKGRAPH_TOOLS": "get_tasks,next_task,set_task_status,add_note"
      }
    }
  }
}
```

#### All Tools

Loads all available (40) tools, including `github_status` and `github_push` (see [GitHub Sync](https://taskgraph-ai.com/capabilities/github-sync.md)). Use when you need full TaskGraph functionality.

```json theme={null}
{
  "mcpServers": {
    "taskgraph-ai": {
      "command": "npx",
      "args": ["-y", "taskgraph-ai"],
      "env": {
        "TASKGRAPH_TOOLS": "all"
      }
    }
  }
}
```

### Choosing the Right Configuration

* **Use `core`/`lean`**: Default setting, ideal for basic task management workflows or when context limits are strict
* **Use `standard`**: For most development workflows that include task creation and analysis
* **Use `all`**: When you need full functionality including tag management, dependencies, and advanced features
* **Use custom list**: When you have specific tool requirements or want to experiment with minimal sets

### Verification

When the MCP server starts, it logs which tools were loaded:

```
TaskGraph MCP Server starting...
Tool mode configuration: standard
Loading standard tools
Registering 16 MCP tools (mode: standard)
Successfully registered 16/16 tools
```

## Tool Categories

The MCP tools can be categorized in the same way as the core functionalities:

### 1. Task and Subtask Management

* **`add_task`**: Creates a new task. `discoveredFrom` links it to the task it was found in, without blocking it.
* **`add_subtask`**: Adds a subtask to a parent task.
* **`remove_task`**: Removes one or more tasks or subtasks.
* **`remove_subtask`**: Removes a subtask from its parent.
* **`update_task`**: Updates a single task.
* **`add_note`**: Appends a progress note to a task or subtask as written, with a timestamp. No AI call.
* **`update_subtask`**: Has the AI write notes onto a subtask.
* **`update`**: Updates multiple tasks.
* **`move_task`**: Moves a task or subtask.
* **`clear_subtasks`**: Clears all subtasks from one or more tasks.

### 2. Task Information and Status

* **`get_tasks`**: Lists tasks as compact JSON with `id`, `title`, `status`, `priority` and `dependencies`. `fields` asks for more (`"title,details"`, or `"all"`), `status` filters (`"pending,review"`), and `withSubtasks` nests subtasks with the same fields.
* **`get_task`**: Shows the details of a specific task.
* **`next_task`**: Shows the next task to work on. With `claim: true` it also starts the task and records who claimed it, in one locked write, so parallel sessions never get the same task.
* **`set_task_status`**: Sets the status of a task or subtask.
* **`archive_tasks`**: Moves done and cancelled tasks older than N days (`olderThanDays`, default 30) into `.taskgraph/tasks/archive.json`; `dryRun` lists them first, and `restore` brings one back by ID. In the `all` tier.

### 3. Task Analysis and Expansion

* **`parse_prd`**: Parses a PRD to generate tasks. With `clarify: true` it returns up to 5 questions about gaps in the PRD, each with a `suggestedAnswer`, and generates nothing; ask the user, then call it again with their answers in `clarifications: [{question, answer}]`. The answers are saved in the PRD under `## Clarifications` before the tasks are generated.
* **`expand_task`**: Expands a task into subtasks.
* **`expand_all`**: Expands all eligible tasks.

Tasks from `parse_prd` and subtasks from `expand_task`/`expand_all` come with unchecked acceptance criteria. `set_task_status` won't mark one done until its criteria are checked off (its `check` parameter), unless `force` is set.

* **`analyze_project_complexity`**: Analyzes task complexity.
* **`complexity_report`**: Displays the complexity analysis report.

### 4. Dependency Management

* **`add_dependency`**: Adds a dependency to a task. With `type: "related"` or `"discovered-from"` it adds a link that never blocks.
* **`remove_dependency`**: Removes a dependency, or a related / discovered-from link, from a task.
* **`validate_dependencies`**: Validates the dependencies of all tasks.
* **`fix_dependencies`**: Fixes any invalid dependencies.
* **`dependency_analysis`**: Shows the bottlenecks, critical path and cycles, and with `id` what blocks one task.

### 5. Project and Configuration

* **`initialize_project`**: Initializes a new project.
* **`generate`**: Generates individual task files.
* **`models`**: Manages AI model configurations.
* **`research`**: Performs AI-powered research.

### 6. Tag Management

* **`add_tag`**: Creates a new tag.
* **`delete_tag`**: Deletes a tag.
* **`list_tags`**: Lists all tags.
* **`use_tag`**: Switches to a different tag.
* **`rename_tag`**: Renames a tag.
* **`copy_tag`**: Copies a tag.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.