Claude Code Integration

Applies to: Dispatch v1.0.0, last verified 2026-04-05

This page explains how to connect Claude Code to Dispatch and what tools become available once connected.

Auto-injection

When you add a project to Dispatch, it automatically writes a .mcp.json file into the project root. Claude Code reads this file on startup and connects to Dispatch without any manual configuration.

The injected file looks like this (the URL uses the port Dispatch is running on):

{
  "mcpServers": {
    "dispatch": {
      "type": "http",
      "url": "http://localhost:<port>/mcp"
    }
  }
}

Injection is idempotent: if .mcp.json already contains a dispatch entry (pointing anywhere), Dispatch leaves it untouched. Existing keys in the file are preserved; only the dispatch key under mcpServers is added.

Opting out of auto-injection

Delete .mcp.json from the project root. Dispatch will not re-create it once removed unless you re-add the project.

To disable auto-injection globally, open Settings > Providers and turn off Auto-inject MCP config.

Manual installation

If you manage .mcp.json yourself, add the dispatch entry:

{
  "mcpServers": {
    "dispatch": {
      "type": "http",
      "url": "http://localhost:<port>/mcp"
    }
  }
}

Replace <port> with the port Dispatch is actually running on (check the URL printed in the terminal when the server starts, or ~/.dispatch/config.json).

Available tools

In Claude Code, Dispatch tools appear as mcp__dispatch__<name>:

Tool	What it does
mcp__dispatch__dispatch_get_state	Summary of all epics, agents, and sessions
mcp__dispatch__dispatch_list_agents	All agents with tool, liveness, persona
mcp__dispatch__dispatch_get_epic	Full epic detail: phases, statuses, plan body
mcp__dispatch__dispatch_update_phase_status	Advance or block a phase
mcp__dispatch__dispatch_emit_activity_event	Push a typed event to the activity feed
mcp__dispatch__dispatch_get_session_context	Transcript path + metadata for a session

dispatch_update_phase_status accepts an optional note string. When provided, Dispatch appends it to the epic’s execution-log.md automatically.

HTTP hooks (real-time telemetry)

Claude Code can push hook events to Dispatch over HTTP, giving near-zero-latency updates to the session list and activity feed. Dispatch auto-generates the correct hook configuration for your server address. You can copy it from Settings > Providers > Claude Code > Hook Config and paste it into your Claude Code settings (global or project-level).

Without hooks, Dispatch falls back to JSONL polling. With hooks, OrgGraph updates and session status changes appear immediately.

TaskCompleted hook events trigger automatic epic phase matching: Dispatch looks for a phase whose title contains the completed task title and marks it DONE.