MCP Server Guide - Joyride Docs

What it exposes

The MCP server gives AI agents access to the Joyride options exchange through 23 tools, 3 resources, and 3 prompts — covering market data, trading, account management, wallet creation, and position analysis. An AI agent can look up options chains, get quotes, place and cancel orders, check balances, and analyze positions — all through natural language. You talk to the agent; the agent calls the tools. Current mode: Paper trading only. No real money at risk. The first successful Joyride authentication seeds your paper-trading account with $10,000.00 in paper USDC. This auto-seed is active until the Season 1 competition launches on 2026-05-05 UTC; after launch, funding requires an invite code.

Quick start

# 1. Install the Joyride CLI (includes the MCP server)
npm install -g joyride-cli

# 2. Verify it installed
joyride --help

# 3. Run the setup wizard (creates a wallet)
joyride setup

# 4. Log in (authenticates with the exchange, stores a JWT)
joyride login

# 5. Configure your AI tool (pick one):
joyride mcp install --client claude    # Claude Code
joyride mcp install --client cursor    # Cursor
joyride mcp install --client codex     # Codex

# 6. Restart your AI tool and start trading
#    "List available SOL instruments"
#    "Get a quote for SOL_USDC-3MAR26-75-C"
#    "Place a limit sell for 1 contract at $5"

For the full guided flow, start with Agent Quickstart.

Prerequisites

Node.js >= 20.0.0
The Joyride CLI — npm install -g joyride-cli (this installs both the CLI and MCP server)
A Joyride wallet — created via joyride wallet create or joyride setup
An active session — run joyride login (stores a JWT at ~/.joyride/session.json)

The MCP server reads the stored JWT from ~/.joyride/session.json on startup. No keypair path or passphrase is needed in the MCP config. If the session is expired or missing, the server exits with: “Not authenticated. Run joyride login first.”

Setup by client

Claude Code

The fastest way:

joyride mcp install --client claude

This runs claude mcp add under the hood and configures everything automatically. To verify, run /mcp inside Claude Code. You should see:

joyride · connected

Manual setup (if you prefer editing config directly): Create .mcp.json in your project root:

{
  "mcpServers": {
    "joyride": {
      "command": "joyride",
      "args": ["mcp", "serve"],
      "env": {
        "JOYRIDE_WS_URL": "wss://joyride.exchange/api/v1",
        "JOYRIDE_HTTP_URL": "https://joyride.exchange/api"
      }
    }
  }
}

Then restart Claude Code.

Cursor

The fastest way:

joyride mcp install --client cursor

This writes the correct entry to ~/.cursor/mcp.json automatically, preserving any existing MCP servers you have configured. Manual setup: Add to ~/.cursor/mcp.json (create the file if it doesn’t exist):

{
  "mcpServers": {
    "joyride": {
      "command": "joyride",
      "args": ["mcp", "serve"],
      "env": {
        "JOYRIDE_WS_URL": "wss://joyride.exchange/api/v1",
        "JOYRIDE_HTTP_URL": "https://joyride.exchange/api"
      }
    }
  }
}

Codex

joyride mcp install --client codex

This runs codex mcp add under the hood.

VS Code Copilot

No auto-install yet. Add to .vscode/mcp.json in your project:

{
  "servers": {
    "joyride": {
      "command": "joyride",
      "args": ["mcp", "serve"],
      "env": {
        "JOYRIDE_WS_URL": "wss://joyride.exchange/api/v1",
        "JOYRIDE_HTTP_URL": "https://joyride.exchange/api"
      }
    }
  }
}

Generic / custom agents

Launch the MCP server directly over stdio:

JOYRIDE_WS_URL=wss://joyride.exchange/api/v1 \
JOYRIDE_HTTP_URL=https://joyride.exchange/api \
joyride mcp serve

It speaks JSON-RPC over stdin/stdout per the MCP specification. Authentication is handled via the stored JWT at ~/.joyride/session.json.

Reconfiguring and uninstalling

Update an existing configuration

If you need to reconfigure (e.g., after changing connection URLs):

joyride mcp install --client claude --force

The --force flag removes the existing config and writes a fresh one.

Remove MCP from a client

joyride mcp uninstall --client claude    # Claude Code
joyride mcp uninstall --client cursor    # Cursor
joyride mcp uninstall --client codex     # Codex

Uninstall is safe to run even if joyride is not currently configured — it’s a no-op. For Cursor, uninstall removes only the joyride entry from ~/.cursor/mcp.json and preserves all other MCP servers.

Uninstall the CLI entirely

npm uninstall -g joyride-cli

This removes both the CLI and the bundled MCP server.

Client support

Client	Auto-install	Status
Claude Code	`joyride mcp install --client claude`	Supported and tested
Cursor	`joyride mcp install --client cursor`	Supported and tested
Codex	`joyride mcp install --client codex`	Supported and tested
VS Code Copilot	Manual config (see above)	Configuration documented

