MCPModel Context Protocol

MCP server

@predictefy/mcp is a guardrailed Model Context Protocol server for the Predictefy API. It gives AI agents one tool surface over all 16 served 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. The default surface registers 48 tools: the 39 read, intelligence, and platform tools below plus the nine paper tools (paper trading), with ten optional guardrailed execution and collateral tools. The ten are off by default; set MCP_ENABLE_TRADE=true or 1 to enable them. Unset or MCP_ENABLE_TRADE=false disables them. See Turning them off to run a server that genuinely cannot trade or move collateral.

This is deliberate agent-surface curation, not REST parity. REST defines 92 operations. The MCP surface with trading enabled semantically covers 86/92 and directly invokes 84/92 through those 58 tools. The six absent operations are listHistoryBookEvents, listDiscrepancyHistory, getUsage, execReserveOrder, execAckOrder, and stripeWebhook. The last is deliberately absent because it is an inbound provider callback, not a caller-facing operation. With trade tools disabled, coverage is 69/92 semantic and 67/92 direct.

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. Since 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.

Covered operations do not imply parameter parity. get_orderbook and get_trades clamp their limit at 100 versus REST’s 1000. get_ohlcv exposes three resolutions versus REST’s twelve. get_orderbooks accepts up to 100 ids even though REST caps the batch at 50.

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`	`https://data.predictefy.com`	API origin override; the hosted reads origin is the default.
`PREDICTEFY_MCP_TIMEOUT_MS`	`15000`	Per-tool-call time budget (ms).
`MCP_ENABLE_TRADE`	`false`	Registers the ten execution/collateral tools only for `true` or `1`; unset and other values leave them off.
`MCP_EXEC_BASE_URL`	`https://exec.predictefy.com`	Isolated execution origin used by the `exec_*` tools.
`MCP_EXEC_ALLOWED_HOSTS`	— (any valid non-metadata host)	Optional comma-separated host allowlist for `MCP_EXEC_BASE_URL`; the configured host must match when set.

Market data tools

Tool	What it does	Server-side caps
`list_venues`	The 16 served venues + the dark one, with 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
`screen_markets`	Screen markets with catalog filters and price-change windows.	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.	stored 100 / live 10
`get_arbitrage`	Fully gated live-book execution analysis at a size; optional `stake` projects a USD budget (dark by default); `executableOnly` serves only passing rows.	max 500 rows

The optional stake on get_arbitrage is a finite, positive USD budget of at most 1,000,000 with at most two decimal places; the calculator is dark by default behind READS_ENABLE_ARBITRAGE_STAKE.

Sports tools

Sports catalogue, screen, and comparison tools have been live and metered since 2026-09-29. On a deployment with the sports surface switched off, they return ROUTE_NOT_FOUND. The screen has a second switch, so catalog reads can answer while the screen remains dark. Dark calls are not charged. The grid is a price comparison; avg, fair, edge, and hold are Predictefy’s own calculations, not an arbitrage claim. If a page is truncated, its cursor is withheld to avoid skipping dropped rows; reduce limit or request fewer venues.

Tool	What it does	Server-side caps
`get_sports_facets`	Browse facets, competitions, or teams by `kind`; `cascade` requires `competition`.	50KB response budget
`get_sports_screen`	Cross-venue fixture price comparison with filters, snapshot metadata, and keyset paging.	default 5 / max 25 rows
`get_fixtures`	Filtered fixture listings with market-block availability and keyset paging.	default 20 / max 100 rows
`get_fixture`	One fixture’s identity, market blocks, and snapshot metadata.	50KB response budget
`compare_fixture_prices`	Compare one fixture’s market blocks across venues.	50KB response budget
`get_fixture_price_history`	Price history of one fixture market block (dark by default).	50KB response budget

