MCP Server

Connect Your AI Platform

Step-by-step guides for connecting Laevitas derivatives data to your favorite AI platform. Requires an Enterprise API key from your Laevitas dashboard.

Claude.ai Connectors

OAuth 2.1

Connect directly from Claude.ai using the built-in MCP Connectors feature. OAuth handles authentication automatically.

1

Go to Settings → Connectors in Claude.ai
2

Click Add custom connector
3

Fill in the fields:

NameLaevitas

Remote MCP server URLhttps://apiv2.laevitas.ch/api/v1/mcp

AuthenticationSign in now

OAuth clientRegister automatically

Request headersnone needed
4

Click Add — a popup will open asking for your Laevitas API key
5

Enter your API key and click Authorize. The connector is now active.

Do not enter a client ID or secret: Claude registers and manages its own credentials automatically. Enter your own API key only on the Laevitas authorization page, not in the connector URL or request headers. Select Register automatically, not Use Claude's published identity; CIMD is not supported. Existing working manual registrations can remain in use. If an old saved ID produces Unknown client_id, reconnect using automatic registration.

Claude Desktop

API Key

Add to your claude_desktop_config.json:

1

Open Claude Desktop → Settings → Developer → Edit Config

Add the following to your config file:

{
  "mcpServers": {
    "laevitas-derivatives": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://apiv2.laevitas.ch/api/v1/mcp",
        "--header",
        "apikey: YOUR_API_KEY"
      ]
    }
  }
}

3

Restart Claude Desktop. The Laevitas tools will appear in your tool list.

Claude CLI (Claude Code)

API Key

One command to connect:

Run in your terminal:

claude mcp add laevitas-derivatives \
  --transport http \
  https://apiv2.laevitas.ch/api/v1/mcp \
  --header "apikey: YOUR_API_KEY"

Ask naturally:

claude -p "What's the BTC perpetual funding rate?"

Cursor

API Key

Add to .cursor/mcp.json in your project root (or the global ~/.cursor/mcp.json):

{
  "mcpServers": {
    "laevitas": {
      "url": "https://apiv2.laevitas.ch/api/v1/mcp",
      "headers": {
        "apikey": "YOUR_API_KEY"
      }
    }
  }
}

Open Settings → MCP and confirm the laevitas server shows a green dot, then ask the agent in chat.

VS Code (Copilot)

API Key

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "laevitas": {
      "type": "http",
      "url": "https://apiv2.laevitas.ch/api/v1/mcp",
      "headers": {
        "apikey": "YOUR_API_KEY"
      }
    }
  }
}

Open the Copilot Chat panel in Agent mode — the Laevitas tools appear in the tools picker. Requires GitHub Copilot with MCP support enabled.

Windsurf

API Key

Add to your mcp_config.json (Cascade → MCP settings → Edit raw config):

{
  "mcpServers": {
    "laevitas": {
      "serverUrl": "https://apiv2.laevitas.ch/api/v1/mcp",
      "headers": {
        "apikey": "YOUR_API_KEY"
      }
    }
  }
}

Click Refresh in the MCP panel, then talk to Cascade.

Codex CLI

API Key

One command to register the server:

codex mcp add laevitas \
  --url https://apiv2.laevitas.ch/api/v1/mcp \
  --header "apikey: YOUR_API_KEY"

Then ask Codex directly — e.g. "Get the BTC perpetual funding rate on Binance."

ChatGPT / OpenAI

GPT Actions

Connect as a custom GPT Action using the MCP endpoint.

1

Go to Explore GPTs → Create in ChatGPT
2

Under Configure → Actions → Create new action
3

Set Authentication to API Key, header name apikey
4
Import the OpenAPI schema from:
```
https://apiv2.laevitas.ch/swagger-json
```
5

Save and test. Your GPT can now call Laevitas endpoints directly.

OpenAI GPT Actions use the REST API directly (not MCP protocol). All futures and options endpoints are available via the Swagger schema.

n8n

n8n Automation

MCP Client Node

Use the n8n MCP Client node to connect to Laevitas.

1

Add an MCP Client node to your workflow
2

Set Transport to Streamable HTTP
3
Enter the server URL:
```
https://apiv2.laevitas.ch/api/v1/mcp
```
4

