claude-multiacc 2.0.37 → 2.0.39

package/bin/codex

@@ -73,11 +73,112 @@ 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) -------------------------
+# Codex keeps MCP servers in CODEX_HOME (`<dir>/config.toml`), so under the pool there
+# is one MCP configuration per account — and a stock `codex mcp add` lands in ONE random
+# one. The pool's registry (mcp-servers.json, synced) 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, lib or a broken registry costs nothing but
+# the servers themselves. Same contract as bin/claude's mcp_ensure.
+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/config.toml"; 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
+  [ "${CODEX_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 codex apply --account-dir "$1" \
+    --fail-open --quiet >/dev/null 2>&1 </dev/null || true
+  return 0
+}
+
+# `codex mcp add|remove` writes ONE account's config.toml — 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
+  shift
+  [ "${1:-}" = "mcp" ] || return 1
+  case "${2:-}" in add|remove) ;; *) return 1 ;; esac
+  [ "${CODEX_MULTIACC_MCP:-1}" != "0" ] && [ -f "$MCP_PY" ] || return 1
+  mcp_ensure "$d"
+  snap="$(mktemp "${TMPDIR:-/tmp}/codex-mcp-snap.XXXXXX" 2>/dev/null)" || snap=""
+  if [ -n "$snap" ] && ! "$MCP_PYBIN" "$MCP_PY" --root "$ACC_ROOT" --provider codex 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 codex learn --account-dir "$d" \
+      --before "$snap" </dev/null \
+      || printf 'codex-multiacc: could not mirror the MCP change to the other accounts — run: codex-accounts mcp apply\n' >&2
+  elif [ "$rc" -eq 0 ]; then
+    printf 'codex-multiacc: could not mirror the MCP change to the other accounts — run: codex-accounts mcp apply\n' >&2
+  fi
+  [ -n "$snap" ] && rm -f "$snap" 2>/dev/null
+  exit "$rc"
+}
+
+# A pooled SESSION exports CODEX_HOME=<acct> and CODEX_SHIM_ACTIVE=1, and every child
+# process inherits both — so a `codex 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
+  [ "${CODEX_MULTIACC_DISABLE:-0}" = "1" ] && return 1
+  [ "${CODEX_MULTIACC_MCP:-1}" = "0" ] && return 1
+  [ -n "${CODEX_HOME:-}" ] || return 1
+  local verb="${1:-}" cfg="${CODEX_HOME%/}" d=""
+  [ "$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, addon disabled, recursion guard, or
 # no account data yet. Byte-identical behavior to stock codex.
 if [ -n "${CODEX_HOME:-}" ] \
   || [ "${CODEX_MULTIACC_DISABLE:-0}" = "1" ] || [ -n "${CODEX_SHIM_ACTIVE:-}" ] \
   || [ ! -f "$MANIFEST" ]; then
+  mcp_nested_mirror "$@" || true
   exec "$REAL" "$@"
 fi
 
@@ -94,13 +195,6 @@ fi
 # complaining to stderr.
 case "$CODEX_MULTIACC_THRESHOLD" in ''|*[!0-9]*|??????*) CODEX_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
-
-
 # A number this shim will do ARITHMETIC on: digits only, and short enough that bash
 # cannot go out of range. An over-range value makes `[ x -lt y ]` print
 # "integer expression expected" on stderr — which a service-spawned run must never see —
@@ -645,6 +739,10 @@ if [ -n "${CODEX_ACCOUNT:-}" ]; then
     share_state_index "$d"
     export CODEX_HOME="$d"
     export CODEX_SHIM_ACTIVE=1
+    # A pinned account carries every registered MCP server too, and a pinned
+    # `codex mcp add|remove` is mirrored like any other (exits inside).
+    mcp_ensure "$d"
+    mcp_mirror_run "$d" "$@" || true
     exec "$REAL" "$@"
   fi
   sel_log "pin-invalid account=$CODEX_ACCOUNT (no such dir; random fallback)"
