feat: personal MCP keys for bearer auth on /mcp #35

Merged
marti merged 3 commits from feature/mcp-keys into develop 2026-11-06 23:59:55 +01:00
Owner

Summary

Users can create personal MCP keys (mhm_...) on the Clients page and connect any MCP client to /mcp with Authorization: Bearer mhm_..., for clients that cannot do OAuth. OAuth is unchanged.

 /mcp request
-  authenticateBearer          # OAuth access token only
+  authenticateMcp
+    mhm_ prefix -> verifyMcpKey   # api_tokens kind='mcp', owner active, unexpired
+    else        -> authenticateBearer (OAuth, unchanged)
   session bound to (user, grant)
+  session bound to (user, grant | key); key deleted -> sessions closed
   tool_calls row
+    api_token_id                 # shown as "<name> (MCP key)" in activity
 api_tokens
+  kind  admin | mcp           # existing rows default to admin (mhk_)
 tool_calls
+  api_token_id  -> api_tokens (on delete set null)

 apps/api/src/routes/me/
   api-tokens.ts              # admin mhk_ tokens, requireAdmin
+  mcp-keys.ts                # mhm_ keys, requireUser, session only
 apps/web/src/components/
+  TokenManager.tsx           # shared by Admin > API & MCP and /clients

The kinds stay separate: mhk_ never opens /mcp, mhm_ never opens /api/admin/* or /mcp/admin, and neither can manage tokens.

Evidence

  • Before: POST /mcp with any non-OAuth bearer -> 401; no way to create a key as a non-admin.
    After: new tests in apps/api/test/gateway.test.ts > MCP keys:

    • any user creates a key, connects, lists and calls their own tools with their own credentials; the call is recorded with api_token_id
    • mhk_ on /mcp, mhm_ on /api/admin/servers and /mcp/admin, mhm_ on /api/me/mcp-keys, and deleting another user's key are all refused
    • unknown, expired, and disabled-owner keys -> 401 invalid_token
    • deleting a key closes its open session; another credential of the same user cannot take over the session

    Web: ClientsPage.test.tsx creates a key and sees it once with the Claude Code command. scripts/ci.sh passes locally (lint, typecheck, 502 tests, build, audit).

trail check flags two learnings (admin tools on the user gateway, hand-written MCP tools) on keyword matches only: this adds no tools and keeps admin power off /mcp.

Merge Danger

Door: two-way

Migration 0005_mcp_keys only adds an enum, a defaulted column and a nullable FK column; reverting the code leaves them harmless.

Blast Radius: auth

/mcp authentication gained a second path. A bug there would let a key reach /mcp it shouldn't, so the review should focus on services/gateway/auth.ts and verifyToken in services/api-tokens.ts. The admin token UI was moved into TokenManager (wording now "API token created" / "API token revoked").

🤖 Generated with Claude Code

## Summary Users can create personal **MCP keys** (`mhm_...`) on the Clients page and connect any MCP client to `/mcp` with `Authorization: Bearer mhm_...`, for clients that cannot do OAuth. OAuth is unchanged. ```diff /mcp request - authenticateBearer # OAuth access token only + authenticateMcp + mhm_ prefix -> verifyMcpKey # api_tokens kind='mcp', owner active, unexpired + else -> authenticateBearer (OAuth, unchanged) session bound to (user, grant) + session bound to (user, grant | key); key deleted -> sessions closed tool_calls row + api_token_id # shown as "<name> (MCP key)" in activity ``` ```diff api_tokens + kind admin | mcp # existing rows default to admin (mhk_) tool_calls + api_token_id -> api_tokens (on delete set null) apps/api/src/routes/me/ api-tokens.ts # admin mhk_ tokens, requireAdmin + mcp-keys.ts # mhm_ keys, requireUser, session only apps/web/src/components/ + TokenManager.tsx # shared by Admin > API & MCP and /clients ``` The kinds stay separate: `mhk_` never opens `/mcp`, `mhm_` never opens `/api/admin/*` or `/mcp/admin`, and neither can manage tokens. ## Evidence - **Before:** `POST /mcp` with any non-OAuth bearer -> 401; no way to create a key as a non-admin. **After:** new tests in `apps/api/test/gateway.test.ts > MCP keys`: - any user creates a key, connects, lists and calls their own tools with their own credentials; the call is recorded with `api_token_id` - `mhk_` on `/mcp`, `mhm_` on `/api/admin/servers` and `/mcp/admin`, `mhm_` on `/api/me/mcp-keys`, and deleting another user's key are all refused - unknown, expired, and disabled-owner keys -> 401 `invalid_token` - deleting a key closes its open session; another credential of the same user cannot take over the session Web: `ClientsPage.test.tsx` creates a key and sees it once with the Claude Code command. `scripts/ci.sh` passes locally (lint, typecheck, 502 tests, build, audit). `trail check` flags two learnings (admin tools on the user gateway, hand-written MCP tools) on keyword matches only: this adds no tools and keeps admin power off `/mcp`. ## Merge Danger **Door:** two-way Migration `0005_mcp_keys` only adds an enum, a defaulted column and a nullable FK column; reverting the code leaves them harmless. **Blast Radius:** auth `/mcp` authentication gained a second path. A bug there would let a key reach `/mcp` it shouldn't, so the review should focus on `services/gateway/auth.ts` and `verifyToken` in `services/api-tokens.ts`. The admin token UI was moved into `TokenManager` (wording now "API token created" / "API token revoked"). 🤖 Generated with [Claude Code](https://claude.com/claude-code)
Users can create mhm_ keys under /api/me/mcp-keys and send them as
Authorization: Bearer on /mcp, for clients that cannot do OAuth. Keys are
api_tokens rows with kind 'mcp'; admin mhk_ tokens are kind 'admin'.
The two kinds never stand in for each other, keys never open /mcp/admin
or the admin REST API, deleting a key closes its sessions, and
tool_calls.api_token_id records the key a call came through.

trail check flags two learnings (admin tools on the user gateway,
hand-written MCP tools) on keyword matches only: this adds no tools and
keeps admin power off /mcp.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The token table and create dialog move into a shared TokenManager, used
by Admin > API & MCP and a new MCP keys section on /clients. A new key is
shown once with a Claude Code command and a JSON config.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
docs: describe MCP keys
All checks were successful
CI / check (pull_request) Successful in 5m59s
118813191b
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
marti merged commit b4567aba25 into develop 2026-11-06 23:59:55 +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!35
No description provided.