LIVE|CLI v0.144.0·model GPT-5.6 Sol·verified 2026-07-09
Vol. I · No. 1Independent coverage of OpenAI CodexMonday, August 3, 2026
Codex Insider
The unofficial wire for OpenAI Codex.
Codex Insider
Ecosystem

Connect Codex to Context7

Published Jul 16, 2026 · Checked against the official docs

The short version

A bare npx command to Context7 fails two different ways in Codex, and they're easy to mix up: 'program not found' means Codex never located npx, while 'request timed out' means the download took too long. Windows needs the absolute npx.cmd path plus two env variables set by hand. Two closed GitHub issues map the fix, plus a way to keep your API key out of the config file.

Context7 is the worked example on this site’s MCP setup page and timeout page, and it’s a reasonable first server to add. It needs no key to try, and it addresses Codex answering from stale training data instead of the library version you’re actually on.

Upstash ships a Codex path already. Their ctx7 installer (v0.5.4, published 2026-07-06) has a --codex flag that writes ~/.codex/config.toml, and their docs have a Codex page with both transports. Their README’s flag list omits --codex; the shipped package has it. So what follows is the manual block plus the failure modes people hit on Windows, which is where both Context7 issues on the Codex tracker come from.

What you get

Two tools, per Upstash’s README:

  • resolve-library-id: takes a library name (libraryName) plus your question (query), and returns the Context7-compatible ID, like /vercel/next.js.
  • query-docs: takes that ID (libraryId) plus your question (query), and returns documentation and code examples pulled from the library’s source.

The README’s own note calls an API key “Recommended” for “higher rate limits”, so keyless works to start. A free key at context7.com/dashboard raises the limit. Upstash’s troubleshooting page says a valid key starts with ctx7sk.

Setup

Pick one transport. An entry gets command or url, never both.

1. Local (stdio) through npx:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 30

Or let the CLI write it:

codex mcp add context7 -- npx -y @upstash/context7-mcp

codex mcp add takes --env flags and the stdio command, and that’s the whole surface. There’s no timeout flag, so open the file afterward and add startup_timeout_sec = 30 by hand. Read Gotchas before you drop it, especially on Windows.

2. Remote (streamable HTTP):

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

There’s no --url flag on codex mcp add. OpenAI’s MCP docs document the CLI for stdio servers and tell you to edit ~/.codex/config.toml for anything else, so remote entries get typed by hand.

3. Confirm it initialized:

codex mcp list

Look for context7. If it’s missing or errored, check Gotchas before changing anything else.

4. Add the key when you want the higher limit.

Upstash documents the key as an HTTP header named CONTEXT7_API_KEY, and their Codex page shows it as a literal:

http_headers = { "CONTEXT7_API_KEY" = "YOUR_API_KEY" }

That commits your key to the file. Codex’s own env_http_headers sends the same header and reads the value from your environment instead:

[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"
env_http_headers = { "CONTEXT7_API_KEY" = "CONTEXT7_API_KEY" }

Then set it once in your shell profile with export CONTEXT7_API_KEY=your-key-here. Mechanism at /config/mcp-servers-env/ and /config/mcp-servers-url/.

On stdio, Upstash only documents the key as a CLI argument (args = [..., "--api-key", "YOUR_API_KEY"]), which puts a plaintext secret in the file and in your process list. I could not confirm from their docs that the stdio build reads CONTEXT7_API_KEY from its own environment. If the key matters to you, use the remote transport, where the secret-safe path is documented.

Gotchas

Cold npx blows the 10-second default. The first run downloads @upstash/context7-mcp before it can answer Codex’s handshake. #2555 (opened 2025-08-21, closed 2025-09-09, 42 comments, 16 reactions) reports this on Windows 11 against Codex 0.23.0 through 0.31.0. Raising startup_timeout_sec to 30 is the first thing to try. Upstash’s Codex page starts at startup_timeout_ms = 20_000 and says go to 40_000 if it still times out. Background at /config/mcp-servers-startup-timeout-sec/ and /errors/mcp-handshake-connection-closed/.

On Windows the timeout alone usually isn’t enough. The configs people actually got working in #2555 pair three things. wbdb reported success on Codex 0.38.0 using command = "cmd" with args = ["/c", "npx", ...], a raised timeout, and SystemRoot set in the env table. Opawn posted the same shape at startup_timeout_ms = 30000. Upstash’s Codex page agrees on the underlying point: on Windows, point command at the absolute npx.cmd path and set SystemRoot and APPDATA explicitly.

[mcp_servers.context7]
command = "cmd"
args = ["/c", "npx", "-y", "@upstash/context7-mcp"]
startup_timeout_ms = 30000

[mcp_servers.context7.env]
SystemRoot = "C:\\Windows"
APPDATA = "C:\\Users\\you\\AppData\\Roaming"

“program not found” is a different failure from “request timed out.” Both issues show the same split. A bare command = "npx" returns MCP client for context7 failed to start: program not found, while cmd /c npx and a full path to npx.cmd return request timed out. Raising the timeout does nothing for program not found, which is Codex failing to resolve npx at all. #3289 (17 comments, closed 2025-11-18) files the same repro from the VS Code extension against Codex 0.4.3, so this isn’t specific to the CLI.

JSON in, TOML out. A Context7 block copied from Claude Desktop or Cursor looks like "mcpServers": { "context7": { "command": "npx", "args": [...] } }. Codex doesn’t read that shape. Translate it by hand, or run codex mcp add and skip the translation. Full table: /config/connect-an-mcp-server/.

Sources

More Ecosystem guides