@@ -874,6 +972,8 @@ pick="$PICK_DIR"
 # CODEX_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
@@ -902,6 +1002,14 @@ sel_log "$acct weekly=$(fresh_field "$pick" weekly_percent || echo '?')%" \
 
 export CODEX_SHIM_ACTIVE=1
 
+# A `codex mcp add|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" ]; then
+  share_state_index "$pick"
+  export CODEX_HOME="$pick"
+  mcp_mirror_run "$pick" "$@" || true
+fi
+
 # Auto-retry applies only to `codex exec` 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
@@ -1033,6 +1141,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"
       attempt=2
       continue
     fi

package/bin/codex-accounts

@@ -89,8 +89,10 @@ USAGE
                                             `codex exec` per account
   codex-accounts limits [--quiet] [--force] [--json]
       refresh usage windows from the ChatGPT usage endpoint, apply >=90% markers.
-      When a fresh bucket is at least 95% used, automatically redeems an earned
-      usage-limit reset if the account has one, using an idempotent request.
+      When the pool has parked the account (a window at/over the threshold, a
+      finished limit, or a client-reported limit that lifts more than an hour from
+      now), automatically redeems an earned usage-limit reset if the account has
+      one, using an idempotent request.
       Auto-refreshes long-expired access tokens via the OAuth refresh-token grant
       (rotated credential is persisted), so idle accounts keep fresh telemetry and
       stay selectable. Skips accounts fetched in the last 45s and honors
@@ -98,6 +100,32 @@ USAGE
   codex-accounts health                     limits + full verify; logs to health.log
   codex-accounts self-update                update this npm/git install; logs to update.log
   codex-accounts post-sync                  (server side) seed dirs, fix perms, quick verify
+  codex-accounts mcp add <name> [--provider claude|codex|both] [--scope user]
+                          [-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 ([mcp_servers.<name>] in every account's config.toml), syncs the
+      registry to the server and peers (their post-sync applies it). Default
+      --provider both: the same server is registered in the claude pool too.
+      A stock `codex mcp add|remove` run under the shim is mirrored into the
+      registry the same way — it no longer lands in one random account.
+      Project scope is claude-only: Codex reads no per-project MCP config.
+      -e takes ONE variable per flag (KEY=VAL). Exit 3 = registry saved, but an account
+      could not be reconciled (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.
+      The codex registry syncs only to codex sync targets; a runner Mac's local-only
+      codex pool is fed by app-robot's overlay (`mcp import-local --owner app-robot`).
+  codex-accounts mcp add-json <name> '<json>' [--provider ...]
+  codex-accounts mcp remove <name> [--provider ...] [--user-only]
+      unregister AND retire EVERYWHERE: every account (fleet-wide after sync) drops the
+      server, even one that was hand-added to a single account (--user-only spares a
+      claude project-local copy in the claude pool).
+  codex-accounts mcp list [--json]          effective registry (+ machine-local overlay)
+  codex-accounts mcp apply [--account-dir DIR]... [--all]
+                                            re-apply the registry now (repair drift)
+  codex-accounts mcp import-local --owner NAME   (stdin JSON) machine-local overlay for
+                                            a runner daemon; applied here, never synced
 
 ENV
   CODEX_ACCOUNTS_ROOT   pool root, overriding ~/.codex-accounts — one isolated pool
@@ -110,6 +138,7 @@ ENV
   CODEX_SHIM_RETRY=0    disable the `codex exec` auto-retry
   CODEX_MULTIACC_DISABLE=1  bypass the shim entirely
   CODEX_MULTIACC_AUTO_RESET=0  disable automatic usage-reset redemption
+  CODEX_MULTIACC_MCP=0   disable the MCP registry (no reconcile at seed/launch, no mirror)
 EOF
 }
 
@@ -1620,7 +1649,8 @@ for acct in manifest.get('accounts', []):
     if sessionp is None and live:
         sessionp = 0
     try:
-        reset_result, reset_view = refresh_reset_credits(d, aid, maxp, data, url, headers, say, int(now))
+        reset_result, reset_view = refresh_reset_credits(d, aid, maxp, data, url, headers, say,
+                                                         int(now), threshold)
     except Exception as e:
         say(f'{aid}: usage reset automation failed unexpectedly ({type(e).__name__}); failing open')
         reset_result = {'status': 'error'}
@@ -1998,6 +2028,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
@@ -2185,6 +2223,97 @@ EOF
   fi
 }
 
+# MCP servers for EVERY account (lib/mcp_registry.py) — the codex twin of
+# claude-accounts' cmd_mcp. `add`/`add-json`/`remove` edit this pool's registry under
+# the mutate lock, reconcile every account's config.toml, auto-sync, and by default
+# (--provider both) make the same change in the claude pool. `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 claude-only Mac must not warn on every codex
+    # change. An EXPLICIT --provider claude 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 [ "${CODEX_MULTIACC_NO_SYNC:-0}" = "1" ]; then export CLAUDE_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
@@ -2303,11 +2432,13 @@ PYEOF
 # 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 login expired relogin re-login sync configure verify limits post-sync health self-update init-pool"
+_KNOWN_VERBS="list status add import export-credential export-cred import-credential import-cred adopt dedupe remove login expired relogin re-login sync configure verify limits post-sync health self-update init-pool 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
 
@@ -2332,6 +2463,7 @@ case "${1:-help}" in
   health) shift; cmd_health "$@" ;;
   self-update) shift; cmd_self_update "$@" ;;
   init-pool) shift; cmd_init_pool "$@" ;;
