# Context7: Current Library Docs for Your Agent (MCP, CLI and Skills Mode)

URL: https://developertoolkit.ai/en/ecosystem/mcp/context7/
Description: Set up Context7 in Claude Code, Codex and Cursor, pin library IDs, choose MCP or skills mode, and prove the agent coded against current APIs.

Context7 is Upstash's documentation service for coding agents: it returns version-specific library docs and code examples on demand, through a remote MCP server, the `@upstash/context7-mcp` package, or the `ctx7` CLI with a skill and no MCP at all. It cuts stale-API errors, but type checks and tests remain the proof that the code is right.

You ask the agent for Next.js request-interception code and it writes `middleware.ts`. The code compiles, and your framework has already deprecated it: since Next.js 16.0.0 the file convention is `proxy.ts` (Next.js `proxy.js` API reference, read 2026-09-26). The model is not careless. Its training data stops before the release you installed, and nothing in the session told it otherwise.

This page is for developers who want the agent to write against the library version in the lockfile, and for tech leads who want that to be the team default rather than a habit one person has.

## What a working Context7 setup gives you

- Context7 installed in Claude Code, Codex and Cursor, with the API key kept out of committed files.
- A choice between MCP mode and CLI + Skills mode, with the trade-off stated.
- Prompts that pin a library ID and a version, so the agent does not guess which package you meant.
- A dependency-upgrade workflow: Context7 for the new API, then codemod, tests and review.
- A short list of other documentation servers and vendor skills for the cases Context7 does not cover.
- Seven failure modes with the recovery for each.

## How Context7 works: two tools, two steps

The MCP server exposes exactly two tools in `@upstash/context7-mcp` 4.1.1 (npm, checked 2026-09-26):

| Tool | Arguments | What it does |
| --- | --- | --- |
| `resolve-library-id` | `libraryName`, `query` | Turns a name such as "next.js" into a Context7 library ID such as `/vercel/next.js`, ranked against your task |
| `query-docs` | `libraryId`, `query` | Returns the doc sections and code examples for that library that match the task |

A normal lookup is two calls: resolve, then query. When you name the ID in the prompt ("use library `/vercel/next.js`"), the agent skips the first call. That is faster, and it removes the most common error: resolving to a fork or a similarly named package.

The CLI mirrors the same two steps: `ctx7 library <name> [query]` and `ctx7 docs <libraryId> <query>` (`ctx7` 0.5.12, `--help`, checked 2026-09-26).

**Older articles use a different tool name**

Version 1.x of the package (for example 1.0.14, published June 2025) named the second tool `get-library-docs`. Version 4.1.1 registers `query-docs` instead. If a prompt or rule in your repository names `get-library-docs`, update it.

## Choose MCP mode or CLI + Skills mode

Upstash ships two ways to connect the same service. The `ctx7` CLI, which runs the setup and powers skills mode, needs Node.js 18 or newer.

| | MCP mode | CLI + Skills mode |
| --- | --- | --- |
| What gets installed | A server entry pointing at `https://mcp.context7.com/mcp` (or a local stdio process) | A skill that tells the agent to run `ctx7 library` and `ctx7 docs` in the shell |
| When the agent uses it | When it decides to call the tool, or when you write "use context7" | When the skill's description matches the task; the skill triggers on library questions |
| Works in | Any MCP client: Claude Code, Codex, Cursor and 30+ others (Upstash README) | Agents that load skills and can run shell commands |
| Good for | Teams that already manage MCP servers centrally | Keeping the MCP server list short; agents without MCP |

`npx ctx7 setup` asks which mode you want, signs you in through OAuth, generates an API key, and writes the configuration. Add `--mcp` or `--cli` to skip the question, and `--claude`, `--codex` or `--cursor` to target one agent. `-p` configures the current project instead of your user profile. `npx ctx7 remove` undoes it.

## Install Context7 in Claude Code, Codex and Cursor

The fastest route is the same everywhere: run `npx ctx7 setup` in a terminal and follow the prompts. The manual routes below are for teams that want the configuration in version control or need to control where the key lives.

A free API key from the Context7 dashboard raises the rate limits. The hosted server also works without one.

**Claude Code**

Remote server, project scope, key read from your environment (tested on Claude Code 2.1.283):

```bash
claude mcp add --scope project --transport http context7 https://mcp.context7.com/mcp \
  --header 'Authorization: Bearer ${CONTEXT7_API_KEY}'
```

