design phase 8 c2

Design: Phase 8 C2 — client MCP serving (shims, dial-site routing, /mcp outlet narrowing)

Status: implemented (branch phase-8-c2). Parent design: design-phase-8-client.md § "MCP serving model (C2)". PRD: prd-phase-8-client.md (locked decisions #1/#2/#4). C1: design-phase-8-c1.md (shipped — machines, realtime v0). Verification: shared 33 (dial-site matrix), server 23 (client-config contract incl. secret-leak assertions + 409 matrix), shim E2E scripts/test-hnx-mcp-serve.mjs 5/5 (config fetch → stdio dial → namespaced serving → call round-trip with the resolved secret), smoke [8 C2] block — 192/192 overall.

Scope

C2 moves MCP serving to the client and deletes the proxy/direct split:

1. Model: McpServer.mode is replaced by dialSite: 'auto' | 'client' | 'server'; Credential gains distributable (personal ⇒ always true; global ⇒ admin opt-in, default false). stdio can never be server-dialed (auto ⇒ client; explicit 'server' + stdio → 409 STDIO_REQUIRES_CLIENT).
2. Dial-site derivation (pure, in shared): auto ⇒ client iff every ${cred:NAME} the transport references is distributable (or none), else server. Unit-tested; used by BOTH the server (pool filter + config API) and the shim (informational).
3. packages/mcp-runtime (new): transport-facing pool extracted from McpRegistry — dial upstreams (sse / streamable-http / stdio, the new one), aggregate namespaced tools, route calls. Takes UpstreamDefinition[] with already-resolved transports; placeholder resolution stays with the callers. Server registry keeps config loading + resolution + 2.4 surface and delegates pool ops; the shim reuses the pool directly.
4. GET /api/client/mcp-config?profile=<id>: the shim's config fetch. Custom auth (like the marketplace routes): accepts an api PAT/JWT or a machine PAT (machine-ctl scope — the one REST exception, bound to its machine's owner). Returns resolved transports for client-dialed servers ONLY; server-dialed servers are listed by name with no transport, plus a platform block iff any entry is server-dialed. Secret-leak assertions: non-distributable plaintext never appears.
5. Outlet narrowing: the server registry pools exactly the resolves-to-server rows; /mcp (Streamable HTTP + SSE) keeps its contract unchanged. The shim dials the outlet as ONE passthrough upstream when the profile has server-dialed entries (outlet tools arrive already namespaced — the shim must NOT re-namespace them).
6. hnx mcp serve --profile <id> [--server <url>] [--token <pat>]: the stdio shim. Per agent-tool process; fetches config, dials client-side upstreams via mcp-runtime, dials the outlet if needed, serves one namespaced tool set over stdio (SDK McpServer + StdioServerTransport; logs to stderr only). Secrets exist in process memory only.
7. Install adapters emit one stdio shim entry per profile (absolute hnx path baked via process.argv[1]; --server URL included). Install-time ${cred:NAME} resolution and the "sensitive/0700" handling disappear. Hermes mcp_servers: merge simplified. Codex adapter ships here as the trivial case: ~/.codex/config.toml [mcp_servers.harness-nexus] command/args (Codex is stdio-only — the shim makes it first-class). Codex non-MCP artifacts follow research-phase-3-plugin-targets.md where the format is documented; anything unverified is explicitly deferred (see Out of scope).
8. Emitter emitMode: 'client' | 'server' (env EMITTER_MODE, default flips to client with C2): client mode emits ONE stdio shim entry in .mcp.json (hnx mcp serve …, no PAT env var, no ${cred:NAME} warning — replaced by an "hnx enrolled" warning); server keeps today's output as the no-hnx fallback.
9. Web: MCP form — mode radio → dialSite select with derivation hint; credential form — distributable switch (global rows, admin). The 2.4 status page keeps working (it now reflects the server-dialed set); per-machine MCP status lands with C3.

Migration 0007

• mcp_servers: add dial_site TEXT NOT NULL DEFAULT 'auto', fold mode: direct → 'client', proxy → 'auto', then drop the mode column.
• credentials: add distributable INTEGER NOT NULL DEFAULT 0 (existing global creds stay non-distributable — the locked default).

Dial-site × distributability matrix (normative)

Transport creds referenced	auto	client	server
none	client	client	server
all distributable	client	client	server
any non-distributable	server	409 at use*	server

* an explicit client + non-distributable credential is a config contradiction: rejected at create/update with 409 CREDENTIAL_NOT_DISTRIBUTABLE (the server would have to ship a secret it must not ship). auto silently routes to server — that is the derived default doing its job.

Tasks (dependency order)

