Skip to main content
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:
The two environment variables control where the server looks for itself and for project 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:
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.

​
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.
1

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

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
3

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.