Context7 MCP Server: Complete Setup Guide (2026)

TL;DR + what you actually need

Three constants you’ll keep typing if you use Context7 regularly:

• Remote endpoint: https://mcp.context7.com/mcp — works with any modern MCP client that speaks Streamable HTTP.
• NPM package: @upstash/context7-mcp — the stdio version, if you prefer running it locally via npx.
• API key: optional. Free tier works without one; generate a key at context7.com/dashboard if you want higher rate limits.

The fast install paths, in case you came here for the one-liner:

• Claude Code: claude mcp add --transport http context7 https://mcp.context7.com/mcp
• Cursor: click the install button at context7.com or paste the JSON snippet below into ~/.cursor/mcp.json
• OpenCode: add a type: "remote" entry pointing at the URL above — full snippet in the OpenCode section
• Codex CLI: a TOML block in ~/.codex/config.toml — snippet below

The rest of this guide explains why those snippets look the way they do, walks through Context7’s two tool methods, shows seven real recipes, and ends with troubleshooting for the things that bite us most often.

What Context7 actually does

Most agent failures we’ve seen come from the same shape of problem: the model knows React 18, but you’re writing React 19. The model knows Pydantic v1, but your project pinned v2. Documentation that’s a few months stale renders the agent confidently wrong. The Context7 MCP server fixes that class of bug by injecting the right version of the docs into the agent’s context at the moment it needs them.

Context7 is maintained by Upstash and indexes version-specific code documentation from the original source — usually a library’s GitHub repo and official docs site. The MCP server exposes that index via two tools (more on that below) so an agent can resolve a question like “how do I configure middleware in Next.js 15 App Router” and get back actual Next.js 15 docs, not a memorised 2024 snapshot of Next.js 13.

The headline differentiator is the resolver step. Other docs-RAG MCP servers do bag-of-snippets retrieval; Context7 forces the agent through a library-ID resolution step first, so the answer is grounded in one specific library and one specific version. That extra hop sounds bureaucratic until you watch a model confidently combine Next.js 13 and Next.js 15 syntax in the same file.

The project lives at github.com/upstash/context7 (MIT-licensed, ~15K stars at the time of writing) and the hosted MCP endpoint runs at mcp.context7.com/mcp. The product page is at context7.com — that’s where you grab an optional API key for higher rate limits, browse the indexed library catalogue, and find install buttons for the clients Upstash supports natively.

How the 2-tool flow works

Context7 exposes two MCP tools. The flow is always: resolve, then query. Skipping the resolve step is the #1 mistake we see in agent traces.

A typical agent prompt that triggers Context7 is anything ending in “use context7” — a convention Upstash promoted early. The model sees the phrase, calls resolve-library-id first to pick the right library, then calls query-docs with that ID and the topic-specific question. Modern clients (Claude Code, Cursor, OpenCode) handle the two-step flow automatically once Context7 is registered as a tool.

Worth knowing: Context7 caps tool calls at 3 per question by default — both tool descriptions explicitly say so. If your agent is hitting that ceiling you’re asking a question that spans multiple libraries; split it.

Install (every client)

Two install paths exist for every modern client. Either:

1. Remote — point your client at https://mcp.context7.com/mcp. Streamable HTTP transport, no local install, Upstash hosts it. Use this unless you have a specific reason not to.
2. stdio (local) — run npx -y @upstash/context7-mcp as a subprocess of your client. Use this if your network blocks the remote endpoint, you need offline mode, or you’re behind a strict corporate proxy.

For the standard clients — Cursor, VS Code, Claude Desktop, Claude Code, Gemini CLI, Codex CLI, Windsurf, ChatGPT, and the manual JSON fallback — the install panel below has the exact one-click button, copy command, or JSON snippet you need. Tap the row of your client, copy the snippet (or click the 1-Click button for Cursor / VS Code), and Context7 is live in that client within seconds. Codex CLI users in particular: the panel emits the [mcp_servers.context7] TOML block ready to paste into ~/.codex/config.toml. The panel pulls its configs directly from our catalog, so it stays in sync as Context7 ships new transport options.

