# Context7 Rate Limits and API Key Authentication: Complete Technical Guide

> Understand Context7 rate limits and API key authentication. Learn how to manage quotas with HTTP 429 responses and Bearer tokens for higher limits.

- Repository: [Upstash/context7](https://github.com/upstash/context7)
- Tags: deep-dive
- Published: 2026-02-16

---

**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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/README.md) emphasizes that providing an API key is recommended for "higher rate limits" (line 40), while [`packages/mcp/README.md`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/packages/mcp/src/lib/encryption.ts) (lines 55-60):

```typescript
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`](https://github.com/upstash/context7/blob/main/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:

```typescript
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:

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

```

For CLI usage with environment variables:

```bash

# 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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/packages/mcp/src/lib/api.ts).
- **Authenticated requests** use **Bearer tokens** (`Authorization: Bearer <key>`) generated in [`packages/mcp/src/lib/encryption.ts`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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.