predmarket-mcp

A monetizable remote MCP server that sells prediction-market intelligence (Polymarket, Kalshi) as tools other AI agents call — and pay for — per call. Not another bot: rails. Normalized data, mispricing detection, and honest realizable edge (after fees/gas/slippage), packaged as tools an agent can lean on instead of building itself.

The server is a thin wrapper over a core/ engine (matcher, signals, realizable-edge, storage). It returns intelligence only — it never executes trades or holds funds.

Engine status. Two interchangeable engines share one surface, selected by CORE_ENGINE (the MCP layer never changes either way):

• mock (default) — realistic, same-signature stubs (core/mock.py) so the server works end-to-end offline.

• live — real Polymarket + Kalshi adapters (core/adapters/) feeding a live engine (core/live.py). Needs network access to the venue APIs; falls back gracefully (empty results) if a venue is unreachable.

The shared intelligence (matcher, signals, realizable-edge) lives in core/algorithms.py and is used by both engines — not duplicated.

Tool catalog (12 tools, 11 resources, 1 prompt)

Descriptions are the agent's only documentation, so they're written as copy. Every response carries freshness (as_of / data_age_seconds) and cost (tier / price_usd).

Free tier (discovery + trust — the funnel)

Paid tier (per-call revenue — realtime)

Prices live in pricing.yaml, never hardcoded.

• Resources: market://{venue}/{market_id} (snapshot), house://{venue}/{market_id} (the server's own fused probability), maker://{venue}/{market_id} (market-maker quote advice), scenario://scan/{spec} (what-if stress test), leaderboard://top (public proof-of-alpha ranking), portfolio://me (your own paper P&L), alerts://me (your queued alerts), plus event://, conditional://, distribution://, outcomes:// — for agents that prefer resources over tools.

• Identity: personal resources are addressed as me and resolved from a derived identity — an OAuth subject, or the payer address of a verified x402 payment. x-client-id is only a namespace hint inside an already-proven identity; it can never select a principal. There is deliberately no URI that names another caller, so cross-tenant reads are impossible by construction rather than by check. Set REQUIRE_PROVEN_IDENTITY=on to refuse personal resources to unauthenticated callers entirely.

• Prompt: arbitrage_scan_workflow(min_edge) — guides an agent scan → confirm → estimate execution → rank.

Related MCP server: Parlay

Quick start

uv sync                                   # Python 3.12, deps
uv run pytest                             # 22 tests, all green
uv run python -m predmarket_mcp.server    # streamable-http on http://0.0.0.0:8000/mcp
curl -s http://127.0.0.1:8000/health      # {"status":"ok",...}

# live data from Polymarket + Kalshi (needs network egress to the venue APIs):
CORE_ENGINE=live uv run python -m predmarket_mcp.server

Verify with the official MCP Inspector (see tests/test_inspector.md):

npx @modelcontextprotocol/inspector       # UI → Streamable HTTP → http://127.0.0.1:8000/mcp

Connecting from a client

Direct HTTP agent (Cursor, LangGraph, any MCP client that speaks Streamable HTTP):

{
  "mcpServers": {
    "predmarket": { "url": "https://your-host/mcp", "transport": "streamable-http" }
  }
}

stdio-only hosts (Claude Desktop / Claude Code) — bridge to the remote server with mcp-remote:

{
  "mcpServers": {
    "predmarket": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-host/mcp"]
    }
  }
}

Monetization

Two rails; x402 is primary, API-key/metering is the fallback. Both are inert until you flip the flag — the server can take money, but doesn't gate at launch (usage first, billing later).

PAID_ENABLED=false   # default: paid tools run free, metering still records usage
PAID_ENABLED=true    # enforce the gate on paid tools
PAYMENT_RAIL=x402    # or "apikey" for the OAuth/metering fallback

x402 (agent-native, stablecoin micropayments)

A paid tool call without a signed X-PAYMENT header gets a real HTTP 402 with an x402 challenge (scheme, network, amount, pay-to). Retry with a valid base64-JSON X-PAYMENT header → the Facilitator verifies it, a receipt is logged, and the call is forwarded. Settlement in USDC.

