Context7 User Guide

Context7 pulls up-to-date, version-specific documentation and code examples straight from the source and places them directly into your AI coding agent's context. Instead of relying on a model's stale training data — which produces outdated examples and hallucinated APIs that don't exist — your agent fetches current docs the moment it needs them.

This repository (upstash/context7) is a monorepo that ships five products, each a different way to get Context7 documentation into your workflow:

Whichever product you use, the result is the same: your agent gains two capabilities — resolve a library name to a Context7 ID, and fetch documentation for that library.

Note

This guide covers the open-source tooling in this repository. The Context7 web platform (the dashboard, the documentation index, billing) lives at context7.com. The API backend, parsing engine, and crawling engine that power the documentation index are private and not part of this repository.

1. Quick Start

The fastest way to add Context7 to your AI coding agent is the CLI's one-command setup:

npx ctx7 setup

This authenticates you via your browser, generates an API key, and installs the right integration for your agent. You'll be asked to choose between two modes:

• MCP server — your agent calls Context7 tools natively over the Model Context Protocol.
• CLI + Skills — installs a skill that teaches your agent to fetch docs by running ctx7 commands (no MCP server required).

Once set up, just mention a library in your prompt and add use context7:

Create a Next.js middleware that checks for a valid JWT in cookies
and redirects unauthenticated users to /login. use context7

Your agent fetches the current Next.js docs and writes code against the real API.

Tip

You can use Context7 without any API key, but anonymous requests are rate-limited. Get a free API key at context7.com/dashboard for higher limits — ctx7 setup creates one for you automatically.

2. Installation

2.1 Requirements

Note

The tools-ai-sdk package targets the Vercel AI SDK and requires AI SDK >=6.0.0. The pi extension requires the pi coding agent runtime. See Section 7 for those.

2.2 Install the CLI

You usually don't need to install the CLI permanently — npx ctx7 <command> runs the latest version on demand. To install it globally:

npm

npm install -g ctx7

pnpm

pnpm add -g ctx7

bun

bun add -g ctx7

Verify the install:

ctx7 --version

0.4.5

2.3 Run setup

npx ctx7 setup

Setup walks you through three choices interactively:

1. Access mode — MCP server or CLI + Skills.
2. Which agents to configure (Claude Code, Cursor, OpenCode, Codex, Gemini CLI, Antigravity).
3. Authentication — by default it logs you in via OAuth and generates an API key.

To skip the prompts and target a specific agent and mode directly:

# MCP mode for Claude Code, no questions asked
npx ctx7 setup --claude --mcp --yes

# CLI + Skills mode for Cursor
npx ctx7 setup --cursor --cli

Tip

Add --project (-p) to configure Context7 only for the current project instead of your global agent config. This writes the MCP entry and skill into the project directory.

2.4 Manual MCP installation (any client)

If your client isn't covered by ctx7 setup, configure the hosted MCP server manually. Point your MCP client at:

https://mcp.context7.com/mcp

Pass your API key via the CONTEXT7_API_KEY header. The Gemini CLI extension shipped in this repo (gemini-extension.json) shows the canonical stdio shape:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp", "--api-key", "${CONTEXT7_API_KEY}"]
    }
  }
}

See the platform's all-clients guide for 30+ client-specific recipes.

3. Everyday Usage

This section covers the two things you'll do most: getting better results in your agent, and querying docs directly from the terminal.

3.1 Triggering Context7 in your agent

After setup, Context7 activates automatically for library-related questions. Three techniques sharpen the results.

Add use context7 to your prompt. This explicitly tells the agent to fetch docs:

Configure a Cloudflare Worker script to cache JSON API responses
for five minutes. use context7

Name the library ID directly. If you already know the Context7 ID, skip the search step:

Implement basic authentication with Supabase.
use library /supabase/supabase for API and docs.

The slash syntax (/owner/repo) tells Context7 exactly which library to load.

Specify a version. Mention a version in your prompt and Context7 matches the right docs:

How do I set up Next.js 14 middleware? use context7

Tip

If you set up in MCP mode, your agent has two tools available: resolve-library-id (find the right library) and query-docs (fetch its documentation). The agent calls them automatically — you rarely invoke them by hand.

