MCP Server

Connect AI assistants to real-time options intelligence

Optionomics supports the Model Context Protocol (MCP), letting you connect your favorite AI assistant directly to institutional-grade options data. Ask questions in natural language and get real-time stock quotes, options flow, gamma exposure, dark pool levels, and more — all without leaving your AI tool.

Requirements: A Vega subscription on Optionomics.

What You’ll Need

Before configuring any client, grab your credentials from the Optionomics dashboard:

  1. Email — the email address on your Vega account
  2. API Token — your authentication token (found in Account → API Keys)

These credentials are used in every client configuration below.

Available Tools

Once connected, your AI assistant can use these tools:

Tool Description
Stock Quote Current or historical OHLC, volume, and price change for any tracked symbol
Options Chain Full chain with Greeks (delta, gamma, theta, vega), strikes, prices, and OI
Option Metrics Put/call ratio, IV rank/percentile, GEX, DEX, max pain, call/put walls
Options Flow Aggregated bullish/bearish flow, top calls, top puts
Net Flow Cumulative call/put premium timeseries with resolution and DTE filters
Unusual Activity High-premium, high-volume alerts indicating institutional activity
Dark Pool Levels Support/resistance levels derived from large dark pool prints
Support & Resistance Key levels derived from options flow activity
Market Overview Major indices (SPY, QQQ, DIA, IWM) prices, changes, and volume

Available resources:

Resource Description
Available Symbols List of all tracked stock symbols
Trading Days List of available trading dates

Cursor

Cursor natively supports remote MCP servers with custom headers.

Option A: Settings UI

  1. Open Settings → Tools & MCP
  2. Click Add new MCP server
  3. Fill in:
    • Name: optionomics
    • Type: streamableHttp
    • URL: https://optionomics.ai/mcp
    • Headers: 
      X-USER-EMAIL: your-email@example.com
X-USER-TOKEN: your-api-token
  4. Restart Cursor

Option B: Project-level config

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "optionomics": {
      "type": "streamableHttp",
      "url": "https://optionomics.ai/mcp",
      "headers": {
        "X-USER-EMAIL": "your-email@example.com",
        "X-USER-TOKEN": "your-api-token"
      }
    }
  }
}

Restart Cursor after saving.

VS Code (GitHub Copilot)

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "optionomics": {
      "type": "http",
      "url": "https://optionomics.ai/mcp",
      "headers": {
        "X-USER-EMAIL": "your-email@example.com",
        "X-USER-TOKEN": "your-api-token"
      }
    }
  }
}

Then open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P), run MCP: List Servers, and start the Optionomics server.

Claude Desktop

Claude Desktop uses local stdio transports for MCP. To connect to a remote server, use the mcp-remote bridge.

Prerequisites: Node.js 18+ installed.

Edit your Claude Desktop config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json

(Access via Claude Desktop → Settings → Developer → Edit Config)

{
  "mcpServers": {
    "optionomics": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://optionomics.ai/mcp",
        "--header",
        "X-USER-EMAIL:${OPTIONOMICS_EMAIL}",
        "--header",
        "X-USER-TOKEN:${OPTIONOMICS_TOKEN}"
      ],
      "env": {
        "OPTIONOMICS_EMAIL": "your-email@example.com",
        "OPTIONOMICS_TOKEN": "your-api-token"
      }
    }
  }
}

Restart Claude Desktop completely (quit and reopen, not just close the window). Look for the hammer icon to confirm tools are loaded.

Windsurf

Option A: Settings UI

  1. Open the Command Palette (Cmd+Shift+P / Ctrl+Shift+P)
  2. Run Windsurf: Configure MCP Servers
  3. Add the configuration below

Option B: Manual config

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "optionomics": {
      "serverUrl": "https://optionomics.ai/mcp",
      "headers": {
        "X-USER-EMAIL": "your-email@example.com",
        "X-USER-TOKEN": "your-api-token"
      }
    }
  }
}

Restart Windsurf after saving.

Gemini CLI

Option A: CLI command

