Context7 Platform -- Up-to-date docs for AI agents
feat(mcp): authenticate and track Claude Code plugin (#3028)
Enes Gules21c3dd464e08
diff --git a/.changeset/mcp-plugin-client-auth.md b/.changeset/mcp-plugin-client-auth.mdnew file mode 100644index 00000000..3eaf1f52--- /dev/null+++ b/.changeset/mcp-plugin-client-auth.md@@ -0,0 +1,5 @@+---+"@upstash/context7-mcp": patch+---++Require authentication and track usage separately for the Claude Code plugin.diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex 9a32fe78..4b7f7ed0 100644--- a/.claude-plugin/marketplace.json+++ b/.claude-plugin/marketplace.json@@ -3,12 +3,13 @@"owner": {"name": "Upstash"},+ "description": "Context7 plugins for coding agents.","plugins": [{"name": "context7","source": "./plugins/claude/context7","description": "Up-to-date documentation lookup. Pull version-specific documentation and code examples directly from source repositories into your LLM context.",- "version": "1.0.2"+ "version": "1.0.3"}]}diff --git a/packages/cli/src/__tests__/plugin-manifests.test.ts b/packages/cli/src/__tests__/plugin-manifests.test.tsindex 60b80fc1..7e323e96 100644--- a/packages/cli/src/__tests__/plugin-manifests.test.ts+++ b/packages/cli/src/__tests__/plugin-manifests.test.ts@@ -1,24 +1,43 @@import { describe, test, expect } from "vitest";import { readFile } from "fs/promises";import { join } from "path";+import { execFile } from "child_process";+import { promisify } from "util";const REPO_ROOT = join(import.meta.dirname, "..", "..", "..", "..");+const execFileAsync = promisify(execFile);describe("plugin MCP manifests", () => {- // Deliberately the raw key, not `Bearer <key>` as the CLI writes. Both plugins- // document that an unset key still works over the anonymous tier, and this is- // the only form that survives both states: the server rejects `Bearer` with an- // empty token but treats an empty Authorization as anonymous.- test.each(["plugins/claude/context7/.mcp.json", "plugins/copilot/context7/.mcp.json"])(- "%s passes the raw key via Authorization",- async (relPath) => {- const raw = await readFile(join(REPO_ROOT, relPath), "utf-8");- const config = JSON.parse(raw) as {- mcpServers: { context7: { headers: Record<string, string> } };- };- expect(config.mcpServers.context7.headers).toEqual({- Authorization: "${CONTEXT7_API_KEY:-}",- });- }- );+ test("Claude uses an API key only when one is set", async () => {+ const relPath = "plugins/claude/context7/.mcp.json";+ const raw = await readFile(join(REPO_ROOT, relPath), "utf-8");+ const config = JSON.parse(raw) as {+ mcpServers: { context7: { headers?: Record<string, string>; headersHelper: string } };+ };+ expect(config.mcpServers.context7.headers).toBeUndefined();+ expect(config.mcpServers.context7.headersHelper).toBe(+ 'node "${CLAUDE_PLUGIN_ROOT}/scripts/headers.mjs"'+ );++ const helper = join(REPO_ROOT, "plugins/claude/context7/scripts/headers.mjs");+ const withoutKey = await execFileAsync(process.execPath, [helper], {+ env: { ...process.env, CONTEXT7_API_KEY: "" },+ });+ expect(JSON.parse(withoutKey.stdout)).toEqual({});++ const withKey = await execFileAsync(process.execPath, [helper], {+ env: { ...process.env, CONTEXT7_API_KEY: "ctx7sk-test" },+ });+ expect(JSON.parse(withKey.stdout)).toEqual({ Authorization: "ctx7sk-test" });+ });++ test("Copilot passes the raw API key via Authorization", async () => {+ const raw = await readFile(join(REPO_ROOT, "plugins/copilot/context7/.mcp.json"), "utf-8");+ const config = JSON.parse(raw) as {+ mcpServers: { context7: { headers: Record<string, string> } };+ };+ expect(config.mcpServers.context7.headers).toEqual({+ Authorization: "${CONTEXT7_API_KEY:-}",+ });+ });});diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.tsindex 009fb7e4..9b197846 100644--- a/packages/mcp/src/index.ts+++ b/packages/mcp/src/index.ts@@ -28,6 +28,15 @@ import { getMaxSubscriptions } from "./lib/subscriptions.js";/** Default HTTP server port */const DEFAULT_PORT = 3000;+const CLAUDE_CODE_PLUGIN = "claude-code-plugin";++function getPluginFromRequest(req: express.Request): typeof CLAUDE_CODE_PLUGIN | undefined {+ return req.query.client === CLAUDE_CODE_PLUGIN ? CLAUDE_CODE_PLUGIN : undefined;+}++function requiresAuthentication(req: express.Request, plugin?: typeof CLAUDE_CODE_PLUGIN): boolean {+ return req.path === "/mcp/oauth" || Boolean(plugin);+}// Parse CLI arguments using commanderconst program = new Command()@@ -390,12 +399,9 @@ async function main() {onerror: (error) => console.error("MCP node adapter error:", error),});- const handleMcpRequest = async (- req: express.Request,- res: express.Response,- requireAuth: boolean- ) => {+ const handleMcpRequest = async (req: express.Request, res: express.Response) => {try {+ const plugin = getPluginFromRequest(req);const apiKey = extractApiKey(req);const baseUrl = new URL(RESOURCE_URL).origin;@@ -409,7 +415,7 @@ async function main() {`Bearer resource_metadata="${baseUrl}/.well-known/oauth-protected-resource"`);- if (requireAuth) {+ if (requiresAuthentication(req, plugin)) {if (!apiKey) {return res.status(401).json({jsonrpc: "2.0",@@ -438,8 +444,9 @@ async function main() {const context: ClientContext = {clientIp: req.ip,- apiKey: apiKey,+ apiKey,clientInfo: extractClientInfoFromUserAgent(req.headers["user-agent"]),+ plugin,transport: "http",};@@ -458,14 +465,13 @@ async function main() {}};- // Anonymous access endpoint - no authentication requiredapp.all("/mcp", async (req, res) => {- await handleMcpRequest(req, res, false);+ await handleMcpRequest(req, res);});// OAuth-protected endpoint - requires authenticationapp.all("/mcp/oauth", async (req, res) => {- await handleMcpRequest(req, res, true);+ await handleMcpRequest(req, res);});app.get("/ping", (_req: express.Request, res: express.Response) => {diff --git a/packages/mcp/src/lib/encryption.ts b/packages/mcp/src/lib/encryption.tsindex a6ed5d70..d6879f55 100644--- a/packages/mcp/src/lib/encryption.ts+++ b/packages/mcp/src/lib/encryption.ts@@ -77,6 +77,9 @@ export function generateHeaders(context: ClientContext): Record<string, string>if (context.clientInfo?.version) {headers["X-Context7-Client-Version"] = context.clientInfo.version;}+ if (context.plugin) {+ headers["X-Context7-Plugin"] = context.plugin;+ }if (context.transport) {headers["X-Context7-Transport"] = context.transport;}diff --git a/packages/mcp/src/lib/types.ts b/packages/mcp/src/lib/types.tsindex 3b5a024f..47cacce2 100644--- a/packages/mcp/src/lib/types.ts+++ b/packages/mcp/src/lib/types.ts@@ -39,6 +39,7 @@ export interface ClientContext {ide?: string;version?: string;};+ plugin?: string;transport?: "stdio" | "http";sessionId?: string;/** Mutable: set by the upstream API layer when the backend signals thediff --git a/packages/mcp/test/integration.test.ts b/packages/mcp/test/integration.test.tsindex 134b9d71..269c6773 100644--- a/packages/mcp/test/integration.test.ts+++ b/packages/mcp/test/integration.test.ts@@ -305,3 +305,74 @@ describe.each([expect(apiCall.headers["x-context7-client-version"]).toBe(expected.version);});});++const INITIALIZE = {+ jsonrpc: "2.0",+ id: 1,+ method: "initialize",+ params: {+ protocolVersion: "2025-06-18",+ capabilities: {},+ clientInfo: { name: "t", version: "1" },+ },+};++async function postMcp(target: string, headers: Record<string, string> = {}) {+ const res = await fetch(target, {+ method: "POST",+ headers: {+ "Content-Type": "application/json",+ Accept: "application/json, text/event-stream",+ ...headers,+ },+ body: JSON.stringify(INITIALIZE),+ });+ return { status: res.status, wwwAuthenticate: res.headers.get("www-authenticate") };+}++describe("plugin authentication", () => {+ beforeEach(() => {+ requests.length = 0;+ });++ test("only challenges the supported plugin", async () => {+ expect((await postMcp(`${httpUrl}?client=other-plugin`)).status).toBe(200);++ const res = await postMcp(`${httpUrl}?client=claude-code-plugin`);+ expect(res.status).toBe(401);+ expect(res.wwwAuthenticate).toContain("resource_metadata=");+ expect(res.wwwAuthenticate).toContain("/.well-known/oauth-protected-resource");+ });++ test("keeps the OAuth endpoint protected", async () => {+ const res = await postMcp(httpUrl.replace(/\/mcp$/, "/mcp/oauth"));++ expect(res.status).toBe(401);+ });++ test("tracks authenticated plugin requests separately", async () => {+ const client = new Client(+ { name: "claude-code", version: "1.0.0" },+ { versionNegotiation: { mode: { pin: "2026-07-28" } } }+ );+ await client.connect(+ new StreamableHTTPClientTransport(new URL(`${httpUrl}?client=claude-code-plugin`), {+ requestInit: { headers: { Authorization: "Bearer ctx7sk-test" } },+ })+ );++ try {+ await client.callTool({+ name: "query-docs",+ arguments: { libraryId: "/vercel/next.js", query: "app router" },+ });+ } finally {+ await client.close();+ }++ const apiCall = requests.find((request) => request.path === "/v2/context");+ expect(apiCall?.headers["x-context7-client-ide"]).toBe("claude-code");+ expect(apiCall?.headers["x-context7-client-version"]).toBe("1.0.0");+ expect(apiCall?.headers["x-context7-plugin"]).toBe("claude-code-plugin");+ });+});diff --git a/plugins/claude/context7/.claude-plugin/plugin.json b/plugins/claude/context7/.claude-plugin/plugin.jsonindex a53438cb..873f1802 100644--- a/plugins/claude/context7/.claude-plugin/plugin.json+++ b/plugins/claude/context7/.claude-plugin/plugin.json@@ -1,5 +1,6 @@{"name": "context7",+ "version": "1.0.3","description": "Upstash Context7 MCP server for up-to-date documentation lookup. Pull version-specific documentation and code examples directly from source repositories into your LLM context.","author": {"name": "Upstash"diff --git a/plugins/claude/context7/.mcp.json b/plugins/claude/context7/.mcp.jsonindex 7fda704c..41153c88 100644--- a/plugins/claude/context7/.mcp.json+++ b/plugins/claude/context7/.mcp.json@@ -2,10 +2,8 @@"mcpServers": {"context7": {"type": "http",- "url": "https://mcp.context7.com/mcp",- "headers": {- "Authorization": "${CONTEXT7_API_KEY:-}"- }+ "url": "https://mcp.context7.com/mcp?client=claude-code-plugin",+ "headersHelper": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/headers.mjs\""}}}diff --git a/plugins/claude/context7/README.md b/plugins/claude/context7/README.mdindex 32f77b24..14044442 100644--- a/plugins/claude/context7/README.md+++ b/plugins/claude/context7/README.md@@ -20,16 +20,17 @@ claude plugin marketplace add upstash/context7claude plugin install context7@context7-marketplace```-## API Key (Recommended)+## Authentication-Without an API key, the plugin connects anonymously and shares the anonymous rate limits. To use your own plan, create an API key in the [Context7 dashboard](https://context7.com/dashboard) and export it as an environment variable before launching Claude Code:+After installing the plugin, restart Claude Code and run:-```bash-# e.g. in ~/.zshrc or ~/.bashrc-export CONTEXT7_API_KEY="your-api-key"```+/mcp+```++Select Context7 and follow the browser sign-in flow. No API key is required.-The plugin's MCP server configuration picks up `CONTEXT7_API_KEY` automatically. Restart Claude Code after setting it, then verify the key is being used by checking your usage in the [dashboard](https://context7.com/dashboard).+To use an API key instead, set `CONTEXT7_API_KEY` before starting Claude Code. The plugin sends the key only when it is present; otherwise it uses OAuth.## Available Toolsdiff --git a/plugins/claude/context7/scripts/headers.mjs b/plugins/claude/context7/scripts/headers.mjsnew file mode 100644index 00000000..5a51464c--- /dev/null+++ b/plugins/claude/context7/scripts/headers.mjs@@ -0,0 +1,3 @@+const apiKey = process.env.CONTEXT7_API_KEY;++process.stdout.write(JSON.stringify(apiKey ? { Authorization: apiKey } : {}));