The single quotes matter. Claude Code writes `"Authorization": "Bearer ${CONTEXT7_API_KEY}"` into `.mcp.json` and expands the variable at runtime, so you can commit the file without the key.

Alternatives:

```bash
# Local stdio process, user scope; the server reads CONTEXT7_API_KEY from its environment
claude mcp add --scope user context7 -e CONTEXT7_API_KEY=YOUR_API_KEY -- npx -y @upstash/context7-mcp@4.1.1

# Official plugin (listed in claude-plugins-official with 417,801 installs on claude.com/plugins, checked 2026-09-26)
claude plugin install context7@claude-plugins-official

# CLI + Skills mode, no MCP server
npx ctx7 setup --cli --claude
```

Put the server name before `-e`: the flag takes several values, so `-e KEY=value context7` reads `context7` as a second variable and fails with `Invalid environment variable format`. If `claude plugin install` reports that the marketplace is missing, use Upstash's own marketplace inside a session: `/plugin marketplace add upstash/context7`, then `/plugin install context7@context7-marketplace`.

**Codex**

Remote server with the key taken from an environment variable (tested on codex-cli 0.157.1):

```bash
codex mcp add context7 --url https://mcp.context7.com/mcp --bearer-token-env-var CONTEXT7_API_KEY
```

That writes this block to `~/.codex/config.toml`, and `codex mcp list` then shows the auth as "Bearer token":

```toml
[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"
bearer_token_env_var = "CONTEXT7_API_KEY"
```

Alternatives:

```bash
# Local stdio process
# writes the key into ~/.codex/config.toml; prefer the --url + --bearer-token-env-var form above
codex mcp add context7 --env CONTEXT7_API_KEY=YOUR_API_KEY -- npx -y @upstash/context7-mcp@4.1.1

# CLI + Skills mode, no MCP server
npx ctx7 setup --cli --codex
```

Codex silently ignores configuration keys it does not know. A block with `headers = { … }` parses without an error and the header is never sent. The keys are `bearer_token_env_var`, `http_headers` and `env_http_headers` (codex-cli 0.157.1).

**Cursor**

Put the remote server in `~/.cursor/mcp.json` (global), so the key never lands in the repository (configuration shape from the Upstash README; not tested in a Cursor binary):