Add a custom header: apikey: YOUR_API_KEY
5

Connect to an AI Agent node. The agent can now call all Laevitas tools.

Any MCP Client

Streamable HTTP transport endpoint. Works with any MCP-compatible client.

Endpoint

POST https://apiv2.laevitas.ch/api/v1/mcp
Content-Type: application/json
Accept: application/json, text/event-stream
apikey: YOUR_API_KEY

OAuth 2.1 (for platforms that require it)

# Discovery endpoints
GET https://apiv2.laevitas.ch/.well-known/oauth-protected-resource
GET https://apiv2.laevitas.ch/.well-known/oauth-authorization-server

# Dynamic client registration (JSON; no API key needed)
POST https://apiv2.laevitas.ch/oauth/register

# Authorization (PKCE S256 required)
GET https://apiv2.laevitas.ch/oauth/authorize

# Token exchange / refresh (application/x-www-form-urlencoded)
POST https://apiv2.laevitas.ch/oauth/token

Register with an approved redirect_uris array and token_endpoint_auth_method of none (default) or client_secret_post. HTTP 201 returns the generated client credentials; keep any secret private and send it with both token exchange and refresh. Every client must use PKCE S256 and user authorization. See the OAuth API reference for request and response fields.

MCP Inspector (debug tool)

npx @modelcontextprotocol/inspector

Enter the endpoint URL and connect. Browse tools, call them, and inspect responses.

Available Tools

80+ tools the AI agent can call, grouped by category. Start with a discovery tool (catalog or metadata) to see what instruments and date ranges are available before fetching data.

Catalog & Discovery

Tool	Description
`get_futures_catalog`	List available dated-futures instruments on an exchange
`get_perpetuals_catalog`	List available perpetual instruments on an exchange
`get_options_catalog`	List available options instruments on an exchange
`get_spot_catalog`	List available spot pairs on an exchange
`get_predictions_catalog`	List available prediction-market instruments
`get_predictions_categories`	List prediction-market categories
`get_futures_metadata`	Data availability for a futures instrument (date range, data points)
`get_perpetuals_metadata`	Data availability for a perpetual instrument
`get_options_metadata`	Data availability for an options instrument
`get_spot_metadata`	Data availability for a spot pair
`get_predictions_metadata`	Data availability for a prediction-market instrument
`get_instruments_metadata`	Cross-market instrument metadata lookup
`get_derivatives_liquidations`	Aggregated liquidations across derivatives markets

Options Backtests

Asynchronous Deribit BTC/ETH portfolio simulations. Shared capital, independent UTC rolls, minute valuation and displayed-size fills. Use the same account as REST; submit once with a stable idempotency key, poll status and download the completed result promptly. Request and response schemas.

Tool	Arguments / purpose
`get_options_backtest_strategies`	{} — templates, limits and execution assumptions
`submit_options_backtest`	{request, idempotency_key} — queue the user-approved strategy; returns job_id
`get_options_backtest_status`	{job_id} — poll state and progress with backoff
`get_options_backtest_result`	{job_id} — combined report, every execution and data-quality evidence
`cancel_options_backtest`	{job_id} — cooperative cancellation, after user confirmation

Dated Futures

Tool	Description
`get_futures_ohlcvt`	OHLCVT candle data (price, volume, trades, liquidations)
`get_futures_ticker_history`	Ticker snapshots (mark price, OI, bid/ask)
`get_futures_trades`	Individual trade records with full details
`get_futures_trades_summary`	Aggregated buy/sell trade flow summary
`get_futures_open_interest`	Aggregated open interest OHLC over time
`get_futures_volume`	24-hour rolling volume (contracts + USD)
`get_futures_level1`	Best bid/ask, spread, and liquidity over time
`get_futures_l2_orderbook`	Aggregated L2 orderbook depth
`get_futures_l2_orderbook_raw`	Raw L2 orderbook snapshots
`get_futures_reference_price`	Mark price and index price OHLC
`get_futures_basis`	Futures basis and annualized term structure
`get_futures_liquidations`	Liquidation events over time
`get_futures_flow`	Order flow (buy/sell pressure) over time
`get_futures_snapshot`	Full market snapshot of ALL instruments at one point in time

Perpetuals

