diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index f39120498..835cb8b40 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -894,6 +894,17 @@ Tokens are omitted from durable workspace metadata. Launch configuration avoids
 
 Sources: [HTTP host](src/mcp/runtime/BuiltInMcpHttpHost.ts), [tool registrar](src/mcp/runtime/createBuiltInMcpServer.ts), [launch configuration](src/providers/shared/runtime/builtInMcpLaunch.ts).
 
+**User MCP servers (#1143).** Users can also attach their own MCP servers to Claude and Codex agents.
+
+- **Storage.** Main owns them in `mcp-servers.json`, stored in the de facto `mcpServers` entry shape. Secret values live in separate `safeStorage` blobs, and entries refer to them as `${input:id}`.
+- **Launch.** The renderer sends only a pane's explicit per-agent choices, as `user:<id>` keys in the same override map as built-in domains. At launch, main applies the per-provider defaults, secret readiness, transport support, Codex name collisions and Claude's enterprise MCP policy. It passes the result to the providers.
+- **Claude.** User entries are added to the same private config file as the built-in server. Secrets are `${VAR}` references expanded from the process environment.
+- **Codex.** User servers become `--config mcp_servers.<name>.*` overrides. Header values go through `env_http_headers`, and stdio secrets through `env_vars`.
+- **Failure handling.** A requested server that cannot attach is reported (`user-mcp-unavailable`) and never fails the launch. The attached ids are an observed backend fact (`userMcpServerIds`), like `builtInMcpDomains`.
+- **Config files.** Provider config files are never written. The user-scope servers each CLI loads itself are only read, to list them and to detect collisions.
+
+Sources: [service](src/main/userMcp/service.ts), [translators](src/providers/shared/runtime/userMcpLaunch.ts), [model and import](src/shared/userMcp), [design](docs/superpowers/specs/2026-09-22-user-mcp-servers-design.md).
+
 #### 5.6.2 Domains and scope
 
 | Domain | Tools/responsibility | Scope notes |
diff --git a/README.md b/README.md
index 130f7cbc4..f41f929de 100644
--- a/README.md
+++ b/README.md
@@ -91,23 +91,31 @@ a running session can move mid-task among Claude Code, Codex, and OpenCode.
     <img src="docs/screenshots/orchestration.png" alt="Agent Code agent index with orchestration MCP tool calls (send_prompt, wait_agents, read_agent, close_run) running in a live session" />
   </p>
 
-- **TLDR peek** — enable **TLDR MCP** for an agent, then hold **Cmd+L** to
+- **MCP servers** — add any MCP server (stdio, HTTP or SSE) by pasting the
+  config from its README, for example Beeper Desktop's, and choose per provider
+  which ones new Claude and Codex agents get. **Settings → MCP** shows Agent
+  Code's own MCP servers and yours in one grid with a column per provider, and
+  **Agent MCP Servers…** changes one agent's set with a single reload. Tokens
+  are stored encrypted and reach the server through environment variables,
+  never a config file or the command line. Servers the CLIs already load from
+  their own config are listed read-only and can be copied in.
+- **TLDR peek** — turn on **TLDR** for an agent, then hold **Cmd+L** to
   see each visible agent’s latest short status centered over its pane.
   A small footer shows **Last active** and **Note written** independently, using
   relative times and calendar dates for older activity. Release to return. The
   **TLDR** palette command also opens the preview; Escape dismisses it. Reporting
   is off by default. MCP settings apply to new agents and existing agents on their
   next reload, including the managed reporting skill. Explicit per-agent choices
-  take priority; **Use Global MCP Settings** clears those choices and reloads the
+  in **Agent MCP Servers…** take priority; its Reset clears them and reloads the
   agent. Claude and Codex agents with TLDR are asked to set their goal on the
   first prompt (through Goal instead when Goal MCP is also on), and at turn end to update after work that used tools without a
   report; the footer notes when that check is not running. **View TLDR History**
   shows how an agent's status evolved. The editor keeps Cmd+L Select Line.
-- **Goal peek** — enable **Goal MCP** for an agent, then hold **Cmd+G** to see
+- **Goal peek** — turn on **Goal** for an agent, then hold **Cmd+G** to see
   what each visible agent’s work is for, next to the TLDR’s where-it-is status.
   Agents set a goal once they understand a task and change it only when the
   direction changes, so it stays meaningful while the TLDR moves. Goal has its
-  own MCP setting, off by default, and works with or without TLDR; only the agent
+  own row in Settings → MCP, and works with or without TLDR; only the agent
   writes it. Claude and Codex agents with Goal are asked for one at the first
   prompt and at turn end if it is still missing. **View TLDR History** shows goal
   changes alongside status updates. The editor keeps Cmd+G Find Next.
diff --git a/docs/superpowers/plans/2026-09-22-user-mcp-servers.md b/docs/superpowers/plans/2026-09-22-user-mcp-servers.md
new file mode 100644
index 000000000..422abbd1e
--- /dev/null
+++ b/docs/superpowers/plans/2026-09-22-user-mcp-servers.md
@@ -0,0 +1,119 @@
+# MCP Servers: Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task by task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** One MCP interface for every MCP server. Users can:
+- add any MCP server by pasting its README snippet;
+- keep its secrets encrypted;
+- choose per provider which servers new agents get, for Agent Code's built-in servers and their own alike;
+- override those choices per agent with one staged reload;
+- see and copy in the servers the CLIs already load directly.
+
+Agents receive user servers when they launch, through the path the built-in MCP servers already use. Provider config files are never written.
+
+**Spec:** `docs/superpowers/specs/2026-09-22-user-mcp-servers-design.md`. Its **Revision 2** section overrides anything in the rest of the spec that conflicts with it. Read Evidence, Decisions and Revision 2 before starting any task.
+
+**Issue:** #1143 (Refs #244). **Status:** user-approved 2026-09-22 (plan auto-approved); Tasks 1–8 implemented on this branch. Verification notes are in the PR.
+
+**Working tree:** `.worktrees/user-mcp-servers`, branch `feat/user-mcp-servers`, based on `origin/main` `672d0941`. Submodules are initialized and `node_modules` is symlinked. Use Node 24 for vitest, because Node 25 breaks happy-dom.
+
+**Conventions:**
+- Write thick WHY comments at every code site that enforces a decision.
+- Use Conventional Commits with scope `mcp`.
+- Test fixtures are the real published Beeper snippets.
+- Verify with `npx tsc -b` and vitest once at the end.
+- Never launch the app.
+
+---
+
+### Task 1: Shared model (`src/shared/userMcp/`)
+- [x] `types.ts`:
+  - `UserMcpServer`, `UserMcpServerEntry`, `UserMcpInput` and `UserMcpDocument`.
+  - The view and problem types.
+  - `USER_MCP_PROVIDERS` (`claude`, `codex`) and the reserved names.
+  - `userMcpOverrideKey(id)` and `userMcpOverridesFrom(map)`.
+- [x] `validate.ts`:
+  - Name rules, entry validation and type normalization.
+  - The rule that `${input:…}` may appear only in `env` and `headers` values.
+  - The support matrix (SSE is Claude-only).
+  - `coerceUserMcpDocument`, which keeps unknown keys and flags malformed servers instead of dropping them.
+- [x] `inputs.ts`: scan and substitute `${input:id}`.
+- [x] `importConfig.ts`:
+  - Accepts the `mcpServers`, VS Code `servers`/`inputs`, bare-map and bare-entry forms.
+  - Moves every literal env and header value into a secret input, returned as `pendingSecrets`.
+- [x] Tests for each of the above, using the Beeper fixtures.
+
+### Task 2: Launch translators (`src/providers/shared/runtime/userMcpLaunch.ts`)
+- [x] `userMcpSecretVariable`: deterministic variable names (needed so Claude's OAuth key stays stable).
+- [x] `claudeUserMcpEntries`: builds Claude's config entries.
+- [x] `addCodexUserMcpLaunchConfig`: builds the Codex arguments, and drops a server whose `env_vars` collide with another's.
+- [x] Widen `createPrivateClaudeMcpConfig(builtIns, userEntries)`.
+- [x] Golden tests, including one asserting that no secret appears in argv.
+
+### Task 3: Main service (`src/main/userMcp/`)
+- [x] `store.ts`: an atomic write of `STATE_DIR/mcp-servers.json` with mode 0600. A corrupt file is preserved rather than overwritten.
+- [x] `secrets.ts`: `safeStorage` blobs, with only a hint ever returned.
+- [x] `nativeServers.ts`:
+  - Lists the CLIs' own user-scope servers for Claude and Codex.
+  - Collects the Codex names used for the collision check.
+  - Detects Claude's managed-policy lock.
+- [x] `service.ts`:
+  - Snapshot and mutations, run through a serialized queue.
+  - `resolveForLaunch(provider, overrides, cwd)`, which returns `{ servers, attachedIds, dropped }`.
+  - A change emitter.
+- [x] IPC in `src/main/ipc/userMcp.ts`, the preload API in `src/preload/api/userMcp.ts`, and wiring in `src/main/index.ts`.
+- [x] Tests for the store, secrets, resolution and native parsing.
+
+### Task 4: Session wiring (main and providers)
+- [x] Add `userMcpOverrides` to the spawn and recover options.
+- [x] Add `userMcpServerIds` to the snapshot, spawn result and recover result.
+- [x] `SessionManager` resolves user servers beside `builtInMcpServers` and records the attached ids per session.
+  - The Codex replacement restore reuses the recorded overrides.
+  - It emits `user-mcp-unavailable`, which the forwarder broadcasts.
+- [x] Claude and Codex sessions accept `userMcpServers`.
+- [x] Tests: a missing secret still spawns; the token is absent from argv.
+
+### Task 5: Renderer model
+- [x] Per-provider `defaultBuiltInMcpDomains`, covering:
+  - type and coercion;
+  - the resolver picking the provider's list;
+  - the refs input type;
+  - the `store.ts` comment.
+- [x] `normalizeBuiltInMcpOverrides` keeps `user:` keys.
+- [x] `clonedMcpOverrides` keeps them too.
+- [x] Every renderer spawn and recover call site sends `userMcpOverrides`, and the pane meta stores `userMcpServerIds`.
+- [x] `features/mcp/store.ts`: a mirror of main's snapshot plus a sync hook, mounted in `App.tsx`.
+- [x] Global toast for `user-mcp-unavailable`.
+
+### Task 6: Settings → MCP
+- [x] Add the `mcp` category.
+- [x] Add the `mcp-servers` marker row, which replaces the eight built-in default toggle rows.
+- [x] Move `external-control` into the new category.
+- [x] `McpServersRow`:
+  - The grid of built-in and user servers, with a column per enabled provider.
+  - Master switches, problem chips, and the ⋯ actions.
+  - The native section with Copy in.
+- [x] `McpServerDialog`:
+  - Add and edit, with paste import and a JSON editor.
+  - Masked secret fields.
+  - Sign in help shows a copyable `codex mcp login <name> -c 'mcp_servers.<name>.url=…'` command and Claude `/mcp` guidance. Changed during implementation: the command is shown rather than run in a new terminal pane, because login opens a browser and waits on the user, and that belongs in a terminal the user controls. Codex login reads the effective config including `-c`, so the stored token is reused by every later launch.
+- [x] `ui.openSettings(category?)`.
+
+### Task 7: Commands and the per-agent modal
+- [x] `AgentMcpServersModal` and its surface: staged toggles, one reload, a reset row, and Root Management going through its confirmation dialog.
+- [x] New commands: `mcp-servers`, `add-mcp-server` and `agent-mcp-servers`.
+- [x] Retire `use-global-mcp-settings` and the eight `enable-*-mcp` toggles.
+- [x] Update the control references, `catalog.test.ts`, `taxonomy.test.ts` and the affected renderer tests.
+
+### Task 8: Documentation, verification and PR
+- [x] Update README and ARCHITECTURE.
+- [x] Run `npx tsc -b` and vitest.
+- [x] Real-binary check of the generated Codex `-c` arguments with `codex mcp list`.
+- [ ] Open the PR `feat(mcp): manage MCP servers per provider and per agent` with `Fixes #1143` and `Refs #244`. Run two orchestrated reviewers, fix the valid findings, wait for CI, and do not merge.
+
+## Out of scope (follow-up issues)
+- Add from MCP Registry.
+- OpenCode and Grok user servers.
+- User servers for workflow subagents.
+- Project-scope native server listing.
+- #244 hosted extension servers.
diff --git a/docs/superpowers/specs/2026-09-22-user-mcp-servers-design.md b/docs/superpowers/specs/2026-09-22-user-mcp-servers-design.md
new file mode 100644
index 000000000..ef4d501ec
--- /dev/null
+++ b/docs/superpowers/specs/2026-09-22-user-mcp-servers-design.md
@@ -0,0 +1,518 @@
+# User MCP servers — design
+
+Status: draft for review · Date: 2026-09-22 · Branch: `feat/user-mcp-servers`
+Issue: #1143 (Refs #244)
+
+## Revision 2: one interface for every MCP server (user-approved 2026-09-22)
+
+The user reviewed ASCII mockups and approved a unified interface. It also
+covers Agent Code's own built-in MCP servers. Where this section conflicts
+with anything below, **this section wins**.
+
+1. **One grid for all servers.** Settings → MCP lists Agent Code's built-in
+   servers (TLDR, Goal, Goal Loop, Orchestration, Agent Transcripts, Agent
+   Management, AI Workspace, Workflows) and the user's servers in **one grid**
+   with the same per-provider columns.
+   - The rule for every cell is: *new agents of this provider get it*.
+   - `—` marks a server that provider can't use, with the reason shown.
+   - Root Management is listed as per-agent only; it is never a default.
+   - A provider column appears only when that provider is enabled in
+     Settings → Providers.
+   - Built-in cells cover all four providers, because every launcher carries
+     built-ins. User-server cells for OpenCode and Grok show `—` "Not
+     supported yet", which is honest and keeps the grid rectangular.
+2. **Per-provider built-in defaults.** `settings.defaultBuiltInMcpDomains`
+   changes from one flat list to
+   `Record<AgentProviderKind, ConfigurableBuiltInMcpDomain[]>`.
+   - Coercion copies a legacy flat list to every provider, so nobody's
+     current behavior changes on upgrade.
+   - The resolver still accepts a flat list, meaning "every provider". That
+     keeps orchestration, control and test callers that pass an explicit list
+     valid without a parallel API.
+3. **One per-agent override map.** Per-agent choices for user servers live in
+   the **same** `builtInMcpOverrides` map, under namespaced keys
+   `user:<serverId>`.
+   - That map already travels through spawn, replace, reload, recovery,
+     undo-close, provider switch, duplicate and the control API. Giving user
+     servers a second parallel map would mean re-threading every one of those
+     paths, and missing one silently drops a choice.
+   - The field name stays as it is, because renaming a persisted workspace
+     field needs a migration.
+   - The type is widened, and a WHY comment at the type explains it.
+4. **Main decides which user servers attach.** The renderer sends only the
+   `user:` subset of the pane's overrides (`userMcpOverrides`) with
+   spawn/recover. Main applies its own store's defaults (the master switch
+   and per-provider flags), overrides, readiness and support.
+   - This replaces the earlier "renderer resolves ids" contract. Main owns
+     the store and the secrets, so letting a stale renderer snapshot decide
+     would add a second authority for no benefit.
+   - Main records the attached ids per session and reports them as
+     `userMcpServerIds` on the session snapshot, spawn result and recover
+     result, exactly like `builtInMcpDomains`.
+5. **One `Agent MCP Servers…` modal.** It lists built-in and user servers for
+   the focused agent, **stages** the toggles, and applies them with **one**
+   reload. "Reset to MCP settings defaults" clears every override.
+   - Root Management in this modal still goes through its confirmation
+     dialog. Applying a staged Root Management grant opens that dialog, and
+     the dialog performs the reload with all the staged choices.
+   - It **retires** `use-global-mcp-settings` and the eight
+     `enable-*-mcp` toggles: AI Workspace, Orchestration, Agent Transcripts,
+     Agent Management, TLDR, Goal, Goal Loop and Workflow.
+   - `enable-root-agent-code-management` (a confirmation-gated command whose
+     id other code refers to) and the debug-only `enable-built-in-mcp-ping`
+     stay.
+6. **Other commands.**
+   - `MCP Servers` opens Settings on the MCP category. `ui.openSettings`
+     gains an optional category.
+   - `Add MCP Server…` opens the add dialog.
+7. **Read-only list of servers the CLIs load directly, now in v1.** It shows
+   user-scope `mcpServers` from `~/.claude.json` (honoring
+   `CLAUDE_CONFIG_DIR`) and `[mcp_servers]` from
+   `${CODEX_HOME:-~/.codex}/config.toml`, each with a **Copy in** action
+   that imports it as a managed server.
+   - Project-scope files depend on the cwd, so Settings (which has no cwd)
+     doesn't list them.
+   - The Codex collision check still reads both the user file and
+     `<cwd>/.codex/config.toml` at spawn.
+8. **Unavailable notice.** A user server that can't attach is broadcast as
+   `user-mcp-unavailable { servers: [{ name, reason }] }` and shown by the
+   global toast, with the same repeat window as `managed-skills-unavailable`.
+9. **External operator MCP** moves unchanged into the MCP category.
+
+## Problem
+
+Agent Code cannot add, configure, or switch off a third-party MCP server. The
+only MCP servers it knows about are its own: the `agent_code` built-in host
+(TLDR, Goal, orchestration, …) and the reserved `agent-code-control` external
+operator server. A user who wants, say, the Beeper Desktop MCP server attached to
+their agents today has to leave the app and hand-edit `~/.claude.json` or
+`~/.codex/config.toml` (or run `claude mcp add` / `codex mcp add`). They then
+get it on *every* agent of that provider, can't switch it off for one agent,
+can't see it anywhere in Agent Code, and have to repeat the work per provider.
+
+Wanted: a single place in Agent Code to add **any** MCP server (stdio,
+Streamable HTTP, SSE; with secrets; OAuth-capable), choose which providers it
+attaches to, override it per agent, and flip it on/off from Settings and the
+command palette. The scope is **Claude Code and Codex**. Beeper Desktop is the
+worked example and acceptance fixture, not a special case.
+
+This complements the provider enablement feature (#1126, Settings →
+Providers). Enablement decides which providers exist in the app, and this
+feature decides which user MCP servers each of them gets.
+
+## Evidence this design rests on
+
+The research ran on 2026-09-22 and is summarized here so the next session
+doesn't have to redo it.
+
+### What Agent Code does today
+
+- **Built-in MCP.** One loopback Streamable-HTTP host
+  (`src/mcp/runtime/BuiltInMcpHttpHost.ts`) mints a per-session bearer and
+  returns one `BuiltInMcpServerConfig` named `agent_code`.
+  `SessionManager.spawn` (`src/main/sessionManager.ts:2875`) passes
+  `builtInMcpServers` into the provider's `createSession`.
+- **Per-launch injection, no durable writes**
+  (`src/providers/shared/runtime/builtInMcpLaunch.ts`):
+  - **Claude** gets a mode-0600 private temp `mcp.json`, passed as
+    `--mcp-config <path>` and deleted on stop or rollback
+    (`claudeSession.ts:1189-1202`).
+  - **Codex** gets `--config mcp_servers.<n>.url=…` plus
+    `env_http_headers.<H>="AGENT_CODE_MCP_i_j"`. Values go in the child env,
+    never in argv.
+  - **OpenCode** gets `OPENCODE_CONFIG_CONTENT` with `{env:…}` references.
+- **User-native servers already load.** `--strict-mcp-config` is deliberately
+  *not* used. Claude gets a targeted `deniedMcpServers` instead, inside the
+  **single** `--settings` value built by `excludeExternalControlFromClaude`
+  (`externalControlExclusion.ts:47-60`). Codex keeps the user's `CODEX_HOME`.
+  So whatever the user put in `~/.claude.json`, `.mcp.json` or
+  `config.toml` still loads, but Agent Code never reads, shows or edits it.
+- **Settings model for built-ins.**
+  - Global `settings.defaultBuiltInMcpDomains` lives in renderer
+    localStorage.
+  - Per-pane `builtInMcpOverrides` (absent means inherit, `false` means
+    explicit off) is resolved by `resolveSessionBuiltInMcpDomains`
+    (`src/renderer/src/workspace/mcpDomains.ts`).
+  - The pane's `builtInMcpDomains` is the *observed* launched set, not a
+    choice.
+  - Changes apply on the next spawn or reload through
+    `reloadSessionWithBuiltInMcpOverrides`.
+- **Codex `config.toml` writer precedent.** The only writer into provider-owned
+  config is `src/main/settings/externalCodexConfig.ts`: a hash-stamped managed
+  block, deep-equal proof that nothing else changed, refusal to touch a
+  same-name unmanaged server, and observed-compare atomic replace. It is about
+  130 lines of safety for **one** server. That cost is why this design does
+  not write provider config.
+- **Provider enablement (#1126)** is the store/IPC/broadcast pattern to copy:
+  - main-owned state with a coerce-on-load setter;
+  - `provider-enablement:get|set|reset` IPC plus a
+    `provider-enablement:changed` broadcast;
+  - a non-persisted zustand mirror in the renderer
+    (`features/providers/store.ts`) with a snapshot getter and a hook, synced
+    once from `App.tsx`;
+  - a self-subscribing settings "marker row" (`ProviderEnablementRow.tsx`).
+- **Secrets precedent.** `src/main/dictation/apiKeyStore.ts` uses Electron
+  `safeStorage` per-file blobs with no auth prompt; the renderer only sees a
+  last-4 hint. The key vault (`src/main/keyVault`) gates every read behind
+  Touch ID, which is wrong for secrets resolved during automatic restore.
+- **Open issue #244** ("Host user-authored MCP servers as Agent Code
+  extensions") is broader: Agent Code *hosting* author-written servers through
+  a manifest. This design is the configuration layer #244 needs anyway. A
+  hosted extension server can later appear as one more entry in the same list.
+
+### How the CLIs load MCP servers (vendor source + installed claude 2.1.280 / codex-cli 0.155.1)
+
+| | Claude Code | Codex |
+|---|---|---|
+| Per-launch injection | `--mcp-config <file\|json>…` (variadic, later wins, overrides all file scopes) | `-c mcp_servers.<n>.*=` (TOML-valued, deep-merged SessionFlags layer, precedence 30) |
+| Launch vs user entry, same name | Whole entry replaced | **Deep-merged key by key.** A user `command` plus our `url` becomes an invalid mixed-transport config, and the launch fails |
+| Transports | stdio, http, sse (deprecated), ws | stdio, streamable HTTP. **No SSE** |
+| Secret indirection | `${VAR}` / `${VAR:-d}` expanded in command, args, env, url, headers | No expansion. Use `env_vars=[names]` (stdio), `bearer_token_env_var`, `env_http_headers` |
+| stdio child env | Inherits Claude's full env plus `env` | Fixed allowlist (HOME, PATH, …) plus `env_vars` plus literal `env` |
+| Name charset | `[A-Za-z0-9_-]` | `[A-Za-z0-9_\-:@/.]`, but `-c` splits paths on `.` naively and never unquotes |
+| OAuth | Keychain `mcpOAuth`, key `name\|sha256({type,url,headers})[:16]`. `/mcp` login works for `--mcp-config` servers | Keyring "Codex MCP Credentials", key `name + url`. `codex mcp login` searches the *effective* config, so `-c` servers work |
+| Persistent per-server off | `disabledMcpServers` in `~/.claude.json` `projects[gitRoot]`, checked **by name for every scope including `--mcp-config`** | `enabled=false` in config.toml |
+| Invalid entry | Process exits 1 | Config load fails, so the launch fails |
+| Enterprise lock | `managed-mcp.json` present: non-sdk `--mcp-config` entries are rejected and the process exits | `requirements.toml` allowlist can disable |
+| Live reload in TUI | Only on `/clear` or `/reload-plugins` | Not reachable from the TUI |
+
+### Beeper Desktop MCP (worked example)
+
+- **Built in.** Beeper Desktop has its own MCP server (enable it under
+  Settings → Developers / Integrations). It runs as Streamable HTTP at
+  `http://localhost:23373/v0/mcp`.
+- **Auth.** OAuth 2.0 + PKCE is the default. Alternatively
+  `Authorization: Bearer <token>` with a token from Settings → Integrations
+  → Approved connections, which bypasses OAuth.
+- **Official snippets:** `claude mcp add beeper http://localhost:23373/v0/mcp -t http`,
+  `codex mcp add beeper --url http://localhost:23373/v0/mcp [--bearer-token-env-var X]`,
+  and the generic `{"mcpServers":{"beeper":{"url":…,"headers":{"Authorization":"Bearer …"}}}}`.
+- **stdio alternatives:** `npx -y @beeper/mcp-remote` or `@beeper/desktop-mcp`
+  (env `BEEPER_ACCESS_TOKEN`).
+
+### Open-source prior art (what to build on)
+
+- **De facto config shape.** Most server READMEs publish
+  `{"mcpServers": {"<name>": {command,args,env} | {type,url,headers}}}`.
+  Claude Code, Claude Desktop and Cursor use it. VS Code differs: it uses
+  `servers` and has `inputs` with `password: true`, referenced as
+  `${input:id}`, prompted once and stored in a secret store. Claude Desktop's
+  MCPB manifest converged on the same idea (`user_config` with
+  `sensitive: true`).
+- **`add-mcp` (Apache-2.0, neon-solutions).** Its per-client
+  `transformConfig(name, cfg)` is the right shape, and ~30 lines per client.
+  It isn't worth depending on: it has CLI deps, and its Codex transform is
+  wrong (SSE, `type` key, no env indirection). We copy the idea, not the
+  package.
+- **Aggregators (MetaMCP, 1MCP, MCPHub, ToolHive, Docker gateway): rejected.**
+  - A supervised runtime to bundle.
+  - Breaks each CLI's native OAuth.
+  - Rewrites tool names (breaking permission rules and our transcript
+    rendering).
+  - A single point of failure for all servers.
+  - Their one advantage, hot-swap without restart, doesn't outweigh these.
+- **MCP Registry** (registry.modelcontextprotocol.io, v0.1 API frozen, still
+  *preview*). `server.json` `packages[]` / `remotes[]` with
+  `isSecret`-flagged env and headers maps directly onto our inputs model. It
+  is a good optional "Add from registry" source later, but not v1. Beeper
+  isn't listed.
+
+## Decisions
+
+| Question | Decision | Why |
+| --- | --- | --- |
+| Deliver by writing provider config, or at launch? | **At launch only.** Never write `~/.claude.json`, `.mcp.json` or `config.toml`. | Reuses the proven built-in path. There's no clobber race with live Claude processes (which rewrite `~/.claude.json` constantly), no `codex mcp add` table rewrite, and a per-agent subset comes free. The price, "needs an agent reload", already holds for built-in MCP and for both CLIs' own config. |
+| Canonical storage format | **The de facto `mcpServers` entry shape**, plus VS Code-style `${input:id}` secret references and a little Agent Code metadata. | Users paste README snippets unchanged. The format is already understood by every MCP author, so there is no bespoke schema to learn or document. |
+| Where state lives | **Main-owned** `STATE_DIR/mcp-servers.json` (0600), not renderer localStorage. | Main resolves secrets and builds launch material. Multiple windows need one owner. This matches provider enablement. |
+| Secrets | `safeStorage` per-file blobs under `STATE_DIR/mcp-secrets/`, no auth prompt, never sent to the renderer (hint only). | A Touch ID-gated vault would prompt during automatic restore or reload. This is the dictation key precedent. |
+| Where may `${input:id}` appear? | **Only in `env` values and `headers` values.** Rejected in `command`, `args` and `url`. | Codex doesn't expand variables, so a secret in args or url lands in argv / `ps`. Servers that need a token on their command line (e.g. `mcp-remote --header "…${X}"`) already expand their *own* env, so the user writes `${X}` in args and puts the secret in `env.X`. |
+| Toggle semantics | Three levels. **`enabled`** is a master switch ("off" means off everywhere, even with a per-agent on). **`providers.{claude,codex}`** is the default attachment for agents of that provider. **Per-agent overrides** add or remove a server for one agent. | Mirrors the built-in MCP defaults-plus-overrides model users already know, plus Cursor's "toggle without deleting". |
+| Provider scope | Claude and Codex. The data model is keyed by provider, so OpenCode or Grok is an additive task later. | User scope. OpenCode's launcher already has an inline-config path to extend. |
+| Transport support matrix | stdio: Claude + Codex. http: Claude + Codex. sse: **Claude only** (the Codex column is disabled with a reason). | Codex has no SSE. |
+| Name rules | Must match `^[A-Za-z0-9_-]{1,64}$`. `agent_code` and `agent-code-control` are rejected (case-insensitive). No automatic prefixing. | The charset is the intersection of both CLIs and `-c` path parsing. A prefix would uglify every tool name (`mcp__ac-beeper__send_message`) and break the permission rules users copy from docs. |
+| Same name as a user-native server | **Codex: skip injecting that server for this spawn and warn.** Claude: inject (launch replaces the native entry), and show a notice in Settings. | The Codex deep merge can create an invalid mixed-transport entry that kills the whole launch. Claude replacement is well-defined. |
+| OAuth | **Delegated to each CLI.** Settings offers "Sign in…" for HTTP servers. For Codex it opens a terminal pane running `codex mcp login <name>` with the same `-c` overrides. For Claude it tells the user to run `/mcp` in an agent that has the server attached. | Both CLIs already store OAuth tokens securely and key them stably. Building our own OAuth client would duplicate that and break the CLIs' own refresh logic. |
+| Aggregator/proxy | Rejected. | See prior art above. |
+| Registry / catalog | Out of v1. Follow-up issue. | Preview API; paste already covers "any server". |
+| Workflows (Codex SDK subagents) | Out of scope. They keep their private `CODEX_HOME` without user servers. | Replay safety (`inheritedMcpServers: 'unknown'`). |
+| Settings location | New **MCP** category holding the user-servers row, **plus** the existing built-in MCP default rows and the External operator MCP row moved from Agents. | One place for MCP. The move is a category change on existing registry entries (opportunistic cleanup within blast radius). |
+| Editing UI | **One JSON editor per server** (the standard entry shape), plus masked secret fields generated from the `${input:*}` references it contains. No field-by-field form builder. | "Any MCP server" means any shape a README publishes. A form either restricts that or grows forever. The user explicitly asked for a lean UI. |
+
+## Contracts
+
+### Stored document (`STATE_DIR/mcp-servers.json`, mode 0600)
+
+```ts
+// src/shared/types/userMcp.ts
+export const USER_MCP_PROVIDERS = ['claude', 'codex'] as const
+export type UserMcpProvider = (typeof USER_MCP_PROVIDERS)[number]
+
+/** The de facto `mcpServers` entry. Kept structurally identical to what
+ *  READMEs publish so paste → store → re-export is lossless. */
+export type UserMcpServerEntry =
+  | { type?: 'stdio'; command: string; args?: string[]; env?: Record<string, string>; cwd?: string }
+  | { type: 'http' | 'sse'; url: string; headers?: Record<string, string> }
+
+export type UserMcpInput = {
+  id: string            // referenced as ${input:<id>}; ^[A-Za-z0-9_-]{1,64}$
+  description: string   // shown next to the masked field
+}
+
+export type UserMcpServer = {
+  id: string                                  // stable uuid; overrides key on this, never on name
+  name: string                                // provider-visible name, see name rules
+  enabled: boolean                            // master switch
+  providers: Record<UserMcpProvider, boolean> // default attachment per provider
+  entry: UserMcpServerEntry
+  inputs: UserMcpInput[]                      // secret definitions only; values live in safeStorage
+}
+
+export type UserMcpDocument = { version: 1; servers: UserMcpServer[] }
+```
+
+A pasted entry that has no `type` but does have `url` is normalized to
+`type: 'http'`. That is Cursor/Claude Desktop behavior, and Streamable HTTP is
+the current transport. Unknown extra keys in `entry` are **preserved**, not
+dropped (see "What would make this wrong").
+
+### Renderer-visible snapshot (IPC, no secret values)
+
+```ts
+export type UserMcpServerView = UserMcpServer & {
+  secrets: Record<string /*inputId*/, { set: boolean; hint?: string /* last 4 */ }>
+  problems: UserMcpProblem[]   // validation + readiness, computed in main
+  support: Record<UserMcpProvider, { ok: true } | { ok: false; reason: string }>
+}
+export type UserMcpProblem =
+  | { kind: 'invalid-name' | 'reserved-name' | 'invalid-entry'; message: string }
+  | { kind: 'secret-in-forbidden-field'; field: string }
+  | { kind: 'unknown-input'; inputId: string }      // ${input:x} with no definition
+  | { kind: 'secret-missing'; inputId: string }
+  | { kind: 'duplicate-name'; otherId: string }
+```
+
+IPC channels are `user-mcp:get`, `user-mcp:save-server` (upsert by id),
+`user-mcp:delete-server`, `user-mcp:set-enabled`, `user-mcp:set-provider`,
+`user-mcp:set-secret`, `user-mcp:clear-secret` and `user-mcp:import` (parse
+only, returns candidate servers), plus the broadcast `user-mcp:changed`. Every
+mutation returns the new full snapshot, as provider enablement does.
+
+### Per-agent state (renderer pane metadata, beside `builtInMcpOverrides`)
+
+```ts
+userMcpOverrides?: Record<string /*server id*/, boolean> // absent = inherit
+userMcpServerIds?: string[]  // OBSERVED: what the running process was launched with
+```
+
+`resolveSessionUserMcpServerIds({ provider, servers, overrides })` returns
+enabled servers whose provider default is on, plus overrides set to `true`,
+minus overrides set to `false`. It then filters out servers whose `enabled` is
+false and servers that don't support that provider. It is a pure function in
+`src/renderer/src/workspace/userMcp.ts`.
+
+`clonedMcpOverrides` copies `userMcpOverrides` too, because a duplicate
+should keep its tools. `Use Global MCP Settings` clears both override maps.
+
+### Spawn contract (renderer → main)
+
+`SessionSpawnOptions` / `SessionRecoverOptions` gain
+`userMcpServerIds?: string[]`. Main is the authority:
+
+1. It re-reads its store and drops unknown ids, disabled servers, servers
+   unsupported on this provider, servers with problems, and servers with a
+   missing secret.
+2. It resolves secrets and builds `ResolvedUserMcpServer[]`.
+3. It passes that list into `createSession({ …, userMcpServers })`.
+4. `SessionInfo.userMcpServerIds` reports what was actually attached.
+
+For every dropped id, main emits `user-mcp-unavailable
+{ sessionId, servers: [{ name, reason }] }`, shown the same way as
+`managed-skills-unavailable` (`sessionManager.ts:220, 2724`). **A bad user
+server never fails an agent launch.**
+
+The renderer sends ids, not configs, because secrets never leave main, and
+because a stale renderer snapshot must not be able to inject a server the user
+has since deleted.
+
+### Launch material (main, per provider)
+
+`src/providers/shared/runtime/userMcpLaunch.ts`. Each translator is a pure
+function (`servers → { claudeEntries | codexArgs, env }`), in the spirit of
+add-mcp's `transformConfig`.
+
+**Secret variable naming.** Each `env`/`headers` value that contains
+`${input:…}` is fully substituted in main. The result goes in a generated
+variable named
+`AGENT_CODE_USER_MCP_<NAME>_<KEY>`: uppercased, non-alphanumerics mapped to
+`_`, and made collision-free with a numeric suffix. The name is
+**deterministic across spawns**. That is required because Claude keys stored
+OAuth tokens on `hash(type,url,headers)`, and headers carry these variable
+names, so an index-based name that shifted when another server was toggled
+would silently discard the user's OAuth login.
+
+**Claude.** User entries merge into the **same** private 0600 file that
+`createPrivateClaudeMcpConfig` already writes, so there's still one
+`--mcp-config`, still last among the flags:
+
+- stdio: `{type:'stdio', command, args, env:{K: '${AGENT_CODE_USER_MCP_…}' | literal}}`.
+- http/sse: `{type, url, headers:{H: '${AGENT_CODE_USER_MCP_…}' | literal}}`.
+- The generated variables go into the Claude process env, and Claude expands
+  them.
+- The file is created even when no built-in servers are enabled. Today the
+  function returns `null` for an empty list, so the signature widens.
+
+**Codex.** Extend beside `addCodexBuiltInMcpLaunchConfig`:
+
+- stdio:
+  - `mcp_servers.<n>.command="…"`
+  - `mcp_servers.<n>.args=[…]` (TOML array via JSON-compatible literal)
+  - `mcp_servers.<n>.cwd="…"`
+  - `mcp_servers.<n>.env_vars=["K1","K2"]`, where each `K` is set to its
+    substituted value in the Codex process env. Codex passes env to stdio
+    children only through its allowlist plus `env_vars`, and a literal `env`
+    would put values in argv.
+  - **Collision:** if two attached stdio servers need the same env key with
+    different values, the second is dropped with a reason. `env_vars` can't
+    rename.
+- http:
+  - `mcp_servers.<n>.url="…"`.
+  - Every header goes through `env_http_headers.<H>="<generated var>"`,
+    exactly like the built-ins. That includes `Authorization`: Codex rejects
+    literal `bearer_token`, and `env_http_headers` covers it without special
+    casing.
+- Name collision with a user-native Codex server: before building args, main
+  parses `${CODEX_HOME:-~/.codex}/config.toml` `mcp_servers` keys with
+  `@iarna/toml` (already a dependency). On a hit, it skips and warns. A
+  project `.codex/config.toml` in the cwd is checked the same way.
+
+**Claude enterprise lock.** If `managed-mcp.json` exists (macOS:
+`/Library/Application Support/ClaudeCode/managed-mcp.json`), user servers are
+not injected for Claude, and each gets a `managed-policy` reason. Injecting
+them would make the process exit.
+
+### Import parser (`user-mcp:import`)
+
+It accepts, in order:
+
+1. `{"mcpServers": {…}}`, the Claude, Cursor and Claude Desktop form.
+2. `{"servers": {…}, "inputs": [...]}`, the VS Code form. `inputs` with
+   `password: true` become our inputs, and non-password `promptString` inputs
+   become literal placeholders the user must fill.
+3. A bare `{"<name>": {command|url…}}` map.
+4. A single bare entry `{command|url…}`, for which the user supplies a name.
+
+The import rule is that every literal `env` value and `headers` value becomes
+a generated secret input (`<name>-<key>`), with its value pre-filled from the
+paste and stored in safeStorage. The JSON keeps only `${input:…}`. The user can
+edit a value back to a literal if it isn't sensitive. We deliberately don't
+guess sensitivity from key names (same reasoning as the built-in launcher's
+`env_http_headers` WHY comment): a missed guess leaks a token into a
+plaintext file.
+
+## UX
+
+### Settings → MCP (new category)
+
+1. **Your MCP servers** (marker row `user-mcp-servers`). Each server shows:
+   - name, and a transport summary (`http · localhost:23373/v0/mcp`,
+     `stdio · npx -y @beeper/mcp-remote`);
+   - a master switch;
+   - one checkbox per provider that is **enabled in Settings → Providers**,
+     so a disabled provider's column is hidden (tying into #1126);
+   - status chips from `problems` and support reasons (for example
+     "Claude only: Codex has no SSE", "Secret not set", "Name collides with
+     your Codex config");
+   - Edit, Delete and, for HTTP servers, Sign in….
+   - Footer: **Add server…** and "Changes apply to new agents and on agent
+     reload."
+2. **Add / Edit dialog.** A name field, a JSON editor holding the entry (paste
+   anything from a README), and a live list of masked secret fields, one per
+   `${input:id}` found. Validation errors show inline and come from the same
+   main-side validator. "Paste config" imports multiple servers at once.
+3. The built-in MCP default rows and External operator MCP move here
+   unchanged.
+
+### Command palette
+
+Per `docs/command-style.md`:
+
+| id | Title | Surface | Behavior |
+|---|---|---|---|
+| `user-mcp-servers` | `MCP Servers…` | app | Picker of all user servers with toggle state, plus "Add server…" and "Open MCP settings" rows. Selecting a server flips its master switch; `keepPaletteOpen`. |
+| `add-user-mcp-server` | `Add MCP Server…` | app | Opens the Add dialog with the paste box focused. |
+| `agent-user-mcp-servers` | `Agent MCP Servers…` | session | Picker for the focused Claude or Codex agent. Each row shows attached, inherited or overridden state. Selecting one writes the override and reloads the agent through the existing reload path, one reload per toggle, like the built-in MCP commands. |
+| `use-global-mcp-settings` | (existing) | session | Also clears `userMcpOverrides`. |
+
+The catalog is context-free, so it can't generate one command per server.
+Hence pickers. `ui.openSettings()` gains an optional category argument so
+"Open MCP settings" deep-links.
+
+## What would make this wrong (invariants)
+
+- **Secrets never reach** argv, the renderer, `mcp-servers.json`, logs or
+  incident bundles. Secrets *do* reach the agent's own process env and the
+  private 0600 Claude file, so the agent's shell tools can read them. That is
+  equally true of the existing built-in bearer and of the CLIs' own config,
+  and it is accepted and stated in the UI copy.
+- **A bad user server never fails an agent launch.** Main validates and
+  drops. The CLIs exit on invalid config (see evidence), so passing something
+  unvalidated through is a fleet-wide outage.
+- **Only one `--settings` for Claude.** This feature adds no Claude settings
+  fragment. If it ever needs one (for example to hide a native server), it
+  must merge into `excludeExternalControlFromClaude`.
+- **Unknown entry keys survive a round trip.** READMEs use client-specific
+  keys (`oauth`, `headersHelper`, `timeout`). For Claude they pass through
+  untouched. For Codex, only the known keys are translated, and the rest are
+  ignored with a visible "Ignored by Codex: …" note, never silently dropped
+  from storage.
+- **The renderer never decides what gets attached.** It proposes ids, and main
+  disposes. The launched set on the pane is observed (`userMcpServerIds`), and
+  recovery adopts the running process's set, exactly like
+  `builtInMcpDomains`.
+- **The master switch really means off.** No per-agent override may resurrect
+  a server whose `enabled` is false.
+
+## Known limitations (stated, not solved)
+
+- A config change needs an agent reload. Neither TUI reloads MCP config
+  (Claude only on `/clear` or `/reload-plugins`).
+- Claude's persistent `disabledMcpServers` (set via `/mcp` in a repo) applies
+  by name to injected servers too. Toggling an injected server inside `/mcp`
+  writes that state back into `~/.claude.json`. We document this and don't
+  fight it.
+- Native servers (from `~/.claude.json`, `.mcp.json` or `config.toml`) still
+  load and aren't shown. The read-only "Also loaded natively" list is a
+  follow-up.
+- Codex can't use SSE-only servers.
+- Workflow subagents don't get user servers.
+
+## Follow-ups (separate issues after v1)
+
+1. Read-only "Also loaded natively" list, with "Copy into Agent Code".
+2. "Add from registry" via the MCP Registry v0.1 API (preview).
+3. OpenCode and Grok support (the data model and translators are additive).
+4. #244: Agent Code-hosted extension servers register into the same list.
+
+## Acceptance (Beeper as the fixture)
+
+1. Paste Beeper's official token snippet →
+   - the result is one server, `beeper`, of type http with a
+     `beeper-authorization` secret;
+   - the JSON on disk contains no token.
+2. With Claude and Codex both ticked, a new Claude agent's private
+   `mcp.json` has `beeper` with an `${AGENT_CODE_USER_MCP_BEEPER_AUTHORIZATION}`
+   header.
+3. A new Codex agent's argv has `mcp_servers.beeper.url` and
+   `env_http_headers.Authorization="AGENT_CODE_USER_MCP_BEEPER_AUTHORIZATION"`,
+   and no token appears in argv.
+4. `Agent MCP Servers…` → Beeper off → after the reload the agent has no
+   beeper tools, and `userMcpServerIds` excludes it.
+5. The master switch off → no new agent gets it, even one with a per-agent
+   on override.
+6. A stdio server (`npx -y @beeper/mcp-remote`) works on both providers.
+7. An SSE server shows the Codex column disabled with a reason.
+8. A server named `agent_code` is rejected. A server colliding with a
+   `[mcp_servers.X]` in the user's `config.toml` is skipped for Codex with a
+   visible reason, and the Claude launch is unaffected.
+9. A deleted secret → the agent still launches, without that server, and
+   shows the unavailable notice.
diff --git a/src/main/index.ts b/src/main/index.ts
index 4d69ab6f7..b84aa9b09 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -138,6 +138,8 @@ import { RemoteController } from '@main/remote/RemoteController.js'
 import { CaffeinateController } from '@main/caffeinate/CaffeinateController.js'
 import { createFileVaultStore } from '@main/keyVault/vaultStore.js'
 import { createSafeStorageCodec } from '@main/keyVault/safeStorageCodec.js'
+import { UserMcpService } from '@main/userMcp/service.js'
+import { sweepStalePrivateMcpConfigs } from '@providers/shared/runtime/builtInMcpLaunch.js'
 import { VaultService } from '@main/keyVault/VaultService.js'
 import { buildAppMenu } from '@main/menu/appMenu.js'
 import { UpdateService } from '@main/updates/UpdateService.js'
@@ -1026,6 +1028,16 @@ async function startApp(): Promise<void> {
   const agentCodeConventionsService = new AgentCodeManagedSkillsService()
   await agentCodeConventionsService.initialize()
   assertStartupOpen()
+  // User MCP servers (#1143). Loaded before the manager so the first restored
+  // agent already launches with them; initialize() never throws (a corrupt
+  // document is moved aside and reported in Settings instead).
+  const userMcpService = new UserMcpService({ stateDir: STATE_DIR, codec: createSafeStorageCodec() })
+  await userMcpService.initialize()
+  // Private MCP config files now carry user secrets; a crash must not leave
+  // them in the temp dir. Before any agent can launch, so nothing live is hit.
+  void sweepStalePrivateMcpConfigs().then(removed => {
+    if (removed > 0) appRunJournal?.record({ area: 'mcp.user', name: 'private_config.swept', data: { removed } })
+  })
   manager = new SessionManager(
     tmuxAvailable ? tmuxRegistry : null,
     builtInMcpHost,
@@ -1042,6 +1054,7 @@ async function startApp(): Promise<void> {
       )
     },
   )
+  manager.setUserMcpResolver(params => userMcpService.resolveForLaunch(params))
   // Adapters seal streams a sleep severed (#963); the manager fans each
   // suspension out to the live agent runtimes.
   systemSuspension.on('suspension', (suspension: import('@shared/types/systemSuspension.js').SystemSuspension) => {
@@ -1218,6 +1231,14 @@ async function startApp(): Promise<void> {
     },
     sessionManager: manager,
     appRunJournal,
+    // #1143: the mcp_servers domain edits the same document Settings → MCP
+    // does, through the same service. Every agent-made change is broadcast so
+    // the user always learns that their MCP configuration changed.
+    userMcpService,
+    onUserMcpChangedByAgent: event => {
+      appRunJournal?.record({ area: 'mcp.user', name: 'user_mcp.agent_change', ids: { sessionId: event.sessionId }, data: { message: event.message } })
+      broadcastToWindows('user-mcp:agent-change', { message: event.message })
+    },
     workflowService: activeWorkflowService,
     workflowBridge: activeWorkflowBridge,
     // Root Agent Code Management (#906): the SAME operator catalog the external
@@ -1415,6 +1436,7 @@ async function startApp(): Promise<void> {
   const conversationService = createConversationService({ ledger: conversationLedger, listWorktrees: listWorktreesForCwd })
   registerAllIpc({
     manager,
+    userMcpService,
     remoteController,
     lspManager,
     ghostJournals,
diff --git a/src/main/ipc/index.ts b/src/main/ipc/index.ts
index b8f96047e..3c35df518 100644
--- a/src/main/ipc/index.ts
+++ b/src/main/ipc/index.ts
@@ -47,6 +47,8 @@ import type { AppRunJournal } from '@main/incident/AppRunJournal.js'
 import { registerIncidentIpc } from '@main/ipc/incident.js'
 import { registerLifecycleIpc } from '@main/ipc/lifecycle.js'
 import { registerProviderEnablementIpc } from '@main/ipc/providerEnablement.js'
+import { registerUserMcpIpc } from '@main/ipc/userMcp.js'
+import type { UserMcpService } from '@main/userMcp/service.js'
 import { registerUsageIpc } from '@main/ipc/usage.js'
 import { registerCliUpdatesIpc } from '@main/ipc/cliUpdates.js'
 import type { CliUpdateOrchestrator } from '@main/setup/cliUpdateOrchestrator.js'
@@ -73,6 +75,7 @@ import type { SystemSuspensionTracker } from '@main/systemSuspension/SystemSuspe
 
 export type IpcDeps = {
   manager: SessionManager
+  userMcpService: UserMcpService
   lspManager: LspManager
   ghostJournals: GhostJournalRegistry
   dictationDebugJournals: DictationDebugJournalRegistry
@@ -140,6 +143,7 @@ export function registerAllIpc(deps: IpcDeps): void {
   )
   registerDebugIpc(deps.appRunJournal, lifecycleDiagnostics)
   registerProviderEnablementIpc()
+  registerUserMcpIpc(deps.userMcpService)
   registerUsageIpc()
   registerCliUpdatesIpc(deps.cliUpdateOrchestrator)
   registerWorkflowIpc(deps.workflowBridge)
diff --git a/src/main/ipc/userMcp.ts b/src/main/ipc/userMcp.ts
new file mode 100644
index 000000000..a8f8479f0
--- /dev/null
+++ b/src/main/ipc/userMcp.ts
@@ -0,0 +1,85 @@
+import { ipcMain } from 'electron'
+
+import type { UserMcpService } from '@main/userMcp/service.js'
+import { broadcastToWindows } from '@main/window/windowRegistry.js'
+import { isUserMcpProvider, isUserMcpServerId, type UserMcpSaveInput } from '@shared/userMcp/types.js'
+import { isPlainObject } from '@shared/userMcp/validate.js'
+
+export const USER_MCP_CHANGED_CHANNEL = 'user-mcp:changed'
+export const USER_MCP_UNAVAILABLE_CHANNEL = 'user-mcp:unavailable'
+
+// Pasted configs are small; anything larger is not an MCP snippet and would
+// only cost a JSON parse in main.
+const MAX_IMPORT_CHARS = 256 * 1024
+const MAX_SECRET_CHARS = 64 * 1024
+
+/**
+ * User MCP servers (#1143). Same contract as provider enablement: every
+ * mutation returns the fresh snapshot AND broadcasts it, so every window's
+ * Settings grid and per-agent picker update even though only one was touched.
+ *
+ * Arguments are untrusted renderer input. The shapes are checked here; the
+ * semantic rules (names, transports, secret placement) are enforced again in
+ * UserMcpService.save, which is the single place that decides what is valid.
+ */
+export function registerUserMcpIpc(service: UserMcpService): void {
+  ipcMain.handle('user-mcp:get', () => service.snapshot())
+
+  ipcMain.handle('user-mcp:save', (_evt, input: unknown) => {
+    if (!isSaveInput(input)) throw new Error('user-mcp:save: invalid arguments')
+    return service.save(input)
+  })
+
+  ipcMain.handle('user-mcp:delete', (_evt, id: unknown) => {
+    if (!isUserMcpServerId(id)) throw new Error('user-mcp:delete: invalid id')
+    return service.delete(id)
+  })
+
+  ipcMain.handle('user-mcp:set-enabled', (_evt, id: unknown, enabled: unknown) => {
+    if (!isUserMcpServerId(id) || typeof enabled !== 'boolean') throw new Error('user-mcp:set-enabled: invalid arguments')
+    return service.setEnabled(id, enabled)
+  })
+
+  ipcMain.handle('user-mcp:set-provider', (_evt, id: unknown, provider: unknown, enabled: unknown) => {
+    if (!isUserMcpServerId(id) || !isUserMcpProvider(provider) || typeof enabled !== 'boolean') {
+      throw new Error('user-mcp:set-provider: invalid arguments')
+    }
+    return service.setProvider(id, provider, enabled)
+  })
+
+  ipcMain.handle('user-mcp:set-secret', (_evt, id: unknown, inputId: unknown, value: unknown) => {
+    if (
+      !isUserMcpServerId(id) || typeof inputId !== 'string' ||
+      typeof value !== 'string' || value.length > MAX_SECRET_CHARS
+    ) {
+      throw new Error('user-mcp:set-secret: invalid arguments')
+    }
+    return service.setSecret(id, inputId, value)
+  })
+
+  ipcMain.handle('user-mcp:import', (_evt, text: unknown, fallbackName: unknown) => {
+    if (typeof text !== 'string' || text.length > MAX_IMPORT_CHARS) throw new Error('user-mcp:import: invalid text')
+    return service.importConfig(text, typeof fallbackName === 'string' ? fallbackName : undefined)
+  })
+
+  ipcMain.handle('user-mcp:copy-native', (_evt, provider: unknown, name: unknown) => {
+    if (!isUserMcpProvider(provider) || typeof name !== 'string') throw new Error('user-mcp:copy-native: invalid arguments')
+    return service.copyNative(provider, name)
+  })
+
+  service.onChange(snapshot => broadcastToWindows(USER_MCP_CHANGED_CHANNEL, snapshot))
+}
+
+function isSaveInput(value: unknown): value is UserMcpSaveInput {
+  if (!isPlainObject(value)) return false
+  if (value.id !== undefined && !isUserMcpServerId(value.id)) return false
+  if (typeof value.name !== 'string' || typeof value.enabled !== 'boolean') return false
+  if (!isPlainObject(value.providers) || !isPlainObject(value.entry) || !Array.isArray(value.inputs)) return false
+  if (value.secrets !== undefined) {
+    if (!isPlainObject(value.secrets)) return false
+    for (const secret of Object.values(value.secrets)) {
+      if (typeof secret !== 'string' || secret.length > MAX_SECRET_CHARS) return false
+    }
+  }
+  return true
+}
diff --git a/src/main/sessionManager.ts b/src/main/sessionManager.ts
index 7f4841c34..d494db241 100644
--- a/src/main/sessionManager.ts
+++ b/src/main/sessionManager.ts
@@ -69,6 +69,24 @@ import type {
 } from '@shared/types/providerKind.js'
 import type { BuiltInMcpDomain, BuiltInMcpServerConfig } from '@mcp/shared/types.js'
 import type { BuiltInMcpHttpHost } from '@mcp/runtime/BuiltInMcpHttpHost.js'
+import {
+  normalizeUserMcpOverrides,
+  type ResolvedUserMcpServer,
+  type UserMcpDroppedServer,
+} from '@shared/userMcp/types.js'
+
+/** Structural so SessionManager does not depend on the service class; see
+ * UserMcpService.resolveForLaunch for the rules it applies. */
+export type UserMcpResolver = (params: {
+  provider: string
+  overrides: Readonly<Record<string, boolean>>
+  cwd: string
+}) => Promise<{
+  servers: ResolvedUserMcpServer[]
+  attachedIds: string[]
+  dropped: UserMcpDroppedServer[]
+  codexShellPolicy?: { style: 'filters' } | { style: 'legacy'; exclude: readonly string[] }
+}>
 import type { AppRunJournal } from '@main/incident/AppRunJournal.js'
 import { SessionLifecycleJournal } from '@main/lifecycle/SessionLifecycleJournal.js'
 import type { PromptGateState } from '@shared/types/session.js'
@@ -218,6 +236,10 @@ type ManagerEvents = {
    *  reconcile could not prepare, and it is being started without them (#1133).
    *  Carries domain names only, never the error: see the pre-spawn gate. */
   'managed-skills-unavailable': [{ sessionId: string; skills: ReportingDomain[] }]
+  // #1143. A user MCP server the agent asked for could not be attached to this
+  // launch (missing secret, unsupported transport, name collision…). The
+  // launch itself proceeded without it.
+  'user-mcp-unavailable': [{ sessionId: string; servers: UserMcpDroppedServer[] }]
   exit: [{ sessionId: string; exitCode: number; signal?: number }]
 }
 
@@ -719,6 +741,25 @@ export class SessionManager extends EventEmitter {
     this.lifecycle = new SessionLifecycleJournal(journal)
   }
 
+  /**
+   * User MCP servers (#1143). A setter rather than another positional
+   * constructor argument because the service is optional (tests and the
+   * headless harnesses construct managers without one) and the constructor's
+   * positional list is already long enough that one more slot invites
+   * argument-order bugs at every call site.
+   */
+  setUserMcpResolver(resolver: UserMcpResolver | null): void {
+    this.userMcpResolver = resolver
+  }
+
+  private userMcpResolver: UserMcpResolver | null = null
+  // What each live agent was actually launched with, and the per-agent
+  // choices it was launched from. The first feeds the backend snapshot the
+  // same way builtInMcpHost.sessionDomains does; the second lets a same-rollout
+  // Codex restore relaunch with the predecessor's exact choices.
+  private readonly userMcpAttached = new Map<string, string[]>()
+  private readonly userMcpOverridesBySession = new Map<string, Record<string, boolean>>()
+
   private readonly lifecycle: SessionLifecycleJournal
 
   // Terminal attach/replay state.
@@ -1035,6 +1076,12 @@ export class SessionManager extends EventEmitter {
       this.agentPtyAttachCounts.delete(sessionId)
       this.agentPtyRestoreSizes.delete(sessionId)
       if (revokeAgentMcp) this.builtInMcpHost?.revokeSession(sessionId)
+      // Once the backend is gone its user-MCP launch facts must not outlive it
+      // and be reported for a successor. Unconditional (review round 2):
+      // `revokeAgentMcp` is about the built-in host bearer and is false when a
+      // launch had no built-in domains, which leaked these entries.
+      this.userMcpAttached.delete(sessionId)
+      this.userMcpOverridesBySession.delete(sessionId)
     }
     forgetFeedDebugSession(sessionId)
     return true
@@ -2350,6 +2397,7 @@ export class SessionManager extends EventEmitter {
         dangerousMode: predecessorInfo.dangerousMode,
         useProxy: predecessorInfo.useProxy,
         builtInMcpDomains: effectiveDomains,
+        userMcpOverrides: this.userMcpOverridesBySession.get(predecessorSessionId) ?? {},
         tldrIdentity: this.builtInMcpHost?.sessionTldrIdentity?.(predecessorSessionId),
       }
       reservation.restoreOptions = restoreOptions
@@ -2721,6 +2769,56 @@ export class SessionManager extends EventEmitter {
    * The toast would also have claimed "agents started" off a launch that did
    * not happen.
    */
+  /**
+   * Decide which user MCP servers this launch gets (#1143).
+   *
+   * Never throws: a broken MCP document, an unreadable keyring or a bad server
+   * must cost the user that server, not the agent. Every server the agent
+   * asked for but did not get is reported through `user-mcp-unavailable`, so
+   * the absence is visible instead of looking like an attached server whose
+   * tools never appear.
+   */
+  private async resolveUserMcpServers(
+    sessionId: string,
+    kind: SessionKind,
+    options: SessionSpawnOptions,
+  ): Promise<{
+    servers: ResolvedUserMcpServer[]
+    codexShellPolicy?: { style: 'filters' } | { style: 'legacy'; exclude: readonly string[] }
+  }> {
+    if (!this.userMcpResolver || !isAgentProviderKind(kind)) return { servers: [] }
+    const overrides = normalizeUserMcpOverrides(options.userMcpOverrides)
+    this.userMcpOverridesBySession.set(sessionId, overrides)
+    try {
+      const resolution = await this.userMcpResolver({ provider: kind, overrides, cwd: options.cwd })
+      this.userMcpAttached.set(sessionId, resolution.attachedIds)
+      if (resolution.dropped.length > 0) {
+        this.journal?.record({
+          area: 'mcp.user',
+          name: 'user_mcp.unavailable',
+          severity: 'warn',
+          ids: { sessionId },
+          // Names and reasons only; reasons are fixed strings built by the
+          // service and never contain a secret value.
+          data: { servers: resolution.dropped.map(server => `${server.name}: ${server.reason}`) },
+        })
+        this.emit('user-mcp-unavailable', { sessionId, servers: resolution.dropped })
+      }
+      return {
+        servers: resolution.servers,
+        ...(resolution.codexShellPolicy ? { codexShellPolicy: resolution.codexShellPolicy } : {}),
+      }
+    } catch (error) {
+      this.userMcpAttached.set(sessionId, [])
+      this.journal?.recordError('user_mcp.resolve_failed', error, undefined, { sessionId })
+      this.emit('user-mcp-unavailable', {
+        sessionId,
+        servers: [{ name: 'MCP servers', reason: 'Your MCP server settings could not be read' }],
+      })
+      return { servers: [] }
+    }
+  }
+
   private reportSkillsUnavailable(sessionId: string, unavailable: readonly ReportingDomain[]): void {
     if (unavailable.length === 0) return
     // Pairs with the `.error` rows (same ids.sessionId): "this session is
@@ -2886,6 +2984,8 @@ export class SessionManager extends EventEmitter {
         })
         mcpRegistered = true
       }
+      const { servers: userMcpServers, codexShellPolicy: userMcpCodexShellPolicy } =
+        await this.resolveUserMcpServers(sessionId, kind, options)
       this.throwIfSpawnCancelled(recoveryClaim, codexReplacementHandoff)
       if (this.beforeAgentSessionStart) {
         const unavailableSkills = await this.runPreSpawnSkillReconcile(sessionId, options)
@@ -2943,6 +3043,8 @@ export class SessionManager extends EventEmitter {
         // `openai_base_url`.
         useProxy: options.useProxy,
         builtInMcpServers,
+        userMcpServers,
+        ...(userMcpCodexShellPolicy ? { userMcpCodexShellPolicy } : {}),
         ...(kind === 'codex' && codexReplacementHandoff
           ? {
               // WHY the provider receives execution timing, not policy: Codex
@@ -3282,6 +3384,7 @@ export class SessionManager extends EventEmitter {
       return {
         sessionId,
         ...(providerSessionId ? { providerSessionId } : {}),
+        userMcpServerIds: this.userMcpAttached.get(sessionId) ?? [],
       }
     }
 
@@ -5459,6 +5562,7 @@ export class SessionManager extends EventEmitter {
         ? {
             builtInMcpDomains:
               this.builtInMcpHost?.sessionDomains?.(sessionId) ?? [],
+            userMcpServerIds: this.userMcpAttached.get(sessionId) ?? [],
             tldrIdentity: this.builtInMcpHost?.sessionTldrIdentity?.(sessionId),
           }
         : {}),
diff --git a/src/main/sessionManager.userMcp.test.ts b/src/main/sessionManager.userMcp.test.ts
new file mode 100644
index 000000000..1af9cdb2a
--- /dev/null
+++ b/src/main/sessionManager.userMcp.test.ts
@@ -0,0 +1,100 @@
+import { EventEmitter } from 'node:events'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { ResolvedUserMcpServer, UserMcpDroppedServer } from '@shared/userMcp/types.js'
+
+// Harness mirrors sessionManager.recover.test.ts: the provider registry is
+// mocked so these tests observe exactly what SessionManager hands a provider,
+// which is the contract under test (#1143).
+const { createSession } = vi.hoisted(() => ({ createSession: vi.fn() }))
+
+vi.mock('@main/workspaceDirectory.js', () => ({
+  MissingWorkspaceDirectoryError: class extends Error {},
+  assertWorkspaceDirectoryExists: vi.fn(async () => {}),
+}))
+vi.mock('@providers/registry.main.js', () => ({
+  getMainProvider: () => ({ createSession, deliverPrompt: vi.fn() }),
+}))
+vi.mock('@main/setup/toolchain.js', () => ({ getToolPath: () => '/usr/bin/true' }))
+vi.mock('@main/performance/PerformanceService.js', () => ({
+  performanceService: { mark: vi.fn(), record: vi.fn(), error: vi.fn() },
+}))
+vi.mock('@main/storage/feedDebugLog.js', () => ({ forgetFeedDebugSession: vi.fn() }))
+
+class FakeAgentSession extends EventEmitter {
+  readonly start = vi.fn(async (): Promise<void> => {
+    this.emit('started', { projectDir: '/tmp/project' })
+  })
+  readonly stop = vi.fn(async (): Promise<void> => {})
+  readonly write = vi.fn()
+  readonly resize = vi.fn()
+}
+
+const beeper: ResolvedUserMcpServer = {
+  id: 'srv-beeper',
+  name: 'beeper',
+  entry: { type: 'http', url: 'http://localhost:23373/v0/mcp' },
+  secrets: {},
+}
+
+describe('SessionManager user MCP servers', () => {
+  beforeEach(() => {
+    createSession.mockReset()
+    createSession.mockImplementation(() => new FakeAgentSession())
+  })
+
+  it('hands the provider exactly the servers main resolved and reports them on the snapshot', async () => {
+    const { SessionManager } = await import('./sessionManager')
+    const manager = new SessionManager()
+    const resolver = vi.fn(async () => ({ servers: [beeper], attachedIds: [beeper.id], dropped: [] }))
+    manager.setUserMcpResolver(resolver)
+
+    const result = await manager.spawn({ kind: 'claude', cwd: '/tmp/project', userMcpOverrides: { 'srv-beeper': true, 'bad id!': true } })
+
+    // The renderer's override map is untrusted: malformed ids never reach the resolver.
+    expect(resolver).toHaveBeenCalledWith({ provider: 'claude', overrides: { 'srv-beeper': true }, cwd: '/tmp/project' })
+    expect(createSession.mock.calls[0]![0].userMcpServers).toEqual([beeper])
+    expect(result.userMcpServerIds).toEqual(['srv-beeper'])
+    expect(manager.getBackendSnapshot(result.sessionId)?.userMcpServerIds).toEqual(['srv-beeper'])
+  })
+
+  it('still launches the agent when a server is dropped, and says why', async () => {
+    const { SessionManager } = await import('./sessionManager')
+    const manager = new SessionManager()
+    const dropped: UserMcpDroppedServer[] = [{ name: 'beeper', reason: 'Secret "beeper-authorization" is not set' }]
+    manager.setUserMcpResolver(async () => ({ servers: [], attachedIds: [], dropped }))
+    const events: unknown[] = []
+    manager.on('user-mcp-unavailable', event => events.push(event))
+
+    const result = await manager.spawn({ kind: 'codex', cwd: '/tmp/project' })
+
+    expect(createSession).toHaveBeenCalledTimes(1)
+    expect(createSession.mock.calls[0]![0].userMcpServers).toEqual([])
+    expect(events).toEqual([{ sessionId: result.sessionId, servers: dropped }])
+  })
+
+  it('treats a resolver failure as "no user servers", never as a failed launch', async () => {
+    const { SessionManager } = await import('./sessionManager')
+    const manager = new SessionManager()
+    manager.setUserMcpResolver(async () => { throw new Error('keyring locked') })
+    const events: unknown[] = []
+    manager.on('user-mcp-unavailable', event => events.push(event))
+
+    const result = await manager.spawn({ kind: 'claude', cwd: '/tmp/project' })
+
+    expect(manager.getBackendSnapshot(result.sessionId)?.lifecycle).toBe('live')
+    expect(result.userMcpServerIds).toEqual([])
+    expect(events).toHaveLength(1)
+  })
+
+  it('never consults the resolver for terminal sessions', async () => {
+    const { SessionManager } = await import('./sessionManager')
+    const manager = new SessionManager()
+    const resolver = vi.fn()
+    manager.setUserMcpResolver(resolver)
+    // Terminal spawn goes through TerminalSession, which this harness does not
+    // fake; only the absence of a resolver call matters here.
+    await manager.spawn({ kind: 'terminal', cwd: '/tmp/project' }).catch(() => {})
+    expect(resolver).not.toHaveBeenCalled()
+  })
+})
diff --git a/src/main/sessions/forwarder.ts b/src/main/sessions/forwarder.ts
index 1d09578e7..9782b5f1f 100644
--- a/src/main/sessions/forwarder.ts
+++ b/src/main/sessions/forwarder.ts
@@ -2,6 +2,8 @@ import type { SessionManager } from '@main/sessionManager.js'
 import { aliasScreenSnapshotForWire } from '@shared/types/session.js'
 import type { AgentScreenSnapshot } from '@shared/types/session.js'
 import type { LspManager } from '@main/lspManager.js'
+import { USER_MCP_UNAVAILABLE_CHANNEL } from '@main/ipc/userMcp.js'
+import type { UserMcpUnavailableEvent } from '@shared/userMcp/types.js'
 import {
   MANAGED_SKILLS_UNAVAILABLE_CHANNEL,
   type ManagedSkillsUnavailableEvent,
@@ -192,6 +194,14 @@ export function wireSessionForwarder(
   manager.on('managed-skills-unavailable', ({ skills }) => {
     const event: ManagedSkillsUnavailableEvent = { skills }
     broadcastToWindows(MANAGED_SKILLS_UNAVAILABLE_CHANNEL, event)
+  })
+  // #1143. Broadcast for the same routing reason as managed skills above: the
+  // launch can be main-initiated (orchestration child, restore) before any
+  // window has claimed the id. Only server names and fixed reason strings
+  // cross; nothing here can carry a secret value.
+  manager.on('user-mcp-unavailable', ({ servers }) => {
+    const event: UserMcpUnavailableEvent = { servers }
+    broadcastToWindows(USER_MCP_UNAVAILABLE_CHANNEL, event)
   })
     // Diagnostics are keyed by file, not by session: two windows can have the
   // same file open in their editors and both need them.
diff --git a/src/main/userMcp/nativeServers.ts b/src/main/userMcp/nativeServers.ts
new file mode 100644
index 000000000..4d02555ae
--- /dev/null
+++ b/src/main/userMcp/nativeServers.ts
@@ -0,0 +1,262 @@
+import { access, readFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+import TOML from '@iarna/toml'
+
+import type { NativeMcpServerSource, UserMcpInput, UserMcpServerEntry } from '@shared/userMcp/types.js'
+import { isPlainObject, isStringArray, isStringRecord, summarizeEntry, transportOf } from '@shared/userMcp/validate.js'
+
+/**
+ * Read-only view of the MCP servers each CLI loads from its OWN config
+ * (spec Revision 2 §7). Agent Code never writes these files; it only reads
+ * them to (a) show the user servers they would otherwise not know are loaded,
+ * (b) offer Copy in, and (c) detect Codex name collisions before launch.
+ *
+ * Only user-scope files are listed. Project-scope files (`.mcp.json`,
+ * `.codex/config.toml`) depend on an agent's cwd, which Settings does not have.
+ */
+
+export type NativeMcpPaths = {
+  home: string
+  claudeConfigDir?: string
+  codexHome?: string
+  platform: NodeJS.Platform
+}
+
+export function defaultNativeMcpPaths(): NativeMcpPaths {
+  return {
+    home: homedir(),
+    claudeConfigDir: process.env.CLAUDE_CONFIG_DIR || undefined,
+    codexHome: process.env.CODEX_HOME || undefined,
+    platform: process.platform,
+  }
+}
+
+// Mirrors Claude's getGlobalClaudeFile (vendor utils/env.ts): the user-scope
+// file lives in CLAUDE_CONFIG_DIR when set, otherwise the home directory.
+function claudeUserConfigFile(paths: NativeMcpPaths): string {
+  return join(paths.claudeConfigDir || paths.home, '.claude.json')
+}
+
+function codexHome(paths: NativeMcpPaths): string {
+  return paths.codexHome || join(paths.home, '.codex')
+}
+
+// Mirrors Claude's getManagedFilePath (vendor utils/settings/managedPath.ts).
+function claudeManagedMcpFile(paths: NativeMcpPaths): string {
+  const dir = paths.platform === 'darwin'
+    ? '/Library/Application Support/ClaudeCode'
+    : paths.platform === 'win32'
+      ? 'C:\\Program Files\\ClaudeCode'
+      : '/etc/claude-code'
+  return join(dir, 'managed-mcp.json')
+}
+
+/**
+ * When an enterprise managed-mcp.json exists, Claude takes exclusive control
+ * of MCP and rejects any non-SDK `--mcp-config` server by exiting (vendor
+ * main.tsx "enterprise MCP config"). User servers must then be held back for
+ * Claude, or every Claude agent would fail to start.
+ */
+export async function claudeManagedMcpPolicyPresent(paths = defaultNativeMcpPaths()): Promise<boolean> {
+  try {
+    await access(claudeManagedMcpFile(paths))
+    return true
+  } catch {
+    return false
+  }
+}
+
+export async function readNativeMcpServers(paths = defaultNativeMcpPaths()): Promise<NativeMcpServerSource[]> {
+  const [claude, codex] = await Promise.all([readClaudeNative(paths), readCodexNative(paths)])
+  return [...claude, ...codex]
+}
+
+/**
+ * Names Codex will already have in `mcp_servers` for an agent in `cwd`.
+ *
+ * WHY launch refuses these names for Codex: `-c mcp_servers.<n>.*` deep-merges
+ * key by key into an existing table (codex-rs config/src/merge.rs). Our `url`
+ * merged into a user's stdio table yields a mixed-transport entry that fails
+ * config load and takes the WHOLE Codex launch down with it.
+ */
+export async function codexNativeServerNames(cwd: string, paths = defaultNativeMcpPaths()): Promise<Set<string>> {
+  const names = new Set<string>()
+  for (const file of await codexConfigLayers(cwd, paths)) {
+    const table = await readCodexMcpTable(file)
+    for (const name of Object.keys(table)) names.add(name)
+  }
+  return names
+}
+
+/**
+ * The config.toml files Codex merges for an agent in `cwd`, lowest precedence
+ * first: system, user (CODEX_HOME), then every `.codex/config.toml` from the
+ * project root down to `cwd`.
+ *
+ * WHY the ancestor walk (review round 2): Codex's project discovery reads
+ * every ancestor `.codex/config.toml` up to the project root marker (`.git`;
+ * vendor codex-rs config/src/loader discover_project_layers), not just the
+ * cwd's. Reading only `<cwd>/.codex` missed a repo-root server or legacy
+ * shell policy for any agent started in a subdirectory or nested worktree —
+ * and either one could make our `-c` overrides fail Codex's config load.
+ * Managed and profile layers are not modelled; they are rare, and a miss
+ * there degrades to the launch-time notice, not a silent change.
+ */
+export async function codexConfigLayers(cwd: string, paths = defaultNativeMcpPaths()): Promise<string[]> {
+  const system = paths.platform === 'win32' ? [] : ['/etc/codex/config.toml']
+  const ancestors: string[] = []
+  let dir = cwd
+  for (let depth = 0; depth < 64; depth++) {
+    ancestors.unshift(join(dir, '.codex', 'config.toml'))
+    if (await exists(join(dir, '.git'))) break
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return [...system, join(codexHome(paths), 'config.toml'), ...ancestors]
+}
+
+async function exists(path: string): Promise<boolean> {
+  try {
+    await access(path)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Which spelling the user's Codex config uses for shell-environment
+ * exclusions, across the user and project config.toml (see
+ * CodexShellPolicyStyle for why it decides how our exclusions are sent).
+ * Legacy `exclude` entries are returned so they can be re-sent with ours,
+ * because a `-c` array replaces the configured one instead of merging.
+ */
+export async function codexShellPolicyStyle(
+  cwd: string,
+  paths = defaultNativeMcpPaths(),
+): Promise<{ style: 'filters' } | { style: 'legacy'; exclude: string[] }> {
+  let legacy = false
+  const exclude: string[] = []
+  for (const file of await codexConfigLayers(cwd, paths)) {
+    const policy = (await readCodexToml(file)).shell_environment_policy
+    if (!isPlainObject(policy)) continue
+    if (policy.exclude !== undefined || policy.include_only !== undefined) legacy = true
+    // A later (project) layer replaces the array; keep the last one seen.
+    if (isStringArray(policy.exclude)) exclude.splice(0, exclude.length, ...policy.exclude)
+  }
+  return legacy ? { style: 'legacy', exclude } : { style: 'filters' }
+}
+
+async function readClaudeNative(paths: NativeMcpPaths): Promise<NativeMcpServerSource[]> {
+  const file = claudeUserConfigFile(paths)
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(await readFile(file, 'utf8'))
+  } catch {
+    return []
+  }
+  if (!isPlainObject(parsed) || !isPlainObject(parsed.mcpServers)) return []
+  return Object.entries(parsed.mcpServers).map(([name, raw]) =>
+    nativeServer('claude', name, displayPath(file, paths.home), isPlainObject(raw) ? raw : null))
+}
+
+async function readCodexNative(paths: NativeMcpPaths): Promise<NativeMcpServerSource[]> {
+  const file = join(codexHome(paths), 'config.toml')
+  const table = await readCodexMcpTable(file)
+  return Object.entries(table).map(([name, raw]) =>
+    nativeServer('codex', name, displayPath(file, paths.home), isPlainObject(raw) ? codexToMcpServersShape(raw) : null))
+}
+
+async function readCodexMcpTable(file: string): Promise<Record<string, unknown>> {
+  const parsed = await readCodexToml(file)
+  return isPlainObject(parsed.mcp_servers) ? parsed.mcp_servers : {}
+}
+
+async function readCodexToml(file: string): Promise<Record<string, unknown>> {
+  let text: string
+  try {
+    text = await readFile(file, 'utf8')
+  } catch {
+    return {}
+  }
+  try {
+    return TOML.parse(text) as Record<string, unknown>
+  } catch {
+    // An unparseable config.toml also fails Codex itself; we have nothing
+    // useful to add, so it contributes nothing rather than blocking launch.
+    return {}
+  }
+}
+
+/** Codex table → `mcpServers` entry, so Copy in can reuse the import path. */
+function codexToMcpServersShape(raw: Record<string, unknown>): Record<string, unknown> {
+  if (typeof raw.command === 'string') {
+    const env: Record<string, string> = isStringRecord(raw.env) ? { ...raw.env } : {}
+    // `env_vars` names pass through from Codex's own environment; in an
+    // mcpServers entry that becomes an env value the user must supply.
+    if (isStringArray(raw.env_vars)) for (const name of raw.env_vars) env[name] ??= ''
+    return {
+      command: raw.command,
+      ...(isStringArray(raw.args) ? { args: raw.args } : {}),
+      ...(Object.keys(env).length > 0 ? { env } : {}),
+      ...(typeof raw.cwd === 'string' ? { cwd: raw.cwd } : {}),
+    }
+  }
+  if (typeof raw.url === 'string') {
+    const headers: Record<string, string> = isStringRecord(raw.http_headers) ? { ...raw.http_headers } : {}
+    if (isStringRecord(raw.env_http_headers)) for (const header of Object.keys(raw.env_http_headers)) headers[header] ??= ''
+    if (typeof raw.bearer_token_env_var === 'string') headers.Authorization ??= 'Bearer '
+    return { type: 'http', url: raw.url, ...(Object.keys(headers).length > 0 ? { headers } : {}) }
+  }
+  return raw
+}
+
+function nativeServer(
+  provider: 'claude' | 'codex',
+  name: string,
+  source: string,
+  raw: Record<string, unknown> | null,
+): NativeMcpServerSource {
+  const transport = raw ? transportOf(raw) : null
+  if (!raw || !transport) {
+    return { provider, name, source, transport: null, summary: '', copyable: false, entry: null, inputs: [] }
+  }
+  const inputs: UserMcpInput[] = []
+  const entry: Record<string, unknown> = { ...raw }
+  // Withhold every value: native configs often store tokens in plaintext and
+  // this object is sent to the renderer.
+  for (const field of ['env', 'headers'] as const) {
+    if (!isStringRecord(entry[field])) {
+      delete entry[field]
+      continue
+    }
+    const next: Record<string, string> = {}
+    for (const [key, value] of Object.entries(entry[field] as Record<string, string>)) {
+      const id = `${name}-${key}`.toLowerCase().replace(/[^a-z0-9_-]+/g, '-').slice(0, 64)
+      // The auth scheme word is not secret and keeping it means the user pastes
+      // just the token. Codex's bearer_token_env_var arrives as "Bearer ".
+      const scheme = /^(Bearer|Token|Basic)\s/i.exec(value)
+      next[key] = scheme ? `${scheme[1]} \${input:${id}}` : `\${input:${id}}`
+      inputs.push({ id, description: `${field === 'env' ? 'Environment variable' : 'Header'} ${key}` })
+    }
+    entry[field] = next
+  }
+  if (transport !== 'stdio') entry.type = transport
+  return {
+    provider,
+    name,
+    source,
+    transport,
+    summary: summarizeEntry(raw),
+    copyable: true,
+    entry: entry as UserMcpServerEntry,
+    inputs,
+  }
+}
+
+function displayPath(file: string, home: string): string {
+  return file.startsWith(home) ? `~${file.slice(home.length)}` : file
+}
diff --git a/src/main/userMcp/secrets.ts b/src/main/userMcp/secrets.ts
new file mode 100644
index 000000000..16de0ca24
--- /dev/null
+++ b/src/main/userMcp/secrets.ts
@@ -0,0 +1,115 @@
+import { mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import type { SecretCodec } from '@main/keyVault/vaultStore.js'
+import type { UserMcpSecretState } from '@shared/userMcp/types.js'
+
+/*
+ * Encryption uses the API Key Vault's safeStorage codec (the same OS-derived
+ * key, injectable so tests do not need Electron), but NOT the vault itself.
+ *
+ * WHY not store MCP secrets in the vault: the vault gates every read behind
+ * Touch ID / the login password once per app run. MCP secrets are read at
+ * agent LAUNCH, which includes automatic restore of a whole workspace at
+ * startup — an OS prompt before any window is usable, or a restore that
+ * silently drops every server until the user unlocks something, are both
+ * worse than the dictation-key precedent (src/main/dictation/apiKeyStore.ts):
+ * encrypted at rest with an OS-derived key, readable without a prompt.
+ */
+
+/**
+ * One encrypted blob per secret at `<dir>/<serverId>/<inputId>.bin`.
+ *
+ * WHY one file per secret instead of one encrypted document: a blob that stops
+ * decrypting (Keychain reset, copied profile) then costs exactly one secret —
+ * shown as "not set" — instead of every server's credentials at once. Server
+ * ids and input ids are both validated to `[A-Za-z0-9_-]`, so they are safe
+ * path segments by construction.
+ */
+export class UserMcpSecretStore {
+  constructor(
+    private readonly dir: string,
+    private readonly codec: SecretCodec,
+  ) {}
+
+  available(): boolean {
+    try {
+      return this.codec.isEncryptionAvailable()
+    } catch {
+      return false
+    }
+  }
+
+  async get(serverId: string, inputId: string): Promise<string | null> {
+    if (!this.available()) return null
+    let ciphertext: Buffer
+    try {
+      ciphertext = await readFile(this.path(serverId, inputId))
+    } catch {
+      return null
+    }
+    try {
+      const value = this.codec.decrypt(ciphertext)
+      return value === '' ? null : value
+    } catch {
+      // Left in place on purpose: if the keyring comes back, so does the value.
+      return null
+    }
+  }
+
+  async set(serverId: string, inputId: string, value: string): Promise<void> {
+    if (value === '') {
+      await this.clear(serverId, inputId)
+      return
+    }
+    if (!this.available()) {
+      throw new Error('Secure storage is not available on this system, so the secret cannot be saved.')
+    }
+    const directory = join(this.dir, serverId)
+    await mkdir(directory, { recursive: true, mode: 0o700 })
+    const target = this.path(serverId, inputId)
+    const temporary = `${target}.${process.pid}.${Date.now()}.tmp`
+    await writeFile(temporary, this.codec.encrypt(value), { mode: 0o600 })
+    await rename(temporary, target)
+  }
+
+  async clear(serverId: string, inputId: string): Promise<void> {
+    await rm(this.path(serverId, inputId), { force: true })
+  }
+
+  async clearServer(serverId: string): Promise<void> {
+    await rm(join(this.dir, serverId), { recursive: true, force: true })
+  }
+
+  /** Drop blobs for inputs the server no longer defines, so a renamed or
+   * removed secret does not linger as an orphaned credential on disk. */
+  async prune(serverId: string, keepInputIds: readonly string[]): Promise<void> {
+    let files: string[]
+    try {
+      files = await readdir(join(this.dir, serverId))
+    } catch {
+      return
+    }
+    const keep = new Set(keepInputIds.map(id => `${id}.bin`))
+    await Promise.all(files.filter(file => !keep.has(file)).map(file =>
+      rm(join(this.dir, serverId, file), { force: true })))
+  }
+
+  /** Presence and a last-4 hint only. The renderer never receives a value. */
+  async state(serverId: string, inputIds: readonly string[]): Promise<Record<string, UserMcpSecretState>> {
+    const entries = await Promise.all(inputIds.map(async id => {
+      const value = await this.get(serverId, id)
+      // No hint for short values: the last four characters of a six-character
+      // PIN are most of the secret.
+      const state: UserMcpSecretState = value === null
+        ? { set: false }
+        : { set: true, ...(value.length >= 12 ? { hint: value.slice(-4) } : {}) }
+      return [id, state] as const
+    }))
+    return Object.fromEntries(entries)
+  }
+
+  private path(serverId: string, inputId: string): string {
+    return join(this.dir, serverId, `${inputId}.bin`)
+  }
+}
diff --git a/src/main/userMcp/service.test.ts b/src/main/userMcp/service.test.ts
new file mode 100644
index 000000000..245c8ddc5
--- /dev/null
+++ b/src/main/userMcp/service.test.ts
@@ -0,0 +1,328 @@
+import { mkdtemp, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import type { SecretCodec } from '@main/keyVault/vaultStore.js'
+import type { NativeMcpServerSource, UserMcpSaveInput } from '@shared/userMcp/types.js'
+
+import { readNativeMcpServers, codexNativeServerNames } from './nativeServers.js'
+import { UserMcpService } from './service.js'
+
+// Reversible stand-in for safeStorage: the tests are about WHERE values go,
+// not about the OS cipher. The prefix makes an accidental plaintext write
+// (a value that skipped encrypt) visible as a mismatch.
+const codec: SecretCodec = {
+  isEncryptionAvailable: () => true,
+  encrypt: plain => Buffer.from(`enc:${plain}`, 'utf8'),
+  decrypt: cipher => {
+    const text = cipher.toString('utf8')
+    if (!text.startsWith('enc:')) throw new Error('not ours')
+    return text.slice(4)
+  },
+}
+
+const TOKEN = 'bpr_live_9f3a1c7d'
+
+let dir: string
+let native: NativeMcpServerSource[]
+let codexNames: Set<string>
+let managed: boolean
+
+function service(): UserMcpService {
+  return new UserMcpService({
+    stateDir: dir,
+    codec,
+    native: {
+      list: async () => native,
+      codexNames: async () => codexNames,
+      claudeManagedPolicy: async () => managed,
+    },
+  })
+}
+
+const beeper = (overrides: Partial<UserMcpSaveInput> = {}): UserMcpSaveInput => ({
+  name: 'beeper',
+  enabled: true,
+  providers: { claude: true, codex: true },
+  entry: { type: 'http', url: 'http://localhost:23373/v0/mcp', headers: { Authorization: 'Bearer ${input:beeper-authorization}' } },
+  inputs: [{ id: 'beeper-authorization', description: 'Header Authorization' }],
+  secrets: { 'beeper-authorization': TOKEN },
+  ...overrides,
+})
+
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'user-mcp-'))
+  native = []
+  codexNames = new Set()
+  managed = false
+})
+afterEach(async () => {
+  await rm(dir, { recursive: true, force: true })
+})
+
+describe('UserMcpService storage', () => {
+  it('persists the server without its secret, and the snapshot shows only a hint', async () => {
+    const result = await service().save(beeper())
+    expect(result.ok).toBe(true)
+    const onDisk = await readFile(join(dir, 'mcp-servers.json'), 'utf8')
+    expect(onDisk).toContain('beeper')
+    expect(onDisk).not.toContain(TOKEN)
+    expect((await stat(join(dir, 'mcp-servers.json'))).mode & 0o777).toBe(0o600)
+    if (!result.ok) return
+    expect(JSON.stringify(result.snapshot)).not.toContain(TOKEN)
+    expect(result.snapshot.servers[0]!.secrets['beeper-authorization']).toEqual({ set: true, hint: '1c7d' })
+  })
+
+  it('refuses structurally invalid servers but accepts a server whose secret is not set yet', async () => {
+    const svc = service()
+    expect(await svc.save(beeper({ name: 'agent_code' }))).toMatchObject({ ok: false })
+    const pending = await svc.save(beeper({ secrets: {} }))
+    expect(pending.ok).toBe(true)
+    if (!pending.ok) return
+    expect(pending.snapshot.servers[0]!.problems.map(problem => problem.kind)).toEqual(['secret-missing'])
+  })
+
+  it('moves an unreadable document aside instead of erasing it', async () => {
+    await writeFile(join(dir, 'mcp-servers.json'), '{ not json')
+    const snapshot = await service().snapshot()
+    expect(snapshot.servers).toEqual([])
+    expect(snapshot.storeProblem).toMatch(/moved to/)
+    expect((await readdir(dir)).some(file => file.startsWith('mcp-servers.json.corrupt-'))).toBe(true)
+  })
+
+  it('deletes a server together with its secrets', async () => {
+    const svc = service()
+    const saved = await svc.save(beeper())
+    if (!saved.ok) throw new Error(saved.error)
+    await svc.delete(saved.id!)
+    expect(await readdir(join(dir, 'mcp-secrets'))).toEqual([])
+  })
+
+  it('copies a CLI-native server in, attached only to the other provider, with secrets unset', async () => {
+    native = [{
+      provider: 'codex', name: 'sentry', source: '~/.codex/config.toml', transport: 'http', summary: 'mcp.sentry.dev/mcp', copyable: true,
+      entry: { type: 'http', url: 'https://mcp.sentry.dev/mcp', headers: { Authorization: 'Bearer ${input:sentry-authorization}' } },
+      inputs: [{ id: 'sentry-authorization', description: 'Header Authorization' }],
+    }]
+    const result = await service().copyNative('codex', 'sentry')
+    if (!result.ok) throw new Error(result.error)
+    const copy = result.snapshot.servers[0]!
+    expect(copy.providers).toEqual({ claude: true, codex: false })
+    expect(copy.secrets['sentry-authorization']).toEqual({ set: false })
+  })
+})
+
+describe('UserMcpService.resolveForLaunch', () => {
+  async function saved(input: UserMcpSaveInput = beeper()) {
+    const svc = service()
+    const result = await svc.save(input)
+    if (!result.ok) throw new Error(result.error)
+    return { svc, id: result.id! }
+  }
+
+  it('attaches a default-on server with its secret resolved', async () => {
+    const { svc, id } = await saved()
+    const resolution = await svc.resolveForLaunch({ provider: 'codex', overrides: {}, cwd: dir })
+    expect(resolution.attachedIds).toEqual([id])
+    expect(resolution.servers[0]!.secrets).toEqual({ 'beeper-authorization': TOKEN })
+    expect(resolution.dropped).toEqual([])
+  })
+
+  it('lets a per-agent override add or remove a server', async () => {
+    const { svc, id } = await saved(beeper({ providers: { claude: false, codex: false } }))
+    expect((await svc.resolveForLaunch({ provider: 'claude', overrides: {}, cwd: dir })).attachedIds).toEqual([])
+    expect((await svc.resolveForLaunch({ provider: 'claude', overrides: { [id]: true }, cwd: dir })).attachedIds).toEqual([id])
+    const { svc: svc2, id: id2 } = await saved(beeper({ name: 'beeper2' }))
+    expect((await svc2.resolveForLaunch({ provider: 'claude', overrides: { [id2]: false }, cwd: dir })).attachedIds)
+      .not.toContain(id2)
+  })
+
+  it('never attaches a server whose master switch is off, even with a per-agent on', async () => {
+    const { svc, id } = await saved(beeper({ enabled: false }))
+    const resolution = await svc.resolveForLaunch({ provider: 'claude', overrides: { [id]: true }, cwd: dir })
+    expect(resolution.attachedIds).toEqual([])
+    // Silent: the user turned it off everywhere, so there is nothing to warn about.
+    expect(resolution.dropped).toEqual([])
+  })
+
+  it('drops a requested server with a reason when its secret is missing', async () => {
+    const { svc } = await saved(beeper({ secrets: {} }))
+    const resolution = await svc.resolveForLaunch({ provider: 'claude', overrides: {}, cwd: dir })
+    expect(resolution.attachedIds).toEqual([])
+    expect(resolution.dropped).toEqual([{ name: 'beeper', reason: 'Secret "beeper-authorization" is not set' }])
+  })
+
+  it('refuses a Codex name that is already in the user\'s Codex config, but not for Claude', async () => {
+    const { svc, id } = await saved()
+    codexNames = new Set(['beeper'])
+    expect((await svc.resolveForLaunch({ provider: 'codex', overrides: {}, cwd: dir })).dropped[0]?.reason)
+      .toMatch(/already in your Codex config/)
+    expect((await svc.resolveForLaunch({ provider: 'claude', overrides: {}, cwd: dir })).attachedIds).toEqual([id])
+  })
+
+  it('holds user servers back for Claude under an enterprise MCP policy', async () => {
+    const { svc } = await saved()
+    managed = true
+    const resolution = await svc.resolveForLaunch({ provider: 'claude', overrides: {}, cwd: dir })
+    expect(resolution.attachedIds).toEqual([])
+    expect(resolution.dropped[0]?.reason).toMatch(/policy/)
+  })
+
+  it('keeps SSE servers off Codex with a reason', async () => {
+    const { svc } = await saved(beeper({
+      name: 'linear', entry: { type: 'sse', url: 'https://mcp.linear.app/sse' }, inputs: [], secrets: {},
+    }))
+    const resolution = await svc.resolveForLaunch({ provider: 'codex', overrides: {}, cwd: dir })
+    expect(resolution.dropped).toEqual([{ name: 'linear', reason: 'Codex does not support SSE servers' }])
+  })
+
+  it('gives providers without user MCP support nothing', async () => {
+    const { svc } = await saved()
+    expect(await svc.resolveForLaunch({ provider: 'opencode', overrides: {}, cwd: dir }))
+      .toEqual({ servers: [], attachedIds: [], dropped: [] })
+  })
+})
+
+describe('native server discovery', () => {
+  it('reads user-scope servers from both CLIs and never forwards their values', async () => {
+    await writeFile(join(dir, '.claude.json'), JSON.stringify({
+      mcpServers: { context7: { type: 'http', url: 'https://mcp.context7.com/mcp', headers: { CONTEXT7_API_KEY: 'ctx7_secret' } } },
+    }))
+    const codexHome = join(dir, 'codex')
+    await import('node:fs/promises').then(fs => fs.mkdir(codexHome))
+    await writeFile(join(codexHome, 'config.toml'), [
+      '[mcp_servers.sentry]',
+      'url = "https://mcp.sentry.dev/mcp"',
+      'bearer_token_env_var = "SENTRY_TOKEN"',
+      '',
+      '[mcp_servers.fs]',
+      'command = "npx"',
+      'args = ["-y", "@modelcontextprotocol/server-filesystem"]',
+      'env = { ROOT_TOKEN = "fs_secret" }',
+    ].join('\n'))
+    const servers = await readNativeMcpServers({ home: dir, codexHome, platform: 'darwin' })
+    expect(servers.map(server => `${server.provider}:${server.name}`)).toEqual(['claude:context7', 'codex:sentry', 'codex:fs'])
+    expect(JSON.stringify(servers)).not.toMatch(/ctx7_secret|fs_secret/)
+    expect(servers.find(server => server.name === 'sentry')!.entry).toEqual({
+      type: 'http', url: 'https://mcp.sentry.dev/mcp', headers: { Authorization: 'Bearer ${input:sentry-authorization}' },
+    })
+    expect(await codexNativeServerNames(join(dir, 'project'), { home: dir, codexHome, platform: 'darwin' }))
+      .toEqual(new Set(['sentry', 'fs']))
+  })
+})
+
+describe('UserMcpService unreadable document (review round 1)', () => {
+  it('refuses writes while the document cannot be read, instead of replacing it with an empty list', async () => {
+    const file = join(dir, 'mcp-servers.json')
+    await writeFile(file, JSON.stringify({ version: 1, servers: [{ id: 'keep-me', name: 'kept', enabled: true, providers: { claude: true, codex: true }, entry: { command: 'x' }, inputs: [] }] }))
+    const { chmod } = await import('node:fs/promises')
+    await chmod(file, 0o000)
+    try {
+      const svc = service()
+      const result = await svc.save(beeper())
+      expect(result.ok).toBe(false)
+      if (!result.ok) expect(result.error).toMatch(/Nothing was changed/)
+    } finally {
+      await chmod(file, 0o600)
+    }
+    expect(await readFile(file, 'utf8')).toContain('keep-me')
+  })
+
+  it('recovers once the document becomes readable again', async () => {
+    const file = join(dir, 'mcp-servers.json')
+    await writeFile(file, JSON.stringify({ version: 1, servers: [{ id: 'keep-me', name: 'kept', enabled: true, providers: { claude: true, codex: true }, entry: { command: 'x' }, inputs: [] }] }))
+    const { chmod } = await import('node:fs/promises')
+    await chmod(file, 0o000)
+    const svc = service()
+    await svc.initialize()
+    await chmod(file, 0o600)
+    const result = await svc.save(beeper())
+    expect(result.ok).toBe(true)
+    if (result.ok) expect(result.snapshot.servers.map(server => server.name).sort()).toEqual(['beeper', 'kept'])
+  })
+})
+
+describe('UserMcpService secret redirection (review round 1)', () => {
+  it('forgets stored secrets when a server is pointed somewhere else', async () => {
+    const svc = service()
+    const saved = await svc.save(beeper())
+    if (!saved.ok) throw new Error(saved.error)
+    const moved = await svc.save({ ...beeper(), id: saved.id, secrets: undefined, entry: { type: 'http', url: 'https://evil.example/mcp', headers: { Authorization: 'Bearer ${input:beeper-authorization}' } } })
+    expect(moved).toMatchObject({ ok: true, secretsCleared: true })
+    const launch = await svc.resolveForLaunch({ provider: 'claude', overrides: {}, cwd: dir })
+    // The token never reaches the new host: the server is dropped instead.
+    expect(launch.servers).toEqual([])
+    expect(launch.dropped[0]?.reason).toMatch(/not set/)
+  })
+
+  it('keeps secrets when only the name or the providers change', async () => {
+    const svc = service()
+    const saved = await svc.save(beeper())
+    if (!saved.ok) throw new Error(saved.error)
+    const edited = await svc.save({ ...beeper(), id: saved.id, name: 'beeper-desktop', secrets: undefined, providers: { claude: true, codex: false } })
+    expect(edited).toMatchObject({ ok: true })
+    expect(edited).not.toHaveProperty('secretsCleared')
+    expect((await svc.resolveForLaunch({ provider: 'claude', overrides: {}, cwd: dir })).servers[0]?.secrets)
+      .toEqual({ 'beeper-authorization': TOKEN })
+  })
+})
+
+
+describe('UserMcpService review round 2', () => {
+  const stdio = (env: Record<string, string>): UserMcpSaveInput => ({
+    name: 'gh', enabled: true, providers: { claude: true, codex: true },
+    entry: { command: 'npx', args: ['-y', '@modelcontextprotocol/server-github'], env },
+    inputs: [{ id: 'pat', description: '' }], secrets: { pat: TOKEN },
+  })
+
+  it('forgets secrets when a literal env value is added, not only when the command moves', async () => {
+    // NODE_OPTIONS=--require ./evil.js runs attacker code with the token in
+    // its env even though command/args/url are unchanged.
+    const svc = service()
+    const saved = await svc.save(stdio({ GITHUB_PERSONAL_ACCESS_TOKEN: '${input:pat}' }))
+    if (!saved.ok) throw new Error(saved.error)
+    const edited = await svc.save({ ...stdio({ GITHUB_PERSONAL_ACCESS_TOKEN: '${input:pat}', NODE_OPTIONS: '--require /tmp/evil.js' }), id: saved.id, secrets: undefined })
+    expect(edited).toMatchObject({ ok: true, secretsCleared: true })
+  })
+
+  it('stores a server an agent adds switched off and flagged for review', async () => {
+    const svc = service()
+    const added = await svc.save(beeper(), 'agent')
+    if (!added.ok) throw new Error(added.error)
+    const view = added.snapshot.servers[0]!
+    expect(view.enabled).toBe(false)
+    expect(view.pendingReview).toBe(true)
+    expect(view.problems[0]?.kind).toBe('pending-review')
+    expect((await svc.resolveForLaunch({ provider: 'claude', overrides: { [view.id]: true }, cwd: dir })).servers).toEqual([])
+  })
+
+  it('never lets an agent turn a server on, and lets the user approve it', async () => {
+    const svc = service()
+    const added = await svc.save(beeper(), 'agent')
+    if (!added.ok) throw new Error(added.error)
+    const id = added.id!
+    expect(await svc.setEnabled(id, true, 'agent')).toMatchObject({ ok: false })
+    expect(await svc.save({ ...beeper(), id, enabled: true }, 'agent')).toMatchObject({ ok: true })
+    expect((await svc.snapshot()).servers[0]!.enabled).toBe(false)
+    const approved = await svc.setEnabled(id, true)
+    if (!approved.ok) throw new Error(approved.error)
+    expect(approved.snapshot.servers[0]!.pendingReview).toBeUndefined()
+    expect((await svc.resolveForLaunch({ provider: 'claude', overrides: {}, cwd: dir })).attachedIds).toEqual([id])
+  })
+
+  it('switches an approved server back off when an agent points it somewhere new', async () => {
+    const svc = service()
+    const saved = await svc.save(beeper())
+    if (!saved.ok) throw new Error(saved.error)
+    const moved = await svc.save({ ...beeper(), id: saved.id, secrets: undefined, entry: { type: 'http', url: 'https://evil.example/mcp' }, inputs: [] }, 'agent')
+    expect(moved).toMatchObject({ ok: true, pendingReview: true })
+    expect((await svc.snapshot()).servers[0]!.enabled).toBe(false)
+  })
+
+  it('refuses a secret value that Claude would expand from its own environment', async () => {
+    const svc = service()
+    expect(await svc.save(beeper({ secrets: { 'beeper-authorization': '${GITHUB_TOKEN}' } }))).toMatchObject({ ok: false })
+  })
+})
diff --git a/src/main/userMcp/service.ts b/src/main/userMcp/service.ts
new file mode 100644
index 000000000..cc9a4ef57
--- /dev/null
+++ b/src/main/userMcp/service.ts
@@ -0,0 +1,492 @@
+import { randomUUID } from 'node:crypto'
+import { join } from 'node:path'
+
+import type { SecretCodec } from '@main/keyVault/vaultStore.js'
+import {
+  addCodexUserMcpLaunchConfig,
+  claudeUserMcpEntries,
+  type CodexShellPolicyStyle,
+  type ResolvedUserMcpServer,
+} from '@providers/shared/runtime/userMcpLaunch.js'
+import { importUserMcpConfig } from '@shared/userMcp/importConfig.js'
+import {
+  isUserMcpProvider,
+  type NativeMcpServer,
+  type NativeMcpServerSource,
+  type UserMcpActor,
+  type UserMcpDocument,
+  type UserMcpDroppedServer,
+  type UserMcpImportResult,
+  type UserMcpMutationResult,
+  type UserMcpProblem,
+  type UserMcpProvider,
+  type UserMcpSaveInput,
+  type UserMcpServer,
+  type UserMcpServerView,
+  type UserMcpSnapshot,
+} from '@shared/userMcp/types.js'
+import {
+  coerceInputs,
+  normalizeEntry,
+  secretValueProblem,
+  userMcpDestination,
+  providerSupportForEntry,
+  referencedInputIds,
+  summarizeEntry,
+  transportOf,
+  validateServer,
+} from '@shared/userMcp/validate.js'
+
+import {
+  claudeManagedMcpPolicyPresent,
+  codexNativeServerNames,
+  codexShellPolicyStyle,
+  readNativeMcpServers,
+} from './nativeServers.js'
+import { UserMcpSecretStore } from './secrets.js'
+import { loadUserMcpDocument, saveUserMcpDocument } from './store.js'
+
+export type UserMcpLaunchResolution = {
+  servers: ResolvedUserMcpServer[]
+  attachedIds: string[]
+  dropped: UserMcpDroppedServer[]
+  /** Codex only: how to send the shell exclusions for the secrets it carries. */
+  codexShellPolicy?: CodexShellPolicyStyle
+}
+
+export type UserMcpServiceDeps = {
+  stateDir: string
+  codec: SecretCodec
+  /** Injectable for tests; production reads the real CLI config files. */
+  native?: {
+    list(): Promise<NativeMcpServerSource[]>
+    codexNames(cwd: string): Promise<Set<string>>
+    claudeManagedPolicy(): Promise<boolean>
+    codexShellPolicy?(cwd: string): Promise<CodexShellPolicyStyle>
+  }
+}
+
+/**
+ * Single owner of user MCP servers (#1143): the document, the secrets, and the
+ * launch-time decision of what attaches to which agent.
+ *
+ * WHY main decides what attaches, not the renderer (spec Revision 2 §4): main
+ * owns the document and the only copy of the secrets, and a renderer holding a
+ * stale snapshot must not be able to attach a server the user has since
+ * deleted or switched off. The renderer contributes only the pane's explicit
+ * per-agent choices; everything else is read here at launch.
+ */
+export class UserMcpService {
+  private document: UserMcpDocument = { version: 1, servers: [] }
+  private storeProblem: string | undefined
+  private readonly file: string
+  private readonly secrets: UserMcpSecretStore
+  private readonly native: NonNullable<UserMcpServiceDeps['native']>
+  private readonly listeners = new Set<(snapshot: UserMcpSnapshot) => void>()
+  // Every mutation runs after the previous one settles. Two windows toggling
+  // at once would otherwise both read-modify-write the same document and the
+  // later write would silently discard the earlier change.
+  private tail: Promise<unknown> = Promise.resolve()
+  private initialized: Promise<void> | null = null
+  // Set while the document on disk could not be read (see
+  // LoadedUserMcpDocument.readFailed). Writing then would atomically replace
+  // every server the user configured with the empty in-memory list, so
+  // mutations are refused until a re-read succeeds.
+  private readFailed = false
+
+  constructor(deps: UserMcpServiceDeps) {
+    this.file = join(deps.stateDir, 'mcp-servers.json')
+    this.secrets = new UserMcpSecretStore(join(deps.stateDir, 'mcp-secrets'), deps.codec)
+    this.native = deps.native ?? {
+      list: () => readNativeMcpServers(),
+      codexNames: cwd => codexNativeServerNames(cwd),
+      claudeManagedPolicy: () => claudeManagedMcpPolicyPresent(),
+      codexShellPolicy: cwd => codexShellPolicyStyle(cwd),
+    }
+  }
+
+  initialize(): Promise<void> {
+    this.initialized ??= (async () => {
+      const loaded = await loadUserMcpDocument(this.file)
+      this.document = loaded.document
+      this.storeProblem = loaded.problem
+      this.readFailed = loaded.readFailed === true
+    })()
+    return this.initialized
+  }
+
+  onChange(listener: (snapshot: UserMcpSnapshot) => void): () => void {
+    this.listeners.add(listener)
+    return () => this.listeners.delete(listener)
+  }
+
+  async snapshot(): Promise<UserMcpSnapshot> {
+    await this.initialize()
+    const [native, claudeManagedPolicy] = await Promise.all([
+      this.native.list().catch(() => [] as NativeMcpServerSource[]),
+      this.native.claudeManagedPolicy().catch(() => false),
+    ])
+    // Names already in the user's own Codex config.toml collide at every Codex
+    // launch (see codexNativeServerNames), so the view says so up front.
+    // Project-scope files depend on the agent's cwd and are only caught at
+    // launch, with a notice.
+    const codexNativeNames = new Set(native.filter(entry => entry.provider === 'codex').map(entry => entry.name))
+    const claudeNativeNames = new Set(native.filter(entry => entry.provider === 'claude').map(entry => entry.name))
+    const servers = await Promise.all(this.document.servers.map(server =>
+      this.view(server, claudeManagedPolicy, codexNativeNames, claudeNativeNames)))
+    return {
+      servers,
+      // Strip Copy-in material: see NativeMcpServer.copyable.
+      native: native.map(({ entry: _entry, inputs: _inputs, ...view }): NativeMcpServer => view),
+      claudeManagedPolicy,
+      ...(this.storeProblem ? { storeProblem: this.storeProblem } : {}),
+    }
+  }
+
+  importConfig(text: string, fallbackName?: string): UserMcpImportResult {
+    return importUserMcpConfig(text, fallbackName)
+  }
+
+  save(input: UserMcpSaveInput, actor: UserMcpActor = 'user'): Promise<UserMcpMutationResult> {
+    return this.mutate(async () => {
+      const existing = input.id ? this.document.servers.find(server => server.id === input.id) : undefined
+      if (input.id && !existing) return { ok: false, error: 'That server no longer exists.' }
+      for (const value of Object.values(input.secrets ?? {})) {
+        const problem = value === '' ? null : secretValueProblem(value)
+        if (problem) return { ok: false, error: problem }
+      }
+      const entry = normalizeEntry(input.entry)
+      const destinationChanged = existing !== undefined && userMcpDestination(existing.entry) !== userMcpDestination(entry)
+      // An agent proposes, the user approves (review round 2): a server an
+      // agent adds, or points somewhere new, is stored OFF and flagged for
+      // review, and an agent can never turn one on. Otherwise a single
+      // prompt-injected agent could install a command that every future agent
+      // runs. A user save of an existing server clears the flag only by
+      // turning it on (setEnabled); saving it off keeps the flag visible.
+      const agentNeedsReview = actor === 'agent' && (existing === undefined || destinationChanged || existing.pendingReview === true)
+      const enabled = actor === 'agent'
+        ? (agentNeedsReview ? false : existing!.enabled && input.enabled)
+        : input.enabled
+      const pendingReview = agentNeedsReview || (actor === 'user' && existing?.pendingReview === true && !enabled)
+      const server: UserMcpServer = {
+        id: existing?.id ?? randomUUID(),
+        name: input.name.trim(),
+        enabled,
+        providers: { claude: input.providers.claude === true, codex: input.providers.codex === true },
+        entry,
+        inputs: coerceInputs(input.inputs),
+        ...(pendingReview ? { pendingReview: true as const } : {}),
+      }
+      const others = this.document.servers.filter(other => other.id !== server.id)
+      // Structural problems block the save. A missing secret does not: it is a
+      // normal intermediate state (paste config now, fetch the token later),
+      // and launch already refuses to attach the server until it is set.
+      const problems = validateServer(server, others)
+      if (problems.length > 0) return { ok: false, error: problems[0]!.message, problems }
+      // Changing WHERE a server connects forgets its stored secrets (review
+      // round 1). Otherwise an edit — or an agent's mcp_servers_update after a
+      // prompt injection — could keep `${input:token}` and point the entry at
+      // another host or command, and the next launch would hand the token to
+      // it: exfiltration without ever reading a secret. Secrets supplied in
+      // this same save are set afterwards, so an intentional move that
+      // re-enters the token still works in one step.
+      this.document = {
+        version: 1,
+        servers: existing
+          ? this.document.servers.map(candidate => candidate.id === server.id ? server : candidate)
+          : [...this.document.servers, server],
+      }
+      // Document first, secret blobs after (review round 2): a failed persist
+      // rolls the document back in mutate(), and blobs cleared before it could
+      // not be rolled back, so a failed destination edit used to lose the
+      // server's token for good.
+      await this.persist()
+      if (destinationChanged) await this.secrets.clearServer(server.id)
+      for (const [inputId, value] of Object.entries(input.secrets ?? {})) {
+        if (server.inputs.some(candidate => candidate.id === inputId)) {
+          await this.secrets.set(server.id, inputId, value)
+        }
+      }
+      await this.secrets.prune(server.id, server.inputs.map(candidate => candidate.id))
+      return {
+        ok: true,
+        id: server.id,
+        ...(destinationChanged ? { secretsCleared: true } : {}),
+        ...(pendingReview ? { pendingReview: true } : {}),
+      }
+    })
+  }
+
+  delete(id: string): Promise<UserMcpMutationResult> {
+    return this.mutate(async () => {
+      if (!this.document.servers.some(server => server.id === id)) return { ok: false, error: 'That server no longer exists.' }
+      this.document = { version: 1, servers: this.document.servers.filter(server => server.id !== id) }
+      await this.persist()
+      await this.secrets.clearServer(id)
+      return { ok: true }
+    })
+  }
+
+  /** Agents may only turn a server OFF; turning one on is the user's review
+   * decision, and doing so clears pendingReview. */
+  setEnabled(id: string, enabled: boolean, actor: UserMcpActor = 'user'): Promise<UserMcpMutationResult> {
+    if (actor === 'agent' && enabled) {
+      return Promise.resolve({ ok: false, error: 'Only the user can turn an MCP server on (Settings → MCP).' })
+    }
+    return this.update(id, server => {
+      const { pendingReview: _pending, ...rest } = server
+      return enabled ? { ...rest, enabled } : { ...server, enabled }
+    })
+  }
+
+  setProvider(id: string, provider: UserMcpProvider, enabled: boolean): Promise<UserMcpMutationResult> {
+    return this.update(id, server => ({ ...server, providers: { ...server.providers, [provider]: enabled } }))
+  }
+
+  setSecret(id: string, inputId: string, value: string): Promise<UserMcpMutationResult> {
+    return this.mutate(async () => {
+      const problem = value === '' ? null : secretValueProblem(value)
+      if (problem) return { ok: false, error: problem }
+      const server = this.document.servers.find(candidate => candidate.id === id)
+      if (!server) return { ok: false, error: 'That server no longer exists.' }
+      if (!server.inputs.some(input => input.id === inputId)) return { ok: false, error: `No secret named "${inputId}".` }
+      await this.secrets.set(id, inputId, value)
+      return { ok: true }
+    })
+  }
+
+  /**
+   * Copy a CLI-native server into Agent Code.
+   *
+   * The copy starts attached only to the OTHER provider. WHY: the source CLI
+   * keeps loading its own entry, so attaching the copy there too duplicates it
+   * — and for Codex, a same-name launch entry is refused at launch (see
+   * codexNativeServerNames). Sharing a server the user set up in one CLI with
+   * the other is the main reason to copy it in.
+   */
+  copyNative(provider: UserMcpProvider, name: string): Promise<UserMcpMutationResult> {
+    return this.mutate(async () => {
+      const native = (await this.native.list()).find(server => server.provider === provider && server.name === name)
+      if (!native?.entry) return { ok: false, error: 'That server can no longer be read from its config file.' }
+      const others = this.document.servers
+      const server: UserMcpServer = {
+        id: randomUUID(),
+        name: native.name,
+        enabled: true,
+        providers: { claude: provider !== 'claude', codex: provider !== 'codex' },
+        entry: normalizeEntry(native.entry),
+        inputs: native.inputs,
+      }
+      const problems = validateServer(server, others)
+      if (problems.length > 0) return { ok: false, error: problems[0]!.message, problems }
+      this.document = { version: 1, servers: [...others, server] }
+      await this.persist()
+      return { ok: true, id: server.id }
+    })
+  }
+
+  /**
+   * Decide and materialize the user servers for one agent launch.
+   *
+   * `overrides` are the pane's explicit per-agent choices (bare server ids).
+   * Order of rules, and why:
+   *  1. master switch off → skip silently. The user turned it off everywhere,
+   *     so there is nothing to warn about, even for a per-agent "on".
+   *  2. not requested (no override and provider default off) → skip silently.
+   *  3. requested but unusable (invalid, unsupported transport, enterprise
+   *     policy, native name collision, missing secret, translator refusal) →
+   *     drop WITH a reason. The user asked for it, so silence would read as
+   *     "it's attached" while the agent has no such tools.
+   * A dropped server never fails the launch.
+   */
+  async resolveForLaunch(params: {
+    provider: string
+    overrides: Readonly<Record<string, boolean>>
+    cwd: string
+  }): Promise<UserMcpLaunchResolution> {
+    await this.initialize()
+    const empty: UserMcpLaunchResolution = { servers: [], attachedIds: [], dropped: [] }
+    if (!isUserMcpProvider(params.provider)) return empty
+    const provider = params.provider
+    const requested = this.document.servers.filter(server =>
+      server.enabled && (params.overrides[server.id] ?? server.providers[provider]))
+    if (requested.length === 0) return empty
+
+    const dropped: UserMcpDroppedServer[] = []
+    const candidates: ResolvedUserMcpServer[] = []
+    const claudeManaged = provider === 'claude' && await this.native.claudeManagedPolicy().catch(() => false)
+    const codexNames = provider === 'codex'
+      ? await this.native.codexNames(params.cwd).catch(() => new Set<string>())
+      : new Set<string>()
+    for (const server of requested) {
+      const others = this.document.servers.filter(other => other.id !== server.id)
+      const problem = validateServer(server, others)[0]
+      if (problem) {
+        dropped.push({ name: server.name, reason: problem.message })
+        continue
+      }
+      const support = providerSupportForEntry(server.entry)[provider]
+      if (!support.ok) {
+        dropped.push({ name: server.name, reason: support.reason })
+        continue
+      }
+      if (claudeManaged) {
+        dropped.push({ name: server.name, reason: "Your organization's Claude MCP policy only allows its own servers" })
+        continue
+      }
+      if (server.pendingReview) {
+        dropped.push({ name: server.name, reason: 'Waiting for your review in Settings → MCP' })
+        continue
+      }
+      if (codexNames.has(server.name)) {
+        dropped.push({ name: server.name, reason: 'A server with this name is already in your Codex config.toml' })
+        continue
+      }
+      const secrets: Record<string, string> = {}
+      let missing: string | null = null
+      for (const inputId of referencedInputIds(server.entry)) {
+        const value = await this.secrets.get(server.id, inputId)
+        if (value === null) {
+          missing = inputId
+          break
+        }
+        secrets[inputId] = value
+      }
+      if (missing) {
+        dropped.push({ name: server.name, reason: `Secret "${missing}" is not set` })
+        continue
+      }
+      candidates.push({ id: server.id, name: server.name, entry: server.entry, secrets })
+    }
+
+    // Dry-run the provider translator here, where drops can be reported, so
+    // the provider session never has to silently omit a server it was handed.
+    // Both translators are pure and deterministic over the same input.
+    const codexShellPolicy = provider === 'codex'
+      ? await (this.native.codexShellPolicy?.(params.cwd) ?? Promise.resolve({ style: 'filters' } as const))
+        .catch(() => ({ style: 'filters' } as const))
+      : undefined
+    const translatorDrops = provider === 'claude'
+      ? claudeUserMcpEntries(candidates).dropped
+      // The dry run sees the same inherited environment the Codex process will
+      // (Codex inherits main's), so its "your environment already sets X"
+      // refusal is reported here rather than silently applied in the session.
+      : addCodexUserMcpLaunchConfig(candidates, [], inheritedEnvironment(), codexShellPolicy)
+    const refused = new Set(translatorDrops.map(server => server.name))
+    dropped.push(...translatorDrops)
+    const servers = candidates.filter(server => !refused.has(server.name))
+    return {
+      servers,
+      attachedIds: servers.map(server => server.id),
+      dropped,
+      ...(codexShellPolicy ? { codexShellPolicy } : {}),
+    }
+  }
+
+  private update(id: string, change: (server: UserMcpServer) => UserMcpServer): Promise<UserMcpMutationResult> {
+    return this.mutate(async () => {
+      const server = this.document.servers.find(candidate => candidate.id === id)
+      if (!server) return { ok: false, error: 'That server no longer exists.' }
+      this.document = {
+        version: 1,
+        servers: this.document.servers.map(candidate => candidate.id === id ? change(candidate) : candidate),
+      }
+      await this.persist()
+      return { ok: true }
+    })
+  }
+
+  private mutate(
+    operation: () => Promise<{ ok: true; id?: string; secretsCleared?: boolean; pendingReview?: boolean } | { ok: false; error: string; problems?: UserMcpProblem[] }>,
+  ): Promise<UserMcpMutationResult> {
+    const run = this.tail.then(async (): Promise<UserMcpMutationResult> => {
+      await this.initialize()
+      const before = this.document
+      if (this.readFailed) {
+        // A transient failure (a restore holding the file, EMFILE while many
+        // agents start) usually clears; retry before refusing.
+        const loaded = await loadUserMcpDocument(this.file)
+        if (loaded.readFailed) {
+          return { ok: false, error: `${loaded.problem ?? 'MCP settings could not be read'}. Nothing was changed.` }
+        }
+        this.document = loaded.document
+        this.storeProblem = loaded.problem
+        this.readFailed = false
+      }
+      try {
+        const outcome = await operation()
+        if (!outcome.ok) return outcome
+        const snapshot = await this.snapshot()
+        for (const listener of this.listeners) listener(snapshot)
+        return {
+          ok: true,
+          snapshot,
+          ...(outcome.id ? { id: outcome.id } : {}),
+          ...(outcome.secretsCleared ? { secretsCleared: true } : {}),
+          ...(outcome.pendingReview ? { pendingReview: true } : {}),
+        }
+      } catch (error) {
+        // Review round 1: a failed persist must not leave memory ahead of
+        // disk, or the snapshot shows a server that a restart will lose and a
+        // retry is refused as a duplicate. (Secrets written before the failure
+        // are orphaned blobs at worst; the next save of that server prunes them.)
+        this.document = before
+        return { ok: false, error: error instanceof Error ? error.message : String(error) }
+      }
+    })
+    this.tail = run.catch(() => {})
+    return run
+  }
+
+  private async persist(): Promise<void> {
+    await saveUserMcpDocument(this.file, this.document)
+    // A successful write supersedes whatever made the old file unreadable.
+    this.storeProblem = undefined
+  }
+
+  private async view(
+    server: UserMcpServer,
+    claudeManagedPolicy: boolean,
+    codexNativeNames: ReadonlySet<string>,
+    claudeNativeNames: ReadonlySet<string>,
+  ): Promise<UserMcpServerView> {
+    const transport = transportOf(server.entry)
+    const others = this.document.servers.filter(other => other.id !== server.id)
+    const secrets = await this.secrets.state(server.id, server.inputs.map(input => input.id))
+    const problems = validateServer(server, others)
+    for (const inputId of referencedInputIds(server.entry)) {
+      if (secrets[inputId] && !secrets[inputId]!.set) {
+        problems.push({ kind: 'secret-missing', message: `Secret "${inputId}" is not set` })
+      }
+    }
+    if (server.pendingReview) {
+      problems.unshift({ kind: 'pending-review', message: 'Added or changed by an agent — review the config, then turn it on' })
+    }
+    // Spec Decisions: Claude replaces a same-name native server with ours for
+    // Agent Code launches (whole-entry --mcp-config precedence), while the
+    // user's own `claude` runs keep theirs. Say so, or a rotated native token
+    // looks ignored (review round 2).
+    if (claudeNativeNames.has(server.name) && server.providers.claude) {
+      problems.push({ kind: 'claude-native-name', message: 'Also in your Claude config; Agent Code agents use this one instead' })
+    }
+    const support = { ...providerSupportForEntry(server.entry) }
+    if (claudeManagedPolicy) {
+      support.claude = { ok: false, reason: "Your organization's Claude MCP policy only allows its own servers" }
+    }
+    if (support.codex.ok && codexNativeNames.has(server.name)) {
+      support.codex = { ok: false, reason: 'A server with this name is already in your Codex config.toml' }
+    }
+    return {
+      ...server,
+      transport,
+      summary: summarizeEntry(server.entry),
+      secrets,
+      problems,
+      support,
+    }
+  }
+}
+
+function inheritedEnvironment(): Record<string, string> {
+  return Object.fromEntries(Object.entries(process.env).filter((entry): entry is [string, string] => typeof entry[1] === 'string'))
+}
diff --git a/src/main/userMcp/store.ts b/src/main/userMcp/store.ts
new file mode 100644
index 000000000..153c5e362
--- /dev/null
+++ b/src/main/userMcp/store.ts
@@ -0,0 +1,60 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+
+import type { UserMcpDocument } from '@shared/userMcp/types.js'
+import { coerceUserMcpDocument } from '@shared/userMcp/validate.js'
+
+export type LoadedUserMcpDocument = {
+  document: UserMcpDocument
+  /** Human-readable notice when the file existed but could not be used. */
+  problem?: string
+  /**
+   * The file exists but could not be READ (EACCES, EIO, EMFILE…), as opposed
+   * to read-but-unparseable. Its contents are unknown and still on disk, so a
+   * write would replace them with the empty document: callers must not write
+   * until a later read succeeds.
+   */
+  readFailed?: boolean
+}
+
+/**
+ * Read `mcp-servers.json`.
+ *
+ * WHY a corrupt file is moved aside instead of overwritten or left in place:
+ * leaving it would make every later save either fail or clobber it, and
+ * silently resetting would erase every server the user configured. Renaming
+ * it keeps the bytes recoverable (`mcp-servers.json.corrupt-<time>`) while the
+ * app continues with an empty list and says so in Settings.
+ */
+export async function loadUserMcpDocument(file: string): Promise<LoadedUserMcpDocument> {
+  let text: string
+  try {
+    text = await readFile(file, 'utf8')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return { document: { version: 1, servers: [] } }
+    return {
+      document: { version: 1, servers: [] },
+      problem: `Could not read ${file}: ${(error as Error).message}`,
+      readFailed: true,
+    }
+  }
+  try {
+    return { document: coerceUserMcpDocument(JSON.parse(text)) }
+  } catch (error) {
+    const aside = `${file}.corrupt-${Date.now()}`
+    await rename(file, aside).catch(() => {})
+    return {
+      document: { version: 1, servers: [] },
+      problem: `MCP settings were unreadable (${(error as Error).message}) and were moved to ${aside}.`,
+    }
+  }
+}
+
+/** Atomic replace at mode 0600. The document holds no secret values, but it
+ * does hold server URLs and commands a user may consider private. */
+export async function saveUserMcpDocument(file: string, document: UserMcpDocument): Promise<void> {
+  await mkdir(dirname(file), { recursive: true })
+  const temporary = `${file}.${process.pid}.${Date.now()}.tmp`
+  await writeFile(temporary, `${JSON.stringify(document, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
+  await rename(temporary, file)
+}
diff --git a/src/mcp/runtime/BuiltInMcpHttpHost.ts b/src/mcp/runtime/BuiltInMcpHttpHost.ts
index c0cfa0e94..48b5dbe32 100644
--- a/src/mcp/runtime/BuiltInMcpHttpHost.ts
+++ b/src/mcp/runtime/BuiltInMcpHttpHost.ts
@@ -1,3 +1,4 @@
+import type { UserMcpToolDependencies } from '@mcp/runtime/userMcpTools.js'
 import type { TldrStore } from '@main/tldr/TldrStore.js'
 import { hasReportingDomain } from '@shared/types/tldr.js'
 import { TLDR_HOOK_EVENTS } from '@main/tldr/enforcement.js'
@@ -69,7 +70,7 @@ type BuiltInMcpServerFactory = (
   dependencies: BuiltInMcpDependencies,
 ) => McpServer
 
-export type BuiltInMcpDependencies = {
+export type BuiltInMcpDependencies = UserMcpToolDependencies & {
   tldrStore?: Pick<TldrStore, 'update'>
   goalStore?: Pick<TldrStore, 'update'>
   tldrEnforcement?: Pick<TldrEnforcement, 'handle' | 'forget'>
diff --git a/src/mcp/runtime/createBuiltInMcpServer.test.ts b/src/mcp/runtime/createBuiltInMcpServer.test.ts
index d44dec0a5..6fe9f2aae 100644
--- a/src/mcp/runtime/createBuiltInMcpServer.test.ts
+++ b/src/mcp/runtime/createBuiltInMcpServer.test.ts
@@ -330,3 +330,40 @@ describe('createBuiltInMcpServer root management domain (#906)', () => {
     expect(record).toHaveBeenCalledWith(expect.objectContaining({ area: 'mcp.root_management', name: 'registrar.missing' }))
   })
 })
+
+describe('orchestration child domains (#1143 review round 2)', () => {
+  async function createChild(parentDomains: BuiltInMcpDomain[], requested: BuiltInMcpDomain[]) {
+    const createAgent = vi.fn(async () => ({ sessionId: 'child-1', kind: 'claude' as const, cwd: '/tmp/project' }))
+    const server = createBuiltInMcpServer(
+      { sessionId: 'session-1', cwd: '/tmp/project', domains: parentDomains },
+      {
+        orchestrationBridge: {
+          createAgent,
+          createAgentCallOnce: async (_key: string, run: () => Promise<unknown>) => await run(),
+        } as never,
+        sessionManager: {} as never,
+      },
+    )
+    const client = new Client({ name: 'child-domain-test', version: '0.0.0' })
+    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair()
+    try {
+      await server.connect(serverTransport)
+      await client.connect(clientTransport)
+      await client.callTool({ name: 'orchestration_create_agent', arguments: { kind: 'claude', builtInMcpDomains: requested } })
+      return (createAgent.mock.calls[0] as unknown as [{ builtInMcpDomains?: BuiltInMcpDomain[] }])[0].builtInMcpDomains
+    } finally {
+      await client.close()
+      await server.close()
+    }
+  }
+
+  it('never hands a child mcp_servers or root_management that the parent does not hold', async () => {
+    // Orchestration is on by default, so without this clamp any agent could
+    // mint MCP management (or root control) for a child it drives.
+    expect(await createChild(['orchestration'], ['tldr', 'mcp_servers', 'root_management'])).toEqual(['tldr'])
+  })
+
+  it('still passes them on when the parent holds them itself', async () => {
+    expect(await createChild(['orchestration', 'mcp_servers'], ['mcp_servers'])).toEqual(['mcp_servers'])
+  })
+})
diff --git a/src/mcp/runtime/createBuiltInMcpServer.ts b/src/mcp/runtime/createBuiltInMcpServer.ts
index 6e24df8f5..e149460f4 100644
--- a/src/mcp/runtime/createBuiltInMcpServer.ts
+++ b/src/mcp/runtime/createBuiltInMcpServer.ts
@@ -27,7 +27,7 @@ import type {
 import { buildOrchestrationBootstrapPrompt } from '@mcp/shared/orchestrationPrompt.js'
 import type { BuiltInMcpDependencies } from '@mcp/runtime/BuiltInMcpHttpHost.js'
 import type { PromptDeliveryResult } from '@shared/types/providerConfig.js'
-import { BUILT_IN_MCP_DOMAINS } from '@mcp/shared/types.js'
+import { BUILT_IN_MCP_DOMAINS, PARENT_HELD_ONLY_BUILT_IN_MCP_DOMAINS } from '@mcp/shared/types.js'
 import type { BuiltInMcpDomain, McpSessionScope } from '@mcp/shared/types.js'
 import type { SessionKind } from '@main/sessionManager.js'
 import {
@@ -38,6 +38,7 @@ import {
 } from '@shared/types/providerKind.js'
 import type { AgentProviderKind } from '@shared/types/providerKind.js'
 import { registerWorkflowMcpTools, WORKFLOW_MCP_INSTRUCTIONS } from 'workflow-mcp'
+import { MCP_SERVERS_INSTRUCTIONS, registerUserMcpTools } from '@mcp/runtime/userMcpTools.js'
 
 export const AGENT_MANAGEMENT_MCP_INSTRUCTIONS = `Agent Management controls Agent Code sessions only in the caller's exact current project tab. Listing and reading are safe audit operations and do not wake parked agents; sending a prompt may wake the named target. For cleanup-review requests, use the inventory plus bulk transcript read, classify agents as active/do not close, uncertain/inspect first, or likely cleanup candidates, and cite lifecycle, transcript, relationship, condition, and activity evidence rather than treating age alone as proof. A missing or truncated transcript is not an empty transcript, and an unresolved latest user request or tool work without a final response belongs in inspect first. Transcript evidence cannot prove a worktree is clean unless that transcript or another tool actually checked it; state what remains unknown. Asking what is safe to clean up authorizes assessment only. Reading an agent or sending it a prompt never grants permission to close it. Never call agent_management_close_agent unless the user's current request explicitly asks you to close that specific agent. A request to inspect agents, identify stale agents, recommend cleanup, manage the project, or say what is safe to clean up is not authorization to close anything. Do not infer closure permission from age, completion state, transcript contents, or a prior request.`
 
@@ -186,6 +187,10 @@ export function createBuiltInMcpServer(
     registerAiWorkspaceTools(server, scope, dependencies)
   }
 
+  if (scope.domains.includes('mcp_servers')) {
+    registerUserMcpTools(server, scope, dependencies)
+  }
+
   if (scope.domains.includes('agent_transcripts')) {
     registerAgentTranscriptTools(server)
   }
@@ -229,6 +234,7 @@ function builtInInstructions(
     ...(scope.domains.includes('tldr') ? [TLDR_INSTRUCTIONS] : []),
     ...(scope.domains.includes('workflows') ? [WORKFLOW_MCP_INSTRUCTIONS] : []),
     ...(scope.domains.includes('agent_management') ? [AGENT_MANAGEMENT_MCP_INSTRUCTIONS] : []),
+    ...(scope.domains.includes('mcp_servers') ? [MCP_SERVERS_INSTRUCTIONS] : []),
     ...(scope.domains.includes('root_management') && dependencies.rootControlTools
       ? [rootManagementInstructions(scope.sessionId)]
       : []),
@@ -881,7 +887,20 @@ function orchestrationCreateAgentCallKey(
         ].join(' '),
       inputSchema: ORCHESTRATION_CREATE_AGENT_INPUT,
     },
-    async args => {
+    async requested => {
+      // Review round 2 (#1143): a child may not be handed a privileged domain
+      // its parent does not hold itself. Orchestration is on by default, so
+      // without this any ordinary agent — or a prompt injection reaching one —
+      // could spawn a child with mcp_servers (and install a server every
+      // future agent runs) or root_management (skipping its confirmation
+      // dialog). Clamped here, at the one place a model-chosen list enters.
+      const args = {
+        ...requested,
+        ...(requested.builtInMcpDomains
+          ? { builtInMcpDomains: requested.builtInMcpDomains.filter(domain =>
+              !PARENT_HELD_ONLY_BUILT_IN_MCP_DOMAINS.has(domain) || scope.domains.includes(domain)) }
+          : {}),
+      }
       const bridge = dependencies.orchestrationBridge
       const manager = dependencies.sessionManager
       if (!bridge || !manager) {
diff --git a/src/mcp/runtime/userMcpTools.test.ts b/src/mcp/runtime/userMcpTools.test.ts
new file mode 100644
index 000000000..e10d56d52
--- /dev/null
+++ b/src/mcp/runtime/userMcpTools.test.ts
@@ -0,0 +1,146 @@
+import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { UserMcpService } from '@main/userMcp/service.js'
+import { createBuiltInMcpServer } from '@mcp/runtime/createBuiltInMcpServer.js'
+import type { BuiltInMcpDomain } from '@mcp/shared/types.js'
+
+// The mcp_servers domain drives the REAL UserMcpService over a temp state
+// dir: the property under test is that an agent changes exactly what Settings
+// would, through the same validation, and can never read a secret back.
+
+const TOKEN = 'bpr_live_9f3a1c7d'
+const codec = {
+  isEncryptionAvailable: () => true,
+  encrypt: (plain: string) => Buffer.from(`enc:${plain}`),
+  decrypt: (cipher: Buffer) => cipher.toString().slice(4),
+}
+
+let dir: string
+let service: UserMcpService
+beforeEach(async () => {
+  dir = await mkdtemp(join(tmpdir(), 'mcp-tools-'))
+  service = new UserMcpService({
+    stateDir: dir,
+    codec,
+    native: { list: async () => [], codexNames: async () => new Set(), claudeManagedPolicy: async () => false },
+  })
+})
+afterEach(async () => { await rm(dir, { recursive: true, force: true }) })
+
+async function connect(domains: BuiltInMcpDomain[], onUserMcpChangedByAgent = vi.fn()) {
+  const server = createBuiltInMcpServer(
+    { sessionId: 'agent-1', cwd: '/tmp/project', domains },
+    { userMcpService: service, onUserMcpChangedByAgent },
+  )
+  const client = new Client({ name: 'mcp-servers-domain-test', version: '0.0.0' })
+  const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair()
+  await server.connect(serverTransport)
+  await client.connect(clientTransport)
+  const call = async (name: string, args: Record<string, unknown> = {}) => {
+    const result = await client.callTool({ name, arguments: args })
+    const text = (result.content as { text: string }[])[0]!.text
+    // Schema rejections (e.g. `enabled: true`, which the schema forbids) come
+    // back as plain MCP error text, not our JSON envelope.
+    let value: Record<string, unknown>
+    try { value = JSON.parse(text) as Record<string, unknown> } catch { value = { message: text } }
+    return { isError: result.isError === true, text, value }
+  }
+  return { client, call, close: async () => { await client.close(); await server.close() } }
+}
+
+describe('mcp_servers built-in domain', () => {
+  it('is only exposed when the domain is granted', async () => {
+    const without = await connect(['tldr'])
+    expect((await without.client.listTools()).tools.map(tool => tool.name)).not.toContain('mcp_servers_add')
+    await without.close()
+    const withDomain = await connect(['mcp_servers'])
+    expect((await withDomain.client.listTools()).tools.map(tool => tool.name).sort()).toEqual([
+      'mcp_servers_add', 'mcp_servers_list', 'mcp_servers_remove', 'mcp_servers_set_secret', 'mcp_servers_update',
+    ])
+    expect(withDomain.client.getInstructions()).toContain('never add a server on your own initiative')
+    await withDomain.close()
+  })
+
+  it('adds Beeper from its official snippet, keeps the token out of every reply and the document, and tells the user', async () => {
+    const announce = vi.fn()
+    const { call, close } = await connect(['mcp_servers'], announce)
+    const added = await call('mcp_servers_add', {
+      config: JSON.stringify({ mcpServers: { beeper: { url: 'http://localhost:23373/v0/mcp', headers: { Authorization: `Bearer ${TOKEN}` } } } }),
+    })
+    expect(added.isError).toBe(false)
+    expect(added.text).not.toContain(TOKEN)
+    expect(await readFile(join(dir, 'mcp-servers.json'), 'utf8')).not.toContain(TOKEN)
+    const listed = await call('mcp_servers_list')
+    expect(listed.text).not.toContain(TOKEN)
+    // Not even the Settings last-4 hint. Asserted structurally: a substring
+    // check for the hint would also match a random server UUID that happens
+    // to contain those four hex characters.
+    expect(listed.text).not.toContain('"hint"')
+    expect((listed.value.servers as { secrets: Record<string, string> }[])[0]!.secrets).toEqual({ 'beeper-authorization': 'set' })
+    expect(announce).toHaveBeenCalledWith({ sessionId: 'agent-1', message: 'An agent added MCP server beeper (off until you review it)' })
+    // Review round 2: an agent proposes, the user approves. Nothing attaches
+    // until the user turns it on; then the stored secret is there.
+    const id = (await service.snapshot()).servers[0]!.id
+    expect((await service.snapshot()).servers[0]!.enabled).toBe(false)
+    expect((await service.resolveForLaunch({ provider: 'codex', overrides: {}, cwd: dir })).servers).toEqual([])
+    await service.setEnabled(id, true)
+    const launch = await service.resolveForLaunch({ provider: 'codex', overrides: {}, cwd: dir })
+    expect(launch.servers[0]!.secrets).toEqual({ 'beeper-authorization': TOKEN })
+    // And the agent was never shown the raw entry.
+    expect(listed.text).not.toContain('"entry"')
+    await close()
+  })
+
+  it('refuses what Settings would refuse, and changes nothing', async () => {
+    const announce = vi.fn()
+    const { call, close } = await connect(['mcp_servers'], announce)
+    const result = await call('mcp_servers_add', { config: '{"url":"http://x/mcp"}', name: 'agent_code' })
+    expect(result.isError).toBe(true)
+    expect(result.value.message).toMatch(/reserved/)
+    expect(announce).not.toHaveBeenCalled()
+    expect((await service.snapshot()).servers).toEqual([])
+    await close()
+  })
+
+  it('updates, sets a secret for, and removes a server by id', async () => {
+    const { call, close } = await connect(['mcp_servers'])
+    await call('mcp_servers_add', { config: '{"command":"npx","args":["-y","@beeper/mcp-remote"],"env":{"ACCESS_TOKEN":"YOUR_TOKEN_HERE"}}', name: 'beeper' })
+    const id = (await service.snapshot()).servers[0]!.id
+    expect((await service.snapshot()).servers[0]!.secrets['beeper-access_token']).toEqual({ set: false })
+
+    const secret = await call('mcp_servers_set_secret', { id, inputId: 'beeper-access_token', value: TOKEN })
+    expect(secret.text).not.toContain(TOKEN)
+    expect((await service.snapshot()).servers[0]!.secrets['beeper-access_token']!.set).toBe(true)
+
+    await call('mcp_servers_update', { id, codex: false })
+    expect((await service.snapshot()).servers[0]!.providers).toEqual({ claude: true, codex: false })
+
+    await call('mcp_servers_remove', { id })
+    expect((await service.snapshot()).servers).toEqual([])
+    await close()
+  })
+
+  it('cannot turn a server on (review round 2)', async () => {
+    const { call, close } = await connect(['mcp_servers'])
+    await call('mcp_servers_add', { config: '{"url":"https://x.dev/mcp"}', name: 'x' })
+    const id = (await service.snapshot()).servers[0]!.id
+    const result = await call('mcp_servers_update', { id, enabled: true })
+    expect(result.isError).toBe(true)
+    expect((await service.snapshot()).servers[0]!.enabled).toBe(false)
+    await close()
+  })
+
+  it('refuses more than 20 servers in one call', async () => {
+    const { call, close } = await connect(['mcp_servers'])
+    const many = Object.fromEntries(Array.from({ length: 21 }, (_, i) => [`s${i}`, { command: 'x' }]))
+    expect((await call('mcp_servers_add', { config: JSON.stringify({ mcpServers: many }) })).isError).toBe(true)
+    expect((await service.snapshot()).servers).toEqual([])
+    await close()
+  })
+})
diff --git a/src/mcp/runtime/userMcpTools.ts b/src/mcp/runtime/userMcpTools.ts
new file mode 100644
index 000000000..9132df6c9
--- /dev/null
+++ b/src/mcp/runtime/userMcpTools.ts
@@ -0,0 +1,237 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+
+import type { UserMcpService } from '@main/userMcp/service.js'
+import type { McpSessionScope } from '@mcp/shared/types.js'
+import type { UserMcpMutationResult, UserMcpServerView, UserMcpSnapshot } from '@shared/userMcp/types.js'
+import { providerSupportForEntry } from '@shared/userMcp/validate.js'
+
+/**
+ * The `mcp_servers` built-in domain (#1143): lets an agent manage Agent
+ * Code's OWN MCP server configuration — "install the Beeper MCP server for me".
+ *
+ * WHY tools over the service instead of a skill that points the agent at
+ * mcp-servers.json: main loads that document once and serializes every write
+ * through one queue, so a file edited behind its back is either overwritten by
+ * the next Settings change or ignored until restart. Secrets are not in the
+ * file at all (they are safeStorage blobs an agent cannot produce). Going
+ * through UserMcpService gives the agent the exact validation, secret handling
+ * and broadcast that the Settings UI gets, and nothing else.
+ *
+ * WHY there is no tool that reads a secret back: an agent that can set a token
+ * because the user just handed it one has no reason to ever read one, and a
+ * read tool would turn any prompt injection into credential exfiltration.
+ */
+/** At most this many servers per mcp_servers_add call. The 64 KB config cap
+ * alone admits thousands of tiny entries, each a queued save, snapshot and
+ * broadcast in main (review round 2). */
+const MAX_SERVERS_PER_ADD = 20
+
+export type UserMcpToolDependencies = {
+  userMcpService?: Pick<UserMcpService, 'snapshot' | 'importConfig' | 'save' | 'delete' | 'setEnabled' | 'setProvider' | 'setSecret'>
+  /** Tells every window that an agent changed the MCP configuration. */
+  onUserMcpChangedByAgent?: (event: { sessionId: string; message: string }) => void
+}
+
+export const MCP_SERVERS_INSTRUCTIONS = `MCP Servers lets you manage the user's own MCP servers in Agent Code (the servers Agent Code attaches to new Claude and Codex agents). Only add, change or remove servers when the user's current request asks for it; never add a server on your own initiative, and prefer the exact config the server's official documentation publishes. Add servers with mcp_servers_add using that config (a {"mcpServers": {...}} block, a VS Code {"servers": ...} block, or one entry). Every env and header value in it becomes an encrypted secret automatically; README placeholders such as YOUR_TOKEN_HERE stay unset. A server you add, or point at a different URL, command, arguments or environment, is saved switched OFF and waits for the user's review: tell the user to review it and turn it on in Settings → MCP. You cannot turn a server on. Set a secret with mcp_servers_set_secret only when the user has given you the value in this conversation; otherwise tell the user to set it in Settings → MCP. Never repeat a secret value back. Changes apply to new agents and to existing agents when they reload — including you: you will not get a server's tools until the user reloads you. OAuth servers sign in through the CLIs (codex mcp login, or /mcp in Claude); say so instead of looking for a token. Report exactly what you changed.`
+
+export function registerUserMcpTools(
+  server: McpServer,
+  scope: McpSessionScope,
+  dependencies: UserMcpToolDependencies,
+): void {
+  const service = () => {
+    if (!dependencies.userMcpService) throw new Error('MCP server management is unavailable.')
+    return dependencies.userMcpService
+  }
+  const failure = (error: unknown) => ({
+    ...toolText({ ok: false, message: error instanceof Error ? error.message : 'MCP server change failed.' }),
+    isError: true,
+  })
+  const changed = (message: string) => dependencies.onUserMcpChangedByAgent?.({ sessionId: scope.sessionId, message })
+  const mutation = (result: UserMcpMutationResult) => result.ok
+    ? toolText({ ok: true, servers: result.snapshot.servers.map(describeServer) })
+    : { ...toolText({ ok: false, message: result.error, problems: result.problems ?? [] }), isError: true }
+  const nameOf = async (id: string) => (await service().snapshot()).servers.find(candidate => candidate.id === id)?.name ?? id
+
+  server.registerTool('mcp_servers_list', {
+    title: 'List MCP servers',
+    description: 'List the user\'s MCP servers managed by Agent Code (ids, transport, which providers new agents get them on, whether secrets are set, problems) and the servers each CLI loads from its own config (read-only). Secret values are never returned.',
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  }, async () => {
+    try {
+      return toolText({ ok: true, ...describeSnapshot(await service().snapshot()) })
+    } catch (error) {
+      return failure(error)
+    }
+  })
+
+  server.registerTool('mcp_servers_add', {
+    title: 'Add MCP servers',
+    description: 'Add one or more MCP servers (at most 20) from a config snippet as published by the server\'s documentation: {"mcpServers": {...}}, a VS Code {"servers": ...} block, or a single entry (then pass name). Env and header values are stored as encrypted secrets automatically. New servers are saved switched off until the user reviews and turns them on in Settings → MCP. Returns the new server ids and any secrets still to set.',
+    inputSchema: {
+      config: z.string().min(2).max(64 * 1024).describe('The JSON config snippet.'),
+      name: z.string().min(1).max(64).optional().describe('Server name, used only when config is a single bare entry.'),
+      claude: z.boolean().optional().describe('Attach to new Claude agents. Defaults to true when supported.'),
+      codex: z.boolean().optional().describe('Attach to new Codex agents. Defaults to true when supported (not for SSE).'),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+  }, async ({ config, name, claude, codex }) => {
+    try {
+      const imported = service().importConfig(config, name)
+      if (!imported.ok) return { ...toolText({ ok: false, message: imported.error }), isError: true }
+      if (imported.candidates.length > MAX_SERVERS_PER_ADD) {
+        return { ...toolText({ ok: false, message: `Add at most ${MAX_SERVERS_PER_ADD} servers per call.` }), isError: true }
+      }
+      const added: unknown[] = []
+      const addedNames: string[] = []
+      for (const candidate of imported.candidates) {
+        const support = providerSupportForEntry(candidate.entry)
+        const result = await service().save({
+          name: candidate.name,
+          // Stored off regardless (actor 'agent'); see UserMcpServer.pendingReview.
+          enabled: false,
+          providers: {
+            claude: support.claude.ok && (claude ?? true),
+            codex: support.codex.ok && (codex ?? true),
+          },
+          entry: candidate.entry,
+          inputs: candidate.inputs,
+          secrets: candidate.pendingSecrets,
+        }, 'agent')
+        if (!result.ok) {
+          if (addedNames.length > 0) changed(`An agent added MCP server${addedNames.length > 1 ? 's' : ''} ${addedNames.join(', ')} (off until you review ${addedNames.length > 1 ? 'them' : 'it'})`)
+          return { ...toolText({ ok: false, message: `${candidate.name}: ${result.error}`, added, problems: result.problems ?? [] }), isError: true }
+        }
+        const view = result.snapshot.servers.find(serverView => serverView.id === result.id)
+        added.push(view ? describeServer(view) : { name: candidate.name })
+        addedNames.push(candidate.name)
+      }
+      // One notice per call, not per server: the toast slot is single, so a
+      // per-server notice left only the last of a burst visible (review round 2).
+      changed(`An agent added MCP server${addedNames.length > 1 ? 's' : ''} ${addedNames.join(', ')} (off until you review ${addedNames.length > 1 ? 'them' : 'it'})`)
+      return toolText({
+        ok: true,
+        added,
+        note: 'Saved switched off. Ask the user to review and turn it on in Settings → MCP; it then applies to new agents and to existing agents after they reload.',
+      })
+    } catch (error) {
+      return failure(error)
+    }
+  })
+
+  server.registerTool('mcp_servers_update', {
+    title: 'Update an MCP server',
+    description: 'Change one server: its name, its config entry (the full entry object, same shape as mcp_servers_add accepts; keep ${input:…} references for secrets), which providers new agents get it on, or turn it OFF. Changing the entry\'s URL, command, arguments or environment forgets its stored secrets and switches it off until the user reviews it. You cannot turn a server on.',
+    inputSchema: {
+      id: z.string().min(1).max(64),
+      name: z.string().min(1).max(64).optional(),
+      entry: z.record(z.string(), z.unknown()).optional(),
+      enabled: z.literal(false).optional().describe('Pass false to switch the server off. Only the user can switch it on.'),
+      claude: z.boolean().optional(),
+      codex: z.boolean().optional(),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  }, async ({ id, name, entry, enabled, claude, codex }) => {
+    try {
+      const current = (await service().snapshot()).servers.find(candidate => candidate.id === id)
+      if (!current) return { ...toolText({ ok: false, message: `No MCP server with id ${id}.` }), isError: true }
+      const nextEntry = (entry ?? current.entry) as typeof current.entry
+      // Secret definitions follow the entry, exactly as in the Settings
+      // editor: references keep their existing definition, new ones get one.
+      const referenced = [...new Set([...JSON.stringify(nextEntry).matchAll(/\$\{input:([A-Za-z0-9_-]{1,64})\}/g)].map(match => match[1]!))]
+      const result = await service().save({
+        id,
+        name: name ?? current.name,
+        enabled: enabled ?? current.enabled,
+        providers: { claude: claude ?? current.providers.claude, codex: codex ?? current.providers.codex },
+        entry: nextEntry,
+        inputs: referenced.map(inputId => current.inputs.find(input => input.id === inputId) ?? { id: inputId, description: 'Secret' }),
+      }, 'agent')
+      if (result.ok) {
+        changed(result.pendingReview
+          ? `An agent changed MCP server ${name ?? current.name} (off until you review it)`
+          : `An agent changed MCP server ${name ?? current.name}`)
+      }
+      return mutation(result)
+    } catch (error) {
+      return failure(error)
+    }
+  })
+
+  server.registerTool('mcp_servers_remove', {
+    title: 'Remove an MCP server',
+    description: 'Delete one of the user\'s MCP servers and its stored secrets. Only when the user\'s current request asks to remove that server.',
+    inputSchema: { id: z.string().min(1).max(64) },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+  }, async ({ id }) => {
+    try {
+      const name = await nameOf(id)
+      const result = await service().delete(id)
+      if (result.ok) changed(`An agent removed MCP server ${name}`)
+      return mutation(result)
+    } catch (error) {
+      return failure(error)
+    }
+  })
+
+  server.registerTool('mcp_servers_set_secret', {
+    title: 'Set an MCP server secret',
+    description: 'Store one secret (a ${input:id} the server config references) encrypted. Only use a value the user gave you in this conversation; never invent one. The value is never returned by any tool.',
+    inputSchema: {
+      id: z.string().min(1).max(64),
+      inputId: z.string().min(1).max(64),
+      value: z.string().min(1).max(64 * 1024),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  }, async ({ id, inputId, value }) => {
+    try {
+      const name = await nameOf(id)
+      const result = await service().setSecret(id, inputId, value)
+      if (result.ok) changed(`An agent set a secret for MCP server ${name}`)
+      return mutation(result)
+    } catch (error) {
+      return failure(error)
+    }
+  })
+}
+
+/** What an agent sees of a server: everything except secret values, which
+ * the view type does not carry in the first place. */
+function describeServer(server: UserMcpServerView) {
+  return {
+    id: server.id,
+    name: server.name,
+    enabled: server.enabled,
+    ...(server.pendingReview ? { waitingForUserReview: true } : {}),
+    providers: server.providers,
+    transport: server.transport,
+    // The redacted one-line summary, never the raw entry (review round 2):
+    // args and URLs have no secret channel and often carry credentials, and
+    // everything this returns lands in the transcript and at the provider.
+    // An update passes the complete entry it wants anyway.
+    summary: server.summary,
+    secretReferences: server.inputs.map(input => input.id),
+    secrets: Object.fromEntries(Object.entries(server.secrets).map(([id, state]) => [id, state.set ? 'set' : 'not set'])),
+    problems: server.problems.map(problem => problem.message),
+    unsupported: Object.fromEntries(Object.entries(server.support).flatMap(([provider, support]) =>
+      support.ok ? [] : [[provider, support.reason]])),
+  }
+}
+
+function describeSnapshot(snapshot: UserMcpSnapshot) {
+  return {
+    servers: snapshot.servers.map(describeServer),
+    loadedByCliDirectly: snapshot.native.map(native => ({
+      provider: native.provider,
+      name: native.name,
+      source: native.source,
+      summary: native.summary,
+    })),
+    ...(snapshot.claudeManagedPolicy ? { note: 'An enterprise Claude MCP policy is active: user servers are not attached to Claude agents.' } : {}),
+  }
+}
+
+function toolText(value: unknown) {
+  return { content: [{ type: 'text' as const, text: JSON.stringify(value) }] }
+}
diff --git a/src/mcp/shared/types.test.ts b/src/mcp/shared/types.test.ts
index fc3ca44cc..4026e91e2 100644
--- a/src/mcp/shared/types.test.ts
+++ b/src/mcp/shared/types.test.ts
@@ -1,9 +1,12 @@
 import { describe, expect, it } from 'vitest'
 
 import {
+  builtInMcpDefaultsFor,
+  coerceBuiltInMcpDefaults,
   filterBuiltInMcpDomainsForProvider,
   normalizeConfigurableBuiltInMcpDomains,
   providerSupportsBuiltInMcpDomain,
+  uniformBuiltInMcpDefaults,
 } from '@mcp/shared/types.js'
 
 describe('built-in MCP provider policy', () => {
@@ -58,3 +61,27 @@ describe('root management domain policy (#906)', () => {
     expect(filterBuiltInMcpDomainsForProvider('opencode', ['root_management'])).toEqual(['root_management'])
   })
 })
+
+describe('per-provider built-in MCP defaults (#1143)', () => {
+  it('copies a pre-#1143 flat list to every provider so upgrading changes nobody\'s agents', () => {
+    const defaults = coerceBuiltInMcpDefaults(['tldr', 'ping', 'orchestration'], ['goal'])
+    // ping is diagnostic-only and never a default, as before.
+    expect(defaults.claude).toEqual(['tldr', 'orchestration'])
+    expect(defaults.codex).toEqual(['tldr', 'orchestration'])
+    expect(defaults.grok).toEqual(['tldr', 'orchestration'])
+  })
+
+  it('keeps an explicit empty column but gives a missing provider the shipped default', () => {
+    const defaults = coerceBuiltInMcpDefaults({ claude: [], codex: ['workflows'] }, ['tldr'])
+    expect(defaults.claude).toEqual([])
+    expect(defaults.codex).toEqual(['workflows'])
+    expect(defaults.opencode).toEqual(['tldr'])
+  })
+
+  it('reads either form for one provider', () => {
+    expect(builtInMcpDefaultsFor(['goal'], 'codex')).toEqual(['goal'])
+    expect(builtInMcpDefaultsFor({ ...uniformBuiltInMcpDefaults([]), codex: ['goal'] }, 'codex')).toEqual(['goal'])
+    expect(builtInMcpDefaultsFor({ ...uniformBuiltInMcpDefaults([]), codex: ['goal'] }, 'claude')).toEqual([])
+    expect(builtInMcpDefaultsFor(undefined, 'claude')).toEqual([])
+  })
+})
diff --git a/src/mcp/shared/types.ts b/src/mcp/shared/types.ts
index 4a6b21bd4..2bf449f90 100644
--- a/src/mcp/shared/types.ts
+++ b/src/mcp/shared/types.ts
@@ -1,4 +1,5 @@
-import type { AgentProviderKind } from '@shared/types/providerKind.js'
+import { AGENT_PROVIDER_KINDS, type AgentProviderKind } from '@shared/types/providerKind.js'
+import type { UserMcpOverrideKey } from '@shared/userMcp/types.js'
 
 // `goal_loop` is harness-driven (main observes turn boundaries and re-prompts
 // through its own send interface), so unlike `workflows` it duplicates no
@@ -14,6 +15,8 @@ export type BuiltInMcpDomain =
   | 'agent_management'
   | 'root_management'
   | 'workflows'
+  // #1143: manage the user's own MCP servers (add/update/remove/set secret).
+  | 'mcp_servers'
 
 export const BUILT_IN_MCP_DOMAINS = [
   'tldr',
@@ -26,6 +29,7 @@ export const BUILT_IN_MCP_DOMAINS = [
   'agent_management',
   'root_management',
   'workflows',
+  'mcp_servers',
 ] as const satisfies readonly BuiltInMcpDomain[]
 
 /**
@@ -55,14 +59,82 @@ export const CONFIGURABLE_BUILT_IN_MCP_DOMAINS = [
   'agent_transcripts',
   'agent_management',
   'workflows',
+  // Configurable (unlike root_management) because its blast radius is the
+  // user's own MCP list, the same thing Settings → MCP edits, and every change
+  // is announced to the user. Off by default all the same: it is not in the
+  // shipped default set.
+  'mcp_servers',
 ] as const satisfies readonly BuiltInMcpDomain[]
 
 export type ConfigurableBuiltInMcpDomain =
   (typeof CONFIGURABLE_BUILT_IN_MCP_DOMAINS)[number]
 
+/**
+ * Which built-in capabilities NEW agents of each provider start with
+ * (Settings → MCP, one column per provider; #1143 Revision 2).
+ *
+ * WHY per provider rather than one list: the MCP settings grid shows built-in
+ * and user servers side by side under the same provider columns, and a user
+ * who wants Orchestration on their Claude agents but not on Codex had no way
+ * to say so. The old flat list is still accepted everywhere a default is
+ * read (BuiltInMcpDefaultsInput) and means "the same for every provider":
+ * that keeps orchestration/control callers and persisted pre-#1143 settings
+ * valid without a parallel API or a destructive migration.
+ */
+export type BuiltInMcpDefaults = Record<AgentProviderKind, ConfigurableBuiltInMcpDomain[]>
+export type BuiltInMcpDefaultsInput = BuiltInMcpDefaults | readonly ConfigurableBuiltInMcpDomain[]
+
+export function uniformBuiltInMcpDefaults(
+  domains: readonly ConfigurableBuiltInMcpDomain[],
+): BuiltInMcpDefaults {
+  return Object.fromEntries(
+    AGENT_PROVIDER_KINDS.map(provider => [provider, [...domains]]),
+  ) as BuiltInMcpDefaults
+}
+
+/**
+ * Coerce persisted defaults. A legacy flat list becomes the same list for
+ * every provider, so nobody's behavior changes on upgrade. In the per-provider
+ * form an ABSENT provider falls back to `fallback` (a provider added later
+ * gets the shipped default), while a PRESENT empty list is kept: "nothing by
+ * default" is a real choice, the same rule the flat list always had.
+ */
+export function coerceBuiltInMcpDefaults(
+  value: unknown,
+  fallback: readonly ConfigurableBuiltInMcpDomain[],
+): BuiltInMcpDefaults {
+  if (Array.isArray(value)) return uniformBuiltInMcpDefaults(normalizeConfigurableBuiltInMcpDomains(value))
+  if (!value || typeof value !== 'object') return uniformBuiltInMcpDefaults(fallback)
+  const record = value as Record<string, unknown>
+  return Object.fromEntries(AGENT_PROVIDER_KINDS.map(provider => [
+    provider,
+    Object.prototype.hasOwnProperty.call(record, provider)
+      ? normalizeConfigurableBuiltInMcpDomains(record[provider])
+      : [...fallback],
+  ])) as BuiltInMcpDefaults
+}
+
+/** The defaults that apply to `provider`, from either accepted form. */
+export function builtInMcpDefaultsFor(
+  defaults: unknown,
+  provider: AgentProviderKind,
+): ConfigurableBuiltInMcpDomain[] {
+  if (Array.isArray(defaults)) return normalizeConfigurableBuiltInMcpDomains(defaults)
+  if (!defaults || typeof defaults !== 'object') return []
+  return normalizeConfigurableBuiltInMcpDomains((defaults as Record<string, unknown>)[provider])
+}
+
 /** Absence inherits Settings. A false value is an intentional per-agent off,
- * not an old effective snapshot captured before a global setting changed. */
-export type BuiltInMcpOverrides = Partial<Record<BuiltInMcpDomain, boolean>>
+ * not an old effective snapshot captured before a global setting changed.
+ *
+ * Despite the name, the map also carries per-agent choices for USER MCP
+ * servers under `user:<serverId>` keys (#1143, spec Revision 2 §3). The field
+ * is persisted on every pane and already threaded through spawn, reload,
+ * recovery, undo, provider switch, duplicate and the control API; renaming it
+ * would need a workspace migration, and a second parallel map would have to be
+ * threaded through all of those paths, where missing one silently drops a
+ * choice. Built-in domain names never contain ':', so the keys cannot clash. */
+export type BuiltInMcpOverrides = Partial<Record<BuiltInMcpDomain | UserMcpOverrideKey, boolean>>
 
 /**
  * Capabilities a NEW agent may never inherit from an existing one, however that
@@ -84,6 +156,18 @@ export const CONFIRMATION_GATED_BUILT_IN_MCP_DOMAINS = [
   'root_management',
 ] as const satisfies readonly BuiltInMcpDomain[]
 
+/**
+ * Domains an orchestration parent can pass to a child only if it holds them
+ * itself (#1143 review round 2). Both reach beyond the agent's own work:
+ * root_management controls the whole app and mcp_servers decides what every
+ * future agent runs. A parent that merely has Orchestration must not be able
+ * to mint either for a child it controls.
+ */
+export const PARENT_HELD_ONLY_BUILT_IN_MCP_DOMAINS: ReadonlySet<BuiltInMcpDomain> = new Set<BuiltInMcpDomain>([
+  'root_management',
+  'mcp_servers',
+])
+
 /**
  * The provider launchers, not the generic "agent provider" type, determine
  * whether an MCP configuration reaches the model. Keep that decision
@@ -114,6 +198,7 @@ const BUILT_IN_MCP_DOMAINS_BY_PROVIDER = {
     'agent_transcripts',
     'agent_management',
     'root_management',
+    'mcp_servers',
   ],
   codex: [...BUILT_IN_MCP_DOMAINS],
   opencode: [...BUILT_IN_MCP_DOMAINS],
diff --git a/src/preload/api/index.ts b/src/preload/api/index.ts
index e573bbcfe..68907d60b 100644
--- a/src/preload/api/index.ts
+++ b/src/preload/api/index.ts
@@ -31,6 +31,7 @@ import { incidentApi } from '@preload/api/incident.js'
 import { lifecycleApi } from '@preload/api/lifecycle.js'
 import { remoteApi } from '@preload/api/remote.js'
 import { providerEnablementApi } from '@preload/api/providerEnablement.js'
+import { userMcpApi } from '@preload/api/userMcp.js'
 import { usageApi } from '@preload/api/usage.js'
 import { cliUpdatesApi } from '@preload/api/cliUpdates.js'
 import { workflowsApi } from '@preload/api/workflows.js'
@@ -98,6 +99,7 @@ export const api = {
   ...lifecycleApi,
   ...remoteApi,
   ...providerEnablementApi,
+  ...userMcpApi,
   ...usageApi,
   ...cliUpdatesApi,
   ...workflowsApi,
diff --git a/src/preload/api/types.ts b/src/preload/api/types.ts
index 671da4702..67d347a65 100644
--- a/src/preload/api/types.ts
+++ b/src/preload/api/types.ts
@@ -224,6 +224,13 @@ export type SessionSpawnOptions = {
   tldrIdentity?: string
   /** Agent sessions only: built-in Agent Code MCP domains exposed to the child. */
   builtInMcpDomains?: BuiltInMcpDomain[]
+  /**
+   * Agent sessions only: the pane's explicit per-agent user MCP choices (bare
+   * server id → on/off, #1143). Deliberately NOT a resolved server list: main
+   * owns the server document and secrets and applies the defaults itself, so a
+   * stale renderer snapshot can never attach a deleted or disabled server.
+   */
+  userMcpOverrides?: Record<string, boolean>
 }
 
 export type SessionSpawnResult = {
@@ -238,6 +245,8 @@ export type SessionSpawnResult = {
    * durable workspace persistence, not this response, commits the transaction.
    */
   replacementTransactionId?: string
+  /** Agent sessions only: user MCP servers main actually attached (#1143). */
+  userMcpServerIds?: string[]
 }
 
 export type { ConditionCustomAction }
diff --git a/src/preload/api/userMcp.ts b/src/preload/api/userMcp.ts
new file mode 100644
index 000000000..85d8f648b
--- /dev/null
+++ b/src/preload/api/userMcp.ts
@@ -0,0 +1,39 @@
+import { ipcRenderer } from 'electron'
+
+import { subscribe } from '@preload/api/ipc.js'
+import type { Unsub } from '@preload/api/types.js'
+import type {
+  UserMcpImportResult,
+  UserMcpMutationResult,
+  UserMcpProvider,
+  UserMcpSaveInput,
+  UserMcpSnapshot,
+  UserMcpUnavailableEvent,
+} from '@shared/userMcp/types.js'
+
+// Preload bridge for user MCP servers (#1143). Its own module for the same
+// reason as providerEnablement: a main-owned document plus a state broadcast
+// is a distinct surface, and the channel prefix mirrors it. Secret VALUES only
+// ever travel renderer → main (set); nothing here can read one back.
+export const userMcpApi = {
+  userMcpGet: (): Promise<UserMcpSnapshot> => ipcRenderer.invoke('user-mcp:get'),
+  userMcpSave: (input: UserMcpSaveInput): Promise<UserMcpMutationResult> =>
+    ipcRenderer.invoke('user-mcp:save', input),
+  userMcpDelete: (id: string): Promise<UserMcpMutationResult> => ipcRenderer.invoke('user-mcp:delete', id),
+  userMcpSetEnabled: (id: string, enabled: boolean): Promise<UserMcpMutationResult> =>
+    ipcRenderer.invoke('user-mcp:set-enabled', id, enabled),
+  userMcpSetProvider: (id: string, provider: UserMcpProvider, enabled: boolean): Promise<UserMcpMutationResult> =>
+    ipcRenderer.invoke('user-mcp:set-provider', id, provider, enabled),
+  userMcpSetSecret: (id: string, inputId: string, value: string): Promise<UserMcpMutationResult> =>
+    ipcRenderer.invoke('user-mcp:set-secret', id, inputId, value),
+  userMcpImport: (text: string, fallbackName?: string): Promise<UserMcpImportResult> =>
+    ipcRenderer.invoke('user-mcp:import', text, fallbackName),
+  userMcpCopyNative: (provider: UserMcpProvider, name: string): Promise<UserMcpMutationResult> =>
+    ipcRenderer.invoke('user-mcp:copy-native', provider, name),
+  onUserMcpChanged: (cb: (snapshot: UserMcpSnapshot) => void): Unsub => subscribe('user-mcp:changed', cb),
+  onUserMcpUnavailable: (cb: (event: UserMcpUnavailableEvent) => void): Unsub =>
+    subscribe('user-mcp:unavailable', cb),
+  /** An agent with the MCP Servers capability changed the configuration. */
+  onUserMcpAgentChange: (cb: (event: { message: string }) => void): Unsub =>
+    subscribe('user-mcp:agent-change', cb),
+}
diff --git a/src/providers/claude/runtime/claudeSession.ts b/src/providers/claude/runtime/claudeSession.ts
index 1a6f93068..0dfbdd54d 100644
--- a/src/providers/claude/runtime/claudeSession.ts
+++ b/src/providers/claude/runtime/claudeSession.ts
@@ -1,3 +1,4 @@
+import { rm } from 'node:fs/promises'
 import { excludeExternalControlFromClaude } from '@providers/shared/runtime/externalControlExclusion.js'
 import { CLAUDE_TLDR_HOOK_TOKEN_ENV, claudeTldrHookSettings, tldrHookServer } from '@providers/shared/runtime/tldrHooks.js'
 import { EventEmitter } from 'events'
@@ -17,6 +18,8 @@ import {
   createPrivateClaudeMcpConfig,
   type PrivateMcpConfig,
 } from '@providers/shared/runtime/builtInMcpLaunch.js'
+import { claudeUserMcpEntries } from '@providers/shared/runtime/userMcpLaunch.js'
+import type { ResolvedUserMcpServer } from '@shared/userMcp/types.js'
 import type {
   AgentInputReadiness,
   PromptAcceptanceOutcome,
@@ -62,6 +65,8 @@ export type ClaudeSessionOptions = {
    *  mitmproxy while letting opted-in users get the richer stream. */
   useProxy?: boolean
   builtInMcpServers?: BuiltInMcpServerConfig[]
+  /** Already filtered and secret-resolved by main (#1143). */
+  userMcpServers?: ResolvedUserMcpServer[]
 }
 
 export type ScreenSnapshot = {
@@ -212,7 +217,9 @@ export class ClaudeSession extends EventEmitter {
   private readonly useProxy: boolean
   private readonly shellSessionId: string | null
   private readonly builtInMcpServers: BuiltInMcpServerConfig[]
+  private readonly userMcpServers: ResolvedUserMcpServer[]
   private privateMcpConfig: PrivateMcpConfig | null = null
+  private privateMcpConfigForgotten = false
 
   constructor(options: ClaudeSessionOptions = {}) {
     super()
@@ -231,6 +238,7 @@ export class ClaudeSession extends EventEmitter {
     this.useProxy = options.useProxy === true
     this.shellSessionId = options.shellSessionId ?? null
     this.builtInMcpServers = options.builtInMcpServers ?? []
+    this.userMcpServers = options.userMcpServers ?? []
 
     const env: Record<string, string | undefined> = {}
     for (const [k, v] of Object.entries(process.env)) {
@@ -865,9 +873,27 @@ export class ClaudeSession extends EventEmitter {
         reason: nextReason,
       })
     }
+    if (next.kind === 'ready') this.forgetPrivateMcpConfigContents()
     return next
   }
 
+  /**
+   * Remove the private MCP config file once Claude is up (#1143 review round
+   * 2). It now carries resolved user secrets, and its path is on Claude's argv,
+   * so for as long as it exists any tool the model runs as the same user can
+   * `ps` for the path and read it. Claude parses `--mcp-config` once during
+   * startup (vendor main.tsx) and reconnects from the in-memory config, and a
+   * ready composer means startup is long past, so the file is not needed
+   * again. Only the FILE goes; the directory and dispose() stay, so stop,
+   * rollback and the startup sweep keep working unchanged.
+   */
+  private forgetPrivateMcpConfigContents(): void {
+    const config = this.privateMcpConfig
+    if (!config || this.privateMcpConfigForgotten) return
+    this.privateMcpConfigForgotten = true
+    void rm(config.path, { force: true }).catch(() => {})
+  }
+
   private refreshPromptGate(): PromptGateState {
     return this.publishPromptGate(this.derivePromptGateState())
   }
@@ -1197,7 +1223,13 @@ export class ClaudeSession extends EventEmitter {
     const tldrHooks = tldrHookServer(this.builtInMcpServers)
     if (tldrHooks) env[CLAUDE_TLDR_HOOK_TOKEN_ENV] = tldrHooks.bearerToken
     excludeExternalControlFromClaude(args, tldrHooks ? claudeTldrHookSettings(tldrHooks.tldrHooks.baseUrl) : {})
-    this.privateMcpConfig = await createPrivateClaudeMcpConfig(this.builtInMcpServers)
+    // User servers (#1143) are resolved INTO the private file, never into
+    // Claude's environment, which every child process and model shell would
+    // inherit; see claudeUserMcpEntries. Main has already dropped anything the
+    // translator would refuse.
+    const userMcp = claudeUserMcpEntries(this.userMcpServers)
+    this.privateMcpConfig = await createPrivateClaudeMcpConfig(this.builtInMcpServers, userMcp.entries)
+    this.privateMcpConfigForgotten = false
     if (this.privateMcpConfig) args.push('--mcp-config', this.privateMcpConfig.path)
   }
 
diff --git a/src/providers/codex/runtime/codexSession.ts b/src/providers/codex/runtime/codexSession.ts
index f3917c769..946985e31 100644
--- a/src/providers/codex/runtime/codexSession.ts
+++ b/src/providers/codex/runtime/codexSession.ts
@@ -36,6 +36,8 @@ import type {
 } from '@shared/types/session.js'
 import { isCodexReadyForPromptScreen } from '@providers/codex/runtime/codexReadyForPrompt.js'
 import { addCodexBuiltInMcpLaunchConfig } from '@providers/shared/runtime/builtInMcpLaunch.js'
+import { addCodexUserMcpLaunchConfig, type CodexShellPolicyStyle } from '@providers/shared/runtime/userMcpLaunch.js'
+import type { ResolvedUserMcpServer } from '@shared/userMcp/types.js'
 import { forwardCodexRolloutEntries } from '@providers/codex/runtime/codexHeadlessForwarding.js'
 
 
@@ -118,6 +120,9 @@ export type CodexSessionOptions = {
   shellSessionId?: string
   useProxy?: boolean
   builtInMcpServers?: BuiltInMcpServerConfig[]
+  /** Already filtered and secret-resolved by main (#1143). */
+  userMcpServers?: ResolvedUserMcpServer[]
+  userMcpCodexShellPolicy?: CodexShellPolicyStyle
   beforeResumeOwnershipAcquire?: () => Promise<void>
 }
 
@@ -239,6 +244,8 @@ export class CodexSession extends EventEmitter {
   private readonly shellSessionId: string | null
   private readonly useProxy: boolean
   private readonly builtInMcpServers: BuiltInMcpServerConfig[]
+  private readonly userMcpServers: ResolvedUserMcpServer[]
+  private readonly userMcpCodexShellPolicy: CodexShellPolicyStyle | undefined
   private readonly beforeResumeOwnershipAcquire: (() => Promise<void>) | null
   private proxyServer: ResponsesProxy | null = null
   private proxyAdapter: CodexResponsesAdapter | null = null
@@ -260,6 +267,8 @@ export class CodexSession extends EventEmitter {
     this.shellSessionId = options.shellSessionId ?? null
     this.useProxy = options.useProxy === true
     this.builtInMcpServers = options.builtInMcpServers ?? []
+    this.userMcpServers = options.userMcpServers ?? []
+    this.userMcpCodexShellPolicy = options.userMcpCodexShellPolicy
     this.beforeResumeOwnershipAcquire =
       options.beforeResumeOwnershipAcquire ?? null
     // Fallback matches sessionManager's explicit 100ms (~10Hz) — see
@@ -342,6 +351,10 @@ export class CodexSession extends EventEmitter {
       args.push('--dangerously-bypass-approvals-and-sandbox')
     }
     addCodexBuiltInMcpLaunchConfig(this.builtInMcpServers, args, cleanEnv)
+    // #1143. Main dry-ran this same translator and reported anything it
+    // refuses, so the return value (dropped servers) is empty here by
+    // construction; it is not re-reported.
+    addCodexUserMcpLaunchConfig(this.userMcpServers, args, cleanEnv, this.userMcpCodexShellPolicy)
     excludeExternalControlFromCodex(args, cleanEnv.CODEX_HOME)
     if (this.useProxy) {
       // Mirror the Claude proxy's on-disk layout so a single
diff --git a/src/providers/shared/runtime/builtInMcpLaunch.ts b/src/providers/shared/runtime/builtInMcpLaunch.ts
index 9839101a5..0cd00d1a8 100644
--- a/src/providers/shared/runtime/builtInMcpLaunch.ts
+++ b/src/providers/shared/runtime/builtInMcpLaunch.ts
@@ -1,4 +1,4 @@
-import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { mkdtemp, readdir, rm, writeFile } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
@@ -115,24 +115,40 @@ export function addOpencodeBuiltInMcpLaunchConfig(
  */
 export async function createPrivateClaudeMcpConfig(
   servers: readonly BuiltInMcpServerConfig[],
+  // User MCP servers (#1143) share this one file rather than a second
+  // `--mcp-config`: the flag is variadic and swallows positional arguments that
+  // follow it, so one occurrence kept last is the only placement that cannot
+  // eat `--resume`. NOTE: user entries carry RESOLVED secret values (see
+  // claudeUserMcpEntries for why the file beats Claude's environment). Never
+  // log or copy this document; the file is removed once Claude is ready
+  // (ClaudeSession.forgetPrivateMcpConfigContents), on stop and rollback, and
+  // by the startup sweep after a crash.
+  userEntries: Readonly<Record<string, Record<string, unknown>>> = {},
 ): Promise<PrivateMcpConfig | null> {
-  if (servers.length === 0) return null
-  const directory = await mkdtemp(join(tmpdir(), 'agent-code-mcp-'))
+  if (servers.length === 0 && Object.keys(userEntries).length === 0) return null
+  // The pid in the prefix lets sweepStalePrivateMcpConfigs tell a crashed
+  // run's leftovers from a live instance's files.
+  const directory = await mkdtemp(join(tmpdir(), `${PRIVATE_MCP_CONFIG_PREFIX}${process.pid}-`))
   const path = join(directory, 'mcp.json')
   const document = {
-    mcpServers: Object.fromEntries(servers.map(server => [
-      server.name,
-      {
-        type: 'http',
-        url: server.url,
-        headers: {
-          ...server.headers,
-          ...(server.bearerToken === undefined
-            ? {}
-            : { Authorization: `Bearer ${server.bearerToken}` }),
+    mcpServers: Object.fromEntries([
+      // User entries first so a built-in entry can never be shadowed. Reserved
+      // names are rejected upstream; this ordering is the second fence.
+      ...Object.entries(userEntries),
+      ...servers.map(server => [
+        server.name,
+        {
+          type: 'http',
+          url: server.url,
+          headers: {
+            ...server.headers,
+            ...(server.bearerToken === undefined
+              ? {}
+              : { Authorization: `Bearer ${server.bearerToken}` }),
+          },
         },
-      },
-    ])),
+      ]),
+    ]),
   }
   try {
     await writeFile(path, `${JSON.stringify(document)}\n`, { encoding: 'utf8', mode: 0o600 })
@@ -148,6 +164,48 @@ export async function createPrivateClaudeMcpConfig(
   }
 }
 
+const PRIVATE_MCP_CONFIG_PREFIX = 'agent-code-mcp-'
+
+/**
+ * Remove private MCP config directories left behind by a run that crashed.
+ *
+ * WHY this became necessary (#1143 review round 1): the file used to hold only
+ * a per-session built-in bearer, worthless once that run ended. It now also
+ * holds user MCP secrets, which are long-lived, so a crash must not leave them
+ * on disk. Only directories whose owning pid is no longer alive are removed,
+ * so a second Agent Code instance (dev beside packaged) keeps its live files.
+ * Directories from before the pid prefix have no pid and are removed too:
+ * nothing can still be using a file from a build that no longer runs.
+ */
+export async function sweepStalePrivateMcpConfigs(dir = tmpdir()): Promise<number> {
+  let names: string[]
+  try {
+    names = await readdir(dir)
+  } catch {
+    return 0
+  }
+  let removed = 0
+  for (const name of names) {
+    if (!name.startsWith(PRIVATE_MCP_CONFIG_PREFIX)) continue
+    const pid = Number(/^agent-code-mcp-(\d+)-/.exec(name)?.[1])
+    if (Number.isInteger(pid) && pid > 0 && pid !== process.pid && isAlive(pid)) continue
+    if (pid === process.pid) continue
+    await rm(join(dir, name), { recursive: true, force: true }).catch(() => {})
+    removed++
+  }
+  return removed
+}
+
+function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    // EPERM: the process exists but belongs to someone else.
+    return (error as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
 function tomlKeySegment(value: string): string {
   return /^[A-Za-z0-9_-]+$/.test(value) ? value : JSON.stringify(value)
 }
diff --git a/src/providers/shared/runtime/userMcpLaunch.test.ts b/src/providers/shared/runtime/userMcpLaunch.test.ts
new file mode 100644
index 000000000..94fe46040
--- /dev/null
+++ b/src/providers/shared/runtime/userMcpLaunch.test.ts
@@ -0,0 +1,237 @@
+import { mkdtemp, mkdir, readFile, readdir, rm, stat } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+import { describe, expect, it } from 'vitest'
+
+import { createPrivateClaudeMcpConfig, sweepStalePrivateMcpConfigs } from './builtInMcpLaunch.js'
+import {
+  addCodexUserMcpLaunchConfig,
+  claudeUserMcpEntries,
+  userMcpSecretVariable,
+  type ResolvedUserMcpServer,
+} from './userMcpLaunch.js'
+
+const TOKEN = 'bpr_live_9f3a1c'
+
+// The Beeper Desktop HTTP server as it looks after importing its official
+// snippet (https://developers.beeper.com/desktop-api/mcp/): the token has been
+// lifted into a secret input and only the reference remains in the entry.
+const beeperHttp: ResolvedUserMcpServer = {
+  id: 'b1',
+  name: 'beeper',
+  entry: {
+    type: 'http',
+    url: 'http://localhost:23373/v0/mcp',
+    headers: { Authorization: 'Bearer ${input:beeper-authorization}' },
+  },
+  secrets: { 'beeper-authorization': TOKEN },
+}
+
+// The official stdio alternative (`npx -y @beeper/mcp-remote`), where the
+// server expands its own ${ACCESS_TOKEN} from the environment we give it.
+const beeperStdio: ResolvedUserMcpServer = {
+  id: 'b2',
+  name: 'beeper-stdio',
+  entry: {
+    command: 'npx',
+    args: ['-y', '@beeper/mcp-remote', '--header', 'Authorization: Bearer ${ACCESS_TOKEN}'],
+    env: { ACCESS_TOKEN: '${input:beeper-access_token}', LOG_LEVEL: 'info' },
+  },
+  secrets: { 'beeper-access_token': TOKEN },
+}
+
+describe('claudeUserMcpEntries', () => {
+  it('resolves a secret header into that server\'s own entry, never into Claude\'s environment', () => {
+    // Review round 1: Claude hands its whole environment to every MCP child
+    // and to the model's Bash tool, so the value must live only in the entry.
+    const result = claudeUserMcpEntries([beeperHttp])
+    expect(result.dropped).toEqual([])
+    expect(result.entries).toEqual({
+      beeper: { type: 'http', url: 'http://localhost:23373/v0/mcp', headers: { Authorization: `Bearer ${TOKEN}` } },
+    })
+    expect(result).not.toHaveProperty('env')
+  })
+
+  it('keeps literal env values and the server-expanded args of a stdio server', () => {
+    const { entries } = claudeUserMcpEntries([beeperStdio])
+    expect(entries['beeper-stdio']).toEqual({
+      command: 'npx',
+      args: ['-y', '@beeper/mcp-remote', '--header', 'Authorization: Bearer ${ACCESS_TOKEN}'],
+      env: { ACCESS_TOKEN: TOKEN, LOG_LEVEL: 'info' },
+    })
+  })
+
+  it('drops a server whose env or header names would break Codex -c paths', () => {
+    const dotted: ResolvedUserMcpServer = { id: 'd', name: 'java', entry: { command: 'x', env: { 'java.home': '/opt' } }, secrets: {} }
+    expect(claudeUserMcpEntries([dotted]).dropped[0]?.reason).toMatch(/java\.home/)
+    const args: string[] = []
+    expect(addCodexUserMcpLaunchConfig([dotted], args, {})[0]?.reason).toMatch(/java\.home/)
+    expect(args).toEqual([])
+  })
+
+  it('drops a server whose secret is missing instead of emitting an empty credential', () => {
+    const { entries, dropped } = claudeUserMcpEntries([{ ...beeperHttp, secrets: {} }])
+    expect(entries).toEqual({})
+    expect(dropped).toEqual([{ name: 'beeper', reason: 'A secret is not set' }])
+  })
+
+  it('writes one private file containing both built-in and user servers', async () => {
+    const { entries } = claudeUserMcpEntries([beeperHttp])
+    const config = await createPrivateClaudeMcpConfig(
+      [{ name: 'agent_code', url: 'http://127.0.0.1:1/mcp', headers: {}, bearerToken: 'builtin' }],
+      entries,
+    )
+    try {
+      const text = await readFile(config!.path, 'utf8')
+      expect(Object.keys(JSON.parse(text).mcpServers)).toEqual(['beeper', 'agent_code'])
+      // The file is private (0600, removed on stop, swept after a crash).
+      expect((await stat(config!.path)).mode & 0o777).toBe(0o600)
+    } finally {
+      await config?.dispose()
+    }
+  })
+
+  it('still creates the file when only user servers are attached', async () => {
+    const config = await createPrivateClaudeMcpConfig([], claudeUserMcpEntries([beeperHttp]).entries)
+    expect(config).not.toBeNull()
+    await config?.dispose()
+  })
+})
+
+describe('addCodexUserMcpLaunchConfig', () => {
+  it('passes every HTTP header through env_http_headers so no token reaches argv', () => {
+    const args: string[] = []
+    const env: Record<string, string> = {}
+    expect(addCodexUserMcpLaunchConfig([beeperHttp], args, env)).toEqual([])
+    const variable = userMcpSecretVariable('beeper', 'Authorization')
+    expect(args).toEqual([
+      '--config', 'mcp_servers.beeper.url="http://localhost:23373/v0/mcp"',
+      '--config', `mcp_servers.beeper.env_http_headers.Authorization="${variable}"`,
+      // Review round 1: Codex model shells inherit the full environment, so
+      // every secret-bearing variable is excluded from them.
+      '--config', 'shell_environment_policy.filters.AGENT_CODE_USER_MCP_*="exclude"',
+    ])
+    expect(env).toEqual({ [variable]: `Bearer ${TOKEN}` })
+    expect(args.join(' ')).not.toContain(TOKEN)
+  })
+
+  it('passes stdio secrets by name through env_vars and literals per server', () => {
+    const args: string[] = []
+    const env: Record<string, string> = {}
+    expect(addCodexUserMcpLaunchConfig([beeperStdio], args, env)).toEqual([])
+    expect(args).toEqual([
+      '--config', 'mcp_servers.beeper-stdio.command="npx"',
+      '--config', 'mcp_servers.beeper-stdio.args=["-y","@beeper/mcp-remote","--header","Authorization: Bearer ${ACCESS_TOKEN}"]',
+      '--config', 'mcp_servers.beeper-stdio.env.LOG_LEVEL="info"',
+      '--config', 'mcp_servers.beeper-stdio.env_vars=["ACCESS_TOKEN"]',
+      '--config', 'shell_environment_policy.filters.ACCESS_TOKEN="exclude"',
+    ])
+    expect(env).toEqual({ ACCESS_TOKEN: TOKEN })
+    expect(args.join(' ')).not.toContain(TOKEN)
+  })
+
+  it('drops SSE servers and secrets that would overwrite Codex\'s own environment', () => {
+    expect(addCodexUserMcpLaunchConfig([
+      { id: 'px', name: 'proxied', entry: { command: 'x', env: { HTTPS_PROXY: '${input:p}' } }, secrets: { p: 'http://corp' } },
+    ], [], {})[0]?.name).toBe('proxied')
+    const args: string[] = []
+    const dropped = addCodexUserMcpLaunchConfig([
+      { id: 's', name: 'linear', entry: { type: 'sse', url: 'https://mcp.linear.app/sse' }, secrets: {} },
+      { id: 'o', name: 'openai', entry: { command: 'x', env: { OPENAI_API_KEY: '${input:k}' } }, secrets: { k: 'v' } },
+    ], args, {})
+    expect(dropped.map(server => server.name)).toEqual(['linear', 'openai'])
+    expect(args).toEqual([])
+  })
+
+  it('refuses a second server that needs the same env name with a different value', () => {
+    const env: Record<string, string> = {}
+    const mk = (name: string, value: string): ResolvedUserMcpServer => ({
+      id: name, name, entry: { command: name, env: { GITHUB_TOKEN: '${input:t}' } }, secrets: { t: value },
+    })
+    const dropped = addCodexUserMcpLaunchConfig([mk('one', 'a'), mk('two', 'b'), mk('three', 'a')], [], env)
+    expect(dropped).toEqual([{ name: 'two', reason: 'Secret GITHUB_TOKEN is already used with a different value by one' }])
+    expect(env.GITHUB_TOKEN).toBe('a')
+  })
+
+  it('leaves no partial table behind for a server dropped half-way', () => {
+    const args: string[] = []
+    addCodexUserMcpLaunchConfig([{ ...beeperStdio, secrets: {} }], args, {})
+    expect(args).toEqual([])
+  })
+})
+
+describe('userMcpSecretVariable', () => {
+  it('is stable for the same server and key', () => {
+    expect(userMcpSecretVariable('beeper', 'Authorization')).toBe(userMcpSecretVariable('beeper', 'Authorization'))
+    expect(userMcpSecretVariable('beeper', 'Authorization')).toMatch(/^AGENT_CODE_USER_MCP_BEEPER_AUTHORIZATION_[0-9A-F]{10}$/)
+  })
+
+  it('never gives two different (server, key) pairs the same variable (review round 1)', () => {
+    // These folded to the same name before the hash suffix, sending one
+    // server's token to the other server's host.
+    expect(userMcpSecretVariable('linear', 'X-Api-Key')).not.toBe(userMcpSecretVariable('linear-x', 'Api-Key'))
+    expect(userMcpSecretVariable('gh', 'k')).not.toBe(userMcpSecretVariable('_gh', 'k'))
+  })
+})
+
+describe('Codex shell exclusion styles', () => {
+  it('re-sends the user\'s legacy exclude list together with ours, since a -c array replaces it', () => {
+    const args: string[] = []
+    addCodexUserMcpLaunchConfig([beeperHttp], args, {}, { style: 'legacy', exclude: ['MY_SECRET'] })
+    expect(args.at(-1)).toBe('shell_environment_policy.exclude=["MY_SECRET","AGENT_CODE_USER_MCP_*"]')
+    expect(args.join(' ')).not.toContain('shell_environment_policy.filters')
+  })
+
+  it('adds nothing to the shell policy when no secret is carried', () => {
+    const args: string[] = []
+    addCodexUserMcpLaunchConfig([{ id: 'p', name: 'plain', entry: { command: 'x', env: { LOG_LEVEL: 'info' } }, secrets: {} }], args, {})
+    expect(args.join(' ')).not.toContain('shell_environment_policy')
+  })
+})
+
+describe('sweepStalePrivateMcpConfigs', () => {
+  it('removes a crashed run\'s private configs but keeps live ones', async () => {
+    const dir = await mkdtemp(join(tmpdir(), 'sweep-'))
+    try {
+      await mkdir(join(dir, `agent-code-mcp-${process.pid}-live`))
+      await mkdir(join(dir, 'agent-code-mcp-2147483646-dead'))
+      await mkdir(join(dir, 'agent-code-mcp-legacyXYZ'))
+      await mkdir(join(dir, 'unrelated'))
+      expect(await sweepStalePrivateMcpConfigs(dir)).toBe(2)
+      expect((await readdir(dir)).sort()).toEqual([`agent-code-mcp-${process.pid}-live`, 'unrelated'])
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+})
+
+
+describe('review round 2 Codex launch rules', () => {
+  const mk = (name: string, env: Record<string, string>, secrets: Record<string, string>): ResolvedUserMcpServer =>
+    ({ id: name, name, entry: { command: name, env }, secrets })
+
+  it('never emits two shell filters that differ only in case (Codex rejects them)', () => {
+    const args: string[] = []
+    const dropped = addCodexUserMcpLaunchConfig([
+      mk('a', { GITHUB_TOKEN: '${input:t}' }, { t: 'v' }),
+      mk('b', { github_token: '${input:t}' }, { t: 'v' }),
+    ], args, {})
+    const filters = args.filter(arg => arg.startsWith('shell_environment_policy.filters.'))
+    expect(new Set(filters.map(filter => filter.toUpperCase())).size).toBe(filters.length)
+    expect(dropped.length + filters.length).toBeGreaterThan(0)
+  })
+
+  it('refuses to silently replace the user\'s own variable with a different value', () => {
+    const env: Record<string, string> = { GITHUB_TOKEN: 'users-own' }
+    const dropped = addCodexUserMcpLaunchConfig([mk('gh', { GITHUB_TOKEN: '${input:t}' }, { t: 'other' })], [], env)
+    expect(dropped[0]?.reason).toMatch(/Your environment already sets GITHUB_TOKEN/)
+    expect(env.GITHUB_TOKEN).toBe('users-own')
+  })
+
+  it('does not hide the user\'s own identical variable from model shells', () => {
+    const args: string[] = []
+    addCodexUserMcpLaunchConfig([mk('gh', { GITHUB_TOKEN: '${input:t}' }, { t: 'same' })], args, { GITHUB_TOKEN: 'same' })
+    expect(args.join(' ')).not.toContain('shell_environment_policy')
+  })
+})
diff --git a/src/providers/shared/runtime/userMcpLaunch.ts b/src/providers/shared/runtime/userMcpLaunch.ts
new file mode 100644
index 000000000..1e86ab322
--- /dev/null
+++ b/src/providers/shared/runtime/userMcpLaunch.ts
@@ -0,0 +1,307 @@
+import { createHash } from 'node:crypto'
+
+import { hasInputReference, substituteInputs } from '@shared/userMcp/inputs.js'
+import type { ResolvedUserMcpServer, UserMcpDroppedServer } from '@shared/userMcp/types.js'
+// CODEX_PROTECTED_ENV's WHY lives beside its definition in validate.ts.
+import {
+  CODEX_PROTECTED_ENV,
+  isStringArray,
+  isStringRecord,
+  transportOf,
+  USER_MCP_ENV_KEY_PATTERN,
+  USER_MCP_HEADER_NAME_PATTERN,
+} from '@shared/userMcp/validate.js'
+
+export type { ResolvedUserMcpServer }
+
+/** Prefix of every generated secret variable; also the shell-exclusion glob. */
+export const USER_MCP_SECRET_VARIABLE_PREFIX = 'AGENT_CODE_USER_MCP_'
+
+/**
+ * Environment variable that carries one secret-bearing Codex header value.
+ *
+ * WHY deterministic from (server name, key) rather than an index: a stable
+ * name keeps the launch config identical across launches, so nothing keyed on
+ * it shifts when an unrelated server is toggled.
+ *
+ * WHY a hash suffix (review round 1): the readable part folds case and every
+ * non-alphanumeric run to `_`, so `linear`+`X-Api-Key` and `linear-x`+`Api-Key`
+ * both produced `…_LINEAR_X_API_KEY` and one server's token was sent to the
+ * other server's host. The suffix is over the exact (name, key) pair, so
+ * distinct pairs cannot collide while the name stays stable for the same pair.
+ */
+export function userMcpSecretVariable(serverName: string, key: string): string {
+  const part = (value: string) => value.toUpperCase().replace(/[^A-Z0-9]+/g, '_').replace(/^_+|_+$/g, '')
+  const digest = createHash('sha256').update(`${serverName}\0${key}`).digest('hex').slice(0, 10).toUpperCase()
+  return `${USER_MCP_SECRET_VARIABLE_PREFIX}${part(serverName) || 'SERVER'}_${part(key) || 'VALUE'}_${digest}`
+}
+
+/**
+ * Keys that cannot travel safely on either launcher. Codex splits `-c` key
+ * paths on every '.', so a dotted env key or header name turns into a nested
+ * table and fails config load for the WHOLE Codex launch (reproduced with
+ * codex-cli in review round 1). Validation rejects these on save; this is the
+ * launch-side fence for documents written by other builds or by hand.
+ */
+function invalidKey(entry: Record<string, unknown>): string | null {
+  if (isStringRecord(entry.env)) {
+    const bad = Object.keys(entry.env).find(key => !USER_MCP_ENV_KEY_PATTERN.test(key))
+    if (bad !== undefined) return `Invalid environment variable name "${bad}"`
+  }
+  if (isStringRecord(entry.headers)) {
+    const bad = Object.keys(entry.headers).find(key => !USER_MCP_HEADER_NAME_PATTERN.test(key))
+    if (bad !== undefined) return `Invalid header name "${bad}"`
+  }
+  return null
+}
+
+/**
+ * Claude `mcpServers` entries for the private `--mcp-config` file, with
+ * secret values RESOLVED into the entry.
+ *
+ * WHY values go into the file and not Claude's environment (review round 1):
+ * Claude launches every stdio MCP child, its Bash tool and hooks with its own
+ * full environment (vendor services/mcp/client.ts `{...subprocessEnv(),
+ * ...serverRef.env}`; subprocessEnv is unfiltered by default). A secret in
+ * Claude's env therefore reached every third-party MCP server and any `env`
+ * the model ran — and from there the transcript and the provider. In the file,
+ * a stdio secret reaches only its own server's `env`, and a header only its
+ * own server's requests. It is the file the built-in bearer already uses: mode
+ * 0600 in a private temp directory, removed on stop and rollback, and swept at
+ * startup if a crash left it behind (sweepStalePrivateMcpConfigs).
+ *
+ * Literal values and unknown keys pass through untouched: Claude's zod schemas
+ * strip keys they do not know rather than rejecting them.
+ */
+export function claudeUserMcpEntries(servers: readonly ResolvedUserMcpServer[]): {
+  entries: Record<string, Record<string, unknown>>
+  dropped: UserMcpDroppedServer[]
+} {
+  const entries: Record<string, Record<string, unknown>> = {}
+  const dropped: UserMcpDroppedServer[] = []
+  for (const server of servers) {
+    const transport = transportOf(server.entry)
+    if (!transport) {
+      dropped.push({ name: server.name, reason: 'Invalid server config' })
+      continue
+    }
+    const entry: Record<string, unknown> = { ...server.entry }
+    const keyProblem = invalidKey(entry)
+    if (keyProblem) {
+      dropped.push({ name: server.name, reason: keyProblem })
+      continue
+    }
+    let missing = false
+    for (const field of ['env', 'headers'] as const) {
+      const record = entry[field]
+      if (!isStringRecord(record)) continue
+      const next: Record<string, string> = {}
+      for (const [key, value] of Object.entries(record)) {
+        if (!hasInputReference(value)) {
+          next[key] = value
+          continue
+        }
+        const resolved = substituteInputs(value, server.secrets)
+        if (resolved === null) {
+          missing = true
+          break
+        }
+        next[key] = resolved
+      }
+      entry[field] = next
+    }
+    if (missing) {
+      dropped.push({ name: server.name, reason: 'A secret is not set' })
+      continue
+    }
+    // Explicit type keeps Claude's union parse unambiguous for remote entries;
+    // stdio is valid with or without it.
+    if (transport !== 'stdio') entry.type = transport
+    entries[server.name] = entry
+  }
+  return { entries, dropped }
+}
+
+/**
+ * How the user's own Codex config spells shell-environment exclusions, read by
+ * main from the user and project config.toml.
+ *
+ * WHY it matters: Codex rejects a config that mixes the keyed `filters` table
+ * with the legacy `exclude`/`include_only` arrays (verified against codex-cli:
+ * it fails config load, so the whole launch). `filters` merges key by key
+ * across layers, so we can ADD our exclusions without touching the user's; the
+ * legacy array is replaced wholesale by a `-c` layer, so there we must re-send
+ * the user's own entries together with ours.
+ */
+export type CodexShellPolicyStyle =
+  | { style: 'filters' }
+  | { style: 'legacy'; exclude: readonly string[] }
+
+/**
+ * Add Codex `-c mcp_servers.<name>.*` overrides for user servers.
+ *
+ * Why each field travels the way it does (argv is readable by any local
+ * process and by our incident collectors; see builtInMcpLaunch.ts):
+ *  - command/args/cwd/url: literal on argv. Validation already guarantees they
+ *    contain no `${input:…}` secret.
+ *  - stdio env, literal values: `env.<KEY>=` on argv, per server, so they
+ *    never change Codex's own environment.
+ *  - stdio env, secret values: set `KEY` in Codex's environment and list it in
+ *    `env_vars`. Codex does no `${VAR}` expansion and `env_vars` cannot rename,
+ *    so pass-through by the server's own variable name is the only secret-safe
+ *    channel.
+ *  - http headers (all of them): `env_http_headers.<H>="<generated var>"`,
+ *    exactly like the built-in servers.
+ *
+ * Every variable that carries a secret is then EXCLUDED from Codex's model
+ * shells via shell_environment_policy (review round 1): Codex's default policy
+ * inherits the full environment with its KEY and TOKEN name filters off, so without
+ * this an `echo $GITHUB_TOKEN` in any shell command printed the secret into
+ * the transcript. MCP children are unaffected: they get only Codex's allowlist
+ * plus their own `env_vars`.
+ *
+ * Accepted residual (review round 2): Codex builds hook and `notify` commands
+ * from its own full process environment with no shell policy (vendor codex-rs
+ * hooks registry), so user, plugin and trusted-project hooks can read these
+ * variables. Closing that needs a wrapper that feeds the server its secret
+ * from a file instead of the Codex environment; recorded as a follow-up.
+ *
+ * Returns servers that could not be attached; a dropped server never fails
+ * the launch.
+ */
+export function addCodexUserMcpLaunchConfig(
+  servers: readonly ResolvedUserMcpServer[],
+  args: string[],
+  env: Record<string, string>,
+  shellPolicy: CodexShellPolicyStyle = { style: 'filters' },
+): UserMcpDroppedServer[] {
+  const dropped: UserMcpDroppedServer[] = []
+  // Secret env names already claimed by an earlier server in this launch,
+  // keyed case-insensitively (review round 2): Codex treats shell filter
+  // patterns case-insensitively and rejects `GITHUB_TOKEN` + `github_token` as
+  // duplicate filters, failing config load for the whole launch.
+  const claimed = new Map<string, string>()
+  // The environment Codex would have had without us. A pass-through secret
+  // that silently replaced the user's own variable of the same name (say the
+  // GITHUB_TOKEN their shells use for `gh`) and then hid it from model shells
+  // broke unrelated tooling with nothing on screen (review round 2).
+  const inherited = { ...env }
+  const secretNames = new Set<string>()
+  let generatedSecrets = false
+  for (const server of servers) {
+    const transport = transportOf(server.entry)
+    if (!transport) {
+      dropped.push({ name: server.name, reason: 'Invalid server config' })
+      continue
+    }
+    if (transport === 'sse') {
+      dropped.push({ name: server.name, reason: 'Codex does not support SSE servers' })
+      continue
+    }
+    const keyProblem = invalidKey(server.entry as Record<string, unknown>)
+    if (keyProblem) {
+      dropped.push({ name: server.name, reason: keyProblem })
+      continue
+    }
+    const serverArgs: string[] = []
+    const serverEnv: Record<string, string> = {}
+    const serverSecretNames: string[] = []
+    const prefix = `mcp_servers.${server.name}`
+    const set = (key: string, value: unknown) => serverArgs.push('--config', `${prefix}.${key}=${JSON.stringify(value)}`)
+    let failure: string | null = null
+
+    if (transport === 'stdio') {
+      const entry = server.entry as Record<string, unknown>
+      set('command', entry.command)
+      if (isStringArray(entry.args) && entry.args.length > 0) set('args', entry.args)
+      if (typeof entry.cwd === 'string' && entry.cwd) set('cwd', entry.cwd)
+      const passThrough: string[] = []
+      if (isStringRecord(entry.env)) {
+        for (const [key, value] of Object.entries(entry.env)) {
+          if (!hasInputReference(value)) {
+            set(`env.${key}`, value)
+            continue
+          }
+          const resolved = substituteInputs(value, server.secrets)
+          if (resolved === null) {
+            failure = 'A secret is not set'
+            break
+          }
+          if (CODEX_PROTECTED_ENV.test(key)) {
+            failure = `Codex cannot pass a secret named ${key} without changing its own environment`
+            break
+          }
+          const owner = claimed.get(key.toUpperCase())
+          if (owner !== undefined && env[key] !== resolved) {
+            failure = `Secret ${key} is already used with a different value by ${owner}`
+            break
+          }
+          const own = Object.keys(inherited).find(name => name.toUpperCase() === key.toUpperCase())
+          if (owner === undefined && own !== undefined && inherited[own] !== resolved) {
+            failure = `Your environment already sets ${own}; Codex cannot pass a different value to this server`
+            break
+          }
+          if (passThrough.some(name => name.toUpperCase() === key.toUpperCase())) {
+            failure = `Secrets ${key} differ only in letter case`
+            break
+          }
+          serverEnv[key] = resolved
+          passThrough.push(key)
+          // Not hidden from model shells when the user's own environment
+          // already carries this exact value: their shells saw it before this
+          // feature existed, and hiding it would break e.g. `gh` auth.
+          if (own === undefined) serverSecretNames.push(key)
+        }
+      }
+      if (passThrough.length > 0) set('env_vars', passThrough)
+    } else {
+      const entry = server.entry as Record<string, unknown>
+      set('url', entry.url)
+      if (isStringRecord(entry.headers)) {
+        for (const [header, value] of Object.entries(entry.headers)) {
+          const resolved = hasInputReference(value) ? substituteInputs(value, server.secrets) : value
+          if (resolved === null) {
+            failure = 'A secret is not set'
+            break
+          }
+          const variable = userMcpSecretVariable(server.name, header)
+          serverEnv[variable] = resolved
+          set(`env_http_headers.${header}`, variable)
+        }
+      }
+    }
+
+    if (failure) {
+      dropped.push({ name: server.name, reason: failure })
+      continue
+    }
+    // Commit only after the whole server succeeded, so a server dropped
+    // half-way leaves neither a partial `mcp_servers` table (which Codex would
+    // reject as an invalid transport, failing the entire launch) nor stray
+    // variables behind.
+    args.push(...serverArgs)
+    Object.assign(env, serverEnv)
+    for (const key of Object.keys(serverEnv)) {
+      if (key.startsWith(USER_MCP_SECRET_VARIABLE_PREFIX)) generatedSecrets = true
+      else claimed.set(key.toUpperCase(), server.name)
+    }
+    for (const name of serverSecretNames) secretNames.add(name)
+  }
+
+  const seen = new Set<string>()
+  const excluded = [...(generatedSecrets ? [`${USER_MCP_SECRET_VARIABLE_PREFIX}*`] : []), ...secretNames]
+    .filter(name => !seen.has(name.toUpperCase()) && seen.add(name.toUpperCase()))
+  if (excluded.length > 0) {
+    if (shellPolicy.style === 'legacy') {
+      const merged = [...new Set([...shellPolicy.exclude, ...excluded])]
+      args.push('--config', `shell_environment_policy.exclude=${JSON.stringify(merged)}`)
+    } else {
+      // Pattern keys contain no '.' (env names are validated), so the naive
+      // `-c` path split is safe.
+      for (const pattern of excluded) {
+        args.push('--config', `shell_environment_policy.filters.${pattern}="exclude"`)
+      }
+    }
+  }
+  return dropped
+}
diff --git a/src/renderer/src/app-state/settings/persistence.test.ts b/src/renderer/src/app-state/settings/persistence.test.ts
index 08fbc92e3..73780d3f6 100644
--- a/src/renderer/src/app-state/settings/persistence.test.ts
+++ b/src/renderer/src/app-state/settings/persistence.test.ts
@@ -1,3 +1,4 @@
+import { uniformBuiltInMcpDefaults } from '@mcp/shared/types'
 import { describe, expect, it } from 'vitest'
 
 import { coerceSettings } from '@renderer/app-state/settings/persistence'
@@ -61,12 +62,14 @@ describe('coerceSettings agentViewMode', () => {
   })
 
   it('defaults missing built-in MCP defaults to the shipped public set', () => {
+    // Per provider since #1143; every provider starts from the same shipped set.
     expect(coerceSettings({}).defaultBuiltInMcpDomains)
-      .toEqual(['tldr', 'goal', 'orchestration', 'agent_transcripts', 'workflows'])
+      .toEqual(uniformBuiltInMcpDefaults(['tldr', 'goal', 'orchestration', 'agent_transcripts', 'workflows']))
   })
 
   it('respects an explicit empty MCP domain list', () => {
-    expect(coerceSettings({ defaultBuiltInMcpDomains: [] }).defaultBuiltInMcpDomains).toEqual([])
+    // A pre-#1143 flat `[]` still means "nothing by default", now for every provider.
+    expect(coerceSettings({ defaultBuiltInMcpDomains: [] }).defaultBuiltInMcpDomains).toEqual(uniformBuiltInMcpDefaults([]))
   })
 
   it('keeps only configurable built-in MCP defaults in first-seen order', () => {
@@ -80,7 +83,18 @@ describe('coerceSettings agentViewMode', () => {
         'agent_management',
         12,
       ],
-    }).defaultBuiltInMcpDomains).toEqual(['workflows', 'orchestration', 'agent_management'])
+    }).defaultBuiltInMcpDomains).toEqual(uniformBuiltInMcpDefaults(['workflows', 'orchestration', 'agent_management']))
+  })
+
+  it('keeps a per-provider choice per provider (#1143)', () => {
+    const defaults = coerceSettings({
+      defaultBuiltInMcpDomains: { claude: ['tldr', 'ping'], codex: [], opencode: ['workflows'] },
+    }).defaultBuiltInMcpDomains
+    expect(defaults.claude).toEqual(['tldr'])
+    expect(defaults.codex).toEqual([])
+    expect(defaults.opencode).toEqual(['workflows'])
+    // A provider missing from the saved map gets the shipped default.
+    expect(defaults.grok).toEqual(['tldr', 'goal', 'orchestration', 'agent_transcripts', 'workflows'])
   })
 })
 
diff --git a/src/renderer/src/app-state/settings/persistence.ts b/src/renderer/src/app-state/settings/persistence.ts
index b0c9cd592..e53ce2f11 100644
--- a/src/renderer/src/app-state/settings/persistence.ts
+++ b/src/renderer/src/app-state/settings/persistence.ts
@@ -5,6 +5,7 @@ import {
   DEFAULT_SETTINGS,
   FONT_FAMILIES,
   isBuiltInThemeMode,
+  SHIPPED_BUILT_IN_MCP_DOMAINS,
   USAGE_HEADER_LEVELS,
 } from '@renderer/app-state/settings/types'
 import {
@@ -32,7 +33,7 @@ import { coerceCommandKeybindingOverrides } from '@renderer/features/command-key
 import { coerceHotkeyBinding } from '@renderer/lib/hotkeyBinding'
 import { coerceMouseButtonBinding, coerceMouseChordBinding } from '@renderer/lib/mouseBinding'
 import { coerceSavedPromptTemplates } from '@renderer/features/prompt-templates/savedPromptTemplates'
-import { normalizeConfigurableBuiltInMcpDomains } from '@mcp/shared/types'
+import { coerceBuiltInMcpDefaults, uniformBuiltInMcpDefaults } from '@mcp/shared/types'
 
 export function coerceSettings(value: unknown): Settings {
   const parsed = value && typeof value === 'object'
@@ -171,11 +172,21 @@ export function coerceSettings(value: unknown): Settings {
     // which is why the absent branch cannot go through the normalizer —
     // normalize treats an empty array as "no preference" and would flatten
     // the shipped default to nothing.
+    //
+    // #1143: the value became a per-provider map. A pre-#1143 flat list is
+    // copied to every provider by coerceBuiltInMcpDefaults, so an upgrade
+    // changes nobody's behavior; no store version bump is needed because this
+    // coercion runs on every hydration and no persisted value changed meaning.
+    //
+    // Known, accepted limitation: a pre-#1143 build reads this object as "not
+    // an array", normalizes it to [] and autosaves that, so downgrading and
+    // then upgrading again starts every provider with no built-in defaults.
+    // Writing the map under a new key would avoid it, at the cost of two keys
+    // for one preference in every build from now on; downgrades are rare and
+    // the loss is visible and one grid away from being restored.
     defaultBuiltInMcpDomains: parsed.defaultBuiltInMcpDomains === undefined
-      ? [...DEFAULT_SETTINGS.defaultBuiltInMcpDomains]
-      : normalizeConfigurableBuiltInMcpDomains(
-        parsed.defaultBuiltInMcpDomains,
-      ),
+      ? uniformBuiltInMcpDefaults(SHIPPED_BUILT_IN_MCP_DOMAINS)
+      : coerceBuiltInMcpDefaults(parsed.defaultBuiltInMcpDomains, SHIPPED_BUILT_IN_MCP_DOMAINS),
     // Same membership-check pattern as accent/mode: garbage / typo / a
     // removed font id from a future migration falls back to the default
     // rather than crashing applyTheme with an undefined family string.
@@ -358,6 +369,18 @@ export const RETIRED_BUILT_IN_COMMAND_IDS: ReadonlySet<string> = new Set([
   'attach-detached-to-grid',
   'attach-all-detached-for-tab',
   'detach-to-dispatch',
+  // Retired by the MCP servers interface (#1143): one staged "Agent MCP
+  // Servers…" picker replaced the per-capability toggles and the reset
+  // command. Listed for the same stale-override reason as the block above.
+  'use-global-mcp-settings',
+  'enable-ai-workspace-mcp',
+  'enable-orchestration-mcp',
+  'enable-agent-transcripts-mcp',
+  'enable-agent-management-mcp',
+  'enable-tldr-mcp',
+  'enable-goal-mcp',
+  'enable-goal-loop-mcp',
+  'enable-workflow-mcp',
 ])
 
 /**
diff --git a/src/renderer/src/app-state/settings/types.ts b/src/renderer/src/app-state/settings/types.ts
index d9dc7d1f1..e6ce03014 100644
--- a/src/renderer/src/app-state/settings/types.ts
+++ b/src/renderer/src/app-state/settings/types.ts
@@ -4,7 +4,14 @@ import type { PromptTemplate } from '@renderer/features/prompt-templates/types'
 import type { ColorFlagId } from '@renderer/app-state/settings/dispatchColorFlags'
 import type { DictationProvider } from '@shared/types/dictation'
 import type { MouseButtonBinding, MouseChordBinding } from '@renderer/lib/mouseBinding'
-import type { ConfigurableBuiltInMcpDomain } from '@mcp/shared/types'
+import { uniformBuiltInMcpDefaults } from '@mcp/shared/types'
+import type { BuiltInMcpDefaults, ConfigurableBuiltInMcpDomain } from '@mcp/shared/types'
+
+/** The shipped per-provider default, before any user choice. Exported so
+ * coercion can fall back to it for a provider missing from a persisted map. */
+export const SHIPPED_BUILT_IN_MCP_DOMAINS: readonly ConfigurableBuiltInMcpDomain[] = [
+  'tldr', 'goal', 'orchestration', 'agent_transcripts', 'workflows',
+]
 import type { CommandSortMode } from '@renderer/features/command-palette/lib/sortCommands'
 // Value import (not type-only): DEFAULT_SETTINGS.dictationShortcut shares ONE
 // source of truth with the HotkeyInput reset button and coerceHotkeyBinding's
@@ -408,7 +415,7 @@ export type Settings = {
    * including reloads. Per-domain session overrides win; a running process's
    * captured capability list is an observation, never its preference source.
    * `ping` stays diagnostic-only. Provider filters run after resolution. */
-  defaultBuiltInMcpDomains: ConfigurableBuiltInMcpDomain[]
+  defaultBuiltInMcpDomains: BuiltInMcpDefaults
   /** When true, agent sessions are spawned through a per-session proxy
    *  that Agent Code owns. Claude gets a mitmproxy that decrypts Anthropic
    *  `/v1/messages` SSE in real time; Codex gets an in-process Responses
@@ -705,7 +712,7 @@ export const DEFAULT_SETTINGS: Settings = {
   // are the Cmd+L / Cmd+G peeks — with no domains on, a new user never sees
   // them do anything. AI Workspace and Agent Management stay opt-in. An
   // explicitly persisted list (including `[]`) always wins in coerceSettings.
-  defaultBuiltInMcpDomains: ['tldr', 'goal', 'orchestration', 'agent_transcripts', 'workflows'],
+  defaultBuiltInMcpDomains: uniformBuiltInMcpDefaults(SHIPPED_BUILT_IN_MCP_DOMAINS),
   // Off (#973): a click that immediately sends a prompt to an agent surprised
   // the owner enough to turn it off; fill-then-edit is the safer public default.
   autoSendPromptSuggestion: false,
diff --git a/src/renderer/src/app-state/store.test.ts b/src/renderer/src/app-state/store.test.ts
index 3777975ed..5eef905ae 100644
--- a/src/renderer/src/app-state/store.test.ts
+++ b/src/renderer/src/app-state/store.test.ts
@@ -1,3 +1,4 @@
+import { uniformBuiltInMcpDefaults } from '@mcp/shared/types'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import {
@@ -79,7 +80,7 @@ describe('useAppStore prompt template migration', () => {
     // list. An install that explicitly cleared the domains persists `[]`,
     // which coerceSettings honours as a real choice.
     expect(useAppStore.getState().settings.defaultBuiltInMcpDomains)
-      .toEqual(['tldr', 'goal', 'orchestration', 'agent_transcripts', 'workflows'])
+      .toEqual(uniformBuiltInMcpDefaults(['tldr', 'goal', 'orchestration', 'agent_transcripts', 'workflows']))
   })
 })
 
diff --git a/src/renderer/src/app-state/types.ts b/src/renderer/src/app-state/types.ts
index aab5cd332..68fa4b024 100644
--- a/src/renderer/src/app-state/types.ts
+++ b/src/renderer/src/app-state/types.ts
@@ -6,6 +6,7 @@ import type {
   UiShellState,
 } from '@renderer/app-state/uiShell/types'
 import type { SessionId, TabId } from '@renderer/workspace/types'
+import type { BuiltInMcpOverrides } from '@mcp/shared/types'
 import type { WorkspaceState } from '@renderer/workspace/types'
 import type { SessionRuntime } from '@renderer/session-runtime/state'
 import type { ExtensionListEntry } from '@shared/types/extensions'
@@ -51,11 +52,15 @@ export type UiShellSlice = UiShellState & {
   closeMergeProjectTabs: () => void
   openPinAgents: () => void
   closePinAgents: () => void
-  openSettingsPage: () => void
+  openSettingsPage: (category?: string) => void
   closeSettingsPage: () => void
+  openMcpServerDialog: (target: { mode: 'add' } | { mode: 'edit'; serverId: string }) => void
+  closeMcpServerDialog: () => void
+  openAgentMcpServers: (sessionId: SessionId) => void
+  closeAgentMcpServers: () => void
   openAgentTitlePrompt: (sessionId: SessionId) => void
   closeAgentTitlePrompt: () => void
-  openRootManagementPrompt: (sessionId: SessionId) => void
+  openRootManagementPrompt: (sessionId: SessionId, stagedOverrides?: BuiltInMcpOverrides, stopGoalLoop?: boolean) => void
   closeRootManagementPrompt: () => void
   openDebugBundleNotePrompt: (payload: {
     bundlePath: string
diff --git a/src/renderer/src/app-state/uiShell/slice.ts b/src/renderer/src/app-state/uiShell/slice.ts
index 33fbbcb3e..9fb907462 100644
--- a/src/renderer/src/app-state/uiShell/slice.ts
+++ b/src/renderer/src/app-state/uiShell/slice.ts
@@ -23,8 +23,14 @@ export const createUiShellSlice: StateCreator<
   mergeProjectTabsOpen: false,
   pinAgentsOpen: false,
   settingsPageOpen: false,
+  settingsPageCategory: null,
+  settingsPageRequest: 0,
+  mcpServerDialog: null,
+  agentMcpServersSessionId: null,
   agentTitlePromptSessionId: null,
   rootManagementPromptSessionId: null,
+  rootManagementPromptOverrides: null,
+  rootManagementPromptStopGoalLoop: false,
   debugBundleNotePrompt: null,
   recordingNotePrompt: null,
   viewPromptsSessionId: null,
@@ -135,20 +141,40 @@ export const createUiShellSlice: StateCreator<
   closePinAgents: () =>
     set({ pinAgentsOpen: false }, false, 'uiShell/closePinAgents'),
 
-  openSettingsPage: () =>
-    set({ settingsPageOpen: true }, false, 'uiShell/openSettingsPage'),
+  openSettingsPage: category =>
+    set(state => ({
+      settingsPageOpen: true,
+      settingsPageCategory: category ?? null,
+      settingsPageRequest: state.settingsPageRequest + 1,
+    }), false, 'uiShell/openSettingsPage'),
   closeSettingsPage: () =>
-    set({ settingsPageOpen: false }, false, 'uiShell/closeSettingsPage'),
+    set({ settingsPageOpen: false, settingsPageCategory: null }, false, 'uiShell/closeSettingsPage'),
+  openMcpServerDialog: target =>
+    set({ mcpServerDialog: target }, false, 'uiShell/openMcpServerDialog'),
+  closeMcpServerDialog: () =>
+    set({ mcpServerDialog: null }, false, 'uiShell/closeMcpServerDialog'),
+  openAgentMcpServers: sessionId =>
+    set({ agentMcpServersSessionId: sessionId }, false, 'uiShell/openAgentMcpServers'),
+  closeAgentMcpServers: () =>
+    set({ agentMcpServersSessionId: null }, false, 'uiShell/closeAgentMcpServers'),
 
   openAgentTitlePrompt: sessionId =>
     set({ agentTitlePromptSessionId: sessionId }, false, 'uiShell/openAgentTitlePrompt'),
   closeAgentTitlePrompt: () =>
     set({ agentTitlePromptSessionId: null }, false, 'uiShell/closeAgentTitlePrompt'),
 
-  openRootManagementPrompt: sessionId =>
-    set({ rootManagementPromptSessionId: sessionId }, false, 'uiShell/openRootManagementPrompt'),
+  openRootManagementPrompt: (sessionId, stagedOverrides, stopGoalLoop) =>
+    set({
+      rootManagementPromptSessionId: sessionId,
+      rootManagementPromptOverrides: stagedOverrides ?? null,
+      rootManagementPromptStopGoalLoop: stopGoalLoop === true,
+    }, false, 'uiShell/openRootManagementPrompt'),
   closeRootManagementPrompt: () =>
-    set({ rootManagementPromptSessionId: null }, false, 'uiShell/closeRootManagementPrompt'),
+    set({
+      rootManagementPromptSessionId: null,
+      rootManagementPromptOverrides: null,
+      rootManagementPromptStopGoalLoop: false,
+    }, false, 'uiShell/closeRootManagementPrompt'),
 
   openDebugBundleNotePrompt: payload =>
     set({ debugBundleNotePrompt: payload }, false, 'uiShell/openDebugBundleNotePrompt'),
diff --git a/src/renderer/src/app-state/uiShell/types.ts b/src/renderer/src/app-state/uiShell/types.ts
index a02ffb89c..79fee2dac 100644
--- a/src/renderer/src/app-state/uiShell/types.ts
+++ b/src/renderer/src/app-state/uiShell/types.ts
@@ -1,5 +1,6 @@
 import type { PaletteMode } from '@renderer/features/command-palette/paletteMode'
 import type { TabId, SessionId } from '@renderer/workspace/types'
+import type { BuiltInMcpOverrides } from '@mcp/shared/types'
 import type { ExtensionListEntry } from '@shared/types/extensions'
 import type { ExtensionFailure } from '@renderer/apps/types'
 
@@ -82,6 +83,20 @@ export type UiShellState = {
    * pin session that the user later cancels with Escape. */
   pinAgentsOpen: boolean
   settingsPageOpen: boolean
+  /** Category the Settings page should show when opened (#1143: "MCP Servers"
+   * deep-links to Settings → MCP). A plain string, not SettingCategoryId, so
+   * this slice does not import the settings feature; SettingsPage validates
+   * it and falls back to "all". */
+  settingsPageCategory: string | null
+  /** Bumped on every openSettingsPage call, so a repeated deep link to the
+   * same category still wins over a sidebar click made in between. */
+  settingsPageRequest: number
+  /** Add/Edit MCP server dialog (#1143). One owner so the Settings grid and
+   * the "Add MCP Server…" command open the same dialog. */
+  mcpServerDialog: { mode: 'add' } | { mode: 'edit'; serverId: string } | null
+  /** Target of the per-agent "Agent MCP Servers…" modal, captured when the
+   * command runs so focus moving while it is open cannot retarget it. */
+  agentMcpServersSessionId: SessionId | null
   /**
    * The session captured when Set Title is invoked.
    *
@@ -98,6 +113,14 @@ export type UiShellState = {
    * by the time the user finishes reading the warning.
    */
   rootManagementPromptSessionId: SessionId | null
+  /** Other per-agent MCP choices staged in "Agent MCP Servers…" alongside a
+   * Root Management grant (#1143). The confirmation dialog applies them in the
+   * SAME reload, so granting root there does not silently discard the rest of
+   * the user's staged changes. Null for the plain root command. */
+  rootManagementPromptOverrides: BuiltInMcpOverrides | null
+  /** The staged choices also remove Goal Loop's tools: stop the running loop,
+   * but only once the confirmed reload actually runs (#1045 rule). */
+  rootManagementPromptStopGoalLoop: boolean
   debugBundleNotePrompt: {
     bundlePath: string
     sessionId: SessionId
diff --git a/src/renderer/src/app/App.tsx b/src/renderer/src/app/App.tsx
index 4b2c1ba0c..dd36a7573 100644
--- a/src/renderer/src/app/App.tsx
+++ b/src/renderer/src/app/App.tsx
@@ -30,6 +30,7 @@ import { SetupGate } from '@renderer/features/setup/ui/SetupGate'
 import { CliUpdateBanner } from '@renderer/features/cli-updates/CliUpdateBanner'
 import { useCliUpdateSync } from '@renderer/features/cli-updates/store'
 import { useProviderEnablementSync } from '@renderer/features/providers/store'
+import { useUserMcpSync } from '@renderer/features/mcp/store'
 
 // App — the composition root, and ONLY that (issue #494).
 //
@@ -85,6 +86,8 @@ export default function App() {
   // Provider enablement mirror: initial fetch + push subscription, same
   // mount-once contract as useCliUpdateSync above (#1102).
   useProviderEnablementSync()
+  // User MCP servers mirror (#1143): same mount-once contract.
+  useUserMcpSync()
   // Captures feed text selections for "Reply to Selection". Mounted here
   // for the same reason as the sync hooks above: `selectionchange` only
   // fires on `document`, so one listener serves every pane and Reader
diff --git a/src/renderer/src/app/surfaces/registry.tsx b/src/renderer/src/app/surfaces/registry.tsx
index 8206c94f1..f5c5e73a0 100644
--- a/src/renderer/src/app/surfaces/registry.tsx
+++ b/src/renderer/src/app/surfaces/registry.tsx
@@ -34,6 +34,8 @@ import { KeyVaultModalSurface } from '@renderer/features/key-vault/surfaces/KeyV
 import { NewAgentInSurface } from '@renderer/features/workspace/surfaces/NewAgentInSurface'
 import { TldrHistorySurface } from '@renderer/features/tldr/surfaces/TldrHistorySurface'
 import { AgentAnalyticsSurface } from '@renderer/features/agent-analytics/surfaces/AgentAnalyticsSurface'
+import { McpServerDialogSurface } from '@renderer/features/mcp/surfaces/McpServerDialogSurface'
+import { AgentMcpServersSurface } from '@renderer/features/mcp/surfaces/AgentMcpServersSurface'
 
 // The surface registry (issue #494). Adding a surface = write a wrapper
 // in the owning feature's surfaces/ folder + add ONE import + ONE array
@@ -108,6 +110,13 @@ export const modalSurfaces: SurfaceEntry[] = [
   // Appended per the contract above (#964). Opened only from a command that
   // closes the palette first, so it stacks over established modals by order.
   { id: 'agent-analytics', Component: AgentAnalyticsSurface },
+  // Appended per the contract above (#1143); both are opened from commands
+  // that close the palette first. The per-agent picker can hand off to the
+  // root-management confirmation (earlier in this array), but it closes itself
+  // before opening it, so the two are never on screen together and the order
+  // between them does not matter.
+  { id: 'agent-mcp-servers', Component: AgentMcpServersSurface },
+  { id: 'mcp-server-dialog', Component: McpServerDialogSurface },
   // Built-in apps host. Last in the array, which per the paint-order contract
   // above means it paints above every modal already mounted. That placement is
   // reasoned, not defaulted: an app is always user-initiated from the palette and
diff --git a/src/renderer/src/control/featureReference.ts b/src/renderer/src/control/featureReference.ts
index 2bc99e951..ce6f3f2b3 100644
--- a/src/renderer/src/control/featureReference.ts
+++ b/src/renderer/src/control/featureReference.ts
@@ -36,6 +36,7 @@ import { controlReference as performanceReference } from '@renderer/features/per
 import { controlReference as tldrReference } from '@renderer/features/tldr/controlReference'
 import { controlReference as goalLoopReference } from '@renderer/features/goal-loop/controlReference'
 import { controlReference as agentAnalyticsReference } from '@renderer/features/agent-analytics/controlReference'
+import { controlReference as mcpReference } from '@renderer/features/mcp/controlReference'
 
 export const featureReferences = [
   ...reference0,
@@ -74,6 +75,7 @@ export const featureReferences = [
   ...tldrReference,
   ...goalLoopReference,
   ...agentAnalyticsReference,
+  ...mcpReference,
 ]
 
 // These directories implement shared infrastructure rather than separate UI
@@ -96,6 +98,7 @@ export const referenceOwnership = {
   "workflows": "workflows",
   "usage": "usage",
   "providers": "providers",
+  "mcp": "mcp",
   "agent-analytics": "agent-analytics",
   "usage-limit": "usage",
   "rendered-content": "rendered-content",
diff --git a/src/renderer/src/features/command-palette/catalog.test.ts b/src/renderer/src/features/command-palette/catalog.test.ts
index 25885e83f..1f7d7ac68 100644
--- a/src/renderer/src/features/command-palette/catalog.test.ts
+++ b/src/renderer/src/features/command-palette/catalog.test.ts
@@ -112,8 +112,8 @@ const BASELINE_COMMAND_IDS: readonly string[] = [
   'create-ai-workspace',
   'clear-ai-workspace',
   'toggle-file-tree',
-  // sessionCommands (33)
-  'use-global-mcp-settings',
+  // sessionCommands (24): the nine per-capability MCP commands were retired
+  // into Agent MCP Servers… (#1143)
   'view-prompts',
   'rewind-to-prompt',
   'remove-cybersecurity-block',
@@ -126,15 +126,7 @@ const BASELINE_COMMAND_IDS: readonly string[] = [
   'switch-agents-provider',
   'search-conversation-prompts',
   'enable-built-in-mcp-ping',
-  'enable-ai-workspace-mcp',
-  'enable-orchestration-mcp',
-  'enable-agent-transcripts-mcp',
-  'enable-agent-management-mcp',
   'enable-root-agent-code-management',
-  'enable-tldr-mcp',
-  'enable-goal-mcp',
-  'enable-goal-loop-mcp',
-  'enable-workflow-mcp',
   'reload-agent',
   'soft-reload-agent',
   'set-agent-view-mode',
@@ -152,6 +144,10 @@ const BASELINE_COMMAND_IDS: readonly string[] = [
   'toggle-html-debug-panel',
   'clear-agent-composer',
   'toggle-dev-debug-panel',
+  // mcpCommands (3), registered right after the session commands (#1143)
+  'mcp-servers',
+  'add-mcp-server',
+  'agent-mcp-servers',
   // agentTitleCommands (1)
   'agent.title.set',
   // dispatchColorFlagCommands (1)
@@ -223,6 +219,17 @@ const RETIRED_COMMAND_IDS: readonly string[] = [
   'usage.toggle-header',
   'usage.cycle-header-level',
   'dangerous-agents',
+  // #1143: replaced by the staged Agent MCP Servers… picker, which carries
+  // the same choices through one reload instead of one reload per toggle.
+  'use-global-mcp-settings',
+  'enable-ai-workspace-mcp',
+  'enable-orchestration-mcp',
+  'enable-agent-transcripts-mcp',
+  'enable-agent-management-mcp',
+  'enable-tldr-mcp',
+  'enable-goal-mcp',
+  'enable-goal-loop-mcp',
+  'enable-workflow-mcp',
 ]
 
 /** The exact six-member Navigation Commands group (plan decision 6). Closed by
@@ -237,12 +244,12 @@ const NAVIGATION_COMMAND_GROUP: readonly string[] = [
 const ids = (): string[] => builtInCommandCatalog.map(c => c.id)
 
 describe('built-in command catalog — baseline characterization', () => {
-  it('contains exactly the 125 governed commands in registration order', () => {
+  it('contains exactly the 119 governed commands in registration order', () => {
     // Order matters: this is the palette's empty-query browse order.
     expect(ids()).toEqual([...BASELINE_COMMAND_IDS])
   })
 
-  it('has exactly 125 commands', () => {
+  it('has exactly 119 commands', () => {
     // Stated separately from the order assertion because this number is the
     // thing that moves, and a bare count failure is a clearer signal than a
     // 99-line array diff.
@@ -265,11 +272,13 @@ describe('built-in command catalog — baseline characterization', () => {
     // −attach×2, −detach → 115 with Clear Lane (#992 stage 4) → 119 with the
     // lane keyboard grammar (#992 stage 5) → 123 once main's Goal Loop preview
     // and stop (#1001) and the two generated Grok splits (#844) merged in → 124
-    // with Goal Loop MCP (#1006) → 125 with Open Setup (#995).
+    // with Goal Loop MCP (#1006) → 125 with Open Setup (#995) → 119 with the MCP
+    // servers interface (#1143): −9 per-capability MCP commands, +3 MCP
+    // commands.
     // Each step of that arithmetic was a deliberate edit to this line, which is the entire point of pinning it. (The two test
     // titles above had drifted to "115" while this line said 116; they now
     // track it again.)
-    expect(builtInCommandCatalog).toHaveLength(125)
+    expect(builtInCommandCatalog).toHaveLength(119)
   })
 
   it('reports no structural defects', () => {
@@ -303,15 +312,15 @@ describe('generated per-provider split commands', () => {
   })
 
   it('accounts for the difference between literal and total command count', () => {
-    // 125 total - 6 generated = 119 literal `id:` fields across the command
+    // 119 total - 6 generated = 113 literal `id:` fields across the command
     // modules. At the original baseline this read 102 - 4 = 98; it moved down by
     // the five retirements, then back up by the nine additions, Grid Dispatch's
     // six row commands, New Window, and the later additions recorded in the
     // count test above (through the lane keyboard grammar, #992 stage 5, and
-    // Goal Loop, #1001, Goal Loop MCP, #1006, and Open Setup, #995). Grok
-    // (#844) grew only the
-    // GENERATED term, 4 → 6.
-    expect(builtInCommandCatalog.length - nonDefaultProviders.length * 2).toBe(119)
+    // Goal Loop, #1001, Goal Loop MCP, #1006, and Open Setup, #995), then
+    // down by six with the MCP servers interface (#1143: −9 toggles, +3).
+    // Grok (#844) grew only the GENERATED term, 4 → 6.
+    expect(builtInCommandCatalog.length - nonDefaultProviders.length * 2).toBe(113)
   })
 
   it('emits both directions for every non-default provider', () => {
@@ -421,9 +430,10 @@ describe('governance targets', () => {
   })
 
   it('lands on the arithmetic the plan predicted', () => {
-    // 102 baseline - 21 retirements + 44 additions = 125, checked against the
+    // 102 baseline - 30 retirements + 47 additions = 119, checked against the
     // real catalog rather than trusted as prose. (5 governance retirements +
-    // 16 unified-layout retirements, all recorded in RETIRED_COMMAND_IDS.)
+    // 16 unified-layout retirements + 9 MCP retirements (#1143), all recorded
+    // in RETIRED_COMMAND_IDS.)
     //
     // The subtracted term is the count of APPROVED ADDITIONS and the expected
     // value is the pre-governance baseline — so growing the catalog means
@@ -452,9 +462,12 @@ describe('governance targets', () => {
     // (#1001), `grok-vertical` and `grok-horizontal` (#844, generated from
     // AGENT_PROVIDER_KINDS), `clear-focused-lane` (#992 stage 4), and the four
     // lane-grammar commands (#992 stage 5), `enable-goal-loop-mcp` (#1006)
-    // and `open-setup` (#995).
-    expect(builtInCommandCatalog.length + RETIRED_COMMAND_IDS.length - 44).toBe(102)
-    expect(builtInCommandCatalog).toHaveLength(125)
+    // and `open-setup` (#995), and `mcp-servers`, `add-mcp-server` and
+    // `agent-mcp-servers` (#1143). The nine commands #1143 retired are counted
+    // in RETIRED_COMMAND_IDS, which is why the additions they had once been
+    // counted as stay in this total.
+    expect(builtInCommandCatalog.length + RETIRED_COMMAND_IDS.length - 47).toBe(102)
+    expect(builtInCommandCatalog).toHaveLength(119)
   })
 })
 
diff --git a/src/renderer/src/features/command-palette/catalog.ts b/src/renderer/src/features/command-palette/catalog.ts
index d83f283a3..989de5f6a 100644
--- a/src/renderer/src/features/command-palette/catalog.ts
+++ b/src/renderer/src/features/command-palette/catalog.ts
@@ -3,6 +3,7 @@ import { goalLoopCommands } from '@renderer/features/goal-loop/commands'
 import { layoutCommands } from '@renderer/features/workspace/commands/layoutCommands'
 import { globalEditorCommands } from '@renderer/features/global-editor/commands/globalEditorCommands'
 import { paneCommands } from '@renderer/features/workspace/commands/paneCommands'
+import { mcpCommands } from '@renderer/features/mcp/commands/mcpCommands'
 import { sessionCommands } from '@renderer/features/workspace/commands/sessionCommands'
 import { tabCommands } from '@renderer/features/workspace/commands/tabCommands'
 import { windowCommands } from '@renderer/features/workspace/commands/windowCommands'
@@ -73,6 +74,9 @@ export const builtInCommandCatalog: readonly CommandDef[] = Object.freeze([
   // regressions to users who navigate by position.
   ...globalEditorCommands,
   ...sessionCommands,
+  // Right after the session commands, where the per-capability MCP toggles it
+  // replaced used to sit (#1143), so the MCP family keeps its browse position.
+  ...mcpCommands,
   ...agentTitleCommands,
   ...dispatchColorFlagCommands,
   ...spotlightCommands,
diff --git a/src/renderer/src/features/command-palette/taxonomy.test.ts b/src/renderer/src/features/command-palette/taxonomy.test.ts
index 01cffb821..c71ebfda6 100644
--- a/src/renderer/src/features/command-palette/taxonomy.test.ts
+++ b/src/renderer/src/features/command-palette/taxonomy.test.ts
@@ -107,12 +107,13 @@ describe('tier classification', () => {
       // attach-detached commands) were retired by the unified stage (#1013)
       // before this landed, so these nine are the survivors.
       //
-      // The operative rule is the owner's pick, not a class-wide claim about
-      // MCP toggles: `enable-orchestration-mcp` and `enable-workflow-mcp` were
-      // NOT in it and stay advanced (pinned four lines below).
+      // The per-capability MCP toggles in that pick were retired into the
+      // single Agent MCP Servers… picker (#1143), which inherits their default
+      // tier; the Settings shortcut and Add MCP Server… are default for the
+      // same reason.
       'toggle-tail-all', 'set-agent-view-mode', 'soft-reload-agent', 'switch-agents-provider',
-      'remove-cybersecurity-block', 'enable-agent-transcripts-mcp', 'enable-agent-management-mcp',
-      'enable-ai-workspace-mcp', 'enable-root-agent-code-management',
+      'remove-cybersecurity-block', 'enable-root-agent-code-management',
+      'agent-mcp-servers', 'mcp-servers', 'add-mcp-server',
     ]) {
       expect(byId(id).pickerVisibility ?? 'default').toBe('default')
     }
@@ -121,10 +122,12 @@ describe('tier classification', () => {
   it('marks niche supported operations advanced rather than hiding them entirely', () => {
     // `advanced` is not `debug`: these are supported operations a power user
     // wants, just not ones that should crowd a fuzzy search.
-    // These three used to be remove-cybersecurity-block, soft-reload-agent and
-    // switch-agents-provider, which B9 promoted (see above). The ones below
-    // were NOT in the owner's pick and stay advanced.
-    for (const id of ['undo-rewind', 'enable-orchestration-mcp', 'enable-workflow-mcp', 'toggle-tail-working']) {
+    // These used to include remove-cybersecurity-block, soft-reload-agent and
+    // switch-agents-provider, which B9 promoted (see above), and the
+    // Orchestration and Workflow MCP toggles, which #1143 retired into Agent
+    // MCP Servers…. The ones below were NOT in the owner's pick and stay
+    // advanced.
+    for (const id of ['undo-rewind', 'toggle-tail-working']) {
       expect(byId(id).pickerVisibility).toBe('advanced')
     }
   })
diff --git a/src/renderer/src/features/command-palette/types.ts b/src/renderer/src/features/command-palette/types.ts
index 5427a7e2f..ad9f7444d 100644
--- a/src/renderer/src/features/command-palette/types.ts
+++ b/src/renderer/src/features/command-palette/types.ts
@@ -199,7 +199,9 @@ export type CommandContext = {
     openReorderTabs: () => void
     /** Open the Merge Project Tabs modal (#913); the modal performs the merge. */
     openMergeProjectTabs: () => void
-    openSettings: () => void
+    /** Open Settings, optionally on one category (a SettingCategoryId; an
+     *  unknown id falls back to "all"). */
+    openSettings: (category?: string) => void
     /** Open the command palette. Exists so ⌘⇧P has a command to name instead
      *  of a hard-coded callback that nothing could rebind or collision-check. */
     openCommandPalette: () => void
@@ -229,6 +231,11 @@ export type CommandContext = {
     /** Open the Agent Analytics modal (#964); the modal fetches its own summary. */
     openAgentAnalytics: () => void
     openKeyVault: () => void
+    /** Open the Add MCP server dialog (#1143). */
+    openMcpServerDialog: () => void
+    /** Open "Agent MCP Servers…" for the captured command-target agent. The
+     *  modal stages choices and performs one reload on Apply. */
+    openAgentMcpServers: (sessionId: string) => void
     toggleGitBar: () => void
     toggleWorktreesBar: () => void
     toggleDebugPanel: () => void
diff --git a/src/renderer/src/features/command-palette/ui/CommandPalette.tsx b/src/renderer/src/features/command-palette/ui/CommandPalette.tsx
index 5f4b22adf..edf2d33f2 100644
--- a/src/renderer/src/features/command-palette/ui/CommandPalette.tsx
+++ b/src/renderer/src/features/command-palette/ui/CommandPalette.tsx
@@ -284,6 +284,8 @@ function OpenCommandPalette({
   const openAgentAnalytics = useAppStore(state => state.openAgentAnalytics)
   const openApp = useAppStore(state => state.openApp)
   const openKeyVault = useAppStore(state => state.openKeyVault)
+  const openMcpServerDialogState = useAppStore(state => state.openMcpServerDialog)
+  const openAgentMcpServers = useAppStore(state => state.openAgentMcpServers)
   const toggleGitBar = useAppStore(state => state.toggleGitBar)
   const toggleWorktreesBar = useAppStore(state => state.toggleWorktreesBar)
   const toggleDebugPanel = useAppStore(state => state.toggleDebugPanel)
@@ -547,6 +549,8 @@ function OpenCommandPalette({
         openUsageModal,
         openAgentAnalytics,
         openKeyVault,
+        openMcpServerDialog: () => openMcpServerDialogState({ mode: 'add' }),
+        openAgentMcpServers,
         toggleGitBar,
         toggleWorktreesBar,
         toggleDebugPanel,
@@ -665,6 +669,8 @@ function OpenCommandPalette({
       openAgentAnalytics,
       openApp,
       openKeyVault,
+      openMcpServerDialogState,
+      openAgentMcpServers,
       toggleGitBar,
       toggleWorktreesBar,
       toggleDebugPanel,
diff --git a/src/renderer/src/features/goal-loop/controlReference.ts b/src/renderer/src/features/goal-loop/controlReference.ts
index 80fd0217a..2d29aaa54 100644
--- a/src/renderer/src/features/goal-loop/controlReference.ts
+++ b/src/renderer/src/features/goal-loop/controlReference.ts
@@ -9,9 +9,9 @@ export const controlReference = [{
   title: 'Harness-owned goal loops',
   purpose: 'Keep an agent working toward a goal across turn boundaries until it reports the goal complete, without the user re-prompting.',
   ui: 'An always-on per-pane status strip while a loop exists, a latched Goal Loop overlay with pause, resume, raise-cap and stop controls (Close leaves it), Dismiss on an ended loop to clear its strip, and a Stop Goal Loop session command.',
-  prerequisites: 'Enable Goal Loop MCP for the agent that should run loops (off by default; per agent with the Goal Loop MCP command, or for all agents in Settings). The agent starts the loop itself with goal_loop_start when asked; users never write the continuation prompt.',
+  prerequisites: 'Turn Goal Loop on for the agent that should run loops (off by default; per agent in the Agent MCP Servers picker, or per provider in Settings → MCP). The agent starts the loop itself with goal_loop_start when asked; users never write the continuation prompt.',
   workflow: [
-    'Enable Goal Loop MCP for the agent; it reloads with the loop tools.',
+    'Turn Goal Loop on for the agent in Agent MCP Servers; it reloads with the loop tools.',
     'Ask the agent to run a loop on an outcome; it calls goal_loop_start with the goal and its own continuation prompt.',
     'Whenever the agent stops before completion, Agent Code re-prompts it with the next continuation, up to the budget (default 25).',
     'The strip above the pane shows state and budget; open the Goal Loop overlay for controls.',
@@ -19,5 +19,5 @@ export const controlReference = [{
   ],
   outcome: 'The pane strip reads e.g. “Goal loop · active · iteration 3/25 · <goal>” with Pause and Stop, and the latched overlay centers the full state with all controls.',
   cautions: 'Loops consume model calls on every continuation; the budget pauses rather than kills, and Raise cap re-arms it knowingly. A paused(loop) after a restart or provider switch stays paused until resumed. complete(done) is the agent\'s own claim of completion, not a verified fact; the summary states what it believes finished.',
-  commandIds: ['goal-loop-preview', 'goal-loop-stop', 'enable-goal-loop-mcp'],
+  commandIds: ['goal-loop-preview', 'goal-loop-stop', 'agent-mcp-servers'],
 }] satisfies FeatureReference[]
diff --git a/src/renderer/src/features/mcp/commands/mcpCommands.renderer.test.ts b/src/renderer/src/features/mcp/commands/mcpCommands.renderer.test.ts
new file mode 100644
index 000000000..5fd0a435e
--- /dev/null
+++ b/src/renderer/src/features/mcp/commands/mcpCommands.renderer.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { CommandContext } from '@renderer/features/command-palette/types'
+import { oneLaneStage } from '@renderer/workspace/testing/stageFixtures'
+import type { Workspace } from '@renderer/workspace/workspaceStore'
+
+import { mcpCommands } from './mcpCommands'
+
+function context(kind: string) {
+  const ui = { closePalette: vi.fn(), openAgentMcpServers: vi.fn(), openSettings: vi.fn(), openMcpServerDialog: vi.fn() }
+  const workspace = {
+    state: {
+      activeTabId: 'tab',
+      stage: oneLaneStage('pane'),
+      pinnedSessionIds: [],
+      tabs: [{ id: 'tab' }],
+      sessions: { pane: { cwd: '/p', kind, projectId: 'tab', joinedAt: 0 } },
+    },
+  } as unknown as Workspace
+  return { ctx: { workspace, ui, flags: {} } as unknown as CommandContext, ui }
+}
+
+const byId = (id: string) => {
+  const command = mcpCommands.find(candidate => candidate.id === id)
+  if (!command) throw new Error(`missing ${id}`)
+  return command
+}
+
+describe('MCP commands (#1143)', () => {
+  it('offers the per-agent picker for agents but not terminals', () => {
+    const command = byId('agent-mcp-servers')
+    expect(command.when?.(context('claude').ctx)).toBe(true)
+    expect(command.when?.(context('codex').ctx)).toBe(true)
+    expect(command.when?.(context('opencode').ctx)).toBe(true)
+    expect(command.when?.(context('terminal').ctx)).toBe(false)
+  })
+
+  it('captures the target agent when the command runs, not when Apply is pressed', () => {
+    const { ctx, ui } = context('codex')
+    void byId('agent-mcp-servers').run(ctx)
+    expect(ui.closePalette).toHaveBeenCalledOnce()
+    expect(ui.openAgentMcpServers).toHaveBeenCalledWith('pane')
+  })
+
+  it('refuses to open the picker for a terminal even when invoked outside the palette', () => {
+    const { ctx, ui } = context('terminal')
+    void byId('agent-mcp-servers').run(ctx)
+    expect(ui.openAgentMcpServers).not.toHaveBeenCalled()
+  })
+
+  it('deep-links MCP Servers to the MCP settings category', () => {
+    const { ctx, ui } = context('claude')
+    void byId('mcp-servers').run(ctx)
+    expect(ui.openSettings).toHaveBeenCalledWith('mcp')
+  })
+})
diff --git a/src/renderer/src/features/mcp/commands/mcpCommands.ts b/src/renderer/src/features/mcp/commands/mcpCommands.ts
new file mode 100644
index 000000000..6499ad9e2
--- /dev/null
+++ b/src/renderer/src/features/mcp/commands/mcpCommands.ts
@@ -0,0 +1,67 @@
+import type { CommandDef } from '@renderer/features/command-palette/types'
+import { commandTargetSessionId } from '@renderer/workspace/hook/selectors/commandTargetSessionId'
+import { DEFAULT_PROVIDER, isAgentProviderKind } from '@shared/types/providerKind'
+
+/**
+ * MCP server commands (#1143).
+ *
+ * WHY three commands and not one per server: the catalog is context-free (it
+ * cannot read stores at module scope; see catalog.ts), so it cannot generate a
+ * command per user-configured server. The per-agent picker and the Settings
+ * grid list the servers instead. These three replace the ten per-capability
+ * `Enable … MCP` toggles and `Use Global MCP Settings`, which each reloaded the
+ * agent on their own; see RETIRED_BUILT_IN_COMMAND_IDS.
+ */
+export const mcpCommands: CommandDef[] = [
+  {
+    id: 'mcp-servers',
+    category: 'preferences',
+    surface: 'app',
+    title: 'MCP Servers',
+    description:
+      '**What it does:** Opens **Settings → MCP**: Agent Code\'s own MCP servers and yours, with one column per provider.\n\n**Use when:** You want to add a server, turn one on or off everywhere, or choose which providers new agents get it on.\n\n**Notes:** Changes apply to new agents and to existing agents when they reload. Use **Agent MCP Servers…** for one agent.',
+    keywords: ['mcp', 'server', 'servers', 'tools', 'settings', 'beeper', 'install', 'enable', 'disable', 'tldr', 'goal', 'orchestration'],
+    run: ({ ui }) => {
+      ui.openSettings('mcp')
+    },
+  },
+  {
+    id: 'add-mcp-server',
+    category: 'preferences',
+    surface: 'app',
+    title: 'Add MCP Server…',
+    description:
+      '**What it does:** Adds an MCP server by pasting the config from its README.\n\n**Use when:** A server documents a Claude Code, Cursor, VS Code or generic `mcpServers` snippet — for example Beeper Desktop.\n\n**Notes:** Tokens in the snippet are stored as encrypted secrets, never in a config file.',
+    keywords: ['mcp', 'server', 'add', 'install', 'new', 'paste', 'config', 'beeper', 'stdio', 'http'],
+    run: ({ ui }) => {
+      ui.openMcpServerDialog()
+    },
+  },
+  {
+    id: 'agent-mcp-servers',
+    category: 'session',
+    surface: 'session',
+    title: 'Agent MCP Servers…',
+    description:
+      '**What it does:** Chooses which MCP servers the focused **agent** has — Agent Code\'s own and yours — then reloads it once.\n\n**Use when:** One agent should have a server the others do not, or should not have one they do.\n\n**Notes:** Resumes the same conversation. Reset returns the agent to Settings → MCP. Root Management still asks for confirmation.',
+    keywords: [
+      'mcp', 'server', 'servers', 'tools', 'agent', 'enable', 'disable', 'toggle', 'reload', 'override',
+      'global', 'reset', 'tldr', 'goal', 'loop', 'orchestration', 'ai workspace', 'transcripts',
+      'agent management', 'workflow', 'root',
+    ],
+    when: ({ workspace }) => {
+      const id = commandTargetSessionId(workspace)
+      const meta = id ? workspace.state.sessions[id] : null
+      return Boolean(meta && isAgentProviderKind(meta.kind ?? DEFAULT_PROVIDER))
+    },
+    run: ({ workspace, ui }) => {
+      // Captured now, not when the user presses Apply: Dispatch focus can move
+      // while the picker is open, and the reload must land on this agent.
+      const id = commandTargetSessionId(workspace)
+      const meta = id ? workspace.state.sessions[id] : null
+      if (!id || !meta || !isAgentProviderKind(meta.kind ?? DEFAULT_PROVIDER)) return
+      ui.closePalette()
+      ui.openAgentMcpServers(id)
+    },
+  },
+]
diff --git a/src/renderer/src/features/mcp/controlReference.ts b/src/renderer/src/features/mcp/controlReference.ts
new file mode 100644
index 000000000..4007bc01e
--- /dev/null
+++ b/src/renderer/src/features/mcp/controlReference.ts
@@ -0,0 +1,23 @@
+import type { FeatureReference } from '@control-sdk'
+
+// Keep purpose, UI routes and limitations beside this feature (#1143). The
+// assembled control reference adds current commands/bindings itself.
+export const controlReference = [
+  {
+    id: 'mcp',
+    title: 'MCP servers',
+    purpose:
+      'Choose which MCP servers agents get: Agent Code\'s built-in servers and user-added servers (stdio, HTTP or SSE), per provider and per agent.',
+    ui: 'Settings → MCP (one grid, a column per enabled provider), Add MCP Server… (paste a README config), and Agent MCP Servers… (the focused agent, applied with one reload). Agents with the MCP Servers built-in capability can manage the same list through mcp_servers_* tools; every such change raises a notice.',
+    prerequisites: 'None for built-in servers. A user server needs whatever its README describes, for example Beeper Desktop running with its MCP server enabled.',
+    workflow: [
+      'Add a server by pasting its mcpServers or VS Code snippet; values from env and headers become encrypted secrets',
+      'Tick the provider columns whose new agents should get it, or switch it off everywhere with its master switch',
+      'Use Agent MCP Servers… to add or remove servers for one agent; it reloads that agent once and resumes the same conversation',
+    ],
+    outcome: 'New agents, and existing agents on their next reload, launch with the chosen servers. Agent Code never writes the CLIs\' own config files.',
+    cautions:
+      'User servers reach Claude and Codex only; OpenCode and Grok get built-in servers only. Codex cannot use SSE servers, and a user server whose name is already in the user\'s Codex config.toml is skipped for Codex. A server that cannot attach (missing secret, invalid config, enterprise Claude MCP policy) is left out of that launch with a notice; the agent still starts. Secrets are passed to the MCP server through the agent process environment, so the agent\'s own tools can read them. Changes need an agent reload. OAuth servers sign in through each CLI (codex mcp login, Claude /mcp).',
+    commandIds: ['mcp-servers', 'add-mcp-server', 'agent-mcp-servers'],
+  },
+] satisfies FeatureReference[]
diff --git a/src/renderer/src/features/mcp/lib/builtInServers.ts b/src/renderer/src/features/mcp/lib/builtInServers.ts
new file mode 100644
index 000000000..c227af1e9
--- /dev/null
+++ b/src/renderer/src/features/mcp/lib/builtInServers.ts
@@ -0,0 +1,27 @@
+import type { ConfigurableBuiltInMcpDomain } from '@mcp/shared/types'
+
+/**
+ * Display metadata for Agent Code's own MCP capabilities in the MCP grid and
+ * the per-agent picker (#1143). The copy is carried over from the eight
+ * Settings rows and ten palette commands this interface replaced, so users
+ * who knew those descriptions find the same words.
+ *
+ * Order is the grid's row order: the everyday peeks first, then coordination,
+ * then the opt-in tools.
+ */
+export const BUILT_IN_MCP_SERVERS: readonly {
+  domain: ConfigurableBuiltInMcpDomain
+  title: string
+  description: string
+}[] = [
+  { domain: 'tldr', title: 'TLDR', description: 'Concise status summaries; hold Cmd+L to read them.' },
+  { domain: 'goal', title: 'Goal', description: 'What each agent\'s work is for; hold Cmd+G to see it.' },
+  { domain: 'goal_loop', title: 'Goal Loop', description: 'Harness-owned loops that re-prompt until the goal is done.' },
+  { domain: 'orchestration', title: 'Orchestration', description: 'Create and coordinate child agents.' },
+  { domain: 'agent_transcripts', title: 'Agent Transcripts', description: 'Bounded transcript file tools.' },
+  { domain: 'agent_management', title: 'Agent Management', description: 'Inspect project agents and send follow-ups.' },
+  { domain: 'ai_workspace', title: 'AI Workspace', description: 'Curate review workspaces across worktrees.' },
+  { domain: 'workflows', title: 'Workflows', description: 'Durable workflow tools. Claude has workflows natively.' },
+  // #1143: last because it manages the list this grid shows.
+  { domain: 'mcp_servers', title: 'MCP Servers', description: 'Let the agent add, change and remove your MCP servers.' },
+]
diff --git a/src/renderer/src/features/mcp/store.ts b/src/renderer/src/features/mcp/store.ts
new file mode 100644
index 000000000..69deedc53
--- /dev/null
+++ b/src/renderer/src/features/mcp/store.ts
@@ -0,0 +1,59 @@
+import { useEffect } from 'react'
+import { create } from 'zustand'
+
+import type { UserMcpMutationResult, UserMcpSnapshot } from '@shared/userMcp/types'
+
+type UserMcpState = {
+  snapshot: UserMcpSnapshot | null
+  setSnapshot: (snapshot: UserMcpSnapshot) => void
+}
+
+// Standalone, non-persisted mirror of main's user MCP document (#1143) — the
+// provider-enablement shape exactly. Main owns the servers and the secrets; a
+// persisted copy here would be a second truth that could drift, and it could
+// never hold the secrets anyway.
+export const useUserMcpStore = create<UserMcpState>(set => ({
+  snapshot: null,
+  setSnapshot: snapshot => set({ snapshot }),
+}))
+
+export function useUserMcpSnapshot(): UserMcpSnapshot | null {
+  return useUserMcpStore(state => state.snapshot)
+}
+
+/** Non-render read for commands and pickers. */
+export function userMcpSnapshot(): UserMcpSnapshot | null {
+  return useUserMcpStore.getState().snapshot
+}
+
+/**
+ * Apply a mutation result immediately. The same snapshot also arrives on the
+ * broadcast; applying it here keeps a switch from flickering back for one IPC
+ * hop. Returns the error message for a failed mutation so callers can show it.
+ */
+export function applyUserMcpResult(result: UserMcpMutationResult): string | null {
+  if (result.ok) {
+    useUserMcpStore.getState().setSnapshot(result.snapshot)
+    return null
+  }
+  return result.error
+}
+
+/** Initial fetch + push subscription. Mount ONCE at the app root, next to
+ * useProviderEnablementSync, for the same reason: a second mount would leak
+ * IPC listeners and double every change. */
+export function useUserMcpSync(): void {
+  useEffect(() => {
+    let cancelled = false
+    void window.api.userMcpGet().then(snapshot => {
+      if (!cancelled) useUserMcpStore.getState().setSnapshot(snapshot)
+    }).catch(() => {})
+    const unsub = window.api.onUserMcpChanged(snapshot => {
+      useUserMcpStore.getState().setSnapshot(snapshot)
+    })
+    return () => {
+      cancelled = true
+      unsub()
+    }
+  }, [])
+}
diff --git a/src/renderer/src/features/mcp/surfaces/AgentMcpServersSurface.tsx b/src/renderer/src/features/mcp/surfaces/AgentMcpServersSurface.tsx
new file mode 100644
index 000000000..b352d32f5
--- /dev/null
+++ b/src/renderer/src/features/mcp/surfaces/AgentMcpServersSurface.tsx
@@ -0,0 +1,10 @@
+import { useAppStore } from '@renderer/app-state/hooks'
+import { AgentMcpServersModal } from '@renderer/features/mcp/ui/AgentMcpServersModal'
+
+// Mounted only while open for the same reason as McpServerDialogSurface: a
+// staged draft belongs to one opening, for one captured agent.
+export function AgentMcpServersSurface() {
+  const sessionId = useAppStore(state => state.agentMcpServersSessionId)
+  if (!sessionId) return null
+  return <AgentMcpServersModal key={sessionId} />
+}
diff --git a/src/renderer/src/features/mcp/surfaces/McpServerDialogSurface.tsx b/src/renderer/src/features/mcp/surfaces/McpServerDialogSurface.tsx
new file mode 100644
index 000000000..de87d681e
--- /dev/null
+++ b/src/renderer/src/features/mcp/surfaces/McpServerDialogSurface.tsx
@@ -0,0 +1,10 @@
+import { useAppStore } from '@renderer/app-state/hooks'
+import { McpServerDialog } from '@renderer/features/mcp/ui/McpServerDialog'
+
+// Mounted only while open so each opening starts from a fresh draft; the
+// dialog's paste/import state must never leak from one "Add server" to the next.
+export function McpServerDialogSurface() {
+  const open = useAppStore(state => state.mcpServerDialog !== null)
+  if (!open) return null
+  return <McpServerDialog />
+}
diff --git a/src/renderer/src/features/mcp/ui/AgentMcpServersModal.renderer.test.tsx b/src/renderer/src/features/mcp/ui/AgentMcpServersModal.renderer.test.tsx
new file mode 100644
index 000000000..41cd85b5c
--- /dev/null
+++ b/src/renderer/src/features/mcp/ui/AgentMcpServersModal.renderer.test.tsx
@@ -0,0 +1,195 @@
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { uniformBuiltInMcpDefaults } from '@mcp/shared/types'
+import { useAppStore } from '@renderer/app-state/store'
+import { useUserMcpStore } from '@renderer/features/mcp/store'
+import { oneLaneStage } from '@renderer/workspace/testing/stageFixtures'
+import { WorkspaceProvider } from '@renderer/workspace/WorkspaceContext'
+import type { Workspace } from '@renderer/workspace/workspaceStore'
+import type { UserMcpServerView, UserMcpSnapshot } from '@shared/userMcp/types'
+
+import { AgentMcpServersModal } from './AgentMcpServersModal'
+
+// These pin the provider policy the retired per-capability commands used to
+// carry (#1143): the picker is now the only per-agent surface, so it is where
+// "Workflows is not offered to Claude" and "one change is one pinned reload"
+// must hold.
+
+const originalApp = useAppStore.getState()
+const originalMcp = useUserMcpStore.getState()
+
+const beeper: UserMcpServerView = {
+  id: 'srv-beeper',
+  name: 'beeper',
+  enabled: true,
+  providers: { claude: false, codex: true },
+  entry: { type: 'http', url: 'http://localhost:23373/v0/mcp' },
+  inputs: [],
+  transport: 'http',
+  summary: 'localhost:23373/v0/mcp',
+  secrets: {},
+  problems: [],
+  support: { claude: { ok: true }, codex: { ok: true } },
+}
+
+function snapshot(servers: UserMcpServerView[]): UserMcpSnapshot {
+  return { servers, native: [], claudeManagedPolicy: false }
+}
+
+function mount(kind: 'claude' | 'codex' | 'opencode', meta: Record<string, unknown> = {}) {
+  const replaceSession = vi.fn().mockResolvedValue('agent-2')
+  const workspace = {
+    state: {
+      activeTabId: 'tab',
+      stage: oneLaneStage('agent'),
+      pinnedSessionIds: [],
+      tabs: [{ id: 'tab' }],
+      sessions: {
+        agent: {
+          cwd: '/projects/mcp',
+          kind,
+          providerSessionId: 'provider-session',
+          projectId: 'tab',
+          joinedAt: 0,
+          builtInMcpDomains: ['tldr'],
+          builtInMcpOverrides: {},
+          ...meta,
+        },
+      },
+    },
+    replaceSession,
+    showPaneToast: vi.fn(),
+  } as unknown as Workspace
+  render(
+    <WorkspaceProvider workspace={workspace}>
+      <AgentMcpServersModal />
+    </WorkspaceProvider>,
+  )
+  return { replaceSession }
+}
+
+beforeEach(() => {
+  useAppStore.setState({
+    agentMcpServersSessionId: 'agent',
+    settings: { ...originalApp.settings, defaultBuiltInMcpDomains: uniformBuiltInMcpDefaults(['tldr']) },
+  })
+  useUserMcpStore.setState({ snapshot: snapshot([beeper]) })
+})
+
+afterEach(() => {
+  cleanup()
+  useAppStore.setState(originalApp, true)
+  useUserMcpStore.setState(originalMcp, true)
+})
+
+describe('Agent MCP Servers picker', () => {
+  it('offers Workflows to Codex and OpenCode but not Claude, which has workflows natively', () => {
+    mount('claude')
+    expect(screen.queryByRole('checkbox', { name: 'Workflows for this agent' })).toBeNull()
+    cleanup()
+    mount('codex')
+    expect(screen.getByRole('checkbox', { name: 'Workflows for this agent' })).toBeTruthy()
+    cleanup()
+    mount('opencode')
+    expect(screen.getByRole('checkbox', { name: 'Workflows for this agent' })).toBeTruthy()
+  })
+
+  it('offers Agent Management to every provider launcher', () => {
+    for (const kind of ['claude', 'codex', 'opencode'] as const) {
+      mount(kind)
+      expect(screen.getByRole('checkbox', { name: 'Agent Management for this agent' })).toBeTruthy()
+      cleanup()
+    }
+  })
+
+  it('applies several staged changes as ONE reload pinned to the captured agent', () => {
+    const { replaceSession } = mount('codex')
+    fireEvent.click(screen.getByRole('checkbox', { name: 'Agent Management for this agent' }))
+    fireEvent.click(screen.getByRole('checkbox', { name: 'TLDR for this agent' }))
+    fireEvent.click(screen.getByRole('checkbox', { name: 'beeper for this agent' }))
+    fireEvent.click(screen.getByRole('button', { name: 'Apply & reload agent' }))
+
+    expect(replaceSession).toHaveBeenCalledTimes(1)
+    expect(replaceSession).toHaveBeenCalledWith('/projects/mcp', {
+      kind: 'codex',
+      resumeSessionId: 'provider-session',
+      targetSessionId: 'agent',
+      builtInMcpOverrides: {
+        agent_management: true,
+        tldr: false,
+        // The user server rides the same override map under its namespaced key.
+        'user:srv-beeper': false,
+      },
+    })
+    expect(useAppStore.getState().agentMcpServersSessionId).toBeNull()
+  })
+
+  it('drops a choice that matches Settings so the agent keeps following Settings', () => {
+    const { replaceSession } = mount('codex', { builtInMcpOverrides: { tldr: false } })
+    // TLDR is on in Settings; turning it back on removes the explicit "off".
+    fireEvent.click(screen.getByRole('checkbox', { name: 'TLDR for this agent' }))
+    fireEvent.click(screen.getByRole('button', { name: 'Apply & reload agent' }))
+    expect(replaceSession.mock.calls[0]![1].builtInMcpOverrides).toEqual({})
+  })
+
+  it('routes a Root Management grant through its confirmation, carrying the other staged choices', () => {
+    const { replaceSession } = mount('claude')
+    fireEvent.click(screen.getByRole('checkbox', { name: 'Agent Management for this agent' }))
+    fireEvent.click(screen.getByRole('checkbox', { name: 'Root Management for this agent' }))
+    fireEvent.click(screen.getByRole('button', { name: 'Apply & reload agent' }))
+
+    expect(replaceSession).not.toHaveBeenCalled()
+    expect(useAppStore.getState().rootManagementPromptSessionId).toBe('agent')
+    expect(useAppStore.getState().rootManagementPromptOverrides).toEqual({ agent_management: true })
+  })
+
+  it('ends a running goal loop before a reload that removes its tools (#1045 review)', async () => {
+    const controlGoalLoop = vi.fn(async () => null)
+    Object.assign(window, { api: { ...window.api, controlGoalLoop } })
+    const { replaceSession } = mount('codex', { builtInMcpDomains: ['goal_loop'], builtInMcpOverrides: { goal_loop: true } })
+    fireEvent.click(screen.getByRole('checkbox', { name: 'Goal Loop for this agent' }))
+    fireEvent.click(screen.getByRole('button', { name: 'Apply & reload agent' }))
+    await waitFor(() => expect(replaceSession).toHaveBeenCalledTimes(1))
+    // Named by the session the loop is filed under, and before the reload.
+    expect(controlGoalLoop).toHaveBeenCalledWith({ sessionId: 'agent', action: 'stop' })
+    expect(controlGoalLoop.mock.invocationCallOrder[0]).toBeLessThan(replaceSession.mock.invocationCallOrder[0]!)
+  })
+
+  it('does not stop a goal loop before a Root grant is confirmed (review round 1)', () => {
+    // Cancelling the confirmation reloads nothing, so a loop stopped up front
+    // would be dead while the agent still has its tools. The stop is handed
+    // to the confirmation, which runs it only on the reload it performs.
+    const controlGoalLoop = vi.fn(async () => null)
+    Object.assign(window, { api: { ...window.api, controlGoalLoop } })
+    mount('codex', { builtInMcpDomains: ['goal_loop'], builtInMcpOverrides: { goal_loop: true } })
+    fireEvent.click(screen.getByRole('checkbox', { name: 'Goal Loop for this agent' }))
+    fireEvent.click(screen.getByRole('checkbox', { name: 'Root Management for this agent' }))
+    fireEvent.click(screen.getByRole('button', { name: 'Apply & reload agent' }))
+    expect(controlGoalLoop).not.toHaveBeenCalled()
+    expect(useAppStore.getState().rootManagementPromptStopGoalLoop).toBe(true)
+  })
+
+  it('leaves a running goal loop alone when its tools stay on', () => {
+    const controlGoalLoop = vi.fn(async () => null)
+    Object.assign(window, { api: { ...window.api, controlGoalLoop } })
+    mount('codex', { builtInMcpDomains: ['goal_loop', 'tldr'], builtInMcpOverrides: { goal_loop: true } })
+    fireEvent.click(screen.getByRole('checkbox', { name: 'TLDR for this agent' }))
+    fireEvent.click(screen.getByRole('button', { name: 'Apply & reload agent' }))
+    expect(controlGoalLoop).not.toHaveBeenCalled()
+  })
+
+  it('shows user servers as unavailable on providers that cannot receive them yet', () => {
+    mount('opencode')
+    const box = screen.getByRole('checkbox', { name: 'beeper for this agent' })
+    expect(box).toHaveProperty('disabled', true)
+    expect(screen.getByText('not supported yet')).toBeTruthy()
+  })
+
+  it('keeps a master-switched-off server off for this agent too', () => {
+    useUserMcpStore.setState({ snapshot: snapshot([{ ...beeper, enabled: false }]) })
+    mount('codex')
+    expect(screen.getByRole('checkbox', { name: 'beeper for this agent' })).toHaveProperty('disabled', true)
+    expect(screen.getByText('off in Settings → MCP')).toBeTruthy()
+  })
+})
diff --git a/src/renderer/src/features/mcp/ui/AgentMcpServersModal.tsx b/src/renderer/src/features/mcp/ui/AgentMcpServersModal.tsx
new file mode 100644
index 000000000..3ebc09312
--- /dev/null
+++ b/src/renderer/src/features/mcp/ui/AgentMcpServersModal.tsx
@@ -0,0 +1,261 @@
+import { useMemo, useState } from 'react'
+
+import {
+  providerSupportsBuiltInMcpDomain,
+  type BuiltInMcpDomain,
+  type BuiltInMcpOverrides,
+} from '@mcp/shared/types'
+import { getRendererProviderCapabilities } from '@providers/registry.renderer.capabilities'
+import { useAppStore } from '@renderer/app-state/hooks'
+import { Button } from '@renderer/components/ui/button'
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@renderer/components/ui/dialog'
+import { BUILT_IN_MCP_SERVERS } from '@renderer/features/mcp/lib/builtInServers'
+import { useUserMcpSnapshot } from '@renderer/features/mcp/store'
+import { Check } from '@renderer/features/mcp/ui/McpServersRow'
+import { ROOT_MANAGEMENT_DOMAIN } from '@renderer/features/workspace/lib/rootManagement'
+import { reloadSessionWithBuiltInMcpOverrides } from '@renderer/workspace/builtInMcpReload'
+import { resolveSessionBuiltInMcpDomains, sessionMcpOverrides } from '@renderer/workspace/mcpDomains'
+import { useWorkspaceContext } from '@renderer/workspace/WorkspaceContext'
+import { DEFAULT_PROVIDER, isAgentProviderKind } from '@shared/types/providerKind'
+import { isUserMcpProvider, userMcpOverrideKey, type UserMcpServerView } from '@shared/userMcp/types'
+
+type Row = {
+  key: BuiltInMcpDomain | `user:${string}`
+  title: string
+  detail: string
+  /** What the agent gets from Settings alone, before its own choice. */
+  inherited: boolean
+  /** Why this row cannot be turned on for this agent, if it cannot. */
+  blocked?: string
+  /** What the running process actually has (main-reported). */
+  attached: boolean
+  /** Set when the server cannot attach yet (missing secret, invalid config).
+   * A reload would not change anything, so it never counts as pending. */
+  problem?: boolean
+}
+
+/**
+ * "Agent MCP Servers…" (#1143, spec Revision 2 §5): every MCP server the
+ * focused agent could have — Agent Code's own and the user's — with the
+ * choices STAGED and applied in ONE reload.
+ *
+ * WHY staged: the MCP server list is fixed when a provider process launches,
+ * so every change is a reload. The ten per-capability commands this replaces
+ * each reloaded on their own, so turning three things on meant three reloads
+ * of a live conversation. Here the user edits a draft and pays one.
+ *
+ * Choices are written as explicit overrides into the pane's existing override
+ * map (user servers under `user:<id>` keys), through the one reload owner every
+ * capability change already uses (reloadSessionWithBuiltInMcpOverrides).
+ */
+export function AgentMcpServersModal() {
+  const workspace = useWorkspaceContext()
+  const sessionId = useAppStore(state => state.agentMcpServersSessionId)
+  const close = useAppStore(state => state.closeAgentMcpServers)
+  const openRootPrompt = useAppStore(state => state.openRootManagementPrompt)
+  const defaults = useAppStore(state => state.settings.defaultBuiltInMcpDomains)
+  const snapshot = useUserMcpSnapshot()
+  const meta = sessionId ? workspace.state.sessions[sessionId] ?? null : null
+  const kind = meta?.kind ?? DEFAULT_PROVIDER
+  const provider = isAgentProviderKind(kind) ? kind : null
+
+  const saved = useMemo(() => (meta ? sessionMcpOverrides(meta) : {}), [meta])
+  const [draft, setDraft] = useState<BuiltInMcpOverrides | null>(null)
+  const current = draft ?? saved
+
+  const rows = useMemo((): Row[] => {
+    if (!provider || !meta) return []
+    const inheritedDomains = resolveSessionBuiltInMcpDomains({ provider, sessionOverrides: {}, defaultDomains: defaults })
+    const builtIns: Row[] = BUILT_IN_MCP_SERVERS
+      .filter(server => providerSupportsBuiltInMcpDomain(provider, server.domain))
+      .map(server => ({
+        key: server.domain,
+        title: server.title,
+        detail: server.description,
+        inherited: inheritedDomains.includes(server.domain),
+        attached: Boolean(meta.builtInMcpDomains?.includes(server.domain)),
+      }))
+    const root: Row[] = providerSupportsBuiltInMcpDomain(provider, ROOT_MANAGEMENT_DOMAIN)
+      ? [{
+          key: ROOT_MANAGEMENT_DOMAIN,
+          title: 'Root Management',
+          detail: 'Application-wide control of Agent Code. Asks for confirmation.',
+          inherited: false,
+          attached: Boolean(meta.builtInMcpDomains?.includes(ROOT_MANAGEMENT_DOMAIN)),
+        }]
+      : []
+    const users: Row[] = (snapshot?.servers ?? []).map(server => userRow(server, provider, meta.userMcpServerIds ?? []))
+    return [...builtIns, ...root, ...users]
+  }, [defaults, meta, provider, snapshot])
+
+  if (!sessionId || !meta || !provider) {
+    return null
+  }
+
+  const effective = (row: Row) => current[row.key] ?? row.inherited
+  const changed = JSON.stringify(normalize(current)) !== JSON.stringify(normalize(saved))
+  // Built-in rows only. A user server can be requested and still not attach
+  // for launch-time reasons the renderer cannot see (a name in the project's
+  // own .codex/config.toml, a keyring hiccup): counting those would leave Apply
+  // permanently armed, and every Apply would reload the conversation for
+  // nothing and raise the same "wasn't attached" notice again.
+  const pendingReload = rows.some(row =>
+    !row.key.startsWith('user:') && !row.blocked && !row.problem && effective(row) !== row.attached)
+
+  const toggle = (row: Row) => {
+    const next = !effective(row)
+    const base = { ...current }
+    // An explicit choice that equals what Settings would give anyway is
+    // dropped rather than stored, so this agent keeps following Settings for
+    // that server — the difference between "on because I said so" and "on
+    // because it is the default" is exactly what the status column shows.
+    if (next === row.inherited && row.key !== ROOT_MANAGEMENT_DOMAIN) delete base[row.key]
+    else base[row.key] = next
+    setDraft(base)
+  }
+
+  const apply = async () => {
+    const overrides = { ...current }
+    const grantsRoot = overrides[ROOT_MANAGEMENT_DOMAIN] === true
+      && !meta.builtInMcpDomains?.includes(ROOT_MANAGEMENT_DOMAIN)
+    close()
+    setDraft(null)
+    // Removing Goal Loop's tools ENDS a running loop (#1045 review; this rule
+    // came with the retired Goal Loop MCP command). The loop is harness-owned
+    // and would survive the reload, but the reloaded agent could no longer
+    // call goal_loop_complete, so every continuation would run to the cap.
+    // Stopped BEFORE the reload so it names the session id the loop is filed
+    // under, not the replacement's. try/catch because a preload without the
+    // channel throws synchronously; the reload the user asked for still runs.
+    const goalLoopRow = rows.find(row => row.key === 'goal_loop')
+    const stopGoalLoop = Boolean(meta.builtInMcpDomains?.includes('goal_loop') && goalLoopRow && !effective(goalLoopRow))
+    if (grantsRoot) {
+      // The confirmation dialog owns every root grant (#906). It receives the
+      // rest of the draft so one confirmed reload applies everything — and the
+      // goal-loop stop, which must only happen if that reload really runs: a
+      // declined confirmation reloads nothing, so stopping here first would
+      // kill a loop whose tools the agent still has.
+      const { [ROOT_MANAGEMENT_DOMAIN]: _root, ...rest } = overrides
+      openRootPrompt(sessionId, rest, stopGoalLoop)
+      return
+    }
+    void reloadSessionWithBuiltInMcpOverrides(workspace, sessionId, overrides, {
+      reloaded: 'Reloaded with updated MCP servers',
+      failed: 'MCP reload failed',
+    }, stopGoalLoop ? stopGoalLoopFor(sessionId) : undefined)
+  }
+
+  const label = [meta.title, getRendererProviderCapabilities(provider).shortLabel].filter(Boolean).join(' · ')
+
+  return (
+    <Dialog open onOpenChange={open => { if (!open) { setDraft(null); close() } }}>
+      <DialogContent className="max-w-xl">
+        <DialogHeader>
+          <DialogTitle>Agent MCP servers</DialogTitle>
+          <DialogDescription>{label}</DialogDescription>
+        </DialogHeader>
+        <div className="flex max-h-[60vh] flex-col overflow-y-auto px-4 py-2 text-[11px]">
+          {rows.map(row => {
+            const on = effective(row)
+            const explicit = current[row.key] !== undefined
+            return (
+              <div key={row.key} className="flex items-center gap-3 border-b border-border/50 py-1.5 last:border-b-0">
+                <Check
+                  checked={on && !row.blocked}
+                  disabled={Boolean(row.blocked)}
+                  label={`${row.title} for this agent`}
+                  onChange={() => toggle(row)}
+                />
+                <div className="min-w-0 flex-1">
+                  <span className="text-ink">{row.title}</span>
+                  {row.key.startsWith('user:') ? null : (
+                    <span className="ml-2 rounded-chip border border-border px-1 text-[9px] text-muted">built-in</span>
+                  )}
+                  <div className="truncate text-[10px] text-muted">{row.detail}</div>
+                </div>
+                <span className="shrink-0 text-[10px] text-muted">
+                  {row.blocked
+                    ? row.blocked
+                    : explicit
+                      ? `● ${on ? 'on' : 'off'} for this agent`
+                      : 'default'}
+                  {/* User rows are not counted as "pending reload" (a launch
+                      can drop them for reasons the renderer cannot see), but
+                      the observed attach state is still shown so "on" is not
+                      mistaken for "attached" (review round 2). */}
+                  {row.key.startsWith('user:') && !row.blocked && on && !row.attached
+                    ? ' · not attached yet — reload'
+                    : ''}
+                </span>
+              </div>
+            )
+          })}
+          {rows.length === 0 ? <div className="py-2 text-muted">No MCP servers apply to this agent.</div> : null}
+        </div>
+        <DialogFooter>
+          <Button variant="ghost" onClick={() => setDraft({})} title="Clear this agent's choices so it follows Settings → MCP">
+            Reset to MCP settings
+          </Button>
+          <span className="flex-1 text-[10px] text-muted">
+            {changed ? 'Changes pending' : pendingReload ? 'Settings changed since this agent started' : ''}
+          </span>
+          <Button variant="outline" onClick={() => { setDraft(null); close() }}>Cancel</Button>
+          {/* Always enabled (review round 1): a user server turned on in
+              Settings after this agent started shows here as its default
+              "on", with nothing staged, and the agent only gets it on a
+              reload. The renderer cannot always know whether it is attached
+              (launch-time drops), so it must never be the one to refuse. */}
+          <Button onClick={() => void apply()}>{changed ? 'Apply & reload agent' : 'Reload agent'}</Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
+
+function userRow(server: UserMcpServerView, provider: string, attachedIds: readonly string[]): Row {
+  const key = userMcpOverrideKey(server.id)
+  const base = {
+    key,
+    title: server.name,
+    detail: server.summary,
+    attached: attachedIds.includes(server.id),
+  }
+  if (!isUserMcpProvider(provider)) return { ...base, inherited: false, blocked: 'not supported yet' }
+  if (!server.enabled) return { ...base, inherited: false, blocked: 'off in Settings → MCP' }
+  const support = server.support[provider]
+  if (!support.ok) return { ...base, inherited: false, blocked: support.reason }
+  // A structural problem or missing secret does not block the choice — the
+  // user may be about to fix it — but it is shown so "on" is not mistaken for
+  // "attached".
+  const problem = server.problems[0]
+  return {
+    ...base,
+    inherited: server.providers[provider],
+    ...(problem ? { detail: `⚠ ${problem.message}`, problem: true } : {}),
+  }
+}
+
+function normalize(overrides: BuiltInMcpOverrides): [string, boolean][] {
+  return Object.entries(overrides)
+    .filter((entry): entry is [string, boolean] => typeof entry[1] === 'boolean')
+    .sort(([a], [b]) => a.localeCompare(b))
+}
+
+/**
+ * Ends the agent's running goal loop (#1045 rule), handed to the reload so it
+ * runs only when the reload really goes ahead. try/catch because a preload
+ * without the channel throws synchronously; the reload the user asked for
+ * still happens.
+ */
+export function stopGoalLoopFor(sessionId: string): () => Promise<void> {
+  return async () => {
+    try { await window.api.controlGoalLoop({ sessionId, action: 'stop' }) } catch { /* reload anyway */ }
+  }
+}
diff --git a/src/renderer/src/features/mcp/ui/McpServerDialog.tsx b/src/renderer/src/features/mcp/ui/McpServerDialog.tsx
new file mode 100644
index 000000000..cc64d59dc
--- /dev/null
+++ b/src/renderer/src/features/mcp/ui/McpServerDialog.tsx
@@ -0,0 +1,562 @@
+import { useEffect, useMemo, useRef, useState } from 'react'
+
+import { useAppStore } from '@renderer/app-state/hooks'
+import { Button } from '@renderer/components/ui/button'
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from '@renderer/components/ui/dialog'
+import { Input } from '@renderer/components/ui/input'
+import { Textarea } from '@renderer/components/ui/textarea'
+import { applyUserMcpResult, useUserMcpSnapshot } from '@renderer/features/mcp/store'
+import { Check } from '@renderer/features/mcp/ui/McpServersRow'
+import type {
+  UserMcpImportCandidate,
+  UserMcpInput,
+  UserMcpProvider,
+  UserMcpServerEntry,
+  UserMcpServerView,
+} from '@shared/userMcp/types'
+import { USER_MCP_PROVIDERS } from '@shared/userMcp/types'
+import { providerSupportForEntry, transportOf, userMcpDestination } from '@shared/userMcp/validate'
+
+const PROVIDER_LABEL: Record<UserMcpProvider, string> = { claude: 'Claude', codex: 'Codex' }
+
+/**
+ * Add / Edit MCP server (#1143). Paste-first on purpose: "any MCP server"
+ * means any shape a README publishes, and a field-by-field form would either
+ * restrict that or grow a field for every transport option ever invented. The
+ * JSON the user edits IS the stored entry; secrets are the only thing pulled
+ * out, into masked fields, because they are the only thing that must never be
+ * written to disk in the clear.
+ *
+ * Validation is main's (UserMcpService.save / validateServer). The dialog only
+ * pre-parses JSON so a typo is flagged while typing instead of on Save.
+ */
+export function McpServerDialog() {
+  const target = useAppStore(state => state.mcpServerDialog)
+  const close = useAppStore(state => state.closeMcpServerDialog)
+  const snapshot = useUserMcpSnapshot()
+  const editing = target?.mode === 'edit'
+    ? snapshot?.servers.find(server => server.id === target.serverId) ?? null
+    : null
+
+  return (
+    <Dialog open={target !== null} onOpenChange={open => { if (!open) close() }}>
+      <DialogContent className="max-w-2xl">
+        {target?.mode === 'add' ? <AddServer onDone={close} /> : null}
+        {target?.mode === 'edit' && editing ? <EditServer key={editing.id} server={editing} onDone={close} /> : null}
+        {target?.mode === 'edit' && !editing ? (
+          <DialogHeader>
+            <DialogTitle>Server not found</DialogTitle>
+            <DialogDescription>It may have been deleted in another window.</DialogDescription>
+          </DialogHeader>
+        ) : null}
+      </DialogContent>
+    </Dialog>
+  )
+}
+
+type Draft = {
+  include: boolean
+  name: string
+  providers: Record<UserMcpProvider, boolean>
+  secrets: Record<string, string>
+}
+
+function AddServer({ onDone }: { onDone: () => void }) {
+  const [text, setText] = useState('')
+  const [candidates, setCandidates] = useState<UserMcpImportCandidate[]>([])
+  const [drafts, setDrafts] = useState<Draft[]>([])
+  const [parseError, setParseError] = useState<string | null>(null)
+  const [saveError, setSaveError] = useState<string | null>(null)
+  const [saving, setSaving] = useState(false)
+  // True from a keystroke until main answers for that text. Add is refused
+  // meanwhile so it can never save a parse of text the user already changed
+  // (review round 1: a token deleted from the box was still saved).
+  const [parsing, setParsing] = useState(false)
+  // Servers already saved in this dialog, keyed by the name the PARSE gave
+  // them. A multi-server paste is saved one server at a time; after a partial
+  // failure the retry must continue with the rest instead of re-adding the
+  // first one and failing as a duplicate. Keyed by parse name, not index
+  // (review round 2), so editing the paste box afterwards does not forget it.
+  const [savedKeys, setSavedKeys] = useState<ReadonlySet<string>>(new Set())
+  // The previous parse and the user's edits to it, read when a new parse
+  // lands so a re-parse refreshes the entries without discarding secrets,
+  // names or provider choices the user already typed (review round 2).
+  const previous = useRef<{ candidates: UserMcpImportCandidate[]; drafts: Draft[] }>({ candidates: [], drafts: [] })
+  previous.current = { candidates, drafts }
+  // The sanitized text we put in the box ourselves, which must not be
+  // re-imported (it no longer contains the lifted values).
+  const [sanitizedText, setSanitizedText] = useState<string | null>(null)
+
+  // Parsing runs in main (the same importer Copy in and tests use) so there is
+  // exactly one definition of what a pasted snippet means. Debounced because
+  // every keystroke would otherwise be an IPC round-trip. A bare entry is
+  // imported as "server" and renamed on its card: a separate name field that
+  // re-imported on every keystroke wiped secrets typed into the card.
+  useEffect(() => {
+    if (text === sanitizedText) {
+      // Back on our own sanitized snapshot (e.g. undo): the cards on screen
+      // are still the ones to save, and any in-flight parse was cancelled.
+      setParsing(false)
+      return
+    }
+    if (!text.trim()) {
+      setCandidates([])
+      setDrafts([])
+      setParseError(null)
+      setParsing(false)
+      return
+    }
+    setParsing(true)
+    let cancelled = false
+    const timer = setTimeout(() => {
+      window.api.userMcpImport(text).then(result => {
+        if (cancelled) return
+        setParsing(false)
+        if (!result.ok) {
+          setParseError(result.error)
+          setCandidates([])
+          setDrafts([])
+          return
+        }
+        setParseError(null)
+        const before = previous.current
+        setCandidates(result.candidates)
+        setDrafts(result.candidates.map(candidate => {
+          const support = providerSupportForEntry(candidate.entry)
+          const fresh: Draft = {
+            include: true,
+            name: candidate.name,
+            providers: { claude: support.claude.ok, codex: support.codex.ok },
+            secrets: { ...candidate.pendingSecrets },
+          }
+          const index = before.candidates.findIndex(old => old.name === candidate.name)
+          const old = index >= 0 ? before.drafts[index] : undefined
+          if (!old) return fresh
+          const stillReferenced = new Set(candidate.inputs.map(input => input.id))
+          return {
+            include: old.include,
+            name: old.name,
+            providers: {
+              claude: old.providers.claude && support.claude.ok,
+              codex: old.providers.codex && support.codex.ok,
+            },
+            // Values typed or lifted earlier survive for every secret the new
+            // parse still references; a value pasted literally again wins.
+            secrets: {
+              ...Object.fromEntries(Object.entries(old.secrets).filter(([id]) => stillReferenced.has(id))),
+              ...candidate.pendingSecrets,
+            },
+          }
+        }))
+        // Review round 1: once a value has been lifted into a masked secret
+        // field, the raw paste must not keep showing it. The box now shows
+        // what will be stored — references only.
+        if (result.candidates.some(candidate => Object.keys(candidate.pendingSecrets).length > 0)) {
+          const sanitized = JSON.stringify(
+            { mcpServers: Object.fromEntries(result.candidates.map(candidate => [candidate.name, candidate.entry])) },
+            null,
+            2,
+          )
+          setSanitizedText(sanitized)
+          setText(sanitized)
+        }
+      }).catch(error => {
+        if (cancelled) return
+        setParsing(false)
+        setParseError(error instanceof Error ? error.message : String(error))
+        setCandidates([])
+        setDrafts([])
+      })
+    }, 250)
+    return () => {
+      cancelled = true
+      clearTimeout(timer)
+    }
+  }, [text, sanitizedText])
+
+  const isSaved = (index: number) => savedKeys.has(candidates[index]?.name ?? '')
+  const pending = drafts.filter((draft, index) => draft.include && !isSaved(index)).length
+  const save = async () => {
+    if (parsing) return
+    setSaving(true)
+    setSaveError(null)
+    try {
+      for (const [index, candidate] of candidates.entries()) {
+        const draft = drafts[index]!
+        if (!draft.include || isSaved(index)) continue
+        const result = await window.api.userMcpSave({
+          name: draft.name,
+          enabled: true,
+          providers: draft.providers,
+          entry: candidate.entry,
+          inputs: candidate.inputs,
+          secrets: draft.secrets,
+        })
+        const error = applyUserMcpResult(result)
+        if (error) {
+          setSaveError(`${draft.name}: ${error}`)
+          return
+        }
+        setSavedKeys(current => new Set([...current, candidate.name]))
+      }
+      onDone()
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  return (
+    <>
+      <DialogHeader>
+        <DialogTitle>Add MCP server</DialogTitle>
+        <DialogDescription>
+          Paste the config from the server&apos;s README. mcpServers blocks, VS Code servers/inputs and single entries all work.
+        </DialogDescription>
+      </DialogHeader>
+      <div className="flex flex-col gap-3 px-4 py-3 text-[11px]">
+        <Textarea
+          autoFocus
+          value={text}
+          disabled={saving}
+          onChange={event => setText(event.target.value)}
+          spellCheck={false}
+          className="h-40 font-code text-[11px]"
+          placeholder={'{\n  "mcpServers": {\n    "beeper": { "url": "http://localhost:23373/v0/mcp" }\n  }\n}'}
+          aria-label="MCP server config"
+        />
+        {parseError ? <div className="text-danger">{parseError}</div> : null}
+        {candidates.map((candidate, index) => isSaved(index) ? (
+          <div key={`${candidate.name}:${index}`} className="rounded-slab border border-border px-3 py-2 text-muted">
+            ✓ {drafts[index]!.name} added
+          </div>
+        ) : (
+          <CandidateCard
+            key={`${candidate.name}:${index}`}
+            candidate={candidate}
+            draft={drafts[index]!}
+            multiple={candidates.length > 1}
+            onChange={draft => setDrafts(current => current.map((item, i) => i === index ? draft : item))}
+          />
+        ))}
+        {candidates.length > 0 ? (
+          <div className="text-[10px] text-muted">
+            Values from env and headers are stored as encrypted secrets, never in the config file. They reach the server through environment variables, not the command line.
+          </div>
+        ) : null}
+        {saveError ? <div className="text-danger">{saveError}</div> : null}
+      </div>
+      <DialogFooter>
+        <Button variant="outline" onClick={onDone}>Cancel</Button>
+        <Button disabled={saving || parsing || pending === 0} onClick={() => void save()}>
+          {pending > 1 ? `Add ${pending} servers` : 'Add server'}
+        </Button>
+      </DialogFooter>
+    </>
+  )
+}
+
+function CandidateCard({
+  candidate,
+  draft,
+  multiple,
+  onChange,
+}: {
+  candidate: UserMcpImportCandidate
+  draft: Draft
+  multiple: boolean
+  onChange: (draft: Draft) => void
+}) {
+  const transport = transportOf(candidate.entry)
+  const support = providerSupportForEntry(candidate.entry)
+  // Problems about the name are re-evaluated by main on save; the name field
+  // here is editable precisely so a reserved or duplicate name can be fixed.
+  const entryProblems = candidate.problems.filter(problem => !['invalid-name', 'reserved-name', 'duplicate-name'].includes(problem.kind))
+  return (
+    <div className="rounded-slab border border-border px-3 py-2">
+      <div className="flex items-center gap-2">
+        {multiple ? (
+          <Check checked={draft.include} label={`Add ${draft.name}`} onChange={include => onChange({ ...draft, include })} />
+        ) : null}
+        <Input value={draft.name} onChange={event => onChange({ ...draft, name: event.target.value })} className="h-7 w-48" aria-label="Server name" />
+        <span className="text-muted">{transport ?? 'unknown transport'}</span>
+        <span className="ml-auto flex items-center gap-3">
+          {USER_MCP_PROVIDERS.map(provider => (
+            <label key={provider} className="flex items-center gap-1" title={support[provider].ok ? undefined : support[provider].reason}>
+              <Check
+                checked={draft.providers[provider]}
+                disabled={!support[provider].ok}
+                label={`Attach to ${PROVIDER_LABEL[provider]}`}
+                onChange={on => onChange({ ...draft, providers: { ...draft.providers, [provider]: on } })}
+              />
+              {PROVIDER_LABEL[provider]}
+            </label>
+          ))}
+        </span>
+      </div>
+      {entryProblems.map(problem => <div key={problem.message} className="mt-1 text-warning">⚠ {problem.message}</div>)}
+      {candidate.inputs.length > 0 ? (
+        <SecretFields
+          inputs={candidate.inputs}
+          values={draft.secrets}
+          states={Object.fromEntries(candidate.inputs.map(input => [input.id, { set: draft.secrets[input.id] !== undefined }]))}
+          onChange={secrets => onChange({ ...draft, secrets })}
+        />
+      ) : null}
+    </div>
+  )
+}
+
+/** What another window or an agent could change under an open editor. */
+function editableFingerprint(server: UserMcpServerView): string {
+  return JSON.stringify([server.name, server.enabled, server.providers, server.entry, server.inputs])
+}
+
+function EditServer({ server, onDone }: { server: UserMcpServerView; onDone: () => void }) {
+  // Review round 1: the form is initialized once, but `server` keeps updating
+  // from the broadcast. Saving a form opened before another window (or an
+  // agent with MCP Servers) changed the same server would write the old entry
+  // back and prune any secret added since. The fingerprint at open time lets
+  // Save refuse instead.
+  const [openedAs] = useState(() => editableFingerprint(server))
+  const changedElsewhere = editableFingerprint(server) !== openedAs
+  const [name, setName] = useState(server.name)
+  const [json, setJson] = useState(() => JSON.stringify(server.entry, null, 2))
+  const [providers, setProviders] = useState(server.providers)
+  const [secretEdits, setSecretEdits] = useState<Record<string, string>>({})
+  const [error, setError] = useState<string | null>(null)
+  const [confirmDelete, setConfirmDelete] = useState(false)
+  const [saving, setSaving] = useState(false)
+
+  const parsed = useMemo((): { entry: UserMcpServerEntry | null; error: string | null } => {
+    try {
+      const value: unknown = JSON.parse(json)
+      if (!value || typeof value !== 'object' || Array.isArray(value)) return { entry: null, error: 'The config must be a JSON object.' }
+      return { entry: value as UserMcpServerEntry, error: null }
+    } catch (cause) {
+      return { entry: null, error: cause instanceof Error ? cause.message : String(cause) }
+    }
+  }, [json])
+
+  // Secret definitions follow the JSON: typing `${input:new-token}` into a
+  // header creates a field for it, and removing the last reference drops it
+  // (main prunes the orphaned blob on save). Existing descriptions are kept.
+  const inputs = useMemo((): UserMcpInput[] => {
+    const ids = [...new Set([...json.matchAll(/\$\{input:([A-Za-z0-9_-]{1,64})\}/g)].map(match => match[1]!))]
+    return ids.map(id => server.inputs.find(input => input.id === id) ?? { id, description: 'Secret' })
+  }, [json, server.inputs])
+
+  const transport = parsed.entry ? transportOf(parsed.entry) : null
+  const support = providerSupportForEntry(parsed.entry)
+  // Saving a changed destination forgets the stored secrets (service.save).
+  // Say so where the secrets are, and show them as not set, instead of a
+  // placeholder claiming they are (review round 2).
+  const destinationChanged = parsed.entry !== null && userMcpDestination(parsed.entry) !== userMcpDestination(server.entry)
+  const secretStates = destinationChanged
+    ? Object.fromEntries(inputs.map(input => [input.id, { set: false }]))
+    : server.secrets
+
+  const save = async () => {
+    if (!parsed.entry || changedElsewhere) return
+    setSaving(true)
+    setError(null)
+    try {
+      const result = await window.api.userMcpSave({
+        id: server.id,
+        name,
+        enabled: server.enabled,
+        providers: {
+          claude: providers.claude && support.claude.ok,
+          codex: providers.codex && support.codex.ok,
+        },
+        entry: parsed.entry,
+        inputs,
+        secrets: secretEdits,
+      })
+      const failure = applyUserMcpResult(result)
+      if (failure) setError(failure)
+      else onDone()
+    } finally {
+      setSaving(false)
+    }
+  }
+
+  const remove = async () => {
+    const failure = applyUserMcpResult(await window.api.userMcpDelete(server.id))
+    if (failure) setError(failure)
+    else onDone()
+  }
+
+  return (
+    <>
+      <DialogHeader>
+        <DialogTitle>Edit MCP server</DialogTitle>
+        <DialogDescription>Changes apply to new agents, and to existing agents when they reload.</DialogDescription>
+      </DialogHeader>
+      <div className="flex flex-col gap-3 px-4 py-3 text-[11px]">
+        <div className="flex items-center gap-3">
+          <label className="flex items-center gap-2">
+            <span className="text-muted">Name</span>
+            <Input value={name} onChange={event => setName(event.target.value)} className="h-7 w-48" />
+          </label>
+          <span className="text-muted">Transport: {transport ?? '—'}</span>
+          <span className="ml-auto flex items-center gap-3">
+            {USER_MCP_PROVIDERS.map(provider => (
+              <label key={provider} className="flex items-center gap-1" title={support[provider].ok ? undefined : support[provider].reason}>
+                <Check
+                  checked={providers[provider] && support[provider].ok}
+                  disabled={!support[provider].ok}
+                  label={`Attach to ${PROVIDER_LABEL[provider]}`}
+                  onChange={on => setProviders(current => ({ ...current, [provider]: on }))}
+                />
+                {PROVIDER_LABEL[provider]}
+              </label>
+            ))}
+          </span>
+        </div>
+        <Textarea
+          value={json}
+          onChange={event => setJson(event.target.value)}
+          spellCheck={false}
+          className="h-44 font-code text-[11px]"
+          aria-label="Server config"
+        />
+        {parsed.error ? <div className="text-danger">{parsed.error}</div> : null}
+        {inputs.length > 0 ? (
+          <SecretFields
+            inputs={inputs}
+            values={secretEdits}
+            states={secretStates}
+            onChange={setSecretEdits}
+          />
+        ) : null}
+        {destinationChanged && inputs.length > 0 ? (
+          <div className="text-warning">
+            This changes where the server connects, so its stored secrets will be forgotten. Re-enter them above to keep them.
+          </div>
+        ) : null}
+        {server.transport === 'http' || server.transport === 'sse'
+          ? <SignInHelp name={server.name} url={String((server.entry as { url?: unknown }).url ?? '')} />
+          : null}
+        {error ? <div className="text-danger">{error}</div> : null}
+        {changedElsewhere ? (
+          <div className="text-warning">
+            This server was changed in another window or by an agent. Close and reopen it to edit the current version.
+          </div>
+        ) : null}
+
+      </div>
+      <DialogFooter>
+        {confirmDelete ? (
+          <Button variant="destructive" onClick={() => void remove()}>Delete {server.name}</Button>
+        ) : (
+          <Button variant="destructive-outline" onClick={() => setConfirmDelete(true)}>Delete…</Button>
+        )}
+        <span className="flex-1" />
+        <Button variant="outline" onClick={onDone}>Cancel</Button>
+        <Button disabled={saving || !parsed.entry || changedElsewhere} onClick={() => void save()}>Save</Button>
+      </DialogFooter>
+    </>
+  )
+}
+
+function SecretFields({
+  inputs,
+  values,
+  states,
+  onChange,
+}: {
+  inputs: UserMcpInput[]
+  values: Record<string, string>
+  states: Record<string, { set: boolean; hint?: string }>
+  onChange: (values: Record<string, string>) => void
+}) {
+  return (
+    <div className="mt-2 flex flex-col gap-1.5">
+      <div className="text-[10px] uppercase tracking-wider text-muted">Secrets</div>
+      {inputs.map(input => {
+        const state = states[input.id]
+        const edited = values[input.id]
+        const placeholder = edited === ''
+          ? 'cleared on save'
+          : state?.set
+          ? `set${state.hint ? ` (…${state.hint})` : ''} — type to replace`
+          : 'not set'
+        return (
+          <label key={input.id} className="flex items-center gap-2">
+            <span className="w-48 shrink-0 truncate font-code text-[10px] text-ink" title={input.description}>{input.id}</span>
+            <Input
+              type="password"
+              autoComplete="off"
+              value={edited ?? ''}
+              placeholder={placeholder}
+              onChange={event => {
+                // An emptied field means "leave it as it was", never "delete"
+                // (review round 1): typing then backspacing looked untouched
+                // but sent '' and erased the stored secret. Only Clear deletes.
+                const next = { ...values }
+                if (event.target.value === '') delete next[input.id]
+                else next[input.id] = event.target.value
+                onChange(next)
+              }}
+              className="h-7 flex-1"
+              aria-label={`Secret ${input.id}`}
+            />
+            {state?.set && edited === undefined ? (
+              <Button size="xs" variant="ghost" onClick={() => onChange({ ...values, [input.id]: '' })}>Clear</Button>
+            ) : null}
+            {edited === '' ? <span className="text-[10px] text-warning">will be cleared</span> : null}
+          </label>
+        )
+      })}
+    </div>
+  )
+}
+
+/**
+ * OAuth stays with each CLI (spec Decisions: "OAuth delegated"). Both store
+ * tokens in the OS keychain keyed on a server identity our launch keeps stable,
+ * so a login done here is reused by every later agent. We show the exact
+ * commands rather than running them: login opens a browser and waits on the
+ * user, which belongs in a terminal the user controls.
+ */
+function SignInHelp({ name, url }: { name: string; url: string }) {
+  // Built from the SAVED server (not the fields being edited) and every
+  // interpolated piece single-quoted for the shell (review round 1): a URL may
+  // legally contain `'`, and an unquoted piece would run `$(…)` when the user
+  // pastes the command. Names are already restricted to [A-Za-z0-9_-].
+  const codexCommand = ['codex', 'mcp', 'login', name, '-c', `mcp_servers.${name}.url=${JSON.stringify(url)}`]
+    .map(shellQuote)
+    .join(' ')
+  const [copied, setCopied] = useState(false)
+  return (
+    <div className="rounded-slab border border-border px-3 py-2 text-[10px] text-muted">
+      <div className="mb-1 uppercase tracking-wider">Sign in (OAuth servers)</div>
+      <div>Servers that use OAuth instead of a token sign in through each CLI. This uses the SAVED name and URL — save your changes first:</div>
+      <div className="mt-1 flex items-center gap-2">
+        <span className="shrink-0">Codex:</span>
+        <code className="min-w-0 flex-1 break-all font-code text-ink">{codexCommand}</code>
+        <Button
+          size="xs"
+          variant="outline"
+          onClick={() => {
+            void navigator.clipboard.writeText(codexCommand).then(() => setCopied(true))
+          }}
+        >
+          {copied ? 'Copied' : 'Copy'}
+        </Button>
+      </div>
+      <div className="mt-1">Claude: run <code className="font-code text-ink">/mcp</code> in an agent that has {name} attached, then choose Authenticate.</div>
+    </div>
+  )
+}
+
+function shellQuote(value: string): string {
+  return /^[A-Za-z0-9_./:=-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`
+}
diff --git a/src/renderer/src/features/mcp/ui/McpServersRow.renderer.test.tsx b/src/renderer/src/features/mcp/ui/McpServersRow.renderer.test.tsx
new file mode 100644
index 000000000..7a0c92eb5
--- /dev/null
+++ b/src/renderer/src/features/mcp/ui/McpServersRow.renderer.test.tsx
@@ -0,0 +1,219 @@
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { uniformBuiltInMcpDefaults } from '@mcp/shared/types'
+import { DEFAULT_SETTINGS } from '@renderer/app-state/settings/types'
+import { useUserMcpStore } from '@renderer/features/mcp/store'
+import { useProviderEnablementStore } from '@renderer/features/providers/store'
+import type { ProviderEnablementSnapshot } from '@shared/types/providerEnablement'
+import type { UserMcpServerView } from '@shared/userMcp/types'
+
+import { McpServerDialog } from './McpServerDialog'
+import { McpServersRow } from './McpServersRow'
+import { useAppStore } from '@renderer/app-state/store'
+
+const originalMcp = useUserMcpStore.getState()
+const originalProviders = useProviderEnablementStore.getState()
+const originalApp = useAppStore.getState()
+
+const TOKEN = 'bpr_live_9f3a1c7d'
+
+function server(overrides: Partial<UserMcpServerView> = {}): UserMcpServerView {
+  return {
+    id: 'srv-beeper',
+    name: 'beeper',
+    enabled: true,
+    providers: { claude: true, codex: false },
+    entry: { type: 'http', url: 'http://localhost:23373/v0/mcp', headers: { Authorization: 'Bearer ${input:beeper-authorization}' } },
+    inputs: [{ id: 'beeper-authorization', description: 'Header Authorization' }],
+    transport: 'http',
+    summary: 'localhost:23373/v0/mcp',
+    secrets: { 'beeper-authorization': { set: true, hint: '1c7d' } },
+    problems: [],
+    support: { claude: { ok: true }, codex: { ok: true } },
+    ...overrides,
+  }
+}
+
+function enable(kinds: string[]) {
+  const snapshot = {
+    entries: ['claude', 'codex', 'opencode', 'grok'].map(kind => ({ kind, enabled: kinds.includes(kind), installed: true, because: 'detected' })),
+  } as unknown as ProviderEnablementSnapshot
+  useProviderEnablementStore.getState().setSnapshot(snapshot)
+}
+
+const api = {
+  userMcpSetProvider: vi.fn(async () => ({ ok: false, error: 'not in this test' })),
+  userMcpSetEnabled: vi.fn(async () => ({ ok: false, error: 'not in this test' })),
+  userMcpImport: vi.fn(),
+  userMcpSave: vi.fn(),
+  userMcpDelete: vi.fn(),
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  Object.assign(window, { api: { ...window.api, ...api } })
+  useUserMcpStore.setState({ snapshot: { servers: [server()], native: [], claudeManagedPolicy: false } })
+  enable(['claude', 'codex'])
+})
+
+afterEach(() => {
+  vi.useRealTimers()
+  cleanup()
+  useUserMcpStore.setState(originalMcp, true)
+  useProviderEnablementStore.setState(originalProviders, true)
+  useAppStore.setState(originalApp, true)
+})
+
+describe('Settings → MCP grid', () => {
+  it('shows a column only for providers enabled in Settings → Providers', () => {
+    render(<McpServersRow settings={DEFAULT_SETTINGS} onChange={vi.fn()} />)
+    expect(screen.getByRole('checkbox', { name: 'beeper for new Claude agents' })).toBeTruthy()
+    expect(screen.queryByRole('checkbox', { name: /for new Grok agents/ })).toBeNull()
+  })
+
+  it('writes a built-in default for ONE provider without touching the others', () => {
+    const onChange = vi.fn()
+    const settings = { ...DEFAULT_SETTINGS, defaultBuiltInMcpDomains: uniformBuiltInMcpDefaults(['tldr']) }
+    render(<McpServersRow settings={settings} onChange={onChange} />)
+    fireEvent.click(screen.getByRole('checkbox', { name: 'Orchestration for new Codex agents' }))
+    const next = onChange.mock.calls[0]![0].defaultBuiltInMcpDomains
+    expect(next.codex).toEqual(['tldr', 'orchestration'])
+    expect(next.claude).toEqual(['tldr'])
+  })
+
+  it('does not offer Workflows as a Claude default, because Claude has workflows natively', () => {
+    render(<McpServersRow settings={DEFAULT_SETTINGS} onChange={vi.fn()} />)
+    expect(screen.queryByRole('checkbox', { name: 'Workflows for new Claude agents' })).toBeNull()
+    expect(screen.getByRole('checkbox', { name: 'Workflows for new Codex agents' })).toBeTruthy()
+  })
+
+  it('shows an SSE server as Claude-only, with the reason, instead of a Codex checkbox', () => {
+    useUserMcpStore.setState({
+      snapshot: {
+        servers: [server({ name: 'linear', transport: 'sse', support: { claude: { ok: true }, codex: { ok: false, reason: 'Codex does not support SSE servers' } } })],
+        native: [],
+        claudeManagedPolicy: false,
+      },
+    })
+    render(<McpServersRow settings={DEFAULT_SETTINGS} onChange={vi.fn()} />)
+    expect(screen.queryByRole('checkbox', { name: 'linear for new Codex agents' })).toBeNull()
+    expect(screen.getByLabelText('Codex does not support SSE servers')).toBeTruthy()
+  })
+
+  it('writes a user-server provider choice to main, not to renderer Settings', () => {
+    const onChange = vi.fn()
+    render(<McpServersRow settings={DEFAULT_SETTINGS} onChange={onChange} />)
+    fireEvent.click(screen.getByRole('checkbox', { name: 'beeper for new Codex agents' }))
+    expect(api.userMcpSetProvider).toHaveBeenCalledWith('srv-beeper', 'codex', true)
+    expect(onChange).not.toHaveBeenCalled()
+  })
+})
+
+describe('MCP server dialog', () => {
+  it('never renders a stored secret, only its hint', () => {
+    useAppStore.setState({ mcpServerDialog: { mode: 'edit', serverId: 'srv-beeper' } })
+    render(<McpServerDialog />)
+    const field = screen.getByLabelText('Secret beeper-authorization')
+    expect((field as HTMLInputElement).value).toBe('')
+    expect(field.getAttribute('placeholder')).toContain('1c7d')
+    expect(document.body.textContent).not.toContain(TOKEN)
+  })
+
+  it('does not clear a stored secret when its field is typed in and emptied again (review round 1)', async () => {
+    api.userMcpSave.mockResolvedValue({ ok: true, snapshot: { servers: [server()], native: [], claudeManagedPolicy: false } })
+    useAppStore.setState({ mcpServerDialog: { mode: 'edit', serverId: 'srv-beeper' } })
+    render(<McpServerDialog />)
+    const field = screen.getByLabelText('Secret beeper-authorization')
+    fireEvent.change(field, { target: { value: 'x' } })
+    fireEvent.change(field, { target: { value: '' } })
+    fireEvent.click(screen.getByRole('button', { name: 'Save' }))
+    await vi.waitFor(() => expect(api.userMcpSave).toHaveBeenCalledTimes(1))
+    expect(api.userMcpSave.mock.calls[0]![0].secrets).toEqual({})
+  })
+
+  it('refuses to save over a server that changed elsewhere while the editor was open (review round 1)', () => {
+    useAppStore.setState({ mcpServerDialog: { mode: 'edit', serverId: 'srv-beeper' } })
+    render(<McpServerDialog />)
+    act(() => {
+      useUserMcpStore.setState({ snapshot: { servers: [server({ providers: { claude: true, codex: true } })], native: [], claudeManagedPolicy: false } })
+    })
+    expect(screen.getByRole('button', { name: 'Save' })).toHaveProperty('disabled', true)
+    expect(screen.getByText(/changed in another window or by an agent/)).toBeTruthy()
+  })
+
+  it('shell-quotes the Codex sign-in command so a quote in the URL cannot run code (review round 1)', () => {
+    useUserMcpStore.setState({ snapshot: { servers: [server({ entry: { type: 'http', url: "https://x.dev/mcp?a='$(echo PWNED)'" } })], native: [], claudeManagedPolicy: false } })
+    useAppStore.setState({ mcpServerDialog: { mode: 'edit', serverId: 'srv-beeper' } })
+    render(<McpServerDialog />)
+    const command = document.body.textContent ?? ''
+    expect(command).toContain(`codex mcp login beeper -c 'mcp_servers.beeper.url="https://x.dev/mcp?a='\\''$(echo PWNED)'\\''"'`)
+  })
+
+  it('warns that changing where a server connects forgets its secrets (review round 2)', () => {
+    useAppStore.setState({ mcpServerDialog: { mode: 'edit', serverId: 'srv-beeper' } })
+    render(<McpServerDialog />)
+    const config = screen.getByLabelText('Server config') as HTMLTextAreaElement
+    fireEvent.change(config, { target: { value: config.value.replace('23373', '23374') } })
+    expect(screen.getByText(/stored secrets will be forgotten/)).toBeTruthy()
+    // The field no longer claims the secret is set.
+    expect(screen.getByLabelText('Secret beeper-authorization').getAttribute('placeholder')).toBe('not set')
+  })
+
+  it('keeps a lifted token when the sanitized paste is edited and re-parsed (review round 2)', async () => {
+    const entry = { type: 'http', url: 'http://localhost:23373/v0/mcp', headers: { Authorization: 'Bearer ${input:beeper-authorization}' } }
+    api.userMcpImport
+      .mockResolvedValueOnce({ ok: true, format: 'mcpServers', candidates: [{ name: 'beeper', entry, inputs: [{ id: 'beeper-authorization', description: '' }], pendingSecrets: { 'beeper-authorization': TOKEN }, problems: [] }] })
+      .mockResolvedValueOnce({ ok: true, format: 'mcpServers', candidates: [{ name: 'beeper', entry: { ...entry, url: 'http://localhost:23374/v0/mcp' }, inputs: [{ id: 'beeper-authorization', description: 'Secret' }], pendingSecrets: {}, problems: [] }] })
+    api.userMcpSave.mockResolvedValue({ ok: true, snapshot: { servers: [], native: [], claudeManagedPolicy: false } })
+    useAppStore.setState({ mcpServerDialog: { mode: 'add' } })
+    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] })
+    render(<McpServerDialog />)
+    const box = screen.getByLabelText('MCP server config') as HTMLTextAreaElement
+    fireEvent.change(box, { target: { value: '{"mcpServers":{}}' } })
+    await act(async () => { await vi.advanceTimersByTimeAsync(300) })
+    fireEvent.change(box, { target: { value: box.value.replace('23373', '23374') } })
+    await act(async () => { await vi.advanceTimersByTimeAsync(300) })
+    vi.useRealTimers()
+    fireEvent.click(screen.getByRole('button', { name: 'Add server' }))
+    await vi.waitFor(() => expect(api.userMcpSave).toHaveBeenCalledTimes(1))
+    expect(api.userMcpSave.mock.calls[0]![0].secrets).toEqual({ 'beeper-authorization': TOKEN })
+  })
+
+  it('adds every server found in a pasted snippet, with its lifted secrets', async () => {
+    api.userMcpImport.mockResolvedValue({
+      ok: true,
+      format: 'mcpServers',
+      candidates: [{
+        name: 'beeper',
+        entry: { type: 'http', url: 'http://localhost:23373/v0/mcp', headers: { Authorization: 'Bearer ${input:beeper-authorization}' } },
+        inputs: [{ id: 'beeper-authorization', description: 'Header Authorization' }],
+        pendingSecrets: { 'beeper-authorization': TOKEN },
+        problems: [],
+      }],
+    })
+    api.userMcpSave.mockResolvedValue({ ok: true, snapshot: { servers: [], native: [], claudeManagedPolicy: false } })
+    useAppStore.setState({ mcpServerDialog: { mode: 'add' } })
+    // The paste box debounces before asking main to parse. Driving that timer
+    // explicitly keeps the test deterministic under load instead of racing a
+    // real 250 ms timer against findBy's polling budget.
+    vi.useFakeTimers({ toFake: ['setTimeout', 'clearTimeout'] })
+    render(<McpServerDialog />)
+    fireEvent.change(screen.getByLabelText('MCP server config'), { target: { value: '{"mcpServers":{}}' } })
+    await act(async () => { await vi.advanceTimersByTimeAsync(300) })
+    vi.useRealTimers()
+    const card = screen.getByLabelText('Server name')
+    expect((card as HTMLInputElement).value).toBe('beeper')
+    // The lifted token no longer shows in the paste box (review round 1).
+    expect((screen.getByLabelText('MCP server config') as HTMLTextAreaElement).value).not.toContain(TOKEN)
+    fireEvent.click(screen.getByRole('button', { name: 'Add server' }))
+    await vi.waitFor(() => expect(api.userMcpSave).toHaveBeenCalledTimes(1))
+    expect(api.userMcpSave.mock.calls[0]![0]).toMatchObject({
+      name: 'beeper',
+      providers: { claude: true, codex: true },
+      secrets: { 'beeper-authorization': TOKEN },
+    })
+    // Closing is the store's job; Radix animates the DOM out asynchronously.
+    await vi.waitFor(() => expect(useAppStore.getState().mcpServerDialog).toBeNull())
+  })
+})
diff --git a/src/renderer/src/features/mcp/ui/McpServersRow.tsx b/src/renderer/src/features/mcp/ui/McpServersRow.tsx
new file mode 100644
index 000000000..abb471806
--- /dev/null
+++ b/src/renderer/src/features/mcp/ui/McpServersRow.tsx
@@ -0,0 +1,281 @@
+import { useState } from 'react'
+
+import { providerSupportsBuiltInMcpDomain, type BuiltInMcpDefaults } from '@mcp/shared/types'
+import { getRendererProviderCapabilities } from '@providers/registry.renderer.capabilities'
+import { useAppStore } from '@renderer/app-state/hooks'
+import type { Settings } from '@renderer/app-state/settings/types'
+import { Button } from '@renderer/components/ui/button'
+import { BUILT_IN_MCP_SERVERS } from '@renderer/features/mcp/lib/builtInServers'
+import { applyUserMcpResult, useUserMcpSnapshot } from '@renderer/features/mcp/store'
+import { useEnabledAgentProviderKinds } from '@renderer/features/providers/store'
+import { AGENT_PROVIDER_KINDS, type AgentProviderKind } from '@shared/types/providerKind'
+import { isUserMcpProvider, type NativeMcpServer, type UserMcpServerView } from '@shared/userMcp/types'
+
+type Props = {
+  settings: Settings
+  onChange: (patch: Partial<Settings>) => void
+}
+
+/**
+ * Settings → MCP grid (#1143, spec Revision 2): Agent Code's built-in servers
+ * and the user's own servers in ONE table with one column per enabled
+ * provider. Every checkbox means the same thing — "new agents of this provider
+ * get it" — whichever kind of server the row is, which is the whole reason the
+ * two previously separate surfaces were merged.
+ *
+ * Built-in defaults live in renderer Settings (they were already there);
+ * user servers live in main's document. The row writes each to its owner and
+ * never mirrors one into the other.
+ */
+export function McpServersRow({ settings, onChange }: Props) {
+  const enabledKinds = useEnabledAgentProviderKinds()
+  const providers = AGENT_PROVIDER_KINDS.filter(kind => enabledKinds.has(kind))
+  const snapshot = useUserMcpSnapshot()
+  const openDialog = useAppStore(state => state.openMcpServerDialog)
+  const [error, setError] = useState<string | null>(null)
+  const [nativeOpen, setNativeOpen] = useState(false)
+
+  const defaults = settings.defaultBuiltInMcpDomains
+  const setBuiltIn = (kind: AgentProviderKind, domain: (typeof BUILT_IN_MCP_SERVERS)[number]['domain'], on: boolean) => {
+    const current = defaults[kind] ?? []
+    const next: BuiltInMcpDefaults = {
+      ...defaults,
+      [kind]: on ? [...current.filter(item => item !== domain), domain] : current.filter(item => item !== domain),
+    }
+    onChange({ defaultBuiltInMcpDomains: next })
+  }
+
+  const run = async (operation: Promise<Parameters<typeof applyUserMcpResult>[0]>) => {
+    setError(null)
+    try {
+      setError(applyUserMcpResult(await operation))
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause))
+    }
+  }
+
+  const columns = `minmax(0,1fr) repeat(${providers.length}, 56px) 72px`
+
+  return (
+    <div className="rounded-slab border border-border bg-surface text-[11px]">
+      <div className="grid items-center gap-2 border-b border-border px-3 py-2 text-[10px] uppercase tracking-wider text-muted" style={{ gridTemplateColumns: columns }}>
+        <span>Server</span>
+        {providers.map(kind => (
+          <span key={kind} className="text-center">{getRendererProviderCapabilities(kind).shortLabel}</span>
+        ))}
+        <span />
+      </div>
+
+      <SectionHeading>Agent Code</SectionHeading>
+      {BUILT_IN_MCP_SERVERS.map(server => (
+        <div key={server.domain} className="grid items-center gap-2 px-3 py-1.5" style={{ gridTemplateColumns: columns }}>
+          <div className="min-w-0">
+            <span className="text-ink">{server.title}</span>
+            <span className="ml-2 rounded-chip border border-border px-1 text-[9px] text-muted">built-in</span>
+            <div className="truncate text-[10px] text-muted">{server.description}</div>
+          </div>
+          {providers.map(kind => providerSupportsBuiltInMcpDomain(kind, server.domain) ? (
+            <Cell key={kind}>
+              <Check
+                checked={(defaults[kind] ?? []).includes(server.domain)}
+                label={`${server.title} for new ${getRendererProviderCapabilities(kind).shortLabel} agents`}
+                onChange={on => setBuiltIn(kind, server.domain, on)}
+              />
+            </Cell>
+          ) : (
+            <Unsupported key={kind} reason={`${getRendererProviderCapabilities(kind).shortLabel} provides this natively`} />
+          ))}
+          <span />
+        </div>
+      ))}
+      <div className="px-3 pb-2 pt-1 text-[10px] text-muted">
+        Root Management is per agent only and always asks for confirmation — use Agent MCP Servers… on one agent.
+      </div>
+
+      <SectionHeading
+        action={<Button size="xs" variant="outline" onClick={() => openDialog({ mode: 'add' })}>Add server…</Button>}
+      >
+        Your servers
+      </SectionHeading>
+      {snapshot?.storeProblem ? <Notice tone="warn">{snapshot.storeProblem}</Notice> : null}
+      {snapshot?.claudeManagedPolicy ? (
+        <Notice tone="warn">Your organization's Claude MCP policy is active, so your servers are not attached to Claude agents.</Notice>
+      ) : null}
+      {!snapshot ? <div className="px-3 py-2 text-muted">Loading…</div> : null}
+      {snapshot && snapshot.servers.length === 0 ? (
+        <div className="px-3 py-2 text-muted">
+          No servers yet. Add one by pasting the config from its README — for example Beeper Desktop&apos;s.
+        </div>
+      ) : null}
+      {snapshot?.servers.map(server => (
+        <UserServerRow
+          key={server.id}
+          server={server}
+          providers={providers}
+          columns={columns}
+          onToggleEnabled={() => void run(window.api.userMcpSetEnabled(server.id, !server.enabled))}
+          onToggleProvider={(kind, on) => void run(window.api.userMcpSetProvider(server.id, kind, on))}
+          onEdit={() => openDialog({ mode: 'edit', serverId: server.id })}
+        />
+      ))}
+      {error ? <Notice tone="danger">{error}</Notice> : null}
+
+      {snapshot && snapshot.native.length > 0 ? (
+        <>
+          <button
+            type="button"
+            onClick={() => setNativeOpen(open => !open)}
+            className="flex w-full items-center justify-between border-t border-border px-3 py-2 text-left text-[10px] uppercase tracking-wider text-muted hover:text-ink"
+            aria-expanded={nativeOpen}
+          >
+            <span>{nativeOpen ? '▾' : '▸'} Also loaded by the CLIs directly (read-only)</span>
+            <span>{snapshot.native.length}</span>
+          </button>
+          {nativeOpen ? snapshot.native.map(server => (
+            <NativeServerRow
+              key={`${server.provider}:${server.name}`}
+              server={server}
+              onCopyIn={() => void run(window.api.userMcpCopyNative(server.provider, server.name))}
+            />
+          )) : null}
+        </>
+      ) : null}
+
+      <div className="border-t border-border px-3 py-2 text-[10px] text-muted">
+        Changes apply to new agents, and to existing agents when they reload. Secrets are encrypted on this computer and passed to agents through environment variables — the agent itself can read them, like any tool it runs.
+      </div>
+    </div>
+  )
+}
+
+function UserServerRow({
+  server,
+  providers,
+  columns,
+  onToggleEnabled,
+  onToggleProvider,
+  onEdit,
+}: {
+  server: UserMcpServerView
+  providers: AgentProviderKind[]
+  columns: string
+  onToggleEnabled: () => void
+  onToggleProvider: (kind: 'claude' | 'codex', on: boolean) => void
+  onEdit: () => void
+}) {
+  const unsetSecrets = Object.values(server.secrets).filter(secret => !secret.set).length
+  const setSecrets = Object.values(server.secrets).length - unsetSecrets
+  return (
+    <div className={`border-t border-border/50 px-3 py-1.5 ${server.enabled ? '' : 'opacity-60'}`}>
+      <div className="grid items-center gap-2" style={{ gridTemplateColumns: columns }}>
+        <div className="flex min-w-0 items-center gap-2">
+          <button
+            type="button"
+            role="switch"
+            aria-checked={server.enabled}
+            aria-label={`${server.name} on or off everywhere`}
+            onClick={onToggleEnabled}
+            className={`h-3 w-5 shrink-0 rounded-full border ${server.enabled ? 'border-control-active-bg bg-control-active-bg' : 'border-control-border bg-transparent'}`}
+          />
+          <div className="min-w-0">
+            <span className="text-ink">{server.name}</span>
+            {server.transport ? <span className="ml-2 text-[10px] text-muted">{server.transport}</span> : null}
+            <div className="truncate text-[10px] text-muted" title={server.summary}>{server.summary}</div>
+          </div>
+        </div>
+        {providers.map(kind => {
+          if (!isUserMcpProvider(kind)) return <Unsupported key={kind} reason="Not supported yet" />
+          const support = server.support[kind]
+          if (!support.ok) return <Unsupported key={kind} reason={support.reason} />
+          return (
+            <Cell key={kind}>
+              <Check
+                checked={server.providers[kind]}
+                label={`${server.name} for new ${getRendererProviderCapabilities(kind).shortLabel} agents`}
+                disabled={!server.enabled}
+                onChange={on => onToggleProvider(kind, on)}
+              />
+            </Cell>
+          )
+        })}
+        <Button size="xs" variant="ghost" onClick={onEdit}>Edit…</Button>
+      </div>
+      <div className="mt-0.5 flex flex-wrap gap-x-3 pl-7 text-[10px]">
+        {setSecrets > 0 ? <span className="text-muted">🔑 {setSecrets} secret{setSecrets === 1 ? '' : 's'} set</span> : null}
+        {server.problems.map(problem => (
+          <span key={`${problem.kind}:${problem.message}`} className="text-warning">⚠ {problem.message}</span>
+        ))}
+      </div>
+    </div>
+  )
+}
+
+function NativeServerRow({ server, onCopyIn }: { server: NativeMcpServer; onCopyIn: () => void }) {
+  return (
+    <div className="flex items-center gap-3 border-t border-border/50 px-3 py-1.5">
+      <div className="min-w-0 flex-1">
+        <span className="text-ink">{server.name}</span>
+        <span className="ml-2 text-[10px] text-muted">{getRendererProviderCapabilities(server.provider).shortLabel} · {server.source}</span>
+        <div className="truncate text-[10px] text-muted">{server.summary}</div>
+      </div>
+      <Button
+        size="xs"
+        variant="outline"
+        disabled={!server.copyable}
+        title={server.copyable ? 'Manage a copy here and share it with the other provider' : 'This entry cannot be expressed as a standard MCP config'}
+        onClick={onCopyIn}
+      >
+        Copy in
+      </Button>
+    </div>
+  )
+}
+
+function SectionHeading({ children, action }: { children: React.ReactNode; action?: React.ReactNode }) {
+  return (
+    <div className="flex items-center justify-between px-3 pb-1 pt-3 text-[10px] uppercase tracking-wider text-muted">
+      <span>{children}</span>
+      {action}
+    </div>
+  )
+}
+
+function Notice({ children, tone }: { children: React.ReactNode; tone: 'warn' | 'danger' }) {
+  return <div className={`px-3 py-1.5 text-[10px] ${tone === 'danger' ? 'text-danger' : 'text-warning'}`}>{children}</div>
+}
+
+function Cell({ children }: { children: React.ReactNode }) {
+  return <div className="flex justify-center">{children}</div>
+}
+
+function Unsupported({ reason }: { reason: string }) {
+  return <div className="text-center text-muted" title={reason} aria-label={reason}>—</div>
+}
+
+export function Check({
+  checked,
+  label,
+  disabled,
+  onChange,
+}: {
+  checked: boolean
+  label: string
+  disabled?: boolean
+  onChange: (next: boolean) => void
+}) {
+  return (
+    <button
+      type="button"
+      role="checkbox"
+      aria-checked={checked}
+      aria-label={label}
+      disabled={disabled}
+      onClick={() => onChange(!checked)}
+      className={`flex h-3.5 w-3.5 items-center justify-center border text-[9px] leading-none disabled:opacity-40 ${
+        checked ? 'border-control-active-bg bg-control-active-bg text-control-active-fg' : 'border-control-border-hover bg-transparent'
+      }`}
+    >
+      {checked ? '✓' : ''}
+    </button>
+  )
+}
diff --git a/src/renderer/src/features/settings/lib/settingsCategories.ts b/src/renderer/src/features/settings/lib/settingsCategories.ts
index 26bb8f104..fc6fe79a6 100644
--- a/src/renderer/src/features/settings/lib/settingsCategories.ts
+++ b/src/renderer/src/features/settings/lib/settingsCategories.ts
@@ -3,6 +3,7 @@ export type SettingCategoryId =
   | 'workspace'
   | 'providers'
   | 'agents'
+  | 'mcp'
   | 'commands'
   | 'dictation'
   | 'performance'
@@ -37,6 +38,14 @@ export const SETTING_CATEGORIES: SettingCategory[] = [
     label: 'Agents',
     description: 'Shared behavior and instructions for agent runtimes.',
   },
+  // Its own category (#1143) because MCP is now one grid of built-in and user
+  // servers per provider plus the external operator server — three rows that
+  // used to be spread through Agents as eight separate toggles.
+  {
+    id: 'mcp',
+    label: 'MCP',
+    description: 'Tools your agents can use: Agent Code\'s own MCP servers and yours.',
+  },
   {
     id: 'commands',
     label: 'Commands',
diff --git a/src/renderer/src/features/settings/lib/settingsRegistry.test.ts b/src/renderer/src/features/settings/lib/settingsRegistry.test.ts
index d321b962c..db5b5695e 100644
--- a/src/renderer/src/features/settings/lib/settingsRegistry.test.ts
+++ b/src/renderer/src/features/settings/lib/settingsRegistry.test.ts
@@ -2,98 +2,37 @@ import { describe, expect, it, vi } from 'vitest'
 
 import { DEFAULT_SETTINGS } from '@renderer/app-state/settings/types'
 import { CONFIGURABLE_BUILT_IN_MCP_DOMAINS } from '@mcp/shared/types'
+import { BUILT_IN_MCP_SERVERS } from '@renderer/features/mcp/lib/builtInServers'
 import {
   getSettingsRegistry,
+  matchesSettingQuery,
   settingMetadata,
   type SettingActionContext,
   type SettingDefinition,
 } from '@renderer/features/settings/lib/settingsRegistry'
 
-type ToggleSetting = Extract<SettingDefinition, { control: { type: 'toggle' } }>
-
-function defaultMcpToggle(id: string): ToggleSetting {
-  const setting = getSettingsRegistry().find(candidate => candidate.id === id)
-  if (!setting || setting.control.type !== 'toggle') {
-    throw new Error(`Missing MCP toggle setting: ${id}`)
-  }
-  return setting as ToggleSetting
-}
-
-describe('built-in MCP default settings', () => {
-  it('exposes all configurable product domains without a persistent ping setting', () => {
-    const ids = getSettingsRegistry().map(setting => setting.id)
-    expect(ids).toEqual(expect.arrayContaining([
-      'default-orchestration-mcp',
-      'default-ai-workspace-mcp',
-      'default-agent-transcripts-mcp',
-      'default-agent-management-mcp',
-      'default-workflow-mcp',
-    ]))
-    expect(ids).not.toContain('default-ping-mcp')
+describe('MCP settings (#1143)', () => {
+  it('replaces the per-domain default toggles with one MCP grid in the MCP category', () => {
+    const registry = getSettingsRegistry()
+    expect(registry.filter(setting => /^default-.*-mcp$/.test(setting.id))).toEqual([])
+    const grid = registry.find(setting => setting.id === 'mcp-servers')
+    expect(grid?.category).toBe('mcp')
+    expect(grid?.control.type).toBe('mcp-servers')
+    expect(registry.find(setting => setting.id === 'external-control')?.category).toBe('mcp')
   })
 
-  it('gives every configurable domain exactly one default toggle that reads that domain', () => {
-    // Derived from the domain list rather than hand-listed ids, so a new
-    // capability (Goal, #936) cannot ship without its row, and a row copied
-    // from a sibling cannot keep reading the sibling's domain.
-    const toggles = getSettingsRegistry().filter((setting): setting is ToggleSetting =>
-      /^default-.*-mcp$/.test(setting.id) && setting.control.type === 'toggle')
-    for (const domain of CONFIGURABLE_BUILT_IN_MCP_DOMAINS) {
-      const reading = toggles.filter(setting => setting.control.getValue({ ...DEFAULT_SETTINGS, defaultBuiltInMcpDomains: [domain] }))
-      expect(reading.map(setting => setting.id), domain).toHaveLength(1)
+  it('still finds the grid by the name of every built-in capability it replaced', () => {
+    // Users who learned "search Settings for orchestration" must still land on
+    // the place that default now lives.
+    const grid = getSettingsRegistry().find(setting => setting.id === 'mcp-servers')!
+    for (const word of ['tldr', 'goal', 'orchestration', 'ai workspace', 'transcripts', 'agent management', 'workflow', 'beeper']) {
+      expect(matchesSettingQuery(grid, word), word).toBe(true)
     }
   })
 
-  it('adds and removes one domain without disturbing sibling defaults', async () => {
-    const setting = defaultMcpToggle('default-workflow-mcp')
-    const onChange = vi.fn()
-    const enabledSettings = {
-      ...DEFAULT_SETTINGS,
-      defaultBuiltInMcpDomains: ['orchestration' as const],
-    }
-    const context = {
-      settings: enabledSettings,
-      onChange,
-    } as unknown as SettingActionContext
-
-    await setting.control.onToggle(context, true)
-    expect(onChange).toHaveBeenLastCalledWith({
-      defaultBuiltInMcpDomains: ['orchestration', 'workflows'],
-    })
-
-    await setting.control.onToggle({
-      ...context,
-      settings: {
-        ...enabledSettings,
-        defaultBuiltInMcpDomains: ['orchestration', 'workflows'],
-      },
-    }, false)
-    expect(onChange).toHaveBeenLastCalledWith({
-      defaultBuiltInMcpDomains: ['orchestration'],
-    })
-  })
-
-  it('documents Workflow MCP for Codex and OpenCode because Claude is native', () => {
-    const setting = defaultMcpToggle('default-workflow-mcp')
-    expect(setting.description).toContain('Codex and OpenCode')
-    expect(setting.description).toContain('Claude uses its native workflow feature')
-  })
-
-  it('toggles the Agent Management default without disturbing sibling domains', async () => {
-    const setting = defaultMcpToggle('default-agent-management-mcp')
-    const onChange = vi.fn()
-    const context = {
-      settings: {
-        ...DEFAULT_SETTINGS,
-        defaultBuiltInMcpDomains: ['orchestration' as const],
-      },
-      onChange,
-    } as unknown as SettingActionContext
-
-    await setting.control.onToggle(context, true)
-    expect(onChange).toHaveBeenCalledWith({
-      defaultBuiltInMcpDomains: ['orchestration', 'agent_management'],
-    })
+  it('lists every configurable built-in domain exactly once in the grid', () => {
+    const domains = BUILT_IN_MCP_SERVERS.map(server => server.domain)
+    expect([...domains].sort()).toEqual([...CONFIGURABLE_BUILT_IN_MCP_DOMAINS].sort())
   })
 })
 
diff --git a/src/renderer/src/features/settings/lib/settingsRegistry.ts b/src/renderer/src/features/settings/lib/settingsRegistry.ts
index f90207cc8..a81217cea 100644
--- a/src/renderer/src/features/settings/lib/settingsRegistry.ts
+++ b/src/renderer/src/features/settings/lib/settingsRegistry.ts
@@ -15,7 +15,6 @@ import type { Workspace } from '@renderer/workspace/workspaceStore'
 import { SETTING_CATEGORIES } from '@renderer/features/settings/lib/settingsCategories'
 import type { SettingCategoryId } from '@renderer/features/settings/lib/settingsCategories'
 import type { ExtensionListEntry } from '@shared/types/extensions'
-import type { ConfigurableBuiltInMcpDomain } from '@mcp/shared/types'
 import type { MouseButtonBinding } from '@renderer/lib/mouseBinding'
 import { coerceMouseChordBinding } from '@renderer/lib/mouseBinding'
 
@@ -281,6 +280,21 @@ export type SettingDefinition =
         type: 'agent-code-conventions'
       }
     }
+  | {
+      id: string
+      category: SettingCategoryId
+      title: string
+      description: string
+      keywords: string[]
+      metadata?: SettingMetadata
+      // One grid for built-in AND user MCP servers (#1143). Marker row: the
+      // user servers live in main's document and the built-in defaults in
+      // renderer Settings, so the row owns both reads/writes itself rather than
+      // pretending to be one scalar setting.
+      control: {
+        type: 'mcp-servers'
+      }
+    }
   | {
       id: string
       category: SettingCategoryId
@@ -360,29 +374,6 @@ const DICTATION_PROVIDER_OPTIONS: ChoiceOption<Settings['dictationProvider']>[]
   },
 ]
 
-function updateDefaultBuiltInMcpDomain(
-  ctx: SettingActionContext,
-  domain: ConfigurableBuiltInMcpDomain,
-  enabled: boolean,
-): void {
-  // WHY every built-in MCP row is 'Next session' rather than 'Reloads live
-  // agents': the capability list is fixed when a provider process launches, so
-  // honoring this edit means replacing that process. Doing it on a Settings
-  // toggle would kill work in flight across the whole fleet, so the edit is
-  // recorded and each agent picks it up the next time it starts — which now
-  // includes an ordinary reload of an existing agent (#904), not just creation.
-  const current = ctx.settings.defaultBuiltInMcpDomains
-  // WHY each row rewrites one shared ordered set instead of storing four
-  // booleans: the session launch contract already speaks domain arrays, and a
-  // single persisted list makes adding a future domain a one-field migration.
-  // Filtering before append also makes the helper safe against a same-value UI
-  // event without allowing duplicates into the in-memory store.
-  const next = enabled
-    ? [...current.filter(candidate => candidate !== domain), domain]
-    : current.filter(candidate => candidate !== domain)
-  ctx.onChange({ defaultBuiltInMcpDomains: next })
-}
-
 /**
  * `SettingDefinition`s for every contributed extension setting. Reads manifests
  * only (no bundle import), the settings sibling of deriveExtensionCommands. Rows
@@ -685,7 +676,7 @@ export function getSettingsRegistry(
       control: { type: 'agent-code-conventions' },
     },
     {
-      id: 'external-control', category: 'agents', title: 'External operator MCP',
+      id: 'external-control', category: 'mcp', title: 'External operator MCP',
       description: 'Let an external assistant discover commands, read agents and operate all Agent Code windows alongside computer use. Disabled by default and excluded from agents launched here.',
       keywords: ['mcp', 'external', 'operator', 'codex', 'chatgpt', 'automation', 'windows', 'control'],
       metadata: { scope: 'app', apply: 'immediate', storage: 'external-files' },
@@ -716,116 +707,22 @@ export function getSettingsRegistry(
       control: { type: 'agent-code-installed-skills' },
     },
     {
-      id: 'default-tldr-mcp',
-      category: 'agents',
-      title: 'TLDR MCP',
-      description:
-        'Keep concise agent summaries with the managed reporting skill. Off by default. Applies to new agents and existing agents on their next reload. Per-agent overrides take precedence; Use Global MCP Settings clears them.',
-      keywords: ['mcp', 'tldr', 'default', 'reload', 'existing agents', 'claude', 'codex'],
-      metadata: { scope: 'app', apply: 'new-session', storage: 'settings' },
-      control: {
-        type: 'toggle',
-        getValue: settings => settings.defaultBuiltInMcpDomains.includes('tldr'),
-        onToggle: (ctx, value) => updateDefaultBuiltInMcpDomain(ctx, 'tldr', value),
-      },
-    },
-    {
-      id: 'default-goal-mcp',
-      category: 'agents',
-      title: 'Goal MCP',
-      description:
-        'Let agents record their goal — what their work is for — with the managed goal skill, and hold Cmd+G to see it. Off by default. Applies to new agents and existing agents on their next reload. Per-agent overrides take precedence; Use Global MCP Settings clears them.',
-      keywords: ['mcp', 'goal', 'purpose', 'objective', 'default', 'reload', 'existing agents', 'claude', 'codex'],
-      metadata: { scope: 'app', apply: 'new-session', storage: 'settings' },
-      control: {
-        type: 'toggle',
-        getValue: settings => settings.defaultBuiltInMcpDomains.includes('goal'),
-        onToggle: (ctx, value) => updateDefaultBuiltInMcpDomain(ctx, 'goal', value),
-      },
-    },
-    {
-      id: 'default-goal-loop-mcp',
-      category: 'agents',
-      title: 'Goal Loop MCP',
-      description:
-        'Let agents run harness-owned goal loops that keep re-prompting until the goal is complete, with a control strip and an overlay on the Goal Loop chord (Cmd+Shift+G by default; it yields to the editor, which owns that chord as Find Previous). Off by default. Applies to new agents and existing agents on their next reload. Per-agent overrides take precedence; Use Global MCP Settings clears them.',
-      keywords: ['mcp', 'goal', 'loop', 'persistence', 'autonomous', 'default', 'reload', 'existing agents'],
-      metadata: { scope: 'app', apply: 'new-session', storage: 'settings' },
-      control: {
-        type: 'toggle',
-        getValue: settings => settings.defaultBuiltInMcpDomains.includes('goal_loop'),
-        onToggle: (ctx, value) => updateDefaultBuiltInMcpDomain(ctx, 'goal_loop', value),
-      },
-    },
-    {
-      id: 'default-orchestration-mcp',
-      category: 'agents',
-      title: 'Orchestration MCP',
-      description:
-        'Let agents create and coordinate child agents. Applies to new agents and existing agents on their next reload. Per-agent overrides take precedence; Use Global MCP Settings clears them.',
-      keywords: ['mcp', 'orchestration', 'default', 'reload', 'existing agents', 'claude', 'codex'],
-      metadata: { scope: 'app', apply: 'new-session', storage: 'settings' },
-      control: {
-        type: 'toggle',
-        getValue: settings => settings.defaultBuiltInMcpDomains.includes('orchestration'),
-        onToggle: (ctx, value) => updateDefaultBuiltInMcpDomain(ctx, 'orchestration', value),
-      },
-    },
-    {
-      id: 'default-ai-workspace-mcp',
-      category: 'agents',
-      title: 'AI Workspace MCP',
-      description:
-        'Let agents curate review workspaces across worktrees. Applies to new agents and existing agents on their next reload. Per-agent overrides take precedence; Use Global MCP Settings clears them.',
-      keywords: ['mcp', 'ai workspace', 'review', 'default', 'reload', 'existing agents', 'claude', 'codex'],
-      metadata: { scope: 'app', apply: 'new-session', storage: 'settings' },
-      control: {
-        type: 'toggle',
-        getValue: settings => settings.defaultBuiltInMcpDomains.includes('ai_workspace'),
-        onToggle: (ctx, value) => updateDefaultBuiltInMcpDomain(ctx, 'ai_workspace', value),
-      },
-    },
-    {
-      id: 'default-agent-transcripts-mcp',
-      category: 'agents',
-      title: 'Agent Transcripts MCP',
-      description:
-        'Give agents bounded transcript file tools. Applies to new agents and existing agents on their next reload. Per-agent overrides take precedence; Use Global MCP Settings clears them.',
-      keywords: ['mcp', 'transcript', 'transcripts', 'default', 'reload', 'existing agents', 'claude', 'codex'],
-      metadata: { scope: 'app', apply: 'new-session', storage: 'settings' },
-      control: {
-        type: 'toggle',
-        getValue: settings => settings.defaultBuiltInMcpDomains.includes('agent_transcripts'),
-        onToggle: (ctx, value) => updateDefaultBuiltInMcpDomain(ctx, 'agent_transcripts', value),
-      },
-    },
-    {
-      id: 'default-agent-management-mcp',
-      category: 'agents',
-      title: 'Agent Management MCP',
+      id: 'mcp-servers',
+      category: 'mcp',
+      title: 'MCP servers',
       description:
-        'Let agents inspect project agents and send follow-ups; closing agents still requires explicit user authorization. Applies to new agents and existing agents on their next reload. Per-agent overrides take precedence; Use Global MCP Settings clears them.',
-      keywords: ['mcp', 'agent management', 'agents', 'project', 'cleanup', 'default', 'reload', 'existing agents', 'claude', 'codex'],
-      metadata: { scope: 'app', apply: 'new-session', storage: 'settings' },
-      control: {
-        type: 'toggle',
-        getValue: settings => settings.defaultBuiltInMcpDomains.includes('agent_management'),
-        onToggle: (ctx, value) => updateDefaultBuiltInMcpDomain(ctx, 'agent_management', value),
-      },
-    },
-    {
-      id: 'default-workflow-mcp',
-      category: 'agents',
-      title: 'Workflow MCP',
-      description:
-        'Give Codex and OpenCode workflow tools. Claude uses its native workflow feature. Applies to new agents and existing agents on their next reload. Per-agent overrides take precedence; Use Global MCP Settings clears them.',
-      keywords: ['mcp', 'workflow', 'workflows', 'codex', 'default', 'reload', 'existing agents', 'claude native'],
-      metadata: { scope: 'app', apply: 'new-session', storage: 'settings' },
-      control: {
-        type: 'toggle',
-        getValue: settings => settings.defaultBuiltInMcpDomains.includes('workflows'),
-        onToggle: (ctx, value) => updateDefaultBuiltInMcpDomain(ctx, 'workflows', value),
-      },
+        'Every MCP server your agents can use: Agent Code\'s own and yours. A checked provider column means new agents of that provider get the server; existing agents pick changes up on their next reload. Per-agent choices (Agent MCP Servers…) take precedence.',
+      // Carries the vocabulary of the eight per-domain rows this grid replaced
+      // (#1143), so searching "tldr" or "orchestration" still finds the place
+      // those defaults now live.
+      keywords: [
+        'mcp', 'server', 'servers', 'tools', 'add', 'install', 'custom', 'beeper', 'stdio', 'http', 'sse',
+        'secret', 'token', 'oauth', 'claude', 'codex', 'default', 'reload', 'existing agents',
+        'tldr', 'summary', 'goal', 'loop', 'orchestration', 'ai workspace', 'review',
+        'transcript', 'transcripts', 'agent management', 'workflow', 'workflows',
+      ],
+      metadata: { scope: 'app', apply: 'new-session', storage: 'external-files' },
+      control: { type: 'mcp-servers' },
     },
     {
       id: 'command-keybindings',
diff --git a/src/renderer/src/features/settings/ui/SettingsList.tsx b/src/renderer/src/features/settings/ui/SettingsList.tsx
index eb66e19c1..370af8183 100644
--- a/src/renderer/src/features/settings/ui/SettingsList.tsx
+++ b/src/renderer/src/features/settings/ui/SettingsList.tsx
@@ -1,4 +1,5 @@
 import { useAppStore } from '@renderer/app-state/hooks'
+import { McpServersRow } from '@renderer/features/mcp/ui/McpServersRow'
 import { ExternalControlRow } from './ExternalControlRow'
 import type { Settings } from '@renderer/app-state/settings/types'
 import type {
@@ -121,6 +122,21 @@ function SettingRow({
   const context = { ...actionContext, settings }
   const control = definition.control
 
+  // The MCP grid (#1143) is a table with one column per provider; squeezing it
+  // into the 420px control column would truncate every server name, so it is
+  // the one row that renders full width under its description.
+  if (control.type === 'mcp-servers') {
+    return (
+      <div className="border-b border-panel-border px-4 py-4 last:border-b-0">
+        <div className="text-[12px] text-ink">{definition.title}</div>
+        <div className="mt-1 text-[11px] leading-5 text-muted">{definition.description}</div>
+        <div className="mt-3">
+          <McpServersRow settings={settings} onChange={actionContext.onChange} />
+        </div>
+      </div>
+    )
+  }
+
   return (
     <div className="border-b border-panel-border px-4 py-4 last:border-b-0">
       <div className="flex flex-col gap-3 lg:flex-row lg:items-start lg:justify-between lg:gap-6">
diff --git a/src/renderer/src/features/settings/ui/SettingsPage.tsx b/src/renderer/src/features/settings/ui/SettingsPage.tsx
index a6e9b7fe1..c3635a164 100644
--- a/src/renderer/src/features/settings/ui/SettingsPage.tsx
+++ b/src/renderer/src/features/settings/ui/SettingsPage.tsx
@@ -1,4 +1,4 @@
-import { useMemo, useState } from 'react'
+import { useEffect, useMemo, useState } from 'react'
 
 import { Button } from '@renderer/components/ui/button'
 import {
@@ -33,6 +33,10 @@ import { SettingsSearch } from '@renderer/features/settings/ui/SettingsSearch'
 import { SettingsSidebar } from '@renderer/features/settings/ui/SettingsSidebar'
 import { useAppStore } from '@renderer/app-state/store'
 
+function validCategory(value: string | null): SettingCategoryId | 'all' {
+  return SETTING_CATEGORIES.find(category => category.id === value)?.id ?? 'all'
+}
+
 type Props = {
   onClose: () => void
   workspace: Workspace
@@ -43,7 +47,20 @@ type Props = {
 
 export function SettingsPage({ onClose, workspace, settings, onChange, onReset }: Props) {
   const [query, setQuery] = useState('')
-  const [selectedCategory, setSelectedCategory] = useState<SettingCategoryId | 'all'>('all')
+  // A deep link (openSettingsPage('mcp')) picks the starting category. Read
+  // once at mount AND followed while open, so "MCP Servers" invoked with
+  // Settings already showing another category still lands on MCP.
+  const requestedCategory = useAppStore(state => state.settingsPageCategory)
+  // The request counter, not the category string, drives the effect: running
+  // "MCP Servers" twice with a sidebar click in between asks for the same
+  // string twice, and only a changed dependency re-applies it (review round 1).
+  const request = useAppStore(state => state.settingsPageRequest)
+  const [selectedCategory, setSelectedCategory] = useState<SettingCategoryId | 'all'>(
+    () => validCategory(requestedCategory),
+  )
+  useEffect(() => {
+    if (requestedCategory) setSelectedCategory(validCategory(requestedCategory))
+  }, [requestedCategory, request])
   // null           → editor closed
   // { id: null }   → creating, seeded from the currently applied appearance
   // { id: '...' }  → editing that saved theme
diff --git a/src/renderer/src/features/tldr/controlReference.ts b/src/renderer/src/features/tldr/controlReference.ts
index 7dca6fa07..eb28df236 100644
--- a/src/renderer/src/features/tldr/controlReference.ts
+++ b/src/renderer/src/features/tldr/controlReference.ts
@@ -4,16 +4,16 @@ export const controlReference = [{
   id: 'tldr',
   title: 'TLDR agent summaries and goals',
   purpose: 'Scan outcomes, next steps and pending decisions across visible agents, and what each agent is for.',
-  ui: 'TLDR MCP and Goal MCP per-agent commands, TLDR MCP and Goal MCP settings, TLDR and Goal preview commands, and View TLDR History command.',
-  prerequisites: 'Enable TLDR MCP for each agent that should report status, and Goal MCP for each agent that should record its goal. The two are independent and both off by default.',
+  ui: 'TLDR and Goal rows in Settings → MCP (per provider) and in the Agent MCP Servers picker (per agent), TLDR and Goal preview commands, and View TLDR History command.',
+  prerequisites: 'Turn TLDR on for agents that should report status, and Goal for agents that should record their goal: per provider in Settings → MCP, or for one agent with Agent MCP Servers. The two are independent.',
   workflow: [
-    'Enable TLDR MCP for the agent; it reloads with the managed reporting skill.',
+    'Turn TLDR on for the agent in Agent MCP Servers; it reloads with the managed reporting skill.',
     'The agent replaces its short summary after substantial work or discussion.',
     'Hold the TLDR shortcut to peek and release to dismiss, or open TLDR from the palette and dismiss with Escape.',
     'Open View TLDR History to read how the focused agent’s status evolved, newest first.',
-    'Enable Goal MCP for an agent; it records what its work is for. Hold the Goal shortcut to peek at goals.',
+    'Turn Goal on for an agent the same way; it records what its work is for. Hold the Goal shortcut to peek at goals.',
   ],
   outcome: 'Each visible agent pane shows its own latest saved summary, or with the Goal preview its recorded goal, in centered text over an overlay in the app’s background color.',
   cautions: 'Reading summaries makes no model calls. Claude and Codex agents are asked to update at turn end when they used tools without reporting; they may decline when nothing changed. A summary describes the last report, not live activity or permission to act. Minor unchanged clarifications need no update. Goals are written by the agent and change only when its direction changes; users cannot edit them. The editor retains its native Select Line and Find Next shortcuts.',
-  commandIds: ['enable-tldr-mcp', 'tldr-preview', 'view-tldr-history', 'enable-goal-mcp', 'goal-preview'],
+  commandIds: ['agent-mcp-servers', 'tldr-preview', 'view-tldr-history', 'goal-preview'],
 }] satisfies FeatureReference[]
diff --git a/src/renderer/src/features/workspace/commands/sessionCommands.renderer.test.ts b/src/renderer/src/features/workspace/commands/sessionCommands.renderer.test.ts
index 824fea1f1..70977fbcf 100644
--- a/src/renderer/src/features/workspace/commands/sessionCommands.renderer.test.ts
+++ b/src/renderer/src/features/workspace/commands/sessionCommands.renderer.test.ts
@@ -310,115 +310,6 @@ describe('Rendering Debug Mode command', () => {
   })
 })
 
-function mcpCommandContext(kind: 'claude' | 'codex' | 'opencode'): {
-  context: CommandContext
-  replaceSession: ReturnType<typeof vi.fn>
-} {
-  const replaceSession = vi.fn().mockResolvedValue('replacement')
-  const workspace = {
-    state: {
-      activeTabId: 'tab-mcp',
-      stage: oneLaneStage('agent'),   pinnedSessionIds: [],
-      sessions: {
-        agent: {
-          cwd: '/projects/mcp',
-          kind,
-          providerSessionId: 'provider-session',
-          builtInMcpDomains: [],
-          projectId: 'tab-mcp',
-          joinedAt: 0,
-        },
-      },
-      tabs: [{
-        id: 'tab-mcp',
-      }],
-    },
-    replaceSession,
-    showPaneToast: vi.fn(),
-  } as unknown as Workspace
-  return {
-    context: {
-      workspace,
-      ui: { closePalette: vi.fn() },
-      flags: {},
-    } as unknown as CommandContext,
-    replaceSession,
-  }
-}
-
-describe('built-in MCP provider command policy', () => {
-  const workflowCommand = sessionCommands.find(command => command.id === 'enable-workflow-mcp')
-  const orchestrationCommand = sessionCommands.find(
-    command => command.id === 'enable-orchestration-mcp',
-  )
-  const agentManagementCommand = sessionCommands.find(
-    command => command.id === 'enable-agent-management-mcp',
-  )
-
-  it('offers Workflow MCP to Codex and OpenCode but not Claude', () => {
-    if (!workflowCommand) throw new Error('Workflow MCP command is missing')
-
-    expect(workflowCommand.when?.(mcpCommandContext('codex').context)).toBe(true)
-    expect(workflowCommand.when?.(mcpCommandContext('claude').context)).toBe(false)
-    expect(workflowCommand.when?.(mcpCommandContext('opencode').context)).toBe(true)
-  })
-
-  it('keeps the Workflow runtime guard inert for Claude', async () => {
-    if (!workflowCommand) throw new Error('Workflow MCP command is missing')
-    const { context, replaceSession } = mcpCommandContext('claude')
-
-    await workflowCommand.run(context)
-
-    expect(replaceSession).not.toHaveBeenCalled()
-  })
-
-  it('still toggles Workflow MCP for a Codex session', async () => {
-    if (!workflowCommand) throw new Error('Workflow MCP command is missing')
-    const { context, replaceSession } = mcpCommandContext('codex')
-
-    await workflowCommand.run(context)
-
-    expect(replaceSession).toHaveBeenCalledWith('/projects/mcp', {
-      kind: 'codex',
-      resumeSessionId: 'provider-session',
-      builtInMcpOverrides: { workflows: true },
-      // Every capability reload now pins its target: Dispatch focus can move
-      // while the replacement is in flight, and an unpinned reload would apply
-      // the change to whichever pane became focused.
-      targetSessionId: 'agent',
-    })
-  })
-
-  it('advertises general MCP toggles to OpenCode now that launch config is injected', () => {
-    if (!orchestrationCommand) throw new Error('Orchestration MCP command is missing')
-    expect(orchestrationCommand.when?.(mcpCommandContext('opencode').context)).toBe(true)
-  })
-
-  it('offers Agent Management to every provider launcher', () => {
-    if (!agentManagementCommand) throw new Error('Agent Management MCP command is missing')
-    expect(agentManagementCommand.when?.(mcpCommandContext('claude').context)).toBe(true)
-    expect(agentManagementCommand.when?.(mcpCommandContext('codex').context)).toBe(true)
-    expect(agentManagementCommand.when?.(mcpCommandContext('opencode').context)).toBe(true)
-  })
-
-  it('toggles Agent Management for one existing session through replacement', async () => {
-    if (!agentManagementCommand) throw new Error('Agent Management MCP command is missing')
-    const { context, replaceSession } = mcpCommandContext('claude')
-
-    await agentManagementCommand.run(context)
-
-    expect(replaceSession).toHaveBeenCalledWith('/projects/mcp', {
-      kind: 'claude',
-      resumeSessionId: 'provider-session',
-      builtInMcpOverrides: { agent_management: true },
-      // Every capability reload now pins its target: Dispatch focus can move
-      // while the replacement is in flight, and an unpinned reload would apply
-      // the change to whichever pane became focused.
-      targetSessionId: 'agent',
-    })
-  })
-})
-
 // ---------------------------------------------------------------------------
 // Which capability gates which command.
 //
diff --git a/src/renderer/src/features/workspace/commands/sessionCommands.ts b/src/renderer/src/features/workspace/commands/sessionCommands.ts
index fb0fe0749..b29931323 100644
--- a/src/renderer/src/features/workspace/commands/sessionCommands.ts
+++ b/src/renderer/src/features/workspace/commands/sessionCommands.ts
@@ -13,13 +13,12 @@ import { runAttachRecordingNoteCommand, runToggleSessionRecordingCommand } from
 import { commandTargetSessionId } from '@renderer/workspace/hook/selectors/commandTargetSessionId'
 import { buildProviderResumeCommand } from '@renderer/workspace/providerResumeCommand'
 import { providerSupportsBuiltInMcpDomain } from '@mcp/shared/types'
-import type { BuiltInMcpDomain, BuiltInMcpOverrides } from '@mcp/shared/types'
+import type { BuiltInMcpDomain } from '@mcp/shared/types'
 import { clearAgentComposer } from '@renderer/workspace/tile-tree/TileLeaf/clearAgentComposer'
 import { hasOrchestrationAgents } from '@renderer/workspace/idleOrchestrationAgents'
 import { sessionHasTranscript } from '@renderer/workspace/transcriptAvailability'
 import {
   reloadSessionWithBuiltInMcpChoice,
-  reloadSessionWithBuiltInMcpOverrides,
 } from '@renderer/workspace/builtInMcpReload'
 import {
   ROOT_MANAGEMENT_DOMAIN,
@@ -64,29 +63,6 @@ function agentViewOverrideLabel(
 }
 
 export const sessionCommands: CommandDef[] = [
-  {
-    id: 'use-global-mcp-settings',
-    category: 'session', surface: 'session', title: 'Use Global MCP Settings',
-    description: '**What it does:** Clears this agent’s MCP overrides and reloads it with the current global settings.\n\n**Use when:** You want this agent to follow Settings again, including on future reloads.\n\n**Notes:** Resumes the same conversation when its provider session is available.',
-    keywords: ['mcp', 'global', 'default', 'inherit', 'reset', 'reload'],
-    when: ({ workspace }) => {
-      const id = commandTargetSessionId(workspace)
-      const meta = id ? workspace.state.sessions[id] : null
-      return Boolean(meta && isAgentProviderKind(meta.kind ?? DEFAULT_PROVIDER))
-    },
-    run: async ({ workspace, ui }) => {
-      const id = commandTargetSessionId(workspace)
-      const meta = id ? workspace.state.sessions[id] : null
-      if (!id || !meta || !isAgentProviderKind(meta.kind ?? DEFAULT_PROVIDER)) return
-      ui.closePalette()
-      // `{}` is the whole point: it removes every per-agent choice so this agent
-      // follows Settings again, now and on every future reload.
-      await reloadSessionWithBuiltInMcpOverrides(workspace, id, {}, {
-        reloaded: 'Reloaded with global MCP settings',
-        failed: 'MCP reload failed',
-      })
-    },
-  },
   {
     id: 'view-prompts',
     category: 'session',
@@ -530,136 +506,6 @@ export const sessionCommands: CommandDef[] = [
       })
     },
   },
-  {
-    id: 'enable-ai-workspace-mcp',
-    category: 'session',
-    surface: 'session',
-    title: 'AI Workspace MCP',
-    description: '**What it does:** Reloads the focused **agent** with Agent Code AI Workspace MCP tools on or off.\n\n**Use when:** You want this agent to create curated cross-worktree file review workspaces.\n\n**Notes:** Orchestration agents can use this domain, but it remains a separate MCP capability.',
-    keywords: ['mcp', 'ai workspace', 'workspace', 'review', 'files', 'worktree', 'enable', 'disable', 'reload', 'claude', 'codex', 'opencode'],
-    when: ({ workspace }) => {
-      return targetSupportsBuiltInMcpDomain(workspace, 'ai_workspace')
-    },
-    getState: ctx => builtInMcpDomainState(ctx, 'ai_workspace'),
-    run: async ({ workspace, ui }) => {
-      const sessionId = commandTargetSessionId(workspace)
-      if (!sessionId) return
-      const meta = workspace.state.sessions[sessionId]
-      const kind = meta?.kind ?? DEFAULT_PROVIDER
-      // See the ping command: hidden commands can still be invoked outside the
-      // picker, so execution must enforce the same provider policy.
-      if (
-        !isAgentProviderKind(kind) ||
-        !providerSupportsBuiltInMcpDomain(kind, 'ai_workspace') ||
-        !meta
-      ) return
-
-      ui.closePalette()
-      const enable = !meta.builtInMcpDomains?.includes('ai_workspace')
-      await reloadSessionWithBuiltInMcpChoice(workspace, sessionId, 'ai_workspace', enable, {
-        reloaded: enable ? 'Reloaded with AI Workspace MCP' : 'Reloaded without AI Workspace MCP',
-        failed: 'AI Workspace MCP reload failed',
-      })
-    },
-  },
-  {
-    id: 'enable-orchestration-mcp',
-    category: 'session',
-    pickerVisibility: 'advanced',
-    surface: 'session',
-    title: 'Orchestration MCP',
-    description: '**What it does:** Reloads the focused **agent** with Agent Code orchestration MCP tools on or off.\n\n**Use when:** You want this agent to create and coordinate distinct orchestration child agents.\n\n**Notes:** Orchestration agents are separate from manual Linked Agents.',
-    keywords: ['mcp', 'orchestration', 'agents', 'workers', 'enable', 'disable', 'reload', 'claude', 'codex', 'opencode'],
-    when: ({ workspace }) => {
-      return targetSupportsBuiltInMcpDomain(workspace, 'orchestration')
-    },
-    getState: ctx => builtInMcpDomainState(ctx, 'orchestration'),
-    run: async ({ workspace, ui }) => {
-      const sessionId = commandTargetSessionId(workspace)
-      if (!sessionId) return
-      const meta = workspace.state.sessions[sessionId]
-      const kind = meta?.kind ?? DEFAULT_PROVIDER
-      // See the ping command: hidden commands can still be invoked outside the
-      // picker, so execution must enforce the same provider policy.
-      if (
-        !isAgentProviderKind(kind) ||
-        !providerSupportsBuiltInMcpDomain(kind, 'orchestration') ||
-        !meta
-      ) return
-
-      ui.closePalette()
-      const enable = !meta.builtInMcpDomains?.includes('orchestration')
-      await reloadSessionWithBuiltInMcpChoice(workspace, sessionId, 'orchestration', enable, {
-        reloaded: enable ? 'Reloaded with orchestration MCP' : 'Reloaded without orchestration MCP',
-        failed: 'Orchestration MCP reload failed',
-      })
-    },
-  },
-  {
-    id: 'enable-agent-transcripts-mcp',
-    category: 'session',
-    surface: 'session',
-    title: 'Agent Transcripts MCP',
-    description: '**What it does:** Reloads the focused **agent** with Agent Code transcript-consumption MCP tools on or off.\n\n**Use when:** You want this agent to read a specific transcript file through filtered projections instead of manual shell parsing.\n\n**Notes:** The tool accepts an explicit file path and returns bounded normalized transcript context; it does not discover transcripts for the agent.',
-    keywords: ['mcp', 'transcript', 'transcripts', 'agent context', 'handoff', 'review', 'enable', 'disable', 'reload', 'claude', 'codex', 'opencode'],
-    when: ({ workspace }) => {
-      return targetSupportsBuiltInMcpDomain(workspace, 'agent_transcripts')
-    },
-    getState: ctx => builtInMcpDomainState(ctx, 'agent_transcripts'),
-    run: async ({ workspace, ui }) => {
-      const sessionId = commandTargetSessionId(workspace)
-      if (!sessionId) return
-      const meta = workspace.state.sessions[sessionId]
-      const kind = meta?.kind ?? DEFAULT_PROVIDER
-      // See the ping command: hidden commands can still be invoked outside the
-      // picker, so execution must enforce the same provider policy.
-      if (
-        !isAgentProviderKind(kind) ||
-        !providerSupportsBuiltInMcpDomain(kind, 'agent_transcripts') ||
-        !meta
-      ) return
-
-      ui.closePalette()
-      const enable = !meta.builtInMcpDomains?.includes('agent_transcripts')
-      await reloadSessionWithBuiltInMcpChoice(workspace, sessionId, 'agent_transcripts', enable, {
-        reloaded: enable ? 'Reloaded with Agent Transcripts MCP' : 'Reloaded without Agent Transcripts MCP',
-        failed: 'Agent Transcripts MCP reload failed',
-      })
-    },
-  },
-  {
-    id: 'enable-agent-management-mcp',
-    category: 'session',
-    surface: 'session',
-    title: 'Agent Management MCP',
-    description: '**What it does:** Reloads the focused **agent** with project-wide Agent Code management tools on or off.\n\n**Use when:** You want this agent to inventory, inspect, prompt, or close other agents in its project.\n\n**Notes:** Read operations include agents that are not in a lane, without waking them. Every close it attempts asks **you** to confirm first, and cascades are refused outright.',
-    keywords: ['mcp', 'agent management', 'agents', 'project', 'transcripts', 'cleanup', 'prompt', 'close', 'enable', 'disable', 'reload', 'claude', 'codex', 'opencode'],
-    when: ({ workspace }) => {
-      return targetSupportsBuiltInMcpDomain(workspace, 'agent_management')
-    },
-    getState: ctx => builtInMcpDomainState(ctx, 'agent_management'),
-    run: async ({ workspace, ui }) => {
-      const sessionId = commandTargetSessionId(workspace)
-      if (!sessionId) return
-      const meta = workspace.state.sessions[sessionId]
-      const kind = meta?.kind ?? DEFAULT_PROVIDER
-      // Command visibility is advisory—the command can still be invoked by a
-      // keybinding or programmatic caller—so provider policy is repeated at the
-      // mutation boundary before we replace a live process.
-      if (
-        !isAgentProviderKind(kind) ||
-        !providerSupportsBuiltInMcpDomain(kind, 'agent_management') ||
-        !meta
-      ) return
-
-      ui.closePalette()
-      const enable = !meta.builtInMcpDomains?.includes('agent_management')
-      await reloadSessionWithBuiltInMcpChoice(workspace, sessionId, 'agent_management', enable, {
-        reloaded: enable ? 'Reloaded with Agent Management MCP' : 'Reloaded without Agent Management MCP',
-        failed: 'Agent Management MCP reload failed',
-      })
-    },
-  },
   {
     id: 'enable-root-agent-code-management',
     category: 'session',
@@ -708,157 +554,6 @@ export const sessionCommands: CommandDef[] = [
       ui.openRootManagementPrompt(sessionId)
     },
   },
-  {
-    id: 'enable-tldr-mcp',
-    category: 'session',
-    surface: 'session',
-    title: 'TLDR MCP',
-    description: '**What it does:** Reloads the focused agent with TLDR reporting on or off.\n\n**Use when:** You want this agent to keep one concise summary of progress, next steps and pending decisions.\n\n**Notes:** Deploys the managed reporting skill. Hold the TLDR shortcut to read summaries across visible agents.',
-    keywords: ['tldr', 'summary', 'status', 'mcp', 'decision', 'report'],
-    when: ({ workspace }) => {
-      return targetSupportsBuiltInMcpDomain(workspace, 'tldr')
-    },
-    getState: ctx => builtInMcpDomainState(ctx, 'tldr'),
-    run: async ({ workspace, ui }) => {
-      const sessionId = commandTargetSessionId(workspace)
-      if (!sessionId) return
-      const meta = workspace.state.sessions[sessionId]
-      const kind = meta?.kind ?? DEFAULT_PROVIDER
-      // Command visibility is advisory—the command can still be invoked by a
-      // keybinding or programmatic caller—so provider policy is repeated at the
-      // mutation boundary before we replace a live process.
-      if (
-        !isAgentProviderKind(kind) ||
-        !providerSupportsBuiltInMcpDomain(kind, 'tldr') ||
-        !meta
-      ) return
-
-      ui.closePalette()
-      const enable = !meta.builtInMcpDomains?.includes('tldr')
-      await reloadSessionWithBuiltInMcpChoice(workspace, sessionId, 'tldr', enable, {
-        reloaded: enable ? 'Reloaded with TLDR MCP' : 'Reloaded without TLDR MCP',
-        failed: 'TLDR MCP reload failed',
-      })
-    },
-  },
-  {
-    id: 'enable-goal-mcp',
-    category: 'session',
-    surface: 'session',
-    title: 'Goal MCP',
-    description: '**What it does:** Reloads the focused agent with goal recording on or off.\n\n**Use when:** You want this agent to record what its work is for, so you can see its purpose at a glance.\n\n**Notes:** Deploys the managed goal skill. Hold the Goal shortcut to read goals across visible agents. Works with or without TLDR.',
-    keywords: ['goal', 'purpose', 'objective', 'intent', 'mcp', 'why'],
-    when: ({ workspace }) => {
-      return targetSupportsBuiltInMcpDomain(workspace, 'goal')
-    },
-    getState: ctx => builtInMcpDomainState(ctx, 'goal'),
-    run: async ({ workspace, ui }) => {
-      const sessionId = commandTargetSessionId(workspace)
-      if (!sessionId) return
-      const meta = workspace.state.sessions[sessionId]
-      const kind = meta?.kind ?? DEFAULT_PROVIDER
-      // Provider policy is repeated at the mutation boundary: visibility is
-      // advisory and the command stays reachable from keybindings and control.
-      if (
-        !isAgentProviderKind(kind) ||
-        !providerSupportsBuiltInMcpDomain(kind, 'goal') ||
-        !meta
-      ) return
-
-      ui.closePalette()
-      const enable = !meta.builtInMcpDomains?.includes('goal')
-      await reloadSessionWithBuiltInMcpChoice(workspace, sessionId, 'goal', enable, {
-        reloaded: enable ? 'Reloaded with Goal MCP' : 'Reloaded without Goal MCP',
-        failed: 'Goal MCP reload failed',
-      })
-    },
-  },
-  {
-    // #1006: the per-agent toggle every sibling domain has (TLDR, Goal).
-    // goal_loop already had the Settings row and the per-session override
-    // plumbing, but no command, so "turn the loop on for just this agent"
-    // meant a trip through Settings and a reload by hand.
-    id: 'enable-goal-loop-mcp',
-    category: 'session',
-    surface: 'session',
-    title: 'Goal Loop MCP',
-    description: '**What it does:** Reloads the focused agent with goal-loop tools on or off.\n\n**Use when:** You want this agent to be able to run a harness-owned goal loop that keeps re-prompting it until the goal is done.\n\n**Notes:** The agent starts a loop itself when you ask it to (goal_loop_start). Every continuation is a model call, and the loop pauses at its budget. Turning the tools off ends a running loop, because the agent would no longer be able to report that it is done. The Goal Loop command shows and controls a running loop.',
-    keywords: ['goal', 'loop', 'autonomous', 'persistence', 'keep going', 'mcp'],
-    when: ({ workspace }) => {
-      return targetSupportsBuiltInMcpDomain(workspace, 'goal_loop')
-    },
-    getState: ctx => builtInMcpDomainState(ctx, 'goal_loop'),
-    run: async ({ workspace, ui }) => {
-      const sessionId = commandTargetSessionId(workspace)
-      if (!sessionId) return
-      const meta = workspace.state.sessions[sessionId]
-      const kind = meta?.kind ?? DEFAULT_PROVIDER
-      // Provider policy is repeated at the mutation boundary: visibility is
-      // advisory and the command stays reachable from keybindings and control.
-      if (
-        !isAgentProviderKind(kind) ||
-        !providerSupportsBuiltInMcpDomain(kind, 'goal_loop') ||
-        !meta
-      ) return
-
-      ui.closePalette()
-      const enable = !meta.builtInMcpDomains?.includes('goal_loop')
-      // Turning the tools off ENDS a running loop (#1045 review). The loop is
-      // harness-owned, so it survives the reload on its own, but the reloaded
-      // agent no longer has goal_loop_complete: it cannot say it is done, and
-      // every continuation it is sent runs to the cap. Ending it here is the
-      // honest reading of "this agent does not do goal loops any more", and it
-      // happens BEFORE the reload so it applies to the session id the loop is
-      // filed under rather than the replacement's.
-      if (!enable) {
-        // try/catch, not .catch(): a preload without the channel throws
-        // synchronously. Either way the reload is what the user asked for and
-        // must still happen; a loop left running is visible and stoppable from
-        // the Goal Loop command.
-        try { await window.api.controlGoalLoop({ sessionId, action: 'stop' }) } catch { /* reload anyway */ }
-      }
-      await reloadSessionWithBuiltInMcpChoice(workspace, sessionId, 'goal_loop', enable, {
-        reloaded: enable ? 'Reloaded with Goal Loop MCP' : 'Reloaded without Goal Loop MCP',
-        failed: 'Goal Loop MCP reload failed',
-      })
-    },
-  },
-  {
-    id: 'enable-workflow-mcp',
-    category: 'session',
-    pickerVisibility: 'advanced',
-    surface: 'session',
-    title: 'Workflow MCP',
-    description: '**What it does:** Reloads the focused **Codex or OpenCode agent** with Agent Code workflow MCP tools on or off.\n\n**Use when:** You want the agent to discover, start, inspect, cancel, or resume portable multi-agent workflows.\n\n**Notes:** Claude is intentionally excluded because it has a native workflow feature. Workflow execution is app-owned and survives renderer reloads; changing MCP capabilities still requires replacing the provider process.',
-    keywords: ['mcp', 'workflow', 'workflows', 'pipeline', 'agents', 'resume', 'enable', 'disable', 'reload', 'codex', 'opencode', 'claude native'],
-    when: ({ workspace }) => {
-      return targetSupportsBuiltInMcpDomain(workspace, 'workflows')
-    },
-    getState: ctx => builtInMcpDomainState(ctx, 'workflows'),
-    run: async ({ workspace, ui }) => {
-      const sessionId = commandTargetSessionId(workspace)
-      if (!sessionId) return
-      const meta = workspace.state.sessions[sessionId]
-      const kind = meta?.kind ?? DEFAULT_PROVIDER
-      if (
-        !isAgentProviderKind(kind) ||
-        !providerSupportsBuiltInMcpDomain(kind, 'workflows') ||
-        !meta
-      ) return
-
-      ui.closePalette()
-      const enable = !meta.builtInMcpDomains?.includes('workflows')
-      // WHY replace the agent instead of mutating the running registration:
-      // Codex and OpenCode receive MCP configuration at process launch. Updating
-      // renderer metadata alone would display an enabled toggle while the
-      // provider still had a cached tools/list response from the old scope.
-      // Replacement keeps visible state and actual capability atomic.
-      await reloadSessionWithBuiltInMcpChoice(workspace, sessionId, 'workflows', enable, {
-        reloaded: enable ? 'Reloaded with Workflow MCP' : 'Reloaded without Workflow MCP',
-        failed: 'Workflow MCP reload failed',
-      })
-    },
-  },
   {
     id: 'reload-agent',
     category: 'session',
diff --git a/src/renderer/src/features/workspace/controlReference.ts b/src/renderer/src/features/workspace/controlReference.ts
index 15c205abe..b15158517 100644
--- a/src/renderer/src/features/workspace/controlReference.ts
+++ b/src/renderer/src/features/workspace/controlReference.ts
@@ -60,7 +60,7 @@ export const controlReference = [
     ],
     "outcome": "The chosen provider or history state is visible and ready for the next step.",
     "cautions": "Use agents.lifecycleRead for supported choices/revisions and nativeHistory.list/prompts for native identities/rewind addresses; nativeHistory.search covers every Claude, Codex and OpenCode conversation in scope by title, name and prompt text; Codex and OpenCode prompt text is searched in the newest rows' recent prompts, not the whole archive. views.preferencesRead/modeSet/followSet expose exact-agent display/follow preferences. Resume, duplicate, switch, reload, rewind and undoRewind report final IDs through operations.read or observations.wait. A live process does not establish input readiness. Provider switch can change the provider conversation identity. Rewind is not a harmless view change.",
-    "commandIds": ["use-global-mcp-settings"]
+    "commandIds": ["agent-mcp-servers"]
   },
   {
     "id": "terminal",
diff --git a/src/renderer/src/features/workspace/surfaces/RootManagementConfirmSurface.tsx b/src/renderer/src/features/workspace/surfaces/RootManagementConfirmSurface.tsx
index 22d352b1b..4be3f3106 100644
--- a/src/renderer/src/features/workspace/surfaces/RootManagementConfirmSurface.tsx
+++ b/src/renderer/src/features/workspace/surfaces/RootManagementConfirmSurface.tsx
@@ -6,8 +6,10 @@ import {
   rootManagementReloadLabels,
 } from '@renderer/features/workspace/lib/rootManagement'
 import { RootManagementConfirmDialog } from '@renderer/features/workspace/ui/RootManagementConfirmDialog'
+import { stopGoalLoopFor } from '@renderer/features/mcp/ui/AgentMcpServersModal'
 import {
   reloadSessionWithBuiltInMcpChoice,
+  reloadSessionWithBuiltInMcpOverrides,
 } from '@renderer/workspace/builtInMcpReload'
 import { useWorkspaceContext } from '@renderer/workspace/WorkspaceContext'
 
@@ -19,6 +21,8 @@ export function RootManagementConfirmSurface() {
   const workspace = useWorkspaceContext()
   const sessionId = useAppStore(state => state.rootManagementPromptSessionId)
   const close = useAppStore(state => state.closeRootManagementPrompt)
+  const stagedOverrides = useAppStore(state => state.rootManagementPromptOverrides)
+  const stopGoalLoop = useAppStore(state => state.rootManagementPromptStopGoalLoop)
   const meta = sessionId ? workspace.state.sessions[sessionId] ?? null : null
   const agentLabel = meta
     ? [meta.title, meta.kind ?? DEFAULT_PROVIDER, cwdBasename(meta.cwd)].filter(Boolean).join(' · ')
@@ -33,6 +37,21 @@ export function RootManagementConfirmSurface() {
       onConfirm={() => {
         if (!sessionId || !meta) return
         close()
+        // From "Agent MCP Servers…": apply every staged choice in this one
+        // reload, with the grant the user just confirmed (#1143).
+        if (stagedOverrides) {
+          // The goal-loop stop (from the staged picker) runs inside the
+          // reload, after its checks, so a declined reload cannot leave a
+          // loop dead while the agent keeps its tools.
+          void reloadSessionWithBuiltInMcpOverrides(
+            workspace,
+            sessionId,
+            { ...stagedOverrides, [ROOT_MANAGEMENT_DOMAIN]: true },
+            rootManagementReloadLabels(true),
+            stopGoalLoop ? stopGoalLoopFor(sessionId) : undefined,
+          )
+          return
+        }
         void reloadSessionWithBuiltInMcpChoice(
           workspace,
           sessionId,
diff --git a/src/renderer/src/ui/GlobalToast.tsx b/src/renderer/src/ui/GlobalToast.tsx
index 1819e6c11..ff66774b1 100644
--- a/src/renderer/src/ui/GlobalToast.tsx
+++ b/src/renderer/src/ui/GlobalToast.tsx
@@ -30,6 +30,12 @@ import { managedSkillsUnavailableMessage } from '@shared/types/tldr'
 
 const MANAGED_SKILLS_WARNING_REPEAT_MS = 60_000
 
+function userMcpUnavailableMessage(servers: readonly { name: string; reason: string }[]): string {
+  const [first] = servers
+  if (servers.length === 1 && first) return `MCP server ${first.name} wasn't attached: ${first.reason}. See Settings → MCP.`
+  return `${servers.length} MCP servers weren't attached (${servers.map(server => server.name).join(', ')}). See Settings → MCP.`
+}
+
 type GlobalToastContextValue = {
   showToast: (message: string, durationMs?: number) => void
 }
@@ -96,6 +102,28 @@ export function GlobalToastProvider({ children }: { children: React.ReactNode })
     showToast(managedSkillsUnavailableMessage(event.skills), 10_000)
   }), [showToast])
 
+  // #1143: a user MCP server an agent asked for was left out of its launch.
+  // Global toast for the managed-skills reasons above (main may launch before
+  // any window claims the pane; a restore fires this per pane). Same repeat
+  // window, keyed by the server+reason set, so one broken server does not
+  // re-raise the same toast for every restored agent.
+  const lastUserMcpWarningRef = useRef<{ key: string; at: number } | null>(null)
+  useEffect(() => window.api.onUserMcpUnavailable?.(event => {
+    const key = event.servers.map(server => `${server.name}:${server.reason}`).sort().join('|')
+    const now = Date.now()
+    const last = lastUserMcpWarningRef.current
+    if (last && last.key === key && now - last.at < MANAGED_SKILLS_WARNING_REPEAT_MS) return
+    lastUserMcpWarningRef.current = { key, at: now }
+    showToast(userMcpUnavailableMessage(event.servers), 10_000)
+  }), [showToast])
+
+  // #1143: an agent changed the user's MCP servers through the mcp_servers
+  // domain. Always surfaced — the user's MCP list decides what code runs in
+  // every future agent, so a change to it must never be silent.
+  useEffect(() => window.api.onUserMcpAgentChange?.(event => {
+    showToast(`${event.message}. See Settings → MCP.`, 8000)
+  }), [showToast])
+
   const dismiss = useCallback(() => {
     if (timerRef.current) {
       clearTimeout(timerRef.current)
diff --git a/src/renderer/src/workspace/builtInMcpReload.ts b/src/renderer/src/workspace/builtInMcpReload.ts
index b5ead7565..b1a3d82c0 100644
--- a/src/renderer/src/workspace/builtInMcpReload.ts
+++ b/src/renderer/src/workspace/builtInMcpReload.ts
@@ -38,6 +38,14 @@ export async function reloadSessionWithBuiltInMcpOverrides(
   sessionId: SessionId,
   overrides: BuiltInMcpOverrides,
   labels: { reloaded: string; failed: string },
+  /**
+   * Runs only once the reload is certain to be attempted — after every check
+   * that can decline it (#1143 review round 2). The per-agent picker uses it to
+   * end a running goal loop whose tools are being removed: stopped earlier, a
+   * declined reload (provisional provider id) left the loop dead while the
+   * agent kept its tools.
+   */
+  beforeReplace?: () => Promise<void>,
 ): Promise<SessionId | undefined> {
   const meta = workspace.state.sessions[sessionId]
   const kind = meta?.kind ?? DEFAULT_PROVIDER
@@ -52,6 +60,9 @@ export async function reloadSessionWithBuiltInMcpOverrides(
     return undefined
   }
   try {
+    // Awaited only when present: `await undefined` still yields a tick, which
+    // moved every plain capability reload one microtask later than before.
+    if (beforeReplace) await beforeReplace()
     const newSessionId = await workspace.replaceSession(meta.cwd, {
       kind,
       targetSessionId: sessionId,
diff --git a/src/renderer/src/workspace/hook/actions/mcpPreferences.renderer.test.tsx b/src/renderer/src/workspace/hook/actions/mcpPreferences.renderer.test.tsx
index 5b393646e..ae73509db 100644
--- a/src/renderer/src/workspace/hook/actions/mcpPreferences.renderer.test.tsx
+++ b/src/renderer/src/workspace/hook/actions/mcpPreferences.renderer.test.tsx
@@ -3,8 +3,11 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 import { CONFIGURABLE_BUILT_IN_MCP_DOMAINS } from '@mcp/shared/types'
 import type { SessionSpawnOptions } from '@preload/api/types'
 import { emptyRuntime, type SessionRuntime } from '@renderer/session-runtime/state'
-import { sessionCommands } from '@renderer/features/workspace/commands/sessionCommands'
-import type { CommandContext } from '@renderer/features/command-palette/types'
+import type { BuiltInMcpDomain } from '@mcp/shared/types'
+import {
+  reloadSessionWithBuiltInMcpChoice,
+  reloadSessionWithBuiltInMcpOverrides,
+} from '@renderer/workspace/builtInMcpReload'
 import { useSessionActions } from './session'
 import { useProviderActions } from './provider'
 import { makeRefs, stateWriter } from './testing/paneActionsHarness'
@@ -41,14 +44,15 @@ function setup(meta: Partial<SessionMeta> = { builtInMcpDomains: [], builtInMcpO
   })
   // The commanded session: the focused lane's occupant. (Tree era: the tab's focus.)
   const focused = () => writer.getState().stage.lanes[writer.getState().stage.focusedLane]!.selectedSessionId!
-  const command = async (id: string) => {
-    const run = sessionCommands.find(item => item.id === id)!.run
-    await run({ workspace: {
-      state: writer.getState(), replaceSession: hook.result.current.sessions.replaceSession,
-      showPaneToast: vi.fn(),
-    }, ui: { closePalette: vi.fn() } } as unknown as CommandContext)
-  }
-  return { refs, writer, hook, spawnSession, focused, command }
+  const workspace = () => ({
+    state: writer.getState(), replaceSession: hook.result.current.sessions.replaceSession,
+    showPaneToast: vi.fn(),
+  })
+  const reload = (domain: BuiltInMcpDomain, enabled: boolean) =>
+    reloadSessionWithBuiltInMcpChoice(workspace(), focused(), domain, enabled, { reloaded: 'ok', failed: 'failed' })
+  const reset = () =>
+    reloadSessionWithBuiltInMcpOverrides(workspace(), focused(), {}, { reloaded: 'ok', failed: 'failed' })
+  return { refs, writer, hook, spawnSession, focused, reload, reset }
 }
 
 async function perform(operation: () => Promise<unknown>) {
@@ -72,39 +76,38 @@ describe('global MCP preferences at actual provider replacement', () => {
     expect(h.writer.getState().sessions[h.focused()]!.tldrIdentity).toBe(first.tldrIdentity)
   })
 
-  it.each([
-    { domain: 'tldr', commandId: 'enable-tldr-mcp' },
-    { domain: 'goal', commandId: 'enable-goal-mcp' },
-    // #1006: the sibling command goal_loop lacked.
-    { domain: 'goal_loop', commandId: 'enable-goal-loop-mcp' },
-  ] as const)('preserves a per-agent $domain off override and lets the reset command restore inheritance', async ({ domain, commandId }) => {
+  // These drove the per-capability commands until #1143 retired them into
+  // Agent MCP Servers…; the picker writes through the same reload owner, so the
+  // preference policy is pinned at that owner directly.
+  it.each(['tldr', 'goal', 'goal_loop'] as const)('preserves a per-agent %s off override and lets a reset restore inheritance', async domain => {
     const h = setup({ builtInMcpDomains: [domain], builtInMcpOverrides: {} })
     h.refs.defaultBuiltInMcpDomainsRef.current = [domain]
-    await perform(() => h.command(commandId))
+    await perform(() => h.reload(domain, false))
     expect(h.writer.getState().sessions[h.focused()]!.builtInMcpOverrides).toEqual({ [domain]: false })
     h.refs.defaultBuiltInMcpDomainsRef.current = [domain, 'orchestration']
     await perform(() => h.hook.result.current.provider.reloadSessionAgent(h.focused()))
     expect(h.spawnSession.mock.calls.at(-1)![0].builtInMcpDomains).toEqual(['orchestration'])
-    await perform(() => h.command('use-global-mcp-settings'))
+    await perform(() => h.reset())
     expect(h.spawnSession.mock.calls.at(-1)![0].builtInMcpDomains).toEqual([domain, 'orchestration'])
     expect(h.writer.getState().sessions[h.focused()]!.builtInMcpOverrides).toEqual({})
   })
 
-  it('ends a running goal loop when its tools are turned off (#1045 review)', async () => {
-    // The loop is harness-owned and survives the reload, but the reloaded
-    // agent has no goal_loop_complete: it could never report success, and
-    // every continuation would run to the cap. The stop names the session the
-    // loop is filed under, before the replacement exists.
-    const controlGoalLoop = vi.fn(async () => null)
-    const h = setup({ builtInMcpDomains: ['goal_loop'], builtInMcpOverrides: {} })
-    window.api = { ...window.api, controlGoalLoop }
-    h.refs.defaultBuiltInMcpDomainsRef.current = ['goal_loop']
-    await perform(() => h.command('enable-goal-loop-mcp'))
-    expect(controlGoalLoop).toHaveBeenCalledWith({ sessionId: 'original', action: 'stop' })
-    // Turning them back ON must not touch the loop.
-    controlGoalLoop.mockClear()
-    await perform(() => h.command('enable-goal-loop-mcp'))
-    expect(controlGoalLoop).not.toHaveBeenCalled()
+  it('applies each provider its own built-in defaults (#1143)', async () => {
+    const h = setup({ builtInMcpDomains: [], builtInMcpOverrides: {} })
+    h.refs.defaultBuiltInMcpDomainsRef.current = {
+      claude: ['tldr'], codex: ['orchestration'], opencode: [], grok: [],
+    }
+    await perform(() => h.hook.result.current.provider.reloadSessionAgent(h.focused()))
+    // The fixture agent is Codex, so it gets Codex's column and not Claude's.
+    expect(h.spawnSession.mock.calls.at(-1)![0].builtInMcpDomains).toEqual(['orchestration'])
+  })
+
+  it('sends only the pane\'s user-server choices to main, never a resolved list (#1143)', async () => {
+    const h = setup({ builtInMcpDomains: [], builtInMcpOverrides: { tldr: true, 'user:srv-beeper': false } })
+    await perform(() => h.hook.result.current.provider.reloadSessionAgent(h.focused()))
+    expect(h.spawnSession.mock.calls.at(-1)![0].userMcpOverrides).toEqual({ 'srv-beeper': false })
+    // And the choice survives the replacement, like a built-in override does.
+    expect(h.writer.getState().sessions[h.focused()]!.builtInMcpOverrides).toMatchObject({ 'user:srv-beeper': false })
   })
 
   it('migrates a legacy agent and resolves bulk reload through the same preference policy', async () => {
diff --git a/src/renderer/src/workspace/hook/actions/session.ts b/src/renderer/src/workspace/hook/actions/session.ts
index 316e6f65b..0e40649c5 100644
--- a/src/renderer/src/workspace/hook/actions/session.ts
+++ b/src/renderer/src/workspace/hook/actions/session.ts
@@ -17,6 +17,7 @@ import { clearLiveEntryWindowSession } from '@renderer/session-runtime/liveEntry
 import type { SessionId, SessionKind, SessionMeta, WorkspaceState } from '@renderer/workspace/types'
 import type { BuiltInMcpDomain, BuiltInMcpOverrides } from '@mcp/shared/types'
 import { resolveSessionBuiltInMcpDomains, sessionMcpOverrides, spawnMcpOverrides } from '@renderer/workspace/mcpDomains'
+import { userMcpOverridesFrom } from '@shared/userMcp/types'
 import {
   clearTiledLaneSessions,
   remapTiledLanes,
@@ -400,6 +401,7 @@ export function useSessionActions(
       let sessionId: SessionId
       let tmuxName: string | undefined
       let startedProviderSessionId: string | undefined
+      let startedUserMcpServerIds: string[] | undefined
       // What this spawn reserved, if anything. `replaceSession` owns the
       // release for every path AFTER spawn resolves, but it never sees an id
       // when spawn THROWS — and by then the successor may already be
@@ -428,10 +430,14 @@ export function useSessionActions(
             useProxy,
             recoverTmuxName: opts?.recoverTmuxName,
             builtInMcpDomains,
+            // Only the pane's explicit choices cross; main applies Settings,
+            // secrets and support itself (#1143, spec Revision 2 §4).
+            ...(isAgentProviderKind(kind) ? { userMcpOverrides: userMcpOverridesFrom(builtInMcpOverrides) } : {}),
           })
           sessionId = result.sessionId
           tmuxName = result.tmuxName
           startedProviderSessionId = result.providerSessionId
+          startedUserMcpServerIds = result.userMcpServerIds
           // WHY the reservation happens HERE, before this function's own commit:
           //
           // The gap the reconciler exploits opens the moment the successor's
@@ -503,6 +509,7 @@ export function useSessionActions(
           ...(isAgentProviderKind(kind) && builtInMcpDomains !== undefined
             ? { builtInMcpDomains, builtInMcpOverrides }
             : {}),
+          ...(isAgentProviderKind(kind) ? { userMcpServerIds: startedUserMcpServerIds ?? [] } : {}),
         }
         setState(prev => ({
           ...prev,
@@ -773,6 +780,7 @@ export function useSessionActions(
             cwd: meta.cwd,
             resumeSessionId,
             builtInMcpDomains,
+            ...(isAgentProviderKind(kind) ? { userMcpOverrides: userMcpOverridesFrom(builtInMcpOverrides) } : {}),
             recoverTmuxName: kind === 'terminal' ? meta.tmuxName : undefined,
             dangerousMode: isAgentSessionKind(kind) ? refs.dangerousAgentsRef.current : undefined,
             useProxy: isAgentSessionKind(kind) ? refs.useProxyStreamingRef.current : undefined,
@@ -1046,6 +1054,11 @@ export function useSessionActions(
           ...(recoveredBuiltInMcpDomains !== undefined
             ? { builtInMcpDomains: recoveredBuiltInMcpDomains }
             : {}),
+          // Same rule as the built-in domains above: an adopted backend keeps
+          // the servers it was launched with, and only main knows which.
+          ...(recoverySnapshot?.userMcpServerIds !== undefined
+            ? { userMcpServerIds: recoverySnapshot.userMcpServerIds }
+            : {}),
           ...(recoveredTmuxName ? { tmuxName: recoveredTmuxName } : {}),
         }
         // The wake genuinely succeeded: recovery resolved, readiness either
@@ -1583,7 +1596,7 @@ export function useSessionActions(
               : undefined
           const resumeSessionId = resumableProviderSessionId(meta)
           const restoredMeta = withoutProvisionalProviderSession(meta)
-          const { sessionId: newId } = await window.api.spawnSession({
+          const { sessionId: newId, userMcpServerIds } = await window.api.spawnSession({
             tldrIdentity: tldrIdentityForSession(oldId, meta),
             kind,
             providerRuntime: meta.providerRuntime,
@@ -1592,6 +1605,7 @@ export function useSessionActions(
             dangerousMode,
             useProxy: isAgentSessionKind(kind) ? refs.useProxyStreamingRef.current : undefined,
             builtInMcpDomains,
+            ...(isAgentProviderKind(kind) ? { userMcpOverrides: userMcpOverridesFrom(builtInMcpOverrides) } : {}),
           })
           idMap.set(oldId, newId)
           freshSessions[newId] = {
@@ -1606,6 +1620,7 @@ export function useSessionActions(
             ...restoredMeta,
             tldrIdentity: tldrIdentityForSession(oldId, meta),
             ...(builtInMcpDomains !== undefined ? { builtInMcpDomains, builtInMcpOverrides } : {}),
+            ...(userMcpServerIds !== undefined ? { userMcpServerIds } : {}),
           }
         } catch {
           failedIds.add(oldId)
diff --git a/src/renderer/src/workspace/hook/actions/sessionReplacementHandoff.renderer.test.tsx b/src/renderer/src/workspace/hook/actions/sessionReplacementHandoff.renderer.test.tsx
index 20b11f70d..7a029e730 100644
--- a/src/renderer/src/workspace/hook/actions/sessionReplacementHandoff.renderer.test.tsx
+++ b/src/renderer/src/workspace/hook/actions/sessionReplacementHandoff.renderer.test.tsx
@@ -143,6 +143,8 @@ describe('renderer session replacement handoff', () => {
       useProxy: destination === 'terminal' ? undefined : true,
       recoverTmuxName: undefined,
       builtInMcpDomains: destination === 'terminal' ? undefined : destination === 'codex' ? ['workflows'] : [],
+      // Agents carry the pane's user MCP choices to main (#1143); terminals never do.
+      ...(destination === 'terminal' ? {} : { userMcpOverrides: {} }),
     })
     // A transaction-bearing result means main already retired the predecessor
     // and is holding the successor pending durable workspace ownership. Sending
@@ -173,6 +175,7 @@ describe('renderer session replacement handoff', () => {
       useProxy: true,
       recoverTmuxName: undefined,
       builtInMcpDomains: [],
+      userMcpOverrides: {},
     })
   })
 })
diff --git a/src/renderer/src/workspace/hook/index.ts b/src/renderer/src/workspace/hook/index.ts
index 4bfd92194..a2a9ba27c 100644
--- a/src/renderer/src/workspace/hook/index.ts
+++ b/src/renderer/src/workspace/hook/index.ts
@@ -2,7 +2,7 @@ import { createElement, useCallback, useEffect, useLayoutEffect, useMemo, useRef
 
 import { useAppStore } from '@renderer/app-state/hooks'
 import { useGlobalToast } from '@renderer/ui/GlobalToast'
-import type { ConfigurableBuiltInMcpDomain } from '@mcp/shared/types'
+import type { BuiltInMcpDefaultsInput } from '@mcp/shared/types'
 import { DEFAULT_PROVIDER, isAgentProviderKind } from '@shared/types/providerKind'
 import type { AgentViewModeOverride, SessionId } from '@renderer/workspace/types'
 
@@ -79,7 +79,7 @@ export type Workspace = ReturnType<typeof useWorkspace>
 export function useWorkspace(
   dangerousAgentsEnabled = false,
   useProxyStreaming = false,
-  defaultBuiltInMcpDomains: ConfigurableBuiltInMcpDomain[] = [],
+  defaultBuiltInMcpDomains: BuiltInMcpDefaultsInput = [],
 ) {
   // ---- Zustand subscriptions (these drive re-renders) ----
   const { showToast } = useGlobalToast()
diff --git a/src/renderer/src/workspace/hook/orchestrationRuntime.renderer.test.tsx b/src/renderer/src/workspace/hook/orchestrationRuntime.renderer.test.tsx
index e13167cb5..0f6478e7d 100644
--- a/src/renderer/src/workspace/hook/orchestrationRuntime.renderer.test.tsx
+++ b/src/renderer/src/workspace/hook/orchestrationRuntime.renderer.test.tsx
@@ -77,6 +77,7 @@ describe('renderer orchestration runtime creation', () => {
     expect(spawnSession).toHaveBeenCalledExactlyOnceWith({
       kind: 'opencode', providerRuntime: terminal ? 'terminal' : undefined, cwd: '/repo/child', resumeSessionId: undefined,
       dangerousMode: false, useProxy: false, recoverTmuxName: undefined, builtInMcpDomains: ['orchestration'],
+      userMcpOverrides: {},
     })
     const ownership = {
       orchestrationParentId: 'parent', orchestrationRootId: 'root', orchestrationRunId: 'run-review', orchestrationRole: 'reviewer',
diff --git a/src/renderer/src/workspace/hook/persistence/rehydrate.ts b/src/renderer/src/workspace/hook/persistence/rehydrate.ts
index 64a176738..3198e5cf8 100644
--- a/src/renderer/src/workspace/hook/persistence/rehydrate.ts
+++ b/src/renderer/src/workspace/hook/persistence/rehydrate.ts
@@ -38,6 +38,7 @@ import type {
 } from '@renderer/workspace/hook/context'
 import type { WorkspaceRefs } from '@renderer/workspace/hook/refs'
 import { resolveSessionBuiltInMcpDomains, sessionMcpOverrides } from '@renderer/workspace/mcpDomains'
+import { userMcpOverridesFrom } from '@shared/userMcp/types'
 import * as perf from '@renderer/performance/client'
 import { reportLifecycle } from '@renderer/lifecycle/report'
 import { loadInitialHistoryForSession } from '@renderer/workspace/hook/actions/initialHistory'
@@ -676,6 +677,9 @@ export async function rehydrateWorkspace(
             useProxy: isAgentSessionKind(kind) ? refs.useProxyStreamingRef.current : undefined,
             recoverTmuxName: kind === 'terminal' ? meta.tmuxName : undefined,
             builtInMcpDomains,
+            // User MCP choices ride the same path as the built-in domains
+            // (#1143); main uses them only if it has to start the backend.
+            ...(isAgentProviderKind(kind) ? { userMcpOverrides: userMcpOverridesFrom(builtInMcpOverrides) } : {}),
             // Only bootstrap can prove the predecessor ID still came from the
             // durable workspace. Ordinary retry/wake calls must not be able to
             // abort a same-pane replacement transaction.
@@ -739,6 +743,9 @@ export async function rehydrateWorkspace(
             ...(recoveredBuiltInMcpDomains !== undefined
               ? { builtInMcpDomains: recoveredBuiltInMcpDomains }
               : {}),
+            ...(recovery.snapshot.userMcpServerIds !== undefined
+              ? { userMcpServerIds: recovery.snapshot.userMcpServerIds }
+              : {}),
             ...(recovery.tmuxName ? { tmuxName: recovery.tmuxName } : {}),
           }
           recoveryOutcomes.set(newId, {
diff --git a/src/renderer/src/workspace/hook/refs.ts b/src/renderer/src/workspace/hook/refs.ts
index 459b64151..16bc7f5e7 100644
--- a/src/renderer/src/workspace/hook/refs.ts
+++ b/src/renderer/src/workspace/hook/refs.ts
@@ -9,7 +9,7 @@ import type {
   SpotlightState,
 } from '@renderer/workspace/types'
 import type { SessionId, WorkspaceState } from '@renderer/workspace/types'
-import type { ConfigurableBuiltInMcpDomain } from '@mcp/shared/types'
+import type { BuiltInMcpDefaultsInput } from '@mcp/shared/types'
 
 // -----------------------------------------------------------------------------
 // Ref factory for the workspace hook.
@@ -32,7 +32,7 @@ export type WorkspaceRefs = {
   latestRuntimesRef: MutableRefObject<Record<SessionId, SessionRuntime>>
   dangerousAgentsRef: MutableRefObject<boolean>
   useProxyStreamingRef: MutableRefObject<boolean>
-  defaultBuiltInMcpDomainsRef: MutableRefObject<ConfigurableBuiltInMcpDomain[]>
+  defaultBuiltInMcpDomainsRef: MutableRefObject<BuiltInMcpDefaultsInput>
   seenUuidsRef: MutableRefObject<Record<SessionId, Set<string>>>
   /** History-boundary window identity per session (grok Stage 5). Decisions
    *  come from session-runtime/historyBoundary.ts — the phone and replay apply
@@ -70,7 +70,7 @@ export function useWorkspaceRefs(
   initialRuntimes: Record<SessionId, SessionRuntime>,
   dangerousAgentsEnabled: boolean,
   useProxyStreaming: boolean,
-  defaultBuiltInMcpDomains: ConfigurableBuiltInMcpDomain[],
+  defaultBuiltInMcpDomains: BuiltInMcpDefaultsInput,
 ): WorkspaceRefs {
   // Each `useRef(...)` already hands back a stable ref OBJECT across
   // renders. But the surrounding `{ ... }` literal does NOT — without
diff --git a/src/renderer/src/workspace/mcpDomains.test.ts b/src/renderer/src/workspace/mcpDomains.test.ts
index 836672be2..7767e3edd 100644
--- a/src/renderer/src/workspace/mcpDomains.test.ts
+++ b/src/renderer/src/workspace/mcpDomains.test.ts
@@ -2,6 +2,7 @@ import { describe, expect, it } from 'vitest'
 
 import {
   clonedMcpOverrides,
+  normalizeBuiltInMcpOverrides,
   normalizeSessionBuiltInMcpDomains,
   resolveSessionBuiltInMcpDomains,
   withNormalizedBuiltInMcpDomains,
@@ -80,3 +81,31 @@ describe('capability choices a clone may inherit', () => {
     expect(source.builtInMcpOverrides).toEqual({ root_management: true, tldr: true })
   })
 })
+
+describe('user MCP server choices in the override map (#1143)', () => {
+  it('keeps well-formed user: keys through normalization and drops malformed ones', () => {
+    expect(normalizeBuiltInMcpOverrides({
+      tldr: false,
+      'user:srv-beeper': true,
+      'user:bad id': true,
+      'user:': true,
+      somethingElse: true,
+    })).toEqual({ tldr: false, 'user:srv-beeper': true })
+  })
+
+  it('carries user-server choices into a duplicate, like built-in ones', () => {
+    // A clone that silently lost its servers would not be a duplicate; only
+    // the confirmation-gated root grant is withheld.
+    expect(clonedMcpOverrides({
+      builtInMcpOverrides: { 'user:srv-beeper': true, root_management: true },
+    })).toEqual({ 'user:srv-beeper': true })
+  })
+
+  it('resolves built-in domains from the per-provider Settings map', () => {
+    const defaults = { claude: ['tldr' as const], codex: ['workflows' as const], opencode: [], grok: [] }
+    expect(resolveSessionBuiltInMcpDomains({ provider: 'claude', sessionOverrides: {}, defaultDomains: defaults }))
+      .toEqual(['tldr'])
+    expect(resolveSessionBuiltInMcpDomains({ provider: 'codex', sessionOverrides: {}, defaultDomains: defaults }))
+      .toEqual(['workflows'])
+  })
+})
diff --git a/src/renderer/src/workspace/mcpDomains.ts b/src/renderer/src/workspace/mcpDomains.ts
index f866785ec..170c861e0 100644
--- a/src/renderer/src/workspace/mcpDomains.ts
+++ b/src/renderer/src/workspace/mcpDomains.ts
@@ -1,11 +1,13 @@
 import {
   BUILT_IN_MCP_DOMAINS,
+  builtInMcpDefaultsFor,
   CONFIRMATION_GATED_BUILT_IN_MCP_DOMAINS,
   filterBuiltInMcpDomainsForProvider,
   normalizeBuiltInMcpDomains,
 } from '@mcp/shared/types'
 import type { BuiltInMcpDomain, BuiltInMcpOverrides } from '@mcp/shared/types'
 import type { AgentProviderKind } from '@shared/types/providerKind'
+import { userMcpOverrideKey, userMcpOverridesFrom } from '@shared/userMcp/types'
 
 export function normalizeSessionBuiltInMcpDomains(
   value: unknown,
@@ -42,8 +44,11 @@ export function resolveSessionBuiltInMcpDomains(params: {
   defaultDomains: unknown
   sessionOverrides?: BuiltInMcpOverrides
 }): BuiltInMcpDomain[] {
+  // `defaultDomains` is either the per-provider Settings map or a flat list
+  // meaning "every provider" (BuiltInMcpDefaultsInput); pick this provider's.
+  const defaults = builtInMcpDefaultsFor(params.defaultDomains, params.provider)
   if (params.sessionOverrides !== undefined) {
-    const requested = new Set(normalizeBuiltInMcpDomains(params.defaultDomains))
+    const requested = new Set<BuiltInMcpDomain>(defaults)
     for (const domain of BUILT_IN_MCP_DOMAINS) {
       if (params.sessionOverrides[domain] === true) requested.add(domain)
       else if (params.sessionOverrides[domain] === false) requested.delete(domain)
@@ -55,16 +60,20 @@ export function resolveSessionBuiltInMcpDomains(params: {
   // defaults into it would report tools the live process does not actually
   // serve; only an absent list (a legacy pane that never recorded one) may fall
   // back to Settings.
-  const requested = explicit ?? normalizeBuiltInMcpDomains(params.defaultDomains)
+  const requested = explicit ?? defaults
   return filterBuiltInMcpDomainsForProvider(params.provider, requested)
 }
 
 export function normalizeBuiltInMcpOverrides(value: unknown): BuiltInMcpOverrides | undefined {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return undefined
-  return Object.fromEntries(BUILT_IN_MCP_DOMAINS.flatMap(domain => {
+  const builtIn = BUILT_IN_MCP_DOMAINS.flatMap(domain => {
     const choice = (value as Record<string, unknown>)[domain]
     return Object.prototype.hasOwnProperty.call(value, domain) && typeof choice === 'boolean' ? [[domain, choice]] : []
-  }))
+  })
+  // User-server choices (#1143) survive normalization; the key format is
+  // validated so a hand-edited workspace cannot smuggle arbitrary keys in.
+  const user = Object.entries(userMcpOverridesFrom(value)).map(([id, choice]) => [userMcpOverrideKey(id), choice])
+  return Object.fromEntries([...builtIn, ...user])
 }
 
 export function sessionMcpOverrides(meta: { builtInMcpDomains?: BuiltInMcpDomain[]; builtInMcpOverrides?: BuiltInMcpOverrides }): BuiltInMcpOverrides {
diff --git a/src/renderer/src/workspace/types.ts b/src/renderer/src/workspace/types.ts
index 04f84f97e..5fe4029f5 100644
--- a/src/renderer/src/workspace/types.ts
+++ b/src/renderer/src/workspace/types.ts
@@ -284,6 +284,10 @@ export type SessionMeta = {
   /** Durable per-domain choices. {} inherits every global preference; missing
    * maps belong to legacy snapshots and migrate via sessionMcpOverrides. */
   builtInMcpOverrides?: BuiltInMcpOverrides
+  /** User MCP server ids (#1143) the last known provider process was launched
+   * with, as reported by main. Observed, like `builtInMcpDomains`; the choices
+   * behind it live in `builtInMcpOverrides` under `user:<id>` keys. */
+  userMcpServerIds?: string[]
   /**
    * Project membership (#992). THE ownership fact: a session belongs to the
    * workspace because it names a live project. It replaces all three ways a
diff --git a/src/shared/types/session.ts b/src/shared/types/session.ts
index fe4e60cb5..d7a77cbc8 100644
--- a/src/shared/types/session.ts
+++ b/src/shared/types/session.ts
@@ -2,6 +2,7 @@ import type {
   BuiltInMcpDomain,
   BuiltInMcpServerConfig,
 } from '@mcp/shared/types.js'
+import type { ResolvedUserMcpServer } from '@shared/userMcp/types.js'
 import type { ProviderConditionSnapshot } from '@shared/types/providerConditions.js'
 import type { AgentProviderRuntime, SessionKind } from '@shared/types/providerKind.js'
 import type { KillCaller } from '@shared/lifecycle/events.js'
@@ -83,6 +84,11 @@ export type SessionBackendSnapshot = {
    *  observed backend fact, not the renderer's requested policy. It is absent
    *  for terminal sessions, which never receive built-in MCP configuration. */
   builtInMcpDomains?: BuiltInMcpDomain[]
+  /** Ids of the user MCP servers (#1143) this backend was launched with. Like
+   *  `builtInMcpDomains`, an observed launch fact reported by main, never the
+   *  renderer's request: main applies defaults, secrets and support at launch,
+   *  and an adopted process keeps whatever it started with. */
+  userMcpServerIds?: string[]
   /** Main-owned logical summary identity when this backend exposes TLDR. */
   tldrIdentity?: string
 }
@@ -100,6 +106,10 @@ export type SessionRecoverOptions = {
   recoverTmuxName?: string
   tldrIdentity?: string
   builtInMcpDomains?: BuiltInMcpDomain[]
+  /** The pane's explicit per-agent user MCP choices (bare server id → on/off).
+   *  Used only if recovery has to START a backend; an adopted one keeps the
+   *  servers it was launched with. */
+  userMcpOverrides?: Record<string, boolean>
   /**
    * Opaque renderer-generated generation for this recovery admission.
    *
@@ -685,6 +695,13 @@ export type SessionOptions = {
    *  never the long-lived domain policy; the renderer/session metadata remains
    *  the source of truth for which domains should be enabled. */
   builtInMcpServers?: BuiltInMcpServerConfig[]
+  /** User MCP servers (#1143) already validated, secret-resolved and filtered
+   *  by main for this launch and this provider. Providers only translate them;
+   *  they never decide which ones apply. */
+  userMcpServers?: ResolvedUserMcpServer[]
+  /** Codex only: how to send shell exclusions for the user-server secrets it
+   *  carries, matching the user's own config (see CodexShellPolicyStyle). */
+  userMcpCodexShellPolicy?: { style: 'filters' } | { style: 'legacy'; exclude: readonly string[] }
   /**
    * Main-owned one-shot boundary invoked by a resumed provider immediately
    * before it acquires exclusive durable-transcript ownership.
diff --git a/src/shared/userMcp/importConfig.ts b/src/shared/userMcp/importConfig.ts
new file mode 100644
index 000000000..b24698237
--- /dev/null
+++ b/src/shared/userMcp/importConfig.ts
@@ -0,0 +1,168 @@
+import { hasInputReference } from './inputs.js'
+import type {
+  UserMcpImportCandidate,
+  UserMcpImportResult,
+  UserMcpInput,
+  UserMcpServerEntry,
+} from './types.js'
+import {
+  coerceInputs,
+  isPlainObject,
+  isStringRecord,
+  normalizeEntry,
+  referencedInputIds,
+  transportOf,
+  validateServer,
+} from './validate.js'
+
+/**
+ * Turn a pasted config snippet into candidate servers.
+ *
+ * Accepted shapes, in detection order:
+ *  1. `{"mcpServers": {...}}` — Claude Code / Claude Desktop / Cursor, and what
+ *     almost every server README publishes.
+ *  2. `{"servers": {...}, "inputs": [...]}` — VS Code's mcp.json.
+ *  3. `{"<name>": {command|url…}, …}` — the inner map on its own, which is what
+ *     people copy when they grab "just the server part".
+ *  4. `{command|url…}` — one bare entry; the caller supplies the name.
+ *
+ * WHY every literal env/header value becomes a secret input: we cannot tell a
+ * token from a log level by looking at the key (`KEY`, `AUTH`, `X-Api-Key`,
+ * `DATABASE_URL`…), and guessing wrong in the permissive direction writes a
+ * credential into a plaintext JSON file. The built-in launcher made the same
+ * call for the same reason (builtInMcpLaunch.ts: "avoids having to guess which
+ * future header names are sensitive"). A user can edit a non-sensitive value
+ * back to a literal afterwards; the reverse mistake cannot be undone.
+ */
+export function importUserMcpConfig(text: string, fallbackName = 'server'): UserMcpImportResult {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch (error) {
+    return {
+      ok: false,
+      error: `Not valid JSON: ${error instanceof Error ? error.message : String(error)}`,
+    }
+  }
+  if (!isPlainObject(parsed)) return { ok: false, error: 'Paste a JSON object.' }
+
+  let format: 'mcpServers' | 'vscode' | 'map' | 'entry'
+  let rawServers: Record<string, unknown>
+  let vscodeInputs: UserMcpInput[] = []
+  if (isPlainObject(parsed.mcpServers)) {
+    format = 'mcpServers'
+    rawServers = parsed.mcpServers
+  } else if (isPlainObject(parsed.servers)) {
+    format = 'vscode'
+    rawServers = parsed.servers
+    vscodeInputs = vscodeInputDefinitions(parsed.inputs)
+  } else if (transportOf(parsed) !== null || 'command' in parsed || 'url' in parsed) {
+    format = 'entry'
+    rawServers = { [fallbackName]: parsed }
+  } else if (Object.values(parsed).length > 0 && Object.values(parsed).every(isPlainObject)) {
+    format = 'map'
+    rawServers = parsed
+  } else {
+    return {
+      ok: false,
+      error: 'No MCP server found. Paste an "mcpServers" block, a VS Code "servers" block, or one server entry.',
+    }
+  }
+
+  const names = Object.keys(rawServers)
+  if (names.length === 0) return { ok: false, error: 'The config contains no servers.' }
+
+  const candidates: UserMcpImportCandidate[] = []
+  for (const name of names) {
+    const raw = rawServers[name]
+    if (!isPlainObject(raw)) continue
+    candidates.push(candidateFor(name, raw, vscodeInputs, candidates))
+  }
+  return { ok: true, candidates, format }
+}
+
+function candidateFor(
+  name: string,
+  raw: Record<string, unknown>,
+  vscodeInputs: readonly UserMcpInput[],
+  earlier: readonly UserMcpImportCandidate[],
+): UserMcpImportCandidate {
+  const inputs: UserMcpInput[] = []
+  const pendingSecrets: Record<string, string> = {}
+  const takenIds = new Set<string>(vscodeInputs.map(input => input.id))
+  const entry: Record<string, unknown> = { ...raw }
+
+  const liftRecord = (field: 'env' | 'headers') => {
+    const record = entry[field]
+    if (!isStringRecord(record)) return
+    const next: Record<string, string> = {}
+    for (const [key, value] of Object.entries(record)) {
+      if (value === '' || hasInputReference(value)) {
+        next[key] = value
+        continue
+      }
+      const id = uniqueInputId(`${name}-${key}`, takenIds)
+      // `Authorization: Bearer <token>` is the dominant header shape, and the
+      // scheme word is not secret. Keeping it in the entry means the stored
+      // secret is exactly what the server's settings page hands the user.
+      const scheme = /^(Bearer|Token|Basic)\s+(.+)$/i.exec(value)
+      next[key] = scheme ? `${scheme[1]} \${input:${id}}` : `\${input:${id}}`
+      const secret = scheme ? scheme[2]! : value
+      inputs.push({ id, description: `${field === 'env' ? 'Environment variable' : 'Header'} ${key}` })
+      // README placeholders ("YOUR_TOKEN_HERE", "<api-key>") are not secrets.
+      // Storing them would make the server look configured and then fail at
+      // tool-call time; leaving the input empty shows "secret not set" instead.
+      if (!isPlaceholder(secret)) pendingSecrets[id] = secret
+    }
+    entry[field] = next
+  }
+  liftRecord('env')
+  liftRecord('headers')
+
+  // VS Code inputs referenced by this entry come along as secret inputs.
+  const referencedVscode = vscodeInputs.filter(input =>
+    JSON.stringify(entry).includes(`\${input:${input.id}}`))
+  inputs.unshift(...referencedVscode)
+  // Any other `${input:id}` reference gets a definition too (review round 2):
+  // a hand-written reference, or our own sanitized text being re-parsed after
+  // the user edited it, used to import with no input at all and then fail
+  // save with "no secret named …".
+  for (const id of referencedInputIds(entry as UserMcpServerEntry)) {
+    if (!inputs.some(input => input.id === id)) inputs.push({ id, description: 'Secret' })
+  }
+
+  const normalized = normalizeEntry(entry as UserMcpServerEntry)
+  const problems = validateServer(
+    { name, entry: normalized, inputs },
+    earlier.map(candidate => ({ id: candidate.name, name: candidate.name })),
+  )
+  return { name, entry: normalized, inputs, pendingSecrets, problems }
+}
+
+function vscodeInputDefinitions(value: unknown): UserMcpInput[] {
+  if (!Array.isArray(value)) return []
+  // Every VS Code input becomes a secret regardless of `password`: the value
+  // is supplied by the user at setup time either way, and treating it as a
+  // secret only costs a masked field.
+  return coerceInputs(value.map(input =>
+    isPlainObject(input)
+      ? { id: input.id, description: typeof input.description === 'string' ? input.description : '' }
+      : input))
+}
+
+function uniqueInputId(seed: string, taken: Set<string>): string {
+  const base = seed.toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'secret'
+  let id = base
+  for (let n = 2; taken.has(id); n++) id = `${base}-${n}`
+  taken.add(id)
+  return id
+}
+
+// `${VAR}` / `${env:VAR}` (review round 1): Claude/Cursor configs reference
+// the user's environment this way. Stored as a secret it would be sent
+// literally, so the server looks configured and fails at tool-call time.
+const PLACEHOLDER = /^(<[^>]*>|\[[^\]]*\]|\.\.\.|x{3,}|your[\s_-].*|.*[\s_-]here|changeme|replace[\s_-]?me|token|api[\s_-]?key|\$\{[^}]+\})$/i
+
+export function isPlaceholder(value: string): boolean {
+  return PLACEHOLDER.test(value.trim())
+}
diff --git a/src/shared/userMcp/inputs.ts b/src/shared/userMcp/inputs.ts
new file mode 100644
index 000000000..706edd77b
--- /dev/null
+++ b/src/shared/userMcp/inputs.ts
@@ -0,0 +1,40 @@
+// `${input:<id>}` references — VS Code's MCP secret syntax (`inputs` with
+// `password: true`), adopted verbatim so a VS Code config pastes unchanged and
+// so users see a syntax they may already know instead of one we invented.
+
+const INPUT_REFERENCE = /\$\{input:([A-Za-z0-9_-]{1,64})\}/g
+
+export const USER_MCP_INPUT_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/
+
+export function inputReferences(value: string): string[] {
+  return [...value.matchAll(INPUT_REFERENCE)].map(match => match[1]!)
+}
+
+export function hasInputReference(value: string): boolean {
+  return inputReferences(value).length > 0
+}
+
+/**
+ * Replace every reference with its secret value.
+ *
+ * Returns null when any referenced value is missing. WHY not substitute an
+ * empty string: an `Authorization: Bearer ` header or an empty API key makes the
+ * server fail in a confusing, server-specific way at tool-call time. Refusing
+ * here lets main drop the server with an explicit "secret not set" reason
+ * before the agent launches.
+ */
+export function substituteInputs(
+  value: string,
+  secrets: Readonly<Record<string, string>>,
+): string | null {
+  let missing = false
+  const result = value.replace(INPUT_REFERENCE, (_whole, id: string) => {
+    const secret = secrets[id]
+    if (secret === undefined || secret === '') {
+      missing = true
+      return ''
+    }
+    return secret
+  })
+  return missing ? null : result
+}
diff --git a/src/shared/userMcp/types.ts b/src/shared/userMcp/types.ts
new file mode 100644
index 000000000..150c7302a
--- /dev/null
+++ b/src/shared/userMcp/types.ts
@@ -0,0 +1,259 @@
+// User-managed MCP servers (#1143). Design: docs/superpowers/specs/
+// 2026-09-22-user-mcp-servers-design.md — read its Evidence section before
+// changing any rule here; each one is pinned to a CLI behavior.
+
+/**
+ * Providers that can receive a user MCP server today.
+ *
+ * WHY only Claude and Codex (not every AgentProviderKind): these are the two
+ * launchers whose MCP injection semantics were verified against their source
+ * and installed binaries. OpenCode and Grok also carry built-in MCP, but a user
+ * server there needs its own translator and evidence. Keeping this list closed
+ * means a new provider shows an honest "not supported yet" instead of silently
+ * receiving a config shape nobody checked.
+ */
+export const USER_MCP_PROVIDERS = ['claude', 'codex'] as const
+export type UserMcpProvider = (typeof USER_MCP_PROVIDERS)[number]
+
+export function isUserMcpProvider(value: unknown): value is UserMcpProvider {
+  return typeof value === 'string' && (USER_MCP_PROVIDERS as readonly string[]).includes(value)
+}
+
+/**
+ * Server names Agent Code already owns on every launch. `agent_code` is the
+ * built-in host's entry (BuiltInMcpHttpHost.serverConfig) and
+ * `agent-code-control` is denied/disabled for every provider by
+ * externalControlExclusion. A user entry with either name would replace or be
+ * replaced by ours: Claude's `--mcp-config` swaps whole entries and Codex
+ * deep-merges keys, so neither outcome is a usable server.
+ */
+export const RESERVED_USER_MCP_NAMES = ['agent_code', 'agent-code-control'] as const
+
+/**
+ * The de facto `mcpServers` entry, as server READMEs publish it.
+ *
+ * WHY we store the published shape instead of a normalized internal one: a
+ * user adds a server by pasting its README snippet, and later wants to copy it
+ * back out. A lossless round trip is only possible if our storage IS that
+ * shape. Unknown keys (Claude's `oauth`, `headersHelper`, a client's `timeout`)
+ * are therefore kept on the object even though no type names them — the index
+ * signature is deliberate, not laziness.
+ */
+export type UserMcpStdioEntry = {
+  type?: 'stdio'
+  command: string
+  args?: string[]
+  env?: Record<string, string>
+  cwd?: string
+  [extra: string]: unknown
+}
+
+export type UserMcpRemoteEntry = {
+  type: 'http' | 'sse'
+  url: string
+  headers?: Record<string, string>
+  [extra: string]: unknown
+}
+
+export type UserMcpServerEntry = UserMcpStdioEntry | UserMcpRemoteEntry
+
+export type UserMcpTransport = 'stdio' | 'http' | 'sse'
+
+/** A secret the entry references as `${input:<id>}`. Only the definition is
+ * stored in the document; the value lives in main's safeStorage blobs. */
+export type UserMcpInput = {
+  id: string
+  description: string
+}
+
+export type UserMcpServer = {
+  /** Stable identity. Per-agent overrides and secrets key on this, never on
+   * the name, so renaming a server keeps every agent's choice attached. */
+  id: string
+  /** Provider-visible server name (tool names become `mcp__<name>__<tool>`). */
+  name: string
+  /** Master switch. Off means off for every agent, whatever it overrides. */
+  enabled: boolean
+  /** Whether NEW agents of each provider get it by default. */
+  providers: Record<UserMcpProvider, boolean>
+  entry: UserMcpServerEntry
+  inputs: UserMcpInput[]
+  /**
+   * Set when an AGENT added this server or pointed it somewhere new (review
+   * round 2). Such a server is stored switched off and stays off until the
+   * user turns it on in Settings, which also clears this flag. Agents cannot
+   * clear it or turn a server on: an agent proposes, the user approves. The
+   * list decides what code runs in every future agent, so a prompt-injected
+   * agent must never be able to change it on its own authority.
+   */
+  pendingReview?: true
+}
+
+/** Who asked for a mutation. Agents go through the mcp_servers built-in
+ * domain; everything else (Settings, IPC) is the user. */
+export type UserMcpActor = 'user' | 'agent'
+
+export type UserMcpDocument = {
+  version: 1
+  servers: UserMcpServer[]
+}
+
+export type UserMcpProblem =
+  | { kind: 'invalid-name'; message: string }
+  | { kind: 'reserved-name'; message: string }
+  | { kind: 'duplicate-name'; message: string }
+  | { kind: 'invalid-entry'; message: string }
+  | { kind: 'secret-in-forbidden-field'; message: string }
+  | { kind: 'unknown-input'; message: string }
+  | { kind: 'secret-missing'; message: string }
+  | { kind: 'pending-review'; message: string }
+  | { kind: 'claude-native-name'; message: string }
+
+export type UserMcpSupport = { ok: true } | { ok: false; reason: string }
+
+export type UserMcpSecretState = { set: boolean; hint?: string }
+
+/** What crosses IPC to the renderer. Never contains a secret value. */
+export type UserMcpServerView = UserMcpServer & {
+  transport: UserMcpTransport | null
+  /** One-line summary for list rows (`localhost:23373/v0/mcp`, `npx -y pkg`). */
+  summary: string
+  secrets: Record<string, UserMcpSecretState>
+  problems: UserMcpProblem[]
+  support: Record<UserMcpProvider, UserMcpSupport>
+}
+
+/** A server the CLI loads from its own config, shown read-only. */
+export type NativeMcpServer = {
+  provider: UserMcpProvider
+  name: string
+  /** Display path of the file it came from, `~`-abbreviated. */
+  source: string
+  transport: UserMcpTransport | null
+  summary: string
+  /** Whether Copy in can express this entry as a managed server. The entry
+   * itself stays in main (review round 1): native configs routinely hold
+   * tokens in args and URLs as well as env/headers, and this snapshot crosses
+   * IPC to every window and, via mcp_servers_list, to agents. Copy in runs in
+   * main from main's own read. */
+  copyable: boolean
+}
+
+/** Main-only form of a native server, with what Copy in needs. Every env and
+ * header VALUE is already replaced by an `${input:…}` reference. */
+export type NativeMcpServerSource = NativeMcpServer & {
+  entry: UserMcpServerEntry | null
+  inputs: UserMcpInput[]
+}
+
+export type UserMcpSnapshot = {
+  servers: UserMcpServerView[]
+  native: NativeMcpServer[]
+  /** Set when the document on disk could not be read. The file is preserved
+   * beside the new one, so this is a notice, not data loss. */
+  storeProblem?: string
+  /** Claude's enterprise managed-mcp.json is present: Claude refuses any
+   * non-SDK `--mcp-config` server, so user servers are held back for Claude. */
+  claudeManagedPolicy: boolean
+}
+
+export type UserMcpSaveInput = {
+  id?: string
+  name: string
+  enabled: boolean
+  providers: Record<UserMcpProvider, boolean>
+  entry: UserMcpServerEntry
+  inputs: UserMcpInput[]
+  /** Secret values to set with this save (inputId → value). Values for inputs
+   * not listed stay as they are; an empty string clears. */
+  secrets?: Record<string, string>
+}
+
+export type UserMcpMutationResult =
+  /** `secretsCleared`: the save changed where the server connects, so its
+   * previously stored secrets were forgotten (see UserMcpService.save). */
+  | { ok: true; snapshot: UserMcpSnapshot; id?: string; secretsCleared?: boolean; pendingReview?: boolean }
+  | { ok: false; error: string; problems?: UserMcpProblem[] }
+
+export type UserMcpImportCandidate = {
+  name: string
+  entry: UserMcpServerEntry
+  inputs: UserMcpInput[]
+  /** Values lifted out of the pasted text into inputs; saved as secrets. */
+  pendingSecrets: Record<string, string>
+  problems: UserMcpProblem[]
+}
+
+export type UserMcpImportResult =
+  | { ok: true; candidates: UserMcpImportCandidate[]; format: 'mcpServers' | 'vscode' | 'map' | 'entry' }
+  | { ok: false; error: string }
+
+/**
+ * Launch material for one user MCP server, produced by main's UserMcpService
+ * right before spawn. `secrets` holds decrypted values and exists only for the
+ * duration of one launch; it is never persisted, logged, or sent to the
+ * renderer. Lives here (not beside the translators) because SessionOptions in
+ * shared/types/session.ts carries it to the provider sessions.
+ */
+export type ResolvedUserMcpServer = {
+  id: string
+  name: string
+  entry: UserMcpServerEntry
+  secrets: Record<string, string>
+}
+
+/** Why a server was not attached to one launch. */
+export type UserMcpDroppedServer = { name: string; reason: string }
+
+export type UserMcpUnavailableEvent = { servers: UserMcpDroppedServer[] }
+
+/**
+ * Per-agent overrides for user servers ride in the pane's existing
+ * `builtInMcpOverrides` map under this prefix (spec Revision 2 §3).
+ *
+ * WHY a prefix in the existing map instead of a second map: that map is already
+ * threaded through spawn, replace, reload, recovery, undo-close, provider
+ * switch, duplicate and the control API. A parallel map would have to be
+ * re-threaded through every one of those paths, and missing one silently drops
+ * a user's choice. Built-in domain names never contain ':', so the namespaces
+ * cannot collide.
+ */
+export const USER_MCP_OVERRIDE_PREFIX = 'user:'
+export type UserMcpOverrideKey = `user:${string}`
+
+export function userMcpOverrideKey(serverId: string): UserMcpOverrideKey {
+  return `${USER_MCP_OVERRIDE_PREFIX}${serverId}` as UserMcpOverrideKey
+}
+
+const SERVER_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/
+
+export function isUserMcpServerId(value: unknown): value is string {
+  return typeof value === 'string' && SERVER_ID_PATTERN.test(value)
+}
+
+export function isUserMcpOverrideKey(key: string): key is UserMcpOverrideKey {
+  return key.startsWith(USER_MCP_OVERRIDE_PREFIX)
+    && isUserMcpServerId(key.slice(USER_MCP_OVERRIDE_PREFIX.length))
+}
+
+/** The `user:` subset of a pane override map, keyed by bare server id — the
+ * shape that crosses IPC to main with spawn/recover. */
+export function userMcpOverridesFrom(value: unknown): Record<string, boolean> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {}
+  const result: Record<string, boolean> = {}
+  for (const [key, choice] of Object.entries(value as Record<string, unknown>)) {
+    if (typeof choice !== 'boolean' || !isUserMcpOverrideKey(key)) continue
+    result[key.slice(USER_MCP_OVERRIDE_PREFIX.length)] = choice
+  }
+  return result
+}
+
+/** Validates the IPC form (bare ids) coming from an untrusted renderer. */
+export function normalizeUserMcpOverrides(value: unknown): Record<string, boolean> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {}
+  const result: Record<string, boolean> = {}
+  for (const [id, choice] of Object.entries(value as Record<string, unknown>)) {
+    if (typeof choice === 'boolean' && isUserMcpServerId(id)) result[id] = choice
+  }
+  return result
+}
diff --git a/src/shared/userMcp/userMcp.test.ts b/src/shared/userMcp/userMcp.test.ts
new file mode 100644
index 000000000..6d34ddc08
--- /dev/null
+++ b/src/shared/userMcp/userMcp.test.ts
@@ -0,0 +1,211 @@
+import { describe, expect, it } from 'vitest'
+
+import { importUserMcpConfig } from './importConfig.js'
+import { substituteInputs } from './inputs.js'
+import { userMcpOverrideKey, userMcpOverridesFrom } from './types.js'
+import {
+  coerceUserMcpDocument,
+  providerSupport,
+  summarizeEntry,
+  transportOf,
+  userMcpDestination,
+  validateServer,
+} from './validate.js'
+
+// Verbatim from https://developers.beeper.com/desktop-api/mcp/ (2026-09-22).
+// Real published snippets are the fixture on purpose: the import path exists
+// to accept exactly what server READMEs print, not a shape we imagined.
+const BEEPER_HTTP_TOKEN = `{ "mcpServers": { "beeper": { "url": "http://localhost:23373/v0/mcp",
+  "headers": { "Authorization": "Bearer YOUR_TOKEN_HERE" } } } }`
+const BEEPER_STDIO_TOKEN = `{ "mcpServers": { "beeper": { "command": "npx",
+  "args": ["-y", "@beeper/mcp-remote", "--header", "Authorization: Bearer \${ACCESS_TOKEN}"],
+  "env": { "ACCESS_TOKEN": "YOUR_TOKEN_HERE" } } } }`
+const BEEPER_VSCODE = `{ "servers": { "beeper": { "type": "http", "url": "http://localhost:23373/v0/mcp" } } }`
+
+describe('importUserMcpConfig', () => {
+  it('imports the Beeper HTTP snippet as an http server whose token is a secret input', () => {
+    const result = importUserMcpConfig(BEEPER_HTTP_TOKEN)
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    expect(result.format).toBe('mcpServers')
+    const [beeper] = result.candidates
+    expect(beeper!.name).toBe('beeper')
+    expect(beeper!.entry).toEqual({
+      type: 'http',
+      url: 'http://localhost:23373/v0/mcp',
+      headers: { Authorization: 'Bearer ${input:beeper-authorization}' },
+    })
+    expect(beeper!.inputs.map(input => input.id)).toEqual(['beeper-authorization'])
+    // The README placeholder is not a secret: storing it would make the server
+    // look configured and fail at tool-call time.
+    expect(beeper!.pendingSecrets).toEqual({})
+    expect(beeper!.problems).toEqual([])
+  })
+
+  it('lifts a real token out of the stored entry entirely', () => {
+    const result = importUserMcpConfig(BEEPER_HTTP_TOKEN.replace('YOUR_TOKEN_HERE', 'bpr_live_9f3a'))
+    if (!result.ok) throw new Error(result.error)
+    const [beeper] = result.candidates
+    expect(JSON.stringify(beeper!.entry)).not.toContain('bpr_live_9f3a')
+    expect(beeper!.pendingSecrets).toEqual({ 'beeper-authorization': 'bpr_live_9f3a' })
+  })
+
+  it('imports the mcp-remote stdio snippet, keeping the server-expanded ${VAR} in args', () => {
+    const result = importUserMcpConfig(BEEPER_STDIO_TOKEN.replace('YOUR_TOKEN_HERE', 'tok'))
+    if (!result.ok) throw new Error(result.error)
+    const [beeper] = result.candidates
+    expect(transportOf(beeper!.entry)).toBe('stdio')
+    expect((beeper!.entry as { args: string[] }).args[3]).toBe('Authorization: Bearer ${ACCESS_TOKEN}')
+    expect((beeper!.entry as { env: Record<string, string> }).env).toEqual({
+      ACCESS_TOKEN: '${input:beeper-access_token}',
+    })
+    expect(beeper!.pendingSecrets).toEqual({ 'beeper-access_token': 'tok' })
+    expect(beeper!.problems).toEqual([])
+  })
+
+  it('accepts the VS Code servers form and carries its password inputs', () => {
+    expect(importUserMcpConfig(BEEPER_VSCODE)).toMatchObject({ ok: true, format: 'vscode' })
+    const withInputs = importUserMcpConfig(JSON.stringify({
+      inputs: [{ type: 'promptString', id: 'gh-token', description: 'GitHub PAT', password: true }],
+      servers: { github: { type: 'http', url: 'https://api.githubcopilot.com/mcp/', headers: { Authorization: 'Bearer ${input:gh-token}' } } },
+    }))
+    if (!withInputs.ok) throw new Error(withInputs.error)
+    expect(withInputs.candidates[0]!.inputs).toEqual([{ id: 'gh-token', description: 'GitHub PAT' }])
+    expect(withInputs.candidates[0]!.problems).toEqual([])
+  })
+
+  it('accepts a bare map and a single bare entry', () => {
+    const map = importUserMcpConfig('{"playwright":{"command":"npx","args":["@playwright/mcp@latest"]}}')
+    expect(map).toMatchObject({ ok: true, format: 'map', candidates: [{ name: 'playwright' }] })
+    const entry = importUserMcpConfig('{"url":"https://mcp.linear.app/sse","type":"sse"}', 'linear')
+    expect(entry).toMatchObject({ ok: true, format: 'entry', candidates: [{ name: 'linear' }] })
+  })
+
+  it('reports malformed JSON as a result, not a throw', () => {
+    expect(importUserMcpConfig('{ "mcpServers": ')).toMatchObject({ ok: false })
+    expect(importUserMcpConfig('[1,2]')).toMatchObject({ ok: false })
+  })
+})
+
+describe('validateServer', () => {
+  const http = { type: 'http' as const, url: 'http://localhost:23373/v0/mcp' }
+
+  it('rejects names that would break Codex -c paths or collide with Agent Code', () => {
+    expect(validateServer({ name: 'my.server', entry: http, inputs: [] })[0]?.kind).toBe('invalid-name')
+    expect(validateServer({ name: 'AGENT_CODE', entry: http, inputs: [] })[0]?.kind).toBe('reserved-name')
+    expect(validateServer({ name: 'agent-code-control', entry: http, inputs: [] })[0]?.kind).toBe('reserved-name')
+    expect(
+      validateServer({ name: 'Beeper', entry: http, inputs: [] }, [{ id: 'x', name: 'beeper' }])[0]?.kind,
+    ).toBe('duplicate-name')
+  })
+
+  it('allows secrets only where they can travel through the environment', () => {
+    const inputs = [{ id: 't', description: '' }]
+    expect(validateServer({ name: 'a', entry: { command: 'srv', env: { T: '${input:t}' } }, inputs }, [])).toEqual([])
+    expect(validateServer({ name: 'a', entry: { ...http, headers: { A: 'Bearer ${input:t}' } }, inputs }, [])).toEqual([])
+    const inArgs = validateServer({ name: 'a', entry: { command: 'srv', args: ['--key', '${input:t}'] }, inputs }, [])
+    expect(inArgs.map(problem => problem.kind)).toEqual(['secret-in-forbidden-field'])
+    const inUrl = validateServer({ name: 'a', entry: { type: 'http', url: 'https://x.dev/?k=${input:t}' }, inputs }, [])
+    expect(inUrl.map(problem => problem.kind)).toContain('secret-in-forbidden-field')
+  })
+
+  it('flags references to secrets that were never defined', () => {
+    const problems = validateServer({ name: 'a', entry: { ...http, headers: { A: '${input:nope}' } }, inputs: [] })
+    expect(problems.map(problem => problem.kind)).toEqual(['unknown-input'])
+  })
+
+  it('rejects mixed and empty transports', () => {
+    expect(validateServer({ name: 'a', entry: { command: 'x', url: 'http://y' } as never, inputs: [] })[0]?.kind)
+      .toBe('invalid-entry')
+    expect(validateServer({ name: 'a', entry: {} as never, inputs: [] })[0]?.kind).toBe('invalid-entry')
+  })
+})
+
+describe('providerSupport', () => {
+  it('keeps SSE servers Claude-only because Codex has no SSE transport', () => {
+    expect(providerSupport('sse').codex).toEqual({ ok: false, reason: 'Codex does not support SSE servers' })
+    expect(providerSupport('sse').claude).toEqual({ ok: true })
+    expect(providerSupport('http').codex).toEqual({ ok: true })
+  })
+})
+
+describe('coerceUserMcpDocument', () => {
+  it('keeps unknown entry keys and malformed servers instead of dropping user work', () => {
+    const doc = coerceUserMcpDocument({
+      version: 1,
+      servers: [
+        { id: 'a1', name: 'beeper', enabled: true, providers: { claude: true }, entry: { url: 'http://x', oauth: { clientId: 'c' } }, inputs: [] },
+        { id: 'b2', name: 'bad name!', entry: 'nonsense' },
+        { name: 'no id at all' },
+      ],
+    })
+    expect(doc.servers.map(server => server.id)).toEqual(['a1', 'b2'])
+    expect(doc.servers[0]!.entry).toMatchObject({ oauth: { clientId: 'c' } })
+    expect(doc.servers[0]!.providers).toEqual({ claude: true, codex: false })
+    expect(doc.servers[1]!.entry).toEqual({})
+  })
+
+  it('treats anything that is not a document as empty', () => {
+    expect(coerceUserMcpDocument(null)).toEqual({ version: 1, servers: [] })
+    expect(coerceUserMcpDocument({ servers: 'x' })).toEqual({ version: 1, servers: [] })
+  })
+})
+
+describe('substituteInputs', () => {
+  it('refuses a partially resolved value rather than emitting an empty credential', () => {
+    expect(substituteInputs('Bearer ${input:t}', { t: 'abc' })).toBe('Bearer abc')
+    expect(substituteInputs('Bearer ${input:t}', {})).toBeNull()
+    expect(substituteInputs('Bearer ${input:t}', { t: '' })).toBeNull()
+  })
+})
+
+describe('user override keys', () => {
+  it('extracts only well-formed user: keys from a pane override map', () => {
+    expect(userMcpOverridesFrom({
+      tldr: true,
+      [userMcpOverrideKey('abc-123')]: false,
+      'user:bad id': true,
+      'user:x': 'yes',
+    })).toEqual({ 'abc-123': false })
+  })
+})
+
+describe('review round 1 model rules', () => {
+  it('rejects env and header names Codex cannot address', () => {
+    expect(validateServer({ name: 'a', entry: { command: 'x', env: { 'java.home': '/opt' } }, inputs: [] })[0]?.message).toMatch(/java\.home/)
+    expect(validateServer({ name: 'a', entry: { type: 'http', url: 'https://x.dev/mcp', headers: { 'X-Foo.Bar': 'v' } }, inputs: [] })[0]?.message).toMatch(/X-Foo\.Bar/)
+  })
+
+  it('treats the ${VAR} environment idiom as a placeholder, not a secret value', () => {
+    const result = importUserMcpConfig('{"mcpServers":{"gh":{"command":"npx","env":{"GITHUB_TOKEN":"${GITHUB_TOKEN}"}}}}')
+    if (!result.ok) throw new Error(result.error)
+    expect(result.candidates[0]!.pendingSecrets).toEqual({})
+  })
+
+  it('never shows a credential-looking URL path or query in summaries', () => {
+    expect(summarizeEntry({ type: 'http', url: 'https://mcp.zapier.com/api/mcp/s/abcdefghijklmnopqrstuvwxyz0123456789/mcp' }))
+      .toBe('mcp.zapier.com/api/mcp/s/…/mcp')
+    expect(summarizeEntry({ type: 'http', url: 'https://x.dev/mcp?key=secret' })).toBe('x.dev/mcp?…')
+    expect(summarizeEntry({ type: 'http', url: 'http://localhost:23373/v0/mcp' })).toBe('localhost:23373/v0/mcp')
+  })
+})
+
+
+describe('review round 2 model rules', () => {
+  it('gives a hand-written ${input:} reference a secret field instead of failing save', () => {
+    const result = importUserMcpConfig('{"mcpServers":{"b":{"url":"http://localhost:23373/v0/mcp","headers":{"Authorization":"Bearer ${input:b-auth}"}}}}')
+    if (!result.ok) throw new Error(result.error)
+    expect(result.candidates[0]!.inputs.map(input => input.id)).toEqual(['b-auth'])
+    expect(result.candidates[0]!.problems).toEqual([])
+  })
+
+  it('elides the value that follows a sensitive flag', () => {
+    expect(summarizeEntry({ command: 'srv', args: ['--api-key', 'd6f8g2h9', '--port', '8080'] })).toBe('srv … … --port 8080')
+  })
+
+  it('counts every literal as part of where secrets go, but not which secret a value references', () => {
+    const base = { command: 'npx', env: { T: '${input:a}' } }
+    expect(userMcpDestination(base)).toBe(userMcpDestination({ command: 'npx', env: { T: '${input:b}' } }))
+    expect(userMcpDestination(base)).not.toBe(userMcpDestination({ command: 'npx', env: { T: '${input:a}', NODE_OPTIONS: '--require x' } }))
+  })
+})
diff --git a/src/shared/userMcp/validate.ts b/src/shared/userMcp/validate.ts
new file mode 100644
index 000000000..59eda5178
--- /dev/null
+++ b/src/shared/userMcp/validate.ts
@@ -0,0 +1,381 @@
+import { hasInputReference, inputReferences, USER_MCP_INPUT_ID_PATTERN } from './inputs.js'
+import {
+  RESERVED_USER_MCP_NAMES,
+  USER_MCP_PROVIDERS,
+  isUserMcpServerId,
+  type UserMcpDocument,
+  type UserMcpInput,
+  type UserMcpProblem,
+  type UserMcpProvider,
+  type UserMcpServer,
+  type UserMcpServerEntry,
+  type UserMcpSupport,
+  type UserMcpTransport,
+} from './types.js'
+
+/**
+ * `[A-Za-z0-9_-]`, 1–64 chars.
+ *
+ * WHY this exact charset: it is the intersection of what both CLIs accept AND
+ * what survives Codex's `-c` override parser. Claude's `mcp add` enforces
+ * `[A-Za-z0-9_-]`. Codex accepts more (`:@/.`) in config.toml, but `-c
+ * mcp_servers.<name>.url=…` splits the key path on '.' naively and never
+ * unquotes a quoted segment (codex-rs config/src/overrides.rs), so any wider
+ * name would silently target the wrong table.
+ *
+ * WHY no automatic `ac-` prefix to avoid collisions: tool names become
+ * `mcp__<server>__<tool>`, which users copy into permission rules from server
+ * docs. A prefix would break every documented rule. Collisions are instead
+ * detected (reserved names here, native Codex names at launch).
+ */
+export const USER_MCP_NAME_PATTERN = /^[A-Za-z0-9_-]{1,64}$/
+
+export function transportOf(entry: unknown): UserMcpTransport | null {
+  if (!isPlainObject(entry)) return null
+  const hasCommand = typeof entry.command === 'string'
+  const hasUrl = typeof entry.url === 'string'
+  if (entry.type === 'stdio') return hasCommand && !hasUrl ? 'stdio' : null
+  if (entry.type === 'http' || entry.type === 'sse') return hasUrl && !hasCommand ? entry.type : null
+  // Entries without `type` are the common README shape. A url-only entry means
+  // Streamable HTTP — Claude Desktop/Cursor behavior and the current transport;
+  // SSE servers publish `"type": "sse"` because SSE is the deprecated one.
+  if (entry.type === undefined) {
+    if (hasCommand && !hasUrl) return 'stdio'
+    if (hasUrl && !hasCommand) return 'http'
+  }
+  return null
+}
+
+/**
+ * Canonical stored form: explicit `type` for remote entries so the Codex and
+ * Claude translators never re-derive it, but stdio keeps whatever the user
+ * pasted (`type` omitted or `"stdio"`) — both are valid everywhere.
+ */
+export function normalizeEntry(entry: UserMcpServerEntry): UserMcpServerEntry {
+  const transport = transportOf(entry)
+  if ((transport === 'http' || transport === 'sse') && entry.type === undefined) {
+    return { ...entry, type: transport } as unknown as UserMcpServerEntry
+  }
+  return entry
+}
+
+export function validateEntry(entry: unknown): UserMcpProblem[] {
+  if (!isPlainObject(entry)) {
+    return [{ kind: 'invalid-entry', message: 'The server config must be a JSON object.' }]
+  }
+  const transport = transportOf(entry)
+  if (!transport) {
+    if (typeof entry.command === 'string' && typeof entry.url === 'string') {
+      return [{ kind: 'invalid-entry', message: 'Use either "command" (stdio) or "url" (http/sse), not both.' }]
+    }
+    if (entry.type !== undefined && !['stdio', 'http', 'sse'].includes(String(entry.type))) {
+      return [{ kind: 'invalid-entry', message: `Unsupported transport type "${String(entry.type)}". Use stdio, http or sse.` }]
+    }
+    return [{ kind: 'invalid-entry', message: 'Add "command" for a local (stdio) server or "url" for a remote one.' }]
+  }
+  const problems: UserMcpProblem[] = []
+  if (transport === 'stdio') {
+    if (!(entry.command as string).trim()) {
+      problems.push({ kind: 'invalid-entry', message: '"command" cannot be empty.' })
+    }
+    if (entry.args !== undefined && !isStringArray(entry.args)) {
+      problems.push({ kind: 'invalid-entry', message: '"args" must be an array of strings.' })
+    }
+    if (entry.env !== undefined && !isStringRecord(entry.env)) {
+      problems.push({ kind: 'invalid-entry', message: '"env" must map names to string values.' })
+    } else if (isStringRecord(entry.env)) {
+      const bad = Object.keys(entry.env).find(key => !USER_MCP_ENV_KEY_PATTERN.test(key))
+      if (bad !== undefined) problems.push({ kind: 'invalid-entry', message: `"${bad}" is not a valid environment variable name.` })
+    }
+    if (entry.cwd !== undefined && typeof entry.cwd !== 'string') {
+      problems.push({ kind: 'invalid-entry', message: '"cwd" must be a string.' })
+    }
+  } else {
+    if (!isHttpUrl(entry.url as string)) {
+      problems.push({ kind: 'invalid-entry', message: '"url" must be an absolute http(s) URL.' })
+    }
+    if (entry.headers !== undefined && !isStringRecord(entry.headers)) {
+      problems.push({ kind: 'invalid-entry', message: '"headers" must map names to string values.' })
+    } else if (isStringRecord(entry.headers)) {
+      const bad = Object.keys(entry.headers).find(key => !USER_MCP_HEADER_NAME_PATTERN.test(key))
+      if (bad !== undefined) problems.push({ kind: 'invalid-entry', message: `"${bad}" is not a valid header name (no dots or spaces).` })
+    }
+  }
+  problems.push(...forbiddenSecretProblems(entry))
+  return problems
+}
+
+/**
+ * `${input:…}` is only allowed in env and header VALUES.
+ *
+ * WHY: Codex does not expand variables in `command`, `args` or `url`, so a
+ * secret there has to be written literally into a `-c` override — i.e. into
+ * the Codex process's argv, readable by any local process via `ps` and by our
+ * own incident collectors. Env and header values can always travel through the
+ * environment instead (`env_vars`, `env_http_headers`, Claude's `${VAR}`).
+ * Servers that want a token on their own command line (mcp-remote's
+ * `--header "Authorization: Bearer ${TOKEN}"`) expand their own environment,
+ * so the user writes `${TOKEN}` in args and keeps the secret in `env.TOKEN`.
+ */
+function forbiddenSecretProblems(entry: Record<string, unknown>): UserMcpProblem[] {
+  const problems: UserMcpProblem[] = []
+  const check = (field: string, value: unknown) => {
+    if (typeof value === 'string' && hasInputReference(value)) {
+      problems.push({
+        kind: 'secret-in-forbidden-field',
+        message: `Secrets can only be used in env or headers values, not in "${field}" (it would be visible to other processes).`,
+      })
+    }
+  }
+  check('command', entry.command)
+  check('url', entry.url)
+  check('cwd', entry.cwd)
+  if (Array.isArray(entry.args)) entry.args.forEach(arg => check('args', arg))
+  return problems
+}
+
+export function referencedInputIds(entry: UserMcpServerEntry): string[] {
+  const ids = new Set<string>()
+  const scan = (record: unknown) => {
+    if (!isStringRecord(record)) return
+    for (const value of Object.values(record)) inputReferences(value).forEach(id => ids.add(id))
+  }
+  scan((entry as Record<string, unknown>).env)
+  scan((entry as Record<string, unknown>).headers)
+  return [...ids]
+}
+
+export function validateServer(
+  server: Pick<UserMcpServer, 'name' | 'entry' | 'inputs'>,
+  others: readonly Pick<UserMcpServer, 'id' | 'name'>[] = [],
+): UserMcpProblem[] {
+  const problems: UserMcpProblem[] = []
+  if (!USER_MCP_NAME_PATTERN.test(server.name)) {
+    problems.push({
+      kind: 'invalid-name',
+      message: 'Use 1–64 letters, digits, "-" or "_" (other characters break Codex config overrides).',
+    })
+  }
+  if (RESERVED_USER_MCP_NAMES.some(reserved => foldName(reserved) === foldName(server.name))) {
+    problems.push({ kind: 'reserved-name', message: `"${server.name}" is reserved for Agent Code's own MCP server.` })
+  }
+  // Case- and separator-insensitive on purpose. "Beeper" vs "beeper" is a
+  // trap for permission rules even where the CLIs would tell them apart, and
+  // "my-server" vs "my_server" would map to the same generated secret variable
+  // (userMcpSecretVariable upper-cases and folds separators), so the second
+  // server's token would silently overwrite the first one's in the launch env.
+  const folded = foldName(server.name)
+  if (others.some(other => foldName(other.name) === folded)) {
+    problems.push({ kind: 'duplicate-name', message: `Another server is already named "${server.name}".` })
+  }
+  problems.push(...validateEntry(server.entry))
+  const defined = new Set(server.inputs.map(input => input.id))
+  if (isPlainObject(server.entry)) {
+    for (const id of referencedInputIds(server.entry)) {
+      if (!defined.has(id)) {
+        problems.push({ kind: 'unknown-input', message: `"\${input:${id}}" is used but no secret named "${id}" exists.` })
+      }
+    }
+  }
+  return problems
+}
+
+/**
+ * Environment names Codex itself depends on. A user stdio server's SECRET has
+ * to be placed in Codex's own environment (Codex forwards env to MCP children
+ * only through an allowlist plus `env_vars` pass-through names, and
+ * `env_vars` cannot rename), so a server asking for one of these would
+ * silently change how Codex authenticates, finds binaries, or talks to our own
+ * MCP host. Lives here, not only in the launcher, so Settings and the
+ * per-agent picker show the server as Codex-unsupported instead of it being
+ * dropped at every launch with nothing on screen explaining why.
+ */
+export const CODEX_PROTECTED_ENV = new RegExp('^(' + [
+  'PATH', 'HOME', 'SHELL', 'USER', 'LOGNAME', 'TMPDIR', 'LANG', 'TERM',
+  'CODEX_.*', 'OPENAI_.*', 'AGENT_CODE_.*',
+  // Review round 1: variables that change how the Codex binary (and its npm
+  // launcher) itself connects, trusts certificates, loads code or logs.
+  'HTTPS?_PROXY', 'ALL_PROXY', 'NO_PROXY', 'SSL_CERT_(FILE|DIR)', 'NODE_EXTRA_CA_CERTS',
+  'NODE_OPTIONS', 'RUST_LOG', 'RUST_BACKTRACE', 'DYLD_.*', 'LD_.*',
+].join('|') + ')$', 'i')
+
+/**
+ * Env keys must be plain identifiers and header names plain HTTP tokens
+ * WITHOUT '.'. Codex splits `-c` key paths on every '.', so a dotted key
+ * becomes a nested table and fails config load for the whole Codex launch
+ * (review round 1, reproduced with codex-cli).
+ */
+export const USER_MCP_ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/
+export const USER_MCP_HEADER_NAME_PATTERN = /^[A-Za-z0-9!#$%&'*+^_`|~-]+$/
+
+/** providerSupport plus the rules that depend on the entry, not just its
+ * transport. Every UI surface and launch uses this one. */
+export function providerSupportForEntry(entry: unknown): Record<UserMcpProvider, UserMcpSupport> {
+  const support = providerSupport(transportOf(entry))
+  if (support.codex.ok && isPlainObject(entry) && isStringRecord(entry.env)) {
+    const protectedKey = Object.entries(entry.env)
+      .find(([key, value]) => hasInputReference(value) && CODEX_PROTECTED_ENV.test(key))?.[0]
+    if (protectedKey) {
+      return { ...support, codex: { ok: false, reason: `Codex cannot pass a secret named ${protectedKey}` } }
+    }
+  }
+  return support
+}
+
+/**
+ * Everything about an entry except the secret references themselves.
+ *
+ * WHY the whole entry and not just url/command/args (review round 2): a secret
+ * can be exfiltrated without moving it to a new host — add a literal
+ * `NODE_OPTIONS=--require ./evil.js` or a `PATH` that finds a fake `npx`, and
+ * the unchanged command runs attacker code with the token in its env. The
+ * only change that must NOT forget secrets is editing which `${input:…}` a
+ * value references, so those values are masked and everything else counts.
+ */
+export function userMcpDestination(entry: unknown): string {
+  if (!isPlainObject(entry)) return 'invalid'
+  const masked: Record<string, unknown> = { ...entry, type: transportOf(entry) }
+  for (const field of ['env', 'headers'] as const) {
+    if (!isStringRecord(entry[field])) continue
+    masked[field] = Object.fromEntries(Object.entries(entry[field] as Record<string, string>)
+      .map(([key, value]) => [key, hasInputReference(value) ? '<secret>' : value])
+      .sort(([a], [b]) => (a as string).localeCompare(b as string)))
+  }
+  return JSON.stringify(Object.keys(masked).sort().map(key => [key, masked[key]]))
+}
+
+/**
+ * Secret values may not contain `${`. Claude expands `${VAR}` in every value
+ * of an `--mcp-config` server (vendor services/mcp/config.ts expandEnvVars),
+ * and since the private file now carries resolved values, a secret containing
+ * `${X}` would be rewritten from Agent Code's own environment at launch
+ * (review round 2). Real tokens never contain it; a value that does is almost
+ * certainly an unfilled template.
+ */
+export function secretValueProblem(value: string): string | null {
+  return value.includes('${') ? 'A secret value cannot contain "${" — paste the actual value, not a variable reference.' : null
+}
+
+function foldName(name: string): string {
+  return name.toLowerCase().replace(/-/g, '_')
+}
+
+export function providerSupport(
+  transport: UserMcpTransport | null,
+): Record<UserMcpProvider, UserMcpSupport> {
+  return {
+    claude: { ok: true },
+    // Codex speaks stdio and Streamable HTTP only (codex-rs mcp_types.rs has
+    // no SSE transport). Claude still accepts SSE, so an SSE server is
+    // Claude-only rather than invalid.
+    codex: transport === 'sse'
+      ? { ok: false, reason: 'Codex does not support SSE servers' }
+      : { ok: true },
+  }
+}
+
+const SENSITIVE_ARG = /(bearer\s|token|secret|passw|api[-_]?key|auth|^sk-|^ghp_|^xox)/i
+
+function redactArg(arg: string): string {
+  return arg.length > 40 || SENSITIVE_ARG.test(arg) ? '…' : arg
+}
+
+export function summarizeEntry(entry: unknown): string {
+  if (!isPlainObject(entry)) return ''
+  const transport = transportOf(entry)
+  if (transport === 'stdio') {
+    const args = isStringArray(entry.args) ? entry.args : []
+    // Review round 1: native (and pasted) configs put tokens in args too
+    // (`--header "Authorization: Bearer sk-…"`, `--api-key …`). Summaries go
+    // to every window and to agents, so anything that looks like a credential
+    // or an opaque blob is elided. The full args stay in main.
+    // The value AFTER a sensitive flag is elided too (review round 2):
+    // `--api-key d6f8g2h9` is short and keyword-free on its own.
+    return [entry.command as string, ...args.map((arg, index) =>
+      index > 0 && SENSITIVE_ARG.test(args[index - 1]!) && args[index - 1]!.startsWith('-') ? '…' : redactArg(arg))].join(' ')
+  }
+  if (transport) {
+    try {
+      const url = new URL(entry.url as string)
+      // Review round 1: some servers (Zapier-style) carry the credential in a
+      // path segment or the query. Summaries reach the renderer and, through
+      // mcp_servers_list, agents, so long opaque segments and the whole query
+      // are elided. Short readable paths (`/v0/mcp`) are kept for recognition.
+      const path = url.pathname.split('/').map(segment => segment.length > 20 ? '…' : segment).join('/')
+      return `${url.host}${path === '/' ? '' : path}${url.search ? '?…' : ''}`
+    } catch {
+      return '(invalid URL)'
+    }
+  }
+  return ''
+}
+
+/**
+ * Coerce the persisted document without ever dropping a server the user made.
+ *
+ * WHY keep malformed servers instead of filtering them: the document is edited
+ * by hand, by older builds and by future ones. Deleting an entry because this
+ * build could not read one field would lose the user's work silently; keeping
+ * it lets validation flag it in Settings and lets main refuse to launch it.
+ * Only entries with no usable identity at all (not an object, no id) go.
+ */
+export function coerceUserMcpDocument(value: unknown): UserMcpDocument {
+  if (!isPlainObject(value) || !Array.isArray(value.servers)) return { version: 1, servers: [] }
+  const servers: UserMcpServer[] = []
+  const seen = new Set<string>()
+  for (const raw of value.servers) {
+    if (!isPlainObject(raw) || !isUserMcpServerId(raw.id) || seen.has(raw.id)) continue
+    seen.add(raw.id)
+    const providers = isPlainObject(raw.providers) ? raw.providers : {}
+    servers.push({
+      id: raw.id,
+      name: typeof raw.name === 'string' ? raw.name : '',
+      enabled: raw.enabled !== false,
+      providers: Object.fromEntries(
+        USER_MCP_PROVIDERS.map(provider => [provider, providers[provider] === true]),
+      ) as Record<UserMcpProvider, boolean>,
+      // Kept verbatim (including unknown keys); validation reports problems.
+      entry: (isPlainObject(raw.entry) ? raw.entry : {}) as UserMcpServerEntry,
+      inputs: coerceInputs(raw.inputs),
+      // Survives a hand edit or an older build only as `true`: anything else
+      // reads as "not pending", which is the conservative direction only
+      // because a pending server is also stored disabled.
+      ...(raw.pendingReview === true ? { pendingReview: true as const } : {}),
+    })
+  }
+  return { version: 1, servers }
+}
+
+export function coerceInputs(value: unknown): UserMcpInput[] {
+  if (!Array.isArray(value)) return []
+  const seen = new Set<string>()
+  const inputs: UserMcpInput[] = []
+  for (const raw of value) {
+    if (!isPlainObject(raw) || typeof raw.id !== 'string' || !USER_MCP_INPUT_ID_PATTERN.test(raw.id)) continue
+    if (seen.has(raw.id)) continue
+    seen.add(raw.id)
+    inputs.push({ id: raw.id, description: typeof raw.description === 'string' ? raw.description : '' })
+  }
+  return inputs
+}
+
+export function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every(item => typeof item === 'string')
+}
+
+export function isStringRecord(value: unknown): value is Record<string, string> {
+  return isPlainObject(value) && Object.values(value).every(item => typeof item === 'string')
+}
+
+function isHttpUrl(value: string): boolean {
+  try {
+    const url = new URL(value)
+    return url.protocol === 'http:' || url.protocol === 'https:'
+  } catch {
+    return false
+  }
+}