# Context7 OAuth 2.0 Flows: Authorization Code with PKCE Configuration Guide

> Configure Context7 OAuth 2.0 Authorization Code with PKCE flow. Easily authenticate users via your browser by switching to the /mcp/oauth endpoint and running ctx7 login.

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

---

**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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/README.md) (lines 162-166).

**Configuration example:**

```json
{
  "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:

```bash
ctx7 login

```

This command orchestrates the full PKCE flow as defined in [`packages/cli/src/commands/auth.ts`](https://github.com/upstash/context7/blob/main/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:

```bash
ctx7 whoami

```

This command calls the Clerk userinfo endpoint to display your account details, as implemented in [`packages/cli/src/commands/auth.ts`](https://github.com/upstash/context7/blob/main/packages/cli/src/commands/auth.ts) (lines 62-70).

To remove stored credentials:

```bash
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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/packages/cli/src/utils/auth.ts) and [`packages/cli/src/commands/auth.ts`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/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`](https://github.com/upstash/context7/blob/main/packages/cli/src/commands/auth.ts).