MCP server

Copy page

@predictefy/mcp is a guardrailed Model Context Protocol server for the Predictefy API. It gives AI agents one tool surface over all 17 venues, including PredictStreet. list_venues reports each venue’s capability notes — read them before assuming a venue has a trades tape or a trading lane.

It uses the hosted API via the Predictefy SDK and reaches every REST capability family: catalog, books, history, cross-market intelligence, Trader Intelligence, Data Feeds, accounts, funding and bridge, platform singletons, enterprise SQL, webhooks, and billing. It registers the thirty-two tools below plus ten guardrailed execution and collateral tools, which are now on by default. Set MCP_ENABLE_TRADE=false to run a server that genuinely cannot trade or move collateral — with that surface off, no registered tool returns a transaction to sign.

Tools are grouped and parameterized rather than one-per-endpoint: a kind or scope enum selects the verb inside a family, so an agent sees a readable tool list instead of ninety near-identical entries. Because a grouped tool shares one schema across its kinds, a parameter the chosen kind cannot honor is refused with an error naming it, never silently dropped — an agent must never read an unfiltered or unpaged result as if its filter had applied.

Configure Claude

Claude Desktop (claude_desktop_config.json) or any MCP-compatible client:

{
  "mcpServers": {
    "predictefy": {
      "command": "npx",
      "args": ["-y", "@predictefy/mcp"],
      "env": {
        "PREDICTEFY_API_KEY": "pk_live_your_key_here"
      }
    }
  }
}

Claude Code one-liner:

claude mcp add predictefy -e PREDICTEFY_API_KEY=pk_live_your_key_here -- npx -y @predictefy/mcp

Environment

Variable	Default	Purpose
`PREDICTEFY_API_KEY`	—	API key sent as `Authorization: Bearer …`.
`PREDICTEFY_API_URL`	—	API origin shown in your developer dashboard.
`PREDICTEFY_MCP_TIMEOUT_MS`	`15000`	Per-tool-call time budget (ms).
`MCP_ENABLE_TRADE`	`true`	Registers the ten execution/collateral tools. Set `false` for read-only.
`MCP_EXEC_BASE_URL`	`https://exec.predictefy.com`	Isolated execution origin used by the `exec_*` tools.

Market data tools

Tool	What it does	Server-side caps
`list_venues`	The 17 product venues + capability notes (book tier, trades tape).	— (static, no upstream call)
`search_markets`	Text search over markets on one venue, or ALL venues when omitted.	max 100 rows
`get_market`	One market by `venue` + `marketId` (or `slug`).	50KB response budget
`get_events`	Event-shaped listings on one venue or ALL venues.	max 100 rows
`get_event`	One event (with markets) by `venue` + `eventId` (or `slug`).	50KB response budget
`get_orderbook`	Live order book for one outcome (`venue` + `outcomeId`).	depth clamp 100 when asked
`get_orderbooks`	Many books in one call (`outcomeIds` csv) → an outcomeId → book map.	max 100 ids
`get_ohlcv`	OHLCV candles (`resolution` `1m`/`1h`/`1d`, optional `start`/`end`).	max 5000 candles
`get_trades`	Recent public trades tape where the venue exposes one.	max 100 rows
`get_catalog_metadata`	`kind`: categories, tags, series, event-metadata, capabilities (`has`), paginated pages.	max 100 rows
`get_execution_price`	Stateless VWAP calculator over a book you pass; `detailed` adds the partial-fill breakdown.	50KB response budget
`filter_catalog`	Pure stateless filter over market or event rows you already have.	50KB response budget
`get_feed_data`	Reference feeds — `kind`: list, markets, ticker, tickers, ohlcv, oracle round/history, prices.	candles 5000 / rows 100

Intelligence tools

