mcp-circuit-breaker

What problem does it solve?

MCP tool failures often trigger cascading retry loops that waste tokens, degrade AI session performance, and produce no useful output, leaving you stuck waiting for unresponsive tools to recover without a clear path forward.

Core Features & Use Cases

• Failure Pattern Detection: Automatically identifies repeated failures of the same MCP tool and classifies the failure type (timeout, auth error, admin gating, rate limit, etc.) to avoid wasting retries on non-transient issues.
• Circuit Breaker State Machine: Trips a circuit after configurable failure thresholds to block further calls to the broken tool, preventing token waste from compounding.
• Ranked Fallback Alternatives: Proposes 3 prioritized fallback options for each failure type, including substitute tools, graceful degradation, and scheduled recovery probes.
• Use Case: If you are working with a flaky third-party MCP server that keeps timing out, this skill stops the retry loop, suggests using a local alternative or waiting for recovery instead of burning through your token budget.

Quick Start

Invoke the mcp-circuit-breaker skill when you notice an MCP tool failing repeatedly to get failure classification, blocked retries, and ranked fallback options immediately.