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"]
    }
  }
}

Hermes Agent mesh config

Hermes Agent does not auto-import repo-local .mcp.json. To use Repo Mesh tools from Hermes, add the mesh server to the Hermes YAML config under mcp_servers, then start a fresh Hermes session.

Find the Hermes config file:

hermes config path

Add a mesh server entry:

mcp_servers:
  adhdev-mesh:
    command: adhdev
    args:
      - mcp
      - --mode
      - ipc
      - --repo-mesh
      - mesh_abc123
    enabled: true

After saving the config, exit and relaunch Hermes. MCP tools are discovered when the Hermes session starts, so an already-running session may not see the new mesh server.

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. The verbose form includes graph-usage counters (graphs created, typical graph size, expired/auto-abandoned gates, tasks chained via depends_on).
• mesh_list_nodes — lists nodes with workspace paths and capabilities.
• 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 — compact history of tasks across the mesh.
• mesh_ledger_query — read-only ledger query along the kind/time/node axes (complements mesh_task_history's task-axis view).
• 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 graph 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, so inputs_from is only needed when a downstream task must bind a specific field precisely.
• mesh_enqueue_batch — atomically submits a multi-step plan (several tasks plus their dependencies, optional coordinator gates, and deferred worktree creation) in one call, with the whole batch rolled back if any item is invalid. Reserved for plans with three or more steps already confirmed up front — not the default way to chain tasks (see mesh_enqueue_task above). Conditional branching fields (run_if / on_false / on_upstream_skip) are no longer accepted on this or the graph tools below; camelCase aliases for existing fields are likewise no longer documented on the schema, though already-written calls using them keep working.
• 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.

Graph orchestration (dependencies & coordinator gates)

• mesh_graph_view — current task DAG state, pending gates, workspace sagas, and the next action the coordinator needs to take.
• mesh_graph_gate — drives a coordinator gate, selected by action: claim takes the lease; release passes the gate once you've verified the external condition it's waiting on (permanent — a timeout is never treated as an approval); abandon permanently gives the gate up (also happens automatically when every task behind a gate has reached a terminal state: completed/failed/cancelled); extend pushes the gate's deadline out without taking a lease. Gates default to a 24-hour deadline if none is set, putting the plan on hold (rather than auto-approving) on expiry and notifying the coordinator once; the release/abandon/extend verbs can also be called directly from the dashboard.
• mesh_graph_node_patch — patches a blocked graph node (e.g. a bad inputs_from reference) so it can retry.

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).
• mesh_refine_plan — preview the convergence plan without executing.

MAGI (multi-agent cross-verification)

• mesh_magi_review — cross-verifies a read-only investigation across a standing panel of independent mesh agents instead of sending a single worker.
• mesh_magi_collect — collects and synthesizes a previously dispatched MAGI fan-out by its consensus group id (the async companion to mesh_magi_review({ wait:false })).
• mesh_magi_kind_panel — action: "set" / "list": bind or list the MAGI panel slots configured per task kind for this mesh.

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.

Coordinator prompt

• mesh_coordinator_prompt_append — action: "get" reads the current user-level coordinator prompt append text for a CLI type (the per-machine ~/.adhdev/coordinator-prompts/<cli>.append.md file on this MCP server's daemon); action: "set" writes (or clears) it. This is append-only by design: it always stacks after whichever base prompt wins and can never replace the daemon's base coordinator prompt — there is no MCP tool to read or write the override (base-replacing) file, which stays a dashboard-only, human-gated action.

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_graph_gate_claim	mesh_graph_gate + action: "claim"
mesh_graph_gate_release	mesh_graph_gate + action: "release"
mesh_graph_gate_abandon	mesh_graph_gate + action: "abandon"
mesh_graph_gate_claim + extend_seconds	mesh_graph_gate + action: "extend"
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_magi_kind_panel_list	mesh_magi_kind_panel + action: "list"
mesh_magi_kind_panel_set	mesh_magi_kind_panel + action: "set"
mesh_coordinator_prompt_append_get	mesh_coordinator_prompt_append + action: "get"
mesh_coordinator_prompt_append_set	mesh_coordinator_prompt_append + 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"

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.

Related references

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