+  mcp) shift; cmd_mcp "$@" ;;
   help|--help|-h) usage ;;
   *) usage; exit 1 ;;
 esac

package/docs/ACCOUNT_OPERATIONS.md

@@ -165,6 +165,40 @@ set, which is what prevents two machines from overwriting each other's manifests
 Make account changes on the source; sign-ins (`login`/`relogin`) still happen on
 whichever machine needs the credential.
 
+### MCP servers for every account
+
+MCP servers live in the config dir, i.e. per account. Never register one with a stock
+`claude mcp add` on a pool Mac and expect it everywhere — under the shim that command is
+mirrored into the registry (see below), but the registry is the source of truth, and it is
+edited on the **source** machine (a replica's own changes land in its machine-local overlay
+and are not pushed anywhere):
+
+```bash
+claude-accounts mcp add appinspire-mcp -- npx -y appinspire-mcp@latest serve
+    # writes ~/.claude-accounts/mcp-servers.json AND ~/.codex-accounts/mcp-servers.json,
+    # reconciles every account of both pools, auto-syncs the registry to server + peers
+claude-accounts mcp add --provider claude --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
+    # a checkout, registered for ONE project (claude only: codex reads no project config);
+    # one -e per variable, and $HOME rather than ~ inside a value
+claude-accounts mcp remove adspower-local-api   # retire EVERYWHERE: user scope + every project entry, hand-added copies too
+claude-accounts mcp remove foo --user-only      # user scope only
+claude-accounts mcp list                        # effective registry (+ machine-local overlay)
+claude-accounts mcp apply                       # re-apply to every account now (exit 3 from add/remove = do this after fixing the account it named)
+codex-accounts mcp list                         # the codex pool's view
+```
+
+How a fleet Mac receives it: `sync` (and every claude limits pass) pushes the claude
+`mcp-servers.json` next to the manifest to the server and every peer; the target's
+`post-sync` re-seeds its account dirs, which applies the registry; and the shim there
+re-applies it to the picked account right before exec whenever the file changed. The codex
+registry travels only to codex sync targets (the server, gas-mini) — runner Macs' codex pools
+are local-only and are fed by app-robot's runner overlay (`codex-accounts mcp import-local
+--owner app-robot`) or a direct `codex-accounts mcp add --provider codex …` on that Mac. A
+runner daemon's overlay (`<provider>-accounts mcp import-local --owner NAME`, JSON on stdin)
+is applied on the Mac and never synced. `--help` on `mcp` lists every option;
+`CLAUDE_MULTIACC_MCP=0` / `CODEX_MULTIACC_MCP=0` stop the reconcile at seed and launch and the
+shim's mirror (the CLI, sync and fan-out keep working).
+
 ### Pointing sync somewhere else (or nowhere)
 
 The target is no longer baked in. In precedence order:

package/docs/CODEX.md

@@ -44,8 +44,9 @@ Codex-specific notes:
   own public client id) and the rotated credential is persisted 0600. Overrides for
   tests: `CODEX_MULTIACC_TOKEN_URL`, `CODEX_MULTIACC_CLIENT_ID`,
   `CODEX_MULTIACC_USAGE_URL`.
-- **Earned usage resets are redeemed automatically at 95% used** (5% remaining) or
-  when the backend reports the limit finished. The limits refresher checks the reset
+- **Earned usage resets are redeemed automatically for a parked account:** a bucket
+  at/over the pool's exclusion threshold (90%), a limit the backend reports finished, or
+  an active usage park (a client-reported 429) that lifts more than an hour from now. The limits refresher checks the reset
   credits belonging to that same account, uses the soonest-expiring available credit,
   and writes a per-account/window idempotency key before redemption so a lost response
   or simultaneous fleet poll cannot spend a second reset. Set
@@ -82,6 +83,32 @@ codex-accounts --help                 # all account commands and options
 claude-multiacc codex status          # same status command via the npm wrapper
 ```
 
