droid-mcp

An MCP server that lets any MCP client (Droid, Claude Code, Cursor, other agents) find, start, steer and read Factory Droid sessions, including mission/workstream orchestrators and their agents. It reads local session files, runs its own sessions through @factory/droid-sdk, and reaches sessions held elsewhere through the Factory REST API when an API key is available.

Status: early (0.1.0). Tested on macOS with droid CLI 1.10.0, @factory/droid-sdk 0.11.0 and Node 26 (engines requires Node >= 24). The only platform-specific code is the Keychain lookup for FACTORY_API_KEY, which runs only on darwin; elsewhere the key must come from the environment. Linux is untested.

How the tools fit together

Discover            Start or steer          Follow and approve                        Read or stop
droid_find    ─┐    droid_start ─┐          droid_wait ── pending prompt? ──► droid_respond
droid_models  ─┴──► droid_send  ─┴─► turn ─► droid_wait ── state "idle" ─────► droid_result
                                     runs in                                   droid_cancel
                                     background

Terms used below:

• Workstream (mission): a multi-agent Factory session: one orchestrator plus child agent sessions, tagged mission-v2.

• Own session: a session currently running inside this server, either started with droid_start or resumed locally by droid_send. It stays own until it is closed.

• Autonomy: what the agent in a session may do without asking: off < low < medium < high.

• Pending prompt: a permission request or AskUser question waiting for droid_respond (listed in attention).

Related MCP server: Open Science MCP

Access at a glance

Three backends, and the credential each needs:

Helpers: git diff HEAD (diffs), rg (transcript search), droid exec --help (model list).

What each tool can do:

"Read-only" means the tool is registered with readOnlyHint: true (src/tools.ts).

Which backend a call uses depends on the target session (src/route.ts, src/tools.ts):

Local resume happens only without a key, only with allowLocalResume: true, and only for a standalone session that has readable settings, is not archived, is not a subagent, was not modified in the last 30 minutes, and has a recorded autonomy within the cap. The resumed session becomes an own session.

What the agent can and cannot touch

Filesystem

• droid_start, local resume and droid_result diffs require a cwd inside DROID_MCP_ROOTS (colon-separated, default ~/repos). Both the cwd and each root go through realpath, so symlinks are resolved before the prefix check, and a missing cwd is refused (src/config.ts).

