claude-sessions-mcp

An MCP server for creating and driving Claude Code sessions inside a running Remote Control server, over the REST API the bridge itself uses.

An agent can call in a colleague that is not running yet, hand it a prompt, and have it start working — as a session that belongs to the project's server, with its worker under that server, visible in claude.ai and reachable from the other sessions on the machine. The same tools let you survey and steer every agent running there from a session opened on a phone.

Runs as a single process per machine (streamable-HTTP on 127.0.0.1), not as a stdio subprocess per session.

See the design for the verified API surface, how bridge servers are discovered without any host-specific configuration, the tools, and the safety rails around spawning agents.

Usage

Build

npm install
npm run build

Install as a systemd user service

Copy the unit into your systemd user directory and adjust the two paths to where you checked out this repository:

cp deploy/claude-sessions-mcp.service ~/.config/systemd/user/

Edit WorkingDirectory= and ExecStart= in the copied unit if the repository does not live directly under your home directory (the shipped unit assumes ~/claude-sessions-mcp). Then enable and start it:

systemctl --user enable --now claude-sessions-mcp

Register it with Claude Code

claude mcp add --transport http --scope user sessions http://127.0.0.1:8765/mcp

Environment variables

Requirements

Node.js 22 or newer (the code is ESM and uses ES2023 library features).

Linux only — bridge discovery reads /proc to find running Remote Control servers and their workers. The server must run as the same user as the bridges it talks to: it reads their process table and the shared credentials file, both of which are only visible to that user.

The server keeps no state between calls: no session registry, no database, no files of its own. wait_for_idle holds an event stream open for the duration of that one call, and alongside it polls the session's status, because archiving a session cuts its turn short without emitting anything on the stream. Both end with the call: nothing is subscribed or watched between calls.

After a bridge restart

A stopped bridge does not release the work leases of its sessions. When it comes back, it re-queues only the one session its pointer file names; every other session stays without a worker until the old lease expires (about six minutes, measured on CLI 2.1.284) and a client re-opens it. A user message alone never gets it a worker. In the claude.ai client this looks like "Remote Control disconnected" for a bridge that is in fact up.

claude-sessions reattach <instance> hands the bridge back every live session of its environment that has no worker, through the same /v1/environments/<env>/bridge/reconnect call the bridge makes for its own anchor, which does not wait for the lease. It waits up to a minute for the bridge to show up, so it can run as an ExecStartPost= of the unit that runs the bridge:

ExecStartPost=-/path/to/claude-sessions reattach %i

It prints a JSON report (reattached, failed) and exits non-zero only when the bridge never appeared. send_message does the same for the one session it writes to, when that session has no worker (reattached: true in its result).

Safety rails

• permission_mode accepts auto, acceptEdits, plan, manual or dontAsk only. bypassPermissions is refused outright, never downgraded.

• Sessions can be spawned only in bridges discovered on this machine, never in a raw environment id.

• CLAUDE_SESSIONS_MCP_MAX_SPAWNED bounds how many active sessions this server may have created per bridge; if that count cannot be established completely, the spawn is refused rather than allowed.

• Every created session is tagged mcp:claude-sessions-mcp and spawned-by:<caller>.

Related MCP server: Rail Connector MCP

Releasing

The version lives in one place, package.json; the server reports it in the MCP handshake, and a test asserts the two agree.

npm run release -- patch | minor | major | X.Y.Z

The script refuses a dirty tree or a branch other than master, checks that the target tag is free and that origin is not ahead, runs the build and the tests, then bumps the version, commits and tags vX.Y.Z. Pushing is left to you — it prints the command.

Pushing the tag opens a draft release with generated notes (.github/workflows/release-draft.yml); edit it into something worth reading and publish it by hand. Nothing else reacts to a tag: there is no build to trigger and nothing to deploy.

Every push and pull request runs the build and the test suite (.github/workflows/ci.yml).

Inside Claude Code, /build [patch|minor|major|X.Y.Z] walks the whole cycle: release script, tag push, both workflows, the draft notes, and a restart of the local service if one is installed. It stops short of publishing the release.

License

MIT — see LICENSE.