Context7 in Claude Code: setup, keeping the API key out of your repo, and fixing 401s

Context7 gives Claude Code current, version-specific library docs through two tools, resolve-library-id and query-docs. The hosted server at https://mcp.context7.com/mcp needs no local Node.js; an API key is optional, but Upstash recommends a free one for higher rate limits. Your library names and queries are sent to Context7's hosted service, whose backend is private.

The steps below summarize the official docs (the Context7 README, Context7's Claude Code page and troubleshooting page, and the Claude Code docs on MCP and permissions), checked on 2026-10-27. They are based on the official docs, not hands-on tested; if something differs on your version, the linked docs win. The original version of this guide lives at AgentTask Atlas: How to connect the Context7 MCP server to Claude Code.

1. Check what you need

Nothing for the hosted server except outbound HTTPS. For an API key, create one in the Context7 dashboard (context7.com/dashboard); keys start with ctx7sk. The local npx server needs Node.js 20 or newer, and the ctx7 setup CLI needs Node.js 22.13 or newer.

2. Fastest: let ctx7 set it up

npx ctx7 setup --claude

It signs you in with an OAuth device flow (a link and short code you can open on any device, so it also works over SSH), generates an API key and lets you choose CLI + skill mode or MCP mode. Undo it later with npx ctx7 remove.

3. Or install the Context7 plugin

Run these inside Claude Code, restart it, then open /mcp, select Context7 and finish the browser sign-in:

/plugin marketplace add upstash/context7
/plugin install context7@context7-marketplace

No API key is needed, and the plugin does not read CONTEXT7_API_KEY, so use the next step on headless, SSH or CI hosts.

4. Manual: hosted server with the key from an env var

export CONTEXT7_API_KEY="YOUR_API_KEY"   # better: load it from your secret manager or shell profile
claude mcp add --scope user --header "Authorization: Bearer $CONTEXT7_API_KEY" --transport http context7 https://mcp.context7.com/mcp

--scope user makes it available in every project and stores it in ~/.claude.json, outside your repository. To skip the key and sign in with OAuth instead, use https://mcp.context7.com/mcp/oauth without the header and authenticate from /mcp.

5. Share it with the team without committing the key

Claude Code expands ${VAR} in the url and headers of a project's .mcp.json, so each teammate sets CONTEXT7_API_KEY in their own environment and the file stays secret-free:

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": { "Authorization": "Bearer ${CONTEXT7_API_KEY}" }
    }
  }
}

Claude Code asks each person to approve project-scoped servers the first time.

6. Or run it locally over stdio

claude mcp add --env CONTEXT7_API_KEY="$CONTEXT7_API_KEY" --transport stdio context7 -- npx -y @upstash/context7-mcp

Pass the key with --env instead of --api-key on the command line. Keep --transport stdio between --env and the server name: if the name comes right after --env, the CLI reads it as another KEY=value pair.

7. Check the connection

claude mcp list
claude mcp get context7
# in a session:
use context7 with /vercel/next.js for app router setup

claude mcp list should show context7 as connected. Adding the library ID (/owner/repo) skips the lookup step.

Troubleshooting (from the official docs)

• Rate-limit errors: add a free API key as an Authorization: Bearer header (remote) or CONTEXT7_API_KEY / --api-key (local).
• 401, and claude mcp list shows Failed to connect: check the key starts with ctx7sk and the header reads exactly Authorization: Bearer <key>. Claude Code reports a rejected header as a failed connection rather than offering OAuth.
• Warning about a missing variable: CONTEXT7_API_KEY isn't set in the shell that launched Claude Code. Export it first, or use a ${VAR:-default} fallback.
• ERR_MODULE_NOT_FOUND / Cannot find module 'uriTemplate.js' locally: use Node.js 20+ and @upstash/context7-mcp@latest, try bunx or deno, or use the hosted URL.
• 404 for a library: IDs look like /owner/repo or /owner/repo/version; let resolve-library-id find it first.
• Corporate proxy: set https_proxy / HTTPS_PROXY (in the server's env for stdio), then check curl https://mcp.context7.com/ping returns pong.
• "already exists in local config": run claude mcp remove context7 first, or add it under a different scope.

Notes

• Context7's 2 tool definitions measured about 1,060 tokens (o200k) on @upstash/context7-mcp 4.4.4, one of the lightest servers on our MCP tool budget table.
• Every query text leaves your machine for Context7's service, so don't paste secrets or proprietary code into one.
• An allow rule for mcp__context7__* in .claude/settings.json stops the per-call prompt; leave it out to keep confirming each lookup.
• Library docs on Context7 are community-contributed; Upstash says it can't guarantee their accuracy or security.