isocast-mcp

isocast-mcp

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

• 5 free tools — no wallet, no API key.
• 4 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 onthe corresponding Polymarket market — the moment the market's implied outcome moves fromone 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, get_spot.

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

Paid / keyed tools

Pricing

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

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

Single latest signal: get_spot is a flat $0.01 USDC per call — one snapshot of acity's latest signal (never history). It is a plain x402 pay-per-call, not a bundle, so itcarries no receipt token and needs no binding nonce.

How payments work (x402)

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

1. POST /v1/subscribe?city=…&count=… with no payment → the API replies HTTP 402with 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 thepayment attached.
3. On success the API returns your paidThroughSeq, a 24h receiptToken, and thesettlement txHash. The receipt is cached so poll_signals can read your bundlewithout re-paying.

The binding nonce (important)

Isocast is anti-grief: the EIP-3009 authorization nonce is not random — it is boundto (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 exactnonce before settling — so a stock x402 client that sends a random nonce isrejected. isocast-mcp computes the binding nonce for you automatically; you neverhave to think about it.

The binding nonce applies only to bundle purchases (buy_signals / /v1/subscribe).get_spot (GET /v1/spot) is a stock x402 call with no binding nonce — anystandard x402 client can pay it, and this MCP settles it with the vanilla@x402/fetch flow.

Environment variables

Disclaimer

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

License

MIT © jcislo