feat: resolve open issues #6-#12, fix Claude Desktop OAuth #13

Merged
marti merged 27 commits from feature/open-issues into develop 2026-11-06 07:16:21 +01:00
Owner

Closes #6, closes #7, closes #8, closes #9, closes #10, closes #11, closes #12

Summary

All seven open issues, plus four things that came up while working on them: Claude Desktop could not connect, the password minimum, a link to this repo in the app, and db:generate ignoring --name.

Change
#6 Known MCP clients (Claude, Codex/ChatGPT, Grok, Gemini, Cursor, VS Code/Copilot, Windsurf, Zed, Cline, Goose, Open WebUI) show their brand mark wherever a client appears. The marks are inline SVGs, nothing is fetched at runtime, and there is no new dependency.
#7 New variables default to instance scope, not secret. Required stays on.
#8 Per server Available to everyone, on by default for new servers. Existing servers are migrated with it off and keep their access lists. Switching it off restores the stored list and closes sessions for users who lose access.
#9 Admins set test values for per-user variables. Test runs on them in its own process (<serverId>.<nil uuid>), never pooled and killed straight after, and fills the tool catalog.
#10 Optional icon URL (https), website and source links. The icon falls back to the website's favicon, then to initials.
#11 My servers is a grid of compact cards: icon, status, description, tools, the In my MCP switch and one action slot.
#12 Remote servers can use OAuth, set shared (admin signs in once) or per user (each user clicks Authenticate). mcphub is the OAuth client: discovery, DCR or an admin-provided client, PKCE, resource, rotating refresh, tokens encrypted.
fix Claude Desktop / claude.ai failed with invalid_client: their client metadata document lists jwt-bearer. Grant types mcphub does not support are now dropped, not refused.
extra Password minimum 12 -> 8. Git icon linking to this repo in the sidebar. npm run db:generate -- --name x passes --name through.

Upstream OAuth sign-in, per user:

sequenceDiagram
    participant B as Browser (portal)
    participant H as mcphub API
    participant AS as Upstream auth server
    participant M as Remote MCP server
    B->>H: POST /api/me/servers/:id/oauth/authorize
    H->>M: discover (RFC 9728) + AS metadata (RFC 8414)
    H->>AS: register client (RFC 7591), unless the admin set one
    H-->>B: authorizationUrl (PKCE S256, state, resource)
    B->>AS: sign in, consent
    AS-->>B: redirect /api/upstream-oauth/callback?code&state
    B->>H: callback (state bound to this browser session, single use)
    H->>AS: exchange code -> tokens (stored encrypted)
    H-->>B: 303 /servers/:id?oauth=connected
    H->>M: /mcp calls with Bearer, refreshed before expiry

How a server's status is decided after this PR:

 status(user, server)
   disabled                                -> disabled
-  not granted                             -> no access
+  not access_all and not granted          -> no access
   not installed / required instance unset -> unavailable
+  shared OAuth, no admin sign-in          -> unavailable
   required user value unset               -> needs_setup
+  per-user OAuth, no sign-in for user     -> needs_setup (Authenticate)
   otherwise                               -> ready

One migration, 0001_open_issues.sql. It replaces the three migrations the branches generated separately:

mcp_servers        + access_all (default true; existing rows backfilled to false)
                   + icon_url, source_url, website_url
                   + oauth_mode, oauth_client_id, oauth_client_secret_encrypted, oauth_scopes
server_variables   + test_value_encrypted (check: only on per-user variables)
new tables         upstream_oauth_clients, upstream_oauth_tokens, upstream_oauth_flows

Evidence

Screenshots come from a throwaway local instance with demo data. Dark theme, 1440 wide unless noted.

#6 client icons

Before: before before

After:
Connected clients
Activity
OAuth clients

#7 variable defaults

Before: before
After: new variable

#8 available to everyone

Before: before
After:
everyone
restricted
servers list

