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.

Modes

Mode	Transport used by the MCP server	Tools
Local standalone	http://localhost:3847 standalone API	list_daemons, list_sessions, launch_session, stop_session, send_chat, read_chat, read_chat_debug, approve, check_pending, git_status, git_diff, git_log, git_checkpoint, git_push, screenshot, spec_debug (16 tools)
IPC	Cloud daemon local IPC at localhost:19222	Same command-routed tool surface as local mode
Mesh	Local or IPC + --repo-mesh <id>	Coordinator-scoped set (28 tools). Status/inspection: mesh_status, mesh_list_nodes, mesh_read_chat, mesh_read_debug, mesh_git_status, mesh_task_history, mesh_review_inbox. Dispatch/sessions: mesh_send_task, mesh_launch_session, mesh_approve, mesh_checkpoint, mesh_cleanup_sessions, mesh_prune_stale_direct. Queue/missions: mesh_enqueue_task, mesh_view_queue, mesh_queue_cancel, mesh_queue_requeue, mesh_mission_upsert, mesh_reconcile_ledger. Nodes: mesh_clone_node, mesh_remove_node, mesh_fast_forward_node. Refinery: mesh_refine_node, mesh_refine_batch, mesh_refine_plan, mesh_refine_config_schema, mesh_suggest_refine_config, mesh_validate_refine_config

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.

Tool notes

• list_daemons reports the connected daemon's identity.
• list_sessions discovers available sessions on a daemon.
• launch_session and stop_session manage CLI/IDE agent lifecycles.
• read_chat reads recent chat for a selected session.
• send_chat sends a message to a selected session.
• approve approves or rejects an approval prompt.
• check_pending lists sessions waiting for approval.
• git_status, git_diff, git_log, git_checkpoint, git_push manage workspace git operations.
• screenshot captures the current IDE window via the daemon.

Mesh tools

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

Status & inspection

• mesh_status — aggregate snapshot: all nodes' health, git state, and active sessions (coordinator-owned).
• 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_git_status — gets git status for a node workspace.
• mesh_task_history — compact history of tasks across the mesh.
• mesh_review_inbox — pending review/approval items awaiting the coordinator.

Dispatch & sessions

• 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_approve — approves/rejects a pending action on a delegated agent.
• 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_reconcile_ledger — reconcile the local ledger against a peer's bounded slice.

Nodes

• mesh_clone_node — clones a node into an isolated git worktree node.
• mesh_remove_node — removes a (worktree) node, optionally cleaning sessions.
• 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.
• mesh_refine_config_schema / mesh_suggest_refine_config / mesh_validate_refine_config — inspect, scaffold, and validate the project's refine config.

Related references

• CLI Commands
• API Keys
• REST API