claude-multiacc 2.0.37 → 2.0.39

package/README.md

@@ -177,17 +177,17 @@ buckets keep being tracked and the ≥90% rule keeps working. Unparseable entrie
 skipped, an all-legacy payload falls back to `five_hour`/`seven_day`, and a payload the
 code cannot read at all degrades that one account (fail open), never the run.
 
-**Limit resets are redeemed automatically, but only when one earns its keep.** Claude
+**A parked account gets its limit reset automatically.** Claude
 Code 2.1.280 added `/limit-reset`: an account can hold a *grant* (the Opus 5.5 launch gave
 every Pro/Max account one reset, usable until 2026-10-22) that refills its five-hour and
 weekly limits at once while the weekly reset day stays put. The same usage call carries the
 grant's status (`?cedar_ember=1&skip_spend=1`, Claude Code's own read, so it costs nothing
 against the endpoint's hourly budget), and the limits pass claims it with
-`POST /api/organizations/<org>/reset_rate_limits` when a **weekly** limit the grant refills
-is ≥ 95% used or reported exhausted — the codex rule, narrowed because a Claude reset is one
-irreversible shot. A full five-hour window alone never spends it (it refills in hours and the
-pool picks another account), and it is held while the account's own week refills in under
-24 h (`CLAUDE_MULTIACC_RESET_MIN_HORIZON`, seconds). The claim carries a request id derived
+`POST /api/organizations/<org>/reset_rate_limits` whenever the pool has **parked** the account on a
+window the grant refills — a bucket at/over the pool's own threshold (90%), a limit the server
+reports exhausted, or an active park (a client 429, or the app-robot panel's own park) — and holds
+it only when every such park lifts on its own within the hour (`CLAUDE_MULTIACC_RESET_MIN_HORIZON`,
+seconds). The claim carries a request id derived
 from the account, grant, remaining count and week, persisted before the POST, so a lost
 response is retried with the same id and fleet peers converge on one claim; a claim whose
 answer never came back is settled by the grant's own remaining count dropping, and a claim
@@ -395,6 +395,84 @@ an account, and if one slips through it returns to the pool by itself. Output is
 never double-emits. Only engages when stdin is finite (tty / regular file / `/dev/null`)
 and ≥2 accounts are eligible; service-spawned pipes take the plain exec path untouched.
 
+## MCP servers for every account
+
+Both clients keep MCP servers in the **config dir** — `<dir>/.claude.json` for Claude Code,
+`<CODEX_HOME>/config.toml` for Codex — so under the pool there is one MCP configuration per
+account, and a stock `claude mcp add` lands in **one random account**. That is how
+`appinspire-mcp` was connected in some sessions and missing in others (2026-09-22). The pool
+now owns a **registry**, `<pool>/mcp-servers.json`, that is reconciled into every account:
+
+```bash
+claude-accounts mcp add appinspire-mcp -- npx -y appinspire-mcp@latest serve   # both pools
+claude-accounts mcp add --provider claude local-dev -e KEY=v -- node /path/server.mjs serve
+claude-accounts mcp add --scope project --project "$HOME/design-lab/run1" appinspire -e APPINSPIRE_LIBRARY_DIR="$HOME/.appinspire-mcp/library" -- node "$HOME/appinspire-mcp/bin/appinspire-mcp.mjs" serve
+claude-accounts mcp remove adspower-local-api    # retire EVERYWHERE: every account, every project entry
+claude-accounts mcp remove foo --user-only       # user scope only; project-local copies stay
+claude-accounts mcp list [--json]
+claude-accounts mcp apply                        # re-apply now (repair drift)
+```
+
+- **Default `--provider both`**: an MCP server is not provider-specific, so `claude-accounts
+  mcp add` also writes the codex pool's registry (and `codex-accounts mcp add` the claude
+  one); `--provider claude|codex` narrows it, and an explicit provider whose pool is missing
+  on this machine is an error (the default is silent about it). `-e KEY=VAL` takes one
+  variable per flag; write `$HOME/...`, never `~/...`, inside a value (zsh does not expand
+  `~` after `=` in a word).
+- **Tombstones**: an explicit `mcp remove NAME` retires the server **everywhere** — user
+  scope and every project entry, in every account, on every Mac after sync — even a copy
+  that was only ever hand-added to a single account (registry key `retired`). `--user-only`
+  records a user-scope-only tombstone (`retiredUser`). A stock removal mirrored from the shim
+  is scope-limited: `claude mcp remove -s user X` retires X in user scope only, a `-s local`
+  removal retires it in that one project only. Re-adding a name lifts its tombstone.
+- **Exit status 3** from `mcp add|add-json|remove` means the registry was saved but some
+  account could not be reconciled (a corrupt `.claude.json`, a `config.toml` layout the
+  editor refuses): the change still syncs and still reaches the sibling pool; fix the account
+  and run `mcp apply`. Exit 1 means nothing was saved.
+- **Where it is applied**: at seed time (`add`/`import`/`sync`/`post-sync`, so a new account or
+  a fleet Mac gets it), and by the **shim right before exec** — the picked account is
+  reconciled when the registry, the machine-local overlay or the account's own config changed
+  since the last verified reconcile (stamp in `<acct>/.mcp-applied`); Claude Code rewrites
+  `.claude.json` during most sessions, so on the claude side that check usually costs one
+  short python start-up per launch. Fail-open: a missing python or lib never breaks a launch.
+- **Stock commands are mirrored**: `claude mcp add|add-json|remove` and `codex mcp add|remove`
+  run under the shim execute against the picked account as usual, and the shim then copies the
+  outcome into the registry and every other account (`learn`). This includes a command run
+  from **inside** a pooled session (an agent's Bash tool, `npx appinspire-mcp install` run by
+  an agent): the session's config dir is a pool account, so the same mirror applies. A
+  config dir outside the pool is plain passthrough.
+- **Replicas**: on a pool whose `sync-role` file says `replica`, `add`/`remove` and the
+  shim's mirror land in the machine-local overlay (owner `local`) instead of the synced
+  registry, because the source's next push would overwrite them. Make registry changes on
+  the source machine.
+- **Project scope is claude-only** (`--scope project --project PATH`, or a stock `-s local`
+  add): Codex 0.156 reads no per-project MCP config, so a project entry is applied to every
+  claude account's `projects[PATH]` and skipped for codex.
+- **Fleet**: the **claude** registry rides with the manifest — `sync` pushes it to the server
+  and every manifest peer (all runner Macs), and the claude limits pass fans it out with the
+  telemetry, so a mirrored add reaches every Mac within one cadence; each target's
+  `post-sync` re-seeds and applies it. The **codex** registry reaches only codex sync
+  targets (the server, gas-mini): runner Macs' codex pools are local-only and get their
+  servers from app-robot's runner overlay (`codex-accounts mcp import-local --owner
+  app-robot`, app-robot PR #1870) or from a direct `codex-accounts mcp add --provider codex …`
+  on that Mac. The **machine-local overlay** `mcp-servers.local.json` is applied on its Mac
+  and **never synced**; the synced registry wins on a name both hold.
+- **Codex translation**: a Claude-style block becomes `[mcp_servers.<name>]`; unrelated
+  tables, their comments and blank lines are left alone. `KEY=${KEY}` env references become
+  `env_vars` (codex forwards a variable under its own name only); `KEY=${OTHER}` and
+  `${VAR:-default}` cannot be expressed, so that variable is left out with a warning. A stdio
+  server gets `startup_timeout_sec = 60` unless the block sets one (a cold `npx` download must
+  not trip Codex's 10 s default); SSE transports are skipped; codex-only keys (`oauth`,
+  `enabled_tools`, …) ride along in the registry block and never reach `.claude.json`.
+- **Kill switches**: `CLAUDE_MULTIACC_MCP=0` / `CODEX_MULTIACC_MCP=0` stop the reconcile at
+  seed and launch and the shim's mirror; `claude-accounts mcp …`, sync and the fan-out still
+  work.
+
+app-robot tasks are different: the panel launches Claude with `--strict-mcp-config` and a
+merged MCP document (`agent_mcp.servers_for`) and Codex with the same document as `-c`
+overrides, so a server every task must see is added there — never with `claude mcp add` on a
+Mac.
+
 ## Codex support (OpenAI Codex CLI)
 
 Both pools use the same selection policy. See [Codex account commands and behavior](docs/CODEX.md).

package/bin/claude

@@ -71,11 +71,117 @@ REAL="$(find_real)" || {
   exit 127
 }
 
+if [ "$(uname -s)" = "Darwin" ]; then
+  file_mtime() { stat -f %m "$1" 2>/dev/null || echo 0; }
+  file_sig() { stat -L -f '%m:%z' "$1" 2>/dev/null || echo '?'; }
+else
+  file_mtime() { stat -c %Y "$1" 2>/dev/null || echo 0; }
+  file_sig() { stat -L -c '%Y:%s' "$1" 2>/dev/null || echo '?'; }
+fi
+
+# ---- MCP servers for every account (lib/mcp_registry.py) -------------------------
+# Claude Code keeps MCP servers in the CONFIG DIR (`<dir>/.claude.json`), so under the
+# pool there is one MCP configuration per account — and a stock `claude mcp add` lands
+# in ONE random one (2026-09-22: appinspire was connected in some sessions and not in
+# others, depending on the account drawn). The pool's registry (mcp-servers.json, synced
+# fleet-wide) plus a machine-local overlay (mcp-servers.local.json) are reconciled into
+# the picked account right before exec, so a session gets the same servers whichever
+# account it drew. Bash only on the hot path: python runs when the registry, the overlay
+# or the account's own config changed since the last verified reconcile — the stamp in
+# <dir>/.mcp-applied — and never otherwise. Fail-open throughout: a missing python, a
+# missing lib or a broken registry costs nothing but the servers themselves.
+MCP_PY="$SELF_DIR/../lib/mcp_registry.py"
+MCP_PYBIN="${CLAUDE_MULTIACC_PYTHON:-python3}"
+mcp_sig() { # $1 acct dir -> "m:z,m:z,m:z" (registry, overlay, account config; - = absent)
+  local f out="" s
+  for f in "$ACC_ROOT/mcp-servers.json" "$ACC_ROOT/mcp-servers.local.json" "$1/.claude.json"; do
+    if [ -f "$f" ]; then s="$(file_sig "$f")"; else s="-"; fi
+    out="$out${out:+,}$s"
+  done
+  printf '%s\n' "$out"
+}
+mcp_ensure() { # $1 acct dir — silent, never changes the exit status
+  [ "${CLAUDE_MULTIACC_MCP:-1}" = "0" ] && return 0
+  [ -f "$ACC_ROOT/mcp-servers.json" ] || [ -f "$ACC_ROOT/mcp-servers.local.json" ] || return 0
+  [ -f "$MCP_PY" ] || return 0
+  local stamp=""
+  [ -f "$1/.mcp-applied" ] && IFS= read -r stamp < "$1/.mcp-applied" 2>/dev/null
+  [ "${stamp:-}" = "$(mcp_sig "$1")" ] && return 0
+  "$MCP_PYBIN" "$MCP_PY" --root "$ACC_ROOT" --provider claude apply --account-dir "$1" \
+    --fail-open --quiet >/dev/null 2>&1 </dev/null || true
+  return 0
+}
+
+# `claude mcp add|add-json|remove` writes ONE account's .claude.json — the one it ran
+# under — and nobody else's. So the shim runs it as a child instead of exec-ing it, then
+# mirrors what it wrote into the registry and every other account (`learn` diffs the
+# account against a snapshot taken just before). The real CLI's own parser and writer do
+# the work; the shim only copies the outcome. Exits with the real binary's status; a
+# mirror failure is one hint line. Returns 1 when this run is not such a command.
+mcp_mirror_run() { # $1 acct dir, then the user's argv — exits when it handled the run
+  local d="$1" snap="" rc verb="${2:-}" sub="${3:-}"
+  shift
+  # The scoped-limit fallback may have prepended `--model X` (a global option the real
+  # CLI accepts in front of any subcommand): look past it.
+  if [ "$verb" = "--model" ]; then verb="${3:-}"; sub="${4:-}"; fi
+  [ "$verb" = "mcp" ] || return 1
+  case "$sub" in add|add-json|remove) ;; *) return 1 ;; esac
+  [ "${CLAUDE_MULTIACC_MCP:-1}" != "0" ] && [ -f "$MCP_PY" ] || return 1
+  mcp_ensure "$d"
+  snap="$(mktemp "${TMPDIR:-/tmp}/claude-mcp-snap.XXXXXX" 2>/dev/null)" || snap=""
+  if [ -n "$snap" ] && ! "$MCP_PYBIN" "$MCP_PY" --root "$ACC_ROOT" --provider claude snapshot \
+       --account-dir "$d" > "$snap" 2>/dev/null </dev/null; then
+    rm -f "$snap" 2>/dev/null; snap=""
+  fi
+  "$REAL" "$@"
+  rc=$?
+  if [ "$rc" -eq 0 ] && [ -n "$snap" ]; then
+    "$MCP_PYBIN" "$MCP_PY" --root "$ACC_ROOT" --provider claude learn --account-dir "$d" \
+      --before "$snap" --project "$(pwd -P 2>/dev/null || pwd)" </dev/null \
+      || printf 'claude-multiacc: could not mirror the MCP change to the other accounts — run: claude-accounts mcp apply\n' >&2
+  elif [ "$rc" -eq 0 ]; then
+    printf 'claude-multiacc: could not mirror the MCP change to the other accounts — run: claude-accounts mcp apply\n' >&2
+  fi
+  [ -n "$snap" ] && rm -f "$snap" 2>/dev/null
+  exit "$rc"
+}
+
+# A pooled SESSION exports CLAUDE_CONFIG_DIR=<acct> and CLAUDE_SHIM_ACTIVE=1, and every child
+# process inherits both — so a `claude mcp add` run from INSIDE a session (an agent's
+# Bash tool, `npx appinspire-mcp install` run by an agent) arrives at the fast passthrough
+# below with the account already chosen, not at the selection path where the mirror
+# lives. That is the very write the 2026-09-22 outage was made of, in the place MCP
+# servers are most often installed. The account is known, so the same mirror applies:
+# exits inside when it handled the run; anything else stays byte-identical passthrough.
+mcp_nested_mirror() {
+  [ -f "$MANIFEST" ] || return 1
+  [ "${CLAUDE_MULTIACC_DISABLE:-0}" = "1" ] && return 1
+  [ "${CLAUDE_MULTIACC_MCP:-1}" = "0" ] && return 1
+  [ -n "${CLAUDE_CONFIG_DIR:-}" ] || return 1
+  local verb="${1:-}" cfg="${CLAUDE_CONFIG_DIR%/}" d=""
+  if [ "$verb" = "--model" ]; then verb="${3:-}"; fi
+  [ "$verb" = "mcp" ] || return 1
+  # A DIRECT child of the pool root, by its given spelling or its physical one (an
+  # adopted account is a symlink whose target is the operator's ~/.claude).
+  case "$cfg" in
+    "$ACC_ROOT"/acct-*) case "${cfg#"$ACC_ROOT"/}" in */*) ;; *) d="$cfg" ;; esac ;;
+  esac
+  if [ -z "$d" ]; then
+    local root_c; root_c="$(canon_path "$ACC_ROOT")"
+    case "$(canon_path "$cfg")" in
+      "$root_c"/acct-*) case "${cfg##*/}" in acct-*) d="$cfg" ;; esac ;;
+    esac
+  fi
+  [ -n "$d" ] && [ -d "$d" ] || return 1
+  mcp_mirror_run "$d" "$@"
+}
+
 # Fast passthrough: caller pinned a config dir or token, addon disabled, recursion
 # guard, or no account data yet. Byte-identical behavior to stock claude.
 if [ -n "${CLAUDE_CONFIG_DIR:-}" ] || [ -n "${CLAUDE_CODE_OAUTH_TOKEN:-}" ] \
   || [ "${CLAUDE_MULTIACC_DISABLE:-0}" = "1" ] || [ -n "${CLAUDE_SHIM_ACTIVE:-}" ] \
   || [ ! -f "$MANIFEST" ]; then
+  mcp_nested_mirror "$@" || true
   exec "$REAL" "$@"
 fi
 
@@ -92,12 +198,6 @@ fi
 # complaining to stderr.
 case "$CLAUDE_MULTIACC_THRESHOLD" in ''|*[!0-9]*|??????*) CLAUDE_MULTIACC_THRESHOLD=90 ;; esac
 
-if [ "$(uname -s)" = "Darwin" ]; then
-  file_mtime() { stat -f %m "$1" 2>/dev/null || echo 0; }
-else
-  file_mtime() { stat -c %Y "$1" 2>/dev/null || echo 0; }
-fi
-
 # ---- macOS Keychain-held logins ----------------------------------------------------
 # Claude Code on macOS moves a config dir's OAuth login into the login Keychain
 # (service "Claude Code-credentials-<sha256(dir)[:8]>") the first time a GUI-session
@@ -1232,6 +1332,10 @@ if [ -n "${CLAUDE_ACCOUNT:-}" ]; then
       fi
       export CLAUDE_CODE_OAUTH_TOKEN="$tok"
     fi
+    # A pinned account carries every registered MCP server too, and a pinned
+    # `claude mcp add|remove` is mirrored like any other (exits inside).
+    mcp_ensure "$d"
+    mcp_mirror_run "$d" "$@" || true
     sel_capture_session "$d"
     exec "$REAL" "$@"
   fi
@@ -1572,6 +1676,8 @@ fi
 # CLAUDE_ACCOUNT pin deliberately does not: a pin is a caller overriding selection,
 # not a turn in the rotation.
 remember_pick "$pick"
+# The picked account carries every registered MCP server before the client starts.
+mcp_ensure "$pick"
 
 # Opportunistic limits refresh: non-blocking, throttled, backgrounded. The windows are
 # deliberately wide (10m, matching the 5m scheduled pass): the usage endpoint rate-limits
@@ -1648,6 +1754,15 @@ fi
 
 export CLAUDE_SHIM_ACTIVE=1
 
+# A `claude mcp add|add-json|remove` is run as a child under the picked account and
+# mirrored to every other one (exits inside); anything else falls through to exec.
+if [ "${1:-}" = "mcp" ] || { [ "${1:-}" = "--model" ] && [ "${3:-}" = "mcp" ]; }; then
+  export CLAUDE_CONFIG_DIR="$pick"
+  tok="$(acct_token "$pick")"
+  [ -n "$tok" ] && export CLAUDE_CODE_OAUTH_TOKEN="$tok"
+  mcp_mirror_run "$pick" "$@" || true
+fi
+
 # Auto-retry applies only to -p/--print runs with an alternative account available,
 # and only when stdin is finite (tty, regular file, or char device like /dev/null).
 # A service-spawned pipe that never EOFs must take the plain exec path, or the
@@ -1878,6 +1993,7 @@ while :; do
       # The account that actually serves the work is the one the next run should rotate
       # away from — not the one that bounced.
       remember_pick "$cur"
+      mcp_ensure "$cur"
       rotated=1
       attempt=2
       continue

package/bin/claude-accounts

@@ -14,6 +14,12 @@ while [ -L "$_self" ]; do
 done
 BIN_DIR="$(cd "$(dirname "$_self")" && pwd -P)"
 REPO_DIR="$(dirname "$BIN_DIR")"
+# Pin the provider here, the way codex-accounts pins codex: lib/common.sh defaults to
+# claude only when the variable is UNSET, and codex-accounts exports it — so a
+# claude-accounts started by codex-accounts (the `mcp --provider both` hop) inherited
+# `codex`, became a second codex CLI, hopped to "its sibling" claude-accounts again, and
+# forked itself to death ("fork: Resource temporarily unavailable").
+export MULTIACC_PROVIDER=claude
 # shellcheck source=lib/common.sh
 . "$REPO_DIR/lib/common.sh"
 
@@ -81,10 +87,10 @@ USAGE
                                             or runner daemon distributes.
   claude-accounts verify [--quick]          auth matrix; full mode runs `-p "reply OK"` per account
   claude-accounts limits [--quiet] [--force] [--json]
-      refresh usage buckets, apply >=90% markers. When a WEEKLY limit is at least
-      95% used or exhausted, automatically redeems the account's Claude Code limit
-      reset (/limit-reset) with an idempotent request — never for a five-hour
-      window alone, and not while the week refills on its own within 24h.
+      refresh usage buckets, apply >=90% markers. When the pool has parked an
+      account on a window its Claude Code limit reset (/limit-reset) refills,
+      redeems it with an idempotent request — unless every park lifts on its own
+      within the hour.
       Auto-refreshes long-expired
       OAuth access tokens via the refresh-token grant (rotated credential is
       persisted), so idle accounts keep fresh telemetry and stay selectable.
@@ -93,6 +99,30 @@ USAGE
   claude-accounts health                    limits + full verify + shim-on-PATH probe; logs to health.log
   claude-accounts self-update               update this npm/git install; logs to update.log
   claude-accounts post-sync                 (server side) seed dirs, fix perms, quick verify
+  claude-accounts mcp add <name> [--provider claude|codex|both] [--scope user|project]
+                          [--project PATH] [-e KEY=VAL]... [-H 'Header: v']...
+                          [--transport stdio|http] -- <command> [args...]   (or a URL)
+      register an MCP server for EVERY account: writes the pool's mcp-servers.json
+      registry, reconciles every account dir, syncs the registry to the server and
+      peers (their post-sync applies it). Default --provider both: the same server is
+      registered in the codex pool too (MCP servers are not provider-specific).
+      A stock `claude mcp add|add-json|remove` run under the shim is mirrored into
+      the registry the same way — it no longer lands in one random account.
+      -e takes ONE variable per flag (KEY=VAL; write $HOME/..., not ~/..., in a value).
+      Exit 3 = registry saved, but an account could not be reconciled (it is named on
+      stderr): the change still syncs; fix the account and run `mcp apply`.
+      On a replica pool the change lands in the machine-local overlay instead of the
+      synced registry — make registry changes on the source machine.
+  claude-accounts mcp add-json <name> '<json>' [--provider ...] [--scope ...]
+  claude-accounts mcp remove <name> [--provider ...] [--user-only] [--scope project --project PATH]
+      unregister AND retire EVERYWHERE: every account (fleet-wide after sync) drops the
+      server from user scope and from every project entry, even one that was hand-added
+      to a single account. --user-only spares project-local copies.
+  claude-accounts mcp list [--json]         effective registry (+ machine-local overlay)
+  claude-accounts mcp apply [--account-dir DIR]... [--all]
+                                            re-apply the registry now (repair drift)
+  claude-accounts mcp import-local --owner NAME   (stdin JSON) machine-local overlay for
+                                            a runner daemon; applied here, never synced
 
 ENV
   CLAUDE_ACCOUNTS_ROOT  pool root, overriding ~/.claude-accounts — one isolated pool
@@ -105,8 +135,9 @@ ENV
   CLAUDE_SHIM_RETRY=0   disable -p auto-retry
   CLAUDE_MULTIACC_DISABLE=1  bypass the shim entirely
   CLAUDE_MULTIACC_AUTO_RESET=0  disable automatic limit-reset redemption
-  CLAUDE_MULTIACC_RESET_MIN_HORIZON  seconds before the natural weekly reset
-                        inside which a reset is held (default 86400)
+  CLAUDE_MULTIACC_MCP=0  disable the MCP registry (no reconcile at seed/launch, no mirror)
+  CLAUDE_MULTIACC_RESET_MIN_HORIZON  a reset is held while every park lifts on
+                        its own within this many seconds (default 3600)
 EOF
 }
 
@@ -1541,6 +1572,10 @@ limits_distribute_now() {
     # never grants any. Erring toward exclusion is the safe direction here.
     [ -f "$d/.limited" ] && printf '%s/.limited\n' "$id" >> "$list"
   done
+  # The MCP registry rides along: a server the shim mirrored from a stock `claude mcp
+  # add` reaches every peer within one limits cadence, with no explicit sync. The
+  # machine-local overlay stays home (see sync_push_target).
+  [ -f "$ACC_ROOT/mcp-servers.json" ] && printf 'mcp-servers.json\n' >> "$list"
   if [ ! -s "$list" ]; then rm -f "$list"; return 0; fi
 
   local pushed=0 failed=0
