unitedideas/resolve-mcp

Structured error recovery for AI agents. When your agent hits a 429, a connection timeout, or an auth failure, Resolve returns a resolution playbook -- not a generic error message.
Works with Claude Code, Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.
The problem
AI agents crash on API errors they could recover from. A 429 Too Many Requests from OpenAI needs exponential backoff. A Stripe authentication_error needs credential rotation. A Postgres ECONNREFUSED needs a connection pool reset. But agents don't know any of this -- they either retry blindly or give up.
The solution
Resolve provides structured resolution playbooks for 20+ services. Each resolution includes:
- **Category** -- rate_limit, auth, payment, connection, timeout, server_error, overloaded, quota, validation, and more
- **Action** -- backoff_and_retry, abort, check_credentials, switch_region, etc.
- **Backoff schedule** -- exact delays in seconds (e.g., [1, 2, 4, 8, 16])
- **Max retries** -- how many attempts before giving up
- **Recovery notes** -- specific steps for the service and error code
- **Confidence score** -- below 0.75 means generic fallback; above means high-confidence match
Tools
| Tool | Description |
|---|---|
| resolve_error | Look up a resolution for a service + error code/message. Returns structured playbook. |
| list_services | List all 20+ supported services. No API key required. |
| submit_feedback | Report whether a resolution helped. Improves quality over time. |
| get_free_key | Provision a free API key (500 req/month) with just an email. |
Supported services
anthropic aws cloudflare discord docker gemini github huggingface linear openai opensrs pinecone postgres redis resend sendgrid shopify stripe supabase twilio
Quick start
1. Install
Or run directly with uvx (no install needed):
2. Get a free API key
From your terminal:
Or call the get_free_key tool from within your MCP client -- no terminal needed.
3. Configure your client
Claude Code
Or add to .claude/settings.json:
Claude Desktop
Add to your claude_desktop_config.json:
Cursor / Windsurf / any MCP client
Standalone (stdio)
Usage examples
**Agent hits a rate limit:**
**Agent gets an auth failure:**
**Feedback loop:**
Why not just hardcode retry logic?
You can. But then you maintain retry strategies for every service your agent calls, across every error code, and update them when services change their rate limit behavior. Resolve centralizes this so your agent code stays clean and the resolution data stays current.