Resolve Mcp

Resolve MCP Server

[](https://pypi.org/project/resolve-mcp/) [](https://python.org) [](LICENSE) [](https://modelcontextprotocol.io)

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

pip install resolve-mcp

Or run directly with uvx (no install needed):

uvx resolve-mcp

2. Get a free API key

From your terminal:

curl -s -X POST https://resolve.arflow.io/billing/free-key \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com"}' | jq -r .api_key

Or call the get_free_key tool from within your MCP client -- no terminal needed.

3. Configure your client

Claude Code

claude mcp add resolve -e RESOLVE_API_KEY=rsl_your_key -- python -m resolve_mcp

Or add to .claude/settings.json:

{
  "mcpServers": {
    "resolve": {
      "command": "python",
      "args": ["-m", "resolve_mcp"],
      "env": {
        "RESOLVE_API_KEY": "rsl_your_key_here"
      }
    }
  }
}

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "resolve": {
      "command": "python",
      "args": ["-m", "resolve_mcp"],
      "env": {
        "RESOLVE_API_KEY": "rsl_your_key_here"
      }
    }
  }
}

Cursor / Windsurf / any MCP client

{
  "resolve": {
    "command": "python",
    "args": ["-m", "resolve_mcp"],
    "env": {
      "RESOLVE_API_KEY": "rsl_your_key_here"
    }
  }
}

Standalone (stdio)

RESOLVE_API_KEY=rsl_your_key python -m resolve_mcp

Usage examples

Agent hits a rate limit:

Agent: "I got a 429 from OpenAI"
-> resolve_error(service="openai", error_code="429")

Returns:
{
  "category": "rate_limit",
  "action": "backoff_and_retry",
  "backoff_schedule": [1, 2, 4, 8, 16],
  "max_retries": 5,
  "notes": "Token-per-minute limit. Reduce batch size or switch to a higher-tier key.",
  "confidence": 0.95
}

Agent gets an auth failure:

Agent: "Stripe returned authentication_error"
-> resolve_error(service="stripe", error_code="authentication_error")

Returns:
{
  "category": "auth",
  "action": "check_credentials",
  "backoff_schedule": [],
  "max_retries": 0,
  "notes": "API key is invalid or revoked. Verify the key starts with sk_live_ or sk_test_. Check Stripe dashboard for key status.",
  "confidence": 0.92
}

Feedback loop:

Agent: "The resolution worked."
-> submit_feedback(resolution_id="3fa85f64-...", helpful=true)

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.

API

The MCP server wraps the Resolve REST API:

| Endpoint | Method | Auth required | |---|---|---| | /resolve | POST | Yes | | /services | GET | No | | /resolve/feedback | POST | Yes | | /billing/free-key | POST | No |

Full OpenAPI spec: resolve.arflow.io/openapi.json

Pricing

| Plan | Requests/month | Price | |---|---|---| | Free | 500 | $0 | | Pro | 50,000 | $29/mo | | Fleet | 500,000 | $99/mo |

Get started free: resolve.arflow.io

Contributing

Issues and PRs welcome. If you want resolution data for a service we don't cover yet, open an issue with the service name and common error codes.

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: unitedideas
• Source: unitedideas/resolve-mcp
• License: MIT
• Homepage: https://resolve.arflow.io

Install and usage instructions live in the source repository linked above.