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

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):

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:

# 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):

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”:

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

Alternatives:

# 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

Caution

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):

{
  "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:

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

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

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

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

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:

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.

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.

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

   Copy-paste prompt: upgrade plan from current docs

   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.

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

The tech lead approves on that evidence, not on reading every changed line. The evidence bundle page has the PR template that makes these rows required.

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

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.

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.

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.

Where to go next with documentation servers

Must-have MCP servers Where Context7 fits among the servers most teams install first.

Documentation as AI context Write the CLAUDE.md and AGENTS.md rules that make docs lookups the default.

Dependency checks for agent changes Catch invented or unpinned packages before they merge.

Microsoft and Azure MCP servers The Microsoft Learn server alongside Azure resource management.

MCP server connection issues When /mcp shows a server as failed or with no tools.

MCP overview How MCP works across Claude Code, Codex and Cursor.