Hosted HTTP mode (preview)

Joyride also exposes an HTTP MCP endpoint for remote agent access, but this path should be treated as preview for now:

Base URL: https://joyride.exchange/api/v1/mcp
Transport: Streamable HTTP
Auth: Bearer token / API key mapping on the server side

Use hosted MCP only if Joyride has explicitly issued you a hosted API key and setup instructions. For early alpha testers, the supported path is the local stdio flow above.

Auto-approve permissions

By default, Claude Code asks permission before calling each MCP tool. To skip prompts for Joyride tools, add them to .claude/settings.json:

{
  "permissions": {
    "allow": [
      "mcp__joyride__list_instruments",
      "mcp__joyride__get_quote",
      "mcp__joyride__get_orderbook",
      "mcp__joyride__get_options_chain",
      "mcp__joyride__get_ticker",
      "mcp__joyride__get_all_tickers",
      "mcp__joyride__get_price_history",
      "mcp__joyride__get_market_config",
      "mcp__joyride__get_index_price",
      "mcp__joyride__get_greeks",
      "mcp__joyride__place_order",
      "mcp__joyride__cancel_order",
      "mcp__joyride__cancel_all_orders",
      "mcp__joyride__get_open_orders",
      "mcp__joyride__get_order_status",
      "mcp__joyride__get_balance",
      "mcp__joyride__get_account",
      "mcp__joyride__get_positions",
      "mcp__joyride__get_positions_with_metrics",
      "mcp__joyride__get_trade_history",
      "mcp__joyride__get_order_history",
      "mcp__joyride__create_wallet",
      "mcp__joyride__get_profiles"
    ]
  }
}

Tip for live trading: Remove place_order, cancel_order, and cancel_all_orders from the allow list so those still require manual confirmation.

Tool reference

All tools accept and return human-friendly units:

Prices in USD (e.g., 5.00) — converted to/from USDC micros internally
Sizes in contracts (e.g., 1, 0.5) — converted to/from millicontracts internally
Sides as "buy" / "sell" — mapped to "bid" / "ask" internally

Market data (8 tools)

`list_instruments`

List available options contracts with optional filters.

Parameter	Type	Required	Description
`asset`	string	No	Filter by asset (`"SOL"`, `"BTC"`, `"ETH"`)
`expiry`	string	No	Filter by expiry date (`"3MAR26"`)
`type`	`"call"` \| `"put"`	No	Filter by option type

Example prompt: “List all SOL call options” Transport: WebSocket

`get_quote`

Get real-time bid/ask/mid quote for a specific instrument.

Parameter	Type	Required	Description
`instrument_id`	string	Yes	e.g., `SOL_USDC-3MAR26-75-C`

Returns: { bid, ask, mid, spread } — all in USD. Returns null for empty sides. Transport: WebSocket

`get_orderbook`

Get full order book depth for a specific instrument.

Parameter	Type	Required	Description
`instrument_id`	string	Yes	Instrument ID
`depth`	number	No	Price levels per side (default: 10)

Returns: { bids: [{price, size, count}], asks: [{price, size, count}] } Transport: HTTP

`get_options_chain`

Get all options for an asset organized by strike (calls and puts side by side).

Parameter	Type	Required	Description
`asset`	string	Yes	`"SOL"`, `"BTC"`, `"ETH"`
`expiry`	string	No	Filter by expiry date

Returns: { asset, expiry, strikes: [{ strike, call?, put? }] } Transport: WebSocket + HTTP

`get_ticker`

Get ticker snapshot for a specific instrument.

Parameter	Type	Required	Description
`instrument_id`	string	Yes	Instrument ID

Returns: { bestBid, bestBidSize, bestAsk, bestAskSize, spread } Transport: HTTP

`get_all_tickers`

Get all tickers in one call. Returns: Array of { instrumentId, bestBid, bestAsk, midPrice, spotPrice } Transport: HTTP

`get_price_history`

Get historical price data for a specific instrument.

Parameter	Type	Required	Description
`instrument_id`	string	Yes	Instrument ID
`start`	number	No	Start timestamp (Unix seconds)
`end`	number	No	End timestamp (Unix seconds)

Returns: Array of { timestamp, bidPrice, askPrice, midPrice, spotPrice } Transport: HTTP

`get_market_config`

Get market configuration (round duration and epoch). Returns: { roundDurationHours, roundEpoch } Transport: HTTP

Trading (5 tools)

All trading tools require wallet authentication.

`place_order`

Place a limit or market order.

Parameter	Type	Required	Description
`instrument_id`	string	Yes	Instrument ID
`side`	`"buy"` \| `"sell"`	Yes	Order side
`type`	`"limit"` \| `"market"`	No	Default: `"limit"`
`price`	number	For limit	Limit price in USD (e.g., `5.00`)
`size`	number	Yes	Number of contracts (e.g., `1`, `0.5`)