get_fixture_price_history requires fixtureId and defaults interval to 1h. It is dark by default behind both READS_ENABLE_SPORTS and READS_ENABLE_SPORTS_HISTORY; an unavailable route returns ROUTE_NOT_FOUND. If truncated is true, narrow venues, from, or to, or choose a coarser interval to fit the response budget.

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` or `action=rotate` (signing secret returned once), or `action=delete`. All need `confirm: true`; rotate also needs `id`. See Rotating a secret.	—
`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.

Paper trading tools

The nine paper tools below are always registered. A paper order reaches no venue and moves no money, so MCP_ENABLE_TRADE has nothing to gate here. Availability is the API’s decision: every /v1/paper/* route needs an API key carrying the trade scope, and each plan caps how many paper orders may be open at once. See Paper trading for the simulation itself.

Tool	What it does	Server-side caps
`paper_account`	The simulated USD account. `reserved` is a hold inside `cash`, so free cash is the difference.	50KB response budget
`paper_reset_account`	Write. Restarts the simulation — working orders canceled, positions flattened, fills kept. Needs `confirm: true`.	—
`paper_place_order`	Write. Places a simulated order against the real book. `idempotencyKey` is required and never minted for you.	—
`paper_list_orders`	This account’s paper orders, newest first, filtered by `status` and/or `venue`, cursor-paged.	max 100 rows
`paper_get_order`	One paper order together with its `fills` — the only read that carries them.	50KB response budget
`paper_cancel_order`	Write. Cancels one working order and releases its unspent hold; filled size stays filled.	—
`paper_list_fills`	Every simulated fill on this account, newest first, cursor-paged.	max 100 rows
`paper_positions`	Per-outcome size, average cost, realized PnL, and a catalog mark (null when unmarkable).	50KB response budget
`paper_portfolio`	The account, its positions, and their totals from ONE consistent snapshot (`asOf`).	50KB response budget

Only paper_reset_account previews. It is the one paper call that cannot be undone — working orders are canceled and positions flattened, and nothing restores them — so it does nothing unless passed confirm: true. Placing and cancelling a simulated order need no confirmation step: nothing is at risk, a cancel only releases a hold, and the required caller-chosen idempotencyKey already makes a retry replay the stored order instead of placing a second one.

Refusals name what to do about them. SCOPE_MISSING means the key lacks the trade scope, PLAN_REQUIRED means the plan gate answered, and PAPER_WORKING_ORDER_CAP means the plan’s open-order allowance is full — cancel a working order or move to a larger plan. PAPER_NO_LIVE_BOOK is a refusal rather than a verdict on the order: no live book is captured for that outcome, so nothing could fill it.

Execution tools (off by default)

The ten execution and collateral tools below are off by default as of 2026-09-14. Enable them with MCP_ENABLE_TRADE=true or 1; new API keys default to read, so opt into trade per key in the console. Existing keys are unchanged. 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 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. 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

Leave MCP_ENABLE_TRADE unset or set it to false in the server’s environment. The ten tools above are then not registered at all, and the surface is exactly the thirty-nine read, intelligence, and platform tools listed earlier plus the nine paper tools — nothing that can trade real money 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 — most list tools cap at 100 rows, live discrepancy lists at 10 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, delete, and rotate. The paper writes follow the same rule: paper_place_order is not read-only, while paper_reset_account and paper_cancel_order are destructive, and only the reset previews unless passed confirm: true.
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

myriad has a dual book model: myriad:ob:* markets serve native CLOB depth, while AMM markets expose an emulated indicative top-of-book. gemini serves real sized CLOB depth. Only rain is wholly emulated as a one-level synthetic book. list_venues reports the tier per venue.
Cross-venue price gaps served by the platform are labeled indicative price discrepancy — observed price gaps (stored Yes prices by default, live order-book mid-prices with live=true), 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. A known but unserved dedicated resource returns the wire code ACCOUNTS_UNSUPPORTED, which the SDK maps to the NotSupportedError class without changing .code. 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.
The paper tools need a key carrying the trade scope, exactly like the execution tools: a read-only key can never place even a simulated order. Paper trading itself is open on every plan, which differ only in how many paper orders may be open at once.