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.

• 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 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, 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).

Related MCP server: polymarket-gateway-core

Tools

Free tools

Paid / keyed tools

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):

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.

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

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.

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 — any standard 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 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