How to set up Context7 MCP in Claude Code, Cursor, VS Code and Codex

Quick answer

• Fastest: run npx ctx7 setup (needs Node.js 22.13 or newer). It signs you in, creates an API key and configures your agent.
• By hand: add the remote server https://mcp.context7.com/mcp to your client. Send an API key as Authorization: Bearer YOUR_API_KEY for higher rate limits. It also works without one, with lower limits.
• Locally: run npx -y @upstash/context7-mcp as a stdio server. It still fetches docs from Context7's service, so it isn't offline.
• Then: add "use context7" to a prompt, or a rule telling the agent to use it for library questions.

What Context7 MCP is

Context7 is a documentation service from Upstash. Its MCP server gives your agent two tools:

• resolve-library-id turns a library name such as "next.js" into a Context7 ID such as /vercel/next.js.
• query-docs fetches documentation and code examples for that ID, matched to your question.

IDs can include a version, such as /vercel/next.js/v16.2.9. Context7 can also run without MCP, as a CLI plus an agent skill. ctx7 setup offers both modes. This guide covers MCP mode, because that is what most clients and the searches for "context7 mcp" are about.

Get an API key (optional)

The hosted server answers without a key, at low rate limits. For regular use, create a free key at context7.com/dashboard. Keys start with ctx7sk. Keep the key out of files you commit: the examples below use a placeholder or read it from an environment variable.

If your client supports OAuth for remote servers, you can sign in instead of using a key. Point it at https://mcp.context7.com/mcp/oauth rather than /mcp. OAuth works only with the remote server.

Option 1: npx ctx7 setup

The ctx7 CLI signs you in through your browser, generates an API key and writes the config for the agent you choose:

npx ctx7 setup            # asks which agent and which mode
npx ctx7 setup --claude   # Claude Code
npx ctx7 setup --cursor   # Cursor
npx ctx7 setup --opencode # OpenCode

• --mcp or --cli picks the mode without asking. In CLI + Skills mode, --codex and --antigravity are also available.
• --project writes the config for the current project instead of globally.
• --api-key YOUR_API_KEY uses an existing key. --oauth uses OAuth instead of a key (MCP mode only).
• --yes skips the prompts.

To undo it, run npx ctx7 remove. If you see a Node.js version error, update Node or use Option 2, which doesn't need ctx7.

Option 2: add the remote server by hand

Claude Code

claude mcp add --scope user --header "Authorization: Bearer YOUR_API_KEY" \
  --transport http context7 https://mcp.context7.com/mcp

Keep --header before --transport or put it after the URL. --header accepts several values, so if it comes right before the server name, Claude Code reads the name as a header and stops with "missing required argument 'name'". Leave out the header to use the server without a key. Run claude mcp list or /mcp to check it shows as connected. More on Claude Code: the best MCP servers for Claude Code.

Cursor

Add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). The ${env:...} syntax reads the key from an environment variable, so the file holds no secret:

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

Check it under Customize → MCPs. More: how to add an MCP server to Cursor.

VS Code (GitHub Copilot)

Context7 publishes a VS Code extension (Upstash.context7-mcp) that registers the server for you. Set your key in the context7.apiKey setting. To configure it by hand instead, add it to .vscode/mcp.json. VS Code uses servers rather than mcpServers:

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

More, including the user-level config and input prompts for keys: how to add an MCP server to VS Code.

Codex

Codex can read the key from an environment variable and send it as a Bearer token:

codex mcp add context7 --url https://mcp.context7.com/mcp --bearer-token-env-var CONTEXT7_API_KEY

That writes this to ~/.codex/config.toml, which you can also edit directly:

[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"
bearer_token_env_var = "CONTEXT7_API_KEY"

codex mcp list should show the server with "Bearer token" under Auth. Context7 also ships a Codex plugin that signs in with OAuth: run codex plugin marketplace add upstash/context7, then codex plugin add context7@context7-marketplace, and start a new thread. More: how to add an MCP server to Codex.

Claude Desktop and other clients

In Claude Desktop, add https://mcp.context7.com/mcp as a custom connector. The steps are in how to add an MCP server to Claude Desktop. Context7's docs list configs for many more clients, including OpenCode, Windsurf and Antigravity. The URL is the same everywhere; only the file and key names change.

Option 3: run Context7 MCP locally

You can run the server on your own machine as a stdio process with npx. It needs Node.js 20 or newer. In Claude Code:

claude mcp add --scope user context7 -- npx -y @upstash/context7-mcp --api-key YOUR_API_KEY

In a JSON config (Cursor, Claude Desktop and others), it looks like this. The CONTEXT7_API_KEY environment variable works in place of --api-key. If you set both, --api-key wins:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": { "CONTEXT7_API_KEY": "YOUR_API_KEY" }
    }
  }
}