#9 test values

test values

header
form

#11 my servers grid

Before: before
After:
dark
light
phone

#12 OAuth for remote servers

portal authenticate
admin form
admin overview

Extras

source link
password hint

Claude Desktop fix

GET https://claude.ai/oauth/mcp-oauth-client-metadata
  "grant_types": ["authorization_code", "refresh_token",
                  "urn:ietf:params:oauth:grant-type:jwt-bearer"]

before: /oauth/authorize -> invalid_client "grant_types must include authorization_code and may add refresh_token"
after:  accepted; stored grant_types = [authorization_code, refresh_token]
test:   "drops grant types it does not support, as claude.ai lists jwt-bearer"  FAIL -> PASS

Checks

nix develop -c ./scripts/ci.sh   lint, typecheck, tests, build, audit: pass
  api 241 passed | 1 skipped    web 104    runner 38 | 2 skipped    shared 5
  npm audit --omit=dev: 0 vulnerabilities
nix flake check                  all checks passed

Tests added for the code written while merging the branches:

  • "an admin test of a per-user OAuth server uses the admin's token" fails without the fix in upstream/context.ts and passes with it.
  • setupNeeded is covered for an unset required instance value and for a shared sign-in.

Merge Danger

Door: one-way

The migration adds columns and tables and backfills access_all = false on existing servers. There is no down migration, so after deploy a rollback means restoring the database or leaving the extra columns in place. The code itself is easy to revert.

Blast Radius: wide

  • Access: services/access.ts decides who sees which server for /mcp, the portal and the admin views. The access_all backfill keeps existing servers as they are, but every server created after this deploys is open to everyone unless the admin switches it off.
  • OAuth client checks: the authorization server now accepts clients that list unknown grant types (they are dropped). The token endpoint still allows only authorization_code and refresh_token.
  • New outbound requests: upstream OAuth makes requests from the API container. Everything except the admin-set server origin goes through lib/safe-fetch.ts: https only, public addresses only, pinned DNS, no redirects, size and time limits. IP literals are now checked too.
  • New route: GET /api/upstream-oauth/callback is public on purpose. It checks the session itself and is bound to the state, single use and limited to 10 minutes.
  • Not done:
    • Disconnect forgets the upstream token but does not revoke it upstream (RFC 7009).
    • A test that is running shows up on the Runner page with no user, because of the probe's nil user id.

🤖 Generated with Claude Code

