MCP Server

Connect AI assistants to real-time options intelligence

Optionomics supports the Model Context Protocol (MCP), letting compatible AI clients call a defined set of read-only market-data tools. You can ask for quotes, options chains, flow, market context, historical prices, earnings, news, and other supported resources without giving the client write access to your Optionomics account.

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: your-email@example.com
     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": "your-email@example.com",
        "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": "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.

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": "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

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": "your-email@example.com",
        "X-USER-TOKEN": "your-api-token"
      }
    }
  }
}

Client compatibility

The configurations above were reviewed in July 2026. MCP client settings can change independently of Optionomics, so use the client’s current documentation if a menu name or configuration key has moved.

The ChatGPT connector interface currently requires an authentication method that is not compatible with Optionomics’ email-and-token headers. Do not add the Optionomics endpoint to that interface until this guide lists a supported setup.

If a client cannot send both X-USER-EMAIL and X-USER-TOKEN headers to a remote Streamable HTTP server, it is not currently compatible with Optionomics MCP.

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.