Tool	What it does	Server-side caps
`get_matches`	Cross-venue matches — `scope`: market, event, or related (subset/superset outcome edges).	max 100 rows
`get_matched_markets`	Browse matched pairs ranked by INDICATIVE price difference.	max 100 rows
`compare_market_prices`	One anchor across venues — `kind`: venues (per-venue prices) or hedges (opposite-side candidates).	max 100 rows
`get_clusters`	Cross-venue clusters — `kind`: canonical (plus `clusterId` for one cluster’s members), market, event.	max 100 rows
`get_discrepancies`	Indicative discrepancies; `clusterId` + `size` runs the fail-closed live qualification instead.	max 100 rows
`get_arbitrage`	Fully gated live-book execution analysis at a size; `executableOnly` serves only passing rows.	max 100 rows

Trader intelligence tools

Tool	What it does	Server-side caps
`get_market_traders`	Wallet-attributed trades for one market, with keyset pagination.	max 100 rows
`get_market_holders`	Top holders per outcome for one market.	max 100 rows
`get_leaderboard`	Venue profit/volume/score rankings, or cross-venue score rankings.	max 100 rows
`get_wallet_profile`	Venue-scoped wallet statistics, score, factors, category, and provenance.	50KB response budget
`get_wallet_trades`	One wallet’s venue-scoped trade history, keyset-paged.	max 100 rows
`get_smart_money`	Ranked notable scored trades with venue/wallet/market/category filters.	max 100 rows

The six trader tools use the live, capability-qualified Trader Intelligence routes. Unsupported venue/verb combinations fail honestly instead of returning made-up empty data. Scores are informational signals, not financial advice, and tool output is not a recommendation.

Account, funding, and platform tools

Tool	What it does	Server-side caps
`get_account`	Venue account resources — `kind`: capabilities, snapshot, balances, positions, open-orders, fills.	max 100 rows
`get_funding`	Funding and bridge INFO — `kind`: requirements, bridge-status. Artifact-bearing reads are gated.	50KB response budget
`get_platform_metadata`	`kind`: portfolio (public address valuation), mappings, venue-metrics.	100 mapping pairs
`run_sql`	One read-only SQL statement. Requires an API key with the `sql` scope, enforced server-side.	50KB response budget
`get_webhooks`	This account’s endpoints (`kind=endpoints`) or one endpoint’s deliveries.	max 100 rows
`manage_webhook`	Write. `action=create` (signing secret returned once) or `action=delete`. Both need `confirm: true`.	—
`create_billing_session`	Write. Opens a Stripe session URL — `kind`: checkout, subscribe, portal. Buys nothing itself.	—

manage_webhook and create_billing_session are the only non-execution tools that write, and both touch nothing but the caller’s own account through the caller’s own key. They are annotated for what they are — readOnlyHint: false, plus destructiveHint: true on the delete-capable one — rather than hidden behind a read-only hint.

The Stripe webhook callback route is deliberately absent: it is an inbound provider callback with no client meaning, and the TypeScript SDK omits it too.

Execution tools (on by default)

The package also registers the ten execution and collateral tools below. They are on by default as of 2026-08-18: every API key already includes the trade scope, so gating them behind an extra environment variable protected nothing. MCP_EXEC_BASE_URL defaults to the canonical isolated execution origin https://exec.predictefy.com; set it explicitly to point at another deployment. A malformed or link-local/cloud-metadata value still refuses to boot rather than risk sending a signed order to the wrong host.

Tool	What it does
`exec_venues`	Read-only: which lanes are armed now (build/submit/cancel/modify per venue).
`exec_quote`	Read-only preview of the live-book cost. Nothing is built, signed, or submitted.
`exec_prepare`	Builds an unsigned order artifact; it never signs.
`exec_submit`	Relays a client-signed artifact. Dry-run unless `confirm` is exactly `true`.
`exec_cancel`	Builds an unsigned cancel intent. It cancels nothing on its own.
`exec_modify`	Builds an unsigned modify intent for a resting order.
`exec_refresh`	Re-reads one execution’s venue status with a transient, never-stored credential.
`exec_orders`	Read-only: `kind` order, list, trades, positions, or balance for this account.
`prepare_funding`	Builds unsigned collateral steps, opens a bridge session, or reports a payment.
`get_funding_artifacts`	Read-only funding reads that RETURN signable artifacts: transfer plan, bridge quote, bridge session.

