MCP Pacemaker

Developer utility for local MCP process supervision and HTTP bridging, with isolated sessions, opt-in compatible sharing, and a web dashboard.

Documentation

mcp-pacemaker

Keep your MCP servers running outside the editor or CLI. One long-lived local bridge runs your MCP servers and every editor and agent CLI connects to it, so a CLI exiting no longer kills them.

Demo: two isolated launches, one shared launch, none added on reconnect

npm install -g mcp-pacemaker   # Node 22 or 24, run as a normal user
mcp-pacemaker init             # imports your servers, asks before rewiring any host

Install from npm · Report a problem · Release notes · Demo and design write-up

This README describes 2.1.2. See the release changes.

What it does

MCP hosts — editors (VS Code, Cursor, Claude Desktop) and CLIs (Claude Code, Copilot CLI, Codex, Gemini) — run stdio MCP servers as child processes. When the host restarts, crashes, or exits (every one-shot CLI run), those servers die.

  • Keeps servers running. mcp-pacemaker runs your servers as children of a small, long-lived bridge and exposes each over the MCP HTTP+SSE / Streamable HTTP transport.
  • Shares one bridge. Multiple hosts use one bridge, with an isolated child per session by default. Opt into pre-warming or reuse one initialized child for compatible stateless tools sessions with shared mode. Wire hosts to one bridge, or give each its own.
  • Survives reboots and token expiry. A cross-platform supervisor + OS auto-start keep the bridge itself alive across reboots and sleep/wake, and a pluggable auth layer injects a fresh token per request for HTTP servers.
  • Reconnects returning clients. After a restart, a returning client can reuse a recorded session ID to re-establish its handshake against a fresh server. This does not restore arbitrary tool state or preserve TCP connections. Clients that stop retrying after a dropped connection may still need a reload; socket handoff is separate planned work.
  • Shows what is running. status, top and a web dashboard show whether each server is up and which clients use it. See dashboards.

Quick start

Install mcp-pacemaker 2.1.2 from npm. Use a maintained Node.js 22 or 24 release; Windows also needs PowerShell 7 and Windows Script Host. See installation requirements before setup.

npm view mcp-pacemaker@2.1.2 version
npm install -g mcp-pacemaker@2.1.2
mcp-pacemaker --version

The version check prints 2.1.2 without running setup.

Run it as an ordinary user. From 2.1.0 the bridge, supervisor and default upgrades refuse a privileged caller at startup — a non-administrator terminal on Windows and a non-root session on Linux/macOS, including the default root user in most containers. A refused start prints User-runtime execution refused: …. There is no override; run as a normal user instead. See the user-runtime contract.

Before setup, have a readable JSON host configuration containing server definitions, or prepare ~/.mcp-pacemaker/servers.json. Supported import sources are vscode, cursor, claude (Claude Desktop), copilot-cli and gemini. Codex and Claude Code are wiring destinations, not import sources.

Then run interactive setup:

mcp-pacemaker init

init detects supported hosts, imports one source host (or reuses servers.json), asks for confirmation before wiring the selected hosts, registers OS auto-start and starts the bridge. Reload or restart the selected hosts afterward.

Setup changes local configuration and auto-start. Importing can create or update servers.json before the wiring confirmation. Existing JSON/TOML host files get a .bak before replacement; native Claude Code registrations do not. Keep your own protected configuration backup, especially before repeating setup.

--from chooses the import source; --client chooses wiring destinations. For example, mcp-pacemaker init --from vscode --client codex imports VS Code's definitions and wires Codex. Without --from, setup prefers the first detected JSON host; it does not merge every detected host. Omit --yes to keep the confirmation prompt.

Check the running bridge:

mcp-pacemaker status     # status without entering first-run setup
mcp-pacemaker top        # live terminal dashboard
mcp-pacemaker doctor     # diagnose config, reachability, wiring
Prefer to drive it yourself? The same steps, one at a time

plan, install and emit accept any supported host as a wiring target. import --from accepts the five JSON import sources listed above. Run import first unless you already have servers.json; plan needs that file.

mcp-pacemaker import  --from <source>          # write servers.json from one JSON host config
mcp-pacemaker plan    --client <host>          # dry run: show what install would change
mcp-pacemaker install --client <host>          # wire one host (--port N gives it its own bridge)
mcp-pacemaker start                            # start the bridge
# e.g. import from Cursor, then wire three hosts to the same bridge
mcp-pacemaker import  --from cursor
mcp-pacemaker install --client cursor
mcp-pacemaker install --client claude-code
mcp-pacemaker install --client gemini

Run install once per host you want wired; repeat with --port N instead to give a host its own bridge. emit prints the config entries without writing anything, if you'd rather paste them in.

How it compares

Checked against each project's latest release on October 16, 2026. Every cell is sourced in docs/comparison.md. These projects overlap; mcp-pacemaker focuses on keeping MCP servers running on a developer workstation.

