feat(mcp): sync MCP servers across enabled CLIs

Adds capabilities.mcpConfig to the CLI registry (Claude, Gemini, Codex,
OpenCode), an additive src/mcp-sync.ts, GET/POST /api/mcp-sync and a
Settings > Agents & CLIs control. Never edits or removes an existing
server; backs up each file it changes; reports conflicts.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

src/web/public/index.html

@@ -2474,6 +2474,23 @@
                   </div>
                 </div>
               </div>
+
+              <div class="set-group">
+                <div class="set-group-head"><h4>MCP servers</h4><span class="set-scope">server</span></div>
+                <div class="set-group-body">
+                  <div class="set-row" data-search="mcp server sync claude codex gemini opencode">
+                    <div class="set-row-text">
+                      <span class="set-row-label">Sync MCP servers across CLIs</span>
+                      <span class="set-row-desc">Copies each enabled CLI's MCP servers into the others' config files. Only adds missing servers; never edits or removes one. The previous file is kept as <code>.codeman-bak</code>.</span>
+                    </div>
+                    <span>
+                      <button class="btn-toolbar btn-sm" id="mcpSyncPreviewBtn" onclick="app.mcpSync(false)">Preview</button>
+                      <button class="btn-toolbar btn-sm btn-primary" id="mcpSyncApplyBtn" onclick="app.mcpSync(true)">Sync now</button>
+                    </span>
+                  </div>
+                  <div id="mcpSyncResult" class="set-note" style="display:none"></div>
+                </div>
+              </div>
             </section>
 
             <!-- ══ Notifications ════════════════════════════════════════════ -->

src/web/public/settings-ui.js

@@ -1114,6 +1114,35 @@ Object.assign(CodemanApp.prototype, {
     this._updateCheck = null;
   },
 
+  /** Preview (apply=false) or run (apply=true) the MCP server sync across enabled CLIs. */
+  async mcpSync(apply) {
+    const out = this.$('mcpSyncResult');
+    const show = (html) => {
+      if (out) { out.style.display = 'block'; out.innerHTML = html; }
+    };
+    if (apply && !confirm('Add missing MCP servers to every enabled CLI\'s config file?')) return;
+    show('Working…');
+    const res = apply ? await this._apiPost('/api/mcp-sync', {}) : await this._api('/api/mcp-sync');
+    let body = null;
+    try { body = res ? await res.json() : null; } catch { /* fall through */ }
+    if (!res || !res.ok || !body || body.success === false) {
+      show(escapeHtml(body?.error || 'MCP sync failed.'));
+      return;
+    }
+    const data = body.data;
+    const rows = data.targets.map((t) => {
+      if (t.status !== 'ok') return `<li><b>${escapeHtml(t.label)}</b>: not touched (${escapeHtml(t.error || 'unreadable')})</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 conflicts = data.conflicts.length
+      ? `<p>Defined differently across CLIs, left unchanged: ${data.conflicts.map(escapeHtml).join(', ')}</p>`
+      : '';
+    show(`<ul>${rows.join('')}</ul>${conflicts}`);
+  },
+
   _setUpdateResult(html) {
     const el = this.$('updateResult');
     if (el) { el.style.display = 'block'; el.innerHTML = html; }

src/web/routes/index.ts

@@ -28,6 +28,7 @@ export { registerWsRoutes } from './ws-routes.js';
 export { registerVoiceRoutes } from './voice-routes.js';
 export { registerWebviewRoutes, tryWebviewRefererFallback } from './webview-routes.js';
 export { registerTabLayoutRoutes } from './tab-layout-routes.js';
+export { registerMcpSyncRoutes } from './mcp-sync-routes.js';
 export {
   registerCustomModelRoutes,
   refreshAllCustomModelHosts,

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

@@ -0,0 +1,45 @@
+/**
+ * @fileoverview MCP server sync (src/mcp-sync.ts).
+ *
+ * GET  /api/mcp-sync — dry run: per enabled CLI, which servers it has and which it would gain.
+ * POST /api/mcp-sync — apply: add the missing servers to each CLI's own config file.
+ *
+ * Writes files in the SERVER user's home, so in multi-user mode it is admin only. Responses
+ * carry server names only, never env values or headers.
+ */
+
+import type { FastifyInstance, FastifyRequest } from 'fastify';
+import { ApiErrorCode, createErrorResponse, getErrorMessage, type ApiResponse } from '../../types.js';
+import { isAdmin } from '../route-helpers.js';
+import { isMultiUserMode } from '../../config/multiuser.js';
+import { enabledClis } from '../../config/cli-registry/registry.js';
+import { syncMcpServers, type McpSyncResult, type McpSyncTarget } from '../../mcp-sync.js';
+
+/** Enabled CLIs that declare an MCP config file, in registry order (first definition wins). */
+export function mcpSyncTargets(): McpSyncTarget[] {
+  return enabledClis()
+    .filter((e) => e.capabilities.mcpConfig)
+    .sort((a, b) => a.order - b.order)
+    .map((e) => ({ id: e.id, label: e.label, ...e.capabilities.mcpConfig! }));
+}
+
+function gate(req: FastifyRequest): ApiResponse<never> | null {
+  if (isMultiUserMode() && !isAdmin(req)) {
+    return createErrorResponse(ApiErrorCode.FORBIDDEN, 'Admin only in multi-user mode');
+  }
+  return null;
+}
+
+export function registerMcpSyncRoutes(app: FastifyInstance): void {
+  const run = async (req: FastifyRequest, apply: boolean): Promise<ApiResponse<McpSyncResult>> => {
+    const denied = gate(req);
+    if (denied) return denied;
+    try {
+      return { success: true, data: await syncMcpServers(mcpSyncTargets(), { apply }) };
+    } catch (err) {
+      return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err));
+    }
+  };
+  app.get('/api/mcp-sync', (req) => run(req, false));
+  app.post('/api/mcp-sync', (req) => run(req, true));
+}

src/web/server.ts

@@ -197,6 +197,7 @@ import {
   registerVoiceRoutes,
   registerWebviewRoutes,
   registerTabLayoutRoutes,
+  registerMcpSyncRoutes,
   registerCustomModelRoutes,
   refreshAllCustomModelHosts,
   readCustomModelEndpointsEnabled,
@@ -1130,6 +1131,7 @@ export class WebServer extends EventEmitter {
     registerOrchestratorRoutes(this.app, ctx);
     registerWebviewRoutes(this.app, ctx, this.basePath);
     registerTabLayoutRoutes(this.app, ctx);
+    registerMcpSyncRoutes(this.app);
     registerCustomModelRoutes(this.app);
     registerCliRegistryRoutes(this.app);