Context7 MCP rate limit trips up developers who hit 429 errors in the middle of a coding session. This article lays out the free plan allowance, the paid tiers, the exact setup for Claude Code and Cursor, fixes for throttling, and an honest look at safety.
You are halfway through a refactor. Your coding assistant asks Context7 for the current Next.js routing docs, and the reply is a flat 429. No documentation, no explanation, just a stalled session. That is the Context7 MCP rate limit at work, and it bites harder since the free plan moved to a monthly cap in early 2026. This article lays out the real numbers, the setup that avoids throttling, the habits that stretch a small quota, and a straight answer to the safety question. Every figure comes from Context7's own plans page and documentation unless a line says someone else reported it. Limits and prices change, so check the dashboard before you build a budget around any number you read here.
Context7 is an MCP server from Upstash that pulls current library documentation into your assistant's context window. Instead of guessing an API from stale training data, the model asks Context7 and receives fresh snippets for the framework version you actually use. That is why developers install it, and also why they run into limits: it sits in the middle of the coding loop, where one task can trigger a dozen lookups without you noticing.
MCP, the Model Context Protocol, is simply the plug that lets an assistant call outside tools. Your client (Claude Code, Cursor, VS Code and others) launches or connects to the server, lists its tools, and the model decides when to call them. You approve or deny each call, but you rarely count them.
The server exposes two tools. resolve-library-id turns a plain name such as "next.js" into a Context7 library ID like /vercel/next.js. query-docs takes that ID plus your question and returns the matching documentation. Your assistant chooses when to call each one, which means you rarely control the call count directly.
A typical lookup is two calls: resolve the ID, then query the docs. Ask about three libraries in one prompt and you are at six calls before the assistant writes a single line of code. Retries add more. This matters because the allowance is counted in API calls, not in conversations or questions. Plan around calls.
Here is how the plans stand on Context7's pricing page:
| Plan | Price | Included API calls | Notes |
|---|---|---|---|
| Free | $0 | 1,000 per month | Public repos, OAuth 2.0 |
| Pro | $10 per seat per month | 2,000 per seat | Private repos, team features, overage at $5 per 1,000 calls |
| Enterprise | Custom | Typically 2,000 per seat | SOC-2, SSO, self-hosted option |
💡 Pro accounts are not blocked when the allowance runs out. They keep working and pay for the overage, which is the main practical difference from the free plan.
A quick way to think about it: 1,000 calls is about 500 two-step lookups, or roughly 33 calls a day if you want the allowance to last the whole month. That pace is easy to beat in a single heavy afternoon of debugging, which is why the monthly cap surprises people who were used to a daily limit.
The free plan gives you 1,000 API calls per month. Cross that line and the service returns an HTTP 429, Too Many Requests. Reports from January 2026 say the free tier used to sit near 200 requests a day, was announced at 500 a month, and was then raised to 1,000. Treat the old figures as history and the plans page as the source of truth.
Anonymous use, with no token at all, is the tightest option. The docs describe it as limited requests per hour, suitable for testing, and prone to 429 errors during heavy use. Create a free account on the dashboard and generate a token even if you never plan to pay a cent.
Pro includes 2,000 calls per seat and charges $5 for each extra 1,000. Enterprise pricing is custom, with the same typical 2,000 calls per seat, plus SOC-2, SSO and a self-hosted option for teams that cannot send queries to a third party. For a solo developer the choice is simple: stay free for light use, and move to Pro once the monthly counter keeps running dry before the month does.
Most 429 complaints trace back to one mistake: running Context7 with no credential at all. Set a token once and you leave the anonymous bucket for good. You also get a usage counter on the dashboard, which turns a mystery error into a number you can read.
Node.js 18 or newer is required. From any terminal, run:
npx ctx7 setup
The command handles OAuth sign in, generates a credential and installs the skill files for your client. Add --cursor, --claude or --opencode when you want to target a single tool instead of everything it finds.
If you prefer to wire it yourself, point the client at the remote server https://mcp.context7.com/mcp and send your token as a bearer header:
claude mcp add --transport http context7 https://mcp.context7.com/mcp --header "Authorization: Bearer YOUR_TOKEN"
Restart the session, run /mcp, and confirm that context7 shows as connected before you trust it with real work.
Clients that read a JSON file need the same two ingredients, a URL and a header:
{
"mcpServers": {
"context7": {
"url": "https://mcp.context7.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_TOKEN"
}
}
}
}
Field names differ slightly between clients, so check the format your tool expects. Never paste a real token into a file you commit to Git.
Test the connection with a prompt that forces a lookup, such as "Use Context7 to show how middleware matchers work in the latest Next.js." A working setup returns documentation snippets tied to a library ID. A setup with a wrong header usually fails right away with an authentication or connection error, so you find out before a real session depends on it.
A 1,000 call budget lasts a long time once you stop wasting it. Three habits do most of the work.
When the prompt already contains the ID, for example use library /vercel/next.js, the assistant can usually skip resolve-library-id and go straight to query-docs. That halves the cost of many lookups. Keep a short list of the IDs for the libraries you touch every day and paste them into your project instructions.
Add a project rule such as: "Call Context7 only for APIs released or changed recently, or when a build error points to a signature mismatch." Without a rule, some assistants fire a lookup for Array.map, which burns calls on knowledge the model already has.
When a lookup returns something you will need again, paste the useful snippet into a notes file in the repo and point the assistant at it. A local file costs zero calls. If you ask the same five framework questions every day, that is 10 calls a day and 220 across 22 workdays. One saved note removes the whole bill.
Whatever habits you pick, glance at the dashboard counter once a week. If you are past 250 calls after seven days, you are on pace to run dry around day 28, and you still have time to change course.
Short answer: safe enough for public library documentation, as long as you treat what comes back as untrusted input. The details matter, so here they are.
Your query text and the library name travel to Context7's servers. The MCP server code is public on GitHub, but the API backend, parsing and crawling engines are private, so answers come from infrastructure you cannot inspect. Do not paste secrets, customer data or proprietary code into a documentation question. A good lookup reads "how does the App Router handle redirects", not a block copied out of your codebase.
Context7's own notice says its projects are community contributed, and the maintainers cannot guarantee the accuracy or the security of all library documentation. Documentation pulled from any third party can carry text that tries to steer your assistant, the standard prompt injection problem for MCP servers. That risk is my assessment of the general MCP pattern, not a reported Context7 incident.
Practical defenses:
The token is a credential, so handle it like one. Store it in an environment variable or your client's secret storage, keep it out of Git, and regenerate it from the dashboard if it ever leaks.
Private code deserves its own paragraph. The free plan is limited to public repositories. Pro adds private repository support, and Enterprise adds a self-hosted option, which is the route to ask about if nothing may leave your network. If your policy forbids sending text to third parties, read the data terms for the plan you want before you enable anything.
| Risk | How likely | What to do |
|---|---|---|
| Query text seen by a third party | Always, by design | Keep secrets out of questions |
| Poisoned documentation | Low, but not zero | Manual approval for risky tools |
| Leaked access token | Depends on your habits | Environment variables, rotate on exposure |
| Outdated or wrong snippet | Occasional | Check against the official docs |
Three different situations produce the same error code:
On the free plan the counter resets with the new month. On Pro there is nothing to wait for. While you are blocked, three fallbacks keep you moving: the CLI path (ctx7 library and ctx7 docs), which needs no MCP layer, the framework's official documentation, or pasting the relevant docs page straight into the chat. Assume the CLI draws on the same allowance until your dashboard proves otherwise.
One more rule: do not let the assistant retry in a loop. I could not confirm whether rejected calls count against the monthly total, so assume they might, and stop after the first 429 instead of letting the session hammer the endpoint.
The numbers below are illustrations built from the published allowances, not measurements from a real account. They assume 22 workdays a month.
| Habit | Calls per day | Calls per month | Fits the free plan? |
|---|---|---|---|
| 30 lookups, resolve and query | 60 | 1,320 | No, empty around day 17 |
| 30 lookups, ID named in the prompt | 30 | 660 | Yes |
| 60 lookups, resolve and query | 120 | 2,640 | No, Pro plus about $3 overage |
The middle row is the whole argument for naming library IDs: same work, half the calls, no invoice. The last row shows what Pro does well. A heavy user pays $10 plus roughly $3 for 640 extra calls, so about $13 for a month that would have stalled on the free plan around day 9.
Teams multiply the math. Each Pro seat brings 2,000 calls, so five developers bring a pool of 10,000 before overage starts. If one person burns far more than the others, the pooled number can hide a problem, so look at per-person usage before you decide the plan is too small.
Once your assistant stops stalling on documentation, you ship faster, and shipping means launch pages, blog headers and social images. Picasso IA puts text and image generators under one roof, so the same afternoon that fixes your rate limit can also produce the visuals for the release.
For writing and reviewing code, try Claude Sonnet 5 or GPT 5.6 Sol, and give Kimi K2.6 a turn when you are building agent workflows. For images, P Image returns photorealistic drafts in about a second, Seedream 4.5 produces 4K output from text, and Flux 2 Pro accepts text or a reference photo.
The images in this article follow one simple prompt shape that works on any of them:
💡 Subject and action, then environment, then light direction, then lens and angle, then texture details. Example: "A developer at an oak desk in a brick loft, rain on the window behind, soft overcast light from the right, 85mm f/1.8 shallow depth of field, wool sweater texture, Kodak Portra 400 grain."
Open a model, paste a prompt like that for your next release banner, and generate three variations before you change a single word. Pick the best frame, compare it with the others, and keep the prompt that worked. Your first batch will take minutes, and the second will be better because you now know which details the model listens to. Try it on Picasso IA today and see what your next project looks like.
