MCP Server
Connect AI clients to Optionomics readings and market data
Optionomics runs a Model Context Protocol (MCP) server, so a compatible AI client—Claude, Cursor, VS Code with GitHub Copilot, ChatGPT, or anything else that speaks MCP—can call a defined set of read-only tools. Your assistant can ask how far a stock is priced to move, how it has moved through past earnings reports, and what the cheapest contract to trade is, and it can read quotes, options chains, flow, gamma exposure, unusual activity, news and events, insider and politician trades, trade ideas and their track record, and earnings analyses. Nothing the server offers can change anything in your Optionomics account.
- Endpoint:
https://optionomics.ai/mcp(Streamable HTTP) - Who can connect: any Optionomics account. Without the Developer plan your key is a free MCP key that reads the previous trading session (see Free key or Developer).
- Registry manifest:
https://optionomics.ai/.well-known/mcp/server.json
Free key or Developer
The same server answers both, and what a call returns depends on the plan of the account that owns the key.
| Free MCP key (any account) | Developer and Developer Pro | |
|---|---|---|
| Session read | The previous trading session. A date you ask for is moved back to the previous session if it is later; a call with no date reads the previous session. On a Tuesday you read Monday; over a weekend, Friday. | The live session, and any earlier date the data covers |
| Tools | expected_move, earnings_move, pulse, session_list, track_record, price_history, stock_quote, events |
Every tool in the table below |
| Requests per minute | 1,000 | 1,000 on Developer, 5,000 on Developer Pro |
A free key that calls a tool outside its list is not refused with an error code. The tool answers with a short message saying the tool needs the Developer plan and listing what the free key can read, so your assistant can tell you why it got no data.
The free key exists so you can put Optionomics readings inside your AI assistant’s answers before you subscribe. Live data, and the rest of the tools, come with the Developer plan. See Subscription Plans for prices.
What you’ll need
- Email — the email address on your Optionomics account.
- API key — created at optionomics.ai/developers/keys. Any signed-in account can create one; see API Key Management.
Every client configuration sends these two values as headers:
X-USER-EMAIL: your-email@example.com
X-USER-TOKEN: your-api-key
The email and the key must belong to the same account. Clients that can send only a single Authorization header (ChatGPT’s connector settings are one example) can use standard bearer syntax instead, with both values joined by a colon and base64-encoded:
Authorization: Bearer base64("your-email@example.com:your-api-key")
For example, in a shell: printf '%s' 'you@example.com:your-api-key' | base64.
Keep API keys out of committed project files. Prefer user-level client configuration or environment variables; if you use a workspace config file, add it to .gitignore.
The fastest path: the developer console’s MCP clients page at optionomics.ai/developers/clients generates the exact config for your client with your email already filled in, offers one-click install for Cursor and VS Code, and shows a Seen recently panel so you can confirm the connection end to end. It is open to any signed-in account. The install links and generated configs never contain your key—you paste it in yourself where the config says paste-your-api-key.
Available tools
These are the tools the server publishes today. Every tool is read-only.
Readings: size, odds, and cost
These tools return Optionomics’ own measured readings. Each one is about how far a stock is priced to move, how often a level is reached, or what a trade costs—none of them says which way a stock will go, and each tool’s description tells your assistant so.
| Tool | Free key | What it returns |
|---|---|---|
expected_move |
✅ | The options-implied expected move for a stock over 1 to 21 sessions: the calibrated move in percent and dollars, and the 50%, 68%, and 90% bands around the current price, with earnings flagged when a report falls inside a horizon. Arguments: symbol (required), date (optional). |
earnings_move |
✅ | The stock’s last eight earnings reactions beside the at-the-money straddle that priced each one: the implied move, the realised close-to-close and gap moves, how often the move ran outside the implied range, and the implied-volatility crush. For the current session only, it adds the model’s forecast reaction and crush for the next report, clearly labelled as a model forecast. Arguments: symbol (required), date (optional). |
vol_premium |
— | The model’s volatility forecast for a stock, current session only: 30-day at-the-money implied volatility and 21-day realised volatility, the forecast change in implied volatility over 5, 10, and 21 sessions, the forecast premium of implied over realised volatility at 10 and 21 sessions, and the simple rules it is judged against. No history is served. Argument: symbol. |
contract_chooser |
— | For a bullish view (calls) or a bearish view (puts), the cheapest single contracts to trade on the stored chain: strike, expiry, delta, bid, ask, mid, spread as a percentage of mid, a tradeability band (tradeable up to 5% of mid, expensive up to 15%, avoid beyond), and breakeven. Arguments: symbol and direction (bullish or bearish) required; horizon (scalp looks 0–5 days out near 0.50 delta, swing looks 21–63 days out near 0.45 delta; default swing), limit (1–5, default 3), date. It ranks by cost and says nothing about whether the view is right. |
pulse |
✅ | The options market’s pulse for a session, aggregated from the tape: premium, volume, and the call/put split for the session and the one before it, plus the ten symbols with the most option premium. Aggregates only, no individual trades. Argument: date (optional). |
session_list |
✅ | The session list behind the Market Overview’s names to watch: optionable stocks ranked by repricing—the next session’s priced move divided by the median of the stock’s own prior 20 sessions (2.0 means priced to move twice its norm)—with the move in percent and dollars, the 68% band, earnings timing, and the number of sessions behind the median. SPY, QQQ, and IWM come back separately. Arguments: date, limit (default 25), reporting (only names that report within one session). |
track_record |
✅ | The published trade-idea track record: rolling win rates, star ratings, and open counts for every strategy family. |
Market data and research
| Tool | Free key | What it returns |
|---|---|---|
stock_quote |
✅ | Regular-session daily open, high, low, close, volume, price change, and freshness information. Extended hours are excluded. |
price_history |
✅ | Daily OHLCV history with period return, drawdown, average volume, and realised volatility (lookback up to 180 calendar days). |
events |
✅ | Market-moving events by date window, ticker, kind, and status. The calendar is public, so a free key can see upcoming dates too. |
options_chain |
— | The options chain with Greeks: strikes, prices, volume, and open interest, with the expirations covered and how fresh the snapshot is. |
option_metrics |
— | Put/call ratio, implied volatility, gamma exposure (GEX), delta exposure (DEX), max pain, and key levels. |
options_flow |
— | Aggregated options flow: bullish flow, bearish flow, top calls, or top puts. |
net_flow |
— | A net call/put premium flow time series with resolution and days-to-expiration filters. |
unusual_activity |
— | Unusual options activity alerts—high-premium, high-volume trades—with an option to exclude ETFs. |
dark_pool_levels |
— | Dark pool support and resistance from large off-exchange prints over a 15-day lookback. |
support_resistance_levels |
— | Support and resistance levels derived from options flow. |
market_overview |
— | Major index proxies with prices, changes, and volume. |
gamma_exposure |
— | GEX levels, net dealer positioning, and support/resistance by strike. |
iv_term_structure |
— | The implied-volatility term structure, IV rank and percentile, and realised-versus-implied context. |
news |
— | Recent ticker or macro market headlines with summaries and source links. |
insider_trades |
— | SEC Form 4 insider trades with filters and pagination. |
politician_trades |
— | House, Senate, and OGE public disclosure trades with filters. |
trade_ideas |
— | Published trade ideas for a session with levels, lifecycle status, and each idea’s track record. |
earnings_analyses |
— | Analysed SEC filings: summary, sentiment, highlights, risks, guidance, and quarter-over-quarter comparison. |
The MCP console shows every tool’s full argument list, generated from the tool’s own schema.
Resources
| Resource | Description |
|---|---|
| Available Symbols | The list of tracked stock symbols |
| Trading Days | The trading-session calendar. Whether a particular symbol or dataset has data on a given day is reported in each tool’s own response. |
Each tool call counts against the same per-account request allowance as the REST API: 1,000 requests a minute, or 5,000 on Developer Pro. Two keys on one account share one allowance.
Claude Desktop
Edit your Claude Desktop config file (Claude Desktop → Settings → Developer → Edit Config):
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"optionomics": {
"type": "http",
"url": "https://optionomics.ai/mcp",
"headers": {
"X-USER-EMAIL": "you@example.com",
"X-USER-TOKEN": "paste-your-api-key"
}
}
}
}
Replace the email with your own and paste-your-api-key with your key. Restart Claude Desktop completely (quit and reopen, not just close the window), then confirm the Optionomics tools appear in the tools menu.
Claude Code
Create .mcp.json in your project root, checked in beside the code that uses it—but keep the key itself out of version control (for example, keep the file ignored, or use your client’s support for environment variables):
{
"mcpServers": {
"optionomics": {
"type": "http",
"url": "https://optionomics.ai/mcp",
"headers": {
"X-USER-EMAIL": "you@example.com",
"X-USER-TOKEN": "paste-your-api-key"
}
}
}
}
Cursor
Use the Install in Cursor one-click button on the MCP clients page, or create ~/.cursor/mcp.json (or .cursor/mcp.json for one project, excluded from source control):
{
"mcpServers": {
"optionomics": {
"type": "http",
"url": "https://optionomics.ai/mcp",
"headers": {
"X-USER-EMAIL": "you@example.com",
"X-USER-TOKEN": "paste-your-api-key"
}
}
}
}
The one-click button fills in the endpoint and your email; replace paste-your-api-key with your key afterwards. Restart Cursor after saving.
VS Code (GitHub Copilot)
Use the Install in VS Code one-click button on the MCP clients page, or create .vscode/mcp.json (or edit your user-level mcp.json). VS Code uses a servers key rather than mcpServers:
{
"servers": {
"optionomics": {
"type": "http",
"url": "https://optionomics.ai/mcp",
"headers": {
"X-USER-EMAIL": "you@example.com",
"X-USER-TOKEN": "paste-your-api-key"
}
}
}
}
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 your key.
Other clients
Any MCP client that speaks Streamable HTTP and can send either custom headers or a bearer token works the same way: point it at https://optionomics.ai/mcp with the X-USER-EMAIL and X-USER-TOKEN headers, or with Authorization: Bearer base64(email:api-key) where only one header is possible. Client settings change independently of Optionomics, so follow your client’s current documentation for where its MCP configuration lives.
Registry-aware clients can also discover the server from its public manifest at https://optionomics.ai/.well-known/mcp/server.json.
Verify and debug your connection
- MCP clients (/developers/clients, any account) — the Seen recently panel lists the client applications that have actually called the server with your keys.
- MCP console (/developers/console, Developer and Developer Pro) — run any tool from the browser as your own account and read exactly the JSON a client would get back, plus the raw request to reproduce it.
- MCP logs (/developers/logs, Developer and Developer Pro) — every call your clients made: tool, arguments, response, latency, and outcome.
See the Developer Console guide for a tour of these pages.
Example prompts
Once connected, try these prompts in your AI client. The first group works with a free key:
- “How far is NVDA priced to move tomorrow, and over the next week?”
- “How has AAPL moved through its last eight earnings reports compared with what the straddle priced?”
- “Which stocks are priced to move the most compared with their usual move? Only ones reporting earnings.”
- “What did the options market’s pulse look like in the last session?”
- “What’s the trade-idea track record by strategy family?”
With the Developer plan:
- “I’m bullish on AMD for a few weeks. What’s the cheapest call to trade, and what does the spread cost me?”
- “Is implied volatility on TSLA rich or cheap against what it is likely to realise?”
- “Show me the top 10 unusual options activity alerts today, excluding ETFs.”
- “What are the dark pool support and resistance levels for AAPL?”
- “Any congressional trades in NVDA this quarter?”
Troubleshooting
| Issue | Solution |
|---|---|
| 401 Unauthorized | The email and key did not authenticate. Check that both belong to the same account, that the key has not expired or been revoked, and that neither has extra spaces or a trailing newline. With bearer authentication, check that you base64-encoded email:key with a colon between them. |
| A tool answers that it “needs the Developer plan” | You are using a free MCP key and called a tool outside the free list. Use one of the free tools, or upgrade to Developer. |
| Data is from yesterday | A free key always reads the previous trading session. Developer reads the live session. |
| 429 Too Many Requests | You crossed your account’s per-minute allowance (shared with the REST API). Wait the number of seconds in the Retry-After header and slow the client down. |
| Connection timeout | Make sure your network allows HTTPS connections to optionomics.ai. |
| Tools not appearing | Restart the client completely (quit and reopen). Check the server’s status in the client’s settings, then check Seen recently on the MCP clients page to see whether calls arrived. |
Security notes
- Never commit your API key to version control. Use environment variables or ignored config files.
- Your API key authenticates as your account. Treat it like a password, and revoke it at optionomics.ai/developers/keys if it leaks.
- Create one key per client, so revoking one does not break the others.
- All connections are encrypted over HTTPS/TLS.
- On Developer and Developer Pro, every call is recorded in your own MCP log, so you can audit what a connected client actually asked for.
Related: