English Français العربية

SelfHeal MCP

Official registry Cloud and DevOps

Self-healing proxy for MCP servers with retry, circuit breaker, and observability

Source code Website Documentation

What can you do with SelfHeal MCP?

  • 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

Install

Add this to your client's MCP configuration (Claude Desktop: claude_desktop_config.json; Cursor: .cursor/mcp.json; VS Code and others use the same "mcpServers" shape).

NPM package selfheal-mcp
Claude Code 
claude mcp add selfheal-mcp -e 'SELFHEAL_CONFIG=<SELFHEAL_CONFIG>' -e 'SELFHEAL_MAX_RETRIES=<SELFHEAL_MAX_RETRIES>' -e 'SELFHEAL_CIRCUIT_THRESHOLD=<SELFHEAL_CIRCUIT_THRESHOLD>' -- npx -y selfheal-mcp@0.1.1
JSON configuration (Claude Desktop, Cursor, VS Code) 
{
    "mcpServers": {
        "selfheal-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "selfheal-mcp@0.1.1"
            ],
            "env": {
                "SELFHEAL_CONFIG": "<SELFHEAL_CONFIG>",
                "SELFHEAL_MAX_RETRIES": "<SELFHEAL_MAX_RETRIES>",
                "SELFHEAL_CIRCUIT_THRESHOLD": "<SELFHEAL_CIRCUIT_THRESHOLD>"
            }
        }
    }
}

Environment variables

  • SELFHEAL_CONFIG Path to selfheal.config.json (optional, defaults to cwd)
  • SELFHEAL_MAX_RETRIES Max retry attempts per call (default: 3)
  • SELFHEAL_CIRCUIT_THRESHOLD Failures before circuit opens (default: 5)

Documentation

From the project's README on GitHub, refreshed weekly. Links open on GitHub.

Contents
  1. SelfHeal MCP
  2. Features
  3. Quick Start
  4. Tools
  5. Configuration
  6. How It Works
  7. Install
  8. License
  9. Related

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

ToolDescription
wrap_callExecute HTTP call with retry + circuit breaker
circuit_statusCheck health of any target
circuit_resetReset circuit breaker after fixing issues
metricsSuccess rates, latency, top errors
recent_errorsRecent failures with full details
Proxy Mode Adds
ToolDescription
selfheal_metricsMetrics for all proxied calls
selfheal_circuitsCircuit status for all targets
selfheal_recent_errorsRecent errors across all targets

Configuration

Environment Variables
VariableDefaultDescription
SELFHEAL_CONFIG./selfheal.config.jsonConfig file path
SELFHEAL_MAX_RETRIES3Max retry attempts
SELFHEAL_BASE_DELAY_MS1000Base delay for backoff
SELFHEAL_MAX_DELAY_MS30000Max delay cap
SELFHEAL_CIRCUIT_THRESHOLD5Failures before circuit opens
SELFHEAL_CIRCUIT_COOLDOWN_MS120000Cooldown before half-open test

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

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

Frequently asked questions

What is SelfHeal MCP?

Self-healing proxy for MCP servers with retry, circuit breaker, and observability

How do I install SelfHeal MCP?

It runs on your machine. In Claude Code: claude mcp add selfheal-mcp -e 'SELFHEAL_CONFIG=<SELFHEAL_CONFIG>' -e 'SELFHEAL_MAX_RETRIES=<SELFHEAL_MAX_RETRIES>' -e 'SELFHEAL_CIRCUIT_THRESHOLD=<SELFHEAL_CIRCUIT_THRESHOLD>' -- npx -y selfheal-mcp@0.1.1. For other clients, paste the JSON configuration from this page into their MCP settings.

Does SelfHeal MCP need an API key?

Its registry entry lists no required key or secret. Some features may still need an account with the service it connects to.

Is SelfHeal MCP open source?

Its code is public on GitHub, but the repository does not declare a standard license.

Who maintains SelfHeal MCP?

It is published by carsonroell-debug. AI.tn lists it but does not maintain or endorse it.

From the official MCP Registry. Listing is not an endorsement: review a server's code and permissions before giving it access to your data.