Closes #6, closes #7, closes #8, closes #9, closes #10, closes #11, closes #12 ## Summary All seven open issues, plus four things that came up while working on them: Claude Desktop could not connect, the password minimum, a link to this repo in the app, and `db:generate` ignoring `--name`. | | Change | |---|---| | #6 | Known MCP clients (Claude, Codex/ChatGPT, Grok, Gemini, Cursor, VS Code/Copilot, Windsurf, Zed, Cline, Goose, Open WebUI) show their brand mark wherever a client appears. The marks are inline SVGs, nothing is fetched at runtime, and there is no new dependency. | | #7 | New variables default to instance scope, not secret. Required stays on. | | #8 | Per server **Available to everyone**, on by default for new servers. Existing servers are migrated with it **off** and keep their access lists. Switching it off restores the stored list and closes sessions for users who lose access. | | #9 | Admins set **test values** for per-user variables. Test runs on them in its own process (`<serverId>.<nil uuid>`), never pooled and killed straight after, and fills the tool catalog. | | #10 | Optional icon URL (https), website and source links. The icon falls back to the website's favicon, then to initials. | | #11 | My servers is a grid of compact cards: icon, status, description, tools, the In my MCP switch and one action slot. | | #12 | Remote servers can use OAuth, set **shared** (admin signs in once) or **per user** (each user clicks Authenticate). mcphub is the OAuth client: discovery, DCR or an admin-provided client, PKCE, `resource`, rotating refresh, tokens encrypted. | | fix | Claude Desktop / claude.ai failed with `invalid_client`: their client metadata document lists `jwt-bearer`. Grant types mcphub does not support are now dropped, not refused. | | extra | Password minimum 12 -> 8. Git icon linking to this repo in the sidebar. `npm run db:generate -- --name x` passes `--name` through. | Upstream OAuth sign-in, per user: ```mermaid sequenceDiagram participant B as Browser (portal) participant H as mcphub API participant AS as Upstream auth server participant M as Remote MCP server B->>H: POST /api/me/servers/:id/oauth/authorize H->>M: discover (RFC 9728) + AS metadata (RFC 8414) H->>AS: register client (RFC 7591), unless the admin set one H-->>B: authorizationUrl (PKCE S256, state, resource) B->>AS: sign in, consent AS-->>B: redirect /api/upstream-oauth/callback?code&state B->>H: callback (state bound to this browser session, single use) H->>AS: exchange code -> tokens (stored encrypted) H-->>B: 303 /servers/:id?oauth=connected H->>M: /mcp calls with Bearer, refreshed before expiry ``` How a server's status is decided after this PR: ```diff status(user, server) disabled -> disabled - not granted -> no access + not access_all and not granted -> no access not installed / required instance unset -> unavailable + shared OAuth, no admin sign-in -> unavailable required user value unset -> needs_setup + per-user OAuth, no sign-in for user -> needs_setup (Authenticate) otherwise -> ready ``` One migration, `0001_open_issues.sql`. It replaces the three migrations the branches generated separately: ```text mcp_servers + access_all (default true; existing rows backfilled to false) + icon_url, source_url, website_url + oauth_mode, oauth_client_id, oauth_client_secret_encrypted, oauth_scopes server_variables + test_value_encrypted (check: only on per-user variables) new tables upstream_oauth_clients, upstream_oauth_tokens, upstream_oauth_flows ``` ## Evidence Screenshots come from a throwaway local instance with demo data. Dark theme, 1440 wide unless noted. ### #6 client icons **Before:** ![before](/attachments/8fcea9cf-3b5d-4221-ae6e-91cc38ae0c79) ![before](/attachments/b9e325ae-ff0c-4d19-b7ba-b29a0bff7be2) **After:** ![Connected clients](https://git.cumsek.com/attachments/e00eb77c-0445-44a0-8ba2-1d336ffa1ded) ![Activity](https://git.cumsek.com/attachments/d3c60e66-443c-4b50-a3cb-8a60192e8ad1) ![OAuth clients](https://git.cumsek.com/attachments/c5a63ee2-c82b-4d67-9e4c-936fec26ee7e) ### #7 variable defaults **Before:** ![before](/attachments/8cf8fdc6-1037-47b5-a148-27ed8a896ff9) **After:** ![new variable](https://git.cumsek.com/attachments/62779c17-a347-427a-8b9f-7f6256368629) ### #8 available to everyone **Before:** ![before](/attachments/d19179df-723c-4a7d-99ae-d3f51cb1535c) **After:** ![everyone](https://git.cumsek.com/attachments/d2286416-9984-4178-9094-75bb18843450) ![restricted](https://git.cumsek.com/attachments/6229aeae-a4d0-466a-86cf-326cb9cb35a8) ![servers list](https://git.cumsek.com/attachments/a3016957-db3f-4a63-bc1e-f4a0dbb5aeb9) ### #9 test values ![test values](https://git.cumsek.com/attachments/70647454-2500-4ec1-9a03-729984301512) ### #10 icon and links ![header](https://git.cumsek.com/attachments/a6f4723b-6780-4eb6-b531-5af126a3a524) ![form](https://git.cumsek.com/attachments/99d20a1a-fda8-4b95-9eb6-597f59d76375) ### #11 my servers grid **Before:** ![before](/attachments/bbab9572-6079-4829-bf45-5bd040bfa51c) **After:** ![dark](https://git.cumsek.com/attachments/ee7e9698-81e9-4dfb-92e9-a79d9ecc65d4) ![light](https://git.cumsek.com/attachments/1d469bc7-8b0f-4e6c-b5b7-274d7e7b9372) <img src="https://git.cumsek.com/attachments/c92116bf-f62d-4218-97a1-bb1c658dbf58" width="320" alt="phone"> ### #12 OAuth for remote servers ![portal authenticate](https://git.cumsek.com/attachments/f69626b1-41a1-42ed-822c-c38c2e52ec8c) ![admin form](https://git.cumsek.com/attachments/962bd415-638a-4fbb-a610-11884c47529a) ![admin overview](https://git.cumsek.com/attachments/00ec4d38-9686-4969-8940-5b7ba215cf8b) ### Extras ![source link](https://git.cumsek.com/attachments/7d9c129b-1f69-4983-9288-9bb986896555) ![password hint](https://git.cumsek.com/attachments/22f59c33-7c93-48d3-901f-33d0ba9200c4) ### Claude Desktop fix ```text GET https://claude.ai/oauth/mcp-oauth-client-metadata "grant_types": ["authorization_code", "refresh_token", "urn:ietf:params:oauth:grant-type:jwt-bearer"] before: /oauth/authorize -> invalid_client "grant_types must include authorization_code and may add refresh_token" after: accepted; stored grant_types = [authorization_code, refresh_token] test: "drops grant types it does not support, as claude.ai lists jwt-bearer" FAIL -> PASS ``` ### Checks ```text nix develop -c ./scripts/ci.sh lint, typecheck, tests, build, audit: pass api 241 passed | 1 skipped web 104 runner 38 | 2 skipped shared 5 npm audit --omit=dev: 0 vulnerabilities nix flake check all checks passed ``` Tests added for the code written while merging the branches: - "an admin test of a per-user OAuth server uses the admin's token" fails without the fix in `upstream/context.ts` and passes with it. - `setupNeeded` is covered for an unset required instance value and for a shared sign-in. ## Merge Danger **Door:** one-way The migration adds columns and tables and backfills `access_all = false` on existing servers. There is no down migration, so after deploy a rollback means restoring the database or leaving the extra columns in place. The code itself is easy to revert. **Blast Radius:** wide - **Access:** `services/access.ts` decides who sees which server for `/mcp`, the portal and the admin views. The `access_all` backfill keeps existing servers as they are, but every server created after this deploys is open to everyone unless the admin switches it off. - **OAuth client checks:** the authorization server now accepts clients that list unknown grant types (they are dropped). The token endpoint still allows only `authorization_code` and `refresh_token`. - **New outbound requests:** upstream OAuth makes requests from the API container. Everything except the admin-set server origin goes through `lib/safe-fetch.ts`: https only, public addresses only, pinned DNS, no redirects, size and time limits. IP literals are now checked too. - **New route:** `GET /api/upstream-oauth/callback` is public on purpose. It checks the session itself and is bound to the state, single use and limited to 10 minutes. - **Not done:** - Disconnect forgets the upstream token but does not revoke it upstream (RFC 7009). - A test that is running shows up on the Runner page with no user, because of the probe's nil user id. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
A git icon next to the logo in the sidebar, and beside the account menu in
the mobile header, opens the Forgejo repository in a new tab.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A variable added in the server form now starts as Scope=Instance with
Secret unchecked (Required stays checked), and VariableInput defaults its
scope to instance, matching the form.

