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-web-api-ui

Admin MCP web/API/UI surface

Overview

This surface is the browser-facing and route-handler shell around the Context7 Admin MCP server. The Vercel functions in packages/admin-mcp/api/ are thin web-standard fetch exports: api/mcp.ts wraps createAdminHandler() from packages/…/http.ts with CORS and serves the streamable HTTP MCP endpoint at /mcp; api/oauth-protected-resource.ts serves RFC 9728 protected-resource metadata for /mcp; api/oauth-authorization-server.ts proxies Clerk authorization-server metadata; api/server-card.ts serves the SEP-2127 server card; and api/ping.ts is an unauthenticated JSON health check.

The route handlers rely on packages/…/http.ts for shared behavior. withCors() adds Access-Control-Allow-Origin: *, allows GET,POST,OPTIONS,DELETE, accepts MCP and Authorization headers, and exposes WWW-Authenticate plus MCP-Session-Id so browser clients can start OAuth. The MCP handler created by createAdminHandler() requires a bearer through withMcpAuth; the bearer can be an OAuth token or ctx7sk- API key and is forwarded unchanged to the Context7 management API, which is the authority on validity and permissions. If the management API later rejects a credential during a tool call, createAdminHandler() buffers the whole MCP response and replaces it with an OAuth bearer challenge.

packages/…/oauth-protected-resource.ts generates metadata with authServerUrls: [OAUTH_AUTH_SERVER_URL], resourceUrl: RESOURCE_URL, scopes_supported: ["profile", "email"], and bearer_methods_supported: ["header"]; its OPTIONS path uses mcp-handler's metadata preflight helper, while non-OPTIONS responses go through the local withCors(). packages/…/oauth-authorization-server.ts exposes authorizationServerMetadata() from src/http.ts, which fetches ${OAUTH_AUTH_SERVER_URL}/.well-known/oauth-authorization-server with a 10s timeout and returns either the upstream JSON or a JSON proxy/upstream error. packages/…/server-card.ts builds the public server card from RESOURCE_URL, SERVER_VERSION, and SERVER_ICONS, advertises optional Authorization: Bearer {api_key}, and returns application/mcp-server-card+json with a one-hour public cache.

The static public landing page is packages/…/index.html. It documents the remote endpoint https://admin.mcp.context7.com/mcp, Claude Code setup, generic HTTP MCP configuration, API-key usage, and dashboard/docs links. The public icon assets are packages/…/context7-icon.svg and packages/…/context7-icon.png; the server-card/API metadata imports the actual advertised icon list from packages/…/server.ts, so public icon file changes should be checked against that list.

The MCP App console source lives under packages/admin-mcp/ui/. ui/console.html mounts ui/…/main.tsx, which renders App from ui/…/app.tsx. The console has two layouts: an inline summary card for chat surfaces and a fullscreen console with navigation across usage, libraries, docs7, and ask. App subscribes to host state from ui/…/host.ts, connects to the MCP Apps host over JSON-RPC postMessage, and selects the teamspace from the latest open_console tool result or, when no tool call preceded the app open, from a list_teamspaces read. Inline cards set model context and expose at most “Open console” plus a host-mediated ChatButton; fullscreen adds the teamspace switcher, dashboard link, tabs, and page bodies.

packages/…/host.ts is the hand-written MCP Apps bridge. It sends ui/initialize with app capabilities for inline and fullscreen, receives host context/theme/display-mode updates, reports size changes via ui/notifications/size-changed, accepts ui/notifications/tool-input and ui/notifications/tool-result for open_console, and answers host ui/resource-teardown/ping requests. The page holds no credential and does not call the management API directly: Host.read() calls tools/call for the app-only server tool console_data, passing one of the console read tool names and arguments, then reads structuredContent only.

