MCP / AI research clients

Ask the question in your own words.

Connect an AI research client to OptionSpace's data and research tools. Claude Code is the tested client; Claude Desktop and Cursor should work but are not yet tested. Your agent uses the same saved credential and account access as the Python package.

What runs where

The MCP server runs locally on your computer using stdio. Your AI client launches it when needed. There is no hosted OptionSpace chat service in this setup. Your AI client's own account or subscription is separate from your OptionSpace data access.

1. Finish package setup

Follow Getting started to install the package with the mcp extra and save your key. Then, in your research folder, check it and print your MCP setup:

uv run optionspace whoami
uv run optionspace mcp --print-config

The second command prints two things, ready to paste: the Claude Code command, and the configuration block for Claude Desktop and Cursor. Both point at your research folder's Python by its full path, because an AI client started from your desktop does not see your terminal's settings. Neither contains your API key; the server reads the key you saved at login.

2. Connect Claude Code

Claude Code must already be installed and signed in. Use a research folder outside your software repository: a new conversation inside an existing repository can still load that repository's instructions and memory.

Copy the line printed under Claude Code in step 1 and run it once. It looks like this (your path will differ):

claude mcp add optionspace -- /Users/you/optionspace-research/.venv/bin/python -m optionspace mcp

On Windows the path looks like C:\Users\you\optionspace-research\.venv\Scripts\python.exe. If an OptionSpace entry already exists, inspect it before replacing it.

Start Claude Code:

claude

Within Claude Code, use /mcp to check that optionspace is connected. Approve the client's normal tool-connection or invocation prompt when appropriate. You do not need to disable the client's permission system.

Do not run optionspace mcp as an interactive chat. It is a protocol process intended to be launched by the AI client. A blank terminal after running that command alone is not a place to type research questions.

Session-only configuration

Prefer not to register a server? Save the configuration block printed in step 1 as a file named optionspace-mcp.json in your research folder.

Then launch:

claude --mcp-config ./optionspace-mcp.json --strict-mcp-config

This session uses only the supplied MCP configuration; it does not change your saved global settings. No API key belongs in this JSON file.

Other AI clients

Tested: Claude Code is the client we test these workflows with. Should work, not yet tested: Claude Desktop and Cursor. Both launch local MCP servers from the same kind of configuration, so the setup below should work, but we have not validated it yet. If you try one, tell us how it went at [email protected].

In each case, paste the configuration block that uv run optionspace mcp --print-config printed in step 1. No API key belongs in either file; the server reads your saved credential.

Claude Desktop (should work, not yet tested)

Open Settings → Developer → Edit Config in Claude Desktop, or edit its config file directly (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS). Add OptionSpace under mcpServers, keeping any servers already listed. The block looks like this, with your own path:

{
  "mcpServers": {
    "optionspace": {
      "command": "/Users/you/optionspace-research/.venv/bin/python",
      "args": ["-m", "optionspace", "mcp"]
    }
  }
}

Quit and reopen Claude Desktop. OptionSpace's tools should then appear in the conversation's tool list.

Cursor (should work, not yet tested)

Create .cursor/mcp.json in your research folder (or .cursor/mcp.json in your home folder to make it available in every project) with the same block:

{
  "mcpServers": {
    "optionspace": {
      "command": "/Users/you/optionspace-research/.venv/bin/python",
      "args": ["-m", "optionspace", "mcp"]
    }
  }
}

Then check Cursor Settings → MCP for a connected optionspace server.

For a named profile, run uv run optionspace mcp --print-config --profile NAME; the setup it prints carries the profile.

3. Ask your first questions

Start with access discovery:

What data can I access through OptionSpace?

Then try a specific historical question within your grant:

What's the SPY and NVDA skew on 2025-04-10 for the expiry on 2025-04-17? How much did it change from the previous day?

Show me a chart of the ATM vol term structure for SPY on 2025-04-09 and 2025-04-10.

What's the percentile and z-score of a 15-delta SPY 1 DTE option at 9:45am on 2025-04-10, with a one-year lookback?

For the last question, expect the agent to clarify the option side and metric. You can answer “The put, implied volatility.” That clarification selects the exposure you mean; the agent should not guess it.

Watch the recorded terminal sessions.

What the tools can do

You can ask the assistant about OptionSpace too, for example "what does vrp_clean mean?" or "why was my call refused with 429?". It looks the answer up in this documentation, which comes with the package, and gives you the link.

Research tools return structured data and paths to generated interactive HTML charts. Open the returned local path in your browser. Whether a client embeds a chart directly depends on that client; MCP connectivity alone does not guarantee an inline chart viewer.

Start with the interactive research charts. PNG and video export use additional dependencies; see rendering troubleshooting.

Continue from your phone

Claude Remote Control lets you use a local Claude Code session from the Claude mobile app or a browser. Your computer continues to run Python, MCP and file operations; it must remain awake and connected for work to proceed.

1. Start your configured Claude Code research session on the computer.
2. Inside Claude Code, type /remote-control and accept its connection confirmation.
3. Open the displayed session link or QR code on your phone, using the same Claude account.
4. Continue asking questions and approving tool calls from your phone.

See Claude's Remote Control instructions for account eligibility and connection troubleshooting. Keep the session in its isolated research folder if you are evaluating without project context.

A local HTML chart on your computer is not automatically a phone-accessible web page. Chart sharing and viewing need to be checked separately. An independent hosted OptionSpace client or remote MCP service, usable while your computer is off, is not part of the current local setup.

Access, usage and answer quality

The agent cannot bypass your key's permissions. A term comparison or replay can make multiple underlying API requests; an answer is not necessarily one request. Each tool's cost reports the OptionSpace credits the server charged (OptionSpace credits are your data allowance, not your AI client's billing). A long research tool call waits for its background job. Check usage with uv run optionspace whoami.

Keep the returned instrument, date, snapshot, expiry and coverage with the answer. Inspect the tool result when a number matters. Agent prose can make interpretation errors even when the underlying data is correct. Missing observations should remain visible, rather than being replaced with a confident guess.

Never paste the API key into the agent conversation. For a named profile, print the setup with uv run optionspace mcp --print-config --profile NAME and check it with uv run optionspace whoami --profile NAME. Claude Code is the client we test these workflows with. Claude Desktop and Cursor should work but are not yet tested; see other AI clients.

Ask for intraday earnings detail

Overlay NVDA's earnings volatility before its last eight reports, as of September 16, 2026. Show five-minute detail.

Show NVDA ATM volatility with and without earnings at five-minute intervals from April 1 through September 16, 2026.

The tools support granularity="5m" when your key permits it. Estimates are matched to each observation's timestamp. Excluded or unavailable observations remain gaps; the historical priced-versus-realized comparison retains its end-of-day anchor.

For a backtest, ask: “Show the position’s P&L and delta at every one-minute snapshot.” The tool supports granularity="1m" when your access allows it; the execution rules remain unchanged.