• DROID_MCP_ROOTS limits where the server starts or diffs work. It is not a read sandbox:

  Operation	Limited to DROID_MCP_ROOTS?
  droid_start cwd, local resume, droid_result diff	Yes
  droid_start fork source (the source's own cwd)	No
  droid_find, droid_wait, droid_result text (any local transcript)	No
  REST sends, droid_respond, droid_cancel (any session the key can reach)	No

• Files read: ~/.factory/sessions/*/*.jsonl and their .settings.json files (src/catalog.ts), ~/.factory/settings.json (src/models.ts), and ~/.droid-mcp/state.json (src/runs.ts).

• The only file the server writes is ~/.droid-mcp/state.json, through a temporary file in the same directory and a rename. The directory is created with mode 0700 and the file with 0600 (src/runs.ts).

• Droid writes its own session files. The agent inside a session starts in its cwd, but autonomy, not the roots list, decides what its commands can touch.

Autonomy

• Levels are off, low, medium, high. A start without autonomy uses off (src/config.ts).

• DROID_MCP_MAX_AUTONOMY sets the cap (default high). An unrecognized value sets the cap to off. Requests above the cap are refused (src/config.ts).

• A local resume refuses a session whose recorded autonomy is above the cap, and checks again after loading it (src/route.ts, src/runs.ts). A fork does not check the source's autonomy; the fork gets the requested autonomy (default off).

• Over REST, the requested autonomy is capped, but the session's existing autonomy is not read or checked (src/tools.ts).

• Permission prompt answers are filtered by allowedDecisions: proceed_always*, proceed_edit, proceed_auto_run and proceed_new_session are never offered, and proceed_auto_run_<level> / proceed_new_session_<level> only when the level is within the cap. This applies to own sessions and REST answers (src/config.ts, src/runs.ts, src/tools.ts).

• No parameter maps to --skip-permissions-unsafe. The only extra droid exec argument the server adds is --worktree [branch] (src/runs.ts).

Models and settings

droid_start and droid_send share these optional settings: model, reasoningEffort, specModel, specReasoningEffort, useSpec, mission, workerModel, workerReasoningEffort, validatorModel, validatorReasoningEffort, tags, worktree, onlyTools, addTools, removeTools, appendSystemPrompt, fork.

Validation, before anything runs (src/settings.ts, src/models.ts):

• Every model id must be a built-in id, a custom id from ~/.factory/settings.json, a tier alias or a version wildcard. Unknown ids are refused with up to five close matches.

• An effort is checked against the model's supported list when that model is given (specReasoningEffort against specModel, falling back to model).

• Worker and validator settings require mission: true; mission cannot be combined with useSpec; mission requires autonomy high (the requested autonomy, or the session's current one for own and local sessions).

Where each setting is applied:

Ignored settings come back in the ignored field of the droid_send result; REST sends also return applied (src/tools.ts, src/settings.ts). useSpec: false and mission: false do nothing: neither switches a session back to normal mode.

Concurrency limits

• At most 3 turns running or waiting on a prompt at once, and one per repo. The repo is the nearest ancestor of the cwd that contains .git (src/runs.ts, src/catalog.ts).

• A pending permission or AskUser prompt is cancelled after 30 minutes (src/runs.ts).

• mode: "interrupt" waits up to 15 s for the running turn to stop; if it does not, nothing is sent (src/runs.ts).

• Each own session keeps its last 1000 events; droid_wait sets gap: true when older events were dropped (src/runs.ts).

Idempotency keys

droid_start and droid_send require an idempotencyKey (1 to 200 characters). Keys are stored in ~/.droid-mcp/state.json for 7 days (src/runs.ts):

• A retry with a finished key returns the first result without running again. For droid_start the session state in the reply is current.

• A key is marked pending before the action runs. If the action was refused before any side effect, the key is dropped and can be reused. If it failed after it may have taken effect, the key stays pending and a retry is refused.

• Each save merges with the file on disk, so several server processes can share it.

HTTP mode

• --http <host:port> requires DROID_MCP_TOKEN. Every request must send Authorization: Bearer <token>, compared with timingSafeEqual (src/main.ts).

• Any request with an Origin header is rejected with 403, so browsers cannot call the server (src/main.ts).

• DROID_MCP_TOKEN is deleted from the process environment at startup, so spawned sessions do not inherit it (src/main.ts).

• Each request gets a fresh, stateless MCP server; sessions and runs are shared across requests (src/main.ts).

What it never does

• Never returns FACTORY_API_KEY or custom-model API keys. Custom models are reduced to an allowlist of fields, and baseUrl is reduced to its host (src/models.ts).

• Never offers "always allow" permission options (src/config.ts).

• Never closes a session that is not an own session; droid_cancel with scope: "session" is refused for those (src/tools.ts).

• Never resumes a workstream session, or one whose settings it cannot read, through droid_send (src/route.ts). droid_start with fork does load its source locally without these checks.

• Never runs commands other than droid exec (through the SDK), droid exec --help, git -C <cwd> diff HEAD, rg and, on macOS, security find-generic-password (src/models.ts, src/tools.ts, src/catalog.ts, src/config.ts).

• Has no tool that deletes sessions or files (src/tools.ts).

How it works

flowchart LR
  client[MCP client] -->|stdio or HTTP| server[droid-mcp]
  server -->|read-only| files[(Local session files<br/>~/.factory/sessions<br/>~/.factory/settings.json)]
  server -->|"@factory/droid-sdk"| exec[droid exec child process]
  exec -->|writes| files
  server -->|FACTORY_API_KEY| rest[Factory REST API<br/>api.factory.ai]
  rest --> daemons[Factory cloud and desktop daemons<br/>holding the session]
  server --> helpers[git diff HEAD, rg,<br/>droid exec --help]

Sessions this server starts live in memory. When the stdio client disconnects, or the process gets SIGINT or SIGTERM, the server closes all of them. After a restart they are ordinary local sessions.

Setup

Requirements: Node >= 24, the droid CLI (logged in, or FACTORY_API_KEY), git and rg on the PATH the MCP client gives the server. Many clients start servers with a minimal PATH; pass one explicitly if droid or rg is not found.

cd /path/to/droid-mcp
npm install

Droid:

droid mcp add droid-mcp node /path/to/droid-mcp/src/main.ts --env PATH=/path/to/bin:/usr/bin:/bin

Claude Code:

claude mcp add droid-mcp -e PATH=/path/to/bin:/usr/bin:/bin -- node /path/to/droid-mcp/src/main.ts

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "droid-mcp": {
      "command": "node",
      "args": ["/path/to/droid-mcp/src/main.ts"],
      "env": { "PATH": "/path/to/bin:/usr/bin:/bin" }
    }
  }
}

HTTP mode

DROID_MCP_TOKEN=<token> node src/main.ts --http 127.0.0.1:37999

Use http://127.0.0.1:37999/mcp as the endpoint (the server answers on any path) with the header Authorization: Bearer <token>:

droid mcp add droid-mcp http://127.0.0.1:37999/mcp --type http --header "Authorization: Bearer <token>"
claude mcp add --transport http droid-mcp http://127.0.0.1:37999/mcp -H "Authorization: Bearer <token>"

To reach it from other machines on a tailnet, put it behind tailscale serve:

tailscale serve --bg --https=8443 http://127.0.0.1:37999

The endpoint is then https://<your-host>.<tailnet>.ts.net:8443/mcp. The bearer token is still required.

Configuration

On macOS, when FACTORY_API_KEY is not set, the server looks for it in the Keychain:

security add-generic-password -s droid-mcp -a FACTORY_API_KEY -w   # prompts for the key

The key is read once at startup; restart the server after changing it.

Tool reference

All results are JSON text, trimmed to about 8 KB; event text is clipped at 4000 characters with truncated: true.

seq is a cursor whose meaning depends on the source: an event number for sessions this server runs, a byte offset into the transcript for other local sessions, and a message sequence number for REST sessions. Treat it as opaque and pass nextSeq back as afterSeq.

Development

npm run typecheck   # tsc --noEmit
npm test            # node --test "test/*.test.ts"
node scripts/smoke.ts [scratchDir] [idleSessionIdToResume]

scripts/smoke.ts is a live end-to-end check over a real stdio MCP client. It spends model tokens. It starts the server with DROID_MCP_MAX_AUTONOMY=medium and FACTORY_API_KEY removed from its environment, then:

• checks the tool list, droid_find grouping, title and content search, and read-only droid_wait/droid_result on a local orchestrator;

• checks refusals: sending to a workstream without a key, an unknown session, a cwd outside the roots, autonomy above the cap;

• starts a session in the scratch dir (default ~/repos/droid-mcp-scratch, which must be inside DROID_MCP_ROOTS) at autonomy off, approves its permission prompt, and checks the created file, the result text, idempotent start and send, the diff and closing;

• with a second argument, resumes that idle local session with allowLocalResume.

It needs at least one local workstream session with its orchestrator, and a transcript containing the text droid_find. It refuses to run when a key is in the Keychain: the refusal checks send to a real workstream, and with a key those sends would go through REST and actually post.

Known limits

• REST settings updates (updateSession) are not verified against the live API.

• Sessions started with worktree run in a worktree outside the allowed roots, so droid_result refuses their diffs.

• A fork keeps its source session loaded until the fork is closed.

• Mission mode is untested live.

• REST droid_wait assumes getMessages returns the newest messages (see the comment in src/tools.ts).

• Sessions on other machines are reachable by REST, but droid_find lists only local session files (plus the REST child summary for local workstreams).

• droid_wait on a local transcript cannot see pending prompts or tool events.

• After an own session is closed, droid_wait and droid_result keep reading its in-memory state. If a later droid_send reaches it over REST, they do not see the new turn.

• Linux is untested.

Security notes

• Treat DROID_MCP_TOKEN like a password: it grants every tool, including starting sessions.

• Autonomy high lets droid run arbitrary commands, starting from a cwd inside the allowed roots but not confined to it. Lower DROID_MCP_MAX_AUTONOMY if clients should not be able to grant it.

• REST sends act as the owner of FACTORY_API_KEY, on any session that key can reach.

• Prompts are sent as the user; the session sees them as the user's own messages.

• When a key is found, the SDK passes it to spawned droid exec processes as FACTORY_API_KEY, so commands an agent runs in those sessions can read it.

License

MIT. See LICENSE.