packages/…/data.ts defines the typed shapes the browser expects from console_data and the useTool() cache. Reads are keyed by JSON stringified [tool,args]; a page shows cached data immediately, refreshes in the background, preserves previous data on refresh failure, and exposes reload() for visible errors. The page modules map directly to tool families: ui/…/usage.tsx reads get_teamspace_usage and get_teamspace; ui/…/libraries.tsx reads list_libraries and, for owned libraries, get_library_benchmarks; ui/…/docs7.tsx reads docs7_list_sites, docs7_get_analytics, and docs7_list_deployments; ui/…/ask.tsx reads ask_list_sites and ask_get_analytics. ui/…/components.tsx, ui/…/charts.tsx, ui/…/format.ts, and ui/…/styles.css provide dashboard-styled cards, controls, meters, SVG charts, formatting, skeleton/error states, host theme variables, safe-area padding, and inline/fullscreen sizing rules.

The UI build is not just a browser artifact. packages/…/vite.config.ts uses React, Tailwind, and vite-plugin-singlefile, then writes the built single-file console into packages/…/console-html.ts as CONSOLE_HTML. That generated module is imported by packages/…/console.ts, which registers ui://context7/console as the MCP App resource. packages/admin-mcp/ui/demo/ is a local MCP Apps host simulator: demo/host.ts uses @modelcontextprotocol/ext-apps AppBridge, feeds fake open_console input/results, services console_data reads from demo/backend.ts, logs model-context/chat/link/display-mode interactions, and renders the built console.html; demo/index.html provides the host shell and query-controlled theme/display/view/teamspace settings.

Coupling

  • If any packages/admin-mcp/api/* route changes URL, CORS, OAuth metadata, or server-card behavior, verify packages/…/http.ts constants (RESOURCE_URL, METADATA_PATH, OAUTH_AUTH_SERVER_URL) and packages/…/console.ts registration still describe the same /mcp resource. Browser clients discover OAuth from the route metadata and WWW-Authenticate challenge, not from duplicated UI code.
  • If packages/…/oauth-protected-resource.ts changes scopes or metadata fields, test an OAuth sign-in client. The file documents that omitting scopes_supported makes clients ask Clerk for every scope, including openid, which Clerk refuses for MCP clients.
  • If packages/…/data.ts types or any ui/…/*.tsx read arguments change, update the corresponding tool definitions in packages/…/tools.ts and the app-only console_data registration in packages/…/server.ts. The browser only receives structuredContent; mismatched field names usually render as empty/error UI rather than a TypeScript error at runtime.
  • If packages/admin-mcp/ui/ source changes, run the UI build that ui/vite.config.ts describes so packages/…/console-html.ts is regenerated. Vercel compiles api/ and src/ and does not build ui/, so a changed React page without the generated module leaves production serving the old console.
  • If host bridge behavior in packages/…/host.ts changes, verify both real MCP Apps hosts and packages/…/host.ts. The app's assumptions about ui/initialize, tools/call, display modes, size reporting, and tool-input/tool-result notifications are mirrored in the demo host.
  • If packages/admin-mcp/public/context7-icon.* or the server-card identity changes, check packages/…/server-card.ts and packages/…/server.ts together. The public files are path assets, while the server card and ChatGPT app entrypoints use SERVER_ICONS.

Risks

  • packages/…/oauth-protected-resource.ts is fragile around OAuth scope metadata: recent history includes d980242 adding icons/server-card metadata and 739d164 “Put scopes_supported back in the Admin MCP resource metadata.” If scopes_supported drifts or is removed, MCP clients can request Clerk scopes this server cannot use and sign-in fails before the MCP endpoint is reached.
  • packages/…/vite.config.ts makes packages/…/console-html.ts a required generated source file. If a reviewer changes packages/admin-mcp/ui/src/* or packages/…/console.html but does not rebuild, the committed server resource still contains the old HTML and hosts will render stale UI even though the source tree looks updated.
  • packages/…/host.ts posts JSON-RPC to window.parent with target origin "*" and accepts messages whose event.source is window.parent. This is intentional for sandboxed MCP Apps hosts, but if the page is ever served outside that host model, an embedding parent controls tool calls, model-context updates, and link/display-mode requests.