Returns: { order: {orderId, status, ...}, trades: [{tradeId, price, size, ...}] } Example prompts:

“Sell 1 contract of SOL_USDC-3MAR26-75-C at $5”
“Buy 2 contracts of SOL_USDC-3MAR26-75-P at market”

Transport: WebSocket

`cancel_order`

Cancel a specific order.

Parameter	Type	Required	Description
`instrument_id`	string	Yes	Instrument ID
`order_id`	number	Yes	Order ID to cancel

Transport: WebSocket

`cancel_all_orders`

Cancel all open orders, optionally for a specific instrument.

Parameter	Type	Required	Description
`instrument_id`	string	No	Cancel only orders for this instrument

Returns: { count, orders: [...] } Transport: WebSocket

`get_open_orders`

List all active/open orders. Returns: Array of { orderId, instrumentId, side, orderType, price, size, remaining, status, timestamp } Transport: WebSocket

`get_order_status`

Check the status of a specific order. Searches open orders first, then falls back to order history.

Parameter	Type	Required	Description
`order_id`	number	Yes	Order ID to look up

Transport: WebSocket + HTTP (fallback)

Account (6 tools)

All account tools require wallet authentication.

`get_balance`

Get current account balance. Returns: { available, locked, total } — all in USD. Transport: WebSocket

`get_account`

Get full account summary (balance and positions). Returns: { available, locked, positions: [{instrumentId, quantity, avgPrice}] } Transport: HTTP

`get_positions`

Get all open positions. Returns: Array of { instrumentId, quantity, avgPrice } Transport: HTTP

`get_positions_with_metrics`

Get positions enriched with PnL metrics. Returns: Array of { instrumentId, quantity, avgPrice, midPrice, currentValue, pnl, pnlPercent, breakeven } Transport: HTTP

`get_trade_history`

Get recent trade fills/executions.

Parameter	Type	Required	Description
`limit`	number	No	Maximum number of trades to return

Transport: HTTP

`get_order_history`

Get all orders including filled and cancelled.

Parameter	Type	Required	Description
`limit`	number	No	Maximum number of orders to return

Transport: HTTP

`create_wallet`

Create a new Solana wallet for trading. The wallet is encrypted and stored on the server. Returns the wallet address. Transport: HTTP

`get_profiles`

Get all user profiles (usernames and avatars). Transport: HTTP

Analysis (2 tools)

`get_index_price`

Get the underlying spot/index price for an asset.

Parameter	Type	Required	Description
`asset`	string	Yes	`"SOL"`, `"BTC"`, `"ETH"`

Returns: { asset, price, timestamp } Transport: HTTP

`get_greeks`

Get Greeks (delta, gamma, theta, vega, rho), implied volatility, and mark price for an instrument.

Parameter	Type	Required	Description
`instrument_id`	string	Yes	Instrument ID

Transport: HTTP (risk engine)

Resources

MCP resources provide read-only data snapshots that clients can request.

URI	Description
`joyride://portfolio`	Current positions, PnL, and account summary
`joyride://markets`	Available instruments with current bid/ask/mid/spot
`joyride://config`	Connection status, trading mode, server version

Resources return JSON. They’re useful for MCP clients that support resource browsing.

Prompts

MCP prompts are pre-built multi-step workflows that guide the AI agent through structured analysis.

`analyze-position`

Analyze a specific options position: Greeks, PnL scenarios, and risk assessment.

Argument	Type	Description
`instrument_id`	string	Instrument ID to analyze

`find-opportunity`

Find the best 0DTE options opportunity for an asset.

Argument	Type	Description
`asset`	string	Asset to analyze (`"SOL"`, `"BTC"`, `"ETH"`)

`build-strategy`

Construct an options strategy based on market outlook (analysis only — each leg must be executed as a separate place_order call).

Argument	Type	Description
`asset`	string	Asset to build strategy for
`outlook`	string	`"bullish"`, `"bearish"`, `"neutral"`, `"volatile"`

Instrument ID format

All instrument IDs follow this pattern:

{ASSET}_USDC-{DMMMYY}-{STRIKE}-{C|P}

Component	Description	Examples
`ASSET`	Underlying asset	`SOL`, `BTC`, `ETH`
`DMMMYY`	Expiry date (1- or 2-digit day)	`3MAR26`, `27FEB26`
`STRIKE`	Strike price (integer USD)	`75`, `100`, `200`
`C\|P`	Option type	`C` (call), `P` (put)

Use list_instruments to discover valid IDs. Instruments are 0DTE (same-day expiry) and refresh daily.

Configuration

The MCP server loads configuration in this order (highest priority first):