3.2 Fetching docs from the terminal

The CLI can query documentation directly, which is handy for scripts, quick lookups, or piping into other tools.

Find a library's Context7 ID:

npx ctx7 library react "how to use hooks"

1. Title: React
   Context7-compatible library ID: /facebook/react
   Description: The library for web and native user interfaces
   Code Snippets: 2847
   Source Reputation: High
   Benchmark Score: 95
   Versions: v19.0.0, v18.3.1, v18.2.0

Quick command:
  ctx7 docs "/facebook/react" "<your question>"

The second argument (the query) is optional — it ranks results by relevance to what you're trying to do.

Fetch documentation for a library ID:

npx ctx7 docs /facebook/react "useEffect cleanup examples"

The library ID must be in /owner/repo or /owner/repo/version form. If you pass a bare name, the CLI tells you to resolve it first:

✖ Invalid library ID: "react"
Expected format: /owner/repo or /owner/repo/version (e.g., /facebook/react)
Run "ctx7 library <name>" to find the correct ID

Get machine-readable output with --json on either command — useful for scripting:

npx ctx7 docs /vercel/next.js "app router middleware" --json

3.3 Authenticating the CLI

Most ctx7 commands work anonymously, but logging in raises your rate limits and unlocks features like skill generation.

# Log in (opens your browser)
npx ctx7 login

# Check who you're logged in as
npx ctx7 whoami

# Log out
npx ctx7 logout

$ npx ctx7 whoami
Logged in
Name:        Ada Lovelace
Email:       [email removed]
Teamspace:   Analytical Engines

Note

ctx7 login opens a browser for OAuth. If you're on a machine with no browser (a remote server or SSH session), pass --no-browser to print the URL so you can open it elsewhere — then complete the flow in any browser that can reach localhost on the server. See Troubleshooting for remote-server caveats.

3.4 Keeping the CLI up to date

# Check whether a newer version exists
npx ctx7 upgrade --check

# Upgrade now (prompts for confirmation)
npx ctx7 upgrade

$ npx ctx7 upgrade
Update available: v0.4.5 -> v0.4.6
Upgrade command: npm install -g ctx7@latest
? Run npm install -g ctx7@latest now? (Y/n)

The CLI detects how it was installed (npm, pnpm, bun) and suggests the matching upgrade command. Add -y/--yes to run it without prompting. When you run via npx/pnpm dlx/bunx, there's nothing to upgrade in place — the CLI tells you to use the @latest tag instead.

4. Configuring Your Agent with setup

The setup command is the heart of the CLI. It writes the integration files your agent needs and is safe to re-run — it reconfigures rather than duplicating.

4.1 What setup installs

The rule nudges your agent to reach for Context7 whenever it needs library documentation.

4.2 setup options

Important

--stdio and --oauth are mutually exclusive — OAuth only applies to the hosted HTTP endpoint. If you pass both, setup stops with an error.

4.3 Choosing transport (HTTP vs stdio)

