Configuration

Context7 MCP Server supports various configuration options for authentication, transport, and behavior customization.

Authentication

Context7 supports two authentication methods: API Key and OAuth 2.0.

API Key Authentication

API key authentication is the simplest method and works with both local and remote connections.

Getting an API Key

Visit context7.com/dashboard
Sign up or log in
Generate a new API key
API keys start with the prefix ctx7sk

Free API keys provide higher rate limits than anonymous access. Paid plans offer professional and enterprise limits.

Passing API Keys

There are multiple ways to provide your API key:

Command Line Flag
Environment Variable
HTTP Header

Pass the API key directly via the --api-key flag:

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

Pros: Simple and explicit
Cons: API key visible in config file

Set the CONTEXT7_API_KEY environment variable:

export CONTEXT7_API_KEY="YOUR_API_KEY"

Then configure without the flag:

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

Or pass via env object:

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

Pros: API key not in config file
Cons: Need to set environment variable

For remote connections, pass the API key via HTTP header:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Alternative header names also supported:

Context7-API-Key
X-API-Key
Authorization: Bearer YOUR_API_KEY

Pros: Standard HTTP pattern
Cons: Remote only

OAuth 2.0 Authentication

OAuth provides secure, token-based authentication for remote connections.

Requirements

Remote HTTP connection only (not available for local stdio)
MCP client must support MCP OAuth specification

Configuration

Change the endpoint from /mcp to /mcp/oauth:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp/oauth"
    }
  }
}

The OAuth flow will be handled automatically by your MCP client.

OAuth Endpoints

Context7 implements OAuth 2.0 Protected Resource Metadata (RFC 9728): Protected Resource Metadata:

GET https://mcp.context7.com/.well-known/oauth-protected-resource

Authorization Server Metadata:

GET https://mcp.context7.com/.well-known/oauth-authorization-server

Supported Scopes:

profile - Access to user profile information
email - Access to user email address

Bearer Methods:

header - Bearer token in Authorization header

OAuth vs API Key

API Key

Best for:

Local connections
Simple setup
Single-user environments
Testing and development

Pros:

Works with both local and remote
Simple configuration
Direct access

Cons:

Manual key management
No automatic refresh

OAuth 2.0

Best for:

Remote connections
Team environments
Enterprise deployments
Enhanced security

Pros:

Automatic token refresh
Revocable access
Scoped permissions

Cons:

Remote only
Requires OAuth support

Transport Configuration

Context7 MCP Server supports two transport modes.

stdio (Local)

Standard input/output transport for local connections. Configuration:

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

Startup:

npx -y @upstash/context7-mcp --api-key YOUR_API_KEY

Characteristics:

Runs on your local machine
Communicates via stdin/stdout
Default transport mode
Maximum privacy

HTTP (Remote)

HTTP transport for remote server connections. Configuration:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Startup:

npx -y @upstash/context7-mcp --transport http --port 3000

Characteristics:

Can run locally or remotely
RESTful HTTP API
Supports OAuth
Scalable for teams

Available Endpoints:

/mcp - Anonymous/API key access
/mcp/oauth - OAuth 2.0 protected access
/ping - Health check
/.well-known/oauth-protected-resource - OAuth metadata
/.well-known/oauth-authorization-server - OAuth server metadata

Environment Variables

Context7 MCP Server reads the following environment variables:

CONTEXT7_API_KEY

string

Your Context7 API key. Get one at context7.com/dashboardFormat: Starts with ctx7sk
Example: ctx7sk_abc123xyz789

CONTEXT7_API_URL

string

Override the Context7 API base URL.Default: https://context7.com/api
Example: https://api.context7.com

RESOURCE_URL

string

Override the MCP resource URL for OAuth.Default: https://mcp.context7.com
Example: https://custom-mcp.example.com

AUTH_SERVER_URL

string

Override the OAuth authorization server URL.Default: https://context7.com
Example: https://auth.example.com

HTTPS_PROXY

string

HTTP/HTTPS proxy URL for outgoing requests.Aliases: https_proxy, HTTP_PROXY, http_proxy
Example: http://proxy.example.com:8080

Command Line Options

When running Context7 MCP Server locally:

--transport

string

default:"stdio"

Transport type to use.Options: stdio, http
Example: --transport http

--port

number

default:"3000"

Port for HTTP transport (only valid with --transport http).Example: --port 8080

--api-key

string

API key for authentication (only valid with --transport stdio).Example: --api-key ctx7sk_abc123

Valid Option Combinations

npx -y @upstash/context7-mcp --transport stdio --api-key YOUR_API_KEY

Invalid combinations:

--api-key with --transport http (use headers instead)
--port with --transport stdio (stdio doesn’t use ports)