One-line install · Context7

Open server page

Install

Cursor

One-click install

1-Click

VS Code

One-click install

1-Click

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

The Claude Code one-liner is worth keeping on hand because it’s the most copy-pasted command in the Context7 setup queries we see:

claude mcp add --transport http context7 https://mcp.context7.com/mcp

Add --scope project to write to .mcp.json at the repo root so it travels with the project. Add --header "Authorization: Bearer YOUR_KEY" if you have a Context7 API key for higher rate limits.

Add Context7 to OpenCode

To add Context7 to OpenCode (the open-source TUI agent by Anomalyco), you edit OpenCode’s config directly — it isn’t in the standard install panel above. This is the single most-searched Context7-plus-client combination on the open web, so here’s the explicit snippet. The config lives in OpenCode’s user config (commonly ~/.config/opencode/config.json; run opencode config print to confirm the path on your install). Remote shape:

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

Local stdio shape:

{
  "mcp": {
    "context7": {
      "type": "local",
      "command": ["npx", "-y", "@upstash/context7-mcp"]
    }
  }
}

Restart OpenCode (opencode in a new shell) and Context7 shows up in the tool list. If you’re still weighing OpenCode against Aider, Claude Code, Cline, or Goose, our CLI agent comparison covers the trade-offs.

Kiro

Kiro (AWS’s spec-first IDE) reads MCP servers from its IDE settings — similar JSON shape to Cursor. Open Settings → AI & MCP → MCP Servers and paste:

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

Kiro routes MCP tool calls through whichever model you’ve selected (Bedrock-hosted Claude variants are the default). As a younger IDE its MCP UI iterates — confirm the exact settings path against current Kiro docs if your version looks different.

Browse every client and its config path at mcp.directory/clients.

The two tool methods, walked through

1. resolve-library-id

The first call. Takes a free-text library or framework name, returns the Context7-compatible library ID with metadata. Typical agent input:

resolve-library-id({
  libraryName: "Next.js 15 App Router"
})

Returns something like:

{
  "selected": {
    "id": "/vercel/next.js/v15",
    "title": "Next.js (App Router, v15)",
    "snippets": 1842,
    "reputation": "High",
    "benchmarkScore": 96
  },
  "alternatives": [
    { "id": "/vercel/next.js/v14", "snippets": 1611 },
    { "id": "/vercel/next.js/v13", "snippets": 1455 }
  ]
}

Tool description explicitly tells the agent: call this before query-docs unless the user already supplied a library ID in the form /org/project or /org/project/version. Capped at 3 calls per question to prevent loops.

2. query-docs

The second call. Takes a resolved ID and (optionally) a topic-specific question, returns documentation snippets and example code. Typical input:

query-docs({
  context7CompatibleLibraryID: "/vercel/next.js/v15",
  topic: "configure middleware with edge runtime"
})

Returns markdown snippets pulled from the indexed Next.js 15 docs at that exact version — the answer you wanted two weeks of arguing-with-the-model ago.

Same 3-call-per-question ceiling applies. If you’re hitting it, your question spans multiple libraries; resolve and query each separately.

Recipes

Seven workflows where Context7 earns its keep. We assume Context7 is installed at user scope in your client of choice.

Recipe 1 — Up-to-date framework docs mid-coding

You’re building with Next.js 15 App Router. Mid-feature, you’re unsure if useFormState still exists in React 19 or if it was renamed. Ask the agent: “How do I wire a React 19 server action with form state? use context7” The agent calls resolve-library-id with “React 19”, picks the right ID, then calls query-docs with the server-action topic. You get the actual React 19 API, not 2024 muscle memory.

Recipe 2 — Library version migration

You’re migrating a project from Pydantic v1 to v2. Prompt: “Show me the v2 equivalent of these v1 validators. use context7 for Pydantic v2.” The library-ID resolver picks the v2 docs explicitly;query-docs returns the validator patterns that actually compile under v2. We’ve watched this single workflow save 1–2 hours per migration on a medium codebase.

Recipe 3 — Picking between similar libraries