@@ -2408,7 +2443,7 @@ for acct in manifest.get('accounts', []):
     if source == 'oauth':
         try:
             reset_result, reset_view = claude_reset.refresh_reset_credits(
-                d, aid, data, url, headers, say, int(now))
+                d, aid, data, url, headers, say, int(now), threshold)
         except Exception as e:
             say(f'{aid}: limit reset automation failed unexpectedly ({type(e).__name__}); '
                 f'failing open')
@@ -2893,6 +2928,14 @@ sync_push_target() {
     || fail "cannot reach $server"
   rsync -az "$MANIFEST" "$server:$sroot/accounts.json" >>"$ACC_ROOT/sync.log" 2>&1 \
     || fail "manifest push to $server failed"
+  # The pool's MCP registry rides with the manifest; the target's post-sync reconciles it
+  # into every account dir there. A missing local registry leaves the target's alone,
+  # and the machine-local overlay (mcp-servers.local.json, a runner daemon's own view
+  # of THIS Mac) never travels.
+  if [ -f "$ACC_ROOT/mcp-servers.json" ]; then
+    rsync -az "$ACC_ROOT/mcp-servers.json" "$server:$sroot/mcp-servers.json" >>"$ACC_ROOT/sync.log" 2>&1 \
+      || fail "MCP registry push to $server failed"
+  fi
 
   local id d
   for id in $(account_ids); do
@@ -3079,6 +3122,97 @@ EOF
   fi
 }
 
