Theta Vantage MCP

Connect Cursor, Claude, Codex, Grok, and other remote MCP clients to Theta Vantage with the same Pro API key you use for /api/v1. The remote MCP server exposes one gateway data catalog — the same tools as Athena chat and GET /api/v1/tools. It is not a second API key or a second data product.

Pro only. Free keys get 403 INSUFFICIENT_TIER, the same as the REST API. Missing or invalid keys get 401. Most MCP HTTP requests (initialize, tools/list, and ordinary tools/call) share the REST data bucket: 60 requests per minute per key. Slow tools — get_fundamentals, get_earnings_calendar, get_iv_rank, get_wheel_strategy, get_income_projections, and search_x_discourse — use a separate 15/min mcp-heavy bucket, the same cadence as POST /api/v1/chat. Those calls may take up to about a minute; the route allows 180s.

Chat (POST /api/v1/chat) and the daily report (GET /api/v1/report) are not MCP tools. Use the REST API for those. They are orchestrators that consume Athena tokens; MCP runs individual tools as Pro data requests and does not debit the chat budget.

Agents should also read /.well-known/mcp and llms.txt.

Server URL

https://thetavantage.com/api/mcp

Remote Streamable HTTP. You paste this URL and a tvk_ key into Cursor, Claude, Codex, Grok, and other remote MCP clients. A local npx install is not required when the client supports remote MCP.

Authentication

Use the key from Account → API. Do not invent a second key type.

Header (recommended)

X-API-Key: tvk_YOUR_KEY

Bearer (also accepted) — some MCP clients only send Authorization:

Authorization: Bearer tvk_YOUR_KEY

Query (last resort) — same as REST api_key. Prefer a header; query strings show up in logs and browser history:

https://thetavantage.com/api/mcp?api_key=tvk_YOUR_KEY

Rate-limit headers on every authenticated response match REST: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Cursor

Edit ~/.cursor/mcp.json (or Cursor Settings → MCP):

{
  "mcpServers": {
    "theta-vantage": {
      "url": "https://thetavantage.com/api/mcp",
      "headers": {
        "X-API-Key": "tvk_YOUR_KEY"
      }
    }
  }
}

Save, then confirm get_stock_quote is listed. Ask: What is the quote for SPY?

Stdio-only builds can bridge with mcp-remote:

{
  "mcpServers": {
    "theta-vantage": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://thetavantage.com/api/mcp",
        "--header",
        "X-API-Key: tvk_YOUR_KEY"
      ]
    }
  }
}

Claude

Claude.ai custom connector: Settings → Connectors → add a custom connector. URL https://thetavantage.com/api/mcp. If the UI asks for a header, set X-API-Key to your tvk_ key (or Authorization Bearer tvk_YOUR_KEY). This is Pro-only; Free keys are rejected.

Claude Desktop (stdio): use the mcp-remote snippet above in claude_desktop_config.json.

Tools (v1)

One catalog. tools/list is the live GET /ai/tools snapshot (static fallback if the gateway catalog is down). tools/call is POST /ai/tools/execute. Results are compact JSON/CSV for model context — not full REST grids.

Folded REST names: there is no get_gex / get_vex / get_charm. Call get_greek_exposure with greek=gamma|vanna|charm. Delta (old DEX) is get_greek_heatmap with greek=delta. Live heatmaps are get_greek_heatmap; historical grids stay on REST GET /api/v1/heatmap/historical.

Pass a ticker as symbol unless the tool uses symbols, query, or username.

Not registered: chat, report, streaming quote sockets.

Quick check

With a Pro key, this initialize request should return JSON-RPC (not 401/403):

curl -sS -X POST "https://thetavantage.com/api/mcp" \
  -H "X-API-Key: tvk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'

A Free key on the same URL returns HTTP 403 with INSUFFICIENT_TIER. No key returns 401 MISSING_API_KEY.