Context7 Rate Limits and API Key Authentication: Complete Technical Guide

Context7 implements tiered rate limits that return standard HTTP 429 responses with RateLimit-* headers when quotas are exceeded, while API keys are transmitted as Bearer tokens via the Authorization header or the CONTEXT7_API_KEY environment variable to unlock higher quotas.

The Context7 MCP server by Upstash provides AI-powered documentation retrieval, but understanding its rate limiting behavior and authentication mechanisms is essential for building resilient integrations. This guide examines the specific implementation details found in the upstash/context7 repository, including header formats, error handling logic, and Bearer token generation.

Understanding Context7 Rate Limits

Rate Limit Headers and Response Format

Every request to the Context7 MCP API returns standard rate-limit headers as defined in docs/openapi.json. These headers provide real-time quota information:

• RateLimit-Limit: Total number of requests allowed in the current window
• RateLimit-Remaining: How many requests are left before the window expires
• RateLimit-Reset: Unix timestamp when the window resets
• Retry-After: Seconds to wait before retrying after receiving a 429 response

When a request exceeds the allowed quota, the server returns HTTP 429 with a RateLimitError response body, also defined in the OpenAPI specification at docs/openapi.json.

Unauthenticated vs. Authenticated Quotas

The rate limit tier depends entirely on authentication status, with distinct error messages generated in packages/mcp/src/lib/api.ts (lines 23-28).

Unauthenticated requests (no API key) receive a low per-minute and per-hour quota. When limits are exceeded, the server returns:

"Rate limited or quota exceeded. Create a free API key at https://context7.com/dashboard for higher limits."

Authenticated requests (valid Context7 API key) receive higher quotas based on the associated plan (free, Pro, or Unlimited). When authenticated users hit limits, the error message in packages/mcp/src/lib/api.ts (lines 25-27) directs them to:

"Rate limited or quota exceeded. Upgrade your plan at https://context7.com/plans for higher limits."

Additionally, the CLI package enforces weekly generation limits that vary by plan tier, as documented in packages/cli/README.md.

How Context7 API Key Authentication Works

Providing Your API Key

Clients can authenticate using two primary methods:

1. Environment variable: Set CONTEXT7_API_KEY to your key value (e.g., ctx7sk_...)
2. Command-line flag: Pass --api-key when running the MCP server locally

The main README.md emphasizes that providing an API key is recommended for "higher rate limits" (line 40), while packages/mcp/README.md provides installation snippets for various clients including Cursor, Claude, and Perplexity.

Bearer Token Implementation

The API key is transmitted as a standard Bearer token in the Authorization header. The header generation logic resides in packages/mcp/src/lib/encryption.ts (lines 55-60):

if (context.apiKey) {
  headers["Authorization"] = `Bearer ${context.apiKey}`;
}

The server validates this token and associates the request with the user's plan, applying the corresponding rate-limit values. This validation occurs server-side upon receiving the request, while the client-side code in packages/mcp/src/lib/encryption.ts handles the header preparation.

Implementation Examples

Checking Rate Limits Programmatically

When using the Context7 client library, inspect response headers to implement intelligent backoff logic:

import { generateHeaders } from "@upstash/context7-mcp/src/lib/encryption";

const clientContext = {
  apiKey: process.env.CONTEXT7_API_KEY,
  clientIp: "203.0.113.42",
  clientInfo: { ide: "cursor", version: "1.2.3" },
  transport: "http",
};

const headers = generateHeaders(clientContext);
const response = await fetch("https://mcp.context7.com/v2/libs/search", { headers });

if (response.status === 429) {
  const limit = response.headers.get("RateLimit-Limit");
  const remaining = response.headers.get("RateLimit-Remaining");
  const reset = response.headers.get("RateLimit-Reset");
  const retryAfter = response.headers.get("Retry-After");
  
  console.error(`Rate limit hit: ${remaining}/${limit} left, resets at ${new Date(Number(reset) * 1000)}`);
  console.error(`Retry after ${retryAfter} seconds`);
}

Configuring the MCP Server with API Keys

For Cursor IDE integration, add the API key to your MCP server configuration:

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

For CLI usage with environment variables:

# Store the key in a .env file

echo "CONTEXT7_API_KEY=ctx7sk_your_key_here" > .env

# Run the server locally with the key

npx -y @upstash/context7-mcp --api-key "$CONTEXT7_API_KEY"

Summary

• Context7 implements tiered rate limiting with standard HTTP 429 responses and RateLimit-* headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, Retry-After) defined in docs/openapi.json.
• Unauthenticated requests face strict per-minute/per-hour quotas and receive guidance to create a free API key at context7.com/dashboard when limits are exceeded, as implemented in packages/mcp/src/lib/api.ts.
• Authenticated requests use Bearer tokens (Authorization: Bearer <key>) generated in packages/mcp/src/lib/encryption.ts and receive higher quotas based on plan tier (free, Pro, Unlimited), with upgrade guidance at context7.com/plans.
• The CONTEXT7_API_KEY environment variable and --api-key CLI flag provide flexible authentication methods across Cursor, Claude, and other MCP clients.
• Client applications should implement backoff logic using the Retry-After header or exponential backoff when receiving HTTP 429 responses.

Frequently Asked Questions

What are the exact rate limit values for Context7?

The specific numeric quotas are not hardcoded in the public repository and are subject to change based on infrastructure capacity. However, the system communicates current limits through the RateLimit-Limit response header on every request. Unauthenticated users receive significantly lower per-minute and per-hour quotas compared to authenticated users, with paid plans (Pro and Unlimited) receiving the highest thresholds as noted in packages/cli/README.md.

How do I upgrade my Context7 rate limits?

To upgrade from unauthenticated limits, create a free API key at https://context7.com/dashboard. If you already have a free key but need higher quotas, upgrade to a paid plan at https://context7.com/plans. The system automatically associates your API key with the new plan tier, and the updated quotas apply immediately to subsequent requests authenticated with that key.

Can I use Context7 without an API key?

Yes, Context7 supports anonymous usage for testing and light development work. However, unauthenticated requests are subject to strict rate limits as implemented in packages/mcp/src/lib/api.ts. When you exceed the anonymous quota, the server returns HTTP 429 with a specific message directing you to create a free API key for higher limits.

Where is the API key validated in the Context7 source code?

API key validation occurs server-side when processing incoming requests. On the client side, the key is prepared as a Bearer token in packages/mcp/src/lib/encryption.ts (lines 55-60), where the code generates the Authorization: Bearer ${context.apiKey} header. The server then validates this token, looks up the associated user plan, and applies the appropriate rate limit tier from the quotas defined in the system configuration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}