---
title: "context7 setup: CLI-first (migrated from official plugin)"
type: concept
updated: 2026-08-13
---

# context7 setup: CLI-first (migrated from official plugin)

_2026-04-28 (plugin era) → 2026-08-12 (CLI migration, setup-context7 v2.0.0)._

## Current state (canonical, since 2026-08-12)

Single source = the **`ctx7` CLI** (npm), agent-neutral — any harness (pi / claude / hermes / codex)
runs it in bash. **No MCP registration, no plugin.**

- CLI: `ctx7` v0.5.8 installed globally (`npm i -g ctx7`).
- API key: `~/.config/projects-secrets/ctx7.env` → `CONTEXT7_API_KEY=<key>` (our secrets convention,
  cf. `interns.env` / `auth.toml`).
- Works anonymously for basic queries; the key raises rate limits but does not change output.
- Legacy removed: plugin `context7@claude-plugins-official` uninstalled (installed_plugins + cache +
  pluginUsage), manual `mcpServers.context7` entries cleaned from `~/.claude.json` /
  `~/.claude/settings.json` (top-level + project-scoped). Backups: `~/.claude.json.bak-<ts>`,
  `~/.claude/settings.json.bak-<ts>`.

Procedure: **`setup-context7`** skill ([`skills/setup-context7/SKILL.md`](../../skills/setup-context7/SKILL.md)) —
key discovery (search `ctx7.env` → env var → settings.json → .claude.json, reuse, never invent),
confirmation gates before any mutation, smoke via `ctx7 library` (functional; works anonymously).
Usage policy: **`using-context7`** skill — `ctx7 library <name>` → `ctx7 docs <libraryId> "<question>"`.
Git Bash gotcha: library IDs start with `/` and path-convert — use `//owner/repo` double-slash.

**Verification gotcha (commit `79baad1`):** `ctx7 whoami` answers "Not logged in" even with an env key —
it's OAuth identity (`ctx7 login`), not a key check. The functional smoke is `ctx7 library`, not `whoami`.

## History: plugin era (2026-04-28 → 2026-08-12, rollback reference only)

Before the CLI migration, context7 ran through the official MCP plugin
`context7@claude-plugins-official`. The plugin's `.mcp.json` (after install):
`~/.claude/plugins/cache/claude-plugins-official/context7/<version>/.mcp.json` (version slug `unknown`).

The key was injected as a CLI flag into `args`:
`["-y", "@upstash/context7-mcp", "--api-key", "ctx7sk-..."]` (Upstash-recommended form for stdio;
header / `env` block forms also supported). Three manual MCP registrations were deleted at the time
(settings.json top-level, .claude.json top-level, and a project-scoped one in
`projects["…/snolla-admin-ui"].mcpServers.context7`).

**Plugin-update gotcha (moot since uninstall, keep for rollback):** `/plugin update` / re-install
overwrote the plugin's `.mcp.json` from the marketplace cache, dropping the `--api-key` flag — needed
re-application after every update.

**Rollback to the plugin path** (if ever needed): restore the `.bak-*` files, reinstall the plugin
(`/plugin install context7@claude-plugins-official`), re-inject the key, restart Claude Code. Full
procedure is in the `setup-context7` skill's Rollback section.

## Why CLI-first

Context7 ships as both an HTTP MCP server and an npm CLI. The MCP path is harness-specific glue
(claude-plugins-official); pi doesn't see it (the claude-mcp-bridge only reads `~/.claude.json`, and
even then it's fragile). Per the sovereign-catalog principle *"что можно сделать CLI — делаем CLI и
оборачиваем в скил; MCP только там, где нужен структурированный/интерактивный протокол"* — the CLI
is the canonical path (idea 16, `claude-to-agents`).

## Why two skills

- **`using-context7`** (policy, every-time): when to call, how to phrase queries, budget.
- **`setup-context7`** (one-time, mutates user config): install, key reuse, legacy cleanup.

Mixing them would dilute the policy skill's description (worse triggering) and pull setup procedure
into every library question. Template for future "X CLI + how-to-use-X" pairs.