@geraldmaron/construct 1.4.2 → 1.5.0

package/lib/mcp/transport/auth.mjs

@@ -0,0 +1,238 @@
+/**
+ * lib/mcp/transport/auth.mjs — remote (HTTP) MCP authorization primitives.
+ *
+ * Pure, network-free functions the http entrypoint composes at request time.
+ * Split out from the transport wiring so every rule is unit-testable without a
+ * socket. Four responsibilities, in the order the http entrypoint applies them:
+ *
+ *   1. resolveHttpAuthConfig — reads the http-remote auth config and FAILS
+ *      CLOSED. http mode has no default identity; a missing bearer secret,
+ *      missing audience, or missing allowed-origin list is a startup error,
+ *      never a warning. There is no skip/allow env var — the absence of config
+ *      is the refusal.
+ *   2. validateOrigin / validateHost — DNS-rebinding defense. A browser that
+ *      resolves a trusted name to 127.0.0.1 still sends the attacker's Origin
+ *      and the attacker's Host; both must be on the operator's allowlist or the
+ *      request is rejected before any tool dispatch. Pairs with N7's SSRF work.
+ *   3. verifyBearer — RFC 8707 shaped: the inbound token must carry the exact
+ *      audience (resource indicator) this server was configured for. A token
+ *      minted for a different audience is rejected even if otherwise valid, so a
+ *      token stolen from an upstream service cannot be replayed here.
+ *   4. mintScopedContext — the broker's internal actor context is derived from
+ *      the VERIFIED claims and NEVER contains the inbound token. Token
+ *      passthrough is structurally impossible: the raw bearer is consumed by
+ *      verifyBearer and dropped; nothing downstream is handed the credential.
+ */
+
+import crypto from 'node:crypto';
+
+export class HttpAuthConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'HttpAuthConfigError';
+  }
+}
+
+export class HttpAuthError extends Error {
+  constructor(message, { status = 401 } = {}) {
+    super(message);
+    this.name = 'HttpAuthError';
+    this.status = status;
+  }
+}
+
+// The scoped context carries the token as a symbol-keyed, non-enumerable
+// nothing: there is no field to hold it. mintScopedContext returns a frozen
+// object with only the derived, non-secret identity. A downstream caller that
+// tries to forward `ctx.token` finds `undefined`, and JSON.stringify(ctx) can
+// never leak a credential because none was ever stored.
+
+const CONTEXT_FIELDS = Object.freeze(['actor', 'audience', 'scopes', 'issuedAt', 'source']);
+
+function parseList(raw) {
+  if (Array.isArray(raw)) return raw.map((s) => String(s).trim()).filter(Boolean);
+  if (typeof raw === 'string') return raw.split(',').map((s) => s.trim()).filter(Boolean);
+  return [];
+}
+
+/**
+ * Resolve the http-remote auth config from env, failing closed. Returns a
+ * frozen config when every required field is present; throws
+ * HttpAuthConfigError otherwise. The http entrypoint calls this BEFORE binding
+ * a socket so a misconfigured server never accepts a single request.
+ *
+ * Required (no defaults, no skip path):
+ *   CONSTRUCT_MCP_HTTP_BEARER_SECRET — HMAC secret the inbound token is signed with
+ *   CONSTRUCT_MCP_HTTP_AUDIENCE      — this server's resource indicator (RFC 8707)
+ *   CONSTRUCT_MCP_HTTP_ALLOWED_ORIGINS — comma list of allowed Origin header values
+ * Optional:
+ *   CONSTRUCT_MCP_HTTP_ALLOWED_HOSTS — comma list of allowed Host header values
+ *                                      (defaults to localhost forms)
+ *   CONSTRUCT_MCP_HTTP_HOST / _PORT   — bind address (defaults to 127.0.0.1)
+ */
+export function resolveHttpAuthConfig(env = process.env) {
+  const missing = [];
+  const bearerSecret = env.CONSTRUCT_MCP_HTTP_BEARER_SECRET;
+  const audience = env.CONSTRUCT_MCP_HTTP_AUDIENCE;
+  const allowedOrigins = parseList(env.CONSTRUCT_MCP_HTTP_ALLOWED_ORIGINS);
+
+  if (!bearerSecret) missing.push('CONSTRUCT_MCP_HTTP_BEARER_SECRET');
+  if (!audience) missing.push('CONSTRUCT_MCP_HTTP_AUDIENCE');
+  if (allowedOrigins.length === 0) missing.push('CONSTRUCT_MCP_HTTP_ALLOWED_ORIGINS');
+
+  if (missing.length > 0) {
+    throw new HttpAuthConfigError(
+      `http-remote MCP refuses to start: missing required auth config (${missing.join(', ')}). `
+      + 'HTTP transport has no default identity; there is no skip flag — supply the config or run stdio-local.',
+    );
+  }
+
+  const allowedHosts = parseList(env.CONSTRUCT_MCP_HTTP_ALLOWED_HOSTS);
+  const bindHost = env.CONSTRUCT_MCP_HTTP_HOST || '127.0.0.1';
+  const bindPort = Number(env.CONSTRUCT_MCP_HTTP_PORT) || 7391;
+
+  return Object.freeze({
+    bearerSecret,
+    audience,
+    allowedOrigins: Object.freeze(allowedOrigins),
+    allowedHosts: Object.freeze(allowedHosts.length > 0 ? allowedHosts : defaultAllowedHosts(bindHost, bindPort)),
+    bindHost,
+    bindPort,
+  });
+}
+
+// Localhost-bind is the default; the default host allowlist is exactly the
+// loopback forms for the bind address so a request whose Host names a public
+// interface is rejected unless the operator explicitly widens allowedHosts.
+
+function defaultAllowedHosts(bindHost, bindPort) {
+  const names = ['localhost', '127.0.0.1', '[::1]', bindHost];
+  const out = [];
+  for (const n of names) {
+    out.push(n);
+    out.push(`${n}:${bindPort}`);
+  }
+  return [...new Set(out)];
+}
+
+/**
+ * Validate the inbound Origin against the allowlist. A missing Origin is
+ * allowed only for non-browser clients (no Origin header at all); a present
+ * Origin that is not on the allowlist is a DNS-rebinding attempt and is
+ * rejected. Returns true when the request may proceed.
+ */
+export function validateOrigin(origin, config) {
+  if (origin == null || origin === '') return true;
+  return config.allowedOrigins.includes(origin);
+}
+
+/**
+ * Validate the inbound Host header against the allowlist. A rebinding attack
+ * resolves a trusted name to a loopback IP but still carries the attacker's
+ * Host value; requiring an exact allowlist match closes that path. A missing
+ * Host is rejected — a well-formed HTTP/1.1 request always carries one.
+ */
+export function validateHost(host, config) {
+  if (host == null || host === '') return false;
+  return config.allowedHosts.includes(host);
+}
+
+// Constant-time compare so a token-signature check cannot be turned into a
+// timing oracle. Both operands are hex/base64url strings of the same length
+// when the request is well-formed; a length mismatch short-circuits to false
+// without leaking where the difference is.
+
+function timingSafeEqualStr(a, b) {
+  const ab = Buffer.from(String(a));
+  const bb = Buffer.from(String(b));
+  if (ab.length !== bb.length) return false;
+  return crypto.timingSafeEqual(ab, bb);
+}
+
+function b64urlDecode(seg) {
+  return Buffer.from(seg.replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8');
+}
+
+function b64urlEncode(buf) {
+  return Buffer.from(buf).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/**
+ * Mint an internal HMAC bearer for tests and local tooling: a compact
+ * `<payloadB64url>.<sigB64url>` token whose payload is a JSON claims object —
+ * the token shape verifyBearer accepts. Not a full JWT — deliberately minimal
+ * so the audience/expiry/signature semantics are auditable in one file.
+ */
+export function mintInternalBearer(claims, secret) {
+  const payload = b64urlEncode(JSON.stringify(claims));
+  const sig = b64urlEncode(crypto.createHmac('sha256', secret).update(payload).digest());
+  return `${payload}.${sig}`;
+}
+
+/**
+ * Verify an inbound bearer against the configured secret AND audience. Order:
+ * shape → signature → expiry → audience. Returns the verified claims on
+ * success; throws HttpAuthError (401) otherwise. The audience check is the
+ * resource-indicator binding: a token minted for a different resource is
+ * rejected here, which is what makes a stolen upstream token un-replayable.
+ *
+ * The returned claims are DATA ONLY. The caller passes them to
+ * mintScopedContext; the raw token string is never returned and never stored.
+ */
+export function verifyBearer(rawAuthHeader, config, { now = () => Date.now() } = {}) {
+  if (typeof rawAuthHeader !== 'string' || !rawAuthHeader.startsWith('Bearer ')) {
+    throw new HttpAuthError('missing or malformed Authorization: Bearer header');
+  }
+  const token = rawAuthHeader.slice('Bearer '.length).trim();
+  const parts = token.split('.');
+  if (parts.length !== 2) throw new HttpAuthError('malformed bearer token');
+
+  const [payloadB64, sigB64] = parts;
+  const expectedSig = b64urlEncode(crypto.createHmac('sha256', config.bearerSecret).update(payloadB64).digest());
+  if (!timingSafeEqualStr(sigB64, expectedSig)) {
+    throw new HttpAuthError('bearer signature does not verify');
+  }
+
+  let claims;
+  try {
+    claims = JSON.parse(b64urlDecode(payloadB64));
+  } catch {
+    throw new HttpAuthError('bearer payload is not valid JSON');
+  }
+
+  if (typeof claims.exp === 'number' && now() >= claims.exp * 1000) {
+    throw new HttpAuthError('bearer token expired');
+  }
+
+  const aud = Array.isArray(claims.aud) ? claims.aud : (claims.aud == null ? [] : [claims.aud]);
+  if (!aud.includes(config.audience)) {
+    throw new HttpAuthError(
+      `bearer audience mismatch: token is for ${JSON.stringify(claims.aud)} but this server is ${JSON.stringify(config.audience)}`,
+      { status: 403 },
+    );
+  }
+
+  return claims;
+}
+
+/**
+ * Mint the broker's internal actor context from VERIFIED claims. Token
+ * passthrough is structurally impossible: the inbound token never reaches this
+ * function — only the already-verified claims do — and the returned object has
+ * no field capable of holding a credential.
+ *
+ * The result is frozen and carries exactly CONTEXT_FIELDS. A read of a token
+ * off it (ctx.token, ctx.bearer, ctx.authorization) yields undefined.
+ */
+export function mintScopedContext(claims, config, { now = () => Date.now() } = {}) {
+  const ctx = {
+    actor: claims.sub || claims.actor || 'http-remote-unknown',
+    audience: config.audience,
+    scopes: Array.isArray(claims.scopes) ? [...claims.scopes] : parseList(claims.scope),
+    issuedAt: new Date(now()).toISOString(),
+    source: 'http-remote',
+  };
+  return Object.freeze(ctx);
+}
+
+export { CONTEXT_FIELDS };

package/lib/mcp/transport/http.mjs

@@ -0,0 +1,136 @@
+/**
+ * lib/mcp/transport/http.mjs — http-remote MCP entrypoint (opt-in, fail-closed).
+ *
+ * The network transport. Every guard the stdio path does not need lives here,
+ * applied in order per request before the MCP SDK transport ever sees the body:
+ *
+ *   1. Host allowlist   — DNS-rebinding defense (a rebound name still carries
+ *                         the attacker's Host).
+ *   2. Origin allowlist — DNS-rebinding defense for browser callers.
+ *   3. Bearer + audience — RFC 8707 resource-indicator binding; a token for a
+ *                         different audience is rejected.
+ *   4. Scoped-context mint — the broker actor context is derived from verified
+ *                         claims; the inbound token is dropped and never
+ *                         forwarded downstream (token passthrough impossible).
+ *
+ * Startup itself fails closed: constructHttpServer resolves the auth config
+ * first (resolveHttpAuthConfig throws HttpAuthConfigError on any missing field)
+ * and binds to localhost by default. TLS is expected to be terminated by a
+ * reverse proxy in front of this server; the localhost bind default keeps the
+ * cleartext hop on the loopback interface. See docs follow-up in the bead.
+ *
+ * authorizeHttpRequest is the pure decision function — headers in, a decision
+ * or a thrown HttpAuthError out — so the whole authorization pipeline is
+ * unit-testable without opening a socket. startHttpTransport wires it to a
+ * real node:http server only at the entrypoint.
+ */
+
+import http from 'node:http';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import {
+  resolveHttpAuthConfig,
+  validateOrigin,
+  validateHost,
+  verifyBearer,
+  mintScopedContext,
+  HttpAuthError,
+} from './auth.mjs';
+
+/**
+ * Resolve config and refuse to continue if auth is unconfigured. Callers that
+ * want to know whether http mode CAN start call this and catch
+ * HttpAuthConfigError; the http entrypoint calls it before binding a socket.
+ */
+export function constructHttpServer(env = process.env) {
+  return resolveHttpAuthConfig(env);
+}
+
+/**
+ * Decide whether a single inbound HTTP request may reach tool dispatch. Runs
+ * the four guards in order and throws HttpAuthError (with a 401/403 status) on
+ * the first failure. On success returns { context } — the scoped internal actor
+ * context minted from verified claims, with NO token field.
+ *
+ * @param {object} headers - lowercased request headers (host, origin, authorization)
+ * @param {object} config  - the frozen config from resolveHttpAuthConfig
+ */
+export function authorizeHttpRequest(headers, config, { now = () => Date.now() } = {}) {
+  const host = headers.host ?? headers.Host;
+  if (!validateHost(host, config)) {
+    throw new HttpAuthError(`host not allowed: ${JSON.stringify(host)}`, { status: 421 });
+  }
+
+  const origin = headers.origin ?? headers.Origin;
+  if (!validateOrigin(origin, config)) {
+    throw new HttpAuthError(`origin not allowed: ${JSON.stringify(origin)}`, { status: 403 });
+  }
+
+  const authHeader = headers.authorization ?? headers.Authorization;
+  const claims = verifyBearer(authHeader, config, { now });
+
+  const context = mintScopedContext(claims, config, { now });
+  return { context };
+}
+
+// The WWW-Authenticate challenge names the resource metadata location per the
+// MCP authorization guidance so a compliant client can discover how to obtain
+// a correctly-scoped token instead of guessing.
+
+function writeAuthError(res, err, config) {
+  const status = err instanceof HttpAuthError ? err.status : 401;
+  res.statusCode = status;
+  res.setHeader('Content-Type', 'application/json');
+  if (status === 401) {
+    res.setHeader('WWW-Authenticate', `Bearer realm="construct-mcp", audience="${config.audience}"`);
+  }
+  res.end(JSON.stringify({ error: err.message }));
+}
+
+/**
+ * Start a real http-remote MCP server bound to localhost by default. Fails
+ * closed at the first line: a missing auth config throws before listen().
+ * Returns { server, transport, config } once listening.
+ *
+ * Each request is authorized by authorizeHttpRequest first; only an authorized
+ * request is handed to the SDK transport, and the scoped context (never the
+ * token) is attached for the dispatch layer to read.
+ */
+export async function startHttpTransport(mcpServer, { env = process.env } = {}) {
+  const config = resolveHttpAuthConfig(env);
+
+  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+  await mcpServer.connect(transport);
+
+  const httpServer = http.createServer(async (req, res) => {
+    let decision;
+    try {
+      decision = authorizeHttpRequest(req.headers, config);
+    } catch (err) {
+      writeAuthError(res, err, config);
+      return;
+    }
+
+    // The verified, token-free scoped context rides on the request object for
+    // the dispatch layer; the raw Authorization header is stripped here, so
+    // nothing downstream can forward the inbound credential.
+
+    req.constructScopedContext = decision.context;
+    delete req.headers.authorization;
+    delete req.headers.Authorization;
+
+    try {
+      await transport.handleRequest(req, res);
+    } catch (err) {
+      if (!res.headersSent) {
+        res.statusCode = 500;
+        res.end(JSON.stringify({ error: err?.message || 'internal error' }));
+      }
+    }
+  });
+
+  await new Promise((resolveListen) => {
+    httpServer.listen(config.bindPort, config.bindHost, resolveListen);
+  });
+
+  return { server: httpServer, transport, config };
+}

package/lib/mcp/transport/mode.mjs

@@ -0,0 +1,31 @@
+/**
+ * lib/mcp/transport/mode.mjs — MCP transport-mode resolution.
+ *
+ * Two explicit, non-overlapping modes with separate entrypoints:
+ *   stdio-local — the default. A local subprocess spoken to over stdin/stdout;
+ *                 identity comes from the local OS session, so no network authn.
+ *                 Behavior is unchanged from the pre-separation server.
+ *   http-remote — opt-in only, via CONSTRUCT_MCP_TRANSPORT=http (or =http-remote).
+ *                 A network surface, so it REQUIRES authn config and refuses to
+ *                 start without it (see resolveHttpAuthConfig).
+ *
+ * There is no auto-detection and no implicit http: a server started with no
+ * transport env is always stdio-local. Selecting http is a deliberate operator
+ * act, and that act carries the fail-closed auth requirement with it.
+ */
+
+export const TRANSPORT_STDIO = 'stdio-local';
+export const TRANSPORT_HTTP = 'http-remote';
+
+export const TRANSPORT_MODE_ENV_KEY = 'CONSTRUCT_MCP_TRANSPORT';
+
+/**
+ * Resolve the transport mode from env. Anything but an explicit http selection
+ * resolves to stdio-local, so a typo or empty value degrades to the safe local
+ * mode rather than silently exposing a network surface.
+ */
+export function resolveTransportMode(env = process.env) {
+  const raw = String(env?.[TRANSPORT_MODE_ENV_KEY] || '').trim().toLowerCase();
+  if (raw === 'http' || raw === 'http-remote' || raw === 'streamable-http') return TRANSPORT_HTTP;
+  return TRANSPORT_STDIO;
+}

package/lib/mcp/transport/stdio.mjs

@@ -0,0 +1,22 @@
+/**
+ * lib/mcp/transport/stdio.mjs — stdio-local MCP entrypoint.
+ *
+ * The default transport, factored out of server.mjs so the http entrypoint can
+ * live beside it under one mode selector. Behavior is byte-for-byte the same as
+ * the original inline `new StdioServerTransport(); await server.connect(...)`:
+ * a local subprocess over stdin/stdout, no network surface, no authn — identity
+ * is the local OS session. The server object (tool catalog + dispatch) is
+ * passed in already built, so this module never re-registers a handler.
+ */
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+/**
+ * Connect the pre-built MCP server to a stdio transport. Resolves once the
+ * transport is connected; the process then stays alive serving requests.
+ */
+export async function startStdioTransport(server) {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  return transport;
+}

package/lib/mcp-catalog.json

@@ -6,11 +6,11 @@
       "name": "Context7",
       "category": "core",
       "description": "Library and framework documentation lookup. Agents use this before writing code against any dependency.",
-      "package": "@upstash/context7-mcp@latest",
+      "package": "@upstash/context7-mcp@3.2.2",
       "command": "npx",
       "args": [
         "-y",
-        "@upstash/context7-mcp@latest"
+        "@upstash/context7-mcp@3.2.2"
       ],
       "env": {},
       "requiredEnv": [],
@@ -31,11 +31,11 @@
       "name": "Sequential Thinking",
       "category": "optional",
       "description": "Structured multi-step reasoning chains. Helps with complex planning and analysis.",
-      "package": "@modelcontextprotocol/server-sequential-thinking",
+      "package": "@modelcontextprotocol/server-sequential-thinking@2026.7.4",
       "command": "npx",
       "args": [
         "-y",
-        "@modelcontextprotocol/server-sequential-thinking"
+        "@modelcontextprotocol/server-sequential-thinking@2026.7.4"
       ],
       "env": {},
       "requiredEnv": [],

package/lib/mcp-manager.mjs

@@ -29,8 +29,15 @@ import {
 } from './mcp-platform-config.mjs';
 import { getMcpById as getMcpByIdFromRegistry, loadPluginRegistry } from './plugin-registry.mjs';
 
-function getClaudeSettingsPath() {
-  return join(homedir(), '.claude', 'settings.json');
+// Claude Code does not read MCP server definitions from ~/.claude/settings.json
+// (confirmed against code.claude.com/docs/en/mcp's installation-scopes table and
+// code.claude.com/docs/en/managed-mcp, plus live `claude mcp list`/`claude mcp get`
+// repro on v2.1.201 — construct-ranh). User-scope servers live in the top-level
+// `mcpServers` object of ~/.claude.json; settings.json carries only policy keys
+// (allowedMcpServers, deniedMcpServers, etc.) and hooks/permissions, untouched here.
+
+function getClaudeUserConfigPath() {
+  return join(homedir(), '.claude.json');
 }
 
 // VS Code's "MCP: Open User Configuration" edits a per-profile mcp.json keyed
@@ -196,20 +203,24 @@ function getConfiguredEnvValues(mcp) {
   return values;
 }
 
-function loadSettings() {
-  const claudeSettingsPath = getClaudeSettingsPath();
-  if (!existsSync(claudeSettingsPath)) return {};
+function loadClaudeUserConfig() {
+  const claudeUserConfigPath = getClaudeUserConfigPath();
+  if (!existsSync(claudeUserConfigPath)) return {};
   try {
-    return JSON.parse(readFileSync(claudeSettingsPath, 'utf8'));
+    return JSON.parse(readFileSync(claudeUserConfigPath, 'utf8'));
   } catch {
     return {};
   }
 }
 
-function saveSettings(settings) {
-  const claudeSettingsPath = getClaudeSettingsPath();
-  mkdirSync(dirname(claudeSettingsPath), { recursive: true });
-  writeFileSync(claudeSettingsPath, JSON.stringify(settings, null, 2) + '\n');
+// Rewrites the whole file: ~/.claude.json also holds unrelated Claude Code
+// runtime state (oauthAccount, projects, numStartups, ...). Only the top-level
+// `mcpServers` key is ever touched here; every other key round-trips untouched.
+
+function saveClaudeUserConfig(config) {
+  const claudeUserConfigPath = getClaudeUserConfigPath();
+  mkdirSync(dirname(claudeUserConfigPath), { recursive: true });
+  writeFileSync(claudeUserConfigPath, JSON.stringify(config, null, 2) + '\n');
 }
 
 function loadOpenCodeConfig() {
@@ -226,12 +237,12 @@ function getMcpById(id) {
 
 function getInstalledMcps() {
   const registry = loadPluginRegistry({ cwd: process.cwd(), homeDir: homedir() });
-  const settings = loadSettings();
+  const claudeUserConfig = loadClaudeUserConfig();
   const oc = loadOpenCodeConfig();
   const codexConfig = readCodexConfig();
   const codexServers = Array.from(codexConfig.matchAll(/^\[mcp_servers\.("?)([^"\]\n]+)\1\]/gm)).map((match) => match[2]);
   const set = new Set([
-    ...Object.keys(settings.mcpServers ?? {}),
+    ...Object.keys(claudeUserConfig.mcpServers ?? {}),
     ...Object.keys(oc.mcp ?? {}),
     ...codexServers,
   ]);
@@ -300,7 +311,7 @@ export function cmdMcpList() {
 
 /**
  * construct mcp add <id>
- * Interactive Guided Wizard: collect required env vars and write to settings.json.
+ * Interactive Guided Wizard: collect required env vars and write to ~/.claude.json.
  */
 export async function cmdMcpAdd(id) {
   const mcp = getMcpById(id);
@@ -412,15 +423,15 @@ export async function cmdMcpAdd(id) {
     resolvedValues.MEMORY_PORT = process.env.MEMORY_PORT || '8765';
   }
 
-  // Write to Claude settings
-  const settings = loadSettings();
-  if (!settings.mcpServers) settings.mcpServers = {};
+  // Write to Claude Code's user-scope MCP config (~/.claude.json), not settings.json
+  const claudeUserConfig = loadClaudeUserConfig();
+  if (!claudeUserConfig.mcpServers) claudeUserConfig.mcpServers = {};
   if (isManagedOnHost(mcp, 'claude')) {
-    settings.mcpServers[id] = buildClaudeMcpEntry(id, mcp, resolvedValues, { auth: authMode });
+    claudeUserConfig.mcpServers[id] = buildClaudeMcpEntry(id, mcp, resolvedValues, { auth: authMode });
   } else {
-    delete settings.mcpServers[id];
+    delete claudeUserConfig.mcpServers[id];
   }
-  saveSettings(settings);
+  saveClaudeUserConfig(claudeUserConfig);
 
   // Write to OpenCode config
   const oc = loadOpenCodeConfig();
@@ -484,13 +495,13 @@ export async function cmdMcpAdd(id) {
  * construct mcp remove <id>
  */
 export function cmdMcpRemove(id) {
-  const settings = loadSettings();
+  const claudeUserConfig = loadClaudeUserConfig();
   const openCodeState = readOpenCodeConfig();
   const oc = openCodeState.config ?? {};
   const openCodeId = getOpenCodeMcpId(id);
   const vscodePaths = getVSCodeUserMcpPaths();
   const cursorPath = getCursorMcpPath();
-  const hasClaudeEntry = Boolean(settings.mcpServers?.[id]);
+  const hasClaudeEntry = Boolean(claudeUserConfig.mcpServers?.[id]);
   const hasOpenCodeEntry = Boolean(oc.mcp?.[openCodeId] || oc.mcp?.[id] || (id === 'memory' && oc.mcp?.cass));
   const hasCodexEntry = readCodexConfig().includes(`[mcp_servers.${id}]`) || readCodexConfig().includes(`[mcp_servers.${tomlString(id)}]`);
   const hasVscodeEntry = vscodePaths.some((p) => mcpFileHasEntry(p, 'servers', id));
@@ -503,8 +514,8 @@ export function cmdMcpRemove(id) {
   const mcp = getMcpById(id);
   const name = mcp?.name ?? id;
 
-  if (settings.mcpServers) delete settings.mcpServers[id];
-  saveSettings(settings);
+  if (claudeUserConfig.mcpServers) delete claudeUserConfig.mcpServers[id];
+  saveClaudeUserConfig(claudeUserConfig);
 
   if (oc.mcp) {
     delete oc.mcp[openCodeId];

package/lib/mcp-platform-config.mjs

@@ -7,6 +7,7 @@
  */
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { memoryPort } from "./home-namespace.mjs";
 
 const ROOT_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 
@@ -31,7 +32,11 @@ function resolveTemplateObject(input, resolvedValues, fallback) {
 // A value is unsafe to write into a host MCP env block when it is an unresolved
 // `__NAME__` template or a 1Password `op://` reference. The op:// form must never
 // be written verbatim: a host that cannot run `op read` would pass the literal
-// reference to the child process, and writing it persists secret topology on disk.
+// reference to the child process, and writing it persists secret topology into a
+// host-readable MCP config file on disk (claude_desktop_config.json, OpenCode
+// settings) — a different sink from Construct's own audit JSONL, where recording
+// the ref (not the value) is the accepted design (secret-audit-wiring.mjs,
+// remediation plan Epic 6, construct-trxz.6).
 
 function isUnwritableEnvValue(value) {
   return typeof value !== "string" || value.includes("__") || value.startsWith("op://");
@@ -58,8 +63,12 @@ const SECRET_REF = {
 // A stdio MCP env value that is a whole-value secret template (`__NAME__` as the
 // entire string) is a credential carrier: emit the host's env-reference form so the
 // live value never lands on disk, exactly as the remote `headers` path does. Claude
-// Code (`${VAR}`), VS Code (`${env:VAR}`), and OpenCode (`{env:VAR}`) each expand
-// their reference syntax inside a stdio env block, and the child still inherits the
+// Code (`${VAR}`, documented at code.claude.com/docs/en/mcp under "Environment
+// variable expansion in .mcp.json," confirmed 2026-07 for construct-trxz.12 --
+// expansion applies to the file format, independent of which host-config file
+// Construct currently targets; see construct-ranh) and OpenCode (`{env:VAR}`, live-
+// validated against the installed binary for construct-trxz.12) each expand their
+// reference syntax inside a stdio env block, and the child still inherits the
 // resolved env from the parent (config.env -> loadConstructEnv -> process.env) as a
 // backstop. A composed value (a URL with an embedded port template, a plain literal)
 // is not a secret and is materialized so the child receives the concrete string;
@@ -67,11 +76,21 @@ const SECRET_REF = {
 
 const WHOLE_SECRET_TEMPLATE = /^__([A-Z0-9_]+)__$/;
 
-function buildLocalEnvironment(mcpDef, resolvedValues, secretRef) {
+// VS Code's own MCP configuration reference (code.visualstudio.com/docs/agents/
+// reference/mcp-configuration, confirmed 2026-07 for construct-trxz.12) documents only
+// `${workspaceFolder}`-style predefined variables and `${input:id}` prompts for
+// mcp.json — no `${env:VAR}` substitution is listed as supported. Writing `${env:NAME}`
+// into a VS Code stdio `env` block would hand the child process that literal,
+// unexpanded string instead of the credential, so VS Code's local/stdio env keeps the
+// Codex-style materialize-or-strip treatment (flipWholeSecret: false) rather than the
+// reference flip Claude and OpenCode confirm via their own documented `${VAR}` /
+// `{env:VAR}` expansion.
+
+function buildLocalEnvironment(mcpDef, resolvedValues, secretRef, { flipWholeSecret = true } = {}) {
   const source = mcpDef.env ?? {};
   const out = {};
   for (const [key, raw] of Object.entries(source)) {
-    const whole = typeof raw === "string" ? raw.match(WHOLE_SECRET_TEMPLATE) : null;
+    const whole = flipWholeSecret && typeof raw === "string" ? raw.match(WHOLE_SECRET_TEMPLATE) : null;
     if (whole) {
       out[key] = secretRef(whole[1]);
       continue;
@@ -86,10 +105,15 @@ function buildRemoteHeaders(mcpDef, secretRef) {
   return resolveTemplateObject(mcpDef.headers ?? {}, {}, secretRef);
 }
 
+// The memory bridge URL is templated from MEMORY_PORT; when a caller does not supply
+// one (an entry built outside a populated config.env), fall back to the derived per-home
+// port from home-namespace, never the dead legacy 8765 literal that produced the
+// split-brain against the actually-allocated port.
+
 function withMemoryDefaults(id, values) {
   if (id !== "memory") return values;
   if (values.MEMORY_PORT) return values;
-  return { ...values, MEMORY_PORT: "8765" };
+  return { ...values, MEMORY_PORT: String(memoryPort()) };
 }
 
 // auth defaults to "oauth": remote MCP servers (e.g. GitHub's hosted server) are
@@ -115,7 +139,7 @@ export function buildClaudeMcpEntry(id, mcpDef, resolvedValues = {}, { host = "c
     };
   }
 
-  const env = buildLocalEnvironment(mcpDef, values, secretRef);
+  const env = buildLocalEnvironment(mcpDef, values, secretRef, { flipWholeSecret: host !== "vscode" });
   return {
     command: mcpDef.command,
     args: resolveArgs(mcpDef.args, values),