1. shared — dial-site.ts (collectPlaceholderNames(transport), resolveDialSite) + schema flips (dialSite, distributable) + requiresDirect deletion. Unit tests incl. the matrix above.
2. core — McpServer.dialSite (drop mode), Credential.distributable.
3. server storage — migration 0007 + both drivers (mode→dial_site, distributable columns).
4. mcp-runtime — new package; UpstreamPool (connect/disconnect/status/ listTools/callTool/listServerTools + stdio transport support + reconcile sync(definitions)); server registry refactored to delegate (public API unchanged for proxy.ts + routes), pooling filter = resolves-to-server.
5. server routes — modules/mcp-servers.ts: dialSite field replaces mode, STDIO_REQUIRES_DIRECT → STDIO_REQUIRES_CLIENT, matrix enforcement, not_proxy RegistryError → not_server_dialed; modules/credentials.ts: distributable handling; modules/client-config.ts (new, custom auth).
6. sdk — field flips + getClientMcpConfig(profileId).
7. cli — src/mcp/serve.ts shim (registry of upstreams + outlet passthrough + stdio server); install resolver drops transport inlining; Hermes adapter simplification; Codex adapter (adapters/codex.ts + registry + TOML add-only merge per ECC pattern); uninstall paths updated.
8. emitter — emitMode (client default) + archive snapshot tests updated.
9. web — form changes (dialSite, distributable).
10. verify — update every mode-sensitive test (emitter.test.ts, scripts/test-hermes-adapter.mjs, test-hnx-uninstall.mjs, smoke); NEW scripts/test-hnx-mcp-serve.mjs — full shim E2E: fixture stdio MCP upstream (SDK server script) + memory server with a personal-cred/dial-client entry + a server-dialed outlet entry → shim serves both, namespaced + passthrough, call round-trips; smoke [8 C2] block asserts the config-API contract (resolved transports only for client-dialed; non-distributable plaintext absent; machine PAT accepted).

Security notes

• The config API is the ONLY REST surface a machine PAT can call, and it is profile-visibility-checked against the machine's owner. Non-distributable plaintext never enters any response — asserted by tests.
• The shim holds resolved secrets in memory only; the sole at-rest client secret remains ~/.hnx/config.json (0600, from C1).
• The outlet keeps its PAT gate and profile routing exactly as in 2.2.

Out of scope (explicit)

• Per-machine MCP status reporting (needs the C3 inventory channel).
• Codex skills/commands/agents artifact formats beyond what the research doc verifies — MCP merge is the C2 deliverable; the rest ships when verified.
• Offline config cache, hybrid connection broker (parent design: deferred).
• Config hot-reload inside a running shim (config applies next session).

Post-ship fix (#7, 2026-09-22): the outlet now accepts machine PATs

Found during #6's rig E2E: a profile whose MCP entry resolves SERVER-dialed (e.g. context7 — global row, header references a non-distributable ${cred:context7-key}) deployed fine to claude-code, CC reported the shim ✔ Connected, but the shim served 0 tools. Chain: the emitter's .mcp.json carries no user PAT by design → hnx mcp serve dials the /mcp?profile=… outlet with the machine's PAT → the root auth hook NULLS machine-ctl tokens (REST blast radius) → the outlet gate 401'd → the passthrough upstream failed, silently yielding an empty tool set.

Fix (mirrors the 3.5 emitter's token acceptance): the outlet gate (mcp/proxy.ts) resolves a Bearer machine-ctl PAT itself into the machine's OWNER, sets req.user, and the ordinary profile-visibility check applies — a machine token gains consumption of its owner's VISIBLE profiles' aggregated MCP, strictly weaker than the /ctl control it already grants. The REST API still rejects machine tokens everywhere else; marketplace-scope PATs remain outlet-refused (URL-capability tokens only).

Tests: server/test/outlet-auth.test.ts (machine PAT passes the gate; foreign personal profile → 403 PROFILE_ENTRY_NOT_ACCESSIBLE; anonymous 401; marketplace PAT 401; REST rejection unchanged) + a smoke [#7] pair. Rig-verified: full stdio handshake through the shim now lists context7__resolve-library-id / context7__query-docs.

Post-ship follow-ups (#7, 2026-09-22): tool schemas, settle race, permission cards

Three follow-ups found while the user E2E'd the outlet through the shim (branch fix/7-outlet-followups, merged (#7)):

1. The outlet dropped tool input schemas. buildSession registered tools through the MCP SDK's registerTool zod-config path; that path re-encodes schemas and silently yields empty ones for passthrough JSON Schema. CC read properties: {}, called the tool with NO arguments, and the upstream rejected it ("CC says no context7"). buildSession is now a low-level Server with explicit ListTools/CallTool handlers that pass registry.listTools()'s inputSchema verbatim. Rule of thumb: the outlet is a PASSTHROUGH — never re-encode an upstream tool schema.
2. Connect settle race (mcp-runtime). connectOne flipped connected BEFORE refreshTools fetched the tool list; a client that lists tools immediately (CC boots that way) could win the race and get 0 tools from a perfectly healthy upstream. Order is now: connect → refreshTools → only then flip to connected.
3. Permission/elicitation cards and turn.cancel. Resolutions were not ring-recorded, so a session switch (resync rebuilds from the ring) resurrected an already-answered card; and chat:turn.cancel left pending cards open, so a turn blocked on a permission could never be stopped from the UI. chat:permission.respond / chat:elicitation.respond now push a permission_resolved / elicitation_resolved ring record after forwarding, and chat:turn.cancel settles every pending card (answering the agent cancelled) before issuing session/cancel.

Tests: cli/test/chat.test.ts (a responded permission rides the ring as permission_resolved; turn.cancel settles pending permission AND elicitation cards, late responds get unknown-permission). Rig-verified: outlet ListTools carries full context7__* schemas, a real call round-trips through the shim, and no-delay probes list both tools every time.