Proxy Configuration

Context7 automatically detects and uses proxy settings from environment variables:

# Set proxy
export HTTPS_PROXY="http://proxy.example.com:8080"

# Run Context7
npx -y @upstash/context7-mcp --api-key YOUR_API_KEY

Supported proxy environment variables (in order of precedence):

HTTPS_PROXY
https_proxy
HTTP_PROXY
http_proxy

Rate Limits

Context7 applies rate limits based on your authentication:

Anonymous (No API Key)

Limited requests per hour
Suitable for testing only
May encounter 429 errors during heavy use

Free API Key

Higher rate limits
Suitable for regular development
Generous quota for individual developers

Paid Plans

Professional rate limits
Enterprise-grade quotas
Priority support

Visit context7.com/plans for detailed limits.

Handling Rate Limits

When you hit rate limits, you’ll receive:

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

Solutions:

Add a free API key if using anonymous access
Wait for rate limit window to reset
Upgrade to a paid plan

Security Best Practices

Never commit API keys to version control. Use environment variables or secure secret management.

Recommended Practices

Use environment variables for API keys
Add to .gitignore:
```
.cursor/mcp.json
.env
**/config.json
```
Rotate keys regularly from the dashboard
Use OAuth for team environments
Never share API keys in prompts or queries

What Not to Send

Do not include in your queries:

API keys, passwords, or credentials
Personal identifiable information (PII)
Proprietary or confidential code
Customer data
Security tokens

Queries are sent to Context7 API for processing and intelligent reranking.

Troubleshooting

Invalid API key error

Invalid API key. Please check your API key. 
API keys should start with 'ctx7sk' prefix.

Solutions:

Verify key starts with ctx7sk
Check for extra spaces or quotes
Regenerate key from dashboard
Ensure key is active (not revoked)

Rate limit errors

Rate limited or quota exceeded.

Solutions:

Add API key if using anonymous access
Wait for rate limit window to reset
Upgrade plan at context7.com/plans
Reduce request frequency

Connection errors

For HTTP transport:

Check internet connectivity
Verify URL is correct
Test endpoint: curl https://mcp.context7.com/ping
Check firewall settings
Verify proxy configuration

For stdio transport:

Ensure Node.js is installed
Clear npx cache: npx clear-npx-cache
Test manually: npx -y @upstash/context7-mcp

OAuth errors

Ensure using /mcp/oauth endpoint
Verify client supports MCP OAuth spec
Check OAuth is only for remote (HTTP) transport
Try API key authentication instead

Next Steps

Tools Reference

Explore available MCP tools

All Clients

See all supported MCP clients

Get Started

MCP Server

SDK

AI SDK Integration

Guides

Configuration

Configuration

Authentication

API Key Authentication

Getting an API Key

Passing API Keys

OAuth 2.0 Authentication

Requirements

Configuration

OAuth Endpoints

OAuth vs API Key

API Key

OAuth 2.0

Transport Configuration

stdio (Local)

HTTP (Remote)

Environment Variables

Command Line Options

Valid Option Combinations

Proxy Configuration

Rate Limits

Anonymous (No API Key)

Free API Key

Paid Plans

Handling Rate Limits

Security Best Practices

Recommended Practices

What Not to Send

Troubleshooting

Next Steps

Tools Reference

All Clients

Build docs developers (and LLMs) love

Get Started

MCP Server

SDK

AI SDK Integration

Guides

​Configuration

​Authentication

​API Key Authentication

​Getting an API Key

​Passing API Keys

​OAuth 2.0 Authentication

​Requirements

​Configuration

​OAuth Endpoints

​OAuth vs API Key

API Key

OAuth 2.0

​Transport Configuration

​stdio (Local)

​HTTP (Remote)

​Environment Variables

​Command Line Options

​Valid Option Combinations

​Proxy Configuration

​Rate Limits

​Anonymous (No API Key)

​Free API Key

​Paid Plans

​Handling Rate Limits

​Security Best Practices

​Recommended Practices

​What Not to Send

​Troubleshooting

​Next Steps

Tools Reference

All Clients

Build docs developers (and LLMs) love

Configuration

Authentication

API Key Authentication

Getting an API Key

Passing API Keys

OAuth 2.0 Authentication

Requirements

Configuration

OAuth Endpoints

OAuth vs API Key

Transport Configuration

stdio (Local)

HTTP (Remote)

Environment Variables

Command Line Options

Valid Option Combinations

Proxy Configuration

Rate Limits

Anonymous (No API Key)

Free API Key

Paid Plans

Handling Rate Limits

Security Best Practices

Recommended Practices

What Not to Send

Troubleshooting

Next Steps