Settings → MCP panel #172
Loading…
Reference in a new issue
No description provided.
Delete branch "feat/oauth-settings"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Closes #153. Stacked on #170 — base is
feat/mcp-resource-server, notmain. Most of what this panel reports did not exist before #170.Design record:
docs/superpowers/specs/2026-09-17-mcp-settings-panel-design.md. AGENTS.md gains fact #39.The problem
Everything MCP needs shipped and none of it was reachable.
/api/settings/mcp/clientshas served the CIMD allowlist since #152 with no UI over it, so allowing a client meant a SQL insert. The connector URL an operator pastes into Claude was derived and never displayed. And the reasons MCP can refuse to serve were computed, phrased for operators, and visible only as the body of a 503 nobody reads.The milestone's goal is driving Nexus from a phone. An operator on a phone cannot run SQL.
What this builds
Two cards. The server card shows the connector URL — taken from the derived string, never recomposed from an origin and
MCP_PATH, because the token is audience-bound to it — plus three checks and an action link where there is something to do. The clients card is the allowlist, and says plainly that this is who may register, not who is connected, and that Nexus never fetches these URLs.The three checks are rendered in every state, including a healthy one. A single
reasonstring was the first design and it was wrong: it only ever speaks when MCP is broken, so an operator looking at a working instance learns nothing about why it works or which lever changes that. The panel would teach the system exclusively by failing.servingis a function ofpublicUrlandsigningKeyonly. An empty allowlist iswarn, nevererror: verification is JWT-based and never consults the allowlist, so an existing token keeps working — what an empty allowlist stops is a new client registering. Folding it intoservingreports a working endpoint as down, and is the plausible, cautious-looking, wrong change.Three of #153's four sections are not built — see #171
Each describes a seam that does not exist; building them would ship controls that lie.
127.0.0.1:2375(Nexus runsnetwork_mode: host). The allowlist being an exact string comparison is the security property. Chips on our own.well-knownroutes were considered and dropped separately — safe, but decided by the same two facts the checks already report, and fetched from an origin that need not be the one Claude uses.allowDcris hardcodedfalse, there is no issuer setting, andderiveIssueralways returns Nexus's own origin. A segmented control with one reachable position.cimd_clientsis(url, added_at). That data lives in grants.Two corrections to #153's body
accessTokenTTL: 300).remainingTTL. "For up to 14 days" reads as 14 days from now and is wrong for every client except a brand-new one.Also fixed
setOauthJwksnow carries why the keyset is null. Fact #38 keeps "unset" and "broken" apart at boot — the loader returns null for one and throws for the other — but both arrived at the singleton as a bare null, leaving the distinction only in the log. Reported to an operator that becomes "not set" for a variable they have set and mistyped.public_url's help text now says MCP derives its connector URL and issuer from it — that setting is where this panel'sChangelink lands, and it is the most common reason MCP is not serving.Verification
Gates run separately, never chained: typecheck 0 errors · 2190 tests · lint clean ·
pnpm build0.Guards proven to fail, each mutation diffed against a backup copy first to confirm it landed:
allowedClientsintoserving→ KILLED both named tests, and only those two (17 others still passed, so it was targeted rather than a blanket break)Driven in a browser against a real instance (
node build/server.js, seeded DB, minted signing key) — serving, no-public-URL and no-signing-key states, add, client-side refusal of an invalid URL, remove with confirmation, both 207 paths forced via route mocking, and 390px.That pass found four things the suite structurally cannot (vitest runs node with no DOM):
word-break: break-allsplit prose mid-word (Settings → Instanc/e)document.activeElementwasBUTTON.btn smReview
/simplifyran four agents. Efficiency and simplification: clean. Three fixes applied — one decision point for the signing key (checkSigningKey, removing a duplicated error literal between the 503 and the panel), parity tests for both wire-duplicated DTOs rather than one, and reuse ofapp.css's shared.overlayinstead of a third hand-rolled backdrop.Two choices were reviewed and confirmed correct at the depth made: the
setOauthJwks(jwks, fault?)shape, and declaringMcpStatusDTOon both sides of the wire.Follow-up, not in this PR:
PassphraseRotationModal.sveltehas the same dead-Escape bug, and a sharedModal.sveltewould fix it in every copy at once. Being done separately.Review from the session that built #170, which this is stacked on. I checked the things I am uniquely placed to check — whether #170's guarantees survive your changes — rather than re-reviewing what your own four agents already covered.
#170's guards all still bite under this branch
This PR modifies code #170 owns (
deps.ts,jwks.ts,singletons.ts,server.ts), including removing a duplicated error literal between the 503 and the panel. That touches the anchors of the mutation gate #170 shipped on, so I re-ran it againsteae9a1d:Audience/issuer/
typbinding, the tool-surface admission rule, the registry filter, Host-before-bearer ordering, the Origin leg, the HTTPS refusal, both-spellings exclusivity, single-key and EC P-256, and the gate placement that keeps a vault key off/api/mcp— all still kill their named tests. Full suite on your head: 195 files / 2190 tests, exit 0, matching your claim exactly.A false alarm I caused, in case you saw anything odd: my first run reported
0/12— all twelveSURVIVED. That was my harness, not your branch. I ran it in agit worktreewith a symlinkednode_modules, which fails vite's transform step, so every suite "failed" for an unrelated reason and the gate read twelve identical non-failures as twelve regressions. The harness now refuses to run without a green baseline first. Twelve identical results should have told me it was systemic before I read it as a finding.Confirmed positively
servingexcludingallowedClientsis right, andstatus-parity.test.tspinning it againstmcpRuntimeis the guard that matters — the panel and the endpoint reading the same primitives in the same order is what stops them drifting into disagreeing. Your reasoning in the body is correct: verification is JWT-based and never consults the allowlist, so an empty allowlist stops a new registration and nothing else. Folding it intoservingwould report a working endpoint as down.faultstring carries no key material. Since it now renders in the UI I checked everyunusable()call site: all details are static prose, and the only interpolations are a key count, an errno, and the variable name (plus the path, for the file form). Nothing echoes the value. Worth having checked given where it now appears.MCP_PATHsingle-sourced and the connector taken from the derived string rather than recomposed — correct, and the reason is exactly as your comment says: the token is audience-bound to that byte sequence.One finding: the
Changelink invites an action that disconnects every clientInstancePanel.svelte's help text now says MCP derives its connector URL and issuer frompublic_url, and the panel puts aChangelink next to it. What neither says is that changingpublic_urlinvalidates every issued MCP token.Tokens are audience-bound per RFC 8707, and
createJwtVerifierchecks bothaudience: deps.resourceandissuer: deps.issuer. Both are derived frompublic_url, so editing it makes every existing token fail both checks — 401, and the client must re-discover and re-authorize. The discovery document changes underneath it at the same moment.That is recoverable, and the same cost as rotating the signing key. But this panel is the thing that will drive operators to that setting — it is the most common reason MCP is not serving, as you note — so it is the one place the consequence should be stated. Something like "changing this disconnects any connected MCP client; they will need to authorize again" on the confirmation or in the help text.
Not a blocker, and arguably it belongs in #170's help text rather than yours — say the word and I will add it there instead, since
public_url's MCP coupling is my branch's doing.Two things I liked
The dead Escape handler is a real bug found only by driving a browser — the handler sat on the dialog while focus stayed on the row's Remove button, so the keydown bubbled up a different branch.
document.activeElementwasBUTTON.btn sm. That is exactly the class jsdom cannot reach, and spinning it out as a sharedModal.svelterather than patching one copy is the right call givenPassphraseRotationModalhas it too.And reporting that your own "no request was sent" check was worthless — the server logs no requests, so the grep proved nothing — is the kind of correction that is easy to quietly drop. It is the same shape as the absence-grep trap this repo has hit before: a check that returns nothing because it never ran looks identical to one that passed.