Tool	Description
`get_perpetuals_funding`	Funding rate history — the headline perp metric
`get_perpetuals_ohlcvt`	OHLCVT candle data (price, volume, trades)
`get_perpetuals_ticker_history`	Ticker snapshots (mark price, funding, OI, bid/ask)
`get_perpetuals_trades`	Individual trade records
`get_perpetuals_trades_summary`	Aggregated buy/sell trade flow summary
`get_perpetuals_open_interest`	Aggregated open interest OHLC over time
`get_perpetuals_volume`	24-hour rolling volume (contracts + USD)
`get_perpetuals_level1`	Best bid/ask, spread, and liquidity over time
`get_perpetuals_l2_orderbook`	Aggregated L2 orderbook depth
`get_perpetuals_l2_orderbook_raw`	Raw L2 orderbook snapshots
`get_perpetuals_reference_price`	Mark price and index price OHLC
`get_perpetuals_liquidations`	Liquidation events over time
`get_perpetuals_flow`	Order flow (buy/sell pressure) over time
`get_perpetuals_snapshot`	Full market snapshot of ALL perpetuals at one point in time

Options

Tool	Description
`get_options_ohlcvt`	OHLCVT candle data for options (trade-based)
`get_options_ticker_history`	Ticker snapshots (IV, Greeks, OI, bid/ask)
`get_options_trades`	Individual option trade records with Greeks
`get_options_trades_summary`	Aggregated trade flow summary
`get_options_open_interest`	Aggregated open interest over time
`get_options_volatility`	IV (mark/bid/ask), Greeks, and vol spread over time
`get_options_volume`	24-hour rolling volume (contracts + USD)
`get_options_level1`	Best bid/ask, spread, and liquidity over time
`get_options_reference_price`	Underlying / reference price OHLC
`get_options_flow`	Options order flow (buy/sell pressure)
`get_options_snapshot`	Full options chain snapshot (all strikes, maturities) at one time

Volatility Surface

Tool	Description
`get_vol_surface_by_expiry`	IV surface sliced by expiry date
`get_vol_surface_by_tenor`	IV surface by constant-maturity tenor (term structure)
`get_vol_surface_by_time`	IV surface evolution over time
`get_vol_surface_catalog`	Proprietary surface catalog by exchange, currency, margin, and model
`get_vol_surface_snapshots`	Engine calibration snapshots, forward curve, and calendar-arb diagnostics
`get_vol_surface_slices`	Per-expiry proprietary fits with model params, diagnostics, quality tier, and fallback metadata
`get_vol_surface_term_structure`	Constant-maturity proprietary term structure and forward vol
`get_vol_surface_strikes`	Per-strike proprietary diagnostics and greeks
`get_vol_surface_risk_decompose`	Live portfolio risk decomposition
`get_vol_surface_risk_scenario`	Live scenario repricing
`get_vol_surface_risk_ladder`	Live spot x vol ladder repricing

Spot

Tool	Description
`get_spot_ohlcvt`	OHLCVT candle data for a spot pair
`get_spot_ticker`	Ticker snapshots (price, bid/ask)
`get_spot_trades`	Individual spot trade records
`get_spot_volume`	24-hour rolling volume
`get_spot_level1`	Best bid/ask, spread, and liquidity over time
`get_spot_l2_orderbook`	Aggregated L2 orderbook depth
`get_spot_l2_orderbook_raw`	Raw L2 orderbook snapshots
`get_spot_snapshot`	Full market snapshot of ALL spot pairs at one time

Prediction Markets

Tool	Description
`get_predictions_ohlcvt`	OHLCVT candle data for a prediction-market instrument
`get_predictions_ticker_history`	Ticker / implied-probability snapshots
`get_predictions_trades`	Individual trade records
`get_predictions_orderbook_raw`	Raw orderbook snapshots
`get_predictions_snapshot`	Full market snapshot at one point in time

Hyperliquid - HyperCore

