Context7 OAuth 2.0 Flows: Authorization Code with PKCE Configuration Guide

Context7 supports only the OAuth 2.0 Authorization Code flow with PKCE, which you configure by switching your MCP endpoint to /mcp/oauth and running ctx7 login to authenticate through your browser.

Context7 is an open-source MCP (Model Context Protocol) server developed by Upstash that enables AI assistants to access up-to-date library documentation. When self-hosting or connecting to protected instances, understanding the supported OAuth 2.0 flows is essential for secure authentication.

Supported OAuth 2.0 Flows in Context7

Context7 implements a single, secure OAuth 2.0 flow designed for public clients.

Authorization Code Flow with PKCE

The Authorization Code flow with PKCE (Proof Key for Code Exchange) is the only OAuth 2.0 flow supported by Context7. This flow is implemented in the CLI to prevent authorization code interception attacks when authenticating native applications.

According to the source code in packages/cli/src/utils/auth.ts, the flow follows these steps:

1. PKCE Generation (lines 24-28): The CLI generates a code_verifier and code_challenge using SHA-256 hashing.
2. Authorization Request: The client builds an authorization URL pointing to /api/oauth/authorize with the challenge and a local redirect URI.
3. Local Callback Server (lines 82-84): The CLI starts a temporary HTTP server on http://localhost:52417/callback to receive the authorization code.
4. Token Exchange (lines 236-250): The CLI exchanges the authorization code for tokens via /api/oauth/token, sending the code verifier for validation.
5. Token Storage: The resulting access_token and optional refresh_token are stored in ~/.context7/credentials.json.

The server signals OAuth protection through the OAuth-Protected Resource Metadata endpoint at /.well-known/oauth-protected-resource and includes a WWW-Authenticate header on MCP requests, as implemented in packages/mcp/src/index.ts (lines 30-34).

Configuring OAuth 2.0 for Context7

To enable OAuth 2.0 authentication, you must update your client configuration and authenticate via the CLI.

Update the MCP Endpoint Configuration

Change your MCP server URL from the unprotected /mcp path to the OAuth-protected /mcp/oauth endpoint. This requirement is documented in docs/howto/oauth.mdx (lines 23-28) and the main README.md (lines 162-166).

Configuration example:

{
  "mcpServers": {
    "context7": {
      "url": "https://mcp.context7.com/mcp/oauth",
      "model": "gpt-4o-mini"
    }
  }
}

Authenticate with the CLI

Run the login command to initiate the Authorization Code flow:

ctx7 login

This command orchestrates the full PKCE flow as defined in packages/cli/src/commands/auth.ts (lines 51-66). The CLI will:

• Generate PKCE parameters
• Start a local callback server on port 52417
• Open your browser to the Context7 authorization page
• Exchange the resulting code for tokens
• Store credentials in ~/.context7/credentials.json

Token Management and Logout

Verify your current session:

ctx7 whoami

This command calls the Clerk userinfo endpoint to display your account details, as implemented in packages/cli/src/commands/auth.ts (lines 62-70).

To remove stored credentials:

ctx7 logout

This deletes the ~/.context7/credentials.json file (lines 41-47 in the same file).

OAuth 2.0 Implementation Details

The Context7 MCP server validates tokens using JWT verification before processing authenticated requests. In packages/mcp/src/index.ts (lines 48-61), the server checks the Authorization header, validates the JWT signature and claims, and rejects requests with expired or invalid tokens.

The server also exposes OAuth metadata to help clients discover authorization server capabilities. The /.well-known/oauth-protected-resource endpoint returns JSON indicating the resource URL, authorization server locations, and supported scopes.

Summary

• Context7 supports only the OAuth 2.0 Authorization Code flow with PKCE, implemented in the CLI at packages/cli/src/utils/auth.ts.
• Configuration requires changing your MCP endpoint from /mcp to /mcp/oauth to enable authentication.
• Authentication is handled via ctx7 login, which generates PKCE challenges, starts a local callback server on port 52417, and stores tokens in ~/.context7/credentials.json.
• Token validation occurs on every MCP request through JWT verification in packages/mcp/src/index.ts.

Frequently Asked Questions

What OAuth 2.0 flows does Context7 support?

Context7 supports only the Authorization Code flow with PKCE (Proof Key for Code Exchange). This is the industry-standard flow for native applications and CLI tools, preventing authorization code interception attacks. The implementation is located in packages/cli/src/utils/auth.ts and packages/cli/src/commands/auth.ts.

How do I configure the Context7 MCP server to use OAuth 2.0?

To enable OAuth 2.0, change your MCP client configuration to use the protected endpoint https://mcp.context7.com/mcp/oauth instead of the unprotected /mcp path. Then run ctx7 login to authenticate. This process is documented in docs/howto/oauth.mdx and the repository's README.md.

Where are OAuth tokens stored locally?

After successful authentication, Context7 stores your access token and optional refresh token in ~/.context7/credentials.json. The CLI manages this file automatically during ctx7 login and removes it during ctx7 logout. Token storage logic is implemented in packages/cli/src/utils/auth.ts.

Does Context7 support refresh tokens?

Yes, the OAuth 2.0 implementation in Context7 optionally returns refresh tokens alongside access tokens during the token exchange phase (see packages/cli/src/utils/auth.ts lines 236-250). The CLI stores these in the credentials file and can use them to obtain new access tokens when the current ones expire, though the specific refresh logic depends on the client implementation in packages/cli/src/commands/auth.ts.

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