feat: admin REST API with OpenAPI and API tokens, admin MCP endpoint, server update #19

Merged
marti merged 7 commits from feature/admin-api-mcp into develop 2026-11-06 11:52:27 +01:00
Owner

Summary

Everything the admin UI does is now scriptable: a documented REST API with personal API tokens, and an admin MCP endpoint (off by default) whose tools are those same routes. Also an Update button that pulls a stdio server's newest release.

flowchart LR
  ui[Admin UI, session cookie] --> routes
  script[Script / CI, Bearer mhk_ token] --> routes
  agent[Admin's agent, OAuth for /mcp/admin] --> mcp[/mcp/admin<br/>off by default/]
  mcp -- "inject() as the calling admin" --> routes[/api/admin/* routes<br/>Zod, requireAdmin, audit, events/]
  routes -. operationId + schemas .-> spec[/api/docs Swagger UI<br/>/api/docs/json OpenAPI 3.1/]
  routes -. same list .-> mcp
 apps/api/src/
 ├── plugins/
+│   └── openapi.ts          # spec + Swagger UI; collects admin routes as app.adminOperations
 ├── routes/
 │   ├── admin/
+│   │   └── settings.ts     # GET/PATCH /api/admin/settings (admin_mcp_enabled)
 │   ├── me/
+│   │   └── api-tokens.ts   # session only, so a token can never mint tokens
 │   └── mcp/
+│       └── admin.ts        # /mcp/admin, its own OAuth resource
 └── services/
+    ├── api-tokens.ts
+    └── admin-mcp/          # tools built from the routes, calls replayed via inject()
  • API tokens (mhk_, hashed, shown once, optional expiry) authenticate only routes whose matched pattern starts with /api/admin/, and only while the owner is an active admin. They skip the CSRF Origin check (a browser never attaches them by itself).
  • Admin MCP is a separate OAuth resource (PUBLIC_URL/mcp/admin). A /mcp token is refused there and vice versa. Consent warns about administrator access, and non-admins get access_denied. While switched off, the endpoint, its PRM and its authorize requests answer 404 / invalid_target, and switching it off closes its sessions.
  • Every admin route now declares operationId + summary (it becomes the tool name); the app refuses to start without them. start_server_oauth opts out of MCP (config: { adminMcp: false }) because it needs a browser session.
  • Update: installs now run with npm --prefer-online and uv tool install --refresh, so latest (or a git branch) really resolves to the newest release. The Version tile shows Update for those, and "Pinned" for exact versions.
  • New page Admin > API & MCP: token management, OpenAPI link, the admin MCP switch with its URL and a claude mcp add snippet.
  • The merge of develop adds get_server_logs to the new logs route.

Evidence

  • Before: no way to call the admin API except with a browser session. No spec. The admin MCP did not exist. Reinstall was hidden in the install-log panel and could reuse cached registry metadata.
    After: npm test all green (API 284, web 108, runner 46, shared 5), plus npm run typecheck, npm run lint and npm audit (0 vulnerabilities). New tests in apps/api/test/admin-automation.test.ts:
API tokens
  shown once, listed without the secret                          ok
  authenticate admin reads and writes without an Origin           ok  (audit actor = token owner)
  401 on /api/me and /api/me/api-tokens                           ok
  401 when invalid, expired, deleted, or owner demoted            ok
  403 to create for non-admins                                    ok
  forged x-mcphub-internal header -> 401                          ok
OpenAPI
  only /api/admin/* paths, operationIds present                   ok
  Swagger UI served                                               ok
admin MCP
  off by default: 404, PRM 404, authorize invalid_target          ok
  on: tools/list has create_user ...; create_user creates + audits ok
  /mcp and /mcp/admin tokens do not cross                         ok
  non-admin consent -> access_denied                              ok
  404 again once switched off                                     ok

Web: AutomationPage.test.tsx covers toggling the switch (PATCH body, snippet appears) and showing a new token once.
Not verified: Swagger UI in a real browser under the CSP. It only loads same-origin scripts, so it should be fine.

Merge Danger

Door: two-way

Migration 0002_api_tokens only adds a table, and reverting leaves it unused. The admin MCP ships off.

Blast Radius: admin-routes

  • Any new /api/admin route without operationId + summary crashes startup. That is intended, but it bites if a parallel branch adds one (as develop's logs route did).
  • The session plugin now accepts Bearer tokens on /api/admin/*. A bug there would be an auth bypass on admin routes, so that path has the most tests.
  • Every install now revalidates the npm/PyPI metadata cache, so installs are slightly slower and need registry access.

🤖 Generated with Claude Code

## Summary Everything the admin UI does is now scriptable: a documented REST API with personal API tokens, and an admin MCP endpoint (off by default) whose tools are those same routes. Also an **Update** button that pulls a stdio server's newest release. ```mermaid flowchart LR ui[Admin UI, session cookie] --> routes script[Script / CI, Bearer mhk_ token] --> routes agent[Admin's agent, OAuth for /mcp/admin] --> mcp[/mcp/admin<br/>off by default/] mcp -- "inject() as the calling admin" --> routes[/api/admin/* routes<br/>Zod, requireAdmin, audit, events/] routes -. operationId + schemas .-> spec[/api/docs Swagger UI<br/>/api/docs/json OpenAPI 3.1/] routes -. same list .-> mcp ``` ```diff apps/api/src/ ├── plugins/ +│ └── openapi.ts # spec + Swagger UI; collects admin routes as app.adminOperations ├── routes/ │ ├── admin/ +│ │ └── settings.ts # GET/PATCH /api/admin/settings (admin_mcp_enabled) │ ├── me/ +│ │ └── api-tokens.ts # session only, so a token can never mint tokens │ └── mcp/ +│ └── admin.ts # /mcp/admin, its own OAuth resource └── services/ + ├── api-tokens.ts + └── admin-mcp/ # tools built from the routes, calls replayed via inject() ``` - **API tokens** (`mhk_`, hashed, shown once, optional expiry) authenticate only routes whose *matched pattern* starts with `/api/admin/`, and only while the owner is an active admin. They skip the CSRF Origin check (a browser never attaches them by itself). - **Admin MCP** is a separate OAuth resource (`PUBLIC_URL/mcp/admin`). A `/mcp` token is refused there and vice versa. Consent warns about administrator access, and non-admins get `access_denied`. While switched off, the endpoint, its PRM and its authorize requests answer 404 / `invalid_target`, and switching it off closes its sessions. - **Every admin route now declares `operationId` + `summary`** (it becomes the tool name); the app refuses to start without them. `start_server_oauth` opts out of MCP (`config: { adminMcp: false }`) because it needs a browser session. - **Update**: installs now run with `npm --prefer-online` and `uv tool install --refresh`, so `latest` (or a git branch) really resolves to the newest release. The Version tile shows **Update** for those, and "Pinned" for exact versions. - New page **Admin > API & MCP**: token management, OpenAPI link, the admin MCP switch with its URL and a `claude mcp add` snippet. - The merge of `develop` adds `get_server_logs` to the new logs route. ## Evidence - **Before:** no way to call the admin API except with a browser session. No spec. The admin MCP did not exist. Reinstall was hidden in the install-log panel and could reuse cached registry metadata. **After:** `npm test` all green (API 284, web 108, runner 46, shared 5), plus `npm run typecheck`, `npm run lint` and `npm audit` (0 vulnerabilities). New tests in `apps/api/test/admin-automation.test.ts`: ```text API tokens shown once, listed without the secret ok authenticate admin reads and writes without an Origin ok (audit actor = token owner) 401 on /api/me and /api/me/api-tokens ok 401 when invalid, expired, deleted, or owner demoted ok 403 to create for non-admins ok forged x-mcphub-internal header -> 401 ok OpenAPI only /api/admin/* paths, operationIds present ok Swagger UI served ok admin MCP off by default: 404, PRM 404, authorize invalid_target ok on: tools/list has create_user ...; create_user creates + audits ok /mcp and /mcp/admin tokens do not cross ok non-admin consent -> access_denied ok 404 again once switched off ok ``` Web: `AutomationPage.test.tsx` covers toggling the switch (PATCH body, snippet appears) and showing a new token once. Not verified: Swagger UI in a real browser under the CSP. It only loads same-origin scripts, so it should be fine. ## Merge Danger **Door:** two-way Migration `0002_api_tokens` only adds a table, and reverting leaves it unused. The admin MCP ships off. **Blast Radius:** admin-routes - Any new `/api/admin` route without `operationId` + `summary` crashes startup. That is intended, but it bites if a parallel branch adds one (as `develop`'s logs route did). - The session plugin now accepts Bearer tokens on `/api/admin/*`. A bug there would be an auth bypass on admin routes, so that path has the most tests. - Every install now revalidates the npm/PyPI metadata cache, so installs are slightly slower and need registry access. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Every /api/admin route gets an operationId and summary; the spec is at
/api/docs/json. mhk_ tokens authenticate /api/admin/* only, while their
owner is an active admin, and are managed under /api/me with a session.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Its own OAuth resource; tools are the admin routes, replayed via inject()
as the calling admin. Switched on and off with PATCH /api/admin/settings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
fix(api): name the server logs route for OpenAPI and the admin MCP
All checks were successful
CI / check (pull_request) Successful in 5m37s
4594769128
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
marti merged commit 73f635c74e into develop 2026-11-06 11:52:27 +01:00
Sign in to join this conversation.
No reviewers
No labels
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
marti/mcphub!19
No description provided.