Session Hook

Health-check servers before they waste tokens.

A SessionStart hook that checks every MCP server at startup, quarantines broken ones, and auto-restores them when they come back online.

Get started Read the Handbook

Install

pip install mcp-bouncer

Status

mcp-bouncer status # 3/4 healthy, quarantined: voice-soundboard

Check

mcp-bouncer check # Re-tests all servers now

Features

Automatic server hygiene for every session.

Health checks

Resolves binaries, spawns each server, and verifies it stays alive for 2 seconds. Catches missing binaries, broken deps, and crash-on-startup bugs.

Auto-quarantine

Broken servers are moved to .mcp.health.json with full config preserved. No tools leak into context, no red warnings on session start.

Auto-restore

Every session, quarantined servers are re-tested. When they pass, they're automatically restored to .mcp.json — zero manual intervention.

How It Works

One hook, fully automatic.

Session starts

Bouncer reads .mcp.json (active) and .mcp.health.json (quarantined), then health-checks ALL servers in parallel.

Broken → quarantined

Servers that fail are moved out of .mcp.json into quarantine with reason, timestamp, and fail count preserved.

Recovered → restored

Quarantined servers that pass are moved back into .mcp.json automatically. Summary logged to session.

Quick Start

pip install

pip install mcp-bouncer

# settings.local.json or .claude/settings.json
{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "mcp-bouncer-hook",
        "timeout": 10
      }]
    }]
  }
}

CLI commands

# Show active vs quarantined
mcp-bouncer status

# Run health checks now
mcp-bouncer check

# Force-restore all quarantined
mcp-bouncer restore

# Custom .mcp.json path
mcp-bouncer status /path/to/.mcp.json

Design

Built for reliability.

Zero dependencies

Stdlib only — runs anywhere Python 3.10+ lives. No pip dependency tree to manage.

Fail-safe

If Bouncer itself crashes, .mcp.json is unchanged. Only touches the mcpServers key, preserves $schema and defaults.

Parallel checks

ThreadPoolExecutor with 5 workers. All servers checked simultaneously, well within the 10-second hook timeout.