{
  "markdown": "# SelfHeal MCP\n\n[![npm](https://img.shields.io/npm/v/selfheal-mcp)](https://www.npmjs.com/package/selfheal-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![MCPize](https://img.shields.io/badge/MCPize-Install-0ea5e9)](https://mcpize.com/mcp/selfheal-mcp)\n\nSelf-healing proxy for MCP servers. Wraps any MCP tool call with automatic retry, circuit breaker protection, and call observability.\n\n**Your AI agents stop breaking on flaky APIs.**\n\n> **One-click install:** [Install on MCPize](https://mcpize.com/mcp/selfheal-mcp) | `npx selfheal-mcp`\n\n## Features\n\n- **Retry with backoff** — Exponential backoff + jitter on transient failures (5xx, timeouts, rate limits)\n- **Circuit breaker** — Per-target circuit breaker stops hammering dead services\n- **Call metrics** — Success rates, latency, error frequency, broken down by tool and target\n- **Proxy mode** — Wrap any existing MCP server transparently\n- **Zero config** — Works standalone out of the box, config file for proxy mode\n\n## Quick Start\n\n### Standalone Mode\n\nAdd to your Claude Desktop / Claude Code config:\n\n```json\n{\n  \"mcpServers\": {\n    \"selfheal\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"selfheal-mcp\"]\n    }\n  }\n}\n```\n\nThen use `wrap_call` to make any HTTP request with self-healing:\n\n```\nUse the wrap_call tool to GET https://api.example.com/data with target \"example-api\"\n```\n\n### Proxy Mode\n\nCreate `selfheal.config.json`:\n\n```json\n{\n  \"mode\": \"proxy\",\n  \"targets\": [\n    {\n      \"name\": \"my-server\",\n      \"transport\": \"streamable-http\",\n      \"url\": \"https://my-mcp-server.com/mcp\"\n    }\n  ]\n}\n```\n\n```json\n{\n  \"mcpServers\": {\n    \"selfheal\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"selfheal-mcp\"],\n      \"env\": {\n        \"SELFHEAL_CONFIG\": \"/path/to/selfheal.config.json\"\n      }\n    }\n  }\n}\n```\n\nAll tools from `my-server` are re-exposed with self-healing built in.\n\n## Tools\n\n| Tool | Description |\n|------|-------------|\n| `wrap_call` | Execute HTTP call with retry + circuit breaker |\n| `circuit_status` | Check health of any target |\n| `circuit_reset` | Reset circuit breaker after fixing issues |\n| `metrics` | Success rates, latency, top errors |\n| `recent_errors` | Recent failures with full details |\n\n### Proxy Mode Adds\n\n| Tool | Description |\n|------|-------------|\n| `selfheal_metrics` | Metrics for all proxied calls |\n| `selfheal_circuits` | Circuit status for all targets |\n| `selfheal_recent_errors` | Recent errors across all targets |\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `SELFHEAL_CONFIG` | `./selfheal.config.json` | Config file path |\n| `SELFHEAL_MAX_RETRIES` | `3` | Max retry attempts |\n| `SELFHEAL_BASE_DELAY_MS` | `1000` | Base delay for backoff |\n| `SELFHEAL_MAX_DELAY_MS` | `30000` | Max delay cap |\n| `SELFHEAL_CIRCUIT_THRESHOLD` | `5` | Failures before circuit opens |\n| `SELFHEAL_CIRCUIT_COOLDOWN_MS` | `120000` | Cooldown before half-open test |\n\n## How It Works\n\n```\nAgent → SelfHeal MCP → [Retry + Circuit Breaker] → Target API/MCP Server\n                ↓\n          Metrics Collector\n```\n\n1. **Request arrives** — Agent calls a tool\n2. **Circuit check** — If target has failed too many times, reject immediately\n3. **Execute with retry** — Try the call, retry on transient errors with exponential backoff\n4. **Record metrics** — Log success/failure, duration, attempts\n5. **Update circuit** — Track consecutive failures per target\n\n## Install\n\n### MCPize (Recommended)\n\nOne-click install with managed hosting: **[Install on MCPize](https://mcpize.com/mcp/selfheal-mcp)**\n\n### npm\n\n```bash\nnpx selfheal-mcp\n```\n\n### PyPI\n\nNot applicable — this is a TypeScript server. For Python alternatives, see [LeadEnrich MCP](https://mcpize.com/mcp/leadenrich-mcp).\n\n## License\n\nMIT — Built by [Freedom Engineers](https://freedomengineers.tech)\n\n## Related\n\n- [SiteHealth MCP](https://mcpize.com/mcp/sitehealth-mcp) — Full website health audit\n- [LeadEnrich MCP](https://mcpize.com/mcp/leadenrich-mcp) — Waterfall lead enrichment\n",
  "bytes": 4090,
  "sha": "e8e6bef4832689d94ef12abe2ff25a972787f902562738761d46dc675bee0903",
  "repo_slug": "carsonroell-debug/selfheal-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_carsonroell_debug_selfheal_mcp_1cba9240/readme"
}