> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dotbot.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# How dotbot configures the MCP server

> dotbot generates .mcp.json automatically at runtime inside each task execution worktree. No manual AI-tool configuration is required.

The dotbot MCP server runs as a child process of the AI agent, communicating over stdio. In v4.0.0, dotbot generates `.mcp.json` automatically inside each task execution worktree at runtime. You do not need to manually point your AI tool at a `dotbot-mcp.ps1` script.

## How configuration is generated

When dotbot prepares a task execution worktree, it writes `.mcp.json` at the worktree root. The agent adapter then passes `--mcp-config .mcp.json` to the Claude CLI when starting the session. The generated file has the following structure:

```json theme={null}
{
  "mcpServers": {
    "dotbot": {
      "command": "pwsh",
      "args": ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", "<DOTBOT_HOME>/src/mcp/dotbot-mcp.ps1"],
      "env": {
        "DOTBOT_HOME": "<path-to-dotbot-install>",
        "DOTBOT_PROJECT_ROOT": "<path-to-execution-worktree>"
      }
    }
  }
}
```

The two environment variables control where the server looks for itself and for project state:

| Variable              | Purpose                                                                                                                                     |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `DOTBOT_HOME`         | Path to the dotbot framework install. The MCP server script at `src/mcp/dotbot-mcp.ps1` is resolved from here.                              |
| `DOTBOT_PROJECT_ROOT` | Path to the task execution worktree. The server treats this directory as the project root when reading and writing `.bot/workspace/` state. |

## Project root resolution

The MCP server calls `Resolve-DotbotProjectRoot` at startup to determine which project it is connected to. Resolution follows this order:

1. If `DOTBOT_PROJECT_ROOT` is set in the environment, use that path directly. This is always the case in runtime-generated configurations.
2. If the env var is absent, run `git rev-parse --git-common-dir` from the script directory. This resolves correctly from inside linked git worktrees, which is where task execution happens.
3. As a final fallback, walk up the directory tree looking for a `.git` folder or gitfile.

If no root can be determined, the server exits immediately:

```
FATAL: Could not auto-detect project root. No .git folder found in parent directories of <path>
```

<Note>
  `DOTBOT_PROJECT_ROOT` takes priority over git detection. In the generated config, it always points at the task execution worktree, not at the main project checkout. This is what lets each task session write state to its own isolated branch.
</Note>

## Workflow-added servers

Installed workflows can declare additional MCP servers in their manifests. dotbot merges those declarations into `.mcp.json` when the workflow is installed. The entries for `dotbot`, `context7`, and `playwright` are treated as core entries and are never removed when workflows are uninstalled.

## Prerequisites

The MCP server requires:

* PowerShell 7 or later (`pwsh`) installed and on your PATH
* The dotbot framework installed and `DOTBOT_HOME` pointing at the install directory
* The dotbot runtime running - start it with `dotbot serve` before launching an agent session

## Verifying the connection

After dotbot starts an agent session, ask the AI to list the available dotbot tools. You should see all 31 built-in tools, plus any tools contributed by installed workflows and stacks.

<Steps>
  <Step title="Ask for the tool list">
    In the agent session, send: "List the available dotbot MCP tools." The response should include tools like `task_create`, `task_get_next`, `decision_list`, and `workflow_start`.
  </Step>

  <Step title="Check for startup errors">
    If the tool list is empty or the server fails to start, check the MCP server stderr output. Common causes are:

    * `pwsh` (PowerShell 7+) is not on the PATH - run `pwsh --version` to confirm
    * `DOTBOT_HOME` does not point at a valid dotbot install - verify `$env:DOTBOT_HOME/src/mcp/dotbot-mcp.ps1` exists
    * The dotbot runtime is not running - start it with `dotbot serve` before launching the agent session
  </Step>

  <Step title="Confirm the project root">
    If tools return path errors, check that `DOTBOT_PROJECT_ROOT` in the generated `.mcp.json` points at a directory that contains a `.bot/workspace/tasks/` folder.
  </Step>
</Steps>