mcp-restart

Supervise your local agents over MCP — start, stop, and restart them, including restarting themselves.

mcp-restart is a small supervisor server. You run it, it starts your agent (Claude Code, or anything else you can launch from a command line) as a child process, and exposes start_agent, stop_agent, restart_agent over a Model Context Protocol endpoint on localhost.

The killer feature: because the agent is a child of the supervisor, the agent can call restart_agent on itself. It edits its own launch config, restarts, and comes back up as the new version — an evolution loop with no human in the middle.

┌─────────────────────────────────────────────┐
│  mcp-restart (supervisor)                   │
│                                             │
│  http://127.0.0.1:4310/mcp  ◄── MCP tools   │
│        │                                    │
│        │ spawn / SIGTERM / SIGKILL          │
│        ▼                                    │
│  ┌───────────────────────────┐              │
│  │  claude (child process)   │              │
│  │  --mcp-config → restart   │              │
│  └───────────────────────────┘              │
└─────────────────────────────────────────────┘

Why a supervisor instead of an MCP server the agent spawns?

An MCP server over stdio is a child of the agent. If the agent kills itself, its pipes close and the server dies with it — you can't restart something from inside a process it spawned.

mcp-restart inverts that: the supervisor is the parent, the agent is the child. Restarting an agent is just kill + respawn, the supervisor owns one port for the whole session (no port contention across restarts), and the supervisor's lifetime is independent of any single agent's lifetime. The agent talks to it over loopback HTTP, so the connection is re-established on every boot.

Quickstart

# install
npm install -g mcp-restart        # or: npx mcp-restart ... (no install)

# create a config
mcp-restart init
# → wrote ./mcp-restart.config.json

# start the supervisor (starts agents with "autostart": true)
mcp-restart serve

Generated config:

{
  "host": "127.0.0.1",
  "port": 4310,
  "agents": [
    {
      "name": "claude",
      "command": "claude",
      "cwd": ".",
      "autostart": true
    }
  ]
}

When serve starts, it spawns Claude with --mcp-config <generated> pointing at http://127.0.0.1:4310/mcp. Claude has the restart tools from the moment it boots. Ctrl+C the supervisor and everything shuts down cleanly together.

MCP tools

Tool	Description
list_agents	All configured agents with state, pid, uptime, last exit code
server_status	Version, pid, endpoint URL, uptime, agent statuses
start_agent	Start a configured agent (name)
stop_agent	Stop gracefully: SIGTERM → wait for graceful timeout → SIGKILL
restart_agent	Stop, re-read the config file, start again with the fresh config

Every tool returns structured JSON. Unknown agents and invalid operations come back as MCP tool errors, never crashes.

The self-restart loop (agent evolution)

The point of this project. An agent that can restart itself can evolve: edit its code or its launch config, then reboot into the new version.

1. The agent writes its own entry into mcp-restart.config.json (it knows how it's launched).
2. It calls restart_agent with its own name.
3. The supervisor terminates it, re-reads the config file, and spawns the replacement.
4. The new agent boots, reconnects to the same endpoint, and picks up where the loop left off.

Because the config is re-read on every restart, changes take effect immediately — no supervisor restart required. The supervisor itself only cares that the agent is running; what the agent becomes is up to the agent.

Config reference

Top-level:

Field	Default	Description
host	127.0.0.1	Bind address. Non-loopback addresses require a token.
port	4310	TCP port. 0 picks a free port.
token	—	Bearer token required on all MCP requests (also settable via MCP_RESTART_TOKEN).
stateDir	~/.local/state/mcp-restart	Generated MCP configs, supervisor log, agent logs.
agents	[]	Array of agent definitions.

Per agent:

Field	Default	Description
name	—	Unique name used to address the agent (letters, digits, ., _, -).
command	—	Executable to spawn, resolved via PATH. No shell involved — put everything in args.
args	[]	Arguments.
cwd	supervisor's cwd	Working directory.
env	—	Extra environment variables.
autostart	false	Start when the supervisor starts.
gracefulTimeoutMs	10000	How long to wait after SIGTERM before SIGKILL.
injectMcp	true	Wire the restart MCP config into the agent (see below).
logFile	<stateDir>/logs/<name>.log	Agent stdout/stderr in --daemon mode.

MCP injection

With injectMcp: true (default), the supervisor:

• generates a standard MCP config file ({ "mcpServers": { "restart": { "type": "http", "url": ... } } }) in <stateDir>/mcp-config/<name>.mcp.json,
• sets MCP_RESTART_URL and MCP_RESTART_CONFIG_FILE env vars for the agent,
• for Claude Code (command basename starting with claude), appends --mcp-config <file> so it's wired up automatically.

Any MCP-capable agent can read MCP_RESTART_CONFIG_FILE and register the restart server itself.

Running in the background

mcp-restart serve --daemon

Daemon mode detaches from the terminal, writes the supervisor log to <stateDir>/mcp-restart.log, and routes agent output to per-agent log files. Agents run headless. Stop it with pkill -TERM -f "mcp-restart serve" or a service manager.

For always-on setups, run serve --daemon under launchd/systemd/whatever you already use for long-running things.

Security

• Loopback only by default. Binding anything else is refused unless you set a token.
• Token auth — when set, every MCP request requires Authorization: Bearer <token>.
• The supervisor only touches processes it spawned. There is no "kill arbitrary PID" tool. restart_agent operates exclusively on configured agents.
• Graceful-then-forced stops. SIGTERM first, SIGKILL only after gracefulTimeoutMs.
• No shell. command/args are passed to execvp directly — no shell injection surface.

FAQ

Why not stdio? Because a stdio MCP server dies with the agent that spawned it. The whole point is surviving the agent's death — and the supervisor model removes the "detached respawn" dance entirely.

Why HTTP instead of spawning a fresh MCP server per boot? One supervisor owns one port for the whole session. No port contention, no config re-wiring across restarts, and the loopback endpoint is reachable by any local process.

Does my agent auto-restart when it crashes? No. autostart only runs at supervisor boot; crashes are logged, never restarted silently. No crash loops. If you want crash-restart, wrap the agent (or run it under launchd/systemd) — the supervisor will happily supervise whatever comes up.

What about Windows? The code has basic support (no process-group kills — children are signalled directly) but it's untested. macOS and Linux are the supported platforms.

What if I remove an agent from the config while it's running? The process keeps running (we don't kill things just because you edited a file) but it stops appearing in list_agents. Use stop_agent first.

Development

npm install
npm run build       # tsc → dist/
npm test            # 30 tests: config validation, supervision, full MCP loop, CLI
npm run typecheck   # strict typecheck of src + test

The integration test boots the real stack (HTTP server + MCP client) with a fake agent, restarts it through the MCP protocol, verifies the replacement sees the edited config, and confirms auth rejection without a token.

License

MIT