In MCP mode, setup defaults to the hosted HTTP endpoint (https://mcp.context7.com/mcp), which requires no local process. Use --stdio to run the MCP server locally instead — your agent launches @upstash/context7-mcp as a child process. stdio is useful when you want the server running entirely on your machine or behind your own network controls.

Tip

When you re-run setup over an existing --stdio entry, the CLI preserves your existing @upstash/context7-mcp invocation (including a pinned version) and only swaps the API key.

4.4 Removing a setup

# Remove everything Context7 added (prompts for what to remove)
npx ctx7 remove

# Remove the MCP setup from Claude Code
npx ctx7 remove --claude --mcp

# Remove both MCP and CLI setups from Cursor
npx ctx7 remove --cursor --all

remove (alias: uninstall) detects which agents and modes you have configured and lets you pick. It cleans up the MCP config entry, the rule, and the installed skills. Options mirror setup: --claude, --cursor, --opencode, --codex, --antigravity, --gemini, plus --mcp, --cli, --all, -p/--project, and -y/--yes.

If nothing is detected and you didn't name an agent, the CLI asks you to pass an explicit --<agent> flag.

5. Generating Skills

Beyond fetching docs, the CLI can generate a reusable skill for a library using AI. A skill encodes best practices, constraints, and decision-making for working with a library — not a one-off tutorial. Your agent loads the skill whenever the topic comes up.

Note

Skill generation requires you to be logged in (ctx7 login) and counts against a weekly quota. Free accounts get a limited number of generations per week; Pro accounts get more. The CLI tells you your remaining quota if you hit the limit.

Generate a skill:

npx ctx7 skills generate

The command walks you through:

1. Describe the expertise you want — phrased as a capability, not a task.
2. Select sources — Context7 finds relevant libraries; you pick which to base the skill on.
3. Answer scoping questions to clarify constraints (each has a recommended default).
4. Review the generated skill — install it, open it in your $EDITOR to tweak, request changes, or cancel.
5. Choose where to install it (Claude Code, Cursor, Universal, etc.).

Tip

Good skill descriptions are about decision-making, not steps. Compare:

• ✕ "Deploy a Next.js app to Vercel"
• ✓ "Best practices and constraints for deploying Next.js apps to Vercel"

5.1 Skill install locations

Skills are written into agent-specific directories. The Universal target (.agents/skills/) is read natively by many agents at once (Amp, Codex, Gemini CLI, GitHub Copilot, OpenCode, and more), so one install covers them.

Note

The ctx7 skills command group (install, search, list, remove, info, suggest, generate) is deprecated and prints a warning. It will stop working in the next major release. Skill generation and the setup-installed skills remain supported; the standalone "Skill Hub" install/search commands are the ones being retired.

6. Using the MCP Server Directly

If you'd rather run the MCP server yourself than use ctx7 setup, you can launch it directly. It supports two transports.

stdio (default) — for local agent integrations:

npx @upstash/context7-mcp --api-key YOUR_API_KEY

Or set the key via environment variable:

CONTEXT7_API_KEY=YOUR_API_KEY npx @upstash/context7-mcp

HTTP — for a long-running server:

npx @upstash/context7-mcp --transport http --port 3000

Context7 Documentation MCP Server v3.1.0 running on HTTP at http://localhost:3000/mcp

Caution

--api-key is not allowed with --transport http — in HTTP mode, callers authenticate per-request via headers, not a server-wide key. Likewise, --port is rejected with --transport stdio. Passing an incompatible flag exits with an error.

The MCP server exposes two tools to your agent:

• resolve-library-id — takes a libraryName and a query, returns matching Context7 library IDs ranked by relevance.
• query-docs — takes a libraryId and a query, returns the documentation.

Note

Both tools instruct the agent not to call them more than 3 times per question. The server is read-only — it never modifies your code or files.

Running your own HTTP MCP server requires Redis and additional configuration. See the Admin Guide for full deployment details.

7. Using the Libraries in Your Own Code

If you're building your own application or agent, three packages let you call Context7 programmatically.

7.1 TypeScript SDK (@upstash/context7-sdk)

A typed client for calling Context7 from Node.js or the browser.

npm install @upstash/context7-sdk

import { Context7 } from "@upstash/context7-sdk";

// Reads CONTEXT7_API_KEY from the environment if you omit `apiKey`
const client = new Context7({ apiKey: "ctx7sk-..." });

// Search for a library — returns Library[]
const libraries = await client.searchLibrary("I need to build a UI", "react");
console.log(libraries[0].id); // "/facebook/react"

// Fetch documentation — returns Documentation[] by default
const docs = await client.getContext("How to use hooks", "/facebook/react");
for (const doc of docs) {
  console.log(doc.title, doc.source);
}

Both methods accept a { type: "json" | "txt" } option. json (the default) returns structured objects; txt returns a single formatted string:

const text = await client.getContext("routing", "/vercel/next.js", { type: "txt" });

Important

An API key is required. Pass it to the constructor or set the CONTEXT7_API_KEY environment variable — otherwise the constructor throws Context7Error: API key is required. Keys start with the ctx7sk prefix.

The client automatically retries failed requests (up to 5 times with exponential backoff). Invalid library IDs and empty queries throw Context7Error.

7.2 Vercel AI SDK tools (@upstash/context7-tools-ai-sdk)

Drop-in tools and an agent for the Vercel AI SDK (v6+).

npm install @upstash/context7-tools-ai-sdk ai zod

Use the tools with generateText:

import { resolveLibraryId, queryDocs } from "@upstash/context7-tools-ai-sdk";
import { generateText, stepCountIs } from "ai";
import { openai } from "@ai-sdk/openai";

const { text } = await generateText({
  model: openai("gpt-4o"),
  prompt: "Find React documentation about hooks",
  tools: {
    resolveLibraryId: resolveLibraryId(),
    queryDocs: queryDocs(),
  },
  stopWhen: stepCountIs(5),
});

Or use the ready-made agent:

import { Context7Agent } from "@upstash/context7-tools-ai-sdk";
import { anthropic } from "@ai-sdk/anthropic";

const agent = new Context7Agent({
  model: anthropic("claude-sonnet-4-20250514"),
  apiKey: "ctx7sk-...", // or CONTEXT7_API_KEY env var
});

const result = await agent.generate({
  prompt: "How do I use React Server Components?",
});

Context7Agent wires both Context7 tools into a multi-step loop (default: stop after 5 steps) and ships with a system prompt tuned for documentation lookups. You can pass your own instructions, stopWhen, and additional tools.

Tip

The tools read CONTEXT7_API_KEY from the environment if you don't pass an apiKey in the config — the same convention as the SDK.

7.3 pi extension (@upstash/context7-pi)

The official Context7 extension for the pi.dev coding agent. It registers resolve-library-id and query-docs as native pi tools. Configure it through pi's extension mechanism and set CONTEXT7_API_KEY in your environment.

8. Common Tasks

Task: Add Context7 to a new project for Claude Code only

cd my-project
npx ctx7 setup --claude --project

Task: Switch from CLI + Skills mode to MCP mode

npx ctx7 remove --claude --cli
npx ctx7 setup --claude --mcp

Task: Use Context7 in CI without a browser login

Generate an API key in the dashboard, then pass it directly — no interactive login:

npx ctx7 setup --claude --mcp --api-key "$CONTEXT7_API_KEY" --yes

Task: Look up a specific version's docs

npx ctx7 library next.js "app router"
# pick the version-pinned ID from the results, then:
npx ctx7 docs "/vercel/next.js/v14.3.0" "middleware"

Task: Disable CLI telemetry

Set the environment variable before running any command:

export CTX7_TELEMETRY_DISABLED=1

9. Troubleshooting

Error: Invalid library ID: "<name>"

Cause: You passed a bare library name to ctx7 docs, which requires a Context7 ID. Solution: Resolve the name first with ctx7 library <name>, then use the returned /owner/repo ID. Prevention: Always run library before docs, or copy the "Quick command" line the library output prints for you.

Error: Invalid API key. Please check your API key. API keys should start with 'ctx7sk' prefix.

Cause: The API key you supplied is malformed, revoked, or not a Context7 key. Solution: Generate a fresh key at context7.com/dashboard and pass it via --api-key or the CONTEXT7_API_KEY environment variable. Prevention: Confirm the key begins with ctx7sk.

Error: Rate limited or quota exceeded.

Cause: You've exceeded the request limit. Anonymous (no API key) requests have the lowest limits. Solution: Create a free API key for higher limits, or upgrade your plan at context7.com/plans if you already have one. Prevention: Authenticate the CLI (ctx7 login) or configure an API key so requests aren't anonymous.

Login fails on a remote server or over SSH

Cause: ctx7 login (and ctx7 setup) opens an OAuth flow that redirects to a localhost callback on the machine running the command. On a headless VDS/SSH host, your local browser can't reach that callback. (Reported in issues #2242 and #2693.) Solution: Run ctx7 login --no-browser to print the authorization URL, then use SSH local port-forwarding (e.g. ssh -L 52417:localhost:52417 user@host) so your local browser can complete the callback. Alternatively, generate an API key in the dashboard and skip login entirely with setup --api-key. Prevention: On servers, prefer API-key auth over the interactive OAuth flow.

Error: Skill file path "SKILL.md" resolves outside the target directory

Cause: A safety guard rejected a skill whose file path tried to escape the install directory (path traversal). This surfaced on Windows for some skills (issue #2361). Solution: Update to the latest ctx7 (npx ctx7 upgrade); path handling has been hardened. Reinstall the skill after upgrading. Prevention: Keep the CLI current.

setup --universal seems ignored when combined with --cli

Cause: A flag-handling issue where --universal was silently dropped under --cli (issue #2695). Solution: Upgrade the CLI. If you still hit it, run setup without --universal and let the interactive target picker place the skill, which always offers the Universal location.

MCP connection times out / context deadline exceeded

Cause: Long-running tool calls or a client that caps its connection wait too aggressively (issue #1508). The hosted server does not use SSE/GET streams — a GET /mcp returns 405 by design. Solution: Ensure your MCP client uses POST for tool calls (the StreamableHTTP transport). Retry the request; transient backend latency usually clears. Prevention: Use an up-to-date MCP client and the official hosted endpoint.

Permission denied writing a skill

Cause: The target skills directory isn't writable by your user (EACCES/EPERM). Solution: The CLI prints the exact fix, e.g. sudo chown -R $(whoami) "<parent-dir>". Run it, then retry. Prevention: Install skills into a project directory you own, or use --global only on machines where your home directory is writable.

10. FAQ

Q: Do I need an API key? No — Context7 works anonymously, but with lower rate limits. A free key from the dashboard raises your limits, and ctx7 setup creates one for you during login.

Q: What's the difference between MCP mode and CLI + Skills mode? In MCP mode, your agent calls Context7's resolve-library-id and query-docs tools natively over the Model Context Protocol. In CLI + Skills mode, no MCP server runs — instead a skill teaches your agent to fetch docs by running ctx7 commands. Choose MCP if your agent supports it; choose CLI + Skills for agents that don't, or when you'd rather not run an MCP server.

Q: Where does the CLI store my login? In ~/.context7/credentials.json, written with owner-only permissions. Run ctx7 logout to delete it.

Q: How do I find a library's Context7 ID? Run ctx7 library <name> (e.g. ctx7 library mongodb), or in your agent let resolve-library-id do it. IDs look like /mongodb/docs or /vercel/next.js.

Q: Can I pin documentation to a specific version? Yes. Use a versioned ID like /vercel/next.js/v15.1.8, or just mention the version in your prompt and Context7 matches it.

Q: Which agents are supported? ctx7 setup directly supports Claude Code, Cursor, OpenCode, Codex, Gemini CLI, and Antigravity. Any MCP-compatible client can use the hosted server manually via https://mcp.context7.com/mcp.

Q: How do I use Context7 from my own code? Use the @upstash/context7-sdk for a typed client, @upstash/context7-tools-ai-sdk for Vercel AI SDK tools and an agent, or @upstash/context7-pi for the pi coding agent. See Section 7.

Q: Is my code sent to Context7? The tools send your query (your question) and the library name to the Context7 API to rank and fetch docs. The tool descriptions explicitly warn not to put secrets, credentials, or proprietary code into the query. Documentation is returned to you; your codebase is not uploaded.

Q: How do I turn off telemetry? Set CTX7_TELEMETRY_DISABLED=1 in your environment. The CLI sends anonymous command-usage events otherwise.

Q: How do I update the CLI? Run ctx7 upgrade. It detects your install method and runs the right command. If you use npx, you're always on the latest by default.

Q: The ctx7 skills install command warns it's deprecated — what should I use? The standalone Skill Hub commands (install, search, info) are being retired. For setting up Context7, use ctx7 setup. Skill generation (ctx7 skills generate) remains supported.

11. Reference

CLI command summary

Global CLI options

Environment variables (CLI)

Library IDs at a glance

• Format: /owner/repo (e.g. /facebook/react, /mongodb/docs)
• Version-pinned: /owner/repo/version (e.g. /vercel/next.js/v15.1.8)
• Resolve a name to an ID with ctx7 library <name> or the resolve-library-id tool.

Where to go next

• CLI Reference — full CLI documentation
• MCP Clients — manual MCP install for 30+ clients
• Adding Libraries — submit your library to Context7
• Troubleshooting — common issues and solutions
• For architecture, self-hosting, configuration, and security details, see the Context7 Admin Guide.