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
Cloud	ADHDev Cloud REST API with an adk_* API key	list_daemons, list_sessions, launch_session, stop_session, send_chat, read_chat, approve, check_pending, git_status, git_diff, git_log, git_checkpoint, git_push (13 tools)
Local standalone	http://localhost:3847 standalone API	All of the above + screenshot (14 tools)
Mesh	Local or Cloud + --repo-mesh <id>	mesh_status, mesh_list_nodes, mesh_send_task, mesh_read_chat, mesh_launch_session, mesh_git_status, mesh_checkpoint, mesh_approve (8 tools)

Cloud mode is API-key based and talks to https://api.adhf.dev by default. It does not open the dashboard P2P data channel, and it should not be treated as a dashboard command fallback.

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

# Cloud mode: requires an ADHDev API key
adhdev mcp --api-key adk_xxx
adhdev mcp --api-key adk_xxx --base-url https://api.adhf.dev

You can also run the OSS package directly:

npx @adhdev/mcp-server
npx @adhdev/mcp-server --api-key adk_xxx
npx @adhdev/mcp-server --repo-mesh mesh_abc123

Environment variables are supported:

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

Cloud Mode Requirements

To use Cloud mode, the target daemon must explicitly allow server API relays. By default, this is disabled for security.

Enable it on the machine running the daemon:

adhdev daemon:api enable

If this is not enabled, MCP tool calls in cloud mode will return a SERVER_API_DISABLED error.

Claude Desktop config

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

For cloud mode, pass the API key as an argument or environment variable:

{
  "mcpServers": {
    "adhdev-cloud": {
      "command": "adhdev",
      "args": ["mcp", "--api-key", "adk_xxx"]
    }
  }
}

For mesh mode (coordinator-scoped tools):

{
  "mcpServers": {
    "adhdev-mesh": {
      "command": "adhdev",
      "args": ["mcp", "--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-mcp
    args:
      - --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.

Prefer using your MCP client's secret/env support instead of committing API keys to a shared config file.

Tool notes

• list_daemons discovers connected machines (cloud mode only, local mode simulates this).
• 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 is local-only because the standalone API exposes it directly (cloud requires P2P DataChannel, which the MCP server does not implement).

Mesh tools

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

• mesh_status — shows all nodes' health, git state, and active sessions.
• mesh_list_nodes — lists nodes with workspace paths and capabilities.
• mesh_send_task — sends a natural-language task to a delegated agent session.
• mesh_read_chat — reads chat history from a delegated agent.
• mesh_launch_session — launches a new agent session on a mesh node.
• mesh_git_status — gets git status for a node workspace.
• mesh_checkpoint — creates a git checkpoint on a node workspace.
• mesh_approve — approves/rejects a pending action on a delegated agent.

Related references

• CLI Commands
• API Keys
• REST API