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 creates a paper-trading account with a starting balance of $10,000.00.

Quick start

# 1. Install the Joyride alpha package you received from the team
#    Verify both binaries work:
joyride --help
command -v joyride-mcp

# 2. Create or import a wallet
joyride setup

# 3. Export the passphrase used for your local keystore
export JOYRIDE_KEYSTORE_PASSWORD="your-passphrase"

# 4. Add the MCP server to your AI tool (see setup sections below)

# 5. 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
A Joyride wallet — created via joyride wallet create or joyride setup
MCP server executable — joyride-mcp available on your PATH

Setup: Claude Code

Step 1: Create `.mcp.json` in your project root

{
  "mcpServers": {
    "joyride": {
      "command": "joyride-mcp",
      "args": [],
      "env": {
        "JOYRIDE_WS_URL": "wss://joyride.exchange/api/v1",
        "JOYRIDE_HTTP_URL": "https://joyride.exchange/api",
        "JOYRIDE_KEYSTORE_PASSWORD": "<your-keystore-passphrase>"
      }
    }
  }
}

Use the passphrase you chose when creating your wallet. The .mcp.json file contains your keystore passphrase, so it should stay out of source control. Add it to .gitignore if the config lives in a repo.

Step 2: Restart Claude Code

Exit your current session (/exit or Ctrl+C) and start a new one:

claude

Step 3: Verify

Run /mcp in Claude Code. You should see:

joyride · ✔ connected

Step 4: Test

Ask Claude:

List available SOL instruments

Claude will call list_instruments and show you the results.

Setup: Other MCP clients

The MCP server runs as a local process over stdio (stdin/stdout). Any MCP-compatible client can launch it.

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "joyride": {
      "command": "joyride-mcp",
      "args": [],
      "env": {
        "JOYRIDE_WS_URL": "wss://joyride.exchange/api/v1",
        "JOYRIDE_HTTP_URL": "https://joyride.exchange/api",
        "JOYRIDE_KEYSTORE_PASSWORD": "<your-keystore-passphrase>"
      }
    }
  }
}

VS Code Copilot

Add to .vscode/mcp.json in your project:

{
  "servers": {
    "joyride": {
      "command": "joyride-mcp",
      "args": [],
      "env": {
        "JOYRIDE_WS_URL": "wss://joyride.exchange/api/v1",
        "JOYRIDE_HTTP_URL": "https://joyride.exchange/api",
        "JOYRIDE_KEYSTORE_PASSWORD": "<your-keystore-passphrase>"
      }
    }
  }
}

Generic / custom agents

Launch the server directly over stdio:

JOYRIDE_WS_URL=wss://joyride.exchange/api/v1 \
JOYRIDE_HTTP_URL=https://joyride.exchange/api \
JOYRIDE_KEYSTORE_PASSWORD=your-passphrase \
joyride-mcp

It speaks JSON-RPC over stdin/stdout per the MCP specification.

Codex and other experimental MCP clients

If a client supports launching local stdio MCP servers but uses a different config format than Claude Code or Cursor, keep the Joyride portion of the configuration the same:

command: joyride-mcp
env:
- JOYRIDE_WS_URL=wss://joyride.exchange/api/v1
- JOYRIDE_HTTP_URL=https://joyride.exchange/api
- JOYRIDE_KEYSTORE_PASSWORD=<your-keystore-passphrase>

Treat Codex and other non-validated MCP clients as experimental until you have confirmed tool discovery, wallet auth, and at least one read-only prompt end to end.

Client support

Client	Status
Claude Code	Supported and tested
Cursor	Supported and tested
VS Code Copilot	Configuration documented; validate before broad alpha rollout
OpenClaw	Requires the local wallet-based config from the repo collateral
Codex	Experimental; use the generic stdio MCP pattern and validate before calling it supported

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 .mcp.json)
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
`JOYRIDE_KEYSTORE_PASSWORD`	—	Passphrase to decrypt wallet keystore
`JOYRIDE_PRIVATE_KEY`	—	Base58 private key (bypasses keystore)

Set JOYRIDE_KEYSTORE_PASSWORD or JOYRIDE_PRIVATE_KEY in your .mcp.json env block. The MCP server runs non-interactively and cannot prompt for a passphrase.

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`

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 2>&1 | head -20

Common causes:

joyride-mcp is not on your PATH
Wallet credentials are missing from MCP env config
Node.js version too old — requires >= 20.0.0

`NOT_AUTHENTICATED` errors

The MCP server needs wallet credentials. Make sure your .mcp.json includes either JOYRIDE_KEYSTORE_PASSWORD (to decrypt the keystore created by joyride wallet create) or JOYRIDE_PRIVATE_KEY (Base58 key directly). The passphrase must match the one you used when creating the wallet. Check which wallet is active with joyride wallet show.

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.

CLI/MCP package version mismatch

If MCP tools error after a CLI upgrade, update both the Joyride CLI and MCP server packages so they are on compatible versions.

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_KEYSTORE_PASSWORD=your-passphrase \
joyride-mcp 2>mcp-debug.log

Check mcp-debug.log for connection warnings and errors.

Guides

​What it exposes

​Quick start

​Prerequisites

​Setup: Claude Code

​Step 1: Create .mcp.json in your project root

​Step 2: Restart Claude Code

​Step 3: Verify

​Step 4: Test

​Setup: Other MCP clients

​Cursor

​VS Code Copilot

​Generic / custom agents

​Codex and other experimental MCP clients

​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 errors

​Gateway connection warning

​Permission prompts on every tool call

​CLI/MCP package version mismatch

​Quotes show all nulls

​Debug mode