fix(mcp): no file text in sync errors, follow relocated config dirs, docs and Settings polish (#521 review)

Maintainer merge-time fixes for the MCP server sync (opt-in mcpSyncEnabled, synced, default OFF).

M1, parse errors echoed config text (secrets included) into the HTTP response and Settings:
smol-toml's TomlError carries a code frame of the offending lines and V8's JSON "Unexpected
token" errors quote source. Both catch sites now go through describeMcpSyncError(): a parse
failure is reported by line/column only ("not valid TOML (line 3, column 21)", "not valid
JSON"), an errno failure by Node's own message (code, syscall, path), the module's own
messages via a McpConfigError class, anything else as "unexpected error". Tests put a secret
on the broken line (TOML, both JSON message shapes, and a write refused at the re-parse that
would have quoted a copied server's env) and assert it is absent from the result and from the
route's response body; they fail against the old code.

M2, CODEX_HOME / CLAUDE_CONFIG_DIR / XDG_CONFIG_HOME were ignored, so a sync could create a
file the CLI never reads and report success: new optional registry field
capabilities.mcpConfig.relocation { envVar, path } (registry data, no id branch; schema
reuses the env-name and no-traversal path rules). Declared for claude (CLAUDE_CONFIG_DIR,
checked in the 2.1.289 binary), codex (CODEX_HOME), opencode (XDG_CONFIG_HOME) and gemini
(GEMINI_CLI_HOME, gemini-cli paths.ts); antigravity follows $HOME only (agy 1.1.12 has no
relocation var). Resolved from the server process env at call time: absolute moves the file,
empty means unset, anything else reports the target with the new status "skipped" plus the
reason and writes nothing. Dedupe is now by resolved file. When a caller overrides `home`
without passing `env`, process.env is not consulted, and the route tests clear those vars so
a CI runner's XDG_CONFIG_HOME can never aim a write outside the temp HOME.

M3, feature undocumented: CLAUDE.md Key Patterns paragraph (opt-in, admin-only, additive
only, backups, re-parse validation, 0600 for copied secrets, names-only responses with
position-only parse errors, capabilities.mcpConfig and relocation), a Settings-Reference row
in the wiki, and docs/cli-registry.md + docs/api-reference.md updated for relocation, the
"skipped" status and the error policy.

Nits:
- N1 Preview/Sync before Save: the UI remembers the saved value on open and says "Save
  settings to turn MCP sync on first" instead of calling the routes; the 403 message also
  says to turn it on and save.
- N2 non-admins in multi-user mode: _applyMcpSyncAdminGate() hides the whole MCP group, called
  from applyMcpSyncVisibility() and the codeman:me event like the CLI-management gate.
- N3 scope chip says "synced".
- N4 "(1 servers)" pluralised; the unsupported list only names installed CLIs (route test
  pins it with a per-test installed set).
- N5 McpSyncResult / McpSyncTargetResult moved to src/types/mcp-sync.ts (barrel export); only
  the route imported them, so no churn.

Verified with an isolated instance (throwaway HOME, own instance and tmux socket) and
Playwright: chip, save-first message, preview rendering and the admin gate.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>

src/config/cli-registry/schema.ts

@@ -28,6 +28,14 @@ const envName = z
   .regex(/^[A-Z_][A-Z0-9_]*$/, 'env var name must be UPPER_SNAKE_CASE')
   .max(64);
 
+/** A relative file path with no traversal or odd characters (MCP sync writes to it). */
+const mcpRelativePath = z
+  .string()
+  .min(1)
+  .max(100)
+  .regex(/^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/)
+  .refine((v) => !v.split('/').includes('..'), 'must not contain ..');
+
 /**
  * A shell-safe bare word: no space, quote, backtick, `$`, `;`, `&`, `|`, `<`, `>`, parens,
  * braces, newline or backslash. Every LITERAL in the launch spec (base command, flag names,
@@ -382,12 +390,7 @@ const capabilitiesSchema = z
     mcpConfig: z
       .object({
         // Home-relative, no traversal: sync writes to this path.
-        path: z
-          .string()
-          .min(1)
-          .max(100)
-          .regex(/^[A-Za-z0-9._-]+(\/[A-Za-z0-9._-]+)*$/)
-          .refine((v) => !v.split('/').includes('..'), 'must not contain ..'),
+        path: mcpRelativePath,
         // Every value must be a known McpConfigFormat (types.ts); mcp-sync.ts's dialect table is
         // keyed by the same type, so an adapter-less format fails to compile there.
         format: z.enum([
@@ -397,6 +400,9 @@ const capabilitiesSchema = z
           'opencode-json',
           'antigravity-json',
         ] as const satisfies readonly McpConfigFormat[]),
+        // The env var the CLI reads to move the file, and the path under it (same no-traversal
+        // rule: sync writes there too). Resolved from the server env at call time, never here.
+        relocation: z.object({ envVar: envName, path: mcpRelativePath }).strict().optional(),
       })
       .strict()
       .optional(),

src/config/cli-registry/stock.ts

@@ -307,7 +307,12 @@ const CLAUDE: CliEntry = {
       'CLAUDE_CONFIG_DIR',
     ],
     gates: { nameFlag: { minVersion: '2.1.224', failClosed: true } },
-    mcpConfig: { path: '.claude.json', format: 'claude-json' },
+    // claude reads `$CLAUDE_CONFIG_DIR/.claude.json` when that is set (checked in 2.1.289).
+    mcpConfig: {
+      path: '.claude.json',
+      format: 'claude-json',
+      relocation: { envVar: 'CLAUDE_CONFIG_DIR', path: '.claude.json' },
+    },
     // Custom Model Endpoint Profiles (docs/custom-model-endpoints-plan.md) — verified by hand against a real
     // llama.cpp server. Claude reads these at process start only, so switching requires a
     // respawn, never a live hot-swap.
@@ -488,7 +493,12 @@ const OPENCODE: CliEntry = {
     ...agentDefaults(),
     altScreen: 'strip-mux-only',
     echo: { policy: 'buffer', anchor: { kind: 'cursor' }, predictProfile: undefined },
-    mcpConfig: { path: '.config/opencode/opencode.json', format: 'opencode-json' },
+    // opencode's global config dir is xdg-basedir's `$XDG_CONFIG_HOME/opencode`.
+    mcpConfig: {
+      path: '.config/opencode/opencode.json',
+      format: 'opencode-json',
+      relocation: { envVar: 'XDG_CONFIG_HOME', path: 'opencode/opencode.json' },
+    },
     // Verified by hand against a real llama.cpp server. Reuses the SAME env var opencode's
     // own `env.configContentVar` already declares — the builder in custom-model-injection.ts
     // must merge into whatever opencode config Codeman would otherwise send, not clobber it.
@@ -632,7 +642,11 @@ const CODEX: CliEntry = {
     // `dangerouslyBypassApprovals` on the wire), so it is the one that would have caught a
     // regression; `schema.ts` now rejects a name that is not a declared param.
     privilegedParams: [{ param: 'bypassApprovals', clampTo: false }],
-    mcpConfig: { path: '.codex/config.toml', format: 'codex-toml' },
+    mcpConfig: {
+      path: '.codex/config.toml',
+      format: 'codex-toml',
+      relocation: { envVar: 'CODEX_HOME', path: 'config.toml' },
+    },
     // Verified by hand against a real llama.cpp server. Written to an isolated CODEX_HOME
     // so the user's real ~/.codex/config.toml is never touched.
     customModelInjection: {
@@ -734,7 +748,12 @@ const GEMINI: CliEntry = {
     // MATERIALIZE a config (not just touch an already-sent one) or a non-granted owner who
     // sends no geminiConfig at all would still get yolo for free.
     privilegedParams: [{ param: 'approvalMode', clampTo: 'auto_edit', materializeWhenAbsent: true }],
-    mcpConfig: { path: '.gemini/settings.json', format: 'gemini-json' },
+    // gemini-cli's `homedir()` returns `GEMINI_CLI_HOME` when set (packages/core/src/utils/paths.ts).
+    mcpConfig: {
+      path: '.gemini/settings.json',
+      format: 'gemini-json',
+      relocation: { envVar: 'GEMINI_CLI_HOME', path: '.gemini/settings.json' },
+    },
     // Web-researched, unverified — needs a restart to pick up (CLI reads these at process
     // start). Confirm the exact model-override env var name against the installed
     // gemini-cli version before shipping.
@@ -814,6 +833,7 @@ const ANTIGRAVITY: CliEntry = {
     // Like codex: an ABSENT config already defaults safe (no bypass flag), so only a
     // SENT config needs the flag forced off — nothing is materialized.
     privilegedParams: [{ param: 'dangerouslySkipPermissions', clampTo: false }],
+    // No relocation var: `agy` 1.1.12 resolves `~/.gemini/config` from $HOME only.
     mcpConfig: { path: '.gemini/config/mcp_config.json', format: 'antigravity-json' },
     // No known CLI/env/config mechanism — Antigravity's own docs describe a GUI-only
     // custom-endpoint setting and explicitly say it "cannot currently" become the core

src/config/cli-registry/types.ts

@@ -530,8 +530,15 @@ export interface CliCapabilities {
    * `path` is relative to the home directory. `format` names the file dialect the sync
    * adapter reads and writes. Absent = no known/verified MCP config file, so the CLI is
    * skipped by sync rather than guessed at.
+   *
+   * `relocation` names the env var the CLI itself reads to move that file (codex's
+   * `CODEX_HOME`, claude's `CLAUDE_CONFIG_DIR`, opencode's `XDG_CONFIG_HOME`). When the SERVER
+   * process env (what the CLIs Codeman spawns inherit) sets it to an absolute directory, the
+   * file is `<that dir>/<relocation.path>` instead; set to anything else, the target is
+   * reported `skipped` rather than written somewhere the CLI never reads. Absent = the file
+   * only follows `$HOME`.
    */
-  mcpConfig?: { path: string; format: McpConfigFormat };
+  mcpConfig?: { path: string; format: McpConfigFormat; relocation?: { envVar: string; path: string } };
   /**
    * How this CLI is pointed at a user-supplied custom OpenAI-compatible
    * endpoint (local, e.g. llama.cpp, or cloud, e.g. Azure AI Foundry) — the

src/mcp-sync.ts

@@ -25,9 +25,13 @@
  *     readable by its owner only.
  *   - Servers a dialect cannot express (SSE for codex) are skipped and reported.
  *   - Only one apply runs at a time.
+ *   - A CLI whose file was moved by its own env var (`mcpConfig.relocation`: `CODEX_HOME`,
+ *     `CLAUDE_CONFIG_DIR`, ...) is followed there, as the SERVER env sets it; a relative value
+ *     cannot be located safely, so that target is reported `skipped` and never written.
  *
- * The result types never carry env values or headers: those commonly hold secrets and the
- * result is returned over HTTP.
+ * The result types (src/types/mcp-sync.ts) never carry env values or headers: those commonly
+ * hold secrets and the result is returned over HTTP. For the same reason a parse failure is
+ * reported by position only (`describeMcpSyncError`): parsers quote the offending source.
  *
  * @module mcp-sync
  */
@@ -35,9 +39,10 @@
 import { promises as fs } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import { homedir } from 'node:os';
-import { dirname, join } from 'node:path';
-import { parse as parseToml } from 'smol-toml';
+import { dirname, isAbsolute, join } from 'node:path';
+import { parse as parseToml, TomlError } from 'smol-toml';
 import type { McpConfigFormat } from './config/cli-registry/types.js';
+import type { McpSyncResult, McpSyncTargetResult } from './types/mcp-sync.js';
 
 export type McpFormat = McpConfigFormat;
 
@@ -58,41 +63,15 @@ export type McpServerMap = Record<string, McpServer>;
 export interface McpSyncTarget {
   id: string;
   label: string;
+  /** Home-relative default location of the config file. */
   path: string;
   format: McpFormat;
+  /** The env var the CLI reads to move the file, and the path under it (`mcpConfig.relocation`). */
+  relocation?: { envVar: string; path: string };
   /** The CLI's binary resolves on this machine. A CLI that is not installed and has no config file is left alone. */
   installed: boolean;
 }
 
-export interface McpSyncTargetResult {
-  id: string;
-  label: string;
-  file: string;
-  /**
-   * `absent`: not installed and no config file, so neither read nor created.
-   * `unreadable`: the file exists but cannot be parsed safely, so it is not written.
-   * `failed`: a read or write error (the file may be unchanged).
-   */
-  status: 'ok' | 'absent' | 'unreadable' | 'failed';
-  error?: string;
-  servers: string[];
-  /** Servers added (apply) or that would be added (plan). */
-  added: string[];
-  /** Missing servers this dialect cannot express. */
-  skipped: string[];
-}
-
-export interface McpSyncResult {
-  applied: boolean;
-  targets: McpSyncTargetResult[];
-  /** Names defined differently by different CLIs; existing definitions are left untouched. */
-  conflicts: string[];
-  /** Names left out because the only definitions are switched off in their own CLI. */
-  disabled: string[];
-  /** Enabled agent CLIs with no known MCP config file, so sync cannot touch them. */
-  unsupported: string[];
-}
-
 /** A second apply was requested while one was running. */
 export class McpSyncBusyError extends Error {
   constructor() {
@@ -101,6 +80,39 @@ export class McpSyncBusyError extends Error {
   }
 }
 
+/**
+ * An error whose message this module wrote itself. It names keys Codeman chose and server names
+ * (which the result reports anyway), never a value from the file, so it may be shown as is.
+ */
+class McpConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'McpConfigError';
+  }
+}
+
+/**
+ * What a target's `error` may say. A parser's own message can quote the file: smol-toml's
+ * `TomlError` carries a code frame of the offending line and the one before it, and V8's JSON
+ * "Unexpected token" errors quote about ten characters of source. These files hold env values
+ * and headers and the result goes over HTTP, so a parse failure is reported by position only,
+ * an errno failure by Node's own message (code, syscall and path: no file content), and anything
+ * else by a fixed category.
+ */
+function describeMcpSyncError(err: unknown): string {
+  if (err instanceof McpConfigError) return err.message;
+  if (err instanceof TomlError) return `not valid TOML (line ${err.line}, column ${err.column})`;
+  if (err instanceof SyntaxError) {
+    const lc = /\(line (\d+) column (\d+)\)/.exec(err.message);
+    if (lc) return `not valid JSON (line ${lc[1]}, column ${lc[2]})`;
+    const pos = /at position (\d+)/.exec(err.message);
+    return pos ? `not valid JSON (position ${pos[1]})` : 'not valid JSON';
+  }
+  const code = (err as NodeJS.ErrnoException | null)?.code;
+  if (err instanceof Error && typeof code === 'string' && /^E[A-Z0-9]+$/.test(code)) return err.message;
+  return 'unexpected error';
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -349,15 +361,15 @@ function mcpTable(format: McpFormat, text: string | null): Record<string, unknow
     const doc = parseToml(text);
     const table = doc.mcp_servers;
     if (table === undefined) return dict<unknown>();
-    if (!isRecord(table)) throw new Error('"mcp_servers" is not a table');
+    if (!isRecord(table)) throw new McpConfigError('"mcp_servers" is not a table');
     return table;
   }
   const dialect = JSON_DIALECTS[format];
   const doc: unknown = JSON.parse(text);
-  if (!isRecord(doc)) throw new Error('top level is not a JSON object');
+  if (!isRecord(doc)) throw new McpConfigError('top level is not a JSON object');
   const table = doc[dialect.key];
   if (table === undefined) return dict<unknown>();
-  if (!isRecord(table)) throw new Error(`"${dialect.key}" is not an object`);
+  if (!isRecord(table)) throw new McpConfigError(`"${dialect.key}" is not an object`);
   return table;
 }
 
@@ -434,12 +446,12 @@ export function addServers(format: McpFormat, text: string | null, add: McpServe
   // Re-read what we are about to write.
   const after = parseConfig(format, out);
   for (const n of before.names) {
-    if (!after.names.has(n)) throw new Error(`refusing to write: "${n}" would be lost`);
+    if (!after.names.has(n)) throw new McpConfigError(`refusing to write: "${n}" would be lost`);
   }
   for (const n of names) {
     const got = after.servers[n];
     if (!got || fullIdentity(got) !== fullIdentity(todo[n])) {
-      throw new Error(`refusing to write: "${n}" does not read back as written`);
+      throw new McpConfigError(`refusing to write: "${n}" does not read back as written`);
     }
   }
   return out;
@@ -481,7 +493,7 @@ async function writeAtomic(file: string, text: string, secret: boolean): Promise
     // ENOENT from realpath on a dangling link, or lstat on a missing file: tell them apart.
     try {
       await fs.lstat(file);
-      throw new Error('config path is a dangling symlink');
+      throw new McpConfigError('config path is a dangling symlink');
     } catch (inner) {
       if ((inner as NodeJS.ErrnoException).code !== 'ENOENT') throw inner;
     }
@@ -514,6 +526,36 @@ export interface McpSyncOptions {
   /** false = report what would change without writing. */
   apply: boolean;
   home?: string;
+  /**
+   * Where relocation env vars (`McpSyncTarget.relocation`) are read from: the env the CLIs
+   * Codeman spawns would inherit. Defaults to `process.env`, except when `home` is overridden
+   * (tests, throwaway homes): then it defaults to none, so a relocation var in the caller's own
+   * env can never aim a write outside that home.
+   */
+  env?: Record<string, string | undefined>;
+}
+
+/**
+ * The config file a target means, honouring its relocation env var. `skip` is set when the var
+ * holds something that cannot be located safely (a relative path resolves against the CLI's
+ * working directory, which differs per session), so the target is neither read nor written.
+ */
+function resolveFile(
+  t: McpSyncTarget,
+  home: string,
+  env: Record<string, string | undefined>
+): { file: string; skip?: string } {
+  const rel = t.relocation;
+  const dir = rel ? env[rel.envVar] : undefined;
+  // Every CLI declared today treats an empty value as unset (`||` / a non-empty filter).
+  if (!rel || dir === undefined || dir === '') return { file: join(home, t.path) };
+  if (!isAbsolute(dir)) {
+    return {
+      file: `$${rel.envVar}/${rel.path}`,
+      skip: `${rel.envVar} is set to a relative path, so the file ${t.label} reads cannot be located safely`,
+    };
+  }
+  return { file: join(dir, rel.path) };
 }
 
 let applying = false;
@@ -541,16 +583,19 @@ export async function syncMcpServers(
 
 async function run(targets: McpSyncTarget[], opts: McpSyncOptions, unsupported: string[]): Promise<McpSyncResult> {
   const home = opts.home ?? homedir();
+  const env = opts.env ?? (opts.home === undefined ? process.env : {});
   const seen = new Set<string>();
-  const live = targets.filter((t) => (seen.has(t.path) ? false : (seen.add(t.path), true)));
+  const live = targets
+    .map((t) => ({ t, ...resolveFile(t, home, env) }))
+    .filter(({ file }) => (seen.has(file) ? false : (seen.add(file), true)));
 
-  const state = live.map((t) => {
-    const file = join(home, t.path);
+  const state = live.map(({ t, file, skip }) => {
     const res: McpSyncTargetResult = {
       id: t.id,
       label: t.label,
       file,
-      status: 'ok',
+      status: skip ? 'skipped' : 'ok',
+      ...(skip ? { error: skip } : {}),
       servers: [],
       added: [],
       skipped: [],
@@ -559,6 +604,7 @@ async function run(targets: McpSyncTarget[], opts: McpSyncOptions, unsupported:
   });
 
   for (const s of state) {
+    if (s.res.status !== 'ok') continue;
     try {
       if (!s.t.installed && !(await exists(s.file))) {
         s.res.status = 'absent';
@@ -570,7 +616,7 @@ async function run(targets: McpSyncTarget[], opts: McpSyncOptions, unsupported:
       s.res.servers = [...parsed.names];
     } catch (err) {
       s.res.status = 'unreadable';
-      s.res.error = err instanceof Error ? err.message : String(err);
+      s.res.error = describeMcpSyncError(err);
     }
   }
 
@@ -618,7 +664,7 @@ async function run(targets: McpSyncTarget[], opts: McpSyncOptions, unsupported:
       s.res.added = written;
     } catch (err) {
       s.res.status = 'failed';
-      s.res.error = err instanceof Error ? err.message : String(err);
+      s.res.error = describeMcpSyncError(err);
       s.res.added = [];
     }
   }

src/types/index.ts

@@ -27,6 +27,7 @@
  * | push         | PushSubscriptionRecord, VapidKeys, WebhookConfig, WebhookStatus, WebhookResult | `~/.codeman/push-keys.json`, `~/.codeman/push-subscriptions.json`, `~/.codeman/webhook.json` |
  * | plan         | PlanItem, PlanTaskStatus, TddPhase                                    | In-memory → `GET /api/sessions/:id/plan/tasks` |
  * | orchestrator | OrchestratorState, OrchestratorPlan, OrchestratorConfig, OrchestratorPersistState | `~/.codeman/state.json` → `GET /api/orchestrator/status` |
+ * | mcp-sync     | McpSyncResult, McpSyncTargetResult                                    | Other CLIs' own config files → `GET`/`POST /api/mcp-sync` |
  *
  * ## Cross-domain relationship map
  *
@@ -72,3 +73,4 @@ export * from './search.js';
 export * from './user.js';
 export * from './webview.js';
 export * from './intent.js';
+export * from './mcp-sync.js';

src/types/mcp-sync.ts

@@ -0,0 +1,41 @@
+/**
+ * @fileoverview Response types for MCP server sync (`GET`/`POST /api/mcp-sync`, src/mcp-sync.ts).
+ *
+ * These are returned over HTTP, so they carry server NAMES only: never env values or headers,
+ * and never file content (a parse failure is reported by position, see `describeMcpSyncError`).
+ */
+
+/** One participating CLI in a sync result. */
+export interface McpSyncTargetResult {
+  id: string;
+  label: string;
+  /** The config file read (and written). For a `skipped` target, the unresolved location. */
+  file: string;
+  /**
+   * `absent`: not installed and no config file, so neither read nor created.
+   * `skipped`: the CLI's config location could not be resolved safely (e.g. its relocation env
+   * var is a relative path), so it is neither read nor written; `error` says why.
+   * `unreadable`: the file exists but cannot be parsed safely, so it is not written.
+   * `failed`: a read or write error (the file may be unchanged).
+   */
+  status: 'ok' | 'absent' | 'skipped' | 'unreadable' | 'failed';
+  /** Why the target is not `ok`. Position or category only, never file content. */
+  error?: string;
+  servers: string[];
+  /** Servers added (apply) or that would be added (plan). */
+  added: string[];
+  /** Missing servers this dialect cannot express. */
+  skipped: string[];
+}
+
+/** The `data` of `GET`/`POST /api/mcp-sync`. */
+export interface McpSyncResult {
+  applied: boolean;
+  targets: McpSyncTargetResult[];
+  /** Names defined differently by different CLIs; existing definitions are left untouched. */
+  conflicts: string[];
+  /** Names left out because the only definitions are switched off in their own CLI. */
+  disabled: string[];
+  /** Installed, enabled agent CLIs with no known MCP config file, so sync cannot touch them. */
+  unsupported: string[];
+}

src/web/public/index.html

@@ -2505,7 +2505,7 @@
               </div>
 
               <div class="set-group" id="mcpSyncGroup">
-                <div class="set-group-head"><h4>MCP servers</h4><span class="set-scope">server</span></div>
+                <div class="set-group-head"><h4>MCP servers</h4><span class="set-scope">synced</span></div>
                 <div class="set-group-body">
                   <div class="set-row" data-search="mcp server sync enable claude codex gemini opencode antigravity">
                     <div class="set-row-text">
@@ -2517,7 +2517,7 @@
                   <div class="set-row" id="mcpSyncActionRow" style="display:none" data-search="mcp server sync preview">
                     <div class="set-row-text">
                       <span class="set-row-label">Sync MCP servers across CLIs</span>
-                      <span class="set-row-desc">Copies each installed, enabled CLI's MCP servers into the others. Only adds missing servers; never edits, removes or copies a server you switched off. Env values and headers are copied too, so a file that receives them is left readable by you only. The previous file is kept as <code>.codeman-bak</code> (overwritten by each sync).</span>
+                      <span class="set-row-desc">Copies each installed, enabled CLI's MCP servers into the others. Only adds missing servers; never edits, removes or copies a server you switched off. Env values and headers are copied too, so a file that receives them is left readable by you only. The previous file is kept as <code>.codeman-bak</code> (overwritten by each sync). A config dir moved by the CLI's own env var (<code>CODEX_HOME</code>, <code>CLAUDE_CONFIG_DIR</code>, <code>XDG_CONFIG_HOME</code>, <code>GEMINI_CLI_HOME</code>) is followed as Codeman's server sees it; a per-session override is not.</span>
                     </div>
                     <span>
                       <button class="btn-toolbar btn-sm" id="mcpSyncPreviewBtn" onclick="app.mcpSync(false)">Preview</button>

src/web/public/settings-ui.js

@@ -417,7 +417,10 @@ Object.assign(CodemanApp.prototype, {
     // needs an explicit sync on every open, not just a save.
     this.applyCliManagementVisibility();
     // MCP server sync: synced, default OFF; same explicit-sync reasoning as above.
-    document.getElementById('appSettingsMcpSync').checked = settings.mcpSyncEnabled === true;
+    // The routes read the SAVED setting, so remember what it was on open: switching it on
+    // here does nothing server-side until Save (see mcpSync()).
+    this._mcpSyncSavedOn = settings.mcpSyncEnabled === true;
+    document.getElementById('appSettingsMcpSync').checked = this._mcpSyncSavedOn;
     this.applyMcpSyncVisibility();
     this.loadWebhook();
     // Read My Mind: synced, default OFF (opt-in; capture + prediction cost real tokens).
@@ -1173,6 +1176,20 @@ Object.assign(CodemanApp.prototype, {
     if (row) row.style.display = on ? '' : 'none';
     const out = this.$('mcpSyncResult');
     if (!on && out) { out.style.display = 'none'; out.innerHTML = ''; }
+    this._applyMcpSyncAdminGate();
+  },
+
+  /**
+   * Both /api/mcp-sync verbs are admin-only in multi-user mode (they write files in the server
+   * user's home), so a non-admin gets no MCP group at all, switch included, the same way
+   * _applyCliManagementAdminGate hides the CLI list. Also wired to `codeman:me`, because
+   * `window.__codemanUser`'s real role can resolve after settings were opened once.
+   */
+  _applyMcpSyncAdminGate() {
+    const group = document.getElementById('mcpSyncGroup');
+    if (!group) return;
+    const me = window.__codemanUser || {};
+    group.style.display = me.multiUser && me.role !== 'admin' ? 'none' : '';
   },
 
   /** Preview (apply=false) or run (apply=true) the MCP server sync across enabled CLIs. */
@@ -1181,6 +1198,11 @@ Object.assign(CodemanApp.prototype, {
     const show = (html) => {
       if (out) { out.style.display = 'block'; out.innerHTML = html; }
     };
+    // Switched on in this modal but not saved yet: the routes would only answer "disabled".
+    if (!this._mcpSyncSavedOn) {
+      show('Save settings to turn MCP sync on first, then reopen Settings to preview or sync.');
+      return;
+    }
     if (apply && !confirm('Add missing MCP servers to every installed, enabled CLI\'s config file? Env values and headers on those servers are copied too.')) return;
     show('Working…');
     const res = apply ? await this._apiPost('/api/mcp-sync', {}) : await this._api('/api/mcp-sync');
@@ -1193,12 +1215,14 @@ Object.assign(CodemanApp.prototype, {
     const data = body.data;
     const rows = data.targets.map((t) => {
       if (t.status === 'absent') return `<li><b>${escapeHtml(t.label)}</b>: not installed, skipped</li>`;
+      if (t.status === 'skipped') return `<li><b>${escapeHtml(t.label)}</b>: not touched (${escapeHtml(t.error || 'config location unknown')})</li>`;
       if (t.status === 'unreadable') return `<li><b>${escapeHtml(t.label)}</b>: not touched, file can't be read safely (${escapeHtml(t.error || 'unreadable')})</li>`;
       if (t.status === 'failed') return `<li><b>${escapeHtml(t.label)}</b>: failed (${escapeHtml(t.error || 'error')}); the file may be unchanged</li>`;
       const verb = data.applied ? 'added' : 'would add';
       const parts = [t.added.length ? `${verb} ${t.added.map(escapeHtml).join(', ')}` : 'up to date'];
       if (t.skipped.length) parts.push(`can't express ${t.skipped.map(escapeHtml).join(', ')}`);
-      return `<li><b>${escapeHtml(t.label)}</b> (${t.servers.length} servers): ${parts.join('; ')}</li>`;
+      const count = `${t.servers.length} server${t.servers.length === 1 ? '' : 's'}`;
+      return `<li><b>${escapeHtml(t.label)}</b> (${count}): ${parts.join('; ')}</li>`;
     });
     const conflicts = data.conflicts.length
       ? `<p>Defined differently across CLIs (each existing definition is kept; the first CLI's is copied where the name is missing): ${data.conflicts.map(escapeHtml).join(', ')}</p>`
@@ -4348,4 +4372,5 @@ Object.assign(CodemanApp.prototype, {
 document.addEventListener?.('codeman:me', () => {
   window.app?._applyCustomModelAdminGate?.();
   window.app?._applyCliManagementAdminGate?.();
+  window.app?._applyMcpSyncAdminGate?.();
 });

src/web/routes/mcp-sync-routes.ts

@@ -7,20 +7,27 @@
  * Opt-in: both verbs answer 403 until `mcpSyncEnabled` is on (default OFF), because this writes
  * OTHER tools' own user config. Writes files in the SERVER user's home, so in multi-user mode it
  * is admin only. A second apply while one is running answers 409. Responses carry server names
- * only, never env values or headers.
+ * only, never env values, headers or file content (a parse failure is reported by position).
  *
  * A CLI takes part when it is ENABLED in the registry, declares an `mcpConfig`, and is installed
  * or already has its config file; one that is enabled but absent from the machine is reported
- * `absent` and never created.
+ * `absent` and never created. Its file is located with this process's env (the env the CLIs
+ * Codeman spawns inherit), so a relocation var such as `CODEX_HOME` is followed.
  */
 
 import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
-import { ApiErrorCode, createErrorResponse, getErrorMessage, type ApiResponse } from '../../types.js';
+import {
+  ApiErrorCode,
+  createErrorResponse,
+  getErrorMessage,
+  type ApiResponse,
+  type McpSyncResult,
+} from '../../types.js';
 import { isAdmin, readJsonConfig, SETTINGS_PATH } from '../route-helpers.js';
 import { isMultiUserMode } from '../../config/multiuser.js';
 import { enabledClis } from '../../config/cli-registry/registry.js';
 import { isCliEntryInstalled, probeStockCliAvailability } from '../../utils/cli-installed-probes.js';
-import { McpSyncBusyError, syncMcpServers, type McpSyncResult, type McpSyncTarget } from '../../mcp-sync.js';
+import { McpSyncBusyError, syncMcpServers, type McpSyncTarget } from '../../mcp-sync.js';
 
 /** Default OFF, same shape as `readCliManagementEnabled`: read fresh so a toggle applies at once. */
 export async function readMcpSyncEnabled(): Promise<boolean> {
@@ -29,8 +36,7 @@ export async function readMcpSyncEnabled(): Promise<boolean> {
 }
 
 /** Enabled CLIs that declare an MCP config file, in registry order (first definition wins). */
-export async function mcpSyncTargets(): Promise<McpSyncTarget[]> {
-  const availability = await probeStockCliAvailability();
+export function mcpSyncTargets(availability: Record<string, boolean>): McpSyncTarget[] {
   return enabledClis()
     .filter((e) => e.capabilities.mcpConfig)
     .sort((a, b) => a.order - b.order)
@@ -42,10 +48,13 @@ export async function mcpSyncTargets(): Promise<McpSyncTarget[]> {
     }));
 }
 
-/** Enabled agent CLIs with no known MCP config file (sync cannot touch them). */
-export function mcpUnsupportedLabels(): string[] {
+/**
+ * Installed, enabled agent CLIs with no known MCP config file (sync cannot touch them). One that
+ * is not installed is left out, the same way a supported one that is not installed reads `absent`.
+ */
+export function mcpUnsupportedLabels(availability: Record<string, boolean>): string[] {
   return enabledClis()
-    .filter((e) => e.kind === 'agent' && !e.capabilities.mcpConfig)
+    .filter((e) => e.kind === 'agent' && !e.capabilities.mcpConfig && isCliEntryInstalled(e, availability))
     .map((e) => e.label);
 }
 
@@ -54,7 +63,10 @@ async function gate(req: FastifyRequest): Promise<ApiResponse<never> | null> {
     return createErrorResponse(ApiErrorCode.FORBIDDEN, 'Admin only in multi-user mode');
   }
   if (!(await readMcpSyncEnabled())) {
-    return createErrorResponse(ApiErrorCode.FORBIDDEN, 'MCP sync is disabled. Enable it in Settings first.');
+    return createErrorResponse(
+      ApiErrorCode.FORBIDDEN,
+      'MCP sync is disabled. Turn on "Enable MCP server sync" in Settings and save first.'
+    );
   }
   return null;
 }
@@ -67,7 +79,10 @@ export function registerMcpSyncRoutes(app: FastifyInstance): void {
       return denied;
     }
     try {
-      return { success: true, data: await syncMcpServers(await mcpSyncTargets(), { apply }, mcpUnsupportedLabels()) };
+      const availability = await probeStockCliAvailability();
+      const targets = mcpSyncTargets(availability);
+      const data = await syncMcpServers(targets, { apply, env: process.env }, mcpUnsupportedLabels(availability));
+      return { success: true, data };
     } catch (err) {
       if (err instanceof McpSyncBusyError) {
         reply.code(409);