@adhdev/mcp-server

An MCP stdio server that exposes running ADHDev agent sessions as tools.

ADHDev supervises AI coding agents — CLI agents (Claude Code, Codex CLI, and others) and IDE copilots — on your machines. This package lets an MCP client drive that supervision: list live sessions, read what an agent is doing, answer an approval prompt it is blocked on, and inspect the workspace it is working in.

It talks to an ADHDev daemon already running on your machine. It is a client of that daemon, not a standalone service — start the daemon first.

Install

The server is wrapped by the main CLI:

adhdev mcp

Direct package entrypoint (compatibility bin, same server):

npx @adhdev/mcp-server

Or install the package globally; the binary is adhdev-mcp:

npm install -g @adhdev/mcp-server

It speaks MCP over stdio, so it is normally launched by an MCP client rather than run by hand.

Connecting a client

Point your MCP client at the wrapper or the binary. For example:

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

Register it with Codex:

codex mcp add adhdev -- adhdev mcp

Run adhdev mcp --help (or adhdev-mcp --help) for the full flag list.

Transports

The --mode flag selects which daemon to talk to. It is a transport choice, independent of which toolset is published.

The IPC port is derived from the daemon's release track, so a preview coordinator does not have to be told which port its own daemon is on.

Defaults to local. Override the port with --port, and supply a standalone password with --password or ADHDEV_PASSWORD. ADHDEV_MCP_TRANSPORT sets the mode from the environment.

If the daemon is unreachable, the server exits at startup with a message naming which daemon it expected — it does not come up with a dead transport.

Toolsets

Which tools are published depends on how the server is started. The three sets are disjoint by design, not merely by convention.

Standard (default) — 19 tools

Direct supervision of agent sessions on one machine.

• Inspect — list_daemons, list_sessions, check_pending, read_chat, read_chat_debug, spec_debug, screenshot (local mode only)
• Control — launch_session, stop_session, send_chat, approve
• Git — git_status, git_log, git_diff, git_checkpoint, git_push
• Mesh bootstrap — mesh_create (its mode: "plan" is the read-only onboarding planner) and mesh_add_node. Exposed here precisely because this is the no-mesh-yet context: mesh mode refuses to start without an existing mesh id.

Repo Mesh (--repo-mesh <id>) — 40 tools

The coordinator surface for Repo Mesh, where work is delegated across multiple machines and agents. Also exposes the coordinator system prompt as an MCP resource at coordinator://system-prompt.

Broadly: mesh and node status (mesh_status, mesh_list_nodes, mesh_route_preview), task dispatch and queue management (mesh_enqueue_task, mesh_enqueue_batch, mesh_send_task, mesh_view_queue, mesh_queue_cancel), reading delegated sessions (mesh_read_chat, mesh_read_terminal, mesh_read_node_logs), approvals (mesh_approve, mesh_answer_question), node lifecycle (mesh_clone_node, mesh_remove_node), git convergence via the Refinery (mesh_refine_node, mesh_fast_forward_node), missions, and the durable task ledger.

Tools that act on the same object are one tool selected by an argument — mesh_node_slots (action: list / propose / set), mesh_note (action: record / forget), mesh_config (kind: refine / change_impact / mesh_json), mesh_init (mode: init / reinit), mesh_create (mode: create / plan) and mesh_cleanup_sessions (mode, including prune_stale_direct). Each action accepts only its own arguments. The names these replaced on 2026-09-26 (mesh_record_note, mesh_plan_onboarding, …) answer with an error naming the replacement tool and argument. The graph orchestration tools (mesh_graph_view, mesh_graph_gate, mesh_graph_node_patch) were removed on 2026-09-30; chain tasks with depends_on instead. mesh_refine_plan was removed on 2026-10-08 (call mesh_refine_node without execute; its default dry-run is the same plan), mesh_coordinator_prompt_append was removed the same day with the per-machine coordinator-prompts/ files (put a standing instruction in the repo's .adhdev/mesh.json coordinator.systemPromptAppend instead), and mesh_ledger_query is a deprecated alias of mesh_task_history — which now takes its kind / since / node filters — for one release.

The mesh id also comes from ADHDEV_MESH_ID.

When ADHDEV_WORKER_MCP is enabled on the target daemon (the default), the coordinator also gets a 41st tool, mesh_notify_worker, to drop an urgent memo into a busy delegated worker's mailbox — delivered on the worker's next MCP tool response rather than interrupting its turn.

Worker (--worker) — 6 tools

The minimal surface for a delegated agent: report_completion, progress_update, peer_context_pull, plus read-only git_status / git_log / git_diff.

Worker mode publishes no mesh tools and no coordinator prompt resource. A worker therefore cannot delegate work of its own — that restriction is a tool that does not exist rather than an instruction it might not follow. --worker deliberately overrides --repo-mesh, so a repo whose committed config carries a mesh id cannot hand a worker the coordinator surface.

Worker mode requires a daemon-issued credential (ADHDEV_WORKER_SESSION_BIND or ADHDEV_WORKER_TASK_TOKEN) in its environment and exits at startup without one.

Tool annotations

Every published tool carries the four MCP behavior hints — readOnlyHint, destructiveHint, idempotentHint, openWorldHint — so a client can decide what to auto-run and what to confirm first.

They describe what a tool can do, not what it does by default. Several tools (mesh_refine_node, mesh_fast_forward_node, mesh_cleanup_sessions with mode: "prune_stale_direct") return a plan unless explicitly told to execute, and are still annotated destructive: a hint that described only the safe default would be the kind of hint that gets someone hurt.

The hints are advisory. Actual enforcement stays in the daemon — dry-run defaults, explicit execute flags, and ownership checks.

Security notes

• The server runs locally and connects to a local daemon. It opens no listening socket of its own; MCP traffic is stdio.
• Standalone (local) connections authenticate with the daemon password when one is configured.
• Tools reach only what the daemon already exposes — the sessions, workspaces, and mesh nodes it manages.

Client Configuration

Claude-style clients auto-import a repo-local .mcp.json. See Self-hosted configuration for the exact snippets.

Development

npm run build -w packages/mcp-server
npm test -w packages/mcp-server

License

AGPL-3.0-or-later. See LICENSE.