# CryptoStruct MCP Server

First-party **remote MCP server** for [cryptostruct.com](https://cryptostruct.com) — historical crypto **and prediction-market** data (tick-level daily files from 35 venues including Kalshi and Polymarket) plus live market statistics, built for traders, quants and AI agents.

This repository documents the hosted server. There is nothing to install or run from here — the server is operated by CryptoStruct.

- **Endpoint:** `https://cryptostruct.com/mcp` (Streamable HTTP, stateless, JSON mode)
- **OAuth endpoint:** `https://cryptostruct.com/mcp/auth` (same tools; answers `401` + `WWW-Authenticate` to trigger the standard OAuth flow — Dynamic Client Registration + PKCE)
- **Server card:** [`/.well-known/mcp/server-card.json`](https://cryptostruct.com/.well-known/mcp/server-card.json)
- **Documentation:** <https://cryptostruct.com/docs/mcp> · Product docs: <https://docs.cryptostruct.com>

No API key required — the catalog, market stats and the guest purchase flow work keyless. Signing in via OAuth (optional) links your CryptoStruct account for order history, purchased-file downloads and paying with your credits — always with your consent (see *Buying data*).

## Quick start

**Claude Code**

```bash
claude mcp add --transport http cryptostruct https://cryptostruct.com/mcp
# or, to enable account sign-in via OAuth:
claude mcp add --transport http cryptostruct https://cryptostruct.com/mcp/auth
```

**Cursor / generic JSON config**

```json
{
  "mcpServers": {
    "cryptostruct": {
      "url": "https://cryptostruct.com/mcp"
    }
  }
}
```

**claude.ai** — Settings → Connectors → *Add custom connector* → `https://cryptostruct.com/mcp/auth`

## What you can do

- **Catalog & discovery:** search ~500K instruments across 35 venues (spot, perpetuals, futures, options, prediction markets), day-level archive coverage back to 2021-02-08.
- **Prediction markets:** Kalshi and Polymarket event contracts are first-class instruments — searchable in the catalog (`class=prediction`), with coverage, live snapshots and minute/daily aggregates like any crypto instrument. Contracts quote 0..1 (USD); turnover comes USD-normalized.
- **Market statistics:** live snapshots and minute/hourly/daily aggregates — OHLC, VWAP, trades, turnover, spreads, top-of-book depth; slippage / market-impact curves.
- **Buying data:** raw tick files — crypto and prediction-market instruments alike — cost €1 per instrument-day. Card payments: the server hands off a Stripe checkout URL — payment happens in the user's browser, the server never touches card details. Free full-day sample files are available without any purchase.
- **Credits & agent consent (OAuth sign-in):** account credits are never spent by an agent without the user's consent. By default `create_checkout` answers `approval_required` with an approval page where the user confirms (pay with credits or by card) or discards the order; unapproved orders expire after 24 h with nothing charged. Users can opt into **autonomous purchases within limits** (per-order and rolling 24-hour caps) at <https://cryptostruct.com/account/agents> — then fully credit-covered orders complete immediately; anything above the caps comes back for approval. The agent may additionally pass its own `max_credit_cents`. `preview_checkout` tells the agent in advance which of the three outcomes to expect. These settings can only be changed on the website, never through an agent's token.
- **Account tools (OAuth sign-in):** list orders, get download URLs for purchased files, check subscription, credit balance and agent-spending settings.

## Tools

| Tool | Description | Tier |
|---|---|---|
| `get_data_dictionary` | Data dictionary & product reference (file format, units, pricing) | free |
| `search_instruments` | Search the instrument catalog | free |
| `list_venues` | List covered venues | free |
| `get_instrument` | Instrument details | free |
| `get_coverage` | Day-level archive coverage for an instrument | free |
| `list_sample_files` | Free full-day sample files | free |
| `get_price_quote` | Price quote for a set of data files | free |
| `get_market_snapshot` | Live market snapshot (60 min + 24 h) | free |
| `get_daily_stats` | Daily aggregates (30d–180d free; 365d/max Premium) | free |
| `get_hourly_stats` | Hourly aggregates (7d–90d free; 180d Premium) | free |
| `get_slippage` | Slippage / market-impact curve (1h free; 24h/7d Premium) | free |
| `get_top_instruments` | Top instruments by live 24 h turnover | free |
| `get_movers` | 24 h movers (gainers & losers) | free |
| `get_minutes_range` | Historical minute series for event studies | premium |
| `create_checkout` | Start a purchase — Stripe URL (card) or `approval_required` / born-paid (credits, per the user's consent settings) | commerce |
| `get_checkout_status` | Poll a checkout by `session_id` (card) or `order_id` (signed-in; credit/approval orders) | commerce |
| `get_order_files` | List a paid order's files with download URLs | commerce |
| `request_file_restore` | Restore an archived (cold-storage) file | commerce |
| `list_my_orders` | My orders | sign-in |
| `get_my_files` | My purchased files | sign-in |
| `get_my_subscription` | My subscription, credit balance & agent-spending settings | sign-in |
| `preview_checkout` | Dry run of a purchase: owned/unavailable files, credit cover, and whether `create_checkout` will complete, ask for approval, or hand off to Stripe | sign-in |

**Tiers:** `free`/`commerce` work keyless. `sign-in` requires a verified OAuth sign-in (any account). `premium` tools/parameters require [CryptoStruct Premium](https://cryptostruct.com/pricing) (€20/month) — which also unlocks longer stats windows (daily 365d/max, hourly 180d, slippage 24h/7d), larger search limits, a data-quality block in `get_market_snapshot`, and a 5× call budget. Calls beyond your tier return static `AUTH_REQUIRED` / `PREMIUM_REQUIRED` errors with an upgrade URL — never a hard failure.

## Rate limits

Weighted per-caller budget: **120 units/min** keyless (per IP) or per signed-in user, **600 units/min** for Premium. Cheap catalog reads cost 1 unit, upstream-heavy stats 3–5, checkout 10. On `RATE_LIMITED` errors, back off for the indicated number of seconds.

## Conventions

- All file sizes are compressed (zstd) bytes; market values are USD; sale prices are EUR.
- Minute-granularity data is retained ~30 days upstream; hourly/daily aggregates reach back further.
- Tick files are full-day JSON-lines captures (orderbook snapshots & updates, trades, liquidations, funding, mark/index incl. options greeks). Format reference: [Market Data Protocol](https://docs.cryptostruct.com/market-data-api/protocol/).

## Related

- **Agent Skill** for parsing the tick files: [`cryptostruct-market-data`](https://cryptostruct.com/skills/cryptostruct-market-data/SKILL.md) ([zip](https://cryptostruct.com/download#ai-toolkit))
- Skills discovery index: [`/.well-known/agent-skills/index.json`](https://cryptostruct.com/.well-known/agent-skills/index.json)
- API catalog (RFC 9727): [`/.well-known/api-catalog`](https://cryptostruct.com/.well-known/api-catalog)
- `llms.txt`: <https://cryptostruct.com/llms.txt>

## Support

Questions or issues: <https://cryptostruct.com/contact>