refinex-mcp

MCP server for RefineX — AWS spot price arbitrage signals with deterministic confidence scoring, delivered as MCP tools for Claude Code and Cursor.

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:

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

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

Example responses

get_live_signal (no auth)

{
  "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)

{
  "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)

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

Links

• Website: refinex.io
• Live signal: refinex-api.onrender.com/v1/signals/now
• Suppression log: refinex.io/transparency
• API docs: refinex-api.onrender.com/docs