Skip to the page
Get started free

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

What you need

  • Codex CLI, installed and signed in.
  • A SpecStream account. New accounts get $10 of credit, no card.

  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
    codex mcp add specstream --url https://api.specstream.ai/mcp

  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
    codex mcp login specstream --no-browser

  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
    codex mcp list

  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
    Use SpecStream to find the current stable release of Node.js and read its release notes.

  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
    [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.<tool>.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.

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 and how billing works.

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: [email protected].

More

SpecStream for Codex CLI covers what it does in Codex CLI on one page. Every other tool has its guide in Connect your tools. You see the most a request can cost before it starts, and the matches are paid from your balance. Billing has the details. For help, email [email protected].