MCP Server

ADHDev ships an MCP stdio server so external MCP clients can use ADHDev sessions as tools. The server is published as @adhdev/mcp-server and is also wrapped by the main cloud CLI as adhdev mcp.

Use it when you want an MCP client such as Claude Desktop to list active ADHDev sessions, read chat history, send a message, or approve a waiting prompt. In mesh mode it becomes the full Repo Mesh coordinator tool surface — see Agent-Driven Repo Mesh Setup for the end-to-end registration flow.

Modes

Mode	Transport used by the MCP server	Tools
Local standalone	http://localhost:3847 standalone API	15 base tools + screenshot + 3 mesh-bootstrap tools (19 total)
IPC	Cloud daemon local IPC at localhost:19222	Same 15 base tools + 3 mesh-bootstrap tools, no screenshot (18 total)
Mesh	Local or IPC + --repo-mesh <id>	Coordinator-scoped set — see Mesh tools below
Worker	Local or IPC + --worker	Minimal delegated-worker toolset: report_completion, progress_update, peer_context_pull, git_status, git_log, git_diff (6 tools)

Local mode is part of the OSS/self-hosted surface. For standalone setup and auth details, use the OSS docs:

• Self-hosted Setup
• Self-hosted Local API

Start the server

# Local mode: requires a running standalone daemon
adhdev mcp
adhdev mcp --port 4000
adhdev mcp --password my-standalone-password

You can also run the OSS package directly:

npx @adhdev/mcp-server
npx @adhdev/mcp-server --mode ipc --repo-mesh mesh_abc123

Environment variables are supported:

ADHDEV_PASSWORD=my-standalone-password adhdev mcp
ADHDEV_MESH_ID=mesh_abc123 adhdev mcp

Claude Desktop config

{
  "mcpServers": {
    "adhdev": {
      "command": "adhdev",
      "args": ["mcp"]
    }
  }
}

For mesh mode (coordinator-scoped tools):

{
  "mcpServers": {
    "adhdev-mesh": {
      "command": "adhdev",
      "args": ["mcp", "--mode", "ipc", "--repo-mesh", "mesh_abc123"]
    }
  }
}

Standard mode tools

Standard mode (no --repo-mesh) exposes the direct session-control surface plus three mesh-bootstrap tools that let an MCP-only agent create a mesh before mesh mode has anything to connect to.

Session & daemon

• list_daemons — reports the connected daemon's identity.
• list_sessions — discovers available sessions on a daemon.
• launch_session / stop_session — manage CLI/IDE agent lifecycles.
• check_pending — lists sessions waiting for approval.

Chat & approval

• read_chat — reads recent chat for a selected session.
• read_chat_debug — bounded debug bundle for a selected session's chat state.
• spec_debug — debug helper for provider spec parsing.
• send_chat — sends a message to a selected session.
• approve — approves or rejects an approval prompt.

Git

• git_status, git_diff, git_log, git_checkpoint, git_push — manage workspace git operations.

Local-only

• screenshot — captures the current IDE window via the daemon. Requires P2P/local daemon access, so it is available in local mode only, not IPC.

Mesh bootstrap (available in both local and IPC standard mode — this is the no-mesh-yet path)

• mesh_create — creates a new mesh, optionally registering the current workspace as its first node. With mode: "plan" it is instead a read-only dry-run that proposes what creating/joining a mesh would do and writes nothing — run that first.
• mesh_add_node — registers an existing workspace as a node of an existing mesh.

Once a mesh exists, re-register the MCP server with --repo-mesh <mesh_id> to switch to mesh mode and unlock the full coordinator toolset below — mesh mode replaces the tool surface entirely rather than adding to it.

Mesh tools

Mesh tools are only available in mesh mode (--repo-mesh). They replace the standard tools with a coordinator-scoped set.

Authoritative names and count live in the code

This page groups tools by family for orientation. The authoritative list — exact names, current count, and full input schemas — is ALL_MESH_TOOLS in oss/packages/mcp-server/src/tools/mesh-tool-schemas.ts. If a tool name below and the code ever disagree, the code wins — this list has drifted stale before.

Status & inspection

