In the first mode Context7 is two console commands plus instructions on when to run them. In the second it is two tools the client sees in its list.

Functionally the modes do the same job, so you choose by environment rather than by capability. If your agent already lives in the terminal, the CLI skill installs more simply. If your client speaks MCP and you already run a couple of servers there, the second mode fits your existing setup more evenly.

Installing With One Command

Everything installs with a single command. The CLI needs Node.js 18 or newer.

What happens next, the README describes this way: the command authenticates over OAuth, generates an API key and installs the appropriate skill. Along the way it asks which mode you want - CLI + Skills or MCP.

If the agent is known in advance, name it with a flag and skip the questions:

Undoing everything the command did is one line as well:

One detail the README calls out separately: if you installed the CLI globally, remove will not delete it - that package is removed on its own.

The API key is formally optional. The README marks it as recommended: basic usage works without one, and a key raises the rate limits. You get it from the dashboard on context7.com.

Manual Setup When setup Does Not Fit

Automatic installation does not cover everything, so it helps to know what it does by hand.

The simplest path is the remote server. It needs no local Node.js at all:

The second path is a local run through npx. The key is easier to keep in an environment variable than in arguments:

The server itself takes three flags, all described in the developer guide.

Precedence between the flag and the variable is stated explicitly: --api-key beats CONTEXT7_API_KEY when both are present. This is exactly the rule worth learning in advance - otherwise half a day goes into working out why the key from .env is being ignored.

The CLI and the MCP server version independently of each other. Their Node.js requirements differ too: 18 is enough for the CLI, while the MCP server needs at least 20.18.1. If you are not installing through setup, check that boundary before you start unpicking mysterious module errors.

How the Agent Uses It: Two Tools

In MCP mode the agent sees exactly two tools, and their order is fixed.

The first is resolve-library-id. It turns a human library name into a Context7 identifier. It takes two required arguments: libraryName - the name, and query - what exactly to look up. The second is not decorative: results are ranked by it, so "next.js" plus "middleware that checks a JWT" produces a more sensible list than "next.js" alone.

It returns not one answer but a list of candidates, each with the signals you choose by:

• Library ID - the identifier in /org/project form
• Name and Description - the name and a short summary
• Code Snippets - how many code examples are in the index
• Source Reputation - source authority: High, Medium, Low or Unknown
• Benchmark Score - a quality indicator where 100 is the maximum
• Versions - a list of versions where they exist

The second tool is query-docs. It takes the chosen libraryId and a query and returns documentation. Calling it without the first step is allowed in one case only: when the user wrote the identifier themselves in /org/project form.

Both schemas carry the same limit, written in capitals in the tool description: do not call more than three times per question. The wording on resolve-library-id is direct: "If you cannot find what you need after 3 calls, use the best result you have." It is a guard against the loop where an agent endlessly refines its query and burns tokens.

The Library Identifier and the Version

The identifier looks like a path: /vercel/next.js, /supabase/supabase, /mongodb/docs. If you know it already, name it in the prompt and save the lookup step - the README shows it like this:

A version goes in as a third segment: /vercel/next.js/v14.3.0-canary.87. You rarely need to spell it out - mentioning the version in the question is enough, and the matching identifier gets picked during the lookup:

The skill installed alongside MCP explicitly tells the agent to prefer version-specific identifiers when the user names a version. This is the case where one word in the question changes the quality of the answer more than any setting does.

One Question, One Concept

The most useful rule in the whole project's documentation is not about installation but about phrasing.

The description of query-docs states what the query argument should be: specific, detailed and about a single topic. It gives examples of good and bad right there:

The reason is stated honestly: a broad query dilutes ranking and returns a shallow result for each of the topics at once. When a question spans several distinct concepts, the skill tells the agent to resolve the identifier once and make a separate query-docs call per topic. There is one exception - when the question is precisely about how those things interact.

The practical takeaway is for the human, not the agent: phrase the task so that it holds one topic. "Set up middleware and wire in auth and fix caching" is three different questions in one sentence, and the documentation for each of them will arrive incomplete.

The CLI Does More Than Documentation

Install the context7-cli skill and it turns out ctx7 handles three things: documentation, skill management and MCP setup.

Documentation is two commands, in strict order:

Skills are a separate set with nothing to do with documentation itself:

Sign-in and configuration:

Most commands work without signing in. The exceptions are listed in the skill: skills generate always requires it, and ctx7 setup requires it unless --api-key or --oauth is passed. Signing in also raises the rate limits on documentation commands. The interactive sign-in can be bypassed entirely with an environment variable:

The "Common Mistakes" section in that same skill deserves its own mention - four things people trip over on day one:

• a library identifier needs the leading slash: /facebook/react, not facebook/react;
• always run ctx7 library first - ctx7 docs react "hooks" fails without a valid identifier;
• the repository format for skills is /owner/repo, for example ctx7 skills install /anthropics/skills;
• skills generate does not work without signing in.

A Rule Instead of a Skill

If no skill was installed, the agent can be nudged with an ordinary rule. The README offers ready wording to drop into CLAUDE.md, into Cursor's rules or into your tool's equivalent:

The repository also carries a longer version - the file rules/context7-mcp.md. It spells out the same four steps as the skill: resolve-library-id first, then picking the best match by name, description relevance, snippet count, source reputation and benchmark score, then query-docs on a single topic, and only then the answer.

There is a practical detail in there that saves time: if the results look wrong, try a different spelling of the name - "next.js" rather than "nextjs" - or rephrase the question.

