> ## 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.

# Advanced Configuration

> Advanced TaskGraph settings: which MCP tools load, timeouts, tagged task lists for branches and features, and the state file.

This page covers MCP tool loading, timeouts, tagged task lists and the state file. For models and environment variables, see the [Configuration reference](https://taskgraph-ai.com/configuration.md).

## MCP tool loading

The `TASKGRAPH_TOOLS` environment variable controls which tools the TaskGraph MCP server loads, so you can trade features for context.

* **`core`** (default, alias `lean`): 7 essential tools. `get_tasks`, `next_task`, `get_task`, `set_task_status`, `add_note`, `parse_prd`, `expand_task`.
* **`standard`**: 16 tools. Core plus `update_subtask`, project initialization, complexity analysis, `dependency_analysis`, `expand_all`, subtask and task add/remove.
* **`all`**: every tool, including dependencies, tags, `research` and scope up/down.
* **Custom list**: comma-separated tool names, for example `"get_tasks,next_task,set_task_status"`.

Set it in the `env` block of `.mcp.json` (recommended):

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

Or when registering the server with Claude Code:

```bash theme={null}
claude mcp add taskgraph-ai --scope user \
  --env TASKGRAPH_TOOLS="core" \
  -- npx -y taskgraph-ai
```

Behavior:

* When `TASKGRAPH_TOOLS` is unset or empty, `core` is used.
* Invalid tool names in a custom list are ignored (a warning is emitted for each).
* If every name in a custom list is invalid, the server falls back to `all`.
* Values are case-insensitive.

## MCP timeouts

Long-running AI operations such as `parse_prd`, `expand_task`, `research` and `analyze_project_complexity` can take 2 to 5 minutes, which exceeds the default 60-second MCP timeout. Add a `timeout` (in seconds, 1 to 3600) to the server entry in `.mcp.json`:

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

If you still see `MCP request timed out after 60000ms`, check that `timeout` is present, restart Claude Code, and try `600` for very large operations.

## Tagged task lists

Tags keep separate task lists for branches, features or experiments.

```json theme={null}
"global": {
  "defaultTag": "master"
}
```

* **`defaultTag`**: the tag used when none is specified (default `master`).
* **Branch-based tags:** `taskgraph tags add <name> --from-branch` creates a tag named after the current git branch. Tags are never switched automatically; you decide when to create and use them.

## State file

`.taskgraph/state.json` tracks runtime information for the tag system:

```json theme={null}
{
  "currentTag": "master",
  "lastSwitched": "2025-06-11T20:26:12.598Z",
  "migrationNoticeShown": true
}
```

* **`currentTag`**: the active tag
* **`lastSwitched`**: when the tag last changed
* **`migrationNoticeShown`**: whether the one-time tag-system notice was displayed

TaskGraph manages this file; do not edit it by hand. It's per-machine, so `taskgraph init` adds it to `.gitignore`: two people on different tags don't conflict.


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