# Context7 resolves a library ID before it fetches any docs

> Context7 feeds version specific library documentation to AI coding agents, through either a ctx7 CLI skill or a hosted MCP server. The interface is two steps, resolve a library ID then query it, and the crawler and index that make the first step work sit outside this repository.

**upstash/context7** — Context7 feeds up-to-date, version-specific library documentation and code examples straight into LLM prompts via MCP, reducing outdated answers and hallucinated APIs.

- Repository: https://github.com/upstash/context7
- Website: https://context7.com
- Stars: 62,531 · Forks: 3,035
- Language: TypeScript
- License: MIT
- Published: 2026-08-08 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/upstash-context7

## Two ways in: a ctx7 skill, or a hosted MCP server

Context7 works in two modes, and the choice decides what you maintain. CLI plus Skills installs a skill that tells your agent to fetch documentation with ctx7 commands, and needs no MCP server. MCP mode registers a Context7 MCP server so the agent calls documentation tools natively. The single setup command covers both, needs Node.js 18 or newer, authenticates over OAuth, generates an API key and installs the right skill:

```bash
npx ctx7 setup
```

Pass --cursor, --claude or --opencode when you want one specific agent rather than a prompt. The undo path is equally explicit: npx ctx7 remove clears the generated setup, and a global CLI installed with npm install -g ctx7 has to be uninstalled separately with npm uninstall -g ctx7. Two copies of the tool are therefore easy to leave behind.

For a manual MCP setup the endpoint is https://mcp.context7.com/mcp and the key travels in an Authorization: Bearer YOUR_API_KEY header. The badge at the top of the README is a Cursor deep link whose config parameter is base64 for the JSON {"url":"https://mcp.context7.com/mcp"}, which is the same endpoint a client would configure by hand.

## resolve-library-id runs first, and what it returns is a ranking

Every docs fetch in MCP mode is two calls. resolve-library-id turns a library name into a Context7 compatible ID and takes two required arguments: query, described as the user's question or task and used to rank results by relevance, and libraryName. query-docs then takes the exact ID plus a query, with examples given as /mongodb/docs and /vercel/next.js.

Because the first argument is used for ranking, the ID you get back is a relevance decision rather than an exact match. When the resolver picks the wrong library, the second call still succeeds and returns confident documentation for a library you did not ask about. Nothing in the two tool signatures reports a low confidence score, so the mistake surfaces as a plausible answer, not as an error.

The CLI exposes the same two steps as ctx7 library <name> <query> and ctx7 docs <libraryId> <query>, which is useful for checking an ID by hand before an agent depends on it. When you already know the library, the slash syntax skips resolution entirely: a prompt carrying use library /supabase/supabase for API and docs tells Context7 exactly which library to load.

## A version exists only if you type it, because no tool takes one

Version selection is a prompt instruction, not a parameter. The documented way to get version specific docs is to mention the version in the question, for example How do I set up Next.js 14 middleware? use context7, and the claim is that Context7 will automatically match the appropriate version. If the version is absent from the prompt, nothing else supplies one.

Look at the tool definitions and the gap is visible. resolve-library-id takes query and libraryName. query-docs takes libraryId and query. The slash syntax pins identity but not release. A program built on @upstash/context7-sdk or on the CLI therefore has no field to pin a version into, which means a version guarantee survives only as long as somebody keeps writing the number into the question.

The consequence for an agent is quiet. A missing version does not raise an error; it returns whatever the index holds for that library, and generated code then targets an API shape the reader did not ask for. Pinning by hand in every prompt is the only mechanism the interface offers.

## MCP_MAX_SUBSCRIPTIONS=0, because the advertised capabilities never change

The sample environment file explains one default better than any documentation would. Next to MCP_MAX_SUBSCRIPTIONS=0 there is a comment saying it is the maximum concurrent MCP notification subscriptions per process, and that Context7's advertised capabilities are static, so subscriptions are disabled by default.

That is a real constraint on long running work. Nothing pushes a change to an agent, so a session that fetched docs for a library an hour ago has no way to learn the index moved, and re-querying is the only way to notice. The rest of the same file is infrastructure for the hosted deployment: CONTEXT7_API_KEY with CONTEXT7_API_URL=https://context7.com/api, OAuth and OIDC variables including VERCEL_MARKETPLACE_OIDC_ISSUER, HTTPS_PROXY and NODE_EXTRA_CA_CERTS for a machine behind a corporate proxy, and CTX7_TELEMETRY_DISABLED with CLAUDE_CONFIG_DIR and EDITOR under a CLI behaviour heading. GITHUB_TOKEN and GH_TOKEN sit under a GitHub integration heading, and the sample does not say which component reads them.

## Only the MCP server is open source, so the index cannot be rebuilt locally

The second item of the disclaimer is the one that shapes your options: this repository hosts the MCP server source code, and the API backend, parsing engine and crawling engine are private and not part of it. Running the server yourself, which the developer guide covers, gives you a process that talks to a Context7 service. It does not give you the service.

Practically, a library that is missing, stale or wrongly identified cannot be fixed from an open source checkout. The available routes are the submission page for adding libraries, the Report button on a project page for content that looks wrong, and the add a library documentation page. All three end in somebody else's queue, which is the opposite of the self hosted answer most people assume a fetch based tool will offer.