The default MockFacilitator does structural verification and stubs settlement (# TODO: real facilitator/settlement). The 402 flow, gating, and receipt log are real.

Metering (fallback)

Every paid call writes exactly one usage record via a pluggable MeteringBackend. Default is local SQLite (zero infra); StripeBackend / MoesifBackend are typed stubs behind the same interface. OAuth 2.1 for the API-key rail is wired via FastMCP helpers (auth.py), enabled by env.

Configuration (all via env — no secrets in code)

Entailment & term-structure arbitrage (C1) and value-based pricing for get_market_history (scales with range, capped) need no flags — always on.

| v4 — autonomy & product depth | | | | PERSISTENCE_MIN_SAMPLES / EXEC_HORIZON_SECONDS | 20 / 60 | Edge-survival model: ranks find_mispricing by expected value (edge × P(survives the execution window)), learned from opportunity lifespans. | | QUALITY_GATE / QUALITY_MIN | off / 0.5 | Quote-quality guard: skip scans on stale/thin/crossed quotes. Advisory (surfaced in evaluate_market) unless the gate is on. | | ADMIN_TOKEN | — | Enables the operator-only GET /revenue (charged-vs-settled reconciliation); sent as X-Admin-Token. | | ALERT_WEBHOOK_SECRET (reuse) | — | Now also HMAC-signs the webhook body (X-Signature: sha256=…). |

New surfaces: free event://{entity} resource (the whole market structure for a subject: related markets, implies/same_event/term_neighbor relations, transitive entailment violations, term structures); paid assess_portfolio tool (net exposure, correlation, portfolio Kelly, hedges); simulate_strategy now includes an out-of-sample walk-forward check.

Quality & provable evidence (J): every find_mispricing opportunity carries an adverse block — a trap_score (informed flow against the position + historical hit-rate of edges of that kind + quote quality) and a trust_adjusted_edge. Pass audit=true for a signed audit bundle per opportunity: inputs, prices, book depth and timestamp, Ed25519-signed and fetchable at public GET /audit/{id} — a buyer independently verifies the edge existed, without trusting our word (the deepest, least-copyable trust primitive).

Capital-velocity strategy (I): find_mispricing prices TIME, not just edge — every opportunity carries velocity metrics (capital_efficiency = EV per locked day, compound_annual_growth under recycling, early-exit liquidity from book depth), rank="velocity" puts the fastest capital turnover first, and passing bankroll_usd + horizon_days returns a rotation_plan: allocations across short-cycle opportunities with a projected compounded bankroll as capital recycles (VELOCITY_DEFAULT_DAYS, ROTATION_MAX_POSITIONS).

Implied distribution & dependency graph (H/J): free distribution://{entity} resource reconstructs the market's whole implied distribution from a threshold ladder (survival curve, percentiles, implied mean, prob at any strike — the prediction-market vol surface) plus a continuous lognormal fit (J2: P(X in [a,b]) for any range, moments, quantiles); free conditional://{event} resource returns market-implied P(A|B) (Gaussian copula from co-movement + exact logical overrides) plus Bayesian belief updates (J3: multi-hop P(A | B,C…) by naive-Bayes log-odds). compare_across_venues adds a calibration-weighted meta_consensus (J4): a best-estimate + credible interval that weights each venue by how accurate it has historically been (Brier), learned as markets resolve — not just liquidity. The cross-venue matcher learns from resolution ground truth — compare_across_venues reports a history-calibrated match confidence, tuned by which past matches actually resolved the same way.

House probability, scenarios & client-sampled rulebooks (K): the server publishes its OWN forecast, not just the market's. evaluate_market and the free house://{venue}/{market_id} resource return a house_probability (K1) that fuses calibration, options-implied, accuracy-weighted consensus and microstructure into one number with a confidence and its edge_vs_market; every forecast is recorded and, when the market resolves, Brier-scored — track_record's house_forecast block reports brier_edge (>0 means the house beats the raw market), a claim no competitor can fake. The free scenario://scan/{spec} resource (K2, e.g. scenario://scan/pm-btc-150k-2026:yes) pins markets to a hypothetical outcome and propagates the consequences across the entity graph — prior → posterior → shift per related market (logical edges exact, copula edges estimated); pass scenario= to assess_portfolio to stress a book under the what-if. And with RULEBOOK_SAMPLING=on, compare_across_venues uses MCP sampling (K3) to ask the calling agent's own model to judge settlement basis risk — the deepest rulebook analysis, run at the client's expense; degrades to the heuristic when the client can't sample.

Agent leaderboard — proof-of-alpha as a service (K4): an agent doesn't just find edge here, it can prove it. Call estimate_execution(commit=true) and the position is logged as a paper trade tagged to you; when the markets resolve it's P&L-scored by the same model as the track record. The free, server-signed leaderboard://top resource ranks agents by REAL, resolution-verified return (handles anonymized; a single lucky trade stays provisional until LEADERBOARD_MIN_RESOLVED), and the caller-scoped portfolio://me resource shows your own trades, rank and realized P&L. The server becomes an independent notary of an agent's performance — a portable, tamper-evident record to show a third party, and the network effect the product was missing.

Market-maker advisor (K5): the other side of the book. Every other tool serves a taker (lift someone's mispricing); the free maker://{venue}/{market_id} resource serves a maker — where to post a two-sided limit quote to earn the spread (recommended_bid/ask, half_spread, skew) and a pull_quotes guard that says step aside when the flow looks informed. It prices adverse-selection risk from microstructure (C8) + quote quality (F7), widening and skewing quotes against informed flow. Intelligence only — it never posts orders.

Reality feeds — the market vs the world (K7): every other signal is intramarket; K7 adds an EXTERNAL anchor. With REALITY_ENABLED=on and a REALITY_NOWCAST_URL feed (a poll aggregator, a macro nowcast, an internal model), evaluate_market reports a reality block — the market's probability vs the real-world nowcast and their divergence ("market says 60%, the data says 45%") — and the reality-implied probability feeds the house forecast (K1) as an independent, heavily-weighted component. The divergence math is pure/offline; the feed is a flag-gated provider (like the Deribit options cross-check) that degrades to nothing when unconfigured.

Native multi-outcome markets (G): free outcomes://{event} resource reconstructs an N-outcome event (election, bracketed number) from its binary markets — de-vigged fair probabilities (margin removed so they sum to 1), the overround, the favorite, and a completeness-aware full dutch book (an over-round set is always arbitrage; an under-round is only free money if the outcome set is complete — flagging otherwise is a false arb the naive path emits). Adapters populate event_group from venue grouping (Polymarket negRisk, Kalshi event ticker).

| Horizontal scaling | | (single-instance defaults need nothing) | | REDIS_URL | — | Shared backend for the x402 replay guard (atomic SET NX) and rate limiter (global fixed-window). Required for correctness behind a load balancer — without it each instance has its own replay set, so one signed payment could buy a call per instance. Degrades to local SQLite/memory if unset or redis isn't installed. | | NONCE_TTL_SECONDS | 2592000 | TTL for consumed-payment fingerprints in Redis (30d). | | PG_POOL_MIN / PG_POOL_MAX | 1 / 10 | asyncpg pool bounds for the Postgres history path. |

Multi-instance deploy: point every instance at the same REDIS_URL (replay + rate limits) and a postgresql:// HISTORY_DB_URL (shared time series). The async asyncpg path runs on a dedicated loop thread so the sync stores are unchanged. Install the extras: --extra redis --extra postgres.

Preflight: validate the live path before launch

Every automated test runs against mocks — the venue adapters normalize a response shape assumed from docs. Real APIs differ, and that gap is the single biggest launch risk. deploy/preflight.py is the check the test suite structurally cannot do: it calls the real venues, pushes what comes back through the actual adapters and the whole pipeline (normalization → matching → claim parsing → scan → execution estimate), and names the link that breaks.

docker compose exec server python deploy/preflight.py          # all venues
docker compose exec server python deploy/preflight.py kalshi   # one venue
docker compose exec server python deploy/preflight.py --json   # for monitoring

Read-only (writes to no store), exits non-zero when the live path is broken, and also audits production config — unsigned provenance, PAID_ENABLED=true with no real facilitator (accepting payments that never settle), a missing RESOLUTION_ENGINE (nothing ever resolves, so calibration / house Brier / leaderboard stay empty forever). Run it before serving traffic.

Deploy

docker build -t predmarket-mcp .
docker run -p 8000:8000 -e PAID_ENABLED=false predmarket-mcp

# with optional features baked in (extras + pre-downloaded embedding weights):
docker build -t predmarket-mcp \
  --build-arg EXTRAS="--extra semantic --extra kalshi --extra postgres" \
  --build-arg WITH_SEMANTIC=true .

Runs on Cloud Run / Container Apps / any container host. Streamable HTTP is serverless-compatible. Terminate TLS and rate-limit at the proxy; use /health for liveness. The container starts via python -m predmarket_mcp.server so the x402 ASGI middleware is wired in (equivalent to fastmcp run + payment gating). WITH_SEMANTIC=true pre-fetches the bge-small weights into the image so the semantic matcher runs with no Hugging Face egress at runtime.

Layout

src/predmarket_mcp/
  server.py     FastMCP app; /health, /metrics, /pubkey, /track-record; HTTP app + middleware
  tools.py      the 11 tools (call core/, format for agents — no logic here)
  resources.py  market:// · house:// · maker:// · scenario:// · leaderboard:// · portfolio://me · alerts://me · event:// · outcomes:// · distribution:// · conditional:// resources
  identity.py   caller identity DERIVED from OAuth / verified x402 payer, never from a header
  multioutcome.py native N-outcome markets: de-vig + complete-set dutch book (G)
  distribution.py implied distribution from a threshold ladder — vol surface (H1)
  conditional.py  market-implied P(A|B): Gaussian copula + logical overrides (H2)
  matchlearn.py   matcher calibrated from resolution ground truth (H5)
  prompts.py    arbitrage_scan_workflow
  config.py     env-driven settings (PAID_ENABLED flag)
  deps.py       the ONLY seam into core/
  provenance.py signed provenance (Ed25519 preferred, HMAC fallback)
  ops.py        metrics registry, token-bucket rate limit, structured logging
  auth.py       OAuth 2.1 fallback wiring
  billing/      tiers.py · metering.py · x402.py · middleware.py
core/
  models.py     canonical pydantic models
  algorithms.py shared matcher / signals / realizable-edge + risk finalize (mock + live reuse)
  entailment.py logical-implication + probability term-structure arbitrage (C1)
  basis.py      resolution-criteria diff / settlement basis risk (C2)
  calibration.py isotonic online probability calibration from history (C3)
  backtest.py   mean-reversion backtester over recorded history (C4)
  options.py    Breeden-Litzenberger options-implied probability, Deribit (C7)
  microstructure.py informed-flow / momentum read from the tape (C8)
  anchor.py     on-chain anchoring of the track-record Merkle root (C6)
  fairvalue.py  liquidity-weighted cross-venue consensus + deviation (B3)
  sizing.py     fractional-Kelly stake + market-impact curve (B4)
  analyst.py    LLM resolution-risk + basis analyst + offline heuristic (B5/C2)
  merkle.py     Merkle commitments/proofs for the track record (B6)
  circuit.py    per-venue circuit breaker (B7)
  streaming.py  WSS price ingestion (B1) · notifier.py  webhook alert push (B2)
  embeddings.py Embedder backends for the semantic matcher tier (fastembed default)
  mock.py       realistic offline engine (default)
  live.py       live engine: adapters + algorithms, TTL-cached, history ingest
  storage.py    price-history store (SQLite default; asyncpg Timescale/PG via DSN)
  pg.py         asyncpg loop-thread bridge for the sync stores (D2)
  reconciliation.py  flag → resolve → realized-edge / hit-rate / Brier + Merkle root
  houseview.py  fuse calibration+options+consensus+microstructure -> house probability (K1)
  houseforecast.py record + Brier-grade the server's own forecasts vs the market (K1)
  scenario.py   what-if propagation across the market graph + portfolio stress (K2)
  rulesample.py client-sampled (MCP sampling) settlement-basis analysis (K3)
  leaderboard.py agent proof-of-alpha: paper trades, P&L, public signed ranking (K4)
  maker.py      market-maker quote advisor + adverse-selection guard (K5)
  reality.py    external nowcast anchor + market-vs-world divergence (K7)
  watches.py    watch/alert store + background AlertEngine (push computed, pull drained)
  adapters/     base.py · polymarket.py · kalshi.py · manifold.py (fetch + normalize only)
tests/          40+ offline tests: tools · billing · adapters · storage · matcher · hardening · streaming · push · fairvalue · sizing · analyst · trust · ops · manifold

Design principles honored

• ≤ 15 tools (7 here) — agent tool-selection degrades past ~25–30.

• Tools are shaped around agent questions, not 1:1 API endpoints.

• Realizable edge, never gross. Every response marks data staleness.

• No custody, no auto-execution — intelligence only.

• core/ logic is not duplicated — tools call the engine.

• Secrets via env only.

Note on FastMCP version

The spec referenced "FastMCP 3.x"; this builds on the current fastmcp 3.x (decorator API, Streamable HTTP, OAuth helpers). SSE is intentionally unused (deprecated).