Supergatewaymcp-proxyMCP HubToolHivemcp-pacemaker
Serves stdio servers over Streamable HTTP✅✅❌✅✅
Serves stdio servers over SSE (legacy)✅✅✅✅ (deprecated)✅
What you installnpm, binary or DockerPyPI or Dockernpm or NixGo binary + Docker or Podmannpm; the bridge has zero dependencies
Restarts crashed processes automaticallynew child per connection❌manual restart (API)✅✅ bridge and warm pools
Starts at OS logon❌❌❌desktop app only✅ Windows, macOS, Linux
Starts again after unlock or wake❌❌❌❌✅ Windows
Auth header from your own command, auto-refreshed❌❌at connect only❌✅
Sessions survive a bridge restart without re-initializing❌❌❌Kubernetes with Redis only✅
Timed restart to refresh an interactive login❌❌❌❌✅
Reuses existing client MCP config files✅stdio entries only✅❌✅
Wires editors and CLIs for you❌❌❌✅✅
Web dashboard❌❌❌desktop app instead✅
Terminal dashboard❌❌❌✅ (experimental)✅
HTTP control APIhealth checks only/status only✅✅✅

A surviving session re-establishes the client's handshake against a fresh server; it does not restore arbitrary tool state. A transport bridge is not a sandbox for untrusted tools.

Everyday commands

CommandWhat it does
init [--from source] [--client a,b] [--yes]Interactive setup: import one source, wire selected hosts, auto-start, launch
statusBridges, wired hosts, servers, and any server currently failing
top / dashboardLive terminal UI / web dashboard
doctorDiagnose config, bridge reachability, host wiring
uninstallStop managed bridges, remove auto-start, restore available host-file .bak copies; native entries are not restored

The command reference lists every command, including reload, logs, prewarm, upgrade and --instance.

Which process-sharing mode?

Sharing a bridge does not automatically share a server process.

ModeProcess behaviorUse when
isolated (default)One child per sessionThe server needs per-client workspace, account or conversation state
pool (opt-in)Pre-started, uninitialized children; each is assigned exclusively to one sessionStartup is slow but sessions must remain separate
shared (opt-in)One initialized child for compatible sessionsTools are stateless, inputs are explicit and the credential context is common

Shared clients must send identical initialization parameters, including clientInfo, and empty client capabilities. It is not automatic cross-editor sharing. See shared-mode limits before enabling it.

Supported hosts

Editors and CLIs are auto-detected and wired to the bridge. Most hosts get Streamable HTTP (/<name>/mcp); Cursor and Claude Desktop are wired over SSE (/<name>/sse) until Streamable HTTP is verified there. The bridge centralizes auth, so hosts talk to it unauthenticated over loopback.

HostTypeConfigWiringTransport
VS CodeeditorCode/User/mcp.jsondirect editStreamable HTTP
Cursoreditor~/.cursor/mcp.jsondirect editSSE
Claude Desktopeditorclaude_desktop_config.jsondirect editSSE
Claude CodeCLI~/.claude.jsonnative claude mcp addStreamable HTTP
Copilot CLICLI~/.copilot/mcp-config.jsondirect editStreamable HTTP
Codex CLICLI~/.codex/config.tomlTOML (comment-preserving)Streamable HTTP
Gemini CLICLI~/.gemini/settings.jsondirect editStreamable HTTP

Topologies: wire every host to one shared bridge (default), or give each host its own bridge (install --client X --port N) — or any mix. status/doctor report all bridges + wired hosts.

Upgrades

Package installation alone does not upgrade a running backend. Use explicit upgrade --to for managed replacement. Bare upgrade retains the older host-repair behavior.

Managed upgrades need 2.1.0 or newer and must run as an ordinary user. Start with mcp-pacemaker upgrade --to <exact-version> --plan, which changes nothing. --sxs keeps the old instance and starts an isolated new one. Do not overwrite a package directory while its supervisor or bridge is running. An upgrade may end open sessions and calls in progress; clients reconnect, and no call is retried. It never changes servers.json or your client setup.

The one-time Windows 1.3 restart migration restarts Pacemaker, not Windows. It stops the 1.3 bridge and the processes it started, so open sessions end. Confirm it at the prompt or with --yes. Run it from a separate durable package; do not overwrite the running 1.3 package first. If 1.3 was set up from an administrator terminal, run mcp-pacemaker upgrade --fix-legacy-access once from an administrator terminal first; see that section.

See upgrades and rollback for recovery, rollback and side-by-side instances.

Uninstall

install backs up an existing JSON/TOML host file to .bak; repeating it replaces that backup. uninstall restores available host-file backups, leaves files without backups as-is, and keeps servers.json. Native Claude Code registrations are not backed up or automatically restored; record their original definitions separately and restore them through Claude Code.

mcp-pacemaker uninstall      # use the CLI from the matching installed version

This stops managed bridges, removes auto-start entries and restores available host-file backups. It leaves files without backups and native Claude Code registrations unchanged. It is not scoped to one port; review replacement and rollback first if another instance must remain running. Do not fetch a different CLI with npx to remove an existing installation.

After the installed service has been removed successfully, remove the global npm package:

npm uninstall -g mcp-pacemaker

Security

  • The bridge binds 127.0.0.1 only (local loopback) — not reachable off-box.
  • Tokens are minted from your own already-authenticated CLI and cached in memory; never written to disk.
  • The bridge (the process that runs 24/7) has zero third-party dependencies; the setup CLI uses commander / @clack/prompts / picocolors / smol-toml, and the TUI adds ink / react.

See SECURITY.md for the threat model and how to report a vulnerability. The HTTP API page explains how administrative requests are guarded.

Documentation

Project

License

MIT © Girish Konda