The network shape follows from that. CONTEXT7_API_URL points at https://context7.com/api and the MCP endpoint is a hosted hostname, so every docs call your agent makes leaves the machine. The environment sample also marks MCP_CLIENT_IP_ASSERTION_KEY as required for hosted HTTP deployments and as something that must match context7.com, which is the clearest sign in the tree that this code is meant to run as the service.

## No guarantee covers the documentation Context7 puts in the prompt

The first disclaimer is unusually blunt about provenance. Projects listed in Context7 are community contributed, the maintainers say they cannot guarantee the accuracy, completeness or security of all library documentation, and they state that listed projects are developed and maintained by their respective owners rather than by Context7. Users are told they use it at their own discretion and risk, and that suspicious content should go through the Report button on the project page.

That chain matters because of where the text lands. Documentation written by a stranger is inserted into a prompt that an agent then follows, so a wrong function signature becomes wrong generated code, and the code carries no marker saying which library version it came from. The failure looks like a model mistake rather than a retrieval mistake, which is the worst shape for debugging.

What you can rely on is the reporting path, not the accuracy. For code you will ship, treat Context7 output as a starting point to check against the library's own site, and for a version sensitive integration keep the version in the prompt where the interface can see it.

## The root package is private, and the three published versions disagree

package.json at the root is marked private with version 1.0.0 and a workspaces entry of packages/*, so that number is internal bookkeeping and no consumer can depend on it. The published surface is the package list: @upstash/context7-mcp for the server, ctx7 for the CLI, @upstash/context7-sdk as a TypeScript SDK, @upstash/context7-tools-ai-sdk for Vercel AI SDK tools, and @upstash/context7-pi as a pi.dev extension.

Those three sit on three different version lines. On 2026-09-22 the releases include ctx7@0.5.12, @upstash/context7-sdk@0.5.0 and @upstash/context7-tools-ai-sdk@1.0.2, published within seconds of each other. Nothing in that pattern tells you which component is considered stable, so the only honest move is to pin the one you use and read its own changelog.

Builds run through pnpm: build and test recurse with pnpm -r, while build:mcp and build:ai-sdk filter to a single package, and publishing is driven by changesets with release running pnpm build and then changeset publish. A second script, release:snapshot, versions a canary and publishes with --no-git-tag, so a canary in the registry has no git tag pointing at the commit that produced it.

## Fifteen READMEs and a set of agent manifests live in the same tree

Beyond the packages, the repository carries the integration surface for several agents at once: server.json, gemini-extension.json, a .claude-plugin/ directory, plus plugins/, skills/, rules/, .agents/, docs/ and public/. This is a distribution for agent configuration, not only a library, and it is where the two ways of enabling Context7 meet.

The automatic path is a skill installed by ctx7 setup, configured to trigger on library questions. The manual path is a rule you write yourself, into Cursor Settings > Rules or into CLAUDE.md, with the example text telling the agent to use Context7 whenever you need library or API documentation, code generation, setup or configuration steps without being asked. Nothing stops a team from ending up with both, and then there are two rules to keep in step when behaviour changes.

The i18n/ directory holds fifteen translated READMEs, from README.zh-CN.md and README.ja.md through README.ar.md and README.vi.md. Every instruction in this article therefore exists in fifteen copies, and a fix to the English original has to be carried to each one.

## Conclusion

Adopt Context7 when your agent's wrong answers come from stale library knowledge and your team can accept documentation it did not write, because the two tools you get are a resolver and a query, and both are documented well enough to predict their behaviour. Do not adopt it as a pinned dependency: no tool takes a version argument, the index is built by code you cannot read, and the service is reached over the network on a hosted endpoint. Check first that the libraries you care about resolve to the IDs you expect, by running ctx7 library against them, before you wire the MCP server into an agent that will act on the answer.

## FAQ

### How much does Context7 cost?

The README mentions a free API key from the context7.com dashboard and says it is recommended for higher rate limits, which implies a lower limit without one. No prices are published in the repository, so the dashboard is the only place the numbers live.

### How do I install Context7?

Run npx ctx7 setup, which requires Node.js 18 or newer, authenticates via OAuth, generates an API key and installs the appropriate skill. Add --cursor, --claude or --opencode to target a single coding agent, and undo the setup later with npx ctx7 remove.

### What are Context 7 Skills?

A skill is what the CLI installs: it guides your agent to fetch documentation using ctx7 CLI commands, with no MCP server required. Choosing MCP mode instead registers a Context7 MCP server that exposes the resolve-library-id and query-docs tools.

### How do I use Context7 with an MCP client?

Point the client at https://mcp.context7.com/mcp and send your key in an Authorization: Bearer YOUR_API_KEY header, or let npx ctx7 setup register the server for you. The README links manual installation instructions covering more than 30 clients.

### How do I use Context7 with Claude Code?

Installing with ctx7 setup configures a skill automatically. To do it by hand, add a rule to CLAUDE.md, and the example rule tells the agent to use Context7 for library or API documentation, code generation, setup and configuration without being asked.

## Sources

- [Official documentation](https://context7.com)
- [Official README](https://github.com/upstash/context7#readme)
- [Project repository](https://github.com/upstash/context7)
- [Release notes](https://github.com/upstash/context7/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/upstash-context7