+# MCP servers for EVERY account (lib/mcp_registry.py). `add`/`add-json`/`remove` edit
+# this pool's registry under the mutate lock, reconcile every account, auto-sync, and
+# by default (--provider both) make the same change in the sibling provider's pool —
+# an MCP server is not provider-specific, and the operator wants it in both CLIs.
+# `list`/`apply`/`import-local` act on this pool alone; the overlay `import-local`
+# writes is machine-local by definition, so it is applied here and never synced.
+mcp_sibling_root() { # the other provider's pool root, by the same env precedence
+  if [ "$MULTIACC_PROVIDER" = "codex" ]; then
+    printf '%s\n' "${CLAUDE_ACCOUNTS_ROOT:-${CLAUDE_ACCOUNTS_DIR:-$HOME/.claude-accounts}}"
+  else
+    printf '%s\n' "${CODEX_ACCOUNTS_ROOT:-${CODEX_ACCOUNTS_DIR:-$HOME/.codex-accounts}}"
+  fi
+}
+cmd_mcp() {
+  require_manifest
+  local sub="${1:-}" provider=both before_dd=1 a rc=0 sibling sibling_root
+  local args=()
+  case "$sub" in
+    add|add-json|remove|list|apply|import-local) shift ;;
+    "") usage; return 1 ;;
+    *) die "unknown mcp subcommand: $sub (add, add-json, remove, list, apply, import-local)" ;;
+  esac
+  [ -f "$LIB_DIR/mcp_registry.py" ] || die "lib/mcp_registry.py is missing from this install"
+  case "$sub" in
+    list|apply|import-local)
+      "$PYBIN" "$LIB_DIR/mcp_registry.py" --root "$ACC_ROOT" --provider "$MULTIACC_PROVIDER" "$sub" "$@"
+      return $? ;;
+  esac
+  # --provider is OUR option: strip it, but only before a literal `--` — after it every
+  # word belongs to the MCP server's own command line and is passed through untouched.
+  while [ $# -gt 0 ]; do
+    a="$1"
+    if [ "$before_dd" = 1 ]; then
+      case "$a" in
+        --) before_dd=0 ;;
+        --provider)
+          [ $# -ge 2 ] || die "--provider needs a value: claude, codex or both"
+          provider="$2"; shift 2; continue ;;
+        --provider=*) provider="${a#--provider=}"; shift; continue ;;
+      esac
+    fi
+    args+=("$a"); shift
+  done
+  case "$provider" in
+    claude|codex|both) ;;
+    *) die "--provider must be claude, codex or both (got '$provider')" ;;
+  esac
+  if [ "$provider" = "$MULTIACC_PROVIDER" ] || [ "$provider" = both ]; then
+    mutate_lock || die "could not acquire the account lock — try again"
+    trap mutate_unlock EXIT
+    "$PYBIN" "$LIB_DIR/mcp_registry.py" --root "$ACC_ROOT" --provider "$MULTIACC_PROVIDER" "$sub" \
+      ${args[@]+"${args[@]}"}
+    rc=$?
+    mutate_unlock
+    trap - EXIT
+    # 3 = the registry WAS saved and some account could not be reconciled (a corrupt
+    # config, a layout the TOML editor refuses): the change still has to reach the
+    # server, the peers and the sibling pool, and `mcp apply` repairs the account once
+    # it is fixed. 1/2 = nothing was saved: stop here.
+    case "$rc" in
+      0) ;;
+      3) printf '%s: registry saved; some accounts were not reconciled — run: %s mcp apply\n' \
+           "$PROVIDER_CLI" "$PROVIDER_CLI" >&2 ;;
+      *) return "$rc" ;;
+    esac
+    auto_sync
+  fi
+  if [ "$provider" != "$MULTIACC_PROVIDER" ]; then
+    if [ "$MULTIACC_PROVIDER" = "codex" ]; then sibling=claude; else sibling=codex; fi
+    sibling_root="$(mcp_sibling_root)"
+    # With the DEFAULT (both), a machine without the sibling pool or CLI has nothing to
+    # mirror, and silently so — a codex-only Mac must not warn on every claude
+    # change. An EXPLICIT --provider codex asked for that pool by name: refuse loudly.
+    if [ ! -f "$sibling_root/accounts.json" ]; then
+      [ "$provider" = both ] && return "$rc"
+      die "no $sibling pool on this machine ($sibling_root/accounts.json is missing)"
+    fi
+    if [ ! -x "$BIN_DIR/$sibling-accounts" ]; then
+      [ "$provider" = both ] && return "$rc"
+      die "$sibling-accounts is not installed beside $PROVIDER_CLI"
+    fi
+    # The caller's no-sync request travels with the hop, in the sibling's spelling.
+    if [ "${CLAUDE_MULTIACC_NO_SYNC:-0}" = "1" ]; then export CODEX_MULTIACC_NO_SYNC=1; fi
+    local sib_rc=0
+    MULTIACC_PROVIDER="$sibling" "$BIN_DIR/$sibling-accounts" mcp "$sub" --provider "$sibling" \
+      ${args[@]+"${args[@]}"} || sib_rc=$?
+    [ "$rc" -eq 0 ] && rc="$sib_rc"
+  fi
+  return "$rc"
+}
+
 cmd_post_sync() {
   require_manifest
   local_pool_fixup
@@ -3194,11 +3328,13 @@ $shim_out"
 # distribution for as long as the arg loops rejected the flag. An UNKNOWN verb must still
 # FAIL, or the probe stops meaning what it says — so this list must hold exactly the verbs
 # the dispatcher below implements, and a test pins that both ways.
-_KNOWN_VERBS="list status add import export-credential export-cred import-credential import-cred adopt dedupe remove mint login expired relogin re-login sync verify limits post-sync health self-update"
+_KNOWN_VERBS="list status add import export-credential export-cred import-credential import-cred adopt dedupe remove mint login expired relogin re-login sync verify limits post-sync health self-update mcp"
 case " $_KNOWN_VERBS " in
   *" ${1:-help} "*)
+    # ...but never past a literal `--`: from there on the words belong to an MCP
+    # server's own command line (`mcp add … -- node s.js -h 127.0.0.1`).
     for _arg in "$@"; do
-      case "$_arg" in --help|-h) usage; exit 0 ;; esac
+      case "$_arg" in --) break ;; --help|-h) usage; exit 0 ;; esac
     done ;;
 esac
 
@@ -3224,6 +3360,7 @@ case "${1:-help}" in
   post-sync) shift; cmd_post_sync "$@" ;;
   health) shift; cmd_health "$@" ;;
   self-update) shift; cmd_self_update "$@" ;;
+  mcp) shift; cmd_mcp "$@" ;;
   help|--help|-h) usage ;;
   *) usage; exit 1 ;;
 esac