Keep MCP servers alive with health checks and auto-restart

MCP servers die quietly mid-session and the agent just... stops using the tool. Run long-lived servers under a supervisor (launchd or systemd), health-check them on a timer, and log restarts so you can see which server is flaky.

Expected result

Long-running MCP servers restart automatically within seconds of crashing, a health-check log tells you which server flapped and when, and agents reconnect instead of silently losing tools mid-session.

Difficulty

Advanced

Estimated time

~45 min

Version notes

Health-check request uses MCP protocol 2025-06-18 streamable HTTP. Older SSE-only servers: probe GET /sse for a 200 and an event-stream content type instead.

1. 01An MCP server worth keeping alive (HTTP/SSE transport — stdio servers are agent-managed)
2. 02macOS (launchd) or Linux (systemd --user)
3. 03curl and jq

01

Know which servers this applies to

stdio servers are children of the agent process; the agent restarts them and there's nothing to supervise. This recipe is for servers you run as standalone HTTP/SSE services — shared Postgres MCP, a team Sentry MCP, anything with its own port.

claude mcp list

Copy

02

Write a real health check, not a port check

A listening port proves nothing — wedged servers keep their sockets. Probe the MCP endpoint with an initialize request and require a sane JSON-RPC response within a timeout.

#!/usr/bin/env bash
# /usr/local/bin/mcp-health — exit 0 healthy, 1 not
set -u
URL="http://127.0.0.1:8931/mcp"
resp=$(curl -sf --max-time 5 -X POST "$URL" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"healthcheck","version":"1.0"}}}') || exit 1
echo "$resp" | grep -q '"serverInfo"' || exit 1

Copy

03

! Common failures

Agent session still loses the tool even though the server restarted

The server is back but the session's connection isn't. In Claude Code, /mcp lets you reconnect without restarting the session. If reconnects fail repeatedly, the restart is losing server-side session state — front it with a stateless proxy or accept session restarts.

launchd job flaps every 10 seconds forever

The command itself fails on boot — usually PATH. launchd doesn't source your shell profile; use absolute paths (which npx to find yours) and check the StandardErrorPath log.

Health check passes but tool calls hang

Initialize is cheap; the wedge is in the tool path (a stuck DB connection, usually). Add a second probe that exercises one real tool call with a timeout, and alert on that one separately.