> ## Documentation index
> Fetch the complete documentation index at: https://docs.predictefy.com/llms.txt
> Use it to discover every available page before exploring further.

# MCP server

> Full REST parity for AI agents — 32 read/intelligence/platform tools plus a guardrailed 10-tool execution and collateral surface, both on by default.

:::note[Beta release]
Published on npm as **`1.0.0-beta.2`**. Pin an exact version while the beta line moves.
:::

`@predictefy/mcp` is a guardrailed
[Model Context Protocol](https://modelcontextprotocol.io) server for the Predictefy API.
It gives AI agents one tool surface over all [17 venues](/reference/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](/guides/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:

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

Claude Code one-liner:

```sh
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.

```json
{
  "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](/guides/streaming/) — 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.