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/mcpresource. Browser clients discover OAuth from the route metadata andWWW-Authenticatechallenge, 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_supportedmakes clients ask Clerk for every scope, includingopenid, 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_dataregistration in packages/…/server.ts. The browser only receivesstructuredContent; 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 compilesapi/andsrc/and does not buildui/, 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 useSERVER_ICONS.
Risks
- packages/…/oauth-protected-resource.ts is fragile around OAuth scope metadata: recent history includes
d980242adding icons/server-card metadata and739d164“Put scopes_supported back in the Admin MCP resource metadata.” Ifscopes_supporteddrifts 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.parentwith target origin"*"and accepts messages whoseevent.sourceiswindow.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.