```json
{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

A project-level `.cursor/mcp.json` works too; keep the header out of it and let each developer add the key globally.

Or let the CLI write the configuration:

```bash
npx ctx7 setup --cursor          # asks for MCP or CLI + Skills mode
```

Replace `YOUR_API_KEY` with the key from your Context7 dashboard, or leave the header out to run anonymously at lower rate limits.

### Check that the agent can reach Context7

Run `/mcp` in a Claude Code or Codex session, or `codex mcp list` in a terminal (in Cursor, open the MCP list in settings), and confirm `context7` is connected with two tools. Then run the first prompt below and watch for a `resolve-library-id` call followed by `query-docs`. If you chose CLI + Skills mode, look for `ctx7 library` and `ctx7 docs` in the shell output instead.

## Ask for current docs: the Next.js example

A prompt adapted from the Upstash README's own example is the right first test, because the answer changed in a recent release:

**Copy-paste prompt: first Context7 test**

```text
Create Next.js request interception that checks for a valid JWT in the "session" cookie and redirects unauthenticated users to /login. Read the installed Next.js version from package.json first, then use context7 with library /vercel/next.js for that version. Tell me which file convention the docs specify for this version and quote the doc section you used.
```

What you should see on Next.js 16: the agent resolves or accepts `/vercel/next.js`, calls `query-docs`, and writes `proxy.ts` with an exported `proxy` function, not `middleware.ts`. On Next.js 15 it should write `middleware.ts`. If it writes `middleware.ts` on 16 without comment, it answered from training data; check the tool log to see whether it queried at all.

Pinning is the habit worth building. The README format is "use library `/owner/repo`":

**Copy-paste prompt: pinned library ID**

```text
Implement email/password sign-up and sign-in with Supabase in src/lib/auth.ts. use library /supabase/supabase for API and docs. Match the @supabase/supabase-js version in package.json, handle the error cases the docs show, and do not call any function that does not appear in the docs you retrieved.
```

When you do not know the ID yet, make the agent show the candidates before it writes code, so you pick the library instead of the ranking:

**Copy-paste prompt: resolve first, then write**

```text
Use context7 resolve-library-id for drizzle-kit and show me the top candidates with their IDs. Stop and wait for me to pick one. Then query that ID for the current way to push schema changes to a development database at the drizzle-kit version in package.json, list any command or flag that changed since the previous major version, and update the db:push script to match.
```

You can do the same lookup yourself with `npx ctx7 library drizzle "push schema"`.

**Copy-paste prompt: build a component from current docs**

```text
Use context7 to look up the shadcn/ui Dialog component docs. Create src/components/ui/confirm-delete-dialog.tsx that follows the documented composition exactly: trigger button, a warning message, and Cancel and Delete actions. After writing it, list every import and prop you used and the doc snippet each one came from.
```

### Make Context7 the default instead of a phrase

Typing "use context7" every time does not scale to a team. Put the rule in the file each agent reads at session start. The Upstash README suggests this wording:

```text
Always use Context7 when I need library/API documentation, code generation, setup or configuration steps without me having to explicitly ask.
```

Put it in `CLAUDE.md` for Claude Code, `AGENTS.md` for Codex, and a Rule (**Cursor Settings > Rules**) for Cursor. CLI + Skills mode needs no rule: `ctx7 setup` installs a skill that already triggers on library questions. For how to keep these files short enough that the agent still reads them, see [documentation as AI context](/en/workflows/context/documentation-as-context/).

## Upgrade a dependency with Context7, a codemod and tests

A major-version upgrade is where stale training data costs the most, and where Context7 earns its place. It does not replace the codemod or the tests; it supplies the new API so the agent can fix what the codemod leaves behind. The prompts are identical in all three tools.

This walk-through upgrades a Next.js 15 app to 16. The same shape fits any library with a changelog and a codemod.

1. **Record the baseline.** On a fresh branch, run the full gate (type check, lint, tests, build) and save the result. Record the installed version with `npm ls next`. If the suite is weak around the code you are about to change, strengthen it first; see [how strong your oracle is](/en/workflows/test/oracle-strength/).

2. **Get the migration list from current docs, not memory.**

   **Copy-paste prompt: upgrade plan from current docs**

   ```text
   We are upgrading next from the version in package-lock.json to 16. Use library /vercel/next.js and query the upgrade guide and the API reference one concept at a time. Produce docs/upgrade-next-16.md with: each breaking change that affects files in this repo (with file paths), the official codemod for it if one exists, and the doc section you took it from. Do not edit code yet.
   ```

   Review this file. It is the contract for the rest of the upgrade, and it is short enough to read in full.

3. **Run the codemods before the agent touches code.** Codemods are deterministic and reviewable as one mechanical diff. For the middleware rename, the Next.js docs give `npx @next/codemod@canary middleware-to-proxy .`, which renames the file and the function. Commit the codemod output on its own.

4. **Let the agent fix the residue, one concept per query.** Ask it to work through the remaining items in `docs/upgrade-next-16.md`, querying Context7 for each one and stopping when the gate is green. The `ctx7 docs` help text says it outright: send a single-topic question per call, and run a separate query for each distinct concept.

5. **Run the gate and compare it with the baseline.** Type check, lint, tests and build must all pass. Treat any new deprecation warning in the build output as a failure.

6. **Review on evidence.** The pull request carries the plan file, the codemod commit, the residue commit and the gate output. The reviewer checks that every item in the plan is closed and that no test was weakened; see [reviewing an agent's pull request](/en/workflows/ship/agent-pr-review/).

## How to prove the agent used the right API

Context7 raises the odds that the agent picks the current API. It proves nothing on its own: the docs are community-contributed, and Upstash's README disclaims their accuracy and completeness. The proof comes from gates that check the code against the installed package, and a person signs off on the result of those gates.

| Check | What it catches | Who owns it |
| --- | --- | --- |
| Type check against the installed package's types | Invented functions, removed options, wrong signatures | CI, blocking |
| Tests and build on the upgraded lockfile | Behaviour changes the types cannot see | CI, blocking |
| Deprecation warnings in build and test output | Code that works today on an API scheduled for removal | CI, blocking once the baseline is clean |
| Library ID and version queried, listed in the PR | Docs retrieved for the wrong library or version | Author (agent), checked by the reviewer |
| New or changed dependencies in the lockfile diff | A package the agent added because the docs mentioned it | CI; see [dependency checks for agent changes](/en/workflows/test/dependency-verification/) |

The tech lead approves on that evidence, not on reading every changed line. The [evidence bundle](/en/workflows/ship/evidence-bundle/) page has the PR template that makes these rows required.

**Copy-paste prompt: self-check before opening the PR**

```text
Before opening the PR: list every third-party API call you added or changed in this branch. For each one, give the Context7 library ID and version you queried and confirm that the symbol exists in the type definitions under node_modules for the installed version. Flag anything you wrote from memory rather than from a doc lookup. Then run the type check, tests and build, and paste the summary.
```

## What Context7 costs in context

Claude Code and Codex both load MCP tool schemas on demand (tool search is on by default in Claude Code 2.1.283 and codex-cli 0.157.1), so two tool definitions cost little. The real cost is the `query-docs` output, which lands in context on every call. A broad question such as "read the Express docs" returns far more than "the authentication middleware section".

Measure it rather than guess. In Claude Code, run `/context` before and after one lookup; for the plugin, `claude plugin details context7` shows its projected token cost, although that figure leaves out the MCP tool schemas. Keep queries to one concept, and move long research into a subagent so only its summary returns to the main session. For the general pattern, see [reducing MCP token cost](/en/ecosystem/mcp/reducing-mcp-token-cost/).

## How popular is Context7?

As of 2026-09-26: 62.4k GitHub stars on `upstash/context7` (GitHub), listed in the Official MCP Registry as `io.github.upstash/context7` 4.1.1, and 417,801 installs of the `context7` plugin on the Claude plugin directory (`claude.com/plugins`). No npm download figure is given here, because none was read.

## Other documentation servers, and when a vendor skill is better

Context7 covers open-source libraries broadly. For a single vendor's platform, the vendor's own server or skill is usually more complete.

| Source | Use it for | Install (Claude Code shown) | Auth | Evidence |
| --- | --- | --- | --- | --- |
| **Microsoft Learn MCP** | Azure, .NET and Microsoft 365 docs and code samples. Tools: `microsoft_docs_search`, `microsoft_docs_fetch`, `microsoft_code_sample_search`. `?maxTokenBudget=2000` on the URL caps response size | `claude mcp add --transport http microsoft-learn https://learn.microsoft.com/api/mcp` | None | Verified; 1.9k stars; plugin `microsoft-docs` |
| **AWS Knowledge MCP** | AWS documentation and guidance | `claude mcp add --transport http aws-knowledge https://knowledge-mcp.global.api.aws` | None; rate-limited | Verified |
| **Hugging Face MCP** | Models, datasets and Spaces on the Hub | `claude mcp add hf-mcp-server -t http "https://huggingface.co/mcp?login"` | Login or HF token | Verified (vendor README) |
| **DeepWiki MCP** | Questions about how a public GitHub repository is built. Tools: `read_wiki_structure`, `read_wiki_contents`, `ask_question` | `claude mcp add --transport http deepwiki https://mcp.deepwiki.com/mcp` | None; public repos only | **Secondary**: from Cognition's docs and blog via search snippets, not fetched |
| **Fetch (reference server)** | Any single page Context7 has not indexed, such as a changelog | `claude mcp add fetch -- uvx mcp-server-fetch` | None | Verified; Python package, run with `uvx`, not `npx` |