Choosing between Zustand and Jotai for client state. Prompt: “use context7 to compare Zustand and Jotai selectors”. The agent calls resolve-library-id twice (once each), then query-docs twice with the selectors topic. You get a real side-by-side grounded in current docs, not vibes.

Recipe 4 — Onboarding to a new library

You hit a job that uses Effect (the TypeScript effects library) and you’ve never used it. One prompt: “Explain Effect’s core abstractions — Effect, Layer, Runtime. use context7.” Context7 returns the canonical intro from the Effect docs at the current version. Beats reading a 2024 tutorial that’s about a refactored API.

Recipe 5 — Debugging a deprecation warning

Your terminal prints DeprecationWarning: Passing FormData is deprecated.... Prompt: “What replaces the deprecated FormData pattern in this version of [library]? use context7.” The agent resolves the library version (from your lockfile or your prompt), queries docs for the replacement API, and writes the replacement diff.

Recipe 6 — Cross-checking ChatGPT/Claude/Gemini answers

When an LLM answer looks confident but suspicious — especially around recently-changed APIs — re-prompt with “use context7” appended. The model re-grounds against the current docs. We treat this as a tightening loop on any code suggestion involving framework APIs we don’t already know cold.

Recipe 7 — Skill / agent prompt that always uses Context7

For frameworks you use constantly, bake Context7 into a Claude Code skill or a custom CLI prompt:

---
name: nextjs-15-helper
description: |
  Helper for Next.js 15 App Router. Always resolves Next.js 15 docs
  via Context7 before answering code questions about Next.js, React
  Server Components, or routing.
---
For any Next.js 15 question, first call resolve-library-id with
"Next.js 15 App Router", then query-docs with the specific topic.
Cite the resolved library version in the response.

The skill auto-activates on Next.js questions, the Context7 calls happen without you typing “use context7”, and the model stays grounded. We use this pattern for the 3–4 frameworks our team writes in every day.

Pricing, API keys, rate limits

Context7 the MCP server is free. Upstash, the parent company, makes money on its core products (Redis, Kafka, vector); Context7 is a developer-relations play, not the revenue centre. Practically what that means:

• Free, no key required. You can use https://mcp.context7.com/mcp or npx @upstash/context7-mcp with no signup. Most users never need a key.
• Optional API key for higher rate limits. Generate one at context7.com/dashboard. Pass it as a Bearer token in the Authorization header.
• Rate limit signals. If the agent starts seeing 429s or unusually slow responses, you’re hitting the free-tier ceiling. Slap an API key on the connection (or back off your agent’s request rate).

Context7 does not currently sell paid tiers in the traditional “X dollars per month for Y queries” sense — the dashboard mostly exists to attach a key identity to your usage so the rate limits are applied to your account rather than your IP. Upstash may evolve this; check the dashboard for the current terms.

License

Context7’s MCP server is MIT-licensed. The full text lives at github.com/upstash/context7/blob/master/LICENSE. MIT is permissive — fork it, redistribute it, use it in proprietary work without asking. The hosted service at mcp.context7.com follows Upstash’s terms of service; the code you run locally via npx @upstash/context7-mcp inherits MIT.

Troubleshooting

When to switch to something else

Context7 is excellent for up-to-date, version-pinned library docs. It’s not the right tool for every retrieval job.

• You want to query an entire GitHub repo (including code + issues), not just the docs: use DeepWiki.
• You want offline / IDE-tight docs without an external service: Ref offers an editor-side alternative.
• You want a tool that bundles docs + web search + repo search in one MCP: Docfork takes that broader scope.

We compared all four in detail in our Context7 vs DeepWiki vs Ref vs Docfork deep dive — read that if you’re still picking. If your need is specifically the “ask any GitHub repo a question” pattern, we also wrote a separate DeepWiki complete guide (post in progress) that goes the same depth as this post.

FAQ

Sources

• Context7 repository & README: github.com/upstash/context7 (MIT, maintained by Upstash)
• Context7 product site: context7.com
• NPM package: @upstash/context7-mcp
• Remote endpoint: mcp.context7.com/mcp
• Dashboard (API key generation): context7.com/dashboard