In Codex, local servers start more slowly, so give them extra time:

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
env_vars = ["CONTEXT7_API_KEY"]
startup_timeout_sec = 20

The package can also serve over HTTP with --transport http (default port 3000, change it with --port). In that mode it expects Authorization: Bearer YOUR_API_KEY on every request by default. The local server still calls Context7's API for the docs. Running it locally changes where the MCP process runs, not where the documentation comes from. Use the remote server unless your client only supports stdio or you want to pin the package version.

On Windows, if the client can't start npx, see fixing spawn npx ENOENT. The usual fix is "command": "cmd" with "args": ["/c", "npx", "-y", "@upstash/context7-mcp"].

Use it in prompts

• Add use context7 to a prompt, for example: "Set up Next.js middleware that checks a JWT. use context7".
• If you know the library, name its ID to skip the lookup: "use library /supabase/supabase".
• Mention the version you use, such as "Next.js 16", so the agent fetches docs for that version.

To skip typing it every time, add a rule. Context7 suggests: "Always use Context7 when I need library/API documentation, code generation, setup or configuration steps without me having to explicitly ask." Put it in CLAUDE.md, AGENTS.md or a Cursor rule. See Cursor rules vs AGENTS.md for where each file goes.

Check that it works

Context7 has a health endpoint:

curl https://mcp.context7.com/ping
# {"status":"ok","message":"pong"}

To see the tools without any client, list them with the MCP Inspector CLI. The output should include resolve-library-id and query-docs:

npx -y @modelcontextprotocol/inspector --cli https://mcp.context7.com/mcp --transport http --method tools/list

If the Inspector lists the tools but your client doesn't, the problem is in the client config, not Context7.

Context7 API without MCP

Context7 also has a REST API at https://context7.com/api for searching libraries and fetching docs from your own scripts. It takes the same ctx7sk key as a Bearer token. If you only want docs in the terminal, the ctx7 CLI does the same lookups without MCP, for example npx ctx7 library react "How to clean up useEffect". Context7's API guide lists the endpoints and rate limits.

Troubleshooting

• Rate limit errors: add an API key. Anonymous use has low limits.
• 401 Unauthorized: check that the key starts with ctx7sk and that the header is exactly Authorization: Bearer <key>. A missing "Bearer " is the usual mistake. A client can show the server as connected even with a wrong key (Claude Code did with a placeholder key when we checked), so test with a real prompt.
• "Library not found": use the ID from resolve-library-id, in the form /owner/repo, or ask with the library's common name.
• `ERR_MODULE_NOT_FOUND` with the local server: Context7's troubleshooting docs suggest running it with bunx instead of npx.
• Timeouts starting the local server: in Codex, raise startup_timeout_sec to 40. Behind a corporate proxy, set HTTPS_PROXY in the server's env. If it keeps closing, see MCP error -32000: connection closed.
• No tools after editing a config: restart Cursor or VS Code. In Claude Code, run claude mcp list; if it still fails, remove the server with claude mcp remove context7 and add it again.

FAQ

Is Context7 free?

You can use it without a key, and there is a free API key with higher limits. Context7 also sells paid plans with higher limits. Check context7.com for current limits, which change.

Do I need an API key?

No, but you'll hit rate limits sooner without one. OAuth through /mcp/oauth is an alternative in clients that support it.

Should I use the remote or local server?

Remote is simpler: there's nothing to install and no Node.js version to manage. Use local if your client only supports stdio. Both need an internet connection.

MCP or CLI + Skills?

MCP mode works in any MCP client. CLI + Skills mode adds no MCP tools to your context and suits agents that support skills. ctx7 setup offers both.