• mesh_status — aggregate snapshot: all nodes' health, git state, active sessions, recovery hints, and per-daemon build/staleness info.
• mesh_list_nodes — lightweight roster from the mesh config: every node with workspace paths, machine identity, node policy and capabilities (no live git or sessions — that is mesh_status).
• mesh_read_chat — reads chat history from a delegated agent.
• mesh_read_debug — bounded debug bundle for a delegated session.
• mesh_read_terminal — reads the current raw PTY viewport of a delegated session (what a human would see on screen right now).
• mesh_git_status — gets git status for a node workspace.
• mesh_read_node_logs — greps a node's daemon log file (full-file, not just the tail).
• mesh_task_history — the mesh ledger: tasks, completions, failures, checkpoints, node and mission lifecycle; filter by kind (one or a comma list), since and node, newest tail entries.
• mesh_ledger_query — deprecated alias of mesh_task_history (see deprecated aliases).
• mesh_review_inbox — pending review/approval items awaiting the coordinator.
• mesh_list_pending_approvals — mesh-wide list of every session currently awaiting an approval decision.
• mesh_route_preview — read-only, fetch-free preview of where a hypothetical task would route and why, from the current in-memory mesh/queue/quota-facts snapshot (capacity-first order, difficulty floor, fitness components, quota bonus, gate outcome). Does not enqueue, write, probe CLIs, or refresh quota.

Dispatch, sessions & control

• mesh_send_task — sends a natural-language task directly to a delegated agent session.
• mesh_launch_session — launches a new agent session on a mesh node.
• mesh_send_keys — injects a structured key sequence into a delegated worker session.
• mesh_restart_daemon — restarts a mesh node's daemon.
• mesh_approve — approves/rejects a pending action on a delegated agent.
• mesh_answer_question — answers a multi-choice question (AskUserQuestion) a delegated session is waiting on.
• mesh_checkpoint — creates a git checkpoint on a node workspace.
• mesh_cleanup_sessions — stops/cleans up stale or orphaned delegated sessions on a node; mode: "prune_stale_direct" instead prunes stale direct-dispatch records mesh-wide (dry-run unless execute: true).

Work queue & missions

• mesh_enqueue_task — enqueues a task that an idle node claims autonomously (supports target_node_id / prefer_worktree routing, task_mode, mission_id, depends_on, and an optional owned_paths declaration so an overlapping code_change task elsewhere in the mesh is refused at claim time instead of racing it). Chaining a new task onto an existing one with depends_on is the default way to build up a multi-step plan — the plan grows one link at a time as work is discovered. A task with depends_on automatically receives an "Upstream results" appendix summarizing what its predecessor(s) reported on completion.
• mesh_enqueue_batch — atomically enqueues several tasks (with their depends_on links) in one call, rolling the whole batch back if any item is invalid. A convenience for plans whose steps are already confirmed — not the default way to chain tasks (see mesh_enqueue_task above).
• mesh_view_queue — current active-work source of truth (pending/assigned/terminal).
• mesh_queue_cancel / mesh_queue_requeue — cancel or requeue a queued task.
• mesh_mission_upsert — create/update a mission (goal grouping + lifecycle status).
• mesh_mission_list — lists missions with goal, status, and live task progress.
• mesh_reconcile_ledger — reconcile the local ledger against a peer's bounded slice.
• mesh_note — action: "record" / "forget": record or retract a durable operating note that future coordinators inherit.

Bootstrap & config (mesh mode; distinct from the standard-mode bootstrap pair above)

