upstash · context7 · Sep 10, 2026
diff --git a/docs/clients/cli.mdx b/docs/clients/cli.mdx
@@ -190,6 +190,21 @@ When `--base-url` targets a custom deployment, setup skips the npm update check
 | ---------------------- | ------------------------------------------------------------------------------ |
 | Agent skills directory | `docs` skill — guides the agent to use `ctx7 library` and `ctx7 docs` commands |
 
+### Skill installation
+
+`ctx7 setup` installs a skill alongside the rule and MCP config:
+
+- **MCP mode** downloads the `context7-mcp` skill from GitHub. If the download fails, setup falls back to a bundled copy of the skill (`installed (bundled fallback)`) and still completes — the skill install is not a hard failure.
+- **CLI + Skills mode** downloads the `find-docs` skill. If that download fails, setup stops with an error before installing anything.
+
+Skills are written to the agent's skills directory — for example `.agents/skills/` for Codex and other universal agents, `.claude/skills/` for Claude Code, `.cursor/skills/` for Cursor. To retry or install manually after a failure, use the skills command:
+
+```bash
+ctx7 skills install /upstash/context7 context7-mcp
+```
+
+or place the `SKILL.md` manually in the target skills directory. The source file lives at [`skills/context7-mcp/SKILL.md`](https://github.com/upstash/context7/blob/master/skills/context7-mcp/SKILL.md) in the repository.
+
 ### ctx7 remove
 
 Remove the setup written by `ctx7 setup`. By default this removes both MCP setup and CLI setup for the selected agent.

diff --git a/docs/clients/codex.mdx b/docs/clients/codex.mdx
@@ -123,6 +123,10 @@ How does Supabase storage work?
 ```
 </Accordion>
 
+<Accordion title="CLI requests fail inside the sandbox">
+If you use CLI + Skills mode, `ctx7 setup` installs guidance telling Codex to run Context7 CLI requests outside its default sandbox. If a `ctx7` command fails with DNS or network errors (such as `ENOTFOUND`, host resolution failures, or `fetch failed`), rerun it outside the sandbox instead of retrying inside it.
+</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>

diff --git a/docs/docs.json b/docs/docs.json
@@ -238,7 +238,7 @@
               {
                 "group": "Resources",
                 "expanded": false,
-                "pages": ["resources/developer", "resources/troubleshooting"]
+                "pages": ["resources/developer", "resources/technical-reference", "resources/troubleshooting"]
               }
             ]
           }

diff --git a/docs/resources/developer.mdx b/docs/resources/developer.mdx
@@ -90,6 +90,30 @@ CONTEXT7_API_KEY=your_api_key_here
 }
 ```
 
+## MCP Tools
+
+The server registers two tools. Both are read-only, idempotent, and open-world (annotations: `readOnlyHint`, `idempotentHint`, and `openWorldHint` are `true`; `destructiveHint` is `false`).
+
+### resolve-library-id
+
+Resolves a package/product name to a Context7-compatible library ID and returns matching libraries. Call this before `query-docs` unless the user already provides a library ID in `/org/project` or `/org/project/version` format.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `libraryName` | string | yes | Library name to search for and resolve to a Context7-compatible library ID. Use the official name with proper punctuation (e.g., "Next.js" not "nextjs"). |
+| `query` | string | yes | What to look up in the library's documentation, used to rank results by relevance. Sent to the Context7 API; do not include sensitive or confidential information. |
+
+### query-docs
+
+Retrieves and queries up-to-date documentation and code examples for a library. Requires a valid library ID from `resolve-library-id` (or one provided directly by the user).
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `libraryId` | string | yes | Exact Context7-compatible library ID (e.g., `/vercel/next.js` or `/vercel/next.js/v14.3.0-canary.87`). |
+| `query` | string | yes | What to look up, scoped to a single concept. Make a separate call per concept unless the question is about how concepts interact. Do not include sensitive or confidential information. |
+
+The server declares the `prompts` and `resources` capabilities but registers no prompts and no resources — `prompts/list` and `resources/list` answer with empty collections.
+
 ## Local Development Configuration
 
 When developing locally, use this configuration to run from source:

diff --git a/docs/resources/technical-reference.mdx b/docs/resources/technical-reference.mdx
@@ -0,0 +1,39 @@
+---
+title: Technical Reference
+description: Package names, versions, runtime requirements, and version migration notes for the Context7 SDK, CLI, and MCP server
+---
+
+Reference for the Context7 packages: current versions, runtime requirements, and breaking changes to watch for when upgrading.
+
+## Packages
+
+| Package | npm name | Current version | Node.js |
+|---------|----------|-----------------|---------|
+| CLI | [`ctx7`](https://www.npmjs.com/package/ctx7) | `0.5.11` | 18+ |
+| MCP server | [`@upstash/context7-mcp`](https://www.npmjs.com/package/@upstash/context7-mcp) | `4.0.7` | 20.18.1+ |
+| TypeScript SDK | [`@upstash/context7-sdk`](https://www.npmjs.com/package/@upstash/context7-sdk) | `0.4.1` | 18+ |
+
+Related packages: [`@upstash/context7-tools-ai-sdk`](https://www.npmjs.com/package/@upstash/context7-tools-ai-sdk) (Vercel AI SDK tools) and [`@upstash/context7-pi`](https://www.npmjs.com/package/@upstash/context7-pi) (pi.dev extension).
+
+For how queries are stored and used (reranking providers, retention, and enterprise opt-out), see [Data Privacy](/security/data-privacy).
+
+## Versioning & Migration
+
+Breaking changes and deprecations to be aware of when upgrading.
+
+### SDK — v0.2.0 API simplification
+
+The SDK API was simplified in `0.2.0`:
+
+- `getDocs()` was replaced by `getContext(query, libraryId, options)`, which takes a `query` for relevance-based retrieval
+- `searchLibrary(query, libraryName)` now takes both a query and a library name
+- Response types were renamed (`Library` and `Documentation` instead of `SearchResult`, `CodeDocsResponse`, etc.)
+- Pagination, mode, topic, and limit options were removed from context retrieval
+
+### CLI — research mode removed (v0.4.1)
+
+Research mode was removed entirely. The `query-docs` MCP tool no longer accepts or forwards a `researchMode` parameter, and the CLI no longer exposes a `--research` flag on `ctx7 docs`.
+
+### CLI — skill commands deprecated
+
+The `ctx7 skills ...` commands are deprecated and will stop working in the next major release. The `context7-mcp` and `find-docs` skills installed by `ctx7 setup` are unaffected.
diff --git a/docs/tips.mdx b/docs/tips.mdx
@@ -36,3 +36,12 @@ How do I set up Next.js 14 middleware? use context7
 ```
 
 Context7 will automatically match the appropriate version.
+
+## Query Strategy
+
+Context7 grounds your assistant with up-to-date docs, but the quality of what it retrieves depends on how the retrieval is scoped. These habits keep the retrieved context minimal and relevant:
+
+- **Retrieve only when needed** — Context7 is for library, framework, SDK, API, and CLI-tool questions. Skip it for refactoring, writing scripts from scratch, debugging business logic, code review, or general programming concepts.
+- **One concept per query** — scope each query to a single topic. Split multi-topic questions (e.g. "routing and auth and caching") into a separate query per concept, unless the question is about how the concepts interact. Combined queries dilute ranking and return shallow results for each topic.
+- **Be specific, not vague** — a query like `"How to set up authentication with JWT in Express.js"` returns far better results than `"auth"` or `"hooks"`.
+- **Keep the context relevant** — don't include sensitive or confidential information in queries, and use the best-matching library ID (and version-specific ID when a version matters) so you don't pull docs for the wrong package.