mirror of
https://github.com/upstash/context7.git
synced 2026-09-14 19:09:34 +08:00
Fahreddin Özcan
b89a04e620
* fix(cli): write the API key as an Authorization header
Codex resolves a server's auth mode by checking only for
`bearer_token_env_var` or a header literally named `Authorization`
(`auth_status_before_discovery` in codex-rs/rmcp-client/src/auth_status.rs,
mirrored in `create_transport` in rmcp_client.rs). The custom
`CONTEXT7_API_KEY` header matched neither, so Codex fell through to any OAuth
credential stored for the same server name and URL and refreshed it during
startup. A dead refresh token then failed the server with `invalid_grant`
before the API key was ever sent, and re-running setup could not recover it
because setup writes config.toml and never touches the credential store.
The hosted endpoint accepts both header forms, so existing configs keep
working.
Two places keep the legacy header deliberately: the plugin .mcp.json files
default to `${CONTEXT7_API_KEY:-}`, and the server rejects `Bearer` with an
empty token while treating a missing header as anonymous; and `env` blocks in
stdio configs, where the name is an environment variable rather than a header.
* fix(plugins): send the API key via the Authorization header
The Claude and Copilot plugin configs default to `${CONTEXT7_API_KEY:-}`, and
both plugins document that an unset key still works over the anonymous tier.
The Bearer form cannot express that: the server rejects `Bearer` with an empty
token while treating an empty or missing Authorization header as anonymous.
The raw-key form satisfies both states. It is genuinely parsed rather than
ignored, verified by an invalid raw key being rejected, so a set key still
authenticates while an unset one falls back to anonymous as documented.
Once the server treats an empty-token Bearer as no header, these can move to
the `Bearer <key>` form used everywhere else.
* refactor(cli): narrow the Codex OAuth probe and trim its surface
Only `oauth` proves a stored credential exists. `not_logged_in` also covers
"no credential, server merely advertises OAuth", which is the normal state for
anyone who never logged in, so treating it as stale told most users their
config held a credential it did not.
Collapse the module to the two functions the call site needs, derive nothing
from a hand-maintained status list, and skip the subprocess entirely when the
server is not already in Codex's config. Drop the probe timeout to 1.5s and
kill with SIGKILL so it is a real ceiling rather than an intent, since the
result is only an advisory hint.
Lock the plugin manifests' raw-key form behind a test, so normalizing them to
`Bearer` for consistency with the CLI fails loudly instead of silently
breaking anonymous access.
* refactor(cli): drop the Codex OAuth cleanup note
The note existed because re-running setup could not rescue a stuck user. The
Authorization header change in this same branch makes it rescue them: Codex
never reads the stored credential once that header is present, so the
credential is inert and the hint only offered cosmetic cleanup.
Removing it drops a subprocess spawn from a user-facing path and a dependency
on the shape of `codex mcp get --json`, an external contract this repo does not
pin. The reason the header name matters moves to `withHeaders`, where the
decision is encoded.
130 lines
5.2 KiB
Plaintext
130 lines
5.2 KiB
Plaintext
---
|
|
title: Codex
|
|
description: Using Context7 with OpenAI Codex
|
|
---
|
|
|
|
Context7 integrates with [OpenAI Codex](https://developers.openai.com/codex/) to provide current library documentation instead of relying on training data. Codex comes in three surfaces — the Codex CLI, Codex Desktop, and Codex Cloud — and Context7 works across all of them.
|
|
|
|
<Info>
|
|
MCP servers in Codex are configured once and shared everywhere. The Codex CLI, Codex Desktop, and the IDE extension all read the same `~/.codex/config.toml`, so adding Context7 in one place enables it in the others. See the [Codex MCP documentation](https://developers.openai.com/codex/mcp) for more details.
|
|
</Info>
|
|
|
|
## Installation
|
|
|
|
Run the setup command to configure Context7 for Codex:
|
|
|
|
```bash
|
|
npx ctx7 setup --codex
|
|
```
|
|
|
|
This authenticates via OAuth, generates an API key, and writes the Context7 configuration to your `~/.codex/config.toml` and `AGENTS.md`. You can choose between CLI or MCP mode. Login uses the OAuth device flow, which shows a verification link and short code you open on any device, so it works locally, on SSH hosts, and in headless environments.
|
|
|
|
You can also install Context7 as a Codex plugin. It connects to the hosted MCP server and includes a skill that looks up documentation when you ask about libraries:
|
|
|
|
```bash
|
|
codex plugin marketplace add upstash/context7
|
|
codex plugin add context7@context7-marketplace
|
|
```
|
|
|
|
After adding the plugin, a browser window opens so you can log in to Context7 via OAuth — plugin installs use your account's authenticated rate limits too. Start a new Codex thread after installation so Codex can load the plugin's skill and MCP tools.
|
|
|
|
Create or manage API keys in the [Context7 dashboard](https://context7.com/dashboard). For manual configuration or other clients, see [All MCP Clients](/resources/all-clients).
|
|
|
|
---
|
|
|
|
## Codex surfaces
|
|
|
|
<CardGroup cols={3}>
|
|
<Card title="Codex CLI" icon="terminal">
|
|
The local coding agent that runs in your terminal. Add Context7 with `codex mcp add` or by editing `config.toml`.
|
|
</Card>
|
|
<Card title="Codex Desktop" icon="desktop">
|
|
The Codex app for macOS and Windows. Enable Context7 from the app's MCP settings, or rely on the shared `config.toml`.
|
|
</Card>
|
|
<Card title="Codex Cloud" icon="cloud">
|
|
The web-based agent that runs tasks in cloud environments. Add Context7 to the tools for an environment from the Codex web app.
|
|
</Card>
|
|
</CardGroup>
|
|
|
|
### Codex CLI
|
|
|
|
If you only want the MCP server, add Context7 from the terminal with the `codex mcp add` command:
|
|
|
|
```bash
|
|
codex mcp add context7 -- npx -y @upstash/context7-mcp --api-key YOUR_API_KEY
|
|
```
|
|
|
|
Or add it directly to `~/.codex/config.toml` (use a project-scoped `.codex/config.toml` for trusted projects):
|
|
|
|
```toml
|
|
[mcp_servers.context7]
|
|
command = "npx"
|
|
args = ["-y", "@upstash/context7-mcp", "--api-key", "YOUR_API_KEY"]
|
|
startup_timeout_ms = 20_000
|
|
```
|
|
|
|
Prefer the hosted server? Use the remote connection instead:
|
|
|
|
```toml
|
|
[mcp_servers.context7]
|
|
url = "https://mcp.context7.com/mcp"
|
|
http_headers = { "Authorization" = "Bearer YOUR_API_KEY" }
|
|
```
|
|
|
|
### Codex Desktop
|
|
|
|
The Codex app (macOS and Windows) shares the same MCP configuration as the CLI and IDE extension. Enable Context7 from the app's MCP settings, or add it to `~/.codex/config.toml` using the snippets above — it's picked up automatically.
|
|
|
|
### Codex Cloud
|
|
|
|
Codex Cloud delegates tasks to OpenAI's agent in managed cloud environments, so they can run in the background without your local machine. Each environment defines the repo, setup steps, and tools Codex uses — configure Context7 as part of an [environment](https://developers.openai.com/codex/cloud/environments) from the Codex web app. Cloud environments also have [configurable internet access](https://developers.openai.com/codex/cloud/internet-access), which Context7 needs to reach the documentation API.
|
|
|
|
---
|
|
|
|
## Using Context7
|
|
|
|
With `ctx7 setup` or the plugin, a skill triggers automatically when you ask about libraries. You can also invoke it explicitly:
|
|
|
|
```
|
|
use context7 to show me how to set up middleware in Next.js 15
|
|
use context7 for Prisma query examples with relations
|
|
use context7 for the Supabase syntax for row-level security
|
|
```
|
|
|
|
If you know the library ID, use it directly to skip resolution:
|
|
|
|
```
|
|
use context7 with /supabase/supabase for authentication docs
|
|
use context7 with /vercel/next.js for app router setup
|
|
```
|
|
|
|
You can also add instructions to your `AGENTS.md` file:
|
|
|
|
```markdown AGENTS.md
|
|
When you need to search docs, use Context7.
|
|
```
|
|
|
|
---
|
|
|
|
## Tips
|
|
|
|
<AccordionGroup>
|
|
<Accordion title="Getting Better Results">
|
|
- Be specific about what you're trying to do, not just which library
|
|
- Mention versions when they matter
|
|
- If the first result isn't right, ask for a different part of the docs
|
|
|
|
```
|
|
# Good
|
|
How do I handle file uploads with the Supabase Storage API?
|
|
|
|
# Less specific
|
|
How does Supabase storage work?
|
|
```
|
|
</Accordion>
|
|
|
|
<Accordion title="Startup timed out or program not found">
|
|
If you see a startup "request timed out" or "not found program" error, increase `startup_timeout_ms` to `40_000` and retry. On Windows, point `command` at the absolute `npx.cmd` path and set `SystemRoot` and `APPDATA` explicitly — `npx` requires them, but some Codex MCP clients don't set them by default.
|
|
</Accordion>
|
|
</AccordionGroup>
|