+## MCP servers for every account
+
+`codex-accounts mcp add|add-json|remove|list|apply|import-local` manages the pool's MCP
+registry (`~/.codex-accounts/mcp-servers.json`); `add`/`remove` default to `--provider both`,
+so the claude pool beside it gets the same change, and `mcp remove` retires the server in
+every account (`--user-only` keeps a claude project-local copy). A stock `codex mcp add|remove`
+run under the shim — or from inside a pooled codex session — is mirrored into the registry and
+every account; on a replica pool the mirror lands in the machine-local overlay instead, so
+make registry changes on the source. The registry holds Claude-style blocks; for codex each
+becomes a `[mcp_servers.<name>]` table in every account's `config.toml`, and unrelated
+tables, their comments and blank lines are left alone: `command`/`args` as is, literal `env`
+values as an inline `env` table, a `KEY=${KEY}` reference as `env_vars = ["KEY"]` (codex
+forwards a variable under its own name only and expands nothing, so `KEY=${OTHER}` and
+`${VAR:-default}` cannot be expressed and are left out with a warning), `headers` on an HTTP
+server as `http_headers` (literal) / `env_http_headers` (references), `Authorization: Bearer
+${VAR}` as `bearer_token_env_var`, and, for a stdio server, `startup_timeout_sec = 60` unless
+the block sets one (a cold `npx` download must not trip codex's 10 s default). Codex-only keys
+codex itself wrote (`oauth`, `enabled_tools`, …) ride along in the registry block and never
+reach `.claude.json`. SSE transports cannot be expressed and are skipped with a warning;
+project scope is claude-only because Codex 0.156 reads no per-project MCP config. Python
+3.11+ is found the same way as for `configure`. `CODEX_MULTIACC_MCP=0` stops the reconcile at
+seed and launch and the mirror; the CLI keeps working. The codex registry syncs only to codex
+sync targets — a runner Mac's local-only codex pool gets its servers from app-robot's runner
+overlay (`mcp import-local --owner app-robot`) or a direct `codex-accounts mcp add
+--provider codex …` there.
+
 ## Opt-in subagent concurrency policy
 
 The addon does not choose delegation policy by default. To manage the concurrent