Introducing a new way to review your PRs.

Read the announcement

upstash / context7

Context7 Platform -- Up-to-date docs for AI agents

View on GitHub

13 documents · Updated Nov 16, 2026

docs / admin-mcp-runtime

Admin MCP runtime

Overview

The Admin MCP package is a Vercel-hosted, stateless MCP server for managing Context7 teamspaces, libraries, Docs7 sites, Ask sites, usage, rules, and feedback. The package metadata in packages/…/package.json defines it as @upstash/context7-admin-mcp, pins the MCP server/client dependencies, and exposes the main runtime checks: build (tsc), test (vitest), typecheck, lint, dev, and the UI build scripts. TypeScript for the shipped runtime is limited to packages/admin-mcp/src/**/* by packages/…/tsconfig.json; packages/…/tsconfig.test.json widens typechecking to test/**/*, api/**/*, and scripts/**/*.

The public MCP endpoint is assembled in packages/…/http.ts. createAdminHandler() wraps mcp-handler's createMcpHandler(registerAdminTools, SERVER_OPTIONS) with withMcpAuth. Authentication is intentionally permissive at the MCP layer: any bearer token or ctx7sk- API key is accepted into request state, then forwarded to the Context7 management API, which is the authority for permissions. If a downstream API call returns 401, src/server.ts marks RequestState.authRejected; src/http.ts buffers the whole MCP response before returning and replaces it with a bearer OAuth challenge so clients sign in again. Requests without a bearer also receive the OAuth challenge. RESOURCE_URL controls the public origin (default https://admin.mcp.context7.com), MCP_PATH is /mcp, and OAUTH_AUTH_SERVER_URL defaults to https://clerk.context7.com.

