mirror of
https://github.com/upstash/context7.git
synced 2026-09-14 19:09:34 +08:00
Fahreddin Özcan
48da517fe5
BREAKING CHANGE: an anonymous client on /mcp is now challenged on its first request, including initialize. Set CONTEXT7_MCP_AUTH_MODE=lazy to restore the previous behaviour, where anonymous callers connect and spend their free monthly requests before being asked to sign in. Testing the lazy gate against real clients showed the challenge lands in the wrong place. Every client we tried runs OAuth natively at connect time: Codex starts the flow the moment it discovers the resource metadata, without sending a single JSON-RPC message; Claude Code exposes its authorize helpers only for servers already flagged when the session started; Zed handles the 401 during server startup. The same challenge raised mid-conversation is handled far worse — it fails the turn in progress, and on Claude Code the recovery path does not appear until the next session, so the user loses their turn and has to know to run /mcp. Challenging on connect trades the anonymous trial for a prompt the client knows how to show. Deployments that would rather keep the trial can set the flag; the gate, the backend-driven quota mirror and the per-client challenge shapes all still work in that mode and are unchanged. The integration suite runs with the flag set, since it exercises anonymous protocol behaviour. test/auth-mode.test.ts covers the new default against the built binary: anonymous initialize and tools/list are refused with a challenge carrying resource_metadata and scope, a credential gets through, and the discovery document stays public.
59 lines
2.9 KiB
Plaintext
59 lines
2.9 KiB
Plaintext
---
|
|
title: Set Up OAuth
|
|
description: Authenticate with Context7 MCP server using OAuth 2.0
|
|
---
|
|
|
|
<Note>
|
|
OAuth is only available for remote HTTP connections. For local MCP connections using stdio
|
|
transport, use [API key authentication](/howto/api-keys) instead.
|
|
</Note>
|
|
|
|
Context7 MCP server supports OAuth 2.0 authentication for MCP clients that implement the [MCP OAuth specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization).
|
|
|
|
## Why Use OAuth?
|
|
|
|
| Feature | OAuth | API Keys |
|
|
| -------------------------- | ----- | -------- |
|
|
| No manual key management | ✅ | ❌ |
|
|
| Automatic token refresh | ✅ | ❌ |
|
|
| Works with stdio transport | ❌ | ✅ |
|
|
|
|
## Two Endpoints
|
|
|
|
| Endpoint | Behaviour |
|
|
| ------------ | --------------------------------------------------------------- |
|
|
| `/mcp` | Asks you to sign in when your client first connects |
|
|
| `/mcp/oauth` | Same, and always enforced regardless of server configuration |
|
|
|
|
Both endpoints ask for sign-in up front. That is deliberate: MCP clients run the OAuth
|
|
flow natively at connect time, so you get your editor's own sign-in prompt instead of a
|
|
failed request part-way through a conversation.
|
|
|
|
Self-hosted deployments can set `CONTEXT7_MCP_AUTH_MODE=lazy` on the MCP server to let
|
|
anonymous callers connect and spend their free monthly requests before being asked to
|
|
sign in. That trades a natively handled prompt for a frictionless trial.
|
|
|
|
```diff
|
|
- "url": "https://mcp.context7.com/mcp"
|
|
+ "url": "https://mcp.context7.com/mcp/oauth"
|
|
```
|
|
|
|
## How It Works
|
|
|
|
1. Your MCP client connects and receives an OAuth challenge pointing at Context7
|
|
2. Your client shows a sign-in prompt or an authorization link
|
|
3. You're redirected to Context7 to sign in
|
|
4. After signing in, your client stores the token and connects
|
|
5. Your client automatically handles token refresh from then on
|
|
|
|
In `lazy` mode the challenge arrives later — on the tool call that crosses your free
|
|
monthly limit — and steps 2 to 5 are otherwise identical.
|
|
|
|
<Warning>
|
|
**Some clients need you to start the sign-in yourself.** Whether the OAuth flow opens on its own depends on the client, not on Context7. Claude, Claude Desktop and ChatGPT show an inline connect prompt and retry the call once you finish. Terminal clients generally do not: in Claude Code run `/mcp`, select the server and choose "Authenticate"; in Codex CLI run `codex mcp login <server-name>`.
|
|
</Warning>
|
|
|
|
## Client Support
|
|
|
|
OAuth authentication requires your MCP client to support the [MCP OAuth specification](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization). If your client doesn't support OAuth, use [API key authentication](/howto/api-keys) instead — an API key raises your limit the same way signing in does, and works on both endpoints.
|