SelfHeal MCP
Self-healing proxy for MCP servers. Wraps any MCP tool call with automatic retry, circuit breaker protection, and call observability.
Your AI agents stop breaking on flaky APIs.
One-click install: Install on MCPize |
npx selfheal-mcp
Features
- Retry with backoff — Exponential backoff + jitter on transient failures (5xx, timeouts, rate limits)
- Circuit breaker — Per-target circuit breaker stops hammering dead services
- Call metrics — Success rates, latency, error frequency, broken down by tool and target
- Proxy mode — Wrap any existing MCP server transparently
- Zero config — Works standalone out of the box, config file for proxy mode
Quick Start
Standalone Mode
Add to your Claude Desktop / Claude Code config:
{
"mcpServers": {
"selfheal": {
"command": "npx",
"args": ["-y", "selfheal-mcp"]
}
}
}
Then use wrap_call to make any HTTP request with self-healing:
Use the wrap_call tool to GET https://api.example.com/data with target "example-api"
Proxy Mode
Create selfheal.config.json:
{
"mode": "proxy",
"targets": [
{
"name": "my-server",
"transport": "streamable-http",
"url": "https://my-mcp-server.com/mcp"
}
]
}
{
"mcpServers": {
"selfheal": {
"command": "npx",
"args": ["-y", "selfheal-mcp"],
"env": {
"SELFHEAL_CONFIG": "/path/to/selfheal.config.json"
}
}
}
}
All tools from my-server are re-exposed with self-healing built in.
Tools
| Tool | Description |
|---|---|
wrap_call | Execute HTTP call with retry + circuit breaker |
circuit_status | Check health of any target |
circuit_reset | Reset circuit breaker after fixing issues |
metrics | Success rates, latency, top errors |
recent_errors | Recent failures with full details |
Proxy Mode Adds
| Tool | Description |
|---|---|
selfheal_metrics | Metrics for all proxied calls |
selfheal_circuits | Circuit status for all targets |
selfheal_recent_errors | Recent errors across all targets |
Configuration
Environment Variables
| Variable | Default | Description |
|---|---|---|
SELFHEAL_CONFIG | ./selfheal.config.json | Config file path |
SELFHEAL_MAX_RETRIES | 3 | Max retry attempts |
SELFHEAL_BASE_DELAY_MS | 1000 | Base delay for backoff |
SELFHEAL_MAX_DELAY_MS | 30000 | Max delay cap |
SELFHEAL_CIRCUIT_THRESHOLD | 5 | Failures before circuit opens |
SELFHEAL_CIRCUIT_COOLDOWN_MS | 120000 | Cooldown before half-open test |
How It Works
Agent → SelfHeal MCP → [Retry + Circuit Breaker] → Target API/MCP Server
↓
Metrics Collector
- Request arrives — Agent calls a tool
- Circuit check — If target has failed too many times, reject immediately
- Execute with retry — Try the call, retry on transient errors with exponential backoff
- Record metrics — Log success/failure, duration, attempts
- Update circuit — Track consecutive failures per target
Install
MCPize (Recommended)
One-click install with managed hosting: Install on MCPize
npm
npx selfheal-mcp
PyPI
Not applicable — this is a TypeScript server. For Python alternatives, see LeadEnrich MCP.
License
MIT — Built by Freedom Engineers
Related
- SiteHealth MCP — Full website health audit
- LeadEnrich MCP — Waterfall lead enrichment