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

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_plan_onboarding — read-only dry-run: proposes what creating/joining a mesh would do, writes nothing.
• mesh_create — creates a new mesh, optionally registering the current workspace as its first node.
• 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.

Source of truth for names and count

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

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.
• mesh_prune_stale_direct — prunes stale direct-dispatch records.

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).
• 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_requeue_held_events — restores recoverable held coordinator events back to the pending queue.
• mesh_record_note / mesh_forget_note — record or retract a durable operating note that future coordinators inherit.

Bootstrap & config (mesh mode; distinct from the standard-mode bootstrap trio 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.
• mesh_reinit — same as mesh_init but for an already-initialized repo, with overwrite defaulting to true and a current-vs-suggested diff.
• mesh_write_mesh_json_config — writes the repo-committed .adhdev/mesh.json from the machine-local mesh entry.
• mesh_refine_config — unified read-only Refinery config helper; the mode parameter (schema / validate / suggest) selects the operation. Replaces the former standalone mesh_refine_config_schema / mesh_validate_refine_config / mesh_suggest_refine_config tools — see the deprecated aliases note below.
• mesh_change_impact_config — the same unified pattern for change-impact config (mode: schema / validate / suggest). Replaces the former standalone mesh_change_impact_config_schema / mesh_validate_change_impact_config / mesh_suggest_change_impact_config tools.

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_set / mesh_magi_kind_panel_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_set — proposes (dry-run) or applies a node's slot list, binding provider/model/thinking-level to difficulty classes.
• mesh_node_slots_list — lists a node's current slots.

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) were consolidated into mesh_refine_config and mesh_change_impact_config respectively, selected via the mode parameter. The six old names are no longer listed by tools/list — they will not appear in a client's tool picker — but the server still dispatches them for one release as a compatibility shim, forwarding to the unified handler with the matching mode. New callers should use mesh_refine_config / mesh_change_impact_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