predictable-mcp

MCP server for Predictable — unified prediction market data and ICM convergence signals across 7+ exchanges (Polymarket, Kalshi, Manifold, Metaculus, Limitless, Probable, Myriad).

Primary surface for AI agents (Claude Desktop, Cursor, Cline, ChatGPT Apps, custom MCP clients). The REST API at api.predictable.dev is the secondary surface for non-agent customers.

Status: v0.2.0 — 8 tools with live handlers wired to @eu-predictions/odds-aggregator (pmxt) + @eu-predictions/markets (ICM convergence). Premium tools (get_brier_leaderboard, backtest_signal) gate on PREDICTABLE_API_KEY; the Brier leaderboard's historical DB lands in v0.3.

Transport

This server uses Streamable HTTP (the MCP 2026 transport). The older SSE transport is deprecated.

Tools

| Tool | Tier | Description | |---|---|---| | list_markets | Free | Search and list markets across 7 exchanges, cursor paginated | | get_market | Free | Full market detail, optional orderbook + history | | get_calibration_score | Free | ICM convergence + component breakdown across exchanges | | get_convergence_alerts | Free | Cross-exchange divergence alerts above a basis-point threshold (the moat) | | get_event_weighted_consensus | Free | Volume-/liquidity-/equal-weighted cross-exchange consensus probability | | map_news_to_markets | Free | Map a headline to the top-K affected markets via term overlap | | get_brier_leaderboard | Premium | Historical Brier calibration ranking by exchange × category (requires PREDICTABLE_API_KEY) | | backtest_signal | Premium | Replay momentum / mean-reversion / threshold strategies on OHLCV (requires PREDICTABLE_API_KEY) |

All tools declare outputSchema so hosts can render structured UI, and carry readOnlyHint: true / idempotentHint: true annotations.

TOS safety: every tool is an intelligence-layer derivation (convergence, alerts, consensus, Brier, backtests). We do not redistribute raw exchange orderbooks or resolution feeds, consistent with Kalshi Data TOS and similar.

Install (end user)

Claude Desktop / Cursor / Cline

Add to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "predictable": {
      "type": "url",
      "url": "https://mcp.predictable.dev/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_PREDICTABLE_API_KEY>"
      }
    }
  }
}

For local development:

{
  "mcpServers": {
    "predictable": {
      "type": "url",
      "url": "http://127.0.0.1:3333/mcp"
    }
  }
}

npm (once published)

npx predictable-mcp

Develop (this repo)

pnpm install
pnpm --filter predictable-mcp dev        # tsx watch mode
pnpm --filter predictable-mcp build      # emit dist/
pnpm --filter predictable-mcp typecheck  # strict TS check
pnpm --filter predictable-mcp inspect    # MCP inspector UI

Configuration (env vars)

| Variable | Default | Purpose | |---|---|---| | PREDICTABLE_API_URL | https://api.predictable.dev/v1 | Backend REST base URL | | PREDICTABLE_API_KEY | — | Bearer token for authenticated / premium tier | | MCP_HTTP_PORT | 3333 | HTTP listen port | | MCP_HTTP_HOST | 127.0.0.1 | HTTP listen host |

Never commit secrets. Use .env.local (git-ignored) or the host process environment.

Architecture

AI agent (Claude / Cursor / Cline / ChatGPT)
   └── MCP Streamable HTTP  →  predictable-mcp
                                    ├── list_markets           → REST  /v1/markets/list
                                    ├── get_market             → REST  /v1/markets/get
                                    └── get_calibration_score  → REST  /v1/markets/calibration
                                                                     └── packages/icm + convergence-scoring

The MCP server is a thin transport+schema layer. All business logic stays in packages/odds-aggregator (pmxt adapters for 7 exchanges) and packages/icm (convergence engine). The web app, enterprise dashboards, and MCP server all call the same REST backend.

Roadmap

• v0.1.0 — scaffold: Streamable HTTP transport, 3 tool stubs, input+output schemas, annotations
• v0.2.0 (this release) — 8 tools with live handlers (3 core + 5 intelligence-layer), wired to @eu-predictions/odds-aggregator (pmxt) + @eu-predictions/markets (ICM convergence). Premium tools gate on PREDICTABLE_API_KEY.
• v0.3.0 — historical resolution feed for get_brier_leaderboard, audit logging, rate limiting
• v0.4.0 — Smithery + Glama listings, install guides for Cline / ChatGPT Apps
• v0.5.0 — x402 pay-per-call rail (reuse OraClaw pattern), publish to npm + MCP registry
• v1.0.0 — Enterprise tier with SLA, SSO, dedicated rate limits

Publish (once v0.5+)

1. pnpm --filter predictable-mcp build
2. npm publish (public or org scope)
3. mcp-publisher login && mcp-publisher publish (JWT expires ~24h, repeat each release)
4. Submit to the 5+ owned awesome-mcp-* directories (zero-budget distribution)

License

UNLICENSED — private source. Public distribution TBD at v1.0.