SelfHeal MCP

io.github.carsonroell-debugPublished by GitHub account carsonroell-debugv0.1.1Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyCloud & InfrastructureDeveloper ToolsSecurity & Monitoring

Overview

AI-generated overview

A local MCP proxy that wraps HTTP calls and other MCP servers with automatic retry, circuit breaking and call metrics.

What you can do
  • Make HTTP requests through a self-healing wrapper with retry and circuit breaker protection
  • Check circuit health for a target and reset a circuit after fixing the underlying issue
  • Read success rates, latency and top errors, and inspect recent failures in detail
  • In proxy mode, re-expose all tools of a configured MCP server with the same retry, circuit and metrics layer
When to use it
Useful when an assistant depends on flaky or rate-limited APIs or MCP servers and you want retries, backoff and failure isolation without changing the underlying tools. Also handy for getting per-tool success and latency figures on those calls.
Requirements
Runs locally over stdio, typically started with npx selfheal-mcp, so Node.js is needed. Proxy mode requires a selfheal.config.json listing target servers, pointed to by SELFHEAL_CONFIG. Optional tuning variables include SELFHEAL_MAX_RETRIES and SELFHEAL_CIRCUIT_THRESHOLD. No authentication is declared.
Before you install
The wrap_call tool performs outbound HTTP requests chosen by the assistant, so any URL and payload it is given will be sent to that third party. Proxy mode forwards calls to the configured target servers. Retries can repeat non-idempotent requests, so writes may be executed more than once.

Installation

In SourceWeft

  1. Open SelfHeal MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

SelfHeal MCP

[npm] [License: MIT] [MCPize]

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:

json
{  "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:

json
{  "mode": "proxy",  "targets": [    {      "name": "my-server",      "transport": "streamable-http",      "url": "https://my-mcp-server.com/mcp"    }  ]}
json
{  "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

MCPize (Recommended)

One-click install with managed hosting: Install on MCPize

npm

bash
npx selfheal-mcp

PyPI

Not applicable — this is a TypeScript server. For Python alternatives, see LeadEnrich MCP.

License

MIT — Built by Freedom Engineers

Related

Source: README.md at commit cb405ae

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.1LatestSep 16, 2026

Score

40% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts

    Declare a license in the repository or the registry entry.