Codex Setup

Connect Massive to Codex with the remote MCP server

Massive's remote MCP server connects Codex to live U.S. market data: dividends, trades, quotes, options chains, and the rest of our catalog. It queries our REST API under the hood, so Codex can pull data and verify response shapes while building against it.

This guide walks through adding the remote server to Codex and authenticating over OAuth. The server needs nothing installed. Setup takes about two minutes and requires the Codex CLI plus a Massive account. It then covers the optional Massive plugin, which teaches Codex to write correct code against our API.

What You Can Do

Once connected, Codex can:

  • Pull live market data while it writes code, like the latest trade or quote for a ticker.
  • Inspect the real response shape of an endpoint before building against it.
  • Confirm a field name exists instead of guessing, avoiding hallucinated keys.
  • Discover which Massive endpoint returns the data shape you need for a use case.

Because the server makes the calls itself, Codex can check real responses as it works, which keeps generated integrations accurate.

Setup

Two steps. Allow about two minutes start to finish.

1. Install Codex

If you don't have it, install the OpenAI Codex CLI and confirm it works:

codex --version

2. Add the Massive Remote MCP Server

Add Massive to your Codex config at ~/.codex/config.toml:

[mcp_servers.massive]
url = "https://mcp.massive.com/"

Then authenticate over OAuth:

codex mcp login massive

This opens your browser to sign in to your Massive account and stores the credentials, refreshing them automatically. There is no API key to copy or store. A free Basic account is enough to start.

Note: Remote (streamable-HTTP) MCP servers are first-class in current Codex. On older versions that only pick up stdio servers, add a [features] block with experimental_use_rmcp_client = true above the server entry, or upgrade Codex. You can also register the server in one step with codex mcp add massive --url https://mcp.massive.com/.

Your MCP access mirrors your Massive entitlements. You can query any asset class your plan includes. If you have Stocks access, stocks data is available through MCP. Requesting data you are not entitled to (for example, Options without an Options plan) returns an access-denied error.

Test the Integration

Now that the connection is live, put it through its paces. A few prompts to start with:

  • "Show me the latest trade for AAPL." (Trades)
  • "Is the U.S. market open right now?" (Market Status)
  • "When is the next market holiday?" (Market Holidays)
  • "What dividends has AAPL paid this year?" (Dividends)
  • "Give me a snapshot of today's biggest gainers." (Snapshots)

When you're ready to go deeper, hand Codex a full brief and let it chain several calls together:

Pull all dividends declared in the last 30 days, filter to U.S. stocks with a market cap over $50 billion, rank them by yield, and summarize the top five with their pay dates.

Codex will search for the right endpoints, make the live calls, and stitch the results into a single answer.

Add the Massive Plugin

The MCP server gives Codex live data. The Massive plugin teaches it how to write correct code against our API: the right host and auth, when to use REST, WebSocket, or Flat Files, what your plan includes, and how to get accurate historical numbers from adjusted prices, point-in-time data, and delisted tickers. It also adds recipes for backtests, screens, options chains, earnings prep, market briefs, and live streams.

The plugin is open source at github.com/massive-com/ai.

1. Set Your API Key

The code the plugin writes calls the REST API directly, so it reads your key from the MASSIVE_API_KEY environment variable. Find your key in the Dashboard and export it before you start Codex:

export MASSIVE_API_KEY=your_key_here

The command above saves your key in your shell history. To keep it out, run the command below instead. Paste your key and press Enter. Nothing appears as you paste.

read -s MASSIVE_API_KEY && export MASSIVE_API_KEY

2. Install the Plugin

Add the Massive marketplace, then install the plugin from it:

codex plugin marketplace add massive-com/ai
codex plugin add massive@massive-plugins

Confirm the install with codex plugin list. It shows massive as installed and enabled. To update later, run codex plugin marketplace upgrade massive-plugins.

How the Plugin and MCP Server Fit Together

Each one works without the other, and they do different jobs:

  • The MCP server runs lookups inside your session. Codex calls its tools to find an endpoint and fetch live data. It signs in with OAuth.
  • The plugin shapes the code Codex writes for you. That code calls the REST API with MASSIVE_API_KEY, so it runs on its own after the session ends.

The plugin does not install the MCP server. When both are present, Codex uses the MCP server for quick lookups during the session and still writes REST code for anything you ship.

Troubleshooting

Massive doesn't appear in Codex's tools. Confirm the entry in ~/.codex/config.toml parses cleanly and restart Codex. On older Codex versions, remote servers are ignored unless experimental_use_rmcp_client is enabled (see Setup).

Authentication didn't complete. Run codex mcp login massive again and finish the browser sign-in.

Codex answers without calling Massive. It's drawing on training data. Prompt it explicitly to "use the Massive MCP server" before the question.

Access-denied errors. You're querying an asset class your plan doesn't include. Check your entitlements in the Dashboard.

The plugin's skills don't load. Run codex plugin list and confirm massive is installed and enabled, then restart Codex.

Code from the plugin fails with an authentication error. MASSIVE_API_KEY isn't set in the shell that started Codex. Export it, then restart Codex.

Did you find this page helpful?
Do you still need help with something?