What Leaves Your Machine

A fair question, given that documentation arrives from outside.

The first thing to know: what goes to the server is not your original question. The query is composed by the model at the moment it calls the tool. The Upstash blog says it directly: "The query sent to Context7 is generated by the LLM, not your original prompt. Your actual question never leaves your machine - we only receive the LLM's reformulated query for documentation lookup."

The second is a warning built into the description of query-docs itself: do not put anything sensitive into the query - API keys, passwords, credentials, personal data, proprietary code. The wording in the source is addressed to the model, but it applies to you too: if you dictate the query to the agent word for word, whatever you dictated goes in.

The third is about quality rather than privacy. The first disclaimer in the README leaves no ambiguity: documentation in Context7 is contributed by the community, and the project does not guarantee its accuracy, completeness or security. Projects in the index are maintained by their owners, not by Context7. The same paragraph holds a sentence worth reading whole: "By using Context7, you acknowledge that you do so at your own discretion and risk."

The practical conclusion is simple. Current documentation from the index beats a model's two-year-old memory, but that does not make it the primary source. For the parts that matter - migrations, security, payments - open the project's page with your own eyes.

Running It Locally and Checking It

When you need to see exactly what the server returns, run it from source.

The same server over HTTP on a port of your choosing:

And over stdio with a key:

The easiest way to confirm the client really sees the tools is the inspector - it opens an interactive panel where both tools can be called by hand:

When Something Does Not Work

The troubleshooting guide opens with a short checklist that covers most cases: confirm Node.js 20 or newer is installed; update to the latest package; verify connectivity with curl https://mcp.context7.com/ping; add a key if you are hitting rate limits; enable verbose logs with DEBUG=* before collecting information for support.

The tip that comes first in the guide is disarming: Node.js problems disappear entirely if you connect to the remote server instead of running one locally. Most clients can talk to https://mcp.context7.com/mcp directly, and then no local Node.js is needed at all.

Of the specific cases, three come up most often. For ERR_MODULE_NOT_FOUND the guide suggests replacing npx with bunx or deno. Separate sections cover ESM resolution and TLS certificates. Proxy configuration is there too: the server reads the https_proxy and HTTPS_PROXY variables, and the proxy can also be set directly in the MCP client's settings.

The Numbers the Project Publishes

Context7 does publish measurements, and they need handling with care: these are the vendor's own benchmarks on its own question sets, not an independent audit. There are several publications and their baselines differ.

In January 2026 a post covered the move to a new architecture: context reported down from roughly 9.7 thousand to 3.3 thousand tokens, latency from 24 to 15 seconds, and tool calls from 3.95 to 2.96. The method is described: more than eighty coding questions, the old and new architectures run over identical sets, quality scored by a separate model on a ten-point scale.

In May 2026 came a comparison against Claude Code's web search - different metrics and a different baseline, reporting average reductions in total tokens and cost.

In July 2026 a third measurement covered an air-gapped setting: fifty questions in five categories, one model in two modes - its own knowledge alone against locally served Context7 documentation. The most vivid pair of numbers comes from there: ten hallucinated APIs against zero.

These figures cannot be added into one conclusion - the baselines differ. What matters more is that each publication describes its method, and that alone separates them from marketing percentages with no explanation of where they came from.

What Context7 Does Not Do

It does not replace reading documentation yourself - it saves the window-switching while you write code with an agent.

It does not help with work where no library is involved: refactoring, debugging your own business logic, code review, general language questions. That is written into the server's own instructions, and an agent that reaches for Context7 on every question is simply spending calls.

It does not guarantee that the documentation in the index is complete or accurate: the community brings it in.

And it does not work offline - the index lives on the service's side, and the public repository holds the client part only.

Mistakes of the First Encounter

Installing MCP where a skill would do. If the agent already runs terminal commands, CLI + Skills is simpler: fewer moving parts and no extra server to keep up.

Asking one broad question instead of three narrow ones. Ranking gets diluted and each topic comes back shallow. The project explicitly asks you to split such questions into separate calls.

Forgetting the slash in the identifier. /facebook/react works, facebook/react does not. The mistake costs one failed call and a minute of confusion.

Calling docs without library. The order is a requirement, not a suggestion: without a valid identifier the second command fails.

Keeping the key in both the flag and the environment variable. The flag always wins and the variable is silently ignored - the most annoying of the non-obvious details here.

Confusing the Node.js requirements. Version 18 suits the CLI but not the MCP server, which needs at least 20.18.1.

Treating the index as a primary source. Documentation is contributed by the community, the project makes no accuracy guarantee and says so in plain words.

To put it in one sentence: Context7 is useful exactly where the question is about a library, and exactly as far as that question is precisely phrased.

Sources

This article was checked against the upstash/context7 repository (branch master), the official documentation and the Upstash blog posts on 25 August 2026: the README, packages/mcp/package.json, packages/cli/package.json, the MCP server source packages/mcp/src/index.ts, the developer guide, the troubleshooting guide, the context7-mcp and context7-cli skills, and the rule rules/context7-mcp.md. The project moves fast and the CLI and MCP server version independently, so check the README of your installed version before configuring anything.

• GitHub: upstash/context7
• Context7 website
• MCP server source
• The context7-mcp skill
• The context7-cli skill
• The agent rule
• Developer guide
• Troubleshooting guide
• Setup for 30+ clients
• CLI reference
• Adding your library
• REST API reference
• Blog: the new architecture and its benchmarks
• Blog: comparison against web search
• Blog: the air-gapped benchmark