mcp-circuit-breaker

mcp-circuit-breaker — MCP Tool Failure Guard

MCP tools can fail silently or return partial results, leading to cascading retry loops that waste tokens and degrade session quality. This skill detects failure patterns, trips a circuit breaker to halt retries, proposes alternatives, and resets when the tool recovers.

Scope distinction

• Claude Code native retry: low-level transport retries (transparent, fast)
• mcp-circuit-breaker: session-level guard — detects repeated semantic failures, intervenes before token waste compounds

---

Triggers

• /mcp-circuit-breaker
• "MCP failing", "MCP keeps erroring", "tool isn't working", "circuit-breaker"
• "same error keeps happening", "tool call looping", "MCP timeout"
• Automatic: when the same MCP tool name appears in 3+ consecutive failed calls within a session

---

Circuit States

CLOSED   → Normal operation (tool calls pass through)
OPEN     → Circuit tripped (calls blocked, alternatives proposed)
HALF-OPEN → Recovery probe (1 test call allowed, resets if success)

Default thresholds:

• Trip threshold: 3 consecutive failures of the same tool
• Half-open probe: after 60s cooldown (or explicit user command)
• Reset: 1 successful call in HALF-OPEN state → back to CLOSED

---

Execution Steps

Step 1. Detect Failure Pattern

Identify the failing tool and failure mode:

# MCP mounts live in SEVERAL scopes — check all that this shell can see. Project settings.json is
# usually NOT one of them (it commonly holds hooks only), so a single-file read renders "no config"
# on a session with live MCP servers — a wrong-location instrument, not a measurement.
for f in .mcp.json .claude/settings.json .claude/settings.local.json; do
  [ -e "$f" ] && { echo "== $f =="; grep -A5 '"mcpServers"' "$f" 2>/dev/null || echo "(present, no mcpServers key)"; }
done
[ -e ~/.claude.json ] && grep -c '"mcpServers"' ~/.claude.json | xargs echo "user-scope ~/.claude.json mcpServers blocks:"