Cancel and modify follow exactly the same shape as prepare: they hand back an unsigned artifact for your own wallet to sign, and the signed artifact goes back through exec_submit. Nothing is ever signed server-side, and no tool both builds and submits.

prepare_funding and get_funding_artifacts sit with this surface because both hand back caller-signable, collateral-moving transactions — the first by building them, the second by reading plans, quotes, and sessions that embed them. Only the purely informational funding lookups (venue requirements and transfer status) stay ungated, on get_funding. One honest caveat: get_funding kind=bridge-status relays the bridge provider’s status payload verbatim (thin-client), so its artifact-freedom is provider-shaped rather than structurally enforced by Predictefy.

Turning them off

Set MCP_ENABLE_TRADE=false in the server’s environment. The ten tools above are then not registered at all, and the surface is exactly the thirty-two read, intelligence, and platform tools listed earlier — nothing that can trade or move collateral, and nothing that hands back a transaction to sign.

{
  "mcpServers": {
    "predictefy": {
      "command": "npx",
      "args": ["-y", "@predictefy/mcp"],
      "env": {
        "PREDICTEFY_API_KEY": "pk_live_your_key_here",
        "MCP_ENABLE_TRADE": "false"
      }
    }
  }
}

No tool both builds and submits an order, and no signing endpoint exists. The execution service still enforces trade scope, spend caps, artifact bounds, and idempotency.

Guardrails (designed in, enforced server-side)

Hard limit clamps — list tools cap at 100 rows and get_ohlcv at 5,000 candles at the wire, regardless of what the model asks for.
Response byte budget — payloads over ~50KB are truncated with an explicit "truncated": true + note (never silently).
Per-request timeout — a hung upstream surfaces a clean MCP error after 15s (configurable), never a hang.
Input validation — unknown venues are rejected before any upstream call, with the full valid venue list in the error.
No secrets in output — the API key is redacted from every error path.
Honest annotations — every read tool is annotated readOnlyHint: true, and every tool that writes says so. exec_quote, exec_venues, and exec_orders are read-only; exec_prepare, exec_cancel, exec_modify, exec_refresh, prepare_funding, and create_billing_session are not read-only; exec_submit and manage_webhook are destructive — and both still preview unless passed confirm: true — manage_webhook on create as well as delete.
Regression-locked tool set — the exact ungated tool list is pinned by test, so nothing that can trade or move collateral can reach the default surface unnoticed.

Notes for agents

Order books from myriad, gemini, and rain are emulated (reconstructed top-of-book) — indicative, not executable. list_venues reports this per venue.
Cross-venue price gaps served by the platform are labeled indicative price discrepancy — observed mid-price gaps, not executable opportunities.
get_trades returns the server’s honest NOT_SUPPORTED error on venues without a public tape.
Trader tools return the server’s honest TRADERS_UNSUPPORTED error when a venue or trader verb is unavailable. Cross-venue get_leaderboard calls require by=score; wallets stay venue-scoped, and window=all means “since collection began” for the scored-trade feed.
There are no streaming tools. MCP is request/response, so the WebSocket surface — live books, trades, price frames, and the arbitrage feed — has no MCP equivalent, and none is faked. Use get_arbitrage for a point-in-time snapshot of the arbitrage stream, and the SDK watch* verbs or the raw WebSocket when you need a live subscription.
Data Feeds (get_feed_data) are reference price sources — Binance spot and Chainlink oracles — not prediction-market venues. Their orderbook kind is a permanent capability gap: reference feeds publish prices, not depth, so it always answers NOT_SUPPORTED.
get_account serves public account data. Owner-authenticated venues answer with an honest NOT_SUPPORTED naming the credential that would be required; this hosted server holds no venue credentials, and credentials never transit Predictefy.
run_sql needs an API key carrying the sql scope. The server enforces the scope and read-only access; a key without it gets a plain authorization error.