Closes #7

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The SPA needs a client's client_uri and logo_uri to pick its icon on the
admin Activity and OAuth clients pages, as it already can for connected
clients and the consent screen.

Refs #6

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ClientAvatar now recognises Claude, Codex, OpenAI/ChatGPT, Grok, Gemini,
Cursor, VS Code, GitHub Copilot, Windsurf, Zed, Cline, Goose and Open WebUI
by client name, then by the hosts or custom schemes of client_uri,
client_id and redirect URIs, and draws their bundled mark (Simple Icons,
Lobe Icons, Tabler paths; nothing fetched at runtime). Black marks use the
theme text colour so they hold up in dark mode. Unknown clients keep their
https logo or the monogram.

The avatar now also appears on the admin Activity table, the admin OAuth
clients list and the connect guide's client tabs.

Closes #6

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Admins can set test values for a server's user-scope variables
(PUT /api/admin/servers/:id/test-values), stored encrypted in
server_variables.test_value_encrypted with AAD tv:<variableId>. Secret
test values are write-only and the audit row lists only the keys.

The connection test of a per-user server now uses them (falling back to
the admin's own value), runs under its own process key
<serverId>.<nil uuid> instead of the admin's real one, is never pooled
and is torn down right after listing tools, so test credentials never
serve a /mcp session. Missing required values come back as `missing`
with a message that says to set test values.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A Test values form (VariableValuesForm, secrets write-only) for per-user
variables; saving runs the connection test and toasts the outcome. A
test that lacks per-user values links to the Variables tab.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Adds mcp_servers.access_all (default true for new servers; the migration
sets it to false for every existing server so nobody gains access by
surprise) and optional icon_url, source_url and website_url columns.

services/access.ts treats an access_all server as reachable by every user,
so the gateway's tools/list, mcphub__status, the portal and change
notifications all follow it. PUT /api/admin/servers/:id/access takes an
optional accessAll and keeps the stored list either way; switching it off
invalidates every user who loses access and emits access.changed, exactly
like removing a grant, and is audited with the new setting. Summaries and
access views report accessAll, a user's access lists 'everyone', and a
group's servers say whether the grant is dormant.

The link fields are validated in the shared contract (http(s) for source
and website, https only for the icon, which the CSP's img-src already
allows), stored on create and update, audited as changed fields, and
returned to admins and the portal.

Refs #8, #10

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Access tab starts with an 'Available to everyone' switch. While it is
on, the group and user pickers are hidden and a note says the earlier
list is kept; switching it off brings the pickers back with that list and
warns that saving takes access away from everyone not listed. The create
form has the same switch (on by default), and the server list, overview
tile and group page show 'Everyone' for such servers.

Closes #8

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
claude.ai's Client ID Metadata Document lists
urn:ietf:params:oauth:grant-type:jwt-bearer next to authorization_code and
refresh_token, and mcphub refused the whole client with invalid_client, so
Claude Desktop and claude.ai could not connect. Registration and metadata
documents now only need authorization_code; other grant types are dropped
(RFC 7591 lets the server replace requested values) and the token endpoint
still accepts only the two it supports.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A shared ServerIcon component shows a server's icon URL, falls back to
its website's /favicon.ico, then to its initials, moving on whenever an
image fails to load (https images only, as the CSP allows, and without a
referrer). ServerLinks renders the website and source links with
rel="noopener noreferrer".

The server form gets Icon URL, Website and Source code inputs with a live
icon preview; the admin server list and detail header show the icon, and
the detail header and the portal's server page show the links. A test
pins the CSP's img-src to https images while scripts and connections stay
same-origin.

Closes #10

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
npm run db:generate -- --name <what> lost --name, because the root script
forwarded to the workspace without its own --, so drizzle-kit picked a random
migration name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Access is now chosen on the form itself (Available to everyone).

Refs #8

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The portal home lists servers as a responsive grid (one column on phones,
two or three as the content area grows, through container queries) of
compact cards: server icon, name, status badge, tools and transport, the
description clamped to two lines instead of the status filler sentence,
then a footer with the In my MCP switch and the card's action (Details or
Add N values). Servers that need the user still sort first and get a
warning accent. The endpoint panel becomes a full-width bar above the
grid. The footer is one component and the action one function, so a
further action type is one more branch.