• mesh_init — one-click onboarding for an existing git project: detects installed CLI providers and proposes the three repo .adhdev/* config families (Refinery, worktree bootstrap, change-impact). Preview by default; write: true to apply. mode: "reinit" is the same operation for an already-initialized repo, with overwrite defaulting to true and a current-vs-suggested diff.
• mesh_config — repo-config helper selected by kind. kind: "refine" and kind: "change_impact" are read-only helpers whose mode (schema / validate / suggest) selects the operation; kind: "mesh_json" writes the repo-committed .adhdev/mesh.json from the machine-local mesh entry (dry-run unless write: true). See retired tool names below.

Nodes

• mesh_clone_node — clones a node into an isolated git worktree node.
• mesh_remove_node — removes a (worktree) node, optionally cleaning sessions.
• mesh_cleanup_worktree_nodes — plans (dry-run by default) or executes safe removal of converged local worktree nodes once their branch is proven merged/pushed and every safety exclusion passes.
• mesh_fast_forward_node — safely dry-runs by default, or explicitly executes, an obvious clean fast-forward without launching an agent session; uses fetch/recheck, merge --ff-only, optional submodule update, and post-status verification only.

Refinery (worktree → base convergence)

• mesh_refine_node / mesh_refine_batch — converge one or many worktree branches back to base (validate → merge → push → cleanup). Both preview the plan by default and execute nothing until execute: true.

Node slots (provider/model/thinking-level routing)

• mesh_node_slots — a node's slot list (provider/model/thinking-level bound to difficulty classes), selected by action: list shows the current slots; set proposes (dry-run) or applies a slot list; propose is a read-only auto-detect that probes the node's installed CLI agents and drafts a capability-slot profile (the "just allow it and it figures out the slots" path). propose never writes; apply its draft with mesh_node_slots({ action: "set", node_id, slots: proposedSlots, write: true }) after review, since slot writes are wholesale replacements that can drop hand-tuned slots.

Worker mode

adhdev mcp --mode ipc --worker starts the minimal delegated-worker toolset used by a Repo Mesh worker session (a mesh coordinator dispatches tasks to other agent sessions, which act as workers). This mode is normally launched by the daemon itself when it starts a worker session, not something you run by hand — the worker process needs a session bind (ADHDEV_WORKER_SESSION_BIND) or a task token (ADHDEV_WORKER_TASK_TOKEN) that the daemon supplies. --worker overrides --repo-mesh: a worker session never gets the coordinator toolset.

Worker tools: report_completion, progress_update, peer_context_pull, git_status, git_log, git_diff.

Retired tool names

On 2026-09-26 the mesh tool surface was consolidated from 60 to 48 tools by merging tools that acted on the same object into one tool selected by an action / kind / mode argument. Every capability is still reachable. The old names are no longer listed by tools/list and are not forwarded: calling one returns an error that names the replacement tool and the argument to add, so an agent running an old prompt recovers on its next call.

Old name	Call instead
mesh_node_slots_list	mesh_node_slots + action: "list"
mesh_node_slots_propose	mesh_node_slots + action: "propose"
mesh_node_slots_set	mesh_node_slots + action: "set"
mesh_record_note	mesh_note + action: "record"
mesh_forget_note	mesh_note + action: "forget"
mesh_reinit	mesh_init + mode: "reinit"
mesh_refine_config	mesh_config + kind: "refine"
mesh_change_impact_config	mesh_config + kind: "change_impact"
mesh_write_mesh_json_config	mesh_config + kind: "mesh_json"
mesh_plan_onboarding	mesh_create + mode: "plan"
mesh_prune_stale_direct	mesh_cleanup_sessions + mode: "prune_stale_direct"

The graph orchestration tools (mesh_graph_view, mesh_graph_gate, mesh_graph_node_patch) were removed on 2026-09-30 without a replacement; chain tasks with depends_on instead.

The MAGI tools (mesh_magi_review, mesh_magi_collect, mesh_magi_kind_panel) were removed on 2026-09-30. Calling one returns an error with the replacement: send the same read-only question to 2–3 workers on different providers with mesh_send_task, wait for their report_completion, and synthesize the answers yourself.

mesh_refine_plan was removed on 2026-10-08: it was an alias of mesh_refine_node's default dry-run. Calling it returns an error pointing to mesh_refine_node, which returns the same plan without executing anything.

mesh_coordinator_prompt_append (and its retired _get / _set names) was removed on 2026-10-08 together with the per-machine ~/.adhdev/coordinator-prompts/ files, which the daemon no longer reads. Calling it returns an error that points to the replacement: put a standing instruction for a project's coordinator in the repo's .adhdev/mesh.json coordinator.systemPromptAppend (mesh_config with kind: "mesh_json"), or record a lesson with mesh_note.

Deprecated aliases

mesh_refine_config_schema, mesh_suggest_refine_config, mesh_validate_refine_config, and their change-impact counterparts (mesh_change_impact_config_schema, mesh_suggest_change_impact_config, mesh_validate_change_impact_config) predate that consolidation. They are not listed by tools/list, but the server still dispatches them as a compatibility shim, forwarding to mesh_config with the matching kind and mode. New callers should use mesh_config directly.

mesh_ledger_query is a deprecated alias of mesh_task_history, which took over its kind / since / node filters on 2026-10-08. It is still listed and still works (full payloads, tail default 50) for one release, then it will be removed. New callers should use mesh_task_history; pass verbose: true for full payloads.

Related references

• Agent-Driven Repo Mesh Setup — end-to-end registration flow (standard mode bootstrap → mesh mode)
• CLI Commands
• API Keys
• REST API