SelfHeal MCP server

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

Proxy Mode Adds

Configuration

Environment Variables

How It Works

Agent → SelfHeal MCP → [Retry + Circuit Breaker] → Target API/MCP Server
                ↓
          Metrics Collector

1. Request arrives — Agent calls a tool
2. Circuit check — If target has failed too many times, reject immediately
3. Execute with retry — Try the call, retry on transient errors with exponential backoff
4. Record metrics — Log success/failure, duration, attempts
5. 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

Shortened. The full README is on GitHub.