gemini mcp add \
  --transport http \
  --header "X-USER-EMAIL: your-email@example.com" \
  --header "X-USER-TOKEN: your-api-token" \
  optionomics https://optionomics.ai/mcp

Option B: settings.json

Edit .gemini/settings.json in your project (or ~/.gemini/settings.json for user-level):

{
  "mcpServers": {
    "optionomics": {
      "url": "https://optionomics.ai/mcp",
      "headers": {
        "X-USER-EMAIL": "your-email@example.com",
        "X-USER-TOKEN": "your-api-token"
      }
    }
  }
}

ChatGPT

ChatGPT supports remote MCP connectors for Pro, Team, and Enterprise plans.

  1. Open Settings → Apps & Connectors → Advanced settings
  2. Enable Developer Mode
  3. Click Add Connector
  4. Enter:
    • Name: Optionomics
    • URL: https://optionomics.ai/mcp

Authentication note: ChatGPT currently requires OAuth for authenticated connectors. Optionomics uses header-based authentication, which is not yet supported in ChatGPT’s connector UI. We are monitoring OpenAI’s MCP roadmap and will update this guide when bearer/header auth is supported.

As a workaround, you can use Optionomics MCP through the OpenAI API (Responses API) programmatically:

from openai import OpenAI
import base64

client = OpenAI()

credentials = base64.b64encode(b"your-email@example.com:your-api-token").decode()

response = client.responses.create(
    model="gpt-4o",
    tools=[{
        "type": "mcp",
        "server_label": "optionomics",
        "server_url": "https://optionomics.ai/mcp",
        "headers": {
            "Authorization": f"Bearer {credentials}"
        }
    }],
    input="What's the current options flow sentiment for SPY?"
)

print(response.output_text)

Bearer Token Authentication

Some clients only support Authorization: Bearer headers. Optionomics accepts this format too — encode your credentials as base64(email:token):

echo -n "your-email@example.com:your-api-token" | base64

Then use the result as a Bearer token:

Authorization: Bearer eW91ci1lbWFpbEBleGFtcGxlLmNvbTp5b3VyLWFwaS10b2tlbg==

This works with any client that supports the Authorization header.

Verifying Your Connection

Test your credentials with curl before configuring a client:

curl -s -w "\n%{http_code}" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-USER-EMAIL: your-email@example.com" \
  -H "X-USER-TOKEN: your-api-token" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' \
  https://optionomics.ai/mcp

Expected responses:

  • 200 with a JSON body — connection successful
  • 401 — invalid email or token
  • 403 — valid credentials but no Vega subscription

Example Prompts

Once connected, try these prompts in your AI assistant:

  • “What’s the current put/call ratio and IV rank for SPY?”
  • “Show me the top 10 unusual options activity alerts today, excluding ETFs”
  • “Get the options chain for TSLA with calls only, sorted by strike”
  • “What are the dark pool support and resistance levels for AAPL?”
  • “Compare the bullish vs bearish flow for QQQ over the last week”
  • “Give me a market overview of major indices”
  • “What symbols does Optionomics track?”

Troubleshooting

Issue Solution
401 Unauthorized Verify your email and API token are correct. Check for extra spaces or newlines.
403 Forbidden Your account needs a Vega subscription. Upgrade here.
Connection timeout Ensure your network allows HTTPS connections to optionomics.ai.
Tools not appearing Restart the client completely (quit and reopen). Check server status in client settings.
524 Timeout on GET This is expected — Optionomics uses Streamable HTTP (POST only), not SSE. Your client should use POST.
Empty response body Ensure your client is using streamableHttp transport type, not legacy SSE.

Security Notes

  • Never commit your API token to version control. Use environment variables or .gitignore‘d config files.
  • Your API token authenticates as your user account. Treat it like a password.
  • All connections are encrypted over HTTPS/TLS.
  • MCP access is restricted to Vega subscribers only.

Related Docs

Optionomics Documentation

Getting Started
Main Features
Daily Analytics
Historical Analytics

Optionomics Documentation