Environment variables (set in your MCP client config or shell)
Config file (~/.joyride/config.toml)
Defaults

Environment variables

Variable	Default	Description
`JOYRIDE_WS_URL`	`wss://joyride.exchange/api/v1`	WebSocket URL
`JOYRIDE_HTTP_URL`	`https://joyride.exchange/api`	HTTP REST URL

Authentication is handled via the stored JWT at ~/.joyride/session.json (created by joyride login). No credential-related env vars are needed in the MCP config.

Config file

The MCP server shares ~/.joyride/config.toml with the CLI. Run joyride setup to create it interactively:

[auth]
wallet_address = "GmQozSzrtMjXt5F1Bed8Vrt55zCbiga8vDZr47RX9wC8"

[defaults]
asset = "SOL"
mode = "paper"

[connection]
ws_url = "wss://joyride.exchange/api/v1"
http_url = "https://joyride.exchange/api"

Example workflows

Discover and quote

You: What SOL options are available today?
Agent: [calls list_instruments] -> 72 instruments

You: Get a quote on the $75 call
Agent: [calls get_quote] -> bid: $3.50, ask: $5.00, mid: $4.25

You: Show me the full options chain
Agent: [calls get_options_chain] -> organized by strike with calls/puts side by side

Place and manage orders

You: Sell 1 contract of the $75 call at $5
Agent: [calls place_order] -> Order #1994754 placed, status: open

You: Show my open orders
Agent: [calls get_open_orders] -> 1 open order

You: Cancel that order
Agent: [calls cancel_order] -> Order cancelled

You: Check my balance
Agent: [calls get_balance] -> Available: $10,000.00

Guided analysis (using prompts)

You: Find the best SOL opportunity right now
Agent: [uses find-opportunity prompt] -> ranks opportunities by risk/reward

You: Build a bullish strategy for SOL
Agent: [uses build-strategy prompt] -> suggests strategies with specific strikes and sizing

Troubleshooting

MCP server doesn’t appear in `/mcp`

Run joyride mcp install --client claude to configure automatically. If you set it up manually, the config must be in .mcp.json at the project root. Restart Claude Code after creating or editing it.

Server shows failed

Check the server logs:

joyride mcp serve 2>&1 | head -20

Common causes:

No valid session — run joyride login first
Node.js version too old — requires >= 20.0.0

The MCP server could not find a valid JWT at ~/.joyride/session.json. Run joyride login in your terminal to authenticate, then restart your MCP client.

`NOT_AUTHENTICATED` or session expired errors

Your JWT has expired. Run joyride login again to get a fresh session, then restart your MCP client.

Gateway connection warning

If you see Could not connect to gateway, the WS gateway is unreachable. The server starts in degraded mode — tools requiring WebSocket will return errors, but HTTP tools still work. Check that JOYRIDE_WS_URL is wss://joyride.exchange/api/v1.

Permission prompts on every tool call

See auto-approve permissions to pre-approve all Joyride tools.

Quotes show all nulls

The order book is empty. Use list_instruments to find instruments with activity.

Debug mode

JOYRIDE_WS_URL=wss://joyride.exchange/api/v1 \
JOYRIDE_HTTP_URL=https://joyride.exchange/api \
joyride mcp serve 2>mcp-debug.log

Check mcp-debug.log for auth status, connection warnings, and errors.

Guides

Documentation Index

​What it exposes

​Quick start

​Prerequisites

​Setup by client

​Claude Code

​Cursor

​Codex

​VS Code Copilot

​Generic / custom agents

​Reconfiguring and uninstalling

​Update an existing configuration

​Remove MCP from a client

​Uninstall the CLI entirely

​Client support

​Hosted HTTP mode (preview)

​Auto-approve permissions

​Tool reference

​Market data (8 tools)

​list_instruments

​get_quote

​get_orderbook

​get_options_chain

​get_ticker

​get_all_tickers

​get_price_history

​get_market_config

​Trading (5 tools)

​place_order

​cancel_order

​cancel_all_orders

​get_open_orders

​get_order_status

​Account (6 tools)

​get_balance

​get_account

​get_positions

​get_positions_with_metrics

​get_trade_history

​get_order_history

​Wallet & social (2 tools)

​create_wallet

​get_profiles

​Analysis (2 tools)

​get_index_price

​get_greeks

​Resources

​Prompts

​analyze-position

​find-opportunity

​build-strategy

​Instrument ID format

​Configuration

​Environment variables

​Config file

​Example workflows

​Discover and quote

​Place and manage orders

​Guided analysis (using prompts)

​Troubleshooting

​MCP server doesn’t appear in /mcp

​Server shows failed

​Not authenticated. Run joyride login first.

​NOT_AUTHENTICATED or session expired errors

​Gateway connection warning

​Permission prompts on every tool call

​Quotes show all nulls

​Debug mode