MCP server

The PolyTest MCP (Model Context Protocol) server lets an AI tool read PolyTest market data directly. It works in Claude Code, Cursor, VS Code, Codex, Gemini CLI, Claude Desktop and other MCP clients. All of its tools are read-only.

Connect

The hosted server is at https://mcp.polytest.io/mcp and uses Streamable HTTP. The Claude Code command adds the server without a key, and you sign in with your PolyTest account after that. The other snippets send an API key from the POLYTEST_KEY environment variable. Authenticate explains both.

claude mcp add --transport http polytest https://mcp.polytest.io/mcp

Run the Claude Code and Gemini CLI lines in a terminal. The Cursor block goes in ~/.cursor/mcp.json, the VS Code block in .mcp.json and the Codex block in ~/.codex/config.toml.

Authenticate

If your client supports OAuth, sign in with your PolyTest account. In Claude Code, run /mcp, select polytest and choose Authenticate. If /mcp isn't available, as in Claude Code inside the desktop app, run claude mcp login polytest in a terminal instead, from the folder where you added the server. Other clients ask you to sign in when they connect or the first time they call a tool.

Your browser opens a sign-in link on qpzofvjvtdvdnvgpxplg.supabase.co, the address of Supabase Auth, which PolyTest uses for sign-in. It then continues on www.polytest.io, where you approve the connection. You can remove it later in Settings, under Connected apps.

You can also send an API key in the header Authorization: Bearer <key>. The X-API-Key header works too. Create a key on the API keys page, and never put it in the URL.

In Claude Code, the key goes in a --header flag:

Claude Code
claude mcp add --transport http polytest https://mcp.polytest.io/mcp --header "Authorization: Bearer $POLYTEST_KEY"

Run it locally

npx -y @polytest/mcp runs the server on your own machine from the npm package @polytest/mcp. It needs Node 20 or newer and reads your key from the POLYTEST_KEY environment variable.

claude mcp add --transport stdio --env POLYTEST_KEY=$POLYTEST_KEY polytest -- npx -y @polytest/mcp

The Claude Desktop block goes in claude_desktop_config.json. Replace pt_live_... with your key.

Tools

The server has five tools. The last column is what one call costs in API requests.

ToolReturnsAPI requests
polytest_list_marketsMarkets of one market_type for one coin, newest first. Each row has its window, status, opening and closing spot price, winner and volume.1
polytest_get_marketOne market, by market_id or slug, including token ids and resolution fields.1
polytest_get_snapshotsSnapshots of one market, oldest first, each with time, spot_price, price_up and price_down. With include_orderbook, each row also has both order books.1
polytest_get_price_seriesEvenly spaced price points across one market, oldest first.1 plus one per sample, 21 with the default
polytest_get_limitsYour plan's limits: tier, rate limits, concurrency cap, data access, key cap and trial budget.1

price_up is the lowest ask on the Up order book: the price you would pay to buy Up at that moment. price_down is the same for Down. Both run from 0 to 1, and each is null when nobody is offering that side. Neither is a midpoint or the last trade price. Because both are asks, Up plus Down usually comes to a little more than 1.

A typical session calls polytest_list_markets to find a market, polytest_get_price_series for the shape of that market, then polytest_get_snapshots for tick detail or the order book at one moment.

Coverage and freshness

PolyTest has btc, eth and sol markets for 5m, 15m and 1hr, and btc only for 4hr and 24hr.

PolyTest loads new markets in batches, so the newest markets can be hours or days behind real time. The lag differs by coin and market type.

Each market row has a status field:

  • upcoming: the window hasn't started.
  • open: the window is still running.
  • resolved: the winner is known.
  • ended_no_result: the window has closed and PolyTest has no result for it.

When you list the newest markets, with no end_time, and the newest one started well before the current time, polytest_list_markets adds a note saying so. For a market that is still running, polytest_get_price_series stops at the current time instead of sampling the future. When the last buckets of a series come back empty, it says where the data ends. A range that starts after the current time, such as a market that hasn't started, returns an error.

Limits and cost

Every tool call makes ordinary API requests, so it counts against the same plan limits as REST calls.

  • Rate limits are per key, so create a dedicated key for the MCP server.
  • Concurrency is shared with anything else running on your account. The server retries briefly when a slot is busy.
  • polytest_get_limits returns trial_budget for every account, paid ones included. Those are the total requests, records and bytes a free trial may use over its 3 days, and they apply only during a trial. The tools can't show what's left: the REST API reports the remaining amounts only in response headers, which MCP clients don't see.
  • Results are sized for an AI context window: pages are small, and order books are trimmed to a chosen depth. For bulk pulls or backtests, have the AI write code against the TypeScript SDK or the REST API instead.

Try it

Once the server is connected, ask in plain language. For example:

  • List the five most recent BTC 5m markets on PolyTest and show how the Up price moved in the latest one.

  • Find the latest resolved BTC 15m market on PolyTest and show both order books thirty seconds before it closed.

  • Check my PolyTest plan limits, then tell me how many API requests a 40-sample price series costs.

Troubleshooting

A tool error says the API key is missing or was rejected
The error says how to fix it for your setup: set POLYTEST_KEY, add the Authorization header, or sign in again. Your keys are on the API keys page.
A tool error names your plan
The plan does not cover that request. Ask the AI to call polytest_get_limits to see what it covers.
The client says the server needs authentication
Sign in when the client offers it, or add the Authorization header from Authenticate.
A tool error says the rate limit was reached
The error says how long to wait before you retry.