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.

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: Claude Code 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.