isocast-mcp

MCP server for Isocast — Polymarket weather-market bucket-transition signals for AI agents. Discover cities and inspect the signal shape for free; buy prepaid signal bundles with USDC on Base via x402, poll the signals you are entitled to, and register Telegram push delivery.

• 5 free tools — no wallet, no API key.
• 3 paid/keyed tools — unlocked by an EVM_PRIVATE_KEY (USDC on Base Mainnet for purchases).

An Isocast signal fires when a city's expected daily-high temperature bucket flips on the corresponding Polymarket market — the moment the market's implied outcome moves from one bucket to the next.

Quick start

Free tier (no wallet)

{
  "mcpServers": {
    "isocast": {
      "command": "npx",
      "args": ["-y", "isocast-mcp"]
    }
  }
}

You get get_health, get_cities, get_city, get_sample_signal, get_signal_meta.

Paid tier (with wallet)

Add an EVM wallet private key (0x-prefixed) that holds USDC on Base Mainnet:

{
  "mcpServers": {
    "isocast": {
      "command": "npx",
      "args": ["-y", "isocast-mcp"],
      "env": { "EVM_PRIVATE_KEY": "0x..." }
    }
  }
}

This additionally unlocks buy_signals, poll_signals, set_telegram.

Install snippets

Claude Code:

claude mcp add isocast -- npx -y isocast-mcp
# with a wallet:
claude mcp add isocast --env EVM_PRIVATE_KEY=0x... -- npx -y isocast-mcp

Claude Desktop / Cursor: add the JSON block above to your MCP config (claude_desktop_config.json or .cursor/mcp.json).

Tools

Free tools

| Tool | Description | | --- | --- | | get_health | Isocast API health, payment mode, OFAC status + signal freshness. | | get_cities | List every active city (slug, unit, timezone, station, latest signal seq). | | get_city | One city by slug, with its current target market day + Polymarket URL. | | get_sample_signal | A free real sample signal for a city (fixed seq-1, never the latest; cross-city fallback via sampleNote) — shows the exact signal shape. | | get_signal_meta | Pricing + payment metadata: unit price, min spend, network, payTo, tier table. |

Paid / keyed tools

| Tool | Description | Cost | | --- | --- | --- | | buy_signals | Buy the next N signals for a city (by count or spend_usdc). | USDC via x402 | | poll_signals | Read the signals you are entitled to, using a bundle receipt. | free (uses receipt) | | set_telegram | Register/delete the Telegram chat_id that receives your signals. | free (signed intent) |

Pricing

Signals are sold in prepaid bundles. The effective unit price drops as the requested count crosses volume tiers (live values come from get_signal_meta):

| Tier | Min count | Unit price (USDC) | | --- | --- | --- | | Min | 2 | $0.005 | | Starter | 20 | $0.005 | | Standard | 100 | $0.0045 | | Pro | 500 | $0.004 | | Whale | 2000 | $0.0035 |

Minimum spend: $0.01 (i.e. 2 signals). buy_signals with spend_usdc derives the count from these tiers and refuses a spend that cannot meet the minimum.

How payments work (x402)

buy_signals speaks the x402 exact scheme over EIP-3009 transferWithAuthorization on Base:

1. POST /v1/subscribe?city=…&count=… with no payment → the API replies HTTP 402 with the accepted payment terms (accepts[]: amount in USDC atomic units, payTo, network) and an extra.binding block.
2. The MCP constructs a signed USDC authorization and retries the request with the payment attached.
3. On success the API returns your paidThroughSeq, a 24h receiptToken, and the settlement txHash. The receipt is cached so poll_signals can read your bundle without re-paying.

The binding nonce (important)

Isocast is anti-grief: the EIP-3009 authorization nonce is not random — it is bound to (payer, citySlug, count):

nonce = keccak256(abi.encodePacked(payer, citySlug, uint256 count, bytes32 salt))

The 402 challenge publishes the salt, and the server recomputes and verifies this exact nonce before settling — so a stock x402 client that sends a random nonce is rejected. isocast-mcp computes the binding nonce for you automatically; you never have to think about it.

Environment variables

| Variable | Required | Description | | --- | --- | --- | | EVM_PRIVATE_KEY | No | 0x-prefixed wallet key with USDC on Base Mainnet. Enables the paid/keyed tools. Free tools work without it. | | ISOCAST_API_URL | No | Override the API base URL (default https://api.isocast.dev). |

Disclaimer

Isocast provides informational data only. It is not financial, trading, or betting advice, and there is no guarantee of accuracy or of any market outcome. You assume all risk for any decisions you make. Prediction markets are restricted or prohibited in some jurisdictions — it is your responsibility to comply with the laws that apply to you. See https://isocast.dev/terms.

License

MIT © jcislo