Closes #11

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An admin chooses per remote server whether mcphub authenticates to it over
OAuth with one shared token (the admin authorizes once) or one token per
user (each user authorizes in the portal). mcphub is the OAuth client: the
SDK's auth() does discovery (RFC 9728, RFC 8414/OIDC), dynamic client
registration (RFC 7591) unless an admin set a client, and the authorization
code flow with PKCE S256 and the resource indicator (RFC 8707).

- Flows are stored under the SHA-256 of state, bound to the browser
  session, single use, 10 minute TTL; the callback is
  GET /api/upstream-oauth/callback.
- Registration, tokens and flows are AES-GCM encrypted with the row
  identity as AAD; responses carry only the connection state.
- The upstream pool injects the token with a fetch wrapper, refreshes
  before expiry or on a 401 (one refresh at a time, rotation), and marks
  the token as needing re-authorization on invalid_grant.
- Shared OAuth without a token makes the server unavailable, per-user
  OAuth without one needs setup; mcphub__status tells the agent where to
  authenticate. Per-user OAuth uses per-user process keys and never
  writes the tool catalog.
- Requests to metadata, registration and token endpoints outside the
  server's own origin go through the CIMD safe fetch (now lib/safe-fetch.ts):
  https, public addresses only, no redirects, size and time limited.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
