# 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

```bash
# 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:

```json
{
  "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

```bash
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

```bash
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