About SelfHeal MCP
SelfHeal MCP is a proxy for MCP servers that adds retries, circuit breakers, and call metrics. It is intended for agent setups that need to handle transient failures and inspect target health.
Key features
- 01Retry transient failures with backoff
- 02Protect targets with circuit breakers
- 03Track call success, latency, and errors
- 04Proxy existing MCP servers
- 05Inspect and reset circuit status
Use cases
- 01Reduce interruptions from flaky API calls
- 02Expose an existing MCP server through a proxy
- 03Review call metrics and recent failures
MCP support
In proxy mode, it wraps existing MCP servers and re-exposes their tools with retry and circuit-breaker handling. Its own MCP tools provide HTTP calls, circuit controls, metrics, and recent error details.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y selfheal-mcpSELFHEAL_CONFIGPath to selfheal.config.json (optional, defaults to cwd)SELFHEAL_MAX_RETRIESMax retry attempts per call (default: 3)SELFHEAL_CIRCUIT_THRESHOLDFailures before circuit opens (default: 5)Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
5Saved tool list · updated 3w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| url | string | No | URL to call (for HTTP targets) |
| body | string | No | Request body (for POST/PUT/PATCH) |
| method | enum | No | HTTP method (default: GET)GET | POST | PUT | PATCH | DELETE |
| target | string | Yes | Identifier for the target service (used for circuit breaker tracking) |
| headers | object | No | HTTP headers |
| timeoutMs | number | No | Timeout per attempt in ms (default: 30000) |
| description | string | Yes | Human-readable description of what this call does |
Details
From the project READMESelfHeal 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
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.