# Conflicts:
#	apps/api/drizzle/meta/0001_snapshot.json
#	apps/api/drizzle/meta/_journal.json
#	apps/web/src/test/fixtures.ts
- Server form: an Authentication choice for remote servers (None, OAuth
  shared, OAuth per user) with an optional client id, write-only client
  secret and scopes.
- Admin server page: an OAuth sign-in section with Authenticate,
  Reconnect and Disconnect for the shared token (or the admin's own one on
  a per-user server, which Test uses).
- Portal: an Authenticate button on the server card and a sign-in block
  on the server page with Reconnect and Disconnect.
- The callback's ?oauth=connected / ?oauth=error result becomes a toast
  once at startup and is removed from the URL.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Architecture gains an Upstream OAuth section with the flow as a sequence
diagram, the trust boundary for metadata-chosen endpoints, and the status
rules; configuration notes the callback under PUBLIC_URL and that
ENCRYPTION_KEY also protects upstream tokens.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A token that lives under two minutes was refreshed on every request; it
now refreshes halfway through. A token without a refresh token is used
until it actually expires. Start and callback failures log the error's
class and the start of its message.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Conflicts with the #9 and #8/#11 branches:
- upstream/context.ts keeps both loadServerContextForUser (OAuth flows) and
  loadProbeContext (admin test). A probe of a per-user OAuth server uses the
  admin's own token under the probe's process key.
- The probe checks the OAuth connection before the per-key probe queue.
- The portal grid's single action slot shows Authenticate when a per-user
  OAuth server needs the user's sign-in.
- One combined migration, 0001_open_issues.sql, replaces the three branch
  migrations and keeps the access_all backfill.
Covers the merge of the #9 probe context with #12: the probe runs under its
own process key but must refresh and read the admin's own token row.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Server icons sit on a white tile in both themes, since many logos (GitHub's)
are black marks that vanished on the dark tile. The portal's Need your input
count now includes per-user OAuth servers waiting for the user's sign-in.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
fix(admin): do not call a server ready while only an admin can unblock it
All checks were successful
CI / check (pull_request) Successful in 6m0s
57599823c5
The admin server list and detail header said Ready for a server with an unset
required instance value or a shared OAuth server nobody signed in to, while
the portal said Waiting on admin. Server summaries now carry setupNeeded and
the badge shows Needs values or Sign-in needed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
marti merged commit 6194f60a3a into develop 2026-11-06 07:16:21 +01:00
marti deleted branch feature/open-issues 2026-11-06 07:16:28 +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!13
No description provided.