For Codex, the remote ones use `codex mcp add <name> --url <url>`; for Cursor, the `url` form in `mcp.json` shown above. The Microsoft Learn and AWS lines are assembled from each vendor's URL and the verified `claude mcp add` syntax.

**Vendor skills that replace a docs lookup.** Some frameworks now ship their knowledge with the framework itself:

- **Next.js**: workflow skills live in the framework repository (`npx skills add vercel/next.js`), and on Next.js 16.3+ the reference knowledge ships as docs bundled with the package plus the `AGENTS.md`/`CLAUDE.md` that `next dev` generates. On Next.js 16.1 or earlier, `npx @next/codemod@canary agents-md` pulls version-matched docs. The older `vercel-labs/next-skills` repository is retired.
- **Stripe**: `npx skills add https://docs.stripe.com` installs Stripe's skills from its docs site.
- **Skills from Context7's index**: `npx ctx7 skills install /google-gemini/gemini-skills gemini-api-dev` installs a vendor skill through the `ctx7` CLI.

The decision rule: when the docs ship inside the installed package, prefer them, because they match the version in your lockfile by construction. Use Context7 when the library has no such bundle, and Fetch when Context7 has not indexed it. For installing and updating skills, see [installing and managing skills](/en/ecosystem/skills/installing-managing/).

