cuporacle-mcp

The missing World Cup MCP server. One npx line adds FIFA World Cup 2026 awareness to any MCP harness — fixtures, live scores, consensus odds, the knockout bracket — and a wc_edge tool that pays x402 itself on Injective, under a spend cap, then cites the on-chain receipt.

cuporacle-mcp is a standalone Model Context Protocol server: 8 tools + 2 resources + 1 prompt over stdio. Free data tools work out of the box; wc_edge is a reference implementation of an agent buying and proving its own alpha keylessly via Injective's x402.

# Claude Code
claude mcp add cuporacle -- npx -y cuporacle-mcp

Why this exists

Agents have no first-class sports capability. Injective's own MCP server covers wallets, markets, CCTP and trading — but an agent asked "is tonight's match worth a bet?" has to hallucinate or scrape, and there's no pattern for an agent paying for premium data itself. CupOracle is that missing layer, built as a composable server that runs side by side with the Injective MCP server.

Related MCP server: ScoutAgent

Tools

Resources: wc://bracket, wc://ledger · Prompt: analyze-match(matchId).

Quickstart

1. Get keys

• football-data.org free tier → FOOTBALL_DATA_KEY

• the-odds-api.com free tier → ODDS_API_KEY

The four free data tools work with just these two keys. wc_edge additionally needs a payer wallet (see Funding).

2. Add to your harness

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "cuporacle": {
      "command": "npx",
      "args": ["-y", "cuporacle-mcp"],
      "env": {
        "FOOTBALL_DATA_KEY": "…",
        "ODDS_API_KEY": "…",
        "CUPORACLE_PRIVATE_KEY": "0x…",
        "CUPORACLE_MAX_SPEND": "0.50"
      }
    }
  }
}

Claude Code:

claude mcp add cuporacle \
  -e FOOTBALL_DATA_KEY=… -e ODDS_API_KEY=… \
  -e CUPORACLE_PRIVATE_KEY=0x… -e CUPORACLE_MAX_SPEND=0.50 \
  -- npx -y cuporacle-mcp

Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "cuporacle": { "command": "npx", "args": ["-y", "cuporacle-mcp"],
      "env": { "FOOTBALL_DATA_KEY": "…", "ODDS_API_KEY": "…" } }
  }
}

3. Ask

"What's tonight's Semi-Final, and is it worth a bet?"

The assistant lists the fixture (wc_fixtures), pulls odds (wc_odds), buys a vetted edge for ~5¢ (wc_edge) paying via x402 itself, and cites the receipt. Paste that hash into receipt_verify to confirm the payment on Injective.

Injective technologies used

CupOracle is Injective-native by construction — remove any layer and it's just a scraper or a hosted API with a billing page.

Interop, not wrap. CupOracle does not reimplement chain ops or wrap the Injective MCP tools as its own — both servers run in the same harness and the Skill routes funding to Injective's tools. Honesty over land-grab.

The autonomous-payment loop (wc_edge)

POST /api/edge  ──▶  402 { accepts: [{ network: eip155:1776, amount: 50000, asset: USDC, payTo }] }
      │
      ├─ spend-cap gate  (per-call max · per-session cap · "ask human above cap")
      ├─ sign EIP-3009 authorization  (local viem signTypedData — no broadcast)
      ├─ retry with PAYMENT-SIGNATURE header
      ▼
200 { edge, ladder, pick_hash }  +  PAYMENT-RESPONSE { transaction: 0x… }
      │
      ▼   agent cites receipt_tx  ──▶  receipt_verify(0x…)  ──▶  block time + amount on Injective

Spending is auditable in-conversation via wc_spend_ledger (and wc://ledger). Failures teach: INSUFFICIENT_USDC carries the CCTP runbook; SPEND_CAP_HIT carries the cap and how to raise it (ask the human — the agent never raises its own).

Funding the agent wallet

wc_edge needs a few cents of USDC on Injective. Generate a throwaway payer wallet and fund it via CCTP:

npx cuporacle-mcp init          # prints a fresh wallet address + key

Then call wallet_fund_guide (or ask your agent to) for the CCTP steps, executed with the Injective MCP server: account_balances → cctp_supported_chains → burn on Base (domain 6) → cctp_attestation_status → cctp_mint. Fund only cents; the default cap is 0.50 USDC.

Development

npm install
npm run smoke      # cold-start over stdio, list 8 tools/2 resources/1 prompt, one live call
npm test           # 63 vitest (schemas, spend cap, 402-parse, EIP-3009 sign, receipts, degrade)
npm run bench      # cache hit/miss + wc_edge dry_run (parse+sign) p50/p95
npm run build      # tsup → dist (publish-ready)
SMOKE_BIN=dist npm run smoke   # smoke the built artifact

npm run paid-call-smoke runs a real paid wc_edge end-to-end — it is funds-gated behind CUPORACLE_ALLOW_PAID=1 and a funded key, and otherwise falls back to a dry run.

Configuration

Extend it (add your own sport)

Each tool is { name, config, handler } (src/tools/). To add, say, a cricket server: copy a free tool, swap the data client in src/data/, register it in src/tools/index.ts. The x402 client (src/x402/) is sport-agnostic — reuse it to sell any premium signal. PRs welcome.

Honest limitations

1. wc_edge depends on EdgeLedger's /api/edge (a disclosed sibling project). If it's down, wc_edge degrades to free odds — it never fabricates an edge.

2. Free-tier data APIs cap request rates → 60s cache + committed snapshots (always labeled [snapshot]).

3. The payer keystore holds a real (tiny) balance. Spend caps default low; fund only cents. Windows keystore paths are documented, not hardened.

License

MIT. "Football data provided by the Football-Data.org API."