mcp-orchestrator

Manages the local MCP servers on a Windows machine. Installs them, starts them hidden at logon, restarts them when they crash, and shows the lot in a tray icon.

One hidden process, started by a Scheduled Task, serving MCP on http://127.0.0.1:8768/mcp.

Install

python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\install\install.ps1
claude mcp add --transport http --scope user orchestrator http://127.0.0.1:8768/mcp

Registers the Scheduled Task and adds two Claude Code hooks. Undo with .\install\uninstall.ps1.

Related MCP server: amp-mcp-server

Installable servers

mcp_install("queue")

mcp_install also takes any git URL, or a local path for a private repo. It expects the ordinary Python layout: a package containing server.py, with requirements.txt beside it.

Tools

What it does about failure

A hidden server has no window to die in, so the whole design is about not letting a dead one look like a missing tool.

• States distinguish causes. crashed (died on its own) is not stopped (somebody stopped it), and unhealthy (alive, not listening) is not either. external means the port answers but the orchestrator did not start it, and will not touch it.

• A start waits for the port before reporting success. A pid proves nothing.

• Crashes are restarted on a 5, 15, 45, 120, 300 second ladder, then abandoned with a notification. Two minutes of health clears the count.

• The tray colour is the summary. Green up, amber starting or stopped, red with an exclamation for trouble.

Sessions and the restart dance

Claude Code attaches MCP servers at startup and never retries. Adding or removing a server is invisible to running sessions until they restart, so mcp_install, mcp_scaffold, mcp_add and mcp_uninstall ask them to. Restarting a server needs nothing; the client reconnects per call.

The restart is decentralised. A change drops a marker, and each session's Stop hook acts on it at the end of a turn, when nothing is in flight, resuming the same transcript so history and queue survive.

Files

State lives in ~/.mcp-orchestrator, outside this repo, because the hooks must find it without knowing where the repo was cloned: servers.json (hand editable), running.json, sessions.json, the restart markers, and logs/.

Known gaps

• The at-logon trigger is configured but has only ever been fired manually.

• The live session restart path (wt.exe plus --resume) is unproven.

• orchestrator.log does not rotate; per-server logs rotate at 5 MB.

• Windows only, throughout.

DESIGN.md has the reasoning, including why this is a Scheduled Task and not a Windows Service, and the Windows traps that cost a debugging round each.