## When Context7 returns the wrong docs, or none

**The agent resolved the wrong library.** A fork or a similarly named package ranks first, and the code uses an API that does not exist in yours. Recovery: pin the ID (`use library /owner/repo`), and add the pinned IDs for your main dependencies to `CLAUDE.md` or `AGENTS.md`.

**The docs are for the wrong version.** The agent retrieved docs for the latest release while your lockfile pins an older one. Recovery: tell it to read the version from `package.json` or the lockfile first and to name that version in the query, as the prompts above do; the README says Context7 matches a version mentioned in the prompt. If you suspect the index lags a release, give the agent the library's changelog URL through the Fetch server and ask it to reconcile the two.

**Context7 has no entry for the library.** Recovery: run `npx ctx7 library <name>` to confirm, then give the agent the documentation URL through the Fetch server, or install the vendor's skill. Library owners can submit their docs to Context7.

**The agent never calls it.** It answers from training data because nothing told it to look. Recovery: add the rule above to the agent's instruction file, or switch to CLI + Skills mode, whose skill triggers on library questions.

**Requests fail with 403 or 429.** Anonymous use hits lower rate limits, and a corporate proxy may block `mcp.context7.com`. Recovery: add an API key; ask for the host to be allowlisted; for a private deployment, `ctx7 setup` accepts `--base-url`.

**The key ends up in Git.** Someone pasted it into `.mcp.json` or `.cursor/mcp.json`. Recovery: rotate the key in the Context7 dashboard, and use `${CONTEXT7_API_KEY}` in Claude Code, `bearer_token_env_var` in Codex, or the global `~/.cursor/mcp.json` in Cursor.

**The package name is wrong.** `@context7/mcp`, `@upstash/context7` and `context7-mcp` all return 404 on npm. The server is `@upstash/context7-mcp`, and the CLI is `ctx7`. Recovery: install `@upstash/context7-mcp` for the server or run `npx ctx7` for the CLI, and check any name with `npm view <name> version` before you add it to a config file.

**Traps: names and flags that do not exist**

Do not copy these from older articles or from an agent's suggestion (checked on 2026-09-26 against npm, Claude Code 2.1.283 and codex-cli 0.157.1):

- **`@context7/mcp`, `@upstash/context7`, `context7-mcp`**: all return 404 on npm. The server is `@upstash/context7-mcp`.
- **`get-library-docs`**: the tool name in the 1.x server only. Version 4.1.1 exposes `resolve-library-id` and `query-docs`.
- **`headers = {…}` in Codex's `config.toml`**: parsed and silently ignored, so the server runs without your key. Use `bearer_token_env_var`, `http_headers` or `env_http_headers`.
- **`claude mcp add -e KEY=value context7 …`**: with `-e` before the server name, the name is read as another environment variable and the command fails. Put the name first: `claude mcp add context7 -e KEY=value -- …`.

**What leaves your machine**

The `query` argument is your task description, and it is sent to Context7's hosted backend, which is not open source. Do not put secrets, customer data or proprietary code in a query. Docs that come back are third-party text in the agent's context, so treat them as untrusted input, like any other tool result. See [securing MCP servers](/en/ecosystem/mcp/mcp-security/).

## Where to go next with documentation servers

- [Must-have MCP servers](/en/ecosystem/mcp/essential-servers/) — Where Context7 fits among the servers most teams install first.
- [Documentation as AI context](/en/workflows/context/documentation-as-context/) — Write the CLAUDE.md and AGENTS.md rules that make docs lookups the default.
- [Dependency checks for agent changes](/en/workflows/test/dependency-verification/) — Catch invented or unpinned packages before they merge.
- [Microsoft and Azure MCP servers](/en/ecosystem/mcp/cloud-platform-mcp/) — The Microsoft Learn server alongside Azure resource management.
- [MCP server connection issues](/en/ecosystem/mcp/mcp-connection-issues/) — When /mcp shows a server as failed or with no tools.
- [MCP overview](/en/ecosystem/mcp/) — How MCP works across Claude Code, Codex and Cursor.
