# refinex-mcp

MCP server for [RefineX](https://www.refinex.io) — AWS spot price arbitrage signals with deterministic confidence scoring, delivered as MCP tools for Claude Code and Cursor.

```bash
pip install refinex-mcp
```

## What it does

RefineX monitors AWS spot prices across 5 regions and surfaces arbitrage opportunities as structured signals. This MCP server wraps the RefineX REST API so you can query live spot data directly inside Claude Code or any MCP-compatible AI tool.

```
get_live_signal → buy_spot c6i.xlarge us-west-2b $0.0626 spot vs $0.17 on-demand (63% discount, confidence 0.72)
```

119 signals detected, 118 suppressed. Only the best one fires.

## Tools

### No API key required

| Tool | Description |
|------|-------------|
| `get_live_signal` | Single best active spot arbitrage signal right now |
| `get_suppression_log` | Mix of delivered + suppressed signals — shows what was held back and why |
| `get_health` | API health + last AWS data ingestion timestamp |

### Requires `REFINEX_API_KEY`

| Tool | Description |
|------|-------------|
| `list_signals` | Paginated list of active signals with filters (cloud, region, instance type, confidence) |
| `get_signal_for_instance` | Best action for a specific cloud/region/instance — built for autoscalers |
| `get_signals_summary` | Aggregate: total opportunities, avg savings %, top instance types by cloud |

## Setup

### Claude Code

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "refinex": {
      "command": "refinex-mcp",
      "env": {
        "REFINEX_API_KEY": "your-key-here"
      }
    }
  }
}
```

No API key? `get_live_signal` and `get_suppression_log` work without one.

### Cursor / other MCP clients

```json
{
  "mcp": {
    "servers": {
      "refinex": {
        "command": "refinex-mcp",
        "env": {
          "REFINEX_API_KEY": "your-key-here"
        }
      }
    }
  }
}
```

## Example responses

### `get_live_signal` (no auth)

```json
{
  "action": "buy_spot",
  "cloud": "aws",
  "region": "us-west-2",
  "availability_zone": "us-west-2b",
  "instance_type": "c6i.xlarge",
  "spot_price_usd": 0.0626,
  "on_demand_price_usd": 0.17,
  "discount_pct": 63.18,
  "confidence": 0.72,
  "ttl_minutes": 28,
  "suppressed_last_6h": 119,
  "signal_id": "e12d4faf-750c-4f4c-933b-260364e47f2f"
}
```

### `get_suppression_log` (no auth)

```json
{
  "signals": [...],
  "count": 20,
  "delivered": 3,
  "suppressed": 17,
  "suppression_rate": 85.0
}
```

High suppression rate is intentional. RefineX fires fewer, better signals.

### `get_signal_for_instance` (API key required)

```json
{
  "action": "buy_spot",
  "signal": {
    "source": { "cloud": "aws", "region": "us-east-1", "availability_zone": "us-east-1a" },
    "asset": { "instance_type": "m6i.large", "current_spot_price": 0.034, "on_demand_price": 0.096 },
    "confidence": 0.85,
    "ttl": 600
  },
  "alternatives": [
    { "availability_zone": "us-east-1b", "current_spot_price": 0.038, "confidence": 0.79 }
  ]
}
```

## Environment variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `REFINEX_API_KEY` | For authenticated tools | — | Your RefineX API key |
| `REFINEX_API_BASE_URL` | No | `https://refinex-api.onrender.com` | Override for self-hosted |

## Signal anatomy

- **confidence**: 0.0–1.0, deterministic — computed from price history, volatility, and AZ spread. No LLM scoring.
- **action**: `buy_spot` / `migrate_spot` / `wait` / `use_on_demand`
- **ttl_minutes**: how long the signal is valid. Treat it as stale after expiry.
- **suppressed_last_6h**: signals detected but not delivered. Suppression is a feature, not a gap.

## Get an API key

Early Access is free for 90 days: [refinex.io](https://www.refinex.io)

## Links

- Website: [refinex.io](https://www.refinex.io)
- Live signal: [refinex-api.onrender.com/v1/signals/now](https://refinex-api.onrender.com/v1/signals/now)
- Suppression log: [refinex.io/transparency](https://www.refinex.io/transparency)
- API docs: [refinex-api.onrender.com/docs](https://refinex-api.onrender.com/docs)