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.

Keep API tokens out of committed project files. Prefer user-level client config or environment variables; if you use a workspace config file, add it to .gitignore.

Available Tools

Once connected, your AI assistant can use these tools:

Available resources:

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: [email protected]
     X-USER-TOKEN: your-api-token
     

4. Restart Cursor

Option B: Project-level config

Only use project-level config if the file is excluded from source control. Prefer your editor’s user-level MCP settings when available.

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

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

Restart Cursor after saving.

Add .cursor/mcp.json to your project .gitignore if you use this option.

VS Code (GitHub Copilot)

Create .vscode/mcp.json in your workspace only if it is excluded from source control:

{
  "servers": {
    "optionomics": {
      "type": "http",
      "url": "https://optionomics.ai/mcp",
      "headers": {
        "X-USER-EMAIL": "[email protected]",
        "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.

Add .vscode/mcp.json to .gitignore if the file contains credentials.

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": "[email protected]",
        "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": "[email protected]",
        "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: [email protected]" \
  --header "X-USER-TOKEN: your-api-token" \
  optionomics https://optionomics.ai/mcp

Option B: settings.json

Prefer user-level ~/.gemini/settings.json. If you use project-level .gemini/settings.json, exclude it from source control:

{
  "mcpServers": {
    "optionomics": {
      "url": "https://optionomics.ai/mcp",
      "headers": {
        "X-USER-EMAIL": "[email protected]",
        "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
import os

client = OpenAI()

email = os.environ["OPTIONOMICS_EMAIL"]
token = os.environ["OPTIONOMICS_TOKEN"]
credentials = base64.b64encode(f"{email}:{token}".encode()).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). The encoded value is equivalent to your raw API token, so keep it secret.

printf "%s:%s" "$OPTIONOMICS_EMAIL" "$OPTIONOMICS_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: [email protected]" \
  -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

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.