> SpecStream is the live web data engine for teams and agents. This is the Markdown copy of https://specstream.ai/docs/integrations/codex-cli. Every page, with what SpecStream does and costs: https://specstream.ai/llms.txt # Codex CLI Add SpecStream to Codex CLI with one `codex mcp add` command, and OpenAI's coding agent can search the live web, read whole pages and build lists of records from your terminal. The same entry works in the Codex IDE extension and the ChatGPT desktop app. [SpecStream for Codex CLICoding agents](https://specstream.ai/integrations/codex-cli.md) ## What you need - Codex CLI, installed and signed in. - A SpecStream account. New accounts get $10 of credit, no card. 1. 1 ## 1. Add SpecStream with one command Run this in a terminal. Codex saves a `[mcp_servers.specstream]` table to `~/.codex/config.toml`, finds that SpecStream signs in with OAuth, and opens your browser at SpecStream's sign in. Terminal ```bash codex mcp add specstream --url https://api.specstream.ai/mcp ``` 2. 2 ## 2. Sign in to SpecStream Sign in, or create an account, and approve the access Codex asks for. Codex registers itself with SpecStream, so there is no client ID and no key to paste. The terminal prints `Successfully logged in.` when it is done. If no browser opened, or you work over SSH, run the command below. Open the address it prints, sign in, and paste the full redirect address back into the terminal, even if the browser can't load that page. Terminal ```bash codex mcp login specstream --no-browser ``` 3. 3 ## 3. Check the server Run `codex mcp list` and SpecStream is in the list. Start a session with `codex` and type `/mcp`: SpecStream is listed with its tools. Terminal ```bash codex mcp list ``` 4. 4 ## 4. Ask Codex Ask for something current and name SpecStream. Codex calls `search_web` for a quick answer and `read_pages` for the full text of the pages it found: In a Codex session ```text Use SpecStream to find the current stable release of Node.js and read its release notes. ``` 5. 5 ## 5. Or use an API key Use a key on a machine with no browser, in CI, or wherever a key with its own spending limit fits better. In your SpecStream workspace, open **Agents & API**, choose **API keys**, then **Create API key**, and set a total spending limit. Put the table below in `~/.codex/config.toml` in place of the entry the command wrote. Codex reads the key from the environment variable that `bearer_token_env_var` names and sends it in the `Authorization` header, so the key never sits in the file. Set it in the shell Codex starts from, for example `export SPECSTREAM_API_KEY=YOUR_SPECSTREAM_API_KEY` in your shell profile. ~/.codex/config.toml ```toml [mcp_servers.specstream] url = "https://api.specstream.ai/mcp" bearer_token_env_var = "SPECSTREAM_API_KEY" [mcp_servers.specstream.tools.authorize_capacity_work] approval_mode = "prompt" ``` ## What Codex gets SpecStream's server at `https://api.specstream.ai/mcp` adds these tools to Codex. - `search_web` answers a question from the live web, with up to 10 results for $5 per 1,000 searches. A search that returns nothing costs nothing. - `read_pages` returns the main text of up to 20 pages or documents (PDF, Word, Excel) in one call, at $0.80 per 1,000 pages. A page that gives no text is not charged. - Deep Search builds a list from a request in plain words. `compile` reads the request, `quote_capacity_work` prices it for free, and `authorize_capacity_work` starts it only after you approve the maximum. `get_find` and `list_find_rows` read the rows, each with its source. ## Approvals in Codex Codex sets approvals per server and per tool in `config.toml`. `default_tools_approval_mode` takes `auto`, `prompt`, `writes` or `approve` for all of a server's tools, and `tools..approval_mode` overrides it for one tool. Set `prompt` on `authorize_capacity_work`, the one tool that starts paid Deep Search work, as in the table above, so Codex asks you every time. SpecStream adds its own gate there: nothing paid starts until you approve the price it quotes. Searches and page reads are charged per call, with no quote. ## Server instructions Codex reads the instructions an MCP server returns when it connects and uses them beside the server's tools. SpecStream's instructions tell Codex which tool fits a question, and that nothing paid starts before you approve the quote. ## One setup for the CLI, the IDE extension and the ChatGPT app The Codex CLI, the IDE extension and the ChatGPT desktop app read the same `~/.codex/config.toml`, so SpecStream added once works in all three. To share SpecStream with a team, put the table in a project's `.codex/config.toml`. Codex loads that file only for trusted projects. With `bearer_token_env_var`, each person's key stays in their own environment and out of the repository. ## Timeouts By default Codex waits 10 seconds for a server to start and 60 seconds for a tool call. `read_pages` gives each page up to 30 seconds, all pages at once, so the defaults hold. To change them, set `startup_timeout_sec` or `tool_timeout_sec` in the `specstream` table. ## Search quality SpecStream's Search API scores 97.9 F-score on all 1,000 SimpleQA Verified questions and 64.0 item F1 on all 200 WideSearch tasks. The method is on [benchmarks](https://specstream.ai/benchmarks.md). ## Cost Connecting SpecStream to Codex is free, and new accounts start with $10 of credit. A search of up to 10 results costs $5 per 1,000, and a page read costs $0.80 per 1,000. Deep Search is priced per delivered row and quoted before it runs, and a run can't cost more than the maximum you approved. See [pricing](https://specstream.ai/pricing.md) and [how billing works](https://specstream.ai/docs/billing.md). ## Turn it off or remove it To pause SpecStream, add `enabled = false` to its table. To remove it, run `codex mcp remove specstream`, and `codex mcp logout specstream` deletes the stored sign in. On the SpecStream side, open **Agents & API** in your workspace and revoke Codex under **OAuth applications**, or revoke its key under **API keys**. Questions: [support@specstream.ai](mailto:support@specstream.ai). ## More [SpecStream for Codex CLI](https://specstream.ai/integrations/codex-cli.md) covers what it does in Codex CLI on one page. Every other tool has its guide in [Connect your tools](https://specstream.ai/docs/integrations.md). You see the most a request can cost before it starts, and the matches are paid from your balance. [Billing](https://specstream.ai/docs/billing.md) has the details. For help, email [support@specstream.ai](mailto:support@specstream.ai).