Tool	Description
`get_hyperliquid_node_fills`	Wallet-attributed node fills with fees, closed PnL, builder/deployer fees, hashes, and block numbers
`get_hyperliquid_prediction_fills`	HIP-4 prediction fills with condition/token ids and wallet attribution
`get_hyperliquid_node_liquidations`	Liquidation fills with role, dedupe mode, backstop labels, and aggregate bucket mode
`get_hyperliquid_wallet_flow`	Wallet flow rollups with sorted notional/PnL/count ranking, net fields, and labels
`get_hyperliquid_wallet_positions`	Latest wallet positions with marks, position notional, nullable entry price, and labels
`get_hyperliquid_funding_payments`	Wallet-level funding payments from node misc events
`get_hyperliquid_twap_events`	TWAP lifecycle events with target-notional discovery for recent large orders
`get_hyperliquid_resting_orders`	Latest L4 resting orders with mark distance, staleness metadata, and labels
`get_hyperliquid_instruments`	Resolve raw Hyperliquid coins and aliases to normalized instruments
`get_hyperliquid_node_l2_orderbook`	Deep HyperCore-derived L2 orderbook snapshot with 100-level liquidity and imbalance

Macro & Analytics

Tool	Description
`get_macro_catalog`	List available macro datasets
`get_macro_asset_classes`	List macro asset classes
`get_macro_venues`	List macro venues / sources
`get_macro_summary`	Cross-market macro summary
`get_realized_volatility`	Realized volatility for an asset over a window

Troubleshooting

Common issues when connecting an MCP client. Restart your client after changing any configuration.

`406 Not Acceptable`

Your client (or curl) didn't send Accept: application/json, text/event-stream. Both content types are required on every request.

`401 Unauthorized`

Missing or invalid credentials. For API-key clients, check the apikey header. The MCP handshake returns 401 with a WWW-Authenticate header before login — that starts OAuth discovery. For Claude.ai, choose Sign in now and Register automatically, with no custom headers. Enter your valid Laevitas API key on the authorization page. A stale or invalid registration header is rejected, not ignored.

Couldn't register / Unknown client_id

Do not reuse a client ID copied from an old guide. Use Register automatically with no custom headers. Registration supports public and client_secret_post clients with approved callbacks; it does not grant access without user sign-in. If registration is rate-limited, wait for Retry-After rather than repeatedly retrying. If it still fails, send support the UTC time and Claude's reference code, never your API key, client secret or tokens.

`429 Too Many Requests`

You hit the per-minute tool-call limit. Back off using the X-RateLimit-Reset response header (seconds until reset). Batched JSON-RPC calls count one slot per tools/call frame.

`402 Payment Required`

A tools/call was sent without an API key or OAuth token, so x402 pay-per-call kicked in. Either authenticate, or let a wallet-enabled agent settle the payment. See the x402 guide.

Duplicate tools / won't connect

Configure the Laevitas server once per client. If you added it more than once (e.g. an API-key entry and an OAuth entry), remove the duplicate, then restart.

`npx` not found

Clients that bridge via mcp-remote need Node.js. Run npx --version to confirm it's installed, and make sure your network allows outbound HTTPS to apiv2.laevitas.ch.

Still stuck? Debug interactively with the MCP Inspector (npx @modelcontextprotocol/inspector) or email [email protected].

Header (preferred)	`apikey: your-key-here`
Header (alternative)	`x-api-key: your-key-here`
Query parameter	`?apiKey=your-key-here`

PKCE	`S256` (required)
Grant type	`authorization_code`
Token lifetime	`24 hours` access; `30 days` refresh. Clients follow the returned `expires_in`.

initialize	Free
tools/list	Free
tools/call	`1 credit` per call

Connect Your AI Platform

Claude.ai Connectors

Claude Desktop

Claude CLI (Claude Code)

Cursor

VS Code (Copilot)

Windsurf

Codex CLI

ChatGPT / OpenAI

n8n Automation

Any MCP Client

Authentication

API Key

OAuth 2.1

x402 Payment

x402 Payment Flow for MCP

Available Tools

Catalog & Discovery

Options Backtests

Dated Futures

Perpetuals

Options

Volatility Surface

Spot

Prediction Markets

Hyperliquid - HyperCore

Macro & Analytics

Protocol Examples

1. Initialize

2. List Tools

3. Call a Tool

Example Prompts

Troubleshooting

406 Not Acceptable

401 Unauthorized

Couldn't register / Unknown client_id

429 Too Many Requests

402 Payment Required

Duplicate tools / won't connect

npx not found

`406 Not Acceptable`

`401 Unauthorized`

`429 Too Many Requests`

`402 Payment Required`

`npx` not found