mcp-circuit-breaker
Detects MCP tool failure patterns and trips a circuit breaker to stop cascading retries. Proposes fallback alternatives and resets when the tool recovers. Triggers on "MCP failing", "tool keeps erroring", "circuit-breaker", repeated tool call failures.
chrono-meta · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add chrono-meta/forge-harness --skill mcp-circuit-breaker技能说明
name: mcp-circuit-breaker description: Detects MCP tool failure patterns and trips a circuit breaker to stop cascading retries. Proposes fallback alternatives and resets when the tool recovers. Triggers on "MCP failing", "tool keeps erroring", "circuit-breaker", repeated tool call failures. user-invocable: true allowed-tools: ["Read", "Bash", "Write"] model: sonnet complexity_routing: base: sonnet high: opus escalate_when: - multi_server_failure - unknown_mcp_server
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:"
An empty result above means "no project/user-scope config found" — never "no MCP mounted":
plugin-provided and remotely-managed servers appear in no local file. The live mount evidence is the
failing tool call itself (mcp__{server}__{tool} in this session); classify from that name even when
every config read comes back empty.
Classify failure type:
| Type | Symptom | Likely Cause |
|---|---|---|
TIMEOUT | Tool call hangs >30s | Server overload / network |
AUTH | 401 / 403 response | Credentials expired or missing |
NOT_FOUND | 404 / tool not available | Server down / tool removed |
MALFORMED | Parse error on response | Schema mismatch / API change |
RATE_LIMIT | 429 / quota exceeded | Too many calls |
ADMIN_GATED | "instance admin approval required" / server pending org enablement / tool unavailable until approved | Capability exists; the MCP mount is gated behind instance/admin permission — not a transport failure. Retrying never recovers it (an admin must act) |
If failure type cannot be determined: classify as UNKNOWN.
ADMIN_GATEDis not a retry case. Distinguish capability unavailable from MCP transport unavailable: when the block is an org/admin approval dependency, do not burn retries — route straight to the lower-permission substitute in Step 4 (Priority 1b).
Step 2. Trip Decision
Count consecutive failures of the identified tool in the current session context.
| Count | Action |
|---|---|
| 1 | Log warning. Continue — "MCP tool {name} failed once. Monitoring." |
| 2 | Escalate warning. Suggest checking server status. |
| 3+ | TRIP CIRCUIT → output circuit open notice, block further calls to this tool |
Non-transient types trip at count 1, not 3.
ADMIN_GATED,AUTH, andNOT_FOUNDdo not recover on retry (an admin must act / credentials must change / the tool is gone), so counting to 3 only wastes calls. On the first failure of one of these types, trip immediately and go to Step 4. The 1→2→3 ramp is for transient types (TIMEOUT,RATE_LIMIT) where a later call may succeed.
Circuit open notice format:
⚡ CIRCUIT OPEN — {tool-name}
Failure type: {TYPE} | Consecutive failures: {N}
Further calls to this tool are blocked until circuit resets.
(Blocking is session-level discipline — this skill's protocol, not a mechanical hook; no PreToolUse gate enforces it. State it that way if asked — a protocol honestly labeled beats a phantom enforcement claim.)
Step 3. Log Circuit State
Write state to session-local file (in-memory is insufficient — logs survive /clear):
mkdir -p .claude/mcp_circuit/
grep -qxF '.claude/mcp_circuit/' .gitignore 2>/dev/null \
|| echo "NOTE: add '.claude/mcp_circuit/' to .gitignore — session state must not become a tracked file (the ignored-but-committed class public-surface-audit Step 3c hunts)"
cat >> .claude/mcp_circuit/circuit_log.yaml << EOF
- tool: {tool-name}
state: OPEN # OPEN | HALF-OPEN | CLOSED — same enum as Done When
failure_type: {TYPE}
failure_count: {N}
tripped_at: {ISO-8601}
reset_at: null
EOF
Step 4. Propose Alternatives
Present the relevant fallback options ranked by effort (at least 3):
| Priority | Alternative | When to Use |
|---|---|---|
| 1 — Substitute tool | Use a different MCP tool or built-in tool that covers the same task | Tool-specific failure (NOT_FOUND, AUTH) |
| 1b — Lower-permission API / workflow substitute | Th |