packages/…/server.ts is the main runtime coordinator. It reads SERVER_VERSION from package.json, derives API_BASE_URL from CONTEXT7_API_URL (default https://context7.com/api), defines server metadata/icons/instructions in SERVER_OPTIONS, registers the console resource, registers every tool from src/tools.ts, and registers the app-only console_data helper. Each tool call goes through runTool(): it builds a per-call API client with authorization and telemetry headers, validates console-originated arguments, resolves teamspace values from an id/name/only-teamspace lookup, handles destructive confirmation, calls the tool's run, and emits a JSON audit line containing tool, optional from: "console", teamspace, and outcome. API requests include Authorization, X-Context7-Source: admin-mcp, X-Context7-Server-Version, and per-tool/client telemetry (X-Context7-Tool, X-Context7-Client-IDE, X-Context7-Client-Version).

Tool definitions live in packages/…/tools.ts. The ToolDef shape describes the MCP name/title/description, one kind or per-action actions, zod argument fields, whether the result contains third-party text, whether a teamspace should be injected, whether it participates in the console, optional idempotency, optional destructive confirmation text, and the run implementation. Helpers in this file normalize path segments and library ids, paginate library and Docs7 site lists, poll long-running jobs for up to about 25 seconds, strip internal/noisy fields from API responses, and adapt API envelopes such as { data }. The TOOLS array is grouped by account, libraries, rules/policies, usage, Docs7, Ask, and feedback. Most tools call /v2/teamspaces/... endpoints through the API abstraction; teamspace-independent tools include list_teamspaces, open_console, and submit_feedback_to_context7_team.

Result formatting and model safety are handled in packages/…/server.ts. Successful results are compact JSON with null/undefined fields removed and are truncated at MAX_RESULT_CHARS (80,000 characters). Tools marked untrusted in src/tools.ts have their text wrapped in a fresh <untrusted-data-UUID> fence with an instruction not to follow third-party content. API failures become actionable tool errors: ApiError preserves status/body, errorText() leads with HTTP status/code/message, maps known Context7 API error codes to next steps, and fences untrusted error bodies too. The console path receives plain error text in structuredContent.error while keeping fenced content for anything that could reach the model.

Destructive confirmation is centralized in packages/…/confirm.ts. confirmArg is injected into any destructive tool schema by src/server.ts; tools provide the concrete target via their confirm() callback in src/tools.ts. For clients that declare 2026-07-28 form elicitation in the per-request MCP envelope, confirmWithUser() returns input_required and only accepts the user's form response. The model-supplied confirm argument is ignored in that mode. For older clients, the server requires confirm to equal the expected target (optionally normalized) before running the destructive API call; otherwise it returns a ToolError telling the agent to ask the user.

Legacy JSON-RPC batch cleanup is in packages/…/batch.ts and is invoked by withoutSelfCancellations() in src/http.ts before dispatch. A 2025-era batch that contains a request and its own notifications/cancelled would make the MCP SDK wait for an answer that will never arrive, holding the Vercel invocation open. filterBatchSelfCancellations() removes both the request and matching cancellation unless any batch element claims the newer protocol version through PROTOCOL_VERSION_META_KEY; if the whole POST becomes empty, src/http.ts answers 202 immediately.

The server-side MCP App resource is registered in packages/…/console.ts. open_console tools advertise CONSOLE_TOOL_META with ui.resourceUri, the legacy ui/resourceUri, and OpenAI app entrypoints. registerConsole() serves CONSOLE_HTML from packages/…/console-html.ts as text/html;profile=mcp-app at ui://context7/console with an empty CSP for connect/resource domains. The page holds no credential and is supposed to read only through the app-visible console_data tool; other tools are registered with _meta.ui.visibility: ["model"]. packages/…/console-html.ts is generated and committed by pnpm build:ui; lint and format configs (packages/…/eslint.config.js, packages/admin-mcp/.prettierignore) explicitly ignore it.

The local development entrypoint is packages/…/dev.ts. It reads the rewrites in packages/…/vercel.json, imports each destination handler, sets RESOURCE_URL to http://localhost:${PORT} if unset, and serves the same routes on 127.0.0.1 (default port 3100) using @hono/node-server. packages/…/vercel.json declares the production rewrite table for /mcp, /mcp/server-card, protected-resource metadata paths, OAuth authorization-server metadata proxy, and /ping; sets an empty buildCommand; enables Fluid; gives api/mcp.ts a 120-second max duration; and serves public/ as static output. packages/…/README.md documents the public connection URL, OAuth/API-key modes, destructive confirmation behavior, console behavior, deployment assumptions, development commands, and the runtime environment variables (CONTEXT7_API_URL, RESOURCE_URL, OAUTH_AUTH_SERVER_URL). packages/admin-mcp/LICENSE is the package's MIT license.

Runtime behavior is covered by packages/…/admin-mcp.test.ts, which drives createAdminHandler() through a real MCP Client and StreamableHTTPClientTransport while stubbing global fetch for the management API. The tests cover teamspace resolution, destructive confirmation with and without form elicitation, telemetry headers, authentication challenges and downstream 401 handling, legacy self-cancelled batches, untrusted-data fences, library id normalization, polling, Docs7 CLI-site deployment routing, read-only-key partial build details, omitted Docs7 site deletion, protected-resource metadata, list pagination/searching, server icons, agent activity summarization, rule deletion library lookup, library-request approval mode warnings, console_data visibility/structuredContent, open_console teamspace selection, and feedback submission.

Coupling

Risks

  • packages/…/confirm.ts and destructive definitions in packages/…/tools.ts: older clients cannot enforce user-only confirmation, so a model can still fill confirm after reading the target. If a destructive tool is added or its expected value is too easy to infer, clients without 2026-07-28 form elicitation may run irreversible deletes without a real user form.
  • packages/…/http.ts and packages/…/batch.ts: the self-cancellation filter protects Vercel invocations from legacy batches that would otherwise hang until timeout. If filterBatchSelfCancellations() stops recognizing these request/cancellation pairs, a POST containing only self-cancelled work can keep the stream open instead of returning 202.
  • packages/…/server.ts: formatResult() truncates before adding the untrusted-data fence wrapper, with the intent that the closing tag survives. If truncation is moved after fencing or the wrapper changes incorrectly, third-party text from tools marked untrusted in packages/…/tools.ts could escape the fence in model-visible content.
  • packages/…/server.ts: runTool() reads ctx.http?.authInfo?.extra?.state as RequestState; that state is populated by withMcpAuth in packages/…/http.ts. If these are decoupled, API calls may lose the caller's Authorization header or fail to report downstream 401s as OAuth challenges.
  • packages/…/console.ts and packages/…/server.ts: the console page relies on MCP host enforcement of _meta.ui.visibility to restrict it to console_data. A host that ignores visibility could let the app call write tools with the user's bearer; keep the page credential-free and keep write actions out of console_data.