About SelfHeal MCP
SelfHeal MCP is an MCP server in the Browser category: self-healing proxy for MCP servers with retry, circuit breaker, and observability.
Install
claude mcp add selfheal-mcp -- npx -y selfheal-mcpnpx -y selfheal-mcpThis server has no ConduID identity, so agent calls to it are not receipted. Pin the version you install and review the source before granting it credentials.
Tools (5)
circuit_resetReset circuit breaker after fixing issues
Parameters not published.
circuit_statusCheck health of any target
Parameters not published.
metricsSuccess rates, latency, top errors
Parameters not published.
recent_errorsRecent failures with full details
Parameters not published.
wrap_callExecute HTTP call with retry + circuit breaker
Parameters not published.
Ask AI
Ask AI about SelfHeal MCP
Powered by Claude · Grounded in docs
Security checks
- ✓README presentThe repository ships documentation.
5 checks have not been run yet.
README
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
README copy captured when this server was indexed; it may lag the repository. The original is authoritative.