From 985e6a4d0c025ebdea435f6884e91158e31d0ce9 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 18 May 2026 22:36:16 -0600
Subject: [PATCH 01/48] =?UTF-8?q?fix(oauth,services):=20port=20#152=20?=
 =?UTF-8?q?=E2=80=94=20DCR=20redirect=20URI=20tolerance=20+=20clippy?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cherry-picks the two changes from upstream PR #152 (mcpmux/mcp-mux#152)
since `feat/workspace-root-routing` (PR #151, this branch's base) reworked
`dcr.rs` extensively and a direct merge would conflict.

- `validate_redirect_uris` now skips invalid URIs with a warn log and only
  fails registration when zero valid URIs remain. Unblocks Cursor 3.4.20,
  which sends a mixed-validity list (`cursor://`, `https://www.cursor.com`,
  `http://localhost`) in a single DCR request.
- `PrefixCacheService` uses `sort_by_key` for the `created_at` sort so
  `clippy::unnecessary_sort_by` doesn't fail `cargo clippy -D warnings`.

Adds two tests covering the mixed-validity case and the all-invalid case.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 crates/mcpmux-gateway/src/oauth/dcr.rs        | 43 ++++++++++++++++---
 .../src/services/prefix_cache.rs              |  2 +-
 2 files changed, 39 insertions(+), 6 deletions(-)

diff --git a/crates/mcpmux-gateway/src/oauth/dcr.rs b/crates/mcpmux-gateway/src/oauth/dcr.rs
index fc6a9a06..ed255019 100644
--- a/crates/mcpmux-gateway/src/oauth/dcr.rs
+++ b/crates/mcpmux-gateway/src/oauth/dcr.rs
@@ -227,6 +227,8 @@ pub fn validate_redirect_uris(uris: &[String]) -> Result<(), DcrError> {
         ));
     }
 
+    let mut valid_count = 0;
+
     for uri in uris {
         let is_loopback = uri.starts_with("http://127.0.0.1")
             || uri.starts_with("http://localhost")
@@ -237,20 +239,28 @@ pub fn validate_redirect_uris(uris: &[String]) -> Result<(), DcrError> {
         let is_custom_scheme = !uri.starts_with("http://") && !uri.starts_with("https://");
 
         if !is_loopback && !is_custom_scheme {
+            // Skip invalid URIs (e.g. https://www.cursor.com/agents/mcp/oauth/callback)
+            // rather than rejecting the entire registration — clients like Cursor send a
+            // mix of valid and invalid URIs and only ever use the valid ones in practice.
             warn!(
-                "[DCR] Rejected redirect_uri: {} (must be loopback or custom scheme)",
+                "[DCR] Skipping invalid redirect_uri: {} (must be loopback or custom scheme)",
                 uri
             );
-            return Err(DcrError::invalid_redirect_uri(
-                "Redirect URI must be loopback (http://127.0.0.1 or http://localhost) \
-                 or a custom URL scheme (e.g., cursor://, vscode://)",
-            ));
+            continue;
         }
 
         debug!(
             "[DCR] Validated redirect_uri: {} (loopback={}, custom_scheme={})",
             uri, is_loopback, is_custom_scheme
         );
+        valid_count += 1;
+    }
+
+    if valid_count == 0 {
+        return Err(DcrError::invalid_redirect_uri(
+            "No valid redirect_uris provided — must include at least one loopback \
+             (http://127.0.0.1 or http://localhost) or custom URL scheme (e.g., cursor://, vscode://)",
+        ));
     }
 
     Ok(())
@@ -462,6 +472,29 @@ mod tests {
         assert!(validate_redirect_uris(&["https://example.com/callback".to_string()]).is_err());
     }
 
+    #[test]
+    fn test_mixed_valid_and_invalid_uris_pass() {
+        // Real-world case: Cursor sends a mix of valid (custom scheme + loopback) and
+        // invalid (https) URIs. Registration must succeed as long as at least one valid
+        // URI is present — otherwise clients that send any non-loopback HTTPS URI cannot
+        // register at all.
+        let uris = vec![
+            "cursor://anysphere.cursor-mcp/oauth/callback".to_string(),
+            "https://www.cursor.com/agents/mcp/oauth/callback".to_string(),
+            "http://localhost:8787/callback".to_string(),
+        ];
+        assert!(validate_redirect_uris(&uris).is_ok());
+    }
+
+    #[test]
+    fn test_all_invalid_uris_fail() {
+        let uris = vec![
+            "https://www.cursor.com/agents/mcp/oauth/callback".to_string(),
+            "http://example.com/callback".to_string(),
+        ];
+        assert!(validate_redirect_uris(&uris).is_err());
+    }
+
     #[test]
     fn loopback_ignores_port_per_rfc_8252() {
         // Registered with one port, requested with another — must match.
diff --git a/crates/mcpmux-gateway/src/services/prefix_cache.rs b/crates/mcpmux-gateway/src/services/prefix_cache.rs
index f5976af6..2a85d95b 100644
--- a/crates/mcpmux-gateway/src/services/prefix_cache.rs
+++ b/crates/mcpmux-gateway/src/services/prefix_cache.rs
@@ -138,7 +138,7 @@ impl PrefixCacheService {
 
         // Sort by created_at (earliest first)
         // TODO: Add verified status priority when registry supports it
-        servers.sort_by(|a, b| a.created_at.cmp(&b.created_at));
+        servers.sort_by_key(|a| a.created_at);
 
         // Clear existing cache for this space
         self.clear_space(space_id).await;

From 7bf4cb17548bf20daa1a49d07565377ceef98001 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 18 May 2026 22:36:23 -0600
Subject: [PATCH 02/48] docs(planning): add plan for dynamic MCP toggle meta
 tools

5-phase plan layered on top of PR #151's `mcpmux_*` meta-tool surface:
adds `mcpmux_list_servers`, `mcpmux_enable_server`, `mcpmux_disable_server`
with a session-scoped default (in-memory `SessionOverrideRegistry`) and a
workspace-scope opt-in that reuses the existing `WorkspaceBinding` write
path. Resolver stays untouched; composition lives in `FeatureService`.

Closes the gap between PR #151's persistent bindings and the ephemeral
"LLM-driven, minimum-context-default" workflow from the jsg-tech-check
homelab plan.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 .../planning/dynamic-mcp-toggle-meta-tools.md | 278 ++++++++++++++++++
 1 file changed, 278 insertions(+)
 create mode 100644 docs/planning/dynamic-mcp-toggle-meta-tools.md

diff --git a/docs/planning/dynamic-mcp-toggle-meta-tools.md b/docs/planning/dynamic-mcp-toggle-meta-tools.md
new file mode 100644
index 00000000..3fca5d91
--- /dev/null
+++ b/docs/planning/dynamic-mcp-toggle-meta-tools.md
@@ -0,0 +1,278 @@
+# Dynamic MCP Toggling via Meta Tools
+
+**Last Updated:** May 18, 2026
+**Status:** Planning — decisions locked, ready for implementation
+**Branch:** `feat/dynamic-mcp-toggle-meta-tools`
+**Base branch:** `feat/workspace-root-routing` ([upstream PR #151](https://github.com/mcpmux/mcp-mux/pull/151))
+**Issue:** TBD — file after planning review
+**Depends on:** [PR #151](https://github.com/mcpmux/mcp-mux/pull/151) merging or being consumed via fork (provides the `mcpmux_*` namespace, `MetaToolRegistry`, `ApprovalBroker`, `FeatureSetResolverService`, per-peer `list_changed`, `SessionRootsRegistry`)
+**Unblocks:** [`jsg-tech-check` homelab MCP strategy](../../../jsg-tech-check/docs/setup/home-lab-overview.md#mcp-strategy--current-state)
+
+---
+
+## Problem
+
+The Cursor / Claude Code pre-McpMux workflow gave a per-project escape valve: each `.cursor/mcp.json` declared a subset of servers, so the client only loaded the tools that mattered for that project. Token budget stayed proportional to the project's actual needs.
+
+Routing everything through McpMux collapses that signal. The gateway exposes one consolidated MCP endpoint; the client side sees a single `mcpmux` server entry that's either ON or OFF. All 35+ tools from every enabled backend land in the LLM context window the moment a session opens, regardless of what the project actually needs.
+
+PR #151 partly addresses this with persistent `WorkspaceBinding`s: bind `~/code/personal/set-times-app` to `{core, browser, design, db-personal}` and the gateway serves exactly those tools when Cursor opens that folder. That works for stable, known scopes. It does not work for:
+
+- **Discovery-driven work** — "use whichever MCPs you need for this task" with no pre-declared bundle.
+- **One-off needs** — "I'm in `set-times-app` (which is bound to a bundle that excludes `firebase`) but I need `firebase` for the next 15 minutes."
+- **Minimum-context defaults** — start a session with zero backend tools loaded, let the LLM pull in what it needs based on the manifest, drop tools when it's done.
+
+The user-facing ask, stated as the original request:
+
+> Instead of having the whole definitions of all my MCPs all the time, I'd just have 1 always-on tool that gives me a manifest and then mcp can be smart enough to turn itself on.
+
+PR #151 ships four meta tools (`mcpmux_list_all_tools`, `mcpmux_list_feature_sets`, `mcpmux_create_feature_set`, `mcpmux_bind_current_workspace`). They cover the manifest + persist-a-new-bundle path. They don't cover the ephemeral toggle path — there's no way to turn a backend server on for "just this session" without writing a binding to the DB.
+
+This doc extends the meta-tools surface with session-scoped enable/disable, plus a server-level (coarser than tool-level) `mcpmux_list_servers` manifest tool. The resolver gains a Tier 0 (`SessionOverride`) that composes additively over Tier 1's `WorkspaceBinding`.
+
+---
+
+## Decisions
+
+| # | Decision | Choice | Rationale |
+| - | -------- | ------ | --------- |
+| 1 | Granularity | **Server-level** (`mcpmux_enable_server("github")`), not tool-level | Matches the user's mental model ("turn on github") and the existing `FeatureSetType::ServerAll`. Tool-level enable can be added later as a degenerate case if a real use case shows up. |
+| 2 | Default scope | **Session** (default), with `scope: "workspace"` as an opt-in arg | Session is the low-risk default; ephemerality is the point. Workspace scope falls back to the existing `WorkspaceBinding` write path, reusing PR #151 plumbing. |
+| 3 | Composition with bindings | **Additive over `WorkspaceBinding`**: `effective = (binding ∪ session_enabled) − session_disabled` | Lets users keep their stable per-project bundle AND opportunistically add a server for a single session. Subtractive disable lets them mute a noisy server temporarily without unbinding. |
+| 4 | Override lifetime | **In-memory, dies with `mcp-session-id`** | Matches `SessionRootsRegistry` semantics introduced by PR #151. Restart of gateway or client = fresh start. No DB persistence; no migration. |
+| 5 | Approval flow | Session enables auto-allow by default (configurable); workspace writes require approval (existing flow) | Session-scope is ephemeral and safer than persistent state. App setting `gateway.session_overrides_require_approval` (default `false`) lets paranoid users gate everything. |
+| 6 | Audit | Every override emits a `DomainEvent::MetaToolInvoked` (existing path) | No new event variants; the audit log already renders meta-tool calls. The "decision" field gets `"session_override"` for auto-allowed session writes. |
+| 7 | Manifest format | `mcpmux_list_servers` returns server roster with `{id, name, tool_count, status}` where status ∈ `enabled_via_binding \| enabled_via_session \| disabled_via_session \| inactive` | The LLM needs to see current state, not just availability — otherwise it can't reason about whether to call enable or just call the tool. |
+| 8 | Tier-0 placement | New `SessionOverrideRegistry` consulted **inside** `FeatureService` materialization, not as a new resolver tier | Resolver already returns `(space, feature_set_ids)` cleanly. Layering at the materialization step keeps the resolver pure and concentrates the composition logic in one place (`FeatureService::get_tools_for_grants`). |
+
+---
+
+## The Model
+
+### Override store
+
+Per-session, two server-id sets. Both empty = no overrides, default routing applies.
+
+```text
+SessionOverrideRegistry {
+    enabled : DashMap<SessionId, HashSet<ServerId>>,
+    disabled: DashMap<SessionId, HashSet<ServerId>>,
+}
+```
+
+GC mirrors `SessionRootsRegistry`: both maps drop on `MCPNotifier`'s session-reap pass.
+
+### Composition rule
+
+For a session resolving its effective server set:
+
+```text
+1. (space, feature_set_ids) ← FeatureSetResolverService::resolve(...)
+2. binding_servers ← FeatureService::servers_for(space, feature_set_ids)
+3. session_on     ← SessionOverrideRegistry.enabled[session_id]
+4. session_off    ← SessionOverrideRegistry.disabled[session_id]
+5. effective      ← (binding_servers ∪ session_on) − session_off
+6. tools          ← every Tool feature whose server_id ∈ effective AND is_available
+```
+
+`session_on` and `session_off` are honored even when the resolver returned `Deny` (no binding match) — the session-override path is how a roots-capable client opts into tools without a binding. Empty override sets + `Deny` from resolver = no tools (existing behavior).
+
+### Tool surface
+
+Three new tools added to `build_default_registry`:
+
+| Tool | Type | Approval (default) | Purpose |
+| ---- | ---- | ------------------ | ------- |
+| `mcpmux_list_servers` | read | none | Server-level manifest with status per server. Coarser than `mcpmux_list_all_tools`. |
+| `mcpmux_enable_server` | write | session: auto-allow; workspace: approval | Adds `server_id` to session overrides (or writes a binding). |
+| `mcpmux_disable_server` | write | session: auto-allow; workspace: approval | Adds `server_id` to session disable set (or removes from binding). |
+
+Each write fires `tools/list_changed` per-peer via the existing `MCPNotifier::notify_peer_lists_changed` path so the calling LLM's tool list refreshes mid-conversation.
+
+### What McpMux still stores
+
+| Item | Storage | Persistence |
+| ---- | ------- | ----------- |
+| Session overrides (enabled + disabled sets) | `SessionOverrideRegistry` (in-memory `DashMap`) | Process-lifetime; dies with session reap |
+| Workspace-scope writes | `workspace_bindings` table (existing) | Persistent (no schema change) |
+| Audit trail | `DomainEvent::MetaToolInvoked` (existing) | Persistent via existing audit log |
+| `gateway.session_overrides_require_approval` setting | `app_settings` table (existing) | Persistent |
+
+---
+
+## Architecture
+
+```
+              ┌──────────────────────────────────────────┐
+              │  FeatureService::get_tools_for_grants    │
+              │  (existing materialization chokepoint)   │
+              │                                          │
+              │  binding_servers   = resolver-derived    │
+              │  + session_enabled ← Tier 0 overrides    │
+              │  − session_disabled                      │
+              └──────────────────────────────────────────┘
+                              ▲
+                              │
+   ┌──────────────────────────┴──────────────────────────┐
+   │                                                     │
+   ▼                                                     ▼
+┌─────────────────────────┐              ┌──────────────────────────────┐
+│ FeatureSetResolverService│             │ SessionOverrideRegistry      │
+│ (PR #151 — unchanged)    │             │ (new)                        │
+│                          │             │                              │
+│ Tier 1: WorkspaceBinding │             │ enabled : DashMap<sid, set>  │
+│ Tier 2: ClientGrant      │             │ disabled: DashMap<sid, set>  │
+│ Tier 3: Deny             │             └──────────────────────────────┘
+└─────────────────────────┘                            ▲
+                                                       │
+                                          ┌────────────┴────────────┐
+                                          │ Meta tool writes mutate │
+                                          │ this registry directly. │
+                                          │                         │
+                                          │ mcpmux_enable_server    │
+                                          │ mcpmux_disable_server   │
+                                          └─────────────────────────┘
+```
+
+- `SessionOverrideRegistry` lives in `crates/mcpmux-gateway/src/services/`, sibling to `session_roots.rs`. Same `Arc<Self>` factory pattern, same GC contract.
+- `FeatureService` is the only consumer that reads it. The resolver itself stays pure — no new tier, no new branch in `feature_set_resolver.rs`.
+- Writes go through the existing `MetaToolRegistry` dispatch in `tools.rs` → `with_approval()` (session-scope short-circuits approval when the setting allows) → mutate the registry → emit `tools/list_changed` via the existing `emit_tools_list_changed` helper.
+
+---
+
+## Files to create
+
+| File | Purpose |
+| ---- | ------- |
+| `crates/mcpmux-gateway/src/services/session_overrides.rs` | `SessionOverrideRegistry` — `DashMap`-backed enable/disable sets, GC hooks, query helpers (`is_enabled`, `is_disabled`, `effective_overlay`) |
+| `tests/rust/tests/integration/session_overrides.rs` | Integration tests: enable adds tool, disable removes tool, composition with binding, GC on session reap, per-peer `list_changed` fires |
+| `docs/planning/dynamic-mcp-toggle-meta-tools.md` | This doc |
+
+## Files to modify
+
+| File | Change |
+| ---- | ------ |
+| [`crates/mcpmux-gateway/src/services/mod.rs`](../../crates/mcpmux-gateway/src/services/mod.rs) | `pub mod session_overrides;` + re-export `SessionOverrideRegistry` |
+| [`crates/mcpmux-gateway/src/services/meta_tools/mod.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/mod.rs) | Register `ListServersTool`, `EnableServerTool`, `DisableServerTool` in `build_default_registry`. Add `session_overrides: Arc<SessionOverrideRegistry>` to `MetaToolContext`. |
+| [`crates/mcpmux-gateway/src/services/meta_tools/registry.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/registry.rs) | Extend `MetaToolContext` with `session_overrides`. Add `"session_override"` to the decision-string match in `MetaToolRegistry::call` so audit rows are distinguishable. |
+| [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | Implement `ListServersTool`, `EnableServerTool`, `DisableServerTool`. Session-scope short-circuits `with_approval` when `gateway.session_overrides_require_approval` is false. |
+| [`crates/mcpmux-gateway/src/pool/features/facade.rs`](../../crates/mcpmux-gateway/src/pool/features/facade.rs) | `FeatureService::get_tools_for_grants` (and sibling `get_prompts_for_grants`, `get_resources_for_grants`) take `session_id: Option<&str>` and apply `SessionOverrideRegistry` composition before returning. |
+| [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) | Pass `session_id` (already on `RequestContext`) into the new `get_*_for_grants` signatures. |
+| [`crates/mcpmux-gateway/src/server/service_container.rs`](../../crates/mcpmux-gateway/src/server/service_container.rs) | Construct `Arc<SessionOverrideRegistry>` once; wire into `MetaToolContext`, `FeatureService`, and the session-reap path in `MCPNotifier`. |
+| [`crates/mcpmux-gateway/src/consumers/mcp_notifier.rs`](../../crates/mcpmux-gateway/src/consumers/mcp_notifier.rs) | In the session-reap pass, also call `SessionOverrideRegistry::remove(session_id)` alongside `SessionRootsRegistry::remove`. |
+| [`crates/mcpmux-core/src/domain/event.rs`](../../crates/mcpmux-core/src/domain/event.rs) | No new variant — `MetaToolInvoked` already carries `decision: String`. Document `"session_override"` as a valid value in the doc comment. |
+| [`apps/desktop/src/features/workspaces/WorkspacesPage.tsx`](../../apps/desktop/src/features/workspaces/WorkspacesPage.tsx) | New "Active session overrides" sub-panel under the live-session inspector: per-session list of enabled / disabled server_ids with a "clear" button. |
+| [`apps/desktop/src-tauri/src/commands/workspace_binding.rs`](../../apps/desktop/src-tauri/src/commands/workspace_binding.rs) | New Tauri commands: `list_session_overrides(session_id)`, `clear_session_overrides(session_id)`. Read-only + clear; mutation happens via the MCP tool, not the UI. |
+| [`apps/desktop/src/lib/api/workspaceBindings.ts`](../../apps/desktop/src/lib/api/workspaceBindings.ts) | TS wrappers for the two new commands. |
+
+---
+
+## Phasing
+
+### Phase 1 — `SessionOverrideRegistry` + composition wiring
+
+**Effort:** 1 evening
+
+- Add `crates/mcpmux-gateway/src/services/session_overrides.rs` mirroring `session_roots.rs` shape: `DashMap`-backed, `Arc<Self>` factory, `set_enabled`, `set_disabled`, `clear_enabled`, `clear_disabled`, `enabled_set`, `disabled_set`, `remove`, `list_all` for the UI.
+- Plumb `Arc<SessionOverrideRegistry>` through `ServiceContainer` into both `FeatureService` and `MCPNotifier`.
+- Extend `FeatureService::get_tools_for_grants` (+ prompts + resources) signatures to accept `session_id: Option<&str>` and apply `(servers ∪ enabled) − disabled` filtering.
+- Update `handler.rs` callsites to pass `session_id` from `RequestContext` headers.
+- `MCPNotifier` session-reap pass also drops override entries.
+- Unit tests in `session_overrides.rs`: set/get round-trip, enable/disable composition, GC on remove.
+
+**Outcome:** A test that directly mutates `SessionOverrideRegistry` for a fake session id observes the next `FeatureService::get_tools_for_grants` call return the composed set. No meta-tools exist yet; UI unchanged. CI green.
+
+### Phase 2 — `mcpmux_list_servers` read tool
+
+**Effort:** 1 evening
+
+- Add `ListServersTool` unit struct + `MetaTool` impl in `meta_tools/tools.rs`.
+- Implementation: load `ServerFeature::list_for_space(caller_space_id)`, group by `server_id`, compute `tool_count = features.iter().filter(|f| f.feature_type == Tool).count()`, derive `status` per server by checking `binding`, `session_overrides.enabled`, `session_overrides.disabled` in order.
+- JSON schema: empty `properties` (no args).
+- Register in `build_default_registry` alongside the existing reads.
+- Integration test: connect a fake session, call `mcpmux_list_servers`, assert response shape includes `status` enum values for both bound and unbound servers.
+
+**Outcome:** An LLM calling `mcpmux_list_servers` from any session receives a server roster like `[{id: "github", name: "GitHub", tool_count: 24, status: "enabled_via_binding"}, {id: "firebase", name: "Firebase", tool_count: 18, status: "inactive"}, ...]`. No state mutation yet.
+
+### Phase 3 — `mcpmux_enable_server` / `mcpmux_disable_server` (session scope)
+
+**Effort:** 1 day
+
+- Add `EnableServerTool` + `DisableServerTool` to `meta_tools/tools.rs`.
+- Args: `{ server_id: string, scope?: "session" | "workspace" (default "session") }`.
+- Session-scope flow: validate `server_id` exists in caller's resolved Space → look up `gateway.session_overrides_require_approval` setting → if `false`, mutate registry directly; if `true`, route through `with_approval` first.
+- Enable adds to `enabled` and removes from `disabled` (the two sets are mutually exclusive per server-id, last-write-wins).
+- Disable mirror: adds to `disabled`, removes from `enabled`.
+- After mutation: fire per-peer `tools/list_changed` via `notify_peer_lists_changed(client_id)`. Emit `MetaToolInvoked` with `decision: "session_override"` when auto-allowed, `"allow_once"` when approval was required.
+- Reject `scope: "workspace"` with `MetaToolError::InvalidArgument("workspace scope not yet implemented; see Phase 4")` until Phase 4 lands.
+- Integration tests: enable → tool appears in next `tools/list`, disable → tool disappears, both with the per-peer notify firing.
+
+**Outcome:** From a fresh Cursor window (no binding, no overrides), an LLM calls `mcpmux_enable_server({"server_id": "github"})`. The GitHub tools appear in the next `tools/list`. The LLM uses them, then calls `mcpmux_disable_server({"server_id": "github"})` when done. Tools disappear. No DB writes; closing Cursor and reopening it = clean slate.
+
+### Phase 4 — Workspace-scope variants
+
+**Effort:** 1 day
+
+- Extend `EnableServerTool` / `DisableServerTool` to handle `scope: "workspace"`.
+- Enable + workspace: requires the caller to have reported MCP roots (reuse `caller_space_id` + `session_roots.get` pattern from `BindCurrentWorkspaceTool`). If no binding exists for the first reported root, return `MetaToolError::InvalidArgument("no binding exists for this workspace; create one with mcpmux_create_feature_set + mcpmux_bind_current_workspace first")`. If a binding exists, look up its FS, add a `ServerAll`-typed `FeatureSet` for `server_id`, append its id to the binding's `feature_set_ids` list.
+- Disable + workspace: remove the matching `ServerAll` FS from the binding's `feature_set_ids` if present; if the server's tools come from a custom FS (not a `ServerAll` row), reject with a message pointing the user at the Workspaces UI.
+- Always require approval for workspace scope (no auto-allow setting).
+- Integration test: enable + workspace persists across a session restart; disable + workspace removes from binding row.
+
+**Outcome:** An LLM in a bound workspace adds a `ServerAll` FS layer to its binding via `mcpmux_enable_server({"server_id": "firebase", "scope": "workspace"})`, approves in the desktop dialog, and the next time it opens that folder Firebase tools are there without re-enabling.
+
+### Phase 5 — UI surface for session overrides
+
+**Effort:** 1 day
+
+- New "Active session overrides" sub-panel inside `WorkspacesPage.tsx`'s live-session inspector: lists per-session `enabled`/`disabled` server ids alongside the reported roots.
+- "Clear all overrides" button per session — calls the new `clear_session_overrides` Tauri command. Useful when a session got into a weird state and the user wants a clean default-routing read.
+- New Tauri commands: `list_session_overrides(session_id) -> { enabled: string[], disabled: string[] }`, `clear_session_overrides(session_id)`.
+- Settings checkbox under Gateway settings: "Require approval for session-scope overrides" — wires to `gateway.session_overrides_require_approval`.
+- README + CHANGELOG entries describing the new meta-tools and the manifest-driven workflow.
+
+**Outcome:** From the Workspaces tab, a user can see at a glance "session abc123 has GitHub enabled (session) and Firebase disabled (session)" and clear them with one click. The new approval-required setting is discoverable in Gateway settings without reading docs.
+
+---
+
+## Out of scope
+
+| Item | Reason |
+| ---- | ------ |
+| Tool-level granularity (`mcpmux_enable_tools(["github_create_issue"])`) | Server-level covers the user's stated use case. Adding tool-level later is additive — same approval flow, more specific `qualified_name` list. No real evidence yet that tool-level matters more than server-level for token budget. |
+| Persistent session preferences across gateway restarts | Process-lifetime is the design — sessions die when the client reconnects. If a user wants stickiness, they should use a binding. Adding persistence here would duplicate the binding system poorly. |
+| Auto-enable on tool-call hint ("LLM tried to call `github_create_issue` → silently enable github first") | Requires a "shadow tool list" mechanism in the handler (advertise more than is currently active). Possible follow-up, but design isn't obvious — silent enable defeats the audit trail. |
+| Cross-client session sharing | `mcp-session-id` is per-MCP-session; two Cursor windows have two sessions and two override sets. By design — independent contexts. |
+| Override expiry / TTL | Sessions are already ephemeral. A TTL would be a different concept and isn't asked for. |
+| Tool-level disable inside an already-enabled server | Use `mcpmux_create_feature_set` + `mcpmux_bind_current_workspace` (PR #151's existing path) for fine-grained subsets. |
+
+---
+
+## Key files referenced
+
+| File | Why |
+| ---- | --- |
+| [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | Where the three new `MetaTool` impls land. Existing `with_approval` + `caller_space_id` patterns are the templates. |
+| [`crates/mcpmux-gateway/src/services/meta_tools/mod.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/mod.rs) | `build_default_registry` factory — registration site for the new tools. `MetaToolContext` gains one new field. |
+| [`crates/mcpmux-gateway/src/services/meta_tools/registry.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/registry.rs) | `MetaToolRegistry::call` dispatch + audit emission. Adds `"session_override"` decision string. |
+| [`crates/mcpmux-gateway/src/services/meta_tools/approval.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/approval.rs) | `ApprovalBroker` — reused as-is for workspace-scope writes. Session-scope writes short-circuit when the setting allows. |
+| [`crates/mcpmux-gateway/src/services/session_roots.rs`](../../crates/mcpmux-gateway/src/services/session_roots.rs) | Pattern reference for `SessionOverrideRegistry`. Same `Arc<Self>` + `DashMap` + GC contract. |
+| [`crates/mcpmux-gateway/src/services/feature_set_resolver.rs`](../../crates/mcpmux-gateway/src/services/feature_set_resolver.rs) | Tier 1/2/3 resolver — stays untouched. Override composition happens in `FeatureService`, not here. |
+| [`crates/mcpmux-gateway/src/pool/features/facade.rs`](../../crates/mcpmux-gateway/src/pool/features/facade.rs) | `FeatureService::get_tools_for_grants` is the materialization chokepoint where the override composition runs. |
+| [`crates/mcpmux-gateway/src/consumers/mcp_notifier.rs`](../../crates/mcpmux-gateway/src/consumers/mcp_notifier.rs) | Session-reap pass — extend to also drop override entries. `notify_peer_lists_changed` is reused for the post-write list refresh. |
+| [`apps/desktop/src/features/workspaces/WorkspacesPage.tsx`](../../apps/desktop/src/features/workspaces/WorkspacesPage.tsx) | New "Active session overrides" sub-panel slots into the existing live-session inspector. |
+
+---
+
+## Related work
+
+- [mcpmux/mcp-mux PR #151](https://github.com/mcpmux/mcp-mux/pull/151) — workspace-root-driven FeatureSet routing + the `mcpmux_*` meta-tool namespace this PR builds on. Must merge (or be consumed via fork) first.
+- [`docs/planning/issue-52-secret-text-input-syntax.md`](./issue-52-secret-text-input-syntax.md) — sibling planning doc; same conventions used here. Independent feature, no functional overlap.
+- [`jsg-tech-check` homelab plan](../../../jsg-tech-check/docs/setup/home-lab-overview.md#mcp-strategy--current-state) — the consuming use case. The "Personal vs Work" Spaces + bundled `set-times-app` / `sync2hire-platform` model leans on bindings; this doc adds the "no, actually just enable this one MCP for the next 10 minutes" escape valve.
+- [MCP spec — Tools `list_changed`](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#list-changed-notification) — the protocol mechanism that makes the post-write tool-list refresh observable mid-conversation. Already wired by PR #151.
+
+---
+
+## Reconciliation
+
+This doc is the source of truth for what gets built. When implementation completes, update the **Status** field at the top and reconcile any deviations (extra files, dropped phases, scope changes) per [`update-planning-md`](~/.cursor/commands/update-planning-md.md).

From 5e04746a5fdd34304cb1e77993c4fc6e54303be0 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 18 May 2026 22:49:36 -0600
Subject: [PATCH 03/48] docs: add macOS build-from-source and app swap guide

Document how to replace /Applications/McpMux.app with a local build
while preserving user data in Application Support and the keychain.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 docs/build-from-source-macos.md | 182 ++++++++++++++++++++++++++++++++
 1 file changed, 182 insertions(+)
 create mode 100644 docs/build-from-source-macos.md

diff --git a/docs/build-from-source-macos.md b/docs/build-from-source-macos.md
new file mode 100644
index 00000000..0410fdb7
--- /dev/null
+++ b/docs/build-from-source-macos.md
@@ -0,0 +1,182 @@
+# Build from Source and Replace the Installed App (macOS)
+
+Replace the release McpMux in `/Applications` with a locally built copy from this repo. Useful when running a fork, a feature branch, or patches that haven't shipped yet.
+
+---
+
+## What survives a swap
+
+Replacing the `.app` bundle does **not** touch your data. McpMux stores everything outside the app:
+
+| Data | Location |
+| ---- | -------- |
+| SQLite DB (spaces, servers, clients, settings) | `~/Library/Application Support/com.mcpmux.desktop/mcpmux.db` |
+| Per-space files | `~/Library/Application Support/com.mcpmux.desktop/spaces/` |
+| Logs | `~/Library/Application Support/com.mcpmux.desktop/logs/` |
+| Encryption master key | macOS Keychain (`com.mcpmux.desktop` service) |
+| OAuth tokens / credentials | Encrypted in SQLite + Keychain |
+
+The app identifier (`com.mcpmux.desktop`) is unchanged between release and source builds, so the new binary reads the same data directory and keychain entries.
+
+**What you might need to redo:** OAuth re-auth in Cursor/Claude Desktop if DCR or token validation changed on your branch. Your McpMux config, spaces, and server installs stay put.
+
+---
+
+## Prerequisites
+
+From repo root (`mcp-mux/`):
+
+- Rust 1.75+
+- Node.js 20+
+- pnpm 9+
+- Xcode Command Line Tools (`xcode-select --install`)
+
+First-time setup (if deps aren't installed):
+
+```bash
+pnpm install
+```
+
+---
+
+## Option A — Full build (recommended)
+
+Rebuilds the React frontend and produces a fresh `.app` bundle. Use this when frontend or Tauri config changed, or when you want a clean bundle.
+
+### 1. Quit the running app
+
+```bash
+osascript -e 'tell application "McpMux" to quit' 2>/dev/null || true
+# Give it a moment to release the gateway port
+sleep 2
+```
+
+### 2. Build
+
+```bash
+cd /path/to/mcp-mux
+pnpm build
+```
+
+First build: ~5–10 min. Incremental: ~1–3 min.
+
+Output:
+
+```
+target/release/bundle/macos/McpMux.app
+target/release/bundle/dmg/McpMux_*.dmg   # optional installer artifact
+```
+
+### 3. Backup and swap
+
+```bash
+# Backup current install (skip if you already have a recent .bak)
+sudo mv /Applications/McpMux.app /Applications/McpMux.app.bak
+
+# Install the new build
+sudo cp -R target/release/bundle/macos/McpMux.app /Applications/
+
+# Fix ownership (sudo cp leaves root-owned files)
+sudo chown -R "$(whoami):admin" /Applications/McpMux.app
+```
+
+### 4. Re-sign (required after manual swap)
+
+macOS Gatekeeper rejects a bundle whose binary was replaced without re-signing:
+
+```bash
+xattr -dr com.apple.quarantine /Applications/McpMux.app 2>/dev/null || true
+codesign --force --deep --sign - /Applications/McpMux.app
+```
+
+### 5. Launch
+
+```bash
+open /Applications/McpMux.app
+```
+
+Verify: spaces, installed servers, and gateway on `localhost:45818` should look exactly as before.
+
+---
+
+## Option B — Binary-only swap (fast path)
+
+When you changed **Rust only** (no frontend, no `tauri.conf.json` changes). Skips the Vite build and DMG step.
+
+```bash
+osascript -e 'tell application "McpMux" to quit' 2>/dev/null || true
+sleep 2
+
+cd /path/to/mcp-mux
+cargo build --release -p mcpmux
+
+cp /Applications/McpMux.app/Contents/MacOS/mcpmux \
+   /Applications/McpMux.app/Contents/MacOS/mcpmux.bak
+cp target/release/mcpmux /Applications/McpMux.app/Contents/MacOS/mcpmux
+
+xattr -dr com.apple.quarantine /Applications/McpMux.app 2>/dev/null || true
+codesign --force --deep --sign - /Applications/McpMux.app
+
+open /Applications/McpMux.app
+```
+
+Keeps the existing bundle shell (icons, Info.plist, embedded frontend from last full build). Only the Rust binary updates.
+
+---
+
+## Rollback
+
+### Full build rollback
+
+```bash
+osascript -e 'tell application "McpMux" to quit' 2>/dev/null || true
+sudo rm -rf /Applications/McpMux.app
+sudo mv /Applications/McpMux.app.bak /Applications/McpMux.app
+open /Applications/McpMux.app
+```
+
+### Binary-only rollback
+
+```bash
+osascript -e 'tell application "McpMux" to quit' 2>/dev/null || true
+cp /Applications/McpMux.app/Contents/MacOS/mcpmux.bak \
+   /Applications/McpMux.app/Contents/MacOS/mcpmux
+codesign --force --deep --sign - /Applications/McpMux.app
+open /Applications/McpMux.app
+```
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+| ------- | --- |
+| "App is damaged" / won't open | Re-run `codesign --force --deep --sign - /Applications/McpMux.app` |
+| Gateway port already in use | Old process still running — `pkill -f mcpmux` then relaunch |
+| Cursor OAuth fails after swap | Re-trigger MCP OAuth in Cursor (DCR redirect URI validation may have changed) |
+| Empty app / missing UI | You used binary-only swap but frontend changed — run Option A (full build) |
+| Permission denied on `/Applications` | Use `sudo` for mv/cp/chown, or install to `~/Applications/` and skip sudo |
+
+---
+
+## One-liner (full build + swap)
+
+Assumes you're in repo root and have a recent backup:
+
+```bash
+osascript -e 'tell application "McpMux" to quit' 2>/dev/null; sleep 2 && \
+pnpm build && \
+sudo rm -rf /Applications/McpMux.app && \
+sudo cp -R target/release/bundle/macos/McpMux.app /Applications/ && \
+sudo chown -R "$(whoami):admin" /Applications/McpMux.app && \
+xattr -dr com.apple.quarantine /Applications/McpMux.app 2>/dev/null; \
+codesign --force --deep --sign - /Applications/McpMux.app && \
+open /Applications/McpMux.app
+```
+
+---
+
+## Related
+
+- [`AGENTS.md`](../AGENTS.md) — build commands and project layout
+- [`CLAUDE.md`](../CLAUDE.md) — full dev environment reference

From e72b64e96de49f2ba85637c8673e0942246aa59b Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 18 May 2026 23:04:01 -0600
Subject: [PATCH 04/48] feat(gateway): add SessionOverrideRegistry and
 list-path composition

Phase 1 of dynamic MCP toggling: per-session enable/disable sets wired
through FeatureService list paths, session GC, and composition tests.
Also fixes a DashMap deadlock in SessionRootsRegistry::record_resolution.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 .../src/consumers/mcp_notifier.rs             |   7 +-
 crates/mcpmux-gateway/src/lib.rs              |   2 +-
 crates/mcpmux-gateway/src/mcp/handler.rs      |  38 ++--
 .../src/pool/features/facade.rs               |  89 +++++++-
 crates/mcpmux-gateway/src/pool/routing.rs     |   9 +-
 .../src/pool/service_factory.rs               |   4 +-
 crates/mcpmux-gateway/src/server/handlers.rs  |   6 +-
 crates/mcpmux-gateway/src/server/mod.rs       |   1 +
 .../src/server/service_container.rs           |   8 +-
 .../src/services/meta_tools/diff.rs           |   2 +-
 crates/mcpmux-gateway/src/services/mod.rs     |   2 +
 .../src/services/session_overrides.rs         | 201 ++++++++++++++++++
 .../src/services/session_roots.rs             |  16 +-
 .../planning/dynamic-mcp-toggle-meta-tools.md |  29 +--
 tests/rust/src/services.rs                    |   4 +-
 .../rust/tests/integration/feature_routing.rs |   3 +-
 tests/rust/tests/integration/mcp_flows.rs     |  35 +--
 tests/rust/tests/integration/meta_tools.rs    |  97 ++++++++-
 .../streamable_http/gateway_notifications.rs  |   1 +
 19 files changed, 478 insertions(+), 76 deletions(-)
 create mode 100644 crates/mcpmux-gateway/src/services/session_overrides.rs

diff --git a/crates/mcpmux-gateway/src/consumers/mcp_notifier.rs b/crates/mcpmux-gateway/src/consumers/mcp_notifier.rs
index 30723200..5820296c 100644
--- a/crates/mcpmux-gateway/src/consumers/mcp_notifier.rs
+++ b/crates/mcpmux-gateway/src/consumers/mcp_notifier.rs
@@ -26,7 +26,7 @@ use tracing::{debug, info, trace, warn};
 use uuid::Uuid;
 
 use crate::pool::FeatureService;
-use crate::services::FeatureSetResolverService;
+use crate::services::{FeatureSetResolverService, SessionOverrideRegistry};
 
 /// MCP Notifier — sends `list_changed` notifications to connected sessions.
 ///
@@ -58,6 +58,8 @@ pub struct MCPNotifier {
     feature_set_resolver: Arc<FeatureSetResolverService>,
     /// Feature service for calculating content hashes
     feature_service: Arc<FeatureService>,
+    /// Session override registry — reaped alongside session roots.
+    session_overrides: Arc<SessionOverrideRegistry>,
     /// Throttle tracker: (space_id, notification_type) -> last_sent_timestamp
     /// Prevents sending duplicate notifications within THROTTLE_WINDOW
     throttle_tracker: Arc<RwLock<HashMap<(Uuid, NotificationType), Instant>>>,
@@ -110,11 +112,13 @@ impl MCPNotifier {
     pub fn new(
         feature_set_resolver: Arc<FeatureSetResolverService>,
         feature_service: Arc<FeatureService>,
+        session_overrides: Arc<SessionOverrideRegistry>,
     ) -> Self {
         Self {
             sessions: Arc::new(RwLock::new(HashMap::new())),
             feature_set_resolver,
             feature_service,
+            session_overrides,
             throttle_tracker: Arc::new(RwLock::new(HashMap::new())),
             state_hashes: Arc::new(RwLock::new(HashMap::new())),
         }
@@ -354,6 +358,7 @@ impl MCPNotifier {
         // sessions that no longer exist.
         for sid in &dead {
             self.feature_set_resolver.session_roots().remove(sid);
+            self.session_overrides.remove(sid);
         }
         info!(
             reaped = dead.len(),
diff --git a/crates/mcpmux-gateway/src/lib.rs b/crates/mcpmux-gateway/src/lib.rs
index c974b0a3..92ada347 100644
--- a/crates/mcpmux-gateway/src/lib.rs
+++ b/crates/mcpmux-gateway/src/lib.rs
@@ -76,7 +76,7 @@ pub use pool::{
 };
 
 // Services module
-pub use services::{EventEmitter, GrantService, PrefixCacheService};
+pub use services::{EventEmitter, GrantService, PrefixCacheService, SessionOverrideRegistry};
 
 // MCP module (rmcp-based implementation)
 pub use mcp::McpMuxGatewayHandler;
diff --git a/crates/mcpmux-gateway/src/mcp/handler.rs b/crates/mcpmux-gateway/src/mcp/handler.rs
index 0279f6ec..3095c656 100644
--- a/crates/mcpmux-gateway/src/mcp/handler.rs
+++ b/crates/mcpmux-gateway/src/mcp/handler.rs
@@ -676,7 +676,7 @@ impl ServerHandler for McpMuxGatewayHandler {
             .services
             .pool_services
             .feature_service
-            .get_tools_for_grants(&space_id.to_string(), &feature_set_ids)
+            .get_tools_for_grants(&space_id.to_string(), &feature_set_ids, session_id_owned.as_deref())
             .await
             .map_err(|e| McpError::internal_error(format!("Failed to get tools: {}", e), None))?;
 
@@ -861,7 +861,11 @@ impl ServerHandler for McpMuxGatewayHandler {
             .services
             .pool_services
             .feature_service
-            .get_prompts_for_grants(&space_id.to_string(), &feature_set_ids)
+            .get_prompts_for_grants(
+                &space_id.to_string(),
+                &feature_set_ids,
+                session_id_owned.as_deref(),
+            )
             .await
             .map_err(|e| McpError::internal_error(format!("Failed to get prompts: {}", e), None))?;
 
@@ -897,11 +901,9 @@ impl ServerHandler for McpMuxGatewayHandler {
         let oauth_ctx = self
             .get_oauth_context(&context.extensions)
             .map_err(|e| McpError::invalid_params(e.to_string(), None))?;
+        let session_id_owned = extract_session_id(&context.extensions);
         let (space_id, feature_set_ids) = self
-            .resolve_routing(
-                extract_session_id(&context.extensions).as_deref(),
-                &oauth_ctx.client_id,
-            )
+            .resolve_routing(session_id_owned.as_deref(), &oauth_ctx.client_id)
             .await?;
 
         let (server_id, prompt_name) = self
@@ -916,7 +918,11 @@ impl ServerHandler for McpMuxGatewayHandler {
             .services
             .pool_services
             .feature_service
-            .get_prompts_for_grants(&space_id.to_string(), &feature_set_ids)
+            .get_prompts_for_grants(
+                &space_id.to_string(),
+                &feature_set_ids,
+                session_id_owned.as_deref(),
+            )
             .await
             .map_err(|e| {
                 McpError::internal_error(format!("Failed to verify authorization: {}", e), None)
@@ -972,7 +978,11 @@ impl ServerHandler for McpMuxGatewayHandler {
             .services
             .pool_services
             .feature_service
-            .get_resources_for_grants(&space_id.to_string(), &feature_set_ids)
+            .get_resources_for_grants(
+                &space_id.to_string(),
+                &feature_set_ids,
+                session_id_owned.as_deref(),
+            )
             .await
             .map_err(|e| {
                 McpError::internal_error(format!("Failed to get resources: {}", e), None)
@@ -1006,11 +1016,9 @@ impl ServerHandler for McpMuxGatewayHandler {
         let oauth_ctx = self
             .get_oauth_context(&context.extensions)
             .map_err(|e| McpError::invalid_params(e.to_string(), None))?;
+        let session_id_owned = extract_session_id(&context.extensions);
         let (space_id, feature_set_ids) = self
-            .resolve_routing(
-                extract_session_id(&context.extensions).as_deref(),
-                &oauth_ctx.client_id,
-            )
+            .resolve_routing(session_id_owned.as_deref(), &oauth_ctx.client_id)
             .await?;
 
         let server_id = self
@@ -1030,7 +1038,11 @@ impl ServerHandler for McpMuxGatewayHandler {
             .services
             .pool_services
             .feature_service
-            .get_resources_for_grants(&space_id.to_string(), &feature_set_ids)
+            .get_resources_for_grants(
+                &space_id.to_string(),
+                &feature_set_ids,
+                session_id_owned.as_deref(),
+            )
             .await
             .map_err(|e| {
                 McpError::internal_error(format!("Failed to verify authorization: {}", e), None)
diff --git a/crates/mcpmux-gateway/src/pool/features/facade.rs b/crates/mcpmux-gateway/src/pool/features/facade.rs
index ad0914c3..c3a6d461 100644
--- a/crates/mcpmux-gateway/src/pool/features/facade.rs
+++ b/crates/mcpmux-gateway/src/pool/features/facade.rs
@@ -1,10 +1,11 @@
 //! Feature Service Facade - Unified API delegating to specialized services
 
 use anyhow::Result;
+use std::collections::HashSet;
 use std::sync::Arc;
 
 use crate::pool::instance::McpClient;
-use crate::services::PrefixCacheService;
+use crate::services::{PrefixCacheService, SessionOverrideRegistry};
 use mcpmux_core::{FeatureSetRepository, FeatureType, ServerFeature, ServerFeatureRepository};
 
 use super::{
@@ -16,6 +17,7 @@ pub struct FeatureService {
     discovery: Arc<FeatureDiscoveryService>,
     resolution: Arc<FeatureResolutionService>,
     routing: Arc<FeatureRoutingService>,
+    session_overrides: Arc<SessionOverrideRegistry>,
 }
 
 impl FeatureService {
@@ -23,6 +25,7 @@ impl FeatureService {
         feature_repo: Arc<dyn ServerFeatureRepository>,
         feature_set_repo: Arc<dyn FeatureSetRepository>,
         prefix_cache: Arc<PrefixCacheService>,
+        session_overrides: Arc<SessionOverrideRegistry>,
     ) -> Self {
         let discovery = Arc::new(FeatureDiscoveryService::new(feature_repo.clone()));
 
@@ -41,6 +44,7 @@ impl FeatureService {
             discovery,
             resolution,
             routing,
+            session_overrides,
         }
     }
 
@@ -86,35 +90,98 @@ impl FeatureService {
             .await
     }
 
-    // Type-specific helpers
+    /// Resolve granted feature sets to tools, applying session server overrides.
     pub async fn get_tools_for_grants(
         &self,
         space_id: &str,
         feature_set_ids: &[String],
+        session_id: Option<&str>,
     ) -> Result<Vec<ServerFeature>> {
-        self.resolution
-            .resolve_feature_sets(space_id, feature_set_ids, Some(FeatureType::Tool))
-            .await
+        self.get_features_for_grants(
+            space_id,
+            feature_set_ids,
+            session_id,
+            Some(FeatureType::Tool),
+        )
+        .await
     }
 
+    /// Resolve granted feature sets to prompts, applying session server overrides.
     pub async fn get_prompts_for_grants(
         &self,
         space_id: &str,
         feature_set_ids: &[String],
+        session_id: Option<&str>,
     ) -> Result<Vec<ServerFeature>> {
-        self.resolution
-            .resolve_feature_sets(space_id, feature_set_ids, Some(FeatureType::Prompt))
-            .await
+        self.get_features_for_grants(
+            space_id,
+            feature_set_ids,
+            session_id,
+            Some(FeatureType::Prompt),
+        )
+        .await
     }
 
+    /// Resolve granted feature sets to resources, applying session server overrides.
     pub async fn get_resources_for_grants(
         &self,
         space_id: &str,
         feature_set_ids: &[String],
+        session_id: Option<&str>,
     ) -> Result<Vec<ServerFeature>> {
-        self.resolution
-            .resolve_feature_sets(space_id, feature_set_ids, Some(FeatureType::Resource))
-            .await
+        self.get_features_for_grants(
+            space_id,
+            feature_set_ids,
+            session_id,
+            Some(FeatureType::Resource),
+        )
+        .await
+    }
+
+    /// Shared list materialization: binding FS resolution + session overrides.
+    async fn get_features_for_grants(
+        &self,
+        space_id: &str,
+        feature_set_ids: &[String],
+        session_id: Option<&str>,
+        filter_type: Option<FeatureType>,
+    ) -> Result<Vec<ServerFeature>> {
+        let binding_features = self
+            .resolution
+            .resolve_feature_sets(space_id, feature_set_ids, filter_type.clone())
+            .await?;
+
+        let Some(session_id) = session_id else {
+            return Ok(binding_features);
+        };
+
+        let enabled = self.session_overrides.enabled_set(session_id);
+        let disabled = self.session_overrides.disabled_set(session_id);
+
+        if enabled.is_empty() && disabled.is_empty() {
+            return Ok(binding_features);
+        }
+
+        let mut binding_servers: HashSet<String> = binding_features
+            .iter()
+            .map(|f| f.server_id.clone())
+            .collect();
+        binding_servers.extend(enabled.iter().cloned());
+        binding_servers.retain(|server_id| !disabled.contains(server_id));
+
+        if binding_servers.is_empty() {
+            return Ok(Vec::new());
+        }
+
+        let all_features = self
+            .resolution
+            .get_all_features_for_space(space_id, filter_type)
+            .await?;
+
+        Ok(all_features
+            .into_iter()
+            .filter(|f| f.is_available && binding_servers.contains(&f.server_id))
+            .collect())
     }
 
     // Delegate to FeatureRoutingService (with type-specific helpers)
diff --git a/crates/mcpmux-gateway/src/pool/routing.rs b/crates/mcpmux-gateway/src/pool/routing.rs
index 28daed57..0c5b21fb 100644
--- a/crates/mcpmux-gateway/src/pool/routing.rs
+++ b/crates/mcpmux-gateway/src/pool/routing.rs
@@ -84,13 +84,14 @@ impl RoutingService {
         &self,
         space_id: Uuid,
         feature_set_ids: &[String],
+        session_id: Option<&str>,
     ) -> Result<Vec<RoutedTool>> {
         let space_id_str = space_id.to_string();
 
         // Resolve feature sets to allowed features
         let allowed_features = self
             .feature_service
-            .get_tools_for_grants(&space_id_str, feature_set_ids)
+            .get_tools_for_grants(&space_id_str, feature_set_ids, session_id)
             .await?;
 
         // Filter to just tools
@@ -119,12 +120,13 @@ impl RoutingService {
         &self,
         space_id: Uuid,
         feature_set_ids: &[String],
+        session_id: Option<&str>,
     ) -> Result<Vec<RoutedPrompt>> {
         let space_id_str = space_id.to_string();
 
         let allowed_features = self
             .feature_service
-            .get_prompts_for_grants(&space_id_str, feature_set_ids)
+            .get_prompts_for_grants(&space_id_str, feature_set_ids, session_id)
             .await?;
 
         let prompts: Vec<RoutedPrompt> = allowed_features
@@ -151,12 +153,13 @@ impl RoutingService {
         &self,
         space_id: Uuid,
         feature_set_ids: &[String],
+        session_id: Option<&str>,
     ) -> Result<Vec<RoutedResource>> {
         let space_id_str = space_id.to_string();
 
         let allowed_features = self
             .feature_service
-            .get_resources_for_grants(&space_id_str, feature_set_ids)
+            .get_resources_for_grants(&space_id_str, feature_set_ids, session_id)
             .await?;
 
         let resources: Vec<RoutedResource> = allowed_features
diff --git a/crates/mcpmux-gateway/src/pool/service_factory.rs b/crates/mcpmux-gateway/src/pool/service_factory.rs
index 99da9ad0..19ff52c0 100644
--- a/crates/mcpmux-gateway/src/pool/service_factory.rs
+++ b/crates/mcpmux-gateway/src/pool/service_factory.rs
@@ -44,6 +44,7 @@ impl ServiceFactory {
         deps: &GatewayDependencies,
         event_tx: tokio::sync::broadcast::Sender<DomainEvent>,
         prefix_cache: Arc<crate::services::PrefixCacheService>,
+        session_overrides: Arc<crate::services::SessionOverrideRegistry>,
     ) -> PoolServices {
         // TokenService - single source of truth for token management
         let token_service = Arc::new(TokenService::new(
@@ -80,7 +81,8 @@ impl ServiceFactory {
         let feature_service = Arc::new(FeatureService::new(
             deps.feature_repo.clone(),
             deps.feature_set_repo.clone(),
-            prefix_cache.clone(), // Clone here since we use it again below
+            prefix_cache.clone(),
+            session_overrides,
         ));
 
         // ServerManager - event-driven orchestrator for server state
diff --git a/crates/mcpmux-gateway/src/server/handlers.rs b/crates/mcpmux-gateway/src/server/handlers.rs
index 09f73593..3aa2db25 100644
--- a/crates/mcpmux-gateway/src/server/handlers.rs
+++ b/crates/mcpmux-gateway/src/server/handlers.rs
@@ -1087,7 +1087,7 @@ pub async fn oauth_get_client_features(
         .services
         .pool_services
         .feature_service
-        .get_tools_for_grants(&space_id_str, &feature_set_ids)
+        .get_tools_for_grants(&space_id_str, &feature_set_ids, None)
         .await
         .unwrap_or_default();
 
@@ -1095,7 +1095,7 @@ pub async fn oauth_get_client_features(
         .services
         .pool_services
         .feature_service
-        .get_prompts_for_grants(&space_id_str, &feature_set_ids)
+        .get_prompts_for_grants(&space_id_str, &feature_set_ids, None)
         .await
         .unwrap_or_default();
 
@@ -1103,7 +1103,7 @@ pub async fn oauth_get_client_features(
         .services
         .pool_services
         .feature_service
-        .get_resources_for_grants(&space_id_str, &feature_set_ids)
+        .get_resources_for_grants(&space_id_str, &feature_set_ids, None)
         .await
         .unwrap_or_default();
 
diff --git a/crates/mcpmux-gateway/src/server/mod.rs b/crates/mcpmux-gateway/src/server/mod.rs
index 4bf01dfc..8bd55dc9 100644
--- a/crates/mcpmux-gateway/src/server/mod.rs
+++ b/crates/mcpmux-gateway/src/server/mod.rs
@@ -231,6 +231,7 @@ impl GatewayServer {
         let notification_bridge = Arc::new(MCPNotifier::new(
             self.services.feature_set_resolver.clone(),
             self.services.pool_services.feature_service.clone(),
+            self.services.session_overrides.clone(),
         ));
 
         // Start listening to DomainEvents
diff --git a/crates/mcpmux-gateway/src/server/service_container.rs b/crates/mcpmux-gateway/src/server/service_container.rs
index d0b6d98c..c729ac15 100644
--- a/crates/mcpmux-gateway/src/server/service_container.rs
+++ b/crates/mcpmux-gateway/src/server/service_container.rs
@@ -9,7 +9,7 @@ use crate::pool::{PoolServices, ServerManager, ServiceFactory};
 use crate::services::{
     meta_tools, ApprovalBroker, AuthorizationService, ClientMetadataService,
     FeatureSetResolverService, GrantService, MetaToolRegistry, PrefixCacheService,
-    SessionRootsRegistry, SpaceResolverService,
+    SessionOverrideRegistry, SessionRootsRegistry, SpaceResolverService,
 };
 use mcpmux_core::DomainEvent;
 
@@ -40,6 +40,9 @@ pub struct ServiceContainer {
     /// Registry of per-session workspace roots (populated from MCP `roots/list`).
     pub session_roots: Arc<SessionRootsRegistry>,
 
+    /// Per-session server enable/disable overrides (in-memory, process-lifetime).
+    pub session_overrides: Arc<SessionOverrideRegistry>,
+
     /// Broker that asks the desktop UI for user approval on meta-tool writes.
     /// Shared with the Tauri layer so it can attach a publisher + respond.
     pub approval_broker: Arc<ApprovalBroker>,
@@ -82,10 +85,12 @@ impl ServiceContainer {
         ));
 
         // Create pool services using factory (pass event_tx and prefix_cache)
+        let session_overrides = SessionOverrideRegistry::new();
         let pool_services = ServiceFactory::create_pool_services(
             deps,
             domain_event_tx.clone(),
             prefix_cache_service.clone(),
+            session_overrides.clone(),
         );
 
         // Extract server_manager before moving pool_services
@@ -157,6 +162,7 @@ impl ServiceContainer {
             authorization_service,
             feature_set_resolver,
             session_roots,
+            session_overrides,
             approval_broker,
             meta_tool_registry,
             space_resolver_service,
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/diff.rs b/crates/mcpmux-gateway/src/services/meta_tools/diff.rs
index 43044303..f3e9d90f 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/diff.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/diff.rs
@@ -65,7 +65,7 @@ impl ToolDiff {
         let space_id_str = space_id.to_string();
         let ids = [fs.to_string()];
         let features = feature_service
-            .get_tools_for_grants(&space_id_str, &ids)
+            .get_tools_for_grants(&space_id_str, &ids, None)
             .await?;
         Ok(features
             .iter()
diff --git a/crates/mcpmux-gateway/src/services/mod.rs b/crates/mcpmux-gateway/src/services/mod.rs
index af1edb07..387b6739 100644
--- a/crates/mcpmux-gateway/src/services/mod.rs
+++ b/crates/mcpmux-gateway/src/services/mod.rs
@@ -13,6 +13,7 @@ mod grant_service;
 pub mod meta_tools;
 mod notification_emitter;
 mod prefix_cache;
+mod session_overrides;
 mod session_roots;
 mod space_resolver;
 
@@ -27,5 +28,6 @@ pub use meta_tools::{
 };
 pub use notification_emitter::NotificationEmitter;
 pub use prefix_cache::PrefixCacheService;
+pub use session_overrides::{SessionOverrideEntry, SessionOverrideRegistry};
 pub use session_roots::SessionRootsRegistry;
 pub use space_resolver::SpaceResolverService;
diff --git a/crates/mcpmux-gateway/src/services/session_overrides.rs b/crates/mcpmux-gateway/src/services/session_overrides.rs
new file mode 100644
index 00000000..e91f3e13
--- /dev/null
+++ b/crates/mcpmux-gateway/src/services/session_overrides.rs
@@ -0,0 +1,201 @@
+//! Session-scoped enable/disable overrides for backend MCP servers.
+//!
+//! When a client session calls `mcpmux_enable_server` / `mcpmux_disable_server`
+//! (Phase 3), the gateway mutates this registry. [`FeatureService`] consults it
+//! at list materialization time to compose the effective server set:
+//! `(binding_servers ∪ enabled) − disabled`.
+
+use std::collections::HashSet;
+use std::sync::Arc;
+
+use dashmap::DashMap;
+
+/// One session's override state for UI inspection (Phase 5).
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SessionOverrideEntry {
+    pub session_id: String,
+    pub enabled: Vec<String>,
+    pub disabled: Vec<String>,
+}
+
+/// Thread-safe registry mapping `mcp-session-id` to per-session server
+/// enable/disable sets. Process-lifetime only — reaped with the session.
+#[derive(Debug, Default)]
+pub struct SessionOverrideRegistry {
+    enabled: DashMap<String, HashSet<String>>,
+    disabled: DashMap<String, HashSet<String>>,
+}
+
+impl SessionOverrideRegistry {
+    /// Create a new registry wrapped in `Arc`.
+    pub fn new() -> Arc<Self> {
+        Arc::new(Self {
+            enabled: DashMap::new(),
+            disabled: DashMap::new(),
+        })
+    }
+
+    /// Add `server_id` to the session's enabled set; remove from disabled.
+    pub fn enable(&self, session_id: impl Into<String>, server_id: impl Into<String>) {
+        let session_id = session_id.into();
+        let server_id = server_id.into();
+        if let Some(mut disabled) = self.disabled.get_mut(&session_id) {
+            disabled.remove(&server_id);
+            if disabled.is_empty() {
+                drop(disabled);
+                self.disabled.remove(&session_id);
+            }
+        }
+        self.enabled
+            .entry(session_id)
+            .or_default()
+            .insert(server_id);
+    }
+
+    /// Add `server_id` to the session's disabled set; remove from enabled.
+    pub fn disable(&self, session_id: impl Into<String>, server_id: impl Into<String>) {
+        let session_id = session_id.into();
+        let server_id = server_id.into();
+        if let Some(mut enabled) = self.enabled.get_mut(&session_id) {
+            enabled.remove(&server_id);
+            if enabled.is_empty() {
+                drop(enabled);
+                self.enabled.remove(&session_id);
+            }
+        }
+        self.disabled
+            .entry(session_id)
+            .or_default()
+            .insert(server_id);
+    }
+
+    /// Drop both override sets for a session.
+    pub fn clear(&self, session_id: &str) {
+        self.enabled.remove(session_id);
+        self.disabled.remove(session_id);
+    }
+
+    /// Enabled server ids for a session (empty when none).
+    pub fn enabled_set(&self, session_id: &str) -> HashSet<String> {
+        self.enabled
+            .get(session_id)
+            .map(|set| set.clone())
+            .unwrap_or_default()
+    }
+
+    /// Disabled server ids for a session (empty when none).
+    pub fn disabled_set(&self, session_id: &str) -> HashSet<String> {
+        self.disabled
+            .get(session_id)
+            .map(|set| set.clone())
+            .unwrap_or_default()
+    }
+
+    /// Drop a session's overrides — call on client disconnect / reap.
+    pub fn remove(&self, session_id: &str) {
+        self.enabled.remove(session_id);
+        self.disabled.remove(session_id);
+    }
+
+    /// Snapshot of every session with non-empty override state.
+    pub fn list_all(&self) -> Vec<SessionOverrideEntry> {
+        let mut session_ids: HashSet<String> = HashSet::new();
+        session_ids.extend(self.enabled.iter().map(|e| e.key().clone()));
+        session_ids.extend(self.disabled.iter().map(|e| e.key().clone()));
+
+        let mut out: Vec<SessionOverrideEntry> = session_ids
+            .into_iter()
+            .filter_map(|session_id| {
+                let enabled: Vec<String> = self
+                    .enabled
+                    .get(&session_id)
+                    .map(|set| set.iter().cloned().collect())
+                    .unwrap_or_default();
+                let disabled: Vec<String> = self
+                    .disabled
+                    .get(&session_id)
+                    .map(|set| set.iter().cloned().collect())
+                    .unwrap_or_default();
+                if enabled.is_empty() && disabled.is_empty() {
+                    return None;
+                }
+                Some(SessionOverrideEntry {
+                    session_id,
+                    enabled,
+                    disabled,
+                })
+            })
+            .collect();
+        out.sort_by(|a, b| a.session_id.cmp(&b.session_id));
+        out
+    }
+
+    /// Current number of sessions with enabled overrides. Test helper.
+    #[cfg(test)]
+    pub fn enabled_session_count(&self) -> usize {
+        self.enabled.len()
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_enable_round_trip() {
+        let reg = SessionOverrideRegistry::default();
+        reg.enable("sess-1", "github");
+        let enabled = reg.enabled_set("sess-1");
+        assert_eq!(enabled.len(), 1);
+        assert!(enabled.contains("github"));
+        assert!(reg.disabled_set("sess-1").is_empty());
+    }
+
+    #[test]
+    fn test_disable_round_trip() {
+        let reg = SessionOverrideRegistry::default();
+        reg.disable("sess-1", "firebase");
+        let disabled = reg.disabled_set("sess-1");
+        assert_eq!(disabled.len(), 1);
+        assert!(disabled.contains("firebase"));
+        assert!(reg.enabled_set("sess-1").is_empty());
+    }
+
+    #[test]
+    fn test_enable_clears_disable_and_vice_versa() {
+        let reg = SessionOverrideRegistry::default();
+        reg.disable("sess-1", "github");
+        reg.enable("sess-1", "github");
+        assert!(reg.enabled_set("sess-1").contains("github"));
+        assert!(!reg.disabled_set("sess-1").contains("github"));
+
+        reg.disable("sess-1", "github");
+        assert!(!reg.enabled_set("sess-1").contains("github"));
+        assert!(reg.disabled_set("sess-1").contains("github"));
+    }
+
+    #[test]
+    fn test_clear_and_remove() {
+        let reg = SessionOverrideRegistry::default();
+        reg.enable("sess-1", "github");
+        reg.disable("sess-1", "firebase");
+        reg.clear("sess-1");
+        assert!(reg.enabled_set("sess-1").is_empty());
+        assert!(reg.disabled_set("sess-1").is_empty());
+
+        reg.enable("sess-2", "slack");
+        reg.remove("sess-2");
+        assert!(reg.enabled_set("sess-2").is_empty());
+    }
+
+    #[test]
+    fn test_list_all() {
+        let reg = SessionOverrideRegistry::default();
+        reg.enable("b", "github");
+        reg.disable("a", "firebase");
+        let all = reg.list_all();
+        assert_eq!(all.len(), 2);
+        assert_eq!(all[0].session_id, "a");
+        assert_eq!(all[1].session_id, "b");
+    }
+}
diff --git a/crates/mcpmux-gateway/src/services/session_roots.rs b/crates/mcpmux-gateway/src/services/session_roots.rs
index d258c70d..ee8a4426 100644
--- a/crates/mcpmux-gateway/src/services/session_roots.rs
+++ b/crates/mcpmux-gateway/src/services/session_roots.rs
@@ -151,13 +151,17 @@ impl SessionRootsRegistry {
     /// `false` when it's the same as before.
     pub fn record_resolution(&self, session_id: &str, fs_id: Option<&str>) -> bool {
         let new_val: Option<String> = fs_id.map(|s| s.to_string());
-        match self.last_resolution.get(session_id) {
-            Some(prev) if *prev == new_val => false,
-            _ => {
-                self.last_resolution.insert(session_id.to_string(), new_val);
-                true
-            }
+        let unchanged = self
+            .last_resolution
+            .get(session_id)
+            .map(|prev| *prev == new_val)
+            .unwrap_or(false);
+        if unchanged {
+            return false;
         }
+        self.last_resolution
+            .insert(session_id.to_string(), new_val);
+        true
     }
 
     /// Returns every reported root across every active session, de-duplicated
diff --git a/docs/planning/dynamic-mcp-toggle-meta-tools.md b/docs/planning/dynamic-mcp-toggle-meta-tools.md
index 3fca5d91..d7333c84 100644
--- a/docs/planning/dynamic-mcp-toggle-meta-tools.md
+++ b/docs/planning/dynamic-mcp-toggle-meta-tools.md
@@ -1,7 +1,7 @@
 # Dynamic MCP Toggling via Meta Tools
 
-**Last Updated:** May 18, 2026
-**Status:** Planning — decisions locked, ready for implementation
+**Last Updated:** May 19, 2026
+**Status:** Phase 1 complete — SessionOverrideRegistry + list-path composition wired; Phases 2–5 pending
 **Branch:** `feat/dynamic-mcp-toggle-meta-tools`
 **Base branch:** `feat/workspace-root-routing` ([upstream PR #151](https://github.com/mcpmux/mcp-mux/pull/151))
 **Issue:** TBD — file after planning review
@@ -145,7 +145,7 @@ Each write fires `tools/list_changed` per-peer via the existing `MCPNotifier::no
 | File | Purpose |
 | ---- | ------- |
 | `crates/mcpmux-gateway/src/services/session_overrides.rs` | `SessionOverrideRegistry` — `DashMap`-backed enable/disable sets, GC hooks, query helpers (`is_enabled`, `is_disabled`, `effective_overlay`) |
-| `tests/rust/tests/integration/session_overrides.rs` | Integration tests: enable adds tool, disable removes tool, composition with binding, GC on session reap, per-peer `list_changed` fires |
+| `tests/rust/tests/integration/meta_tools.rs` | Composition tests: deny bootstrap, disable, additive (Phase 1); meta-tool E2E (existing) |
 | `docs/planning/dynamic-mcp-toggle-meta-tools.md` | This doc |
 
 ## Files to modify
@@ -169,18 +169,23 @@ Each write fires `tools/list_changed` per-peer via the existing `MCPNotifier::no
 
 ## Phasing
 
-### Phase 1 — `SessionOverrideRegistry` + composition wiring
+### Phase 1 — `SessionOverrideRegistry` + composition wiring ✅
 
-**Effort:** 1 evening
+**Effort:** 1 evening  
+**Completed:** May 19, 2026
+
+- [x] `crates/mcpmux-gateway/src/services/session_overrides.rs` — `DashMap`-backed registry with `enable`, `disable`, `clear`, `enabled_set`, `disabled_set`, `remove`, `list_all`
+- [x] Plumb `Arc<SessionOverrideRegistry>` through `ServiceContainer` → `ServiceFactory` → `FeatureService` and `MCPNotifier`
+- [x] `FeatureService::get_*_for_grants(..., session_id: Option<&str>)` applies server-level composition: `effective = (binding_servers ∪ enabled) − disabled`, then all available features per effective `server_id`
+- [x] All callsites updated (`handler.rs`, `routing.rs`, `handlers.rs`, `meta_tools/diff.rs`, integration tests) — MCP handler passes real session id; others pass `None`
+- [x] `MCPNotifier::reap_dead_sessions` drops override entries alongside session roots
+- [x] Unit tests in `session_overrides.rs`; composition tests in `tests/rust/tests/integration/meta_tools.rs` (deny bootstrap, disable, additive)
 
-- Add `crates/mcpmux-gateway/src/services/session_overrides.rs` mirroring `session_roots.rs` shape: `DashMap`-backed, `Arc<Self>` factory, `set_enabled`, `set_disabled`, `clear_enabled`, `clear_disabled`, `enabled_set`, `disabled_set`, `remove`, `list_all` for the UI.
-- Plumb `Arc<SessionOverrideRegistry>` through `ServiceContainer` into both `FeatureService` and `MCPNotifier`.
-- Extend `FeatureService::get_tools_for_grants` (+ prompts + resources) signatures to accept `session_id: Option<&str>` and apply `(servers ∪ enabled) − disabled` filtering.
-- Update `handler.rs` callsites to pass `session_id` from `RequestContext` headers.
-- `MCPNotifier` session-reap pass also drops override entries.
-- Unit tests in `session_overrides.rs`: set/get round-trip, enable/disable composition, GC on remove.
+**Outcome (verified):** Direct registry mutation changes the next `get_tools_for_grants` result. Meta-tools and UI unchanged. `RoutingService::call_tool` authorization deferred to Phase 3 (list-only in Phase 1).
 
-**Outcome:** A test that directly mutates `SessionOverrideRegistry` for a fake session id observes the next `FeatureService::get_tools_for_grants` call return the composed set. No meta-tools exist yet; UI unchanged. CI green.
+**Implementation notes:**
+- Server-level composition loads **all available** features for each effective `server_id` (not FS-partial tool subsets).
+- Fixed pre-existing DashMap deadlock in `SessionRootsRegistry::record_resolution` (`get` guard must not overlap `insert` on the same map).
 
 ### Phase 2 — `mcpmux_list_servers` read tool
 
diff --git a/tests/rust/src/services.rs b/tests/rust/src/services.rs
index 06501cce..e7500990 100644
--- a/tests/rust/src/services.rs
+++ b/tests/rust/src/services.rs
@@ -8,7 +8,7 @@ use mcpmux_core::DomainEvent;
 use tokio::sync::broadcast;
 
 use mcpmux_gateway::pool::{FeatureService, ServerManager};
-use mcpmux_gateway::services::PrefixCacheService;
+use mcpmux_gateway::services::{PrefixCacheService, SessionOverrideRegistry};
 
 use crate::mocks::{
     MockCredentialRepository, MockFeatureSetRepository, MockOutboundOAuthRepository,
@@ -59,6 +59,7 @@ impl ServerManagerTestHarness {
             feature_repo.clone(),
             feature_set_repo.clone(),
             prefix_cache.clone(),
+            SessionOverrideRegistry::new(),
         ));
 
         // Create ConnectionService mock
@@ -155,6 +156,7 @@ pub fn test_feature_service() -> (
         feature_repo.clone(),
         feature_set_repo.clone(),
         prefix_cache,
+        SessionOverrideRegistry::new(),
     ));
 
     (service, feature_repo, feature_set_repo)
diff --git a/tests/rust/tests/integration/feature_routing.rs b/tests/rust/tests/integration/feature_routing.rs
index c749eb22..a29593c7 100644
--- a/tests/rust/tests/integration/feature_routing.rs
+++ b/tests/rust/tests/integration/feature_routing.rs
@@ -7,7 +7,7 @@ use std::sync::Arc;
 use uuid::Uuid;
 
 use mcpmux_core::{FeatureSetRepository, ServerFeature, ServerFeatureRepository};
-use mcpmux_gateway::{FeatureService, PrefixCacheService};
+use mcpmux_gateway::{FeatureService, PrefixCacheService, SessionOverrideRegistry};
 use tests::mocks::{MockFeatureSetRepository, MockServerFeatureRepository};
 
 // Helper to create test features
@@ -38,6 +38,7 @@ fn create_feature_service(
         feature_repo as Arc<dyn ServerFeatureRepository>,
         feature_set_repo as Arc<dyn FeatureSetRepository>,
         prefix_cache,
+        SessionOverrideRegistry::new(),
     )
 }
 
diff --git a/tests/rust/tests/integration/mcp_flows.rs b/tests/rust/tests/integration/mcp_flows.rs
index 77c1cc09..04f23d40 100644
--- a/tests/rust/tests/integration/mcp_flows.rs
+++ b/tests/rust/tests/integration/mcp_flows.rs
@@ -17,7 +17,7 @@ use mcpmux_core::{
     FeatureSet, FeatureSetMember, FeatureSetRepository, FeatureType, MemberMode, MemberType,
     ServerFeature, ServerFeatureRepository,
 };
-use mcpmux_gateway::{FeatureService, PrefixCacheService};
+use mcpmux_gateway::{FeatureService, PrefixCacheService, SessionOverrideRegistry};
 use tests::mocks::{MockFeatureSetRepository, MockServerFeatureRepository};
 
 // Helper functions
@@ -56,6 +56,7 @@ impl TestContext {
             Arc::clone(&feature_repo) as Arc<dyn ServerFeatureRepository>,
             Arc::clone(&feature_set_repo) as Arc<dyn FeatureSetRepository>,
             Arc::clone(&prefix_cache),
+            SessionOverrideRegistry::new(),
         );
 
         Self {
@@ -156,7 +157,7 @@ async fn test_list_tools_with_all_grant() {
     // Simulate tools/list with grant
     let tools = ctx
         .service
-        .get_tools_for_grants(&ctx.space_id, &[all_fs_id])
+        .get_tools_for_grants(&ctx.space_id, &[all_fs_id], None)
         .await
         .unwrap();
 
@@ -192,7 +193,7 @@ async fn test_list_tools_with_restricted_grant() {
 
     let tools = ctx
         .service
-        .get_tools_for_grants(&ctx.space_id, &[custom_fs_id])
+        .get_tools_for_grants(&ctx.space_id, &[custom_fs_id], None)
         .await
         .unwrap();
 
@@ -235,7 +236,7 @@ async fn test_call_tool_unauthorized() {
 
     let tools = ctx
         .service
-        .get_tools_for_grants(&ctx.space_id, &[empty_fs_id])
+        .get_tools_for_grants(&ctx.space_id, &[empty_fs_id], None)
         .await
         .unwrap();
 
@@ -261,7 +262,7 @@ async fn test_list_resources_with_grant() {
 
     let resources = ctx
         .service
-        .get_resources_for_grants(&ctx.space_id, &[all_fs_id])
+        .get_resources_for_grants(&ctx.space_id, &[all_fs_id], None)
         .await
         .unwrap();
 
@@ -304,7 +305,7 @@ async fn test_resource_custom_uri_scheme() {
 
     let resources = ctx
         .service
-        .get_resources_for_grants(&ctx.space_id, &[all_fs_id])
+        .get_resources_for_grants(&ctx.space_id, &[all_fs_id], None)
         .await
         .unwrap();
 
@@ -334,7 +335,7 @@ async fn test_list_prompts_with_grant() {
 
     let prompts = ctx
         .service
-        .get_prompts_for_grants(&ctx.space_id, &[all_fs_id])
+        .get_prompts_for_grants(&ctx.space_id, &[all_fs_id], None)
         .await
         .unwrap();
 
@@ -396,17 +397,17 @@ async fn test_server_provides_multiple_feature_types() {
     // Filter by type
     let tools = ctx
         .service
-        .get_tools_for_grants(&ctx.space_id, &[all_fs_id.clone()])
+        .get_tools_for_grants(&ctx.space_id, &[all_fs_id.clone()], None)
         .await
         .unwrap();
     let prompts = ctx
         .service
-        .get_prompts_for_grants(&ctx.space_id, &[all_fs_id.clone()])
+        .get_prompts_for_grants(&ctx.space_id, &[all_fs_id.clone()], None)
         .await
         .unwrap();
     let resources = ctx
         .service
-        .get_resources_for_grants(&ctx.space_id, &[all_fs_id])
+        .get_resources_for_grants(&ctx.space_id, &[all_fs_id], None)
         .await
         .unwrap();
 
@@ -441,7 +442,7 @@ async fn test_aggregate_tools_from_multiple_servers() {
 
     let tools = ctx
         .service
-        .get_tools_for_grants(&ctx.space_id, &[all_fs_id])
+        .get_tools_for_grants(&ctx.space_id, &[all_fs_id], None)
         .await
         .unwrap();
 
@@ -471,7 +472,7 @@ async fn test_partial_server_grant() {
 
     let tools = ctx
         .service
-        .get_tools_for_grants(&ctx.space_id, &[server_all_a_id])
+        .get_tools_for_grants(&ctx.space_id, &[server_all_a_id], None)
         .await
         .unwrap();
 
@@ -519,11 +520,12 @@ async fn test_features_dont_leak_between_spaces() {
         feature_repo as Arc<dyn ServerFeatureRepository>,
         feature_set_repo as Arc<dyn FeatureSetRepository>,
         prefix_cache,
+        SessionOverrideRegistry::new(),
     );
 
     // Query work space
     let work_tools = service
-        .get_tools_for_grants(&space_work, &[work_all_id])
+        .get_tools_for_grants(&space_work, &[work_all_id], None)
         .await
         .unwrap();
 
@@ -562,6 +564,7 @@ async fn test_routing_is_space_scoped() {
         feature_repo as Arc<dyn ServerFeatureRepository>,
         feature_set_repo as Arc<dyn FeatureSetRepository>,
         prefix_cache,
+        SessionOverrideRegistry::new(),
     );
 
     // Resolve same qualified name in different spaces
@@ -608,7 +611,7 @@ async fn test_unavailable_features_filtered_out() {
 
     let tools = ctx
         .service
-        .get_tools_for_grants(&ctx.space_id, &[all_fs_id])
+        .get_tools_for_grants(&ctx.space_id, &[all_fs_id], None)
         .await
         .unwrap();
 
@@ -630,7 +633,7 @@ async fn test_server_disconnect_marks_features_unavailable() {
     // Initially available
     let tools_before = ctx
         .service
-        .get_tools_for_grants(&ctx.space_id, &[all_fs_id.clone()])
+        .get_tools_for_grants(&ctx.space_id, &[all_fs_id.clone()], None)
         .await
         .unwrap();
     assert_eq!(tools_before.len(), 2);
@@ -644,7 +647,7 @@ async fn test_server_disconnect_marks_features_unavailable() {
     // After disconnect
     let tools_after = ctx
         .service
-        .get_tools_for_grants(&ctx.space_id, &[all_fs_id])
+        .get_tools_for_grants(&ctx.space_id, &[all_fs_id], None)
         .await
         .unwrap();
     assert_eq!(tools_after.len(), 0);
diff --git a/tests/rust/tests/integration/meta_tools.rs b/tests/rust/tests/integration/meta_tools.rs
index 4b81e6d5..0d56816c 100644
--- a/tests/rust/tests/integration/meta_tools.rs
+++ b/tests/rust/tests/integration/meta_tools.rs
@@ -11,14 +11,15 @@ use std::time::Duration;
 
 use futures::FutureExt;
 use mcpmux_core::{
-    normalize_workspace_root, Client, DomainEvent, FeatureSet, FeatureSetRepository,
-    InboundMcpClientRepository, ServerFeature, ServerFeatureRepository, SpaceRepository,
-    WorkspaceBindingRepository,
+    normalize_workspace_root, Client, DomainEvent, FeatureSet, FeatureSetMember,
+    FeatureSetRepository, InboundMcpClientRepository, MemberMode, MemberType, ServerFeature,
+    ServerFeatureRepository, SpaceRepository, WorkspaceBindingRepository,
 };
 use mcpmux_gateway::pool::FeatureService;
 use mcpmux_gateway::services::{
     meta_tools, ApprovalBroker, ApprovalDecision, ApprovalPayload, ApprovalPublisher,
-    FeatureSetResolverService, MetaToolRegistry, PrefixCacheService, SessionRootsRegistry,
+    FeatureSetResolverService, MetaToolRegistry, PrefixCacheService, SessionOverrideRegistry,
+    SessionRootsRegistry,
 };
 use mcpmux_storage::{
     Database, InboundClientRepository, SqliteFeatureSetRepository,
@@ -37,12 +38,15 @@ struct Fixture {
     feature_set_repo: Arc<dyn FeatureSetRepository>,
     binding_repo: Arc<dyn WorkspaceBindingRepository>,
     session_roots: Arc<SessionRootsRegistry>,
+    session_overrides: Arc<SessionOverrideRegistry>,
+    feature_service: Arc<FeatureService>,
     space_id: Uuid,
     /// Opaque client identity (UUID-as-string here; in production for DCR
     /// clients this can be a `client_metadata` URL).
     client_id: String,
     session_id: String,
     fs_android_id: Uuid,
+    github_tool_id: Uuid,
 }
 
 impl Fixture {
@@ -82,6 +86,7 @@ impl Fixture {
         feature2.description = Some("Deploy to Firebase".into());
         server_feature_repo.upsert(&feature1).await.unwrap();
         server_feature_repo.upsert(&feature2).await.unwrap();
+        let github_tool_id = feature1.id;
 
         // The space's auto-seeded Default FS is the resolver's baseline
         // when no binding matches — no "set active FS" step needed.
@@ -93,6 +98,7 @@ impl Fixture {
         client_repo.create(&client).await.unwrap();
 
         let session_roots = SessionRootsRegistry::new();
+        let session_overrides = SessionOverrideRegistry::new();
         let session_id = "sess-meta".to_string();
 
         let inbound_client_repo = Arc::new(InboundClientRepository::new(db.clone()));
@@ -108,6 +114,7 @@ impl Fixture {
             server_feature_repo.clone(),
             feature_set_repo.clone(),
             prefix_cache,
+            session_overrides.clone(),
         ));
 
         let broker = Arc::new(ApprovalBroker::new().with_timeout(Duration::from_millis(500)));
@@ -120,7 +127,7 @@ impl Fixture {
             binding_repo.clone(),
             server_feature_repo.clone(),
             resolver,
-            feature_service,
+            feature_service.clone(),
             session_roots.clone(),
             broker.clone(),
             tx,
@@ -134,10 +141,13 @@ impl Fixture {
             feature_set_repo,
             binding_repo,
             session_roots,
+            session_overrides,
+            feature_service,
             space_id,
             client_id,
             session_id,
             fs_android_id,
+            github_tool_id,
         }
     }
 
@@ -503,6 +513,7 @@ async fn bare_registry(
         server_feature_repo.clone(),
         feature_set_repo.clone(),
         prefix_cache,
+        SessionOverrideRegistry::new(),
     ));
     let (tx, rx) = broadcast::channel::<DomainEvent>(32);
     let registry = meta_tools::build_default_registry(
@@ -615,6 +626,7 @@ async fn master_switch_toggles_registry_visibility() {
         server_feature_repo.clone(),
         feature_set_repo.clone(),
         prefix_cache,
+        SessionOverrideRegistry::new(),
     ));
     let (tx, _) = broadcast::channel::<DomainEvent>(16);
     let registry = meta_tools::build_default_registry(
@@ -650,3 +662,78 @@ async fn master_switch_toggles_registry_visibility() {
 // Silence unused-import warnings from helper imports that only some tests exercise.
 #[allow(dead_code)]
 fn _unused(_: ApprovalPayload) {}
+
+// ============================================================================
+// Session override composition (Phase 1)
+// ============================================================================
+
+async fn github_only_fs(f: &Fixture) -> String {
+    let mut fs = FeatureSet::new_custom("GitHub only", f.space_id.to_string());
+    fs.members.push(FeatureSetMember {
+        id: Uuid::new_v4().to_string(),
+        feature_set_id: fs.id.clone(),
+        member_type: MemberType::Feature,
+        member_id: f.github_tool_id.to_string(),
+        mode: MemberMode::Include,
+    });
+    let id = fs.id.clone();
+    f.feature_set_repo.create(&fs).await.unwrap();
+    id
+}
+
+#[tokio::test]
+async fn session_override_deny_bootstrap_enables_server() {
+    let f = Fixture::new().await;
+    f.session_overrides.enable(&f.session_id, "github");
+
+    let tools = f
+        .feature_service
+        .get_tools_for_grants(&f.space_id.to_string(), &[], Some(&f.session_id))
+        .await
+        .unwrap();
+
+    assert_eq!(tools.len(), 1);
+    assert_eq!(tools[0].server_id, "github");
+    assert_eq!(tools[0].feature_name, "create_issue");
+}
+
+#[tokio::test]
+async fn session_override_disable_mutes_bound_server() {
+    let f = Fixture::new().await;
+    let fs_id = github_only_fs(&f).await;
+
+    let before = f
+        .feature_service
+        .get_tools_for_grants(&f.space_id.to_string(), &[fs_id.clone()], Some(&f.session_id))
+        .await
+        .unwrap();
+    assert_eq!(before.len(), 1);
+
+    f.session_overrides.disable(&f.session_id, "github");
+
+    let after = f
+        .feature_service
+        .get_tools_for_grants(&f.space_id.to_string(), &[fs_id], Some(&f.session_id))
+        .await
+        .unwrap();
+    assert!(after.is_empty());
+}
+
+#[tokio::test]
+async fn session_override_additive_over_binding() {
+    let f = Fixture::new().await;
+    let fs_id = github_only_fs(&f).await;
+
+    f.session_overrides.enable(&f.session_id, "firebase");
+
+    let tools = f
+        .feature_service
+        .get_tools_for_grants(&f.space_id.to_string(), &[fs_id], Some(&f.session_id))
+        .await
+        .unwrap();
+
+    assert_eq!(tools.len(), 2);
+    let servers: std::collections::HashSet<_> = tools.iter().map(|t| t.server_id.as_str()).collect();
+    assert!(servers.contains("github"));
+    assert!(servers.contains("firebase"));
+}
diff --git a/tests/rust/tests/streamable_http/gateway_notifications.rs b/tests/rust/tests/streamable_http/gateway_notifications.rs
index 7ba1fc85..5c722b53 100644
--- a/tests/rust/tests/streamable_http/gateway_notifications.rs
+++ b/tests/rust/tests/streamable_http/gateway_notifications.rs
@@ -200,6 +200,7 @@ impl TestGateway {
         let notifier = Arc::new(MCPNotifier::new(
             services.feature_set_resolver.clone(),
             services.pool_services.feature_service.clone(),
+            services.session_overrides.clone(),
         ));
 
         // Start MCPNotifier listening for domain events

From f29543aad281cff5cc8fbdd0feffdbb035824f0e Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 18 May 2026 23:06:26 -0600
Subject: [PATCH 05/48] feat(meta-tools): add mcpmux_list_servers read tool
 (Phase 2)

Server-level manifest with binding/session status per installed server.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 .../src/server/service_container.rs           |   1 +
 .../src/services/meta_tools/mod.rs            |   3 +
 .../src/services/meta_tools/registry.rs       |   5 +-
 .../src/services/meta_tools/tools.rs          | 126 ++++++++++++++++++
 .../planning/dynamic-mcp-toggle-meta-tools.md |  19 +--
 tests/rust/tests/integration/meta_tools.rs    |  98 ++++++++++++++
 6 files changed, 242 insertions(+), 10 deletions(-)

diff --git a/crates/mcpmux-gateway/src/server/service_container.rs b/crates/mcpmux-gateway/src/server/service_container.rs
index c729ac15..1273fa79 100644
--- a/crates/mcpmux-gateway/src/server/service_container.rs
+++ b/crates/mcpmux-gateway/src/server/service_container.rs
@@ -134,6 +134,7 @@ impl ServiceContainer {
             feature_set_resolver.clone(),
             pool_services.feature_service.clone(),
             session_roots.clone(),
+            session_overrides.clone(),
             approval_broker.clone(),
             domain_event_tx.clone(),
             deps.settings_repo.clone(),
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/mod.rs b/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
index 49c151ec..4b4e75d7 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
@@ -55,6 +55,7 @@ pub fn build_default_registry(
     resolver: std::sync::Arc<crate::services::FeatureSetResolverService>,
     feature_service: std::sync::Arc<crate::pool::FeatureService>,
     session_roots: std::sync::Arc<crate::services::SessionRootsRegistry>,
+    session_overrides: std::sync::Arc<crate::services::SessionOverrideRegistry>,
     approval_broker: std::sync::Arc<ApprovalBroker>,
     domain_event_tx: tokio::sync::broadcast::Sender<mcpmux_core::DomainEvent>,
     settings_repo: Option<std::sync::Arc<dyn mcpmux_core::AppSettingsRepository>>,
@@ -68,6 +69,7 @@ pub fn build_default_registry(
         resolver,
         feature_service,
         session_roots,
+        session_overrides,
         approval_broker,
         domain_event_tx,
         settings_repo,
@@ -77,6 +79,7 @@ pub fn build_default_registry(
     // Reads — no approval needed.
     registry.register(Box::new(tools::ListAllToolsTool));
     registry.register(Box::new(tools::ListFeatureSetsTool));
+    registry.register(Box::new(tools::ListServersTool));
     // Both `describe_resolution` and `describe_workspace` were removed by
     // user request — the read surface is just the two list_* tools above,
     // which an LLM can stitch into the same picture without an extra hop.
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/registry.rs b/crates/mcpmux-gateway/src/services/meta_tools/registry.rs
index 54307dd5..c1e3836d 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/registry.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/registry.rs
@@ -19,7 +19,9 @@ use tokio::sync::broadcast;
 
 use super::approval::ApprovalBroker;
 use crate::pool::FeatureService;
-use crate::services::{FeatureSetResolverService, SessionRootsRegistry};
+use crate::services::{
+    FeatureSetResolverService, SessionOverrideRegistry, SessionRootsRegistry,
+};
 
 /// App-settings key that toggles the entire `mcpmux_*` namespace.
 /// Present + "false" → hidden; missing or anything else → enabled.
@@ -39,6 +41,7 @@ pub struct MetaToolContext {
     pub resolver: Arc<FeatureSetResolverService>,
     pub feature_service: Arc<FeatureService>,
     pub session_roots: Arc<SessionRootsRegistry>,
+    pub session_overrides: Arc<SessionOverrideRegistry>,
     pub approval_broker: Arc<ApprovalBroker>,
     /// Broadcast domain events (e.g. ToolsChanged) so MCPNotifier can push
     /// `tools/list_changed` to connected peers after a write mutates state.
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
index 95fc1112..71cac23f 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
@@ -9,12 +9,14 @@ use mcpmux_core::{
 };
 use rmcp::model::{CallToolResult, Content};
 use serde_json::{json, Value};
+use std::collections::{HashMap, HashSet};
 use tokio::sync::broadcast;
 use tracing::info;
 use uuid::Uuid;
 
 use super::approval::{ApprovalPayload, ApprovalScope};
 use super::registry::{MetaTool, MetaToolCall, MetaToolError};
+use crate::services::ResolvedFeatureSet;
 
 /// Fire a `FeatureSetMembersChanged` event so MCPNotifier pushes a
 /// `tools/list_changed` notification to every connected client in the Space.
@@ -64,6 +66,33 @@ async fn caller_space_id(call: &MetaToolCall<'_>) -> Result<Uuid, MetaToolError>
     ))
 }
 
+/// Full resolver output for the caller — space + binding FS ids + source.
+async fn caller_resolution(call: &MetaToolCall<'_>) -> Result<ResolvedFeatureSet, MetaToolError> {
+    call.ctx
+        .resolver
+        .resolve(call.session_id, Some(call.client_id))
+        .await
+        .map_err(|e| MetaToolError::Internal(e.to_string()))
+}
+
+/// Derive the manifest status for one server in the caller's session.
+fn derive_server_status(
+    server_id: &str,
+    binding_servers: &HashSet<String>,
+    session_enabled: &HashSet<String>,
+    session_disabled: &HashSet<String>,
+) -> &'static str {
+    if session_disabled.contains(server_id) {
+        "disabled_via_session"
+    } else if session_enabled.contains(server_id) && !binding_servers.contains(server_id) {
+        "enabled_via_session"
+    } else if binding_servers.contains(server_id) {
+        "enabled_via_binding"
+    } else {
+        "inactive"
+    }
+}
+
 // ---------------------------------------------------------------------------
 // mcpmux_list_all_tools — read
 // ---------------------------------------------------------------------------
@@ -165,6 +194,103 @@ impl MetaTool for ListFeatureSetsTool {
     }
 }
 
+// ---------------------------------------------------------------------------
+// mcpmux_list_servers — read
+// ---------------------------------------------------------------------------
+
+pub struct ListServersTool;
+
+#[async_trait]
+impl MetaTool for ListServersTool {
+    fn name(&self) -> &'static str {
+        "mcpmux_list_servers"
+    }
+
+    fn description(&self) -> &'static str {
+        "List every MCP server installed in the caller's resolved Space with \
+         a coarse status per server: enabled_via_binding, enabled_via_session, \
+         disabled_via_session, or inactive. Use before enable/disable to see \
+         current routing state without loading every tool."
+    }
+
+    fn input_schema(&self) -> Value {
+        json!({ "type": "object", "properties": {} })
+    }
+
+    async fn call(&self, call: MetaToolCall<'_>) -> Result<CallToolResult, MetaToolError> {
+        let resolved = caller_resolution(&call).await?;
+        let space_id = resolved
+            .space_id
+            .ok_or_else(|| MetaToolError::Internal("space missing".into()))?;
+
+        let binding_features = call
+            .ctx
+            .feature_service
+            .resolve_feature_sets(&space_id.to_string(), &resolved.feature_set_ids)
+            .await?;
+        let binding_servers: HashSet<String> = binding_features
+            .iter()
+            .map(|f| f.server_id.clone())
+            .collect();
+
+        let session_enabled = call
+            .session_id
+            .map(|sid| call.ctx.session_overrides.enabled_set(sid))
+            .unwrap_or_default();
+        let session_disabled = call
+            .session_id
+            .map(|sid| call.ctx.session_overrides.disabled_set(sid))
+            .unwrap_or_default();
+
+        let features = call
+            .ctx
+            .server_feature_repo
+            .list_for_space(&space_id.to_string())
+            .await?;
+
+        let mut by_server: HashMap<String, (Option<String>, usize)> = HashMap::new();
+        for feature in &features {
+            if feature.feature_type != FeatureType::Tool {
+                continue;
+            }
+            let entry = by_server
+                .entry(feature.server_id.clone())
+                .or_insert((None, 0));
+            if entry.0.is_none() {
+                entry.0 = feature.display_name.clone();
+            }
+            entry.1 += 1;
+        }
+
+        let mut servers: Vec<Value> = by_server
+            .into_iter()
+            .map(|(id, (display_name, tool_count))| {
+                let name = display_name.unwrap_or_else(|| id.clone());
+                let status = derive_server_status(
+                    &id,
+                    &binding_servers,
+                    &session_enabled,
+                    &session_disabled,
+                );
+                json!({
+                    "id": id,
+                    "name": name,
+                    "tool_count": tool_count,
+                    "status": status,
+                })
+            })
+            .collect();
+        servers.sort_by(|a, b| {
+            a.get("id")
+                .and_then(|v| v.as_str())
+                .unwrap_or("")
+                .cmp(b.get("id").and_then(|v| v.as_str()).unwrap_or(""))
+        });
+
+        Ok(text_result(json!({ "servers": servers })))
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Writes — each goes through the ApprovalBroker before mutating state.
 // ---------------------------------------------------------------------------
diff --git a/docs/planning/dynamic-mcp-toggle-meta-tools.md b/docs/planning/dynamic-mcp-toggle-meta-tools.md
index d7333c84..f3c3db1c 100644
--- a/docs/planning/dynamic-mcp-toggle-meta-tools.md
+++ b/docs/planning/dynamic-mcp-toggle-meta-tools.md
@@ -1,7 +1,7 @@
 # Dynamic MCP Toggling via Meta Tools
 
 **Last Updated:** May 19, 2026
-**Status:** Phase 1 complete — SessionOverrideRegistry + list-path composition wired; Phases 2–5 pending
+**Status:** Phase 2 complete — `mcpmux_list_servers` read tool shipped; Phases 3–5 pending
 **Branch:** `feat/dynamic-mcp-toggle-meta-tools`
 **Base branch:** `feat/workspace-root-routing` ([upstream PR #151](https://github.com/mcpmux/mcp-mux/pull/151))
 **Issue:** TBD — file after planning review
@@ -187,17 +187,18 @@ Each write fires `tools/list_changed` per-peer via the existing `MCPNotifier::no
 - Server-level composition loads **all available** features for each effective `server_id` (not FS-partial tool subsets).
 - Fixed pre-existing DashMap deadlock in `SessionRootsRegistry::record_resolution` (`get` guard must not overlap `insert` on the same map).
 
-### Phase 2 — `mcpmux_list_servers` read tool
+### Phase 2 — `mcpmux_list_servers` read tool ✅
 
-**Effort:** 1 evening
+**Effort:** 1 evening  
+**Completed:** May 19, 2026
 
-- Add `ListServersTool` unit struct + `MetaTool` impl in `meta_tools/tools.rs`.
-- Implementation: load `ServerFeature::list_for_space(caller_space_id)`, group by `server_id`, compute `tool_count = features.iter().filter(|f| f.feature_type == Tool).count()`, derive `status` per server by checking `binding`, `session_overrides.enabled`, `session_overrides.disabled` in order.
-- JSON schema: empty `properties` (no args).
-- Register in `build_default_registry` alongside the existing reads.
-- Integration test: connect a fake session, call `mcpmux_list_servers`, assert response shape includes `status` enum values for both bound and unbound servers.
+- [x] `ListServersTool` in `meta_tools/tools.rs` — groups `ServerFeature::list_for_space` by `server_id`, counts tools, derives status
+- [x] Status enum: `enabled_via_binding | enabled_via_session | disabled_via_session | inactive` (binding → session-enabled → session-disabled priority)
+- [x] `SessionOverrideRegistry` plumbed into `MetaToolContext` for status derivation
+- [x] Registered in `build_default_registry`
+- [x] Integration tests: inactive (no binding), `enabled_via_binding`, session override statuses
 
-**Outcome:** An LLM calling `mcpmux_list_servers` from any session receives a server roster like `[{id: "github", name: "GitHub", tool_count: 24, status: "enabled_via_binding"}, {id: "firebase", name: "Firebase", tool_count: 18, status: "inactive"}, ...]`. No state mutation yet.
+**Outcome:** LLM calls `mcpmux_list_servers` and gets a server roster with per-server status. No state mutation.
 
 ### Phase 3 — `mcpmux_enable_server` / `mcpmux_disable_server` (session scope)
 
diff --git a/tests/rust/tests/integration/meta_tools.rs b/tests/rust/tests/integration/meta_tools.rs
index 0d56816c..d3df9c3f 100644
--- a/tests/rust/tests/integration/meta_tools.rs
+++ b/tests/rust/tests/integration/meta_tools.rs
@@ -129,6 +129,7 @@ impl Fixture {
             resolver,
             feature_service.clone(),
             session_roots.clone(),
+            session_overrides.clone(),
             broker.clone(),
             tx,
             None,
@@ -260,6 +261,100 @@ async fn list_feature_sets_returns_space_contents() {
     assert_eq!(sets.len(), 3, "Default + 2 custom expected");
 }
 
+fn server_status(body: &Value, server_id: &str) -> String {
+    body.get("servers")
+        .unwrap()
+        .as_array()
+        .unwrap()
+        .iter()
+        .find(|s| s.get("id").and_then(|v| v.as_str()) == Some(server_id))
+        .unwrap()
+        .get("status")
+        .unwrap()
+        .as_str()
+        .unwrap()
+        .to_string()
+}
+
+async fn bind_github_only_to_session_root(f: &Fixture) -> String {
+    use mcpmux_core::WorkspaceBinding;
+
+    let fs_id = github_only_fs(f).await;
+    let root = "/tmp/mcpmux-list-servers-test";
+    f.session_roots.set_roots_capable(&f.session_id, true);
+    f.session_roots.set(&f.session_id, [root]);
+    let binding = WorkspaceBinding::new(
+        normalize_workspace_root(root),
+        f.space_id,
+        fs_id.clone(),
+    );
+    f.binding_repo.create(&binding).await.unwrap();
+    fs_id
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn list_servers_marks_unbound_servers_inactive() {
+    let f = Fixture::new().await;
+    let result = f
+        .registry
+        .call(
+            "mcpmux_list_servers",
+            &f.client_id,
+            Some(&f.session_id),
+            json!({}),
+        )
+        .await
+        .unwrap();
+    assert!(!Fixture::is_error(&result));
+    let body = Fixture::result_json(&result);
+    let servers = body.get("servers").unwrap().as_array().unwrap();
+    assert_eq!(servers.len(), 2);
+    assert_eq!(server_status(&body, "github"), "inactive");
+    assert_eq!(server_status(&body, "firebase"), "inactive");
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn list_servers_shows_enabled_via_binding() {
+    let f = Fixture::new().await;
+    bind_github_only_to_session_root(&f).await;
+
+    let result = f
+        .registry
+        .call(
+            "mcpmux_list_servers",
+            &f.client_id,
+            Some(&f.session_id),
+            json!({}),
+        )
+        .await
+        .unwrap();
+    let body = Fixture::result_json(&result);
+    assert_eq!(server_status(&body, "github"), "enabled_via_binding");
+    assert_eq!(server_status(&body, "firebase"), "inactive");
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn list_servers_shows_session_override_statuses() {
+    let f = Fixture::new().await;
+    bind_github_only_to_session_root(&f).await;
+    f.session_overrides.enable(&f.session_id, "firebase");
+    f.session_overrides.disable(&f.session_id, "github");
+
+    let result = f
+        .registry
+        .call(
+            "mcpmux_list_servers",
+            &f.client_id,
+            Some(&f.session_id),
+            json!({}),
+        )
+        .await
+        .unwrap();
+    let body = Fixture::result_json(&result);
+    assert_eq!(server_status(&body, "github"), "disabled_via_session");
+    assert_eq!(server_status(&body, "firebase"), "enabled_via_session");
+}
+
 // `describe_resolution` and `describe_workspace` were both removed at the
 // user's request — the read surface is now just `list_all_tools` and
 // `list_feature_sets`. Behavior previously asserted here is covered by
@@ -448,6 +543,7 @@ async fn registry_advertises_every_default_tool_with_annotations() {
     for expected in [
         "mcpmux_list_all_tools",
         "mcpmux_list_feature_sets",
+        "mcpmux_list_servers",
         "mcpmux_create_feature_set",
         "mcpmux_bind_current_workspace",
     ] {
@@ -525,6 +621,7 @@ async fn bare_registry(
         resolver,
         feature_service,
         SessionRootsRegistry::new(),
+        SessionOverrideRegistry::new(),
         Arc::new(ApprovalBroker::new()),
         tx.clone(),
         settings_repo,
@@ -638,6 +735,7 @@ async fn master_switch_toggles_registry_visibility() {
         resolver,
         feature_service,
         SessionRootsRegistry::new(),
+        SessionOverrideRegistry::new(),
         Arc::new(ApprovalBroker::new()),
         tx,
         Some(settings_repo.clone()),

From 0905d381e1982d0bd0c1bb97dc9514479fa33dab Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 18 May 2026 23:08:55 -0600
Subject: [PATCH 06/48] feat(meta-tools): add session-scope enable/disable
 server tools (Phase 3)

mcpmux_enable_server and mcpmux_disable_server mutate SessionOverrideRegistry,
audit as session_override when auto-allowed, and notify the calling session.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 .../src/consumers/mcp_notifier.rs             | 133 +++++++---
 crates/mcpmux-gateway/src/mcp/handler.rs      |  14 +-
 .../src/services/meta_tools/mod.rs            |  12 +-
 .../src/services/meta_tools/registry.rs       |  21 +-
 .../src/services/meta_tools/tools.rs          | 242 +++++++++++++++++-
 .../planning/dynamic-mcp-toggle-meta-tools.md |  23 +-
 tests/rust/tests/integration/meta_tools.rs    | 102 +++++++-
 7 files changed, 486 insertions(+), 61 deletions(-)

diff --git a/crates/mcpmux-gateway/src/consumers/mcp_notifier.rs b/crates/mcpmux-gateway/src/consumers/mcp_notifier.rs
index 5820296c..0dfc7926 100644
--- a/crates/mcpmux-gateway/src/consumers/mcp_notifier.rs
+++ b/crates/mcpmux-gateway/src/consumers/mcp_notifier.rs
@@ -1064,45 +1064,100 @@ impl MCPNotifier {
         );
 
         for (session_id, peer) in &live {
-            match peer.notify_tool_list_changed().await {
-                Ok(_) => debug!(
-                    %session_id,
-                    %client_id,
-                    "[MCPNotifier] ✅ Sent tools/list_changed to session (per-client)"
-                ),
-                Err(e) => warn!(
-                    %session_id,
-                    %client_id,
-                    error = ?e,
-                    "[MCPNotifier] failed tools/list_changed"
-                ),
-            }
-            match peer.notify_prompt_list_changed().await {
-                Ok(_) => debug!(
-                    %session_id,
-                    %client_id,
-                    "[MCPNotifier] ✅ Sent prompts/list_changed to session (per-client)"
-                ),
-                Err(e) => warn!(
-                    %session_id,
-                    %client_id,
-                    error = ?e,
-                    "[MCPNotifier] failed prompts/list_changed"
-                ),
-            }
-            match peer.notify_resource_list_changed().await {
-                Ok(_) => debug!(
-                    %session_id,
-                    %client_id,
-                    "[MCPNotifier] ✅ Sent resources/list_changed to session (per-client)"
-                ),
-                Err(e) => warn!(
-                    %session_id,
-                    %client_id,
-                    error = ?e,
-                    "[MCPNotifier] failed resources/list_changed"
-                ),
-            }
+            self.send_all_lists_changed_to_peer(session_id, client_id, peer)
+                .await;
+        }
+    }
+
+    /// Send all three list_changed notifications to one session, bypassing
+    /// space-level hash dedup. Used after session-scoped override mutations
+    /// so only the calling session refreshes its tool list.
+    pub async fn notify_session_lists_changed(&self, session_id: &str) {
+        if DISABLE_ALL_NOTIFICATIONS {
+            trace!(
+                %session_id,
+                "[MCPNotifier] 🚫 disabled — skipping session list_changed"
+            );
+            return;
+        }
+
+        let snapshot: Option<(String, Arc<Peer<RoleServer>>)> = {
+            let sessions = self.sessions.read();
+            sessions.get(session_id).and_then(|entry| {
+                if entry.has_active_stream {
+                    Some((entry.client_id.clone(), entry.peer.clone()))
+                } else {
+                    None
+                }
+            })
+        };
+
+        let Some((client_id, peer)) = snapshot else {
+            debug!(
+                %session_id,
+                "[MCPNotifier] no active stream — skipping session list_changed"
+            );
+            return;
+        };
+
+        if self.reap_dead_sessions(&[(session_id.to_string(), peer.clone())]).contains(&session_id.to_string()) {
+            return;
+        }
+
+        info!(
+            %session_id,
+            %client_id,
+            "[MCPNotifier] 📤 session list_changed (override mutated)"
+        );
+        self.send_all_lists_changed_to_peer(session_id, &client_id, &peer)
+            .await;
+    }
+
+    /// Push tools/prompts/resources list_changed to a single peer.
+    async fn send_all_lists_changed_to_peer(
+        &self,
+        session_id: &str,
+        client_id: &str,
+        peer: &Peer<RoleServer>,
+    ) {
+        match peer.notify_tool_list_changed().await {
+            Ok(_) => debug!(
+                %session_id,
+                %client_id,
+                "[MCPNotifier] ✅ Sent tools/list_changed to session"
+            ),
+            Err(e) => warn!(
+                %session_id,
+                %client_id,
+                error = ?e,
+                "[MCPNotifier] failed tools/list_changed"
+            ),
+        }
+        match peer.notify_prompt_list_changed().await {
+            Ok(_) => debug!(
+                %session_id,
+                %client_id,
+                "[MCPNotifier] ✅ Sent prompts/list_changed to session"
+            ),
+            Err(e) => warn!(
+                %session_id,
+                %client_id,
+                error = ?e,
+                "[MCPNotifier] failed prompts/list_changed"
+            ),
+        }
+        match peer.notify_resource_list_changed().await {
+            Ok(_) => debug!(
+                %session_id,
+                %client_id,
+                "[MCPNotifier] ✅ Sent resources/list_changed to session"
+            ),
+            Err(e) => warn!(
+                %session_id,
+                %client_id,
+                error = ?e,
+                "[MCPNotifier] failed resources/list_changed"
+            ),
         }
     }
 }
diff --git a/crates/mcpmux-gateway/src/mcp/handler.rs b/crates/mcpmux-gateway/src/mcp/handler.rs
index 3095c656..e94d4ca0 100644
--- a/crates/mcpmux-gateway/src/mcp/handler.rs
+++ b/crates/mcpmux-gateway/src/mcp/handler.rs
@@ -752,7 +752,19 @@ impl ServerHandler for McpMuxGatewayHandler {
                 .call(&params.name, &oauth_ctx.client_id, session_id, args)
                 .await
             {
-                Ok(result) => Ok(result),
+                Ok(result) => {
+                    if matches!(
+                        params.name.as_ref(),
+                        "mcpmux_enable_server" | "mcpmux_disable_server"
+                    ) {
+                        if let Some(sid) = session_id {
+                            self.notification_bridge
+                                .notify_session_lists_changed(sid)
+                                .await;
+                        }
+                    }
+                    Ok(result)
+                }
                 Err(e) => Ok(e.into_call_tool_result()),
             };
         }
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/mod.rs b/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
index 4b4e75d7..ebb23656 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
@@ -30,7 +30,10 @@ pub use approval::{
     ApprovalScope,
 };
 pub use diff::ToolDiff;
-pub use registry::{MetaToolContext, MetaToolError, MetaToolRegistry, META_TOOLS_ENABLED_KEY};
+pub use registry::{
+    MetaToolContext, MetaToolError, MetaToolRegistry, META_TOOLS_ENABLED_KEY,
+    SESSION_OVERRIDES_REQUIRE_APPROVAL_KEY,
+};
 
 /// Every built-in tool's name must start with this prefix so the handler
 /// can intercept it before routing to backend servers.
@@ -80,10 +83,9 @@ pub fn build_default_registry(
     registry.register(Box::new(tools::ListAllToolsTool));
     registry.register(Box::new(tools::ListFeatureSetsTool));
     registry.register(Box::new(tools::ListServersTool));
-    // Both `describe_resolution` and `describe_workspace` were removed by
-    // user request — the read surface is just the two list_* tools above,
-    // which an LLM can stitch into the same picture without an extra hop.
-    // Writes — gated by ApprovalBroker.
+    // Writes — gated by ApprovalBroker (or auto-allowed for session overrides).
+    registry.register(Box::new(tools::EnableServerTool));
+    registry.register(Box::new(tools::DisableServerTool));
     registry.register(Box::new(tools::CreateFeatureSetTool));
     registry.register(Box::new(tools::BindCurrentWorkspaceTool));
     std::sync::Arc::new(registry)
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/registry.rs b/crates/mcpmux-gateway/src/services/meta_tools/registry.rs
index c1e3836d..4e1a82e0 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/registry.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/registry.rs
@@ -5,7 +5,7 @@
 //! `tools/list` response.
 
 use std::collections::HashMap;
-use std::sync::Arc;
+use std::sync::{Arc, Mutex};
 
 use async_trait::async_trait;
 use mcpmux_core::{
@@ -27,6 +27,11 @@ use crate::services::{
 /// Present + "false" → hidden; missing or anything else → enabled.
 pub const META_TOOLS_ENABLED_KEY: &str = "gateway.meta_tools_enabled";
 
+/// When `"true"`, session-scope enable/disable routes through the approval
+/// broker. Default (missing / unparseable): auto-allow.
+pub const SESSION_OVERRIDES_REQUIRE_APPROVAL_KEY: &str =
+    "gateway.session_overrides_require_approval";
+
 /// Context injected into every meta-tool invocation.
 ///
 /// Cheap to clone (all `Arc`s); the registry holds one and hands references
@@ -63,6 +68,9 @@ pub struct MetaToolCall<'a> {
     /// JSON arguments supplied in `CallToolRequestParams.arguments`.
     pub args: Value,
     pub ctx: &'a MetaToolContext,
+    /// Write tools set this before returning `Ok` to override the default
+    /// `"allow_once"` audit decision (e.g. `"session_override"`).
+    pub audit_decision: Arc<Mutex<Option<&'static str>>>,
 }
 
 /// Errors a meta tool can surface that map cleanly to `CallToolResult::error`.
@@ -223,16 +231,25 @@ impl MetaToolRegistry {
             .get(name)
             .ok_or_else(|| MetaToolError::InvalidArgument(format!("unknown meta tool: {name}")))?;
         let is_write = tool.is_write();
+        let audit_decision = Arc::new(Mutex::new(None));
         let call = MetaToolCall {
             client_id,
             session_id,
             args: args.clone(),
             ctx: &self.ctx,
+            audit_decision: audit_decision.clone(),
         };
         let result = tool.call(call).await;
 
         let (decision, summary) = match &result {
-            Ok(_) if is_write => ("allow_once", format!("{name} succeeded")),
+            Ok(_) if is_write => (
+                audit_decision
+                    .lock()
+                    .ok()
+                    .and_then(|g| *g)
+                    .unwrap_or("allow_once"),
+                format!("{name} succeeded"),
+            ),
             Ok(_) => ("read", format!("{name} read")),
             Err(MetaToolError::ApprovalDenied) => ("deny", format!("{name} denied by user")),
             Err(MetaToolError::ApprovalTimedOut) => ("timeout", format!("{name} timed out")),
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
index 71cac23f..d0508657 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
@@ -15,7 +15,9 @@ use tracing::info;
 use uuid::Uuid;
 
 use super::approval::{ApprovalPayload, ApprovalScope};
-use super::registry::{MetaTool, MetaToolCall, MetaToolError};
+use super::registry::{
+    MetaTool, MetaToolCall, MetaToolError, SESSION_OVERRIDES_REQUIRE_APPROVAL_KEY,
+};
 use crate::services::ResolvedFeatureSet;
 
 /// Fire a `FeatureSetMembersChanged` event so MCPNotifier pushes a
@@ -335,6 +337,244 @@ fn parse_uuid_arg(args: &Value, field: &str) -> Result<Uuid, MetaToolError> {
         .map_err(|_| MetaToolError::InvalidArgument(format!("`{field}` is not a UUID: {s}")))
 }
 
+fn parse_string_arg(args: &Value, field: &str) -> Result<String, MetaToolError> {
+    args.get(field)
+        .and_then(|v| v.as_str())
+        .map(|s| s.to_string())
+        .ok_or_else(|| MetaToolError::InvalidArgument(format!("missing `{field}`")))
+}
+
+/// Parse `scope` — only `"session"` is implemented in Phase 3.
+fn parse_scope(args: &Value) -> Result<&'static str, MetaToolError> {
+    match args.get("scope").and_then(|v| v.as_str()) {
+        None | Some("session") => Ok("session"),
+        Some("workspace") => Err(MetaToolError::InvalidArgument(
+            "workspace scope not yet implemented; see Phase 4".into(),
+        )),
+        Some(other) => Err(MetaToolError::InvalidArgument(format!(
+            "invalid scope '{other}'; expected 'session' or 'workspace'"
+        ))),
+    }
+}
+
+/// Whether session-scope server overrides require desktop approval.
+async fn session_overrides_require_approval(ctx: &super::registry::MetaToolContext) -> bool {
+    let Some(repo) = ctx.settings_repo.as_ref() else {
+        return false;
+    };
+    match repo.get(SESSION_OVERRIDES_REQUIRE_APPROVAL_KEY).await {
+        Ok(Some(v)) => matches!(v.as_str(), "true" | "1"),
+        _ => false,
+    }
+}
+
+/// Ensure `server_id` has at least one feature row in the caller's Space.
+async fn validate_server_in_space(
+    call: &MetaToolCall<'_>,
+    space_id: Uuid,
+    server_id: &str,
+) -> Result<(), MetaToolError> {
+    let features = call
+        .ctx
+        .server_feature_repo
+        .list_for_space(&space_id.to_string())
+        .await?;
+    if features.iter().any(|f| f.server_id == server_id) {
+        return Ok(());
+    }
+    Err(MetaToolError::InvalidArgument(format!(
+        "unknown server_id '{server_id}' in this Space"
+    )))
+}
+
+fn require_session_id(call: &MetaToolCall<'_>) -> Result<String, MetaToolError> {
+    call.session_id
+        .map(|s| s.to_string())
+        .ok_or_else(|| {
+            MetaToolError::InvalidArgument("session scope requires an MCP session id".into())
+        })
+}
+
+// ---------------------------------------------------------------------------
+// mcpmux_enable_server / mcpmux_disable_server — write (session scope)
+// ---------------------------------------------------------------------------
+
+pub struct EnableServerTool;
+
+#[async_trait]
+impl MetaTool for EnableServerTool {
+    fn name(&self) -> &'static str {
+        "mcpmux_enable_server"
+    }
+
+    fn description(&self) -> &'static str {
+        "Enable an MCP server for the current session only. The server's tools \
+         appear on the next tools/list without changing workspace bindings. \
+         Use mcpmux_list_servers first to see current status."
+    }
+
+    fn input_schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "required": ["server_id"],
+            "properties": {
+                "server_id": { "type": "string" },
+                "scope": {
+                    "type": "string",
+                    "enum": ["session", "workspace"],
+                    "default": "session"
+                }
+            }
+        })
+    }
+
+    fn is_write(&self) -> bool {
+        true
+    }
+
+    async fn call(&self, call: MetaToolCall<'_>) -> Result<CallToolResult, MetaToolError> {
+        parse_scope(&call.args)?;
+        let server_id = parse_string_arg(&call.args, "server_id")?;
+        let space_id = caller_space_id(&call).await?;
+        validate_server_in_space(&call, space_id, &server_id).await?;
+        let session_id = require_session_id(&call)?;
+
+        if session_overrides_require_approval(call.ctx).await {
+            let overrides = call.ctx.session_overrides.clone();
+            let server_id_for_closure = server_id.clone();
+            let session_id_owned = session_id.to_string();
+            let summary = format!("Enable server '{server_id}' for this session");
+            return with_approval(
+                &call,
+                "mcpmux_enable_server",
+                summary,
+                None,
+                false,
+                call.args.clone(),
+                || async move {
+                    overrides.enable(&session_id_owned, &server_id_for_closure);
+                    info!(
+                        session_id = %session_id_owned,
+                        server_id = %server_id_for_closure,
+                        "[meta_tools] enable_server applied (approved)"
+                    );
+                    Ok(text_result(json!({
+                        "ok": true,
+                        "server_id": server_id_for_closure,
+                        "scope": "session",
+                    })))
+                },
+            )
+            .await;
+        }
+
+        call.ctx
+            .session_overrides
+            .enable(&session_id, &server_id);
+        if let Ok(mut decision) = call.audit_decision.lock() {
+            *decision = Some("session_override");
+        }
+        info!(
+            %session_id,
+            server_id = %server_id,
+            "[meta_tools] enable_server applied"
+        );
+        Ok(text_result(json!({
+            "ok": true,
+            "server_id": server_id,
+            "scope": "session",
+        })))
+    }
+}
+
+pub struct DisableServerTool;
+
+#[async_trait]
+impl MetaTool for DisableServerTool {
+    fn name(&self) -> &'static str {
+        "mcpmux_disable_server"
+    }
+
+    fn description(&self) -> &'static str {
+        "Disable an MCP server for the current session only. Bound servers \
+         are muted until re-enabled or the session ends. Use \
+         mcpmux_list_servers to inspect status first."
+    }
+
+    fn input_schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "required": ["server_id"],
+            "properties": {
+                "server_id": { "type": "string" },
+                "scope": {
+                    "type": "string",
+                    "enum": ["session", "workspace"],
+                    "default": "session"
+                }
+            }
+        })
+    }
+
+    fn is_write(&self) -> bool {
+        true
+    }
+
+    async fn call(&self, call: MetaToolCall<'_>) -> Result<CallToolResult, MetaToolError> {
+        parse_scope(&call.args)?;
+        let server_id = parse_string_arg(&call.args, "server_id")?;
+        let space_id = caller_space_id(&call).await?;
+        validate_server_in_space(&call, space_id, &server_id).await?;
+        let session_id = require_session_id(&call)?;
+
+        if session_overrides_require_approval(call.ctx).await {
+            let overrides = call.ctx.session_overrides.clone();
+            let server_id_for_closure = server_id.clone();
+            let session_id_owned = session_id.to_string();
+            let summary = format!("Disable server '{server_id}' for this session");
+            return with_approval(
+                &call,
+                "mcpmux_disable_server",
+                summary,
+                None,
+                false,
+                call.args.clone(),
+                || async move {
+                    overrides.disable(&session_id_owned, &server_id_for_closure);
+                    info!(
+                        session_id = %session_id_owned,
+                        server_id = %server_id_for_closure,
+                        "[meta_tools] disable_server applied (approved)"
+                    );
+                    Ok(text_result(json!({
+                        "ok": true,
+                        "server_id": server_id_for_closure,
+                        "scope": "session",
+                    })))
+                },
+            )
+            .await;
+        }
+
+        call.ctx
+            .session_overrides
+            .disable(&session_id, &server_id);
+        if let Ok(mut decision) = call.audit_decision.lock() {
+            *decision = Some("session_override");
+        }
+        info!(
+            %session_id,
+            server_id = %server_id,
+            "[meta_tools] disable_server applied"
+        );
+        Ok(text_result(json!({
+            "ok": true,
+            "server_id": server_id,
+            "scope": "session",
+        })))
+    }
+}
+
 // ---------------------------------------------------------------------------
 // mcpmux_create_feature_set — write (creates FS, optionally activates)
 // ---------------------------------------------------------------------------
diff --git a/docs/planning/dynamic-mcp-toggle-meta-tools.md b/docs/planning/dynamic-mcp-toggle-meta-tools.md
index f3c3db1c..0da7a4da 100644
--- a/docs/planning/dynamic-mcp-toggle-meta-tools.md
+++ b/docs/planning/dynamic-mcp-toggle-meta-tools.md
@@ -1,7 +1,7 @@
 # Dynamic MCP Toggling via Meta Tools
 
 **Last Updated:** May 19, 2026
-**Status:** Phase 2 complete — `mcpmux_list_servers` read tool shipped; Phases 3–5 pending
+**Status:** Phase 3 complete — session-scope enable/disable meta tools; Phases 4–5 pending
 **Branch:** `feat/dynamic-mcp-toggle-meta-tools`
 **Base branch:** `feat/workspace-root-routing` ([upstream PR #151](https://github.com/mcpmux/mcp-mux/pull/151))
 **Issue:** TBD — file after planning review
@@ -200,20 +200,19 @@ Each write fires `tools/list_changed` per-peer via the existing `MCPNotifier::no
 
 **Outcome:** LLM calls `mcpmux_list_servers` and gets a server roster with per-server status. No state mutation.
 
-### Phase 3 — `mcpmux_enable_server` / `mcpmux_disable_server` (session scope)
+### Phase 3 — `mcpmux_enable_server` / `mcpmux_disable_server` (session scope) ✅
 
-**Effort:** 1 day
+**Effort:** 1 day  
+**Completed:** May 19, 2026
 
-- Add `EnableServerTool` + `DisableServerTool` to `meta_tools/tools.rs`.
-- Args: `{ server_id: string, scope?: "session" | "workspace" (default "session") }`.
-- Session-scope flow: validate `server_id` exists in caller's resolved Space → look up `gateway.session_overrides_require_approval` setting → if `false`, mutate registry directly; if `true`, route through `with_approval` first.
-- Enable adds to `enabled` and removes from `disabled` (the two sets are mutually exclusive per server-id, last-write-wins).
-- Disable mirror: adds to `disabled`, removes from `enabled`.
-- After mutation: fire per-peer `tools/list_changed` via `notify_peer_lists_changed(client_id)`. Emit `MetaToolInvoked` with `decision: "session_override"` when auto-allowed, `"allow_once"` when approval was required.
-- Reject `scope: "workspace"` with `MetaToolError::InvalidArgument("workspace scope not yet implemented; see Phase 4")` until Phase 4 lands.
-- Integration tests: enable → tool appears in next `tools/list`, disable → tool disappears, both with the per-peer notify firing.
+- [x] `EnableServerTool` + `DisableServerTool` in `meta_tools/tools.rs` with `{ server_id, scope? }` args
+- [x] Session flow: validate server in Space → optional approval via `gateway.session_overrides_require_approval` → mutate `SessionOverrideRegistry`
+- [x] Workspace scope rejected until Phase 4
+- [x] Auto-allowed writes audit as `session_override`; approval-gated writes audit as `allow_once`
+- [x] Handler fires `MCPNotifier::notify_session_lists_changed` after successful enable/disable
+- [x] Integration tests: enable adds tools, disable removes tools, workspace rejected, audit decision
 
-**Outcome:** From a fresh Cursor window (no binding, no overrides), an LLM calls `mcpmux_enable_server({"server_id": "github"})`. The GitHub tools appear in the next `tools/list`. The LLM uses them, then calls `mcpmux_disable_server({"server_id": "github"})` when done. Tools disappear. No DB writes; closing Cursor and reopening it = clean slate.
+**Outcome:** LLM can toggle servers mid-session; tools appear/disappear on next `tools/list`. No DB writes.
 
 ### Phase 4 — Workspace-scope variants
 
diff --git a/tests/rust/tests/integration/meta_tools.rs b/tests/rust/tests/integration/meta_tools.rs
index d3df9c3f..fce2ae27 100644
--- a/tests/rust/tests/integration/meta_tools.rs
+++ b/tests/rust/tests/integration/meta_tools.rs
@@ -47,6 +47,7 @@ struct Fixture {
     session_id: String,
     fs_android_id: Uuid,
     github_tool_id: Uuid,
+    event_rx: broadcast::Receiver<DomainEvent>,
 }
 
 impl Fixture {
@@ -118,7 +119,7 @@ impl Fixture {
         ));
 
         let broker = Arc::new(ApprovalBroker::new().with_timeout(Duration::from_millis(500)));
-        let (tx, _rx) = broadcast::channel::<DomainEvent>(32);
+        let (tx, event_rx) = broadcast::channel::<DomainEvent>(32);
 
         let registry = meta_tools::build_default_registry(
             client_repo.clone(),
@@ -149,6 +150,7 @@ impl Fixture {
             session_id,
             fs_android_id,
             github_tool_id,
+            event_rx,
         }
     }
 
@@ -355,6 +357,102 @@ async fn list_servers_shows_session_override_statuses() {
     assert_eq!(server_status(&body, "firebase"), "enabled_via_session");
 }
 
+#[tokio::test(flavor = "multi_thread")]
+async fn enable_server_adds_tools_on_next_list() {
+    let f = Fixture::new().await;
+    let result = f
+        .registry
+        .call(
+            "mcpmux_enable_server",
+            &f.client_id,
+            Some(&f.session_id),
+            json!({ "server_id": "github" }),
+        )
+        .await
+        .unwrap();
+    assert!(!Fixture::is_error(&result));
+
+    let tools = f
+        .feature_service
+        .get_tools_for_grants(&f.space_id.to_string(), &[], Some(&f.session_id))
+        .await
+        .unwrap();
+    assert_eq!(tools.len(), 1);
+    assert_eq!(tools[0].server_id, "github");
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn disable_server_removes_tools_from_list() {
+    let f = Fixture::new().await;
+    f.session_overrides.enable(&f.session_id, "github");
+
+    f.registry
+        .call(
+            "mcpmux_disable_server",
+            &f.client_id,
+            Some(&f.session_id),
+            json!({ "server_id": "github" }),
+        )
+        .await
+        .unwrap();
+
+    let tools = f
+        .feature_service
+        .get_tools_for_grants(&f.space_id.to_string(), &[], Some(&f.session_id))
+        .await
+        .unwrap();
+    assert!(tools.is_empty());
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn enable_server_rejects_workspace_scope() {
+    let f = Fixture::new().await;
+    let result = f
+        .call_tool_as_handler_would(
+            "mcpmux_enable_server",
+            json!({ "server_id": "github", "scope": "workspace" }),
+        )
+        .await;
+    assert!(Fixture::is_error(&result));
+    let body = Fixture::result_json(&result);
+    assert!(
+        body.get("message")
+            .and_then(|m| m.as_str())
+            .unwrap_or("")
+            .contains("Phase 4")
+    );
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn enable_server_emits_session_override_audit_decision() {
+    let mut f = Fixture::new().await;
+    f.registry
+        .call(
+            "mcpmux_enable_server",
+            &f.client_id,
+            Some(&f.session_id),
+            json!({ "server_id": "github" }),
+        )
+        .await
+        .unwrap();
+
+    let evt = tokio::time::timeout(Duration::from_millis(200), f.event_rx.recv())
+        .await
+        .expect("receive within 200ms")
+        .expect("event");
+    match evt {
+        DomainEvent::MetaToolInvoked {
+            tool_name,
+            decision,
+            ..
+        } => {
+            assert_eq!(tool_name, "mcpmux_enable_server");
+            assert_eq!(decision, "session_override");
+        }
+        other => panic!("unexpected event: {other:?}"),
+    }
+}
+
 // `describe_resolution` and `describe_workspace` were both removed at the
 // user's request — the read surface is now just `list_all_tools` and
 // `list_feature_sets`. Behavior previously asserted here is covered by
@@ -544,6 +642,8 @@ async fn registry_advertises_every_default_tool_with_annotations() {
         "mcpmux_list_all_tools",
         "mcpmux_list_feature_sets",
         "mcpmux_list_servers",
+        "mcpmux_enable_server",
+        "mcpmux_disable_server",
         "mcpmux_create_feature_set",
         "mcpmux_bind_current_workspace",
     ] {

From b29d5e8bbc3288952792c876cd5c141c1b5130a7 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 18 May 2026 23:11:47 -0600
Subject: [PATCH 07/48] feat(meta-tools): add workspace-scope enable/disable
 server tools (Phase 4)

Persist server-all FeatureSets on workspace bindings with approval;
session list_changed only fires for session scope.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 crates/mcpmux-gateway/src/mcp/handler.rs      |   8 +-
 .../src/services/meta_tools/mod.rs            |   1 +
 .../src/services/meta_tools/tools.rs          |  43 ++-
 .../services/meta_tools/workspace_server.rs   | 279 ++++++++++++++++++
 .../planning/dynamic-mcp-toggle-meta-tools.md |  20 +-
 tests/rust/tests/integration/meta_tools.rs    | 106 ++++++-
 6 files changed, 423 insertions(+), 34 deletions(-)
 create mode 100644 crates/mcpmux-gateway/src/services/meta_tools/workspace_server.rs

diff --git a/crates/mcpmux-gateway/src/mcp/handler.rs b/crates/mcpmux-gateway/src/mcp/handler.rs
index e94d4ca0..b5242ef5 100644
--- a/crates/mcpmux-gateway/src/mcp/handler.rs
+++ b/crates/mcpmux-gateway/src/mcp/handler.rs
@@ -746,6 +746,11 @@ impl ServerHandler for McpMuxGatewayHandler {
                 .arguments
                 .map(|a| serde_json::to_value(a).unwrap_or(serde_json::Value::Null))
                 .unwrap_or(serde_json::Value::Null);
+            let scope = args
+                .get("scope")
+                .and_then(|v| v.as_str())
+                .unwrap_or("session")
+                .to_string();
             return match self
                 .services
                 .meta_tool_registry
@@ -756,7 +761,8 @@ impl ServerHandler for McpMuxGatewayHandler {
                     if matches!(
                         params.name.as_ref(),
                         "mcpmux_enable_server" | "mcpmux_disable_server"
-                    ) {
+                    ) && scope == "session"
+                    {
                         if let Some(sid) = session_id {
                             self.notification_bridge
                                 .notify_session_lists_changed(sid)
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/mod.rs b/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
index ebb23656..e4fc7908 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
@@ -24,6 +24,7 @@ pub mod approval;
 pub mod diff;
 mod registry;
 mod tools;
+mod workspace_server;
 
 pub use approval::{
     ApprovalBroker, ApprovalDecision, ApprovalPayload, ApprovalPublisher, ApprovalRequest,
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
index d0508657..f16824d6 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
@@ -39,7 +39,7 @@ fn emit_tools_list_changed(event_tx: &broadcast::Sender<DomainEvent>, space_id:
 // Helpers
 // ---------------------------------------------------------------------------
 
-fn text_result(v: Value) -> CallToolResult {
+pub(crate) fn text_result(v: Value) -> CallToolResult {
     CallToolResult::success(vec![Content::text(v.to_string())])
 }
 
@@ -301,7 +301,7 @@ impl MetaTool for ListServersTool {
 /// mutation. Returns the broker's decision so the caller can proceed only
 /// on success. `mutate` is the thing that runs post-approval and is
 /// expected to emit `tools/list_changed` when relevant.
-async fn with_approval<F, Fut, T>(
+pub(crate) async fn with_approval<F, Fut, T>(
     call: &MetaToolCall<'_>,
     tool_name: &'static str,
     summary: String,
@@ -344,13 +344,11 @@ fn parse_string_arg(args: &Value, field: &str) -> Result<String, MetaToolError>
         .ok_or_else(|| MetaToolError::InvalidArgument(format!("missing `{field}`")))
 }
 
-/// Parse `scope` — only `"session"` is implemented in Phase 3.
+/// Parse `scope` for enable/disable server tools.
 fn parse_scope(args: &Value) -> Result<&'static str, MetaToolError> {
     match args.get("scope").and_then(|v| v.as_str()) {
         None | Some("session") => Ok("session"),
-        Some("workspace") => Err(MetaToolError::InvalidArgument(
-            "workspace scope not yet implemented; see Phase 4".into(),
-        )),
+        Some("workspace") => Ok("workspace"),
         Some(other) => Err(MetaToolError::InvalidArgument(format!(
             "invalid scope '{other}'; expected 'session' or 'workspace'"
         ))),
@@ -408,9 +406,9 @@ impl MetaTool for EnableServerTool {
     }
 
     fn description(&self) -> &'static str {
-        "Enable an MCP server for the current session only. The server's tools \
-         appear on the next tools/list without changing workspace bindings. \
-         Use mcpmux_list_servers first to see current status."
+        "Enable an MCP server. Default scope is session (ephemeral). Use \
+         scope: \"workspace\" to persist on the matched workspace binding \
+         (requires approval). Use mcpmux_list_servers first."
     }
 
     fn input_schema(&self) -> Value {
@@ -433,16 +431,22 @@ impl MetaTool for EnableServerTool {
     }
 
     async fn call(&self, call: MetaToolCall<'_>) -> Result<CallToolResult, MetaToolError> {
-        parse_scope(&call.args)?;
+        let scope = parse_scope(&call.args)?;
         let server_id = parse_string_arg(&call.args, "server_id")?;
         let space_id = caller_space_id(&call).await?;
         validate_server_in_space(&call, space_id, &server_id).await?;
+
+        if scope == "workspace" {
+            return super::workspace_server::enable_workspace_server(call, space_id, server_id)
+                .await;
+        }
+
         let session_id = require_session_id(&call)?;
 
         if session_overrides_require_approval(call.ctx).await {
             let overrides = call.ctx.session_overrides.clone();
             let server_id_for_closure = server_id.clone();
-            let session_id_owned = session_id.to_string();
+            let session_id_owned = session_id.clone();
             let summary = format!("Enable server '{server_id}' for this session");
             return with_approval(
                 &call,
@@ -496,9 +500,10 @@ impl MetaTool for DisableServerTool {
     }
 
     fn description(&self) -> &'static str {
-        "Disable an MCP server for the current session only. Bound servers \
-         are muted until re-enabled or the session ends. Use \
-         mcpmux_list_servers to inspect status first."
+        "Disable an MCP server. Default scope is session (ephemeral). Use \
+         scope: \"workspace\" to remove the server-all layer from the \
+         workspace binding (requires approval; custom FeatureSets must be \
+         edited in the Workspaces UI)."
     }
 
     fn input_schema(&self) -> Value {
@@ -521,16 +526,22 @@ impl MetaTool for DisableServerTool {
     }
 
     async fn call(&self, call: MetaToolCall<'_>) -> Result<CallToolResult, MetaToolError> {
-        parse_scope(&call.args)?;
+        let scope = parse_scope(&call.args)?;
         let server_id = parse_string_arg(&call.args, "server_id")?;
         let space_id = caller_space_id(&call).await?;
         validate_server_in_space(&call, space_id, &server_id).await?;
+
+        if scope == "workspace" {
+            return super::workspace_server::disable_workspace_server(call, space_id, server_id)
+                .await;
+        }
+
         let session_id = require_session_id(&call)?;
 
         if session_overrides_require_approval(call.ctx).await {
             let overrides = call.ctx.session_overrides.clone();
             let server_id_for_closure = server_id.clone();
-            let session_id_owned = session_id.to_string();
+            let session_id_owned = session_id.clone();
             let summary = format!("Disable server '{server_id}' for this session");
             return with_approval(
                 &call,
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/workspace_server.rs b/crates/mcpmux-gateway/src/services/meta_tools/workspace_server.rs
new file mode 100644
index 00000000..9496d6c2
--- /dev/null
+++ b/crates/mcpmux-gateway/src/services/meta_tools/workspace_server.rs
@@ -0,0 +1,279 @@
+//! Workspace-scope enable/disable for MCP servers via binding FeatureSets.
+//!
+//! Persists a per-server "all tools" FeatureSet (tagged with
+//! [`FeatureSet::server_id`]) and appends it to the matched
+//! [`WorkspaceBinding`]'s `feature_set_ids`.
+
+use mcpmux_core::{DomainEvent, FeatureSet, MemberMode, MemberType, WorkspaceBinding};
+use rmcp::model::CallToolResult;
+use serde_json::json;
+use tokio::sync::broadcast;
+use tracing::info;
+use uuid::Uuid;
+
+use super::registry::{MetaToolCall, MetaToolError};
+use super::tools::{text_result, with_approval};
+
+/// Whether a FeatureSet is the workspace-scoped "all tools for server" row.
+fn is_server_all_feature_set(fs: &FeatureSet, server_id: &str) -> bool {
+    !fs.is_deleted && fs.server_id.as_deref() == Some(server_id)
+}
+
+/// Resolve the workspace binding for the caller's first reported root.
+async fn resolve_workspace_binding(
+    call: &MetaToolCall<'_>,
+    space_id: Uuid,
+) -> Result<(WorkspaceBinding, String), MetaToolError> {
+    let session_id = call
+        .session_id
+        .ok_or_else(|| MetaToolError::InvalidArgument("workspace scope requires an MCP session id".into()))?;
+    let roots = call
+        .ctx
+        .session_roots
+        .get(session_id)
+        .unwrap_or_default();
+    let root = roots.into_iter().next().ok_or_else(|| {
+        MetaToolError::InvalidArgument(
+            "caller did not report any MCP roots; cannot resolve workspace".into(),
+        )
+    })?;
+    let normalized = mcpmux_core::normalize_workspace_root(&root);
+
+    let binding = call
+        .ctx
+        .binding_repo
+        .find_longest_prefix_match(&space_id, std::slice::from_ref(&normalized))
+        .await?
+        .ok_or_else(|| {
+            MetaToolError::InvalidArgument(
+                "no binding exists for this workspace; create one with \
+                 mcpmux_create_feature_set + mcpmux_bind_current_workspace first"
+                    .into(),
+            )
+        })?;
+    Ok((binding, normalized))
+}
+
+fn emit_workspace_binding_changed(
+    event_tx: &broadcast::Sender<DomainEvent>,
+    space_id: Uuid,
+    workspace_root: &str,
+) {
+    let _ = event_tx.send(DomainEvent::WorkspaceBindingChanged {
+        space_id,
+        workspace_root: workspace_root.to_string(),
+    });
+}
+
+/// Enable `server_id` persistently on the caller's workspace binding.
+pub async fn enable_workspace_server(
+    call: MetaToolCall<'_>,
+    space_id: Uuid,
+    server_id: String,
+) -> Result<CallToolResult, MetaToolError> {
+    let (binding, workspace_root) = resolve_workspace_binding(&call, space_id).await?;
+    let summary = format!(
+        "Enable server '{server_id}' for workspace '{workspace_root}' (persists across sessions)"
+    );
+
+    let fs_repo = call.ctx.feature_set_repo.clone();
+    let binding_repo = call.ctx.binding_repo.clone();
+    let server_feature_repo = call.ctx.server_feature_repo.clone();
+    let event_tx = call.ctx.domain_event_tx.clone();
+    let args = call.args.clone();
+
+    let mut binding_for_closure = binding.clone();
+    let workspace_root_for_closure = workspace_root.clone();
+
+    with_approval(
+        &call,
+        "mcpmux_enable_server",
+        summary,
+        None,
+        true,
+        args,
+        || async move {
+            let existing = {
+                let sets = fs_repo.list_by_space(&space_id.to_string()).await?;
+                Ok::<_, MetaToolError>(
+                    sets.into_iter()
+                        .find(|fs| is_server_all_feature_set(fs, &server_id)),
+                )
+            }?;
+
+            let fs_id = if let Some(fs) = existing {
+                fs.id
+            } else {
+                let mut fs =
+                    FeatureSet::new_custom(format!("{server_id} — All"), space_id.to_string());
+                fs.server_id = Some(server_id.clone());
+                fs.description = Some(format!("All tools from {server_id} (workspace scope)"));
+
+                let features = server_feature_repo
+                    .list_for_space(&space_id.to_string())
+                    .await?
+                    .into_iter()
+                    .filter(|f| f.server_id == server_id)
+                    .collect::<Vec<_>>();
+
+                fs_repo.create(&fs).await?;
+                for feature in &features {
+                    fs_repo
+                        .add_feature_member(&fs.id, &feature.id.to_string(), MemberMode::Include)
+                        .await?;
+                }
+                fs.id
+            };
+
+            if binding_for_closure
+                .feature_set_ids
+                .iter()
+                .any(|id| id == &fs_id)
+            {
+                info!(
+                    binding_id = %binding_for_closure.id,
+                    server_id = %server_id,
+                    "[meta_tools] enable_server workspace already bound"
+                );
+                return Ok(text_result(json!({
+                    "ok": true,
+                    "server_id": server_id,
+                    "scope": "workspace",
+                    "feature_set_id": fs_id,
+                    "binding_id": binding_for_closure.id,
+                })));
+            }
+
+            binding_for_closure.feature_set_ids.push(fs_id.clone());
+            binding_for_closure.updated_at = chrono::Utc::now();
+            binding_repo.update(&binding_for_closure).await?;
+            emit_workspace_binding_changed(&event_tx, space_id, &workspace_root_for_closure);
+            info!(
+                binding_id = %binding_for_closure.id,
+                feature_set_id = %fs_id,
+                server_id = %server_id,
+                "[meta_tools] enable_server workspace applied"
+            );
+            Ok(text_result(json!({
+                "ok": true,
+                "server_id": server_id,
+                "scope": "workspace",
+                "feature_set_id": fs_id,
+                "binding_id": binding_for_closure.id,
+            })))
+        },
+    )
+    .await
+}
+
+/// Returns true when `server_id` tools are exposed via a non-server-all FS on the binding.
+async fn binding_exposes_server_via_custom_fs(
+    call: &MetaToolCall<'_>,
+    binding: &WorkspaceBinding,
+    space_id: &str,
+    server_id: &str,
+) -> Result<bool, MetaToolError> {
+    for fs_id in &binding.feature_set_ids {
+        let Some(fs) = call.ctx.feature_set_repo.get(fs_id).await? else {
+            continue;
+        };
+        if is_server_all_feature_set(&fs, server_id) {
+            continue;
+        }
+        let members = call.ctx.feature_set_repo.get_feature_members(fs_id).await?;
+        for member in members {
+            if member.member_type != MemberType::Feature {
+                continue;
+            }
+            let Ok(feature_id) = Uuid::parse_str(&member.member_id) else {
+                continue;
+            };
+            if let Some(feature) = call.ctx.server_feature_repo.get(&feature_id).await? {
+                if feature.space_id == space_id && feature.server_id == server_id {
+                    return Ok(true);
+                }
+            }
+        }
+    }
+    Ok(false)
+}
+
+/// Disable `server_id` on the caller's workspace binding (server-all FS only).
+pub async fn disable_workspace_server(
+    call: MetaToolCall<'_>,
+    space_id: Uuid,
+    server_id: String,
+) -> Result<CallToolResult, MetaToolError> {
+    let (binding, workspace_root) = resolve_workspace_binding(&call, space_id).await?;
+
+    if binding_exposes_server_via_custom_fs(&call, &binding, &space_id.to_string(), &server_id)
+        .await?
+    {
+        return Err(MetaToolError::InvalidArgument(format!(
+            "server '{server_id}' is enabled via a custom FeatureSet on this binding; \
+             edit or remove it in the Workspaces UI instead"
+        )));
+    }
+
+    let server_all_id = {
+        let mut found: Option<String> = None;
+        for fs_id in &binding.feature_set_ids {
+            if let Some(fs) = call.ctx.feature_set_repo.get(fs_id).await? {
+                if is_server_all_feature_set(&fs, &server_id) {
+                    found = Some(fs_id.clone());
+                    break;
+                }
+            }
+        }
+        found
+    };
+
+    let Some(server_all_id) = server_all_id else {
+        return Ok(text_result(json!({
+            "ok": true,
+            "server_id": server_id,
+            "scope": "workspace",
+            "removed": false,
+        })));
+    };
+
+    let summary = format!(
+        "Disable server '{server_id}' for workspace '{workspace_root}' (persistent binding change)"
+    );
+    let binding_repo = call.ctx.binding_repo.clone();
+    let event_tx = call.ctx.domain_event_tx.clone();
+    let mut binding_for_closure = binding.clone();
+    let args = call.args.clone();
+
+    with_approval(
+        &call,
+        "mcpmux_disable_server",
+        summary,
+        None,
+        true,
+        args,
+        || async move {
+            binding_for_closure
+                .feature_set_ids
+                .retain(|id| id != &server_all_id);
+            binding_for_closure.updated_at = chrono::Utc::now();
+            binding_repo.update(&binding_for_closure).await?;
+            emit_workspace_binding_changed(&event_tx, space_id, &workspace_root);
+            info!(
+                binding_id = %binding_for_closure.id,
+                feature_set_id = %server_all_id,
+                server_id = %server_id,
+                "[meta_tools] disable_server workspace applied"
+            );
+            Ok(text_result(json!({
+                "ok": true,
+                "server_id": server_id,
+                "scope": "workspace",
+                "removed": true,
+                "feature_set_id": server_all_id,
+                "binding_id": binding_for_closure.id,
+            })))
+        },
+    )
+    .await
+}
diff --git a/docs/planning/dynamic-mcp-toggle-meta-tools.md b/docs/planning/dynamic-mcp-toggle-meta-tools.md
index 0da7a4da..adcdd7ab 100644
--- a/docs/planning/dynamic-mcp-toggle-meta-tools.md
+++ b/docs/planning/dynamic-mcp-toggle-meta-tools.md
@@ -1,7 +1,7 @@
 # Dynamic MCP Toggling via Meta Tools
 
 **Last Updated:** May 19, 2026
-**Status:** Phase 3 complete — session-scope enable/disable meta tools; Phases 4–5 pending
+**Status:** Phase 4 complete — workspace-scope enable/disable on bindings; Phase 5 pending
 **Branch:** `feat/dynamic-mcp-toggle-meta-tools`
 **Base branch:** `feat/workspace-root-routing` ([upstream PR #151](https://github.com/mcpmux/mcp-mux/pull/151))
 **Issue:** TBD — file after planning review
@@ -214,17 +214,19 @@ Each write fires `tools/list_changed` per-peer via the existing `MCPNotifier::no
 
 **Outcome:** LLM can toggle servers mid-session; tools appear/disappear on next `tools/list`. No DB writes.
 
-### Phase 4 — Workspace-scope variants
+### Phase 4 — Workspace-scope variants ✅
 
-**Effort:** 1 day
+**Effort:** 1 day  
+**Completed:** May 19, 2026
 
-- Extend `EnableServerTool` / `DisableServerTool` to handle `scope: "workspace"`.
-- Enable + workspace: requires the caller to have reported MCP roots (reuse `caller_space_id` + `session_roots.get` pattern from `BindCurrentWorkspaceTool`). If no binding exists for the first reported root, return `MetaToolError::InvalidArgument("no binding exists for this workspace; create one with mcpmux_create_feature_set + mcpmux_bind_current_workspace first")`. If a binding exists, look up its FS, add a `ServerAll`-typed `FeatureSet` for `server_id`, append its id to the binding's `feature_set_ids` list.
-- Disable + workspace: remove the matching `ServerAll` FS from the binding's `feature_set_ids` if present; if the server's tools come from a custom FS (not a `ServerAll` row), reject with a message pointing the user at the Workspaces UI.
-- Always require approval for workspace scope (no auto-allow setting).
-- Integration test: enable + workspace persists across a session restart; disable + workspace removes from binding row.
+- [x] `scope: "workspace"` on enable/disable — resolves workspace binding from session roots
+- [x] Enable: create/reuse server-all FeatureSet (`server_id` field tagged), append to binding, emit `WorkspaceBindingChanged`
+- [x] Disable: remove server-all FS from binding; reject if server exposed via custom FS (Workspaces UI message)
+- [x] Always requires approval via `ApprovalBroker`
+- [x] Handler skips session `list_changed` for workspace scope (binding event fanout handles it)
+- [x] Integration tests: persist across simulated session restart, disable removes binding layer, unbound workspace rejected
 
-**Outcome:** An LLM in a bound workspace adds a `ServerAll` FS layer to its binding via `mcpmux_enable_server({"server_id": "firebase", "scope": "workspace"})`, approves in the desktop dialog, and the next time it opens that folder Firebase tools are there without re-enabling.
+**Outcome:** Workspace binding gains/loses persistent server-all FeatureSet layers via meta tools.
 
 ### Phase 5 — UI surface for session overrides
 
diff --git a/tests/rust/tests/integration/meta_tools.rs b/tests/rust/tests/integration/meta_tools.rs
index fce2ae27..39215ab4 100644
--- a/tests/rust/tests/integration/meta_tools.rs
+++ b/tests/rust/tests/integration/meta_tools.rs
@@ -405,8 +405,105 @@ async fn disable_server_removes_tools_from_list() {
 }
 
 #[tokio::test(flavor = "multi_thread")]
-async fn enable_server_rejects_workspace_scope() {
+async fn enable_server_workspace_persists_on_binding() {
     let f = Fixture::new().await;
+    f.attach_auto_publisher(ApprovalDecision::AllowOnce);
+    bind_github_only_to_session_root(&f).await;
+
+    let result = f
+        .registry
+        .call(
+            "mcpmux_enable_server",
+            &f.client_id,
+            Some(&f.session_id),
+            json!({ "server_id": "firebase", "scope": "workspace" }),
+        )
+        .await
+        .unwrap();
+    assert!(!Fixture::is_error(&result));
+    let body = Fixture::result_json(&result);
+    assert_eq!(body.get("scope").unwrap().as_str().unwrap(), "workspace");
+
+    let root = normalize_workspace_root("/tmp/mcpmux-list-servers-test");
+    let binding = f
+        .binding_repo
+        .find_longest_prefix_match(&f.space_id, &[root.clone()])
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(binding.feature_set_ids.len(), 2);
+
+    let new_session = "sess-restart-sim";
+    let tools = f
+        .feature_service
+        .get_tools_for_grants(
+            &f.space_id.to_string(),
+            &binding.feature_set_ids,
+            Some(new_session),
+        )
+        .await
+        .unwrap();
+    let servers: std::collections::HashSet<_> =
+        tools.iter().map(|t| t.server_id.as_str()).collect();
+    assert!(servers.contains("github"));
+    assert!(servers.contains("firebase"));
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn disable_server_workspace_removes_server_all_from_binding() {
+    let f = Fixture::new().await;
+    f.attach_auto_publisher(ApprovalDecision::AllowOnce);
+    bind_github_only_to_session_root(&f).await;
+
+    f.registry
+        .call(
+            "mcpmux_enable_server",
+            &f.client_id,
+            Some(&f.session_id),
+            json!({ "server_id": "firebase", "scope": "workspace" }),
+        )
+        .await
+        .unwrap();
+
+    f.registry
+        .call(
+            "mcpmux_disable_server",
+            &f.client_id,
+            Some(&f.session_id),
+            json!({ "server_id": "firebase", "scope": "workspace" }),
+        )
+        .await
+        .unwrap();
+
+    let root = normalize_workspace_root("/tmp/mcpmux-list-servers-test");
+    let binding = f
+        .binding_repo
+        .find_longest_prefix_match(&f.space_id, &[root.clone()])
+        .await
+        .unwrap()
+        .unwrap();
+    assert_eq!(binding.feature_set_ids.len(), 1);
+
+    let tools = f
+        .feature_service
+        .get_tools_for_grants(
+            &f.space_id.to_string(),
+            &binding.feature_set_ids,
+            None,
+        )
+        .await
+        .unwrap();
+    assert_eq!(tools.len(), 1);
+    assert_eq!(tools[0].server_id, "github");
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn enable_server_workspace_requires_binding() {
+    let f = Fixture::new().await;
+    f.attach_auto_publisher(ApprovalDecision::AllowOnce);
+    f.session_roots.set_roots_capable(&f.session_id, true);
+    f.session_roots.set(&f.session_id, ["/tmp/unbound-workspace"]);
+
     let result = f
         .call_tool_as_handler_would(
             "mcpmux_enable_server",
@@ -414,13 +511,6 @@ async fn enable_server_rejects_workspace_scope() {
         )
         .await;
     assert!(Fixture::is_error(&result));
-    let body = Fixture::result_json(&result);
-    assert!(
-        body.get("message")
-            .and_then(|m| m.as_str())
-            .unwrap_or("")
-            .contains("Phase 4")
-    );
 }
 
 #[tokio::test(flavor = "multi_thread")]

From b590b0b5ce5c4087ddb9e8e226caa26d94a8cba2 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Tue, 19 May 2026 09:36:46 -0600
Subject: [PATCH 08/48] feat(meta-tools): session override UI and settings
 toggle (Phase 5)

Expose session overrides in the Workspaces inspector with clear controls,
wire list/clear Tauri commands, and add a settings gate for session-scope
enable/disable approval.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 .../desktop/src-tauri/src/commands/gateway.rs |   8 +
 apps/desktop/src-tauri/src/commands/mod.rs    |   2 +
 .../src/commands/session_overrides.rs         | 107 ++++++++++
 .../src-tauri/src/commands/settings.rs        |  38 ++++
 apps/desktop/src-tauri/src/lib.rs             |   4 +
 .../src/features/settings/SettingsPage.tsx    |  54 +++++
 .../features/workspaces/WorkspacesPage.tsx    | 191 ++++++++++++++++++
 apps/desktop/src/lib/api/sessionOverrides.ts  |  60 ++++++
 crates/mcpmux-gateway/src/server/mod.rs       |  36 +++-
 .../src/services/session_roots.rs             |  11 +
 .../planning/dynamic-mcp-toggle-meta-tools.md |  12 +-
 11 files changed, 506 insertions(+), 17 deletions(-)
 create mode 100644 apps/desktop/src-tauri/src/commands/session_overrides.rs
 create mode 100644 apps/desktop/src/lib/api/sessionOverrides.ts

diff --git a/apps/desktop/src-tauri/src/commands/gateway.rs b/apps/desktop/src-tauri/src/commands/gateway.rs
index 9c04632e..f23d88e8 100644
--- a/apps/desktop/src-tauri/src/commands/gateway.rs
+++ b/apps/desktop/src-tauri/src/commands/gateway.rs
@@ -79,6 +79,10 @@ pub struct GatewayAppState {
     /// Surfaced to the desktop Workspaces tab so users can see + act on
     /// every folder connected clients are currently operating in.
     pub session_roots: Option<Arc<mcpmux_gateway::services::SessionRootsRegistry>>,
+    /// Session-scoped server enable/disable overrides (meta-tool mutations).
+    pub session_overrides: Option<Arc<mcpmux_gateway::services::SessionOverrideRegistry>>,
+    /// Per-session list_changed bridge — used when the UI clears overrides.
+    pub mcp_notifier: Option<Arc<mcpmux_gateway::consumers::MCPNotifier>>,
 }
 
 /// Gracefully shuts down a running gateway and waits for the axum task
@@ -888,6 +892,8 @@ pub async fn start_gateway(
     let server_manager = server.server_manager();
     let grant_service = server.grant_service();
     let session_roots = server.session_roots();
+    let session_overrides = server.session_overrides();
+    let mcp_notifier = server.notification_bridge();
 
     // Subscribe to OAuth completions BEFORE spawn so we don't miss early
     // events emitted during initial auto-connect.
@@ -935,6 +941,8 @@ pub async fn start_gateway(
     state.grant_service = Some(grant_service);
     state.approval_broker = Some(approval_broker);
     state.session_roots = Some(session_roots);
+    state.session_overrides = Some(session_overrides);
+    state.mcp_notifier = Some(mcp_notifier);
     info!(
         "[Gateway] Started — url={}, event_emitter={}, grant_service={}",
         url,
diff --git a/apps/desktop/src-tauri/src/commands/mod.rs b/apps/desktop/src-tauri/src/commands/mod.rs
index bbfd57d9..692c5bd3 100644
--- a/apps/desktop/src-tauri/src/commands/mod.rs
+++ b/apps/desktop/src-tauri/src/commands/mod.rs
@@ -17,6 +17,7 @@ pub mod server;
 pub mod server_discovery;
 pub mod server_feature;
 pub mod server_manager;
+pub mod session_overrides;
 pub mod settings;
 pub mod space;
 pub mod workspace_binding;
@@ -35,6 +36,7 @@ pub use server::*;
 pub use server_discovery::*;
 pub use server_feature::*;
 pub use server_manager::*;
+pub use session_overrides::*;
 pub use settings::*;
 pub use space::*;
 pub use workspace_binding::*;
diff --git a/apps/desktop/src-tauri/src/commands/session_overrides.rs b/apps/desktop/src-tauri/src/commands/session_overrides.rs
new file mode 100644
index 00000000..f6c06cd4
--- /dev/null
+++ b/apps/desktop/src-tauri/src/commands/session_overrides.rs
@@ -0,0 +1,107 @@
+//! Tauri commands for inspecting and clearing session-scoped server overrides.
+
+use std::sync::Arc;
+
+use mcpmux_gateway::services::SessionOverrideEntry;
+use serde::Serialize;
+use tauri::{AppHandle, Emitter, State};
+use tokio::sync::RwLock;
+use tracing::info;
+
+use super::gateway::GatewayAppState;
+
+/// Per-session override state surfaced to the Workspaces inspector.
+#[derive(Debug, Clone, Serialize)]
+pub struct SessionOverrideDto {
+    pub session_id: String,
+    pub enabled: Vec<String>,
+    pub disabled: Vec<String>,
+    pub roots: Vec<String>,
+}
+
+impl SessionOverrideDto {
+    fn from_entry(entry: SessionOverrideEntry, roots: Vec<String>) -> Self {
+        Self {
+            session_id: entry.session_id,
+            enabled: entry.enabled,
+            disabled: entry.disabled,
+            roots,
+        }
+    }
+}
+
+fn build_dtos(gateway: &GatewayAppState) -> Vec<SessionOverrideDto> {
+    let Some(ref overrides) = gateway.session_overrides else {
+        return vec![];
+    };
+    let roots_by_session: std::collections::HashMap<String, Vec<String>> = gateway
+        .session_roots
+        .as_ref()
+        .map(|reg| {
+            reg.list_all_sessions()
+                .into_iter()
+                .collect()
+        })
+        .unwrap_or_default();
+
+    overrides
+        .list_all()
+        .into_iter()
+        .map(|entry| {
+            let roots = roots_by_session
+                .get(&entry.session_id)
+                .cloned()
+                .unwrap_or_default();
+            SessionOverrideDto::from_entry(entry, roots)
+        })
+        .collect()
+}
+
+/// List override state for one session, or every session when `session_id`
+/// is omitted. Returns an empty list when the gateway is not running.
+#[tauri::command]
+pub async fn list_session_overrides(
+    session_id: Option<String>,
+    gateway_state: State<'_, Arc<RwLock<GatewayAppState>>>,
+) -> Result<Vec<SessionOverrideDto>, String> {
+    let guard = gateway_state.read().await;
+    let mut dtos = build_dtos(&guard);
+    if let Some(sid) = session_id {
+        dtos.retain(|d| d.session_id == sid);
+    }
+    Ok(dtos)
+}
+
+/// Drop all enable/disable overrides for a session and push list_changed so
+/// the client's tool list reverts to binding-only routing.
+#[tauri::command]
+pub async fn clear_session_overrides(
+    session_id: String,
+    gateway_state: State<'_, Arc<RwLock<GatewayAppState>>>,
+    app_handle: AppHandle,
+) -> Result<(), String> {
+    let notifier = {
+        let guard = gateway_state.read().await;
+        let overrides = guard
+            .session_overrides
+            .as_ref()
+            .ok_or("Gateway is not running")?;
+        overrides.clear(&session_id);
+        guard.mcp_notifier.clone()
+    };
+
+    if let Some(notifier) = notifier {
+        notifier.notify_session_lists_changed(&session_id).await;
+    }
+
+    info!("[session_overrides] cleared overrides for session {}", session_id);
+
+    if let Err(e) = app_handle.emit(
+        "session-overrides-changed",
+        serde_json::json!({ "session_id": session_id }),
+    ) {
+        tracing::warn!("[session_overrides] failed to emit session-overrides-changed: {e}");
+    }
+
+    Ok(())
+}
diff --git a/apps/desktop/src-tauri/src/commands/settings.rs b/apps/desktop/src-tauri/src/commands/settings.rs
index 10299519..d0c95682 100644
--- a/apps/desktop/src-tauri/src/commands/settings.rs
+++ b/apps/desktop/src-tauri/src/commands/settings.rs
@@ -165,6 +165,44 @@ pub async fn set_meta_tools_enabled(
     Ok(())
 }
 
+/// Whether session-scope `mcpmux_enable_server` / `mcpmux_disable_server`
+/// calls require approval. Default OFF (auto-allow).
+#[tauri::command]
+pub async fn get_session_overrides_require_approval(
+    app_state: State<'_, AppState>,
+) -> Result<bool, String> {
+    match app_state
+        .settings_repository
+        .get("gateway.session_overrides_require_approval")
+        .await
+    {
+        Ok(Some(v)) => Ok(matches!(v.as_str(), "true" | "1")),
+        _ => Ok(false),
+    }
+}
+
+/// Flip the session-override approval gate. Takes effect on the next
+/// session-scope enable/disable meta-tool call.
+#[tauri::command]
+pub async fn set_session_overrides_require_approval(
+    require_approval: bool,
+    app_state: State<'_, AppState>,
+) -> Result<(), String> {
+    app_state
+        .settings_repository
+        .set(
+            "gateway.session_overrides_require_approval",
+            if require_approval { "true" } else { "false" },
+        )
+        .await
+        .map_err(|e| format!("Failed to save session_overrides_require_approval: {}", e))?;
+    info!(
+        "[Settings] session_overrides_require_approval = {}",
+        require_approval
+    );
+    Ok(())
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
diff --git a/apps/desktop/src-tauri/src/lib.rs b/apps/desktop/src-tauri/src/lib.rs
index 08c7d44d..bca6e511 100644
--- a/apps/desktop/src-tauri/src/lib.rs
+++ b/apps/desktop/src-tauri/src/lib.rs
@@ -912,6 +912,10 @@ pub fn run() {
             commands::revoke_meta_tool_grant,
             commands::get_meta_tools_enabled,
             commands::set_meta_tools_enabled,
+            commands::get_session_overrides_require_approval,
+            commands::set_session_overrides_require_approval,
+            commands::list_session_overrides,
+            commands::clear_session_overrides,
             // Config export commands
             commands::preview_config_export,
             commands::export_config_to_file,
diff --git a/apps/desktop/src/features/settings/SettingsPage.tsx b/apps/desktop/src/features/settings/SettingsPage.tsx
index caccec21..7ea6a0f8 100644
--- a/apps/desktop/src/features/settings/SettingsPage.tsx
+++ b/apps/desktop/src/features/settings/SettingsPage.tsx
@@ -36,6 +36,10 @@ import {
 import { useAppStore, useTheme, useAnalyticsEnabled } from '@/stores';
 import { UpdateChecker } from './UpdateChecker';
 import { getMetaToolsEnabled, setMetaToolsEnabled } from '@/lib/api/metaTools';
+import {
+  getSessionOverridesRequireApproval,
+  setSessionOverridesRequireApproval,
+} from '@/lib/api/sessionOverrides';
 import { MetaToolAuditLog, MetaToolGrantsPanel } from '@/features/metaTools';
 import { useGatewayControl } from '@/features/gateway/useGatewayControl';
 import { CONTRIBUTE, openExternal } from '@/lib/contribute';
@@ -78,6 +82,10 @@ export function SettingsPage() {
   // Meta-tools master switch — gates the entire `mcpmux_*` namespace.
   const [metaToolsEnabled, setMetaToolsEnabledState] = useState<boolean>(true);
   const [loadingMetaTools, setLoadingMetaTools] = useState(true);
+  const [sessionOverridesRequireApproval, setSessionOverridesRequireApprovalState] =
+    useState<boolean>(false);
+  const [loadingSessionOverrideApproval, setLoadingSessionOverrideApproval] =
+    useState(true);
 
   // Gateway port — persisted user override, the default the app ships
   // with, and the port the currently-running gateway is bound to. When
@@ -181,6 +189,12 @@ export function SettingsPage() {
       .then((v) => setMetaToolsEnabledState(v))
       .catch((e) => console.error('Failed to load meta_tools_enabled', e))
       .finally(() => setLoadingMetaTools(false));
+    getSessionOverridesRequireApproval()
+      .then((v) => setSessionOverridesRequireApprovalState(v))
+      .catch((e) =>
+        console.error('Failed to load session_overrides_require_approval', e)
+      )
+      .finally(() => setLoadingSessionOverrideApproval(false));
   }, []);
 
   const handleToggleMetaTools = async (next: boolean) => {
@@ -200,6 +214,23 @@ export function SettingsPage() {
     }
   };
 
+  const handleToggleSessionOverrideApproval = async (next: boolean) => {
+    const previous = sessionOverridesRequireApproval;
+    setSessionOverridesRequireApprovalState(next);
+    try {
+      await setSessionOverridesRequireApproval(next);
+      success(
+        next ? 'Session overrides require approval' : 'Session overrides auto-allowed',
+        next
+          ? 'mcpmux_enable_server / mcpmux_disable_server (session scope) will prompt before applying.'
+          : 'Session-scope enable/disable applies immediately without a dialog.'
+      );
+    } catch (e) {
+      setSessionOverridesRequireApprovalState(previous);
+      error('Failed to save setting', e instanceof Error ? e.message : String(e));
+    }
+  };
+
   // Load logs path on mount
   useEffect(() => {
     const loadLogsPath = async () => {
@@ -632,6 +663,29 @@ export function SettingsPage() {
               data-testid="meta-tools-enabled-switch"
             />
           </div>
+          <div className="flex items-center justify-between gap-4">
+            <div className="flex items-start gap-3 flex-1 min-w-0">
+              <AlertCircle className="h-5 w-5 mt-0.5 text-[rgb(var(--muted))] flex-shrink-0" />
+              <div>
+                <label className="text-sm font-medium">
+                  Require approval for session-scope overrides
+                </label>
+                <p className="text-xs text-[rgb(var(--muted))] mt-1">
+                  When on,{' '}
+                  <code className="font-mono">mcpmux_enable_server</code> /{' '}
+                  <code className="font-mono">mcpmux_disable_server</code> with{' '}
+                  <code className="font-mono">scope: &quot;session&quot;</code> show the native
+                  approval dialog. Workspace-scope writes always require approval.
+                </p>
+              </div>
+            </div>
+            <Switch
+              checked={sessionOverridesRequireApproval}
+              onCheckedChange={handleToggleSessionOverrideApproval}
+              disabled={loadingSessionOverrideApproval || !metaToolsEnabled}
+              data-testid="session-overrides-require-approval-switch"
+            />
+          </div>
           <MetaToolGrantsPanel />
           <MetaToolAuditLog />
         </CardContent>
diff --git a/apps/desktop/src/features/workspaces/WorkspacesPage.tsx b/apps/desktop/src/features/workspaces/WorkspacesPage.tsx
index 18b66666..cda9b4e0 100644
--- a/apps/desktop/src/features/workspaces/WorkspacesPage.tsx
+++ b/apps/desktop/src/features/workspaces/WorkspacesPage.tsx
@@ -19,6 +19,7 @@ import {
   Search,
   Server as ServerIcon,
   Trash2,
+  ToggleLeft,
   Wrench,
   X,
 } from 'lucide-react';
@@ -43,6 +44,12 @@ import {
   type WorkspaceBindingInput,
   type WorkspaceEffectiveFeatures,
 } from '@/lib/api/workspaceBindings';
+import {
+  clearSessionOverrides,
+  listSessionOverrides,
+  overridesForWorkspace,
+  type SessionOverride,
+} from '@/lib/api/sessionOverrides';
 import {
   isStarterFeatureSet,
   listFeatureSets,
@@ -925,6 +932,19 @@ function InspectorPanel({
             />
           </CollapsibleSection>
         )}
+
+        {entry && !isNew && entry.isLive && (
+          <CollapsibleSection
+            icon={<ToggleLeft className="h-5 w-5" />}
+            tone="primary"
+            title="Active session overrides"
+            subtitle="Servers an LLM enabled or disabled for live sessions on this folder"
+            defaultOpen={true}
+            testId="workspace-session-overrides-section"
+          >
+            <SessionOverridesContent workspaceRoot={entry.root} />
+          </CollapsibleSection>
+        )}
       </div>
 
       {entry?.binding && (
@@ -980,6 +1000,177 @@ function SaveStatusPill({ status }: { status: SaveStatus }) {
   );
 }
 
+// ---------------------------------------------------------------------------
+// Session overrides — per-session enable/disable from meta tools
+// ---------------------------------------------------------------------------
+
+/**
+ * Lists live sessions reporting this workspace root and any session-scoped
+ * server overrides applied via `mcpmux_enable_server` / `mcpmux_disable_server`.
+ */
+function SessionOverridesContent({ workspaceRoot }: { workspaceRoot: string }) {
+  const [entries, setEntries] = useState<SessionOverride[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+  const [error, setError] = useState<string | null>(null);
+  const [clearingId, setClearingId] = useState<string | null>(null);
+
+  const reload = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const all = await listSessionOverrides();
+      setEntries(overridesForWorkspace(all, workspaceRoot));
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+      setEntries([]);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [workspaceRoot]);
+
+  useEffect(() => {
+    void reload();
+  }, [reload]);
+
+  useEffect(() => {
+    const unMeta = listen<{ tool_name?: string }>('meta-tool-invoked', (ev) => {
+      const name = ev.payload?.tool_name ?? '';
+      if (name === 'mcpmux_enable_server' || name === 'mcpmux_disable_server') {
+        void reload();
+      }
+    });
+    const unOverrides = listen('session-overrides-changed', () => {
+      void reload();
+    });
+    return () => {
+      void unMeta.then((fn) => fn());
+      void unOverrides.then((fn) => fn());
+    };
+  }, [reload]);
+
+  const handleClear = async (sessionId: string) => {
+    setClearingId(sessionId);
+    try {
+      await clearSessionOverrides(sessionId);
+      await reload();
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+    } finally {
+      setClearingId(null);
+    }
+  };
+
+  if (isLoading) {
+    return (
+      <div className="flex items-center gap-2 text-sm text-[rgb(var(--muted))] py-2">
+        <Loader2 className="h-4 w-4 animate-spin" />
+        Loading session overrides…
+      </div>
+    );
+  }
+
+  if (error) {
+    return (
+      <p className="text-sm text-red-600 dark:text-red-400" role="alert">
+        {error}
+      </p>
+    );
+  }
+
+  if (entries.length === 0) {
+    return (
+      <p className="text-sm text-[rgb(var(--muted))]">
+        No live sessions on this folder have session-scoped server overrides.
+      </p>
+    );
+  }
+
+  return (
+    <div className="space-y-3" data-testid="workspace-session-overrides-list">
+      {entries.map((entry) => {
+        const shortId =
+          entry.session_id.length > 12
+            ? `${entry.session_id.slice(0, 8)}…${entry.session_id.slice(-4)}`
+            : entry.session_id;
+        const hasOverrides = entry.enabled.length > 0 || entry.disabled.length > 0;
+        return (
+          <div
+            key={entry.session_id}
+            className="rounded-lg border border-[rgb(var(--border-subtle))] bg-[rgb(var(--background))] p-3 space-y-2"
+            data-testid={`session-override-${entry.session_id}`}
+          >
+            <div className="flex items-start justify-between gap-2">
+              <div className="min-w-0">
+                <p
+                  className="text-xs font-mono text-[rgb(var(--foreground))] truncate"
+                  title={entry.session_id}
+                >
+                  {shortId}
+                </p>
+                {entry.roots.length > 0 && (
+                  <p className="text-[10px] text-[rgb(var(--muted))] font-mono truncate mt-0.5">
+                    {entry.roots.join(', ')}
+                  </p>
+                )}
+              </div>
+              {hasOverrides && (
+                <Button
+                  variant="ghost"
+                  size="sm"
+                  className="flex-shrink-0 text-xs h-7"
+                  disabled={clearingId === entry.session_id}
+                  onClick={() => void handleClear(entry.session_id)}
+                  data-testid={`session-override-clear-${entry.session_id}`}
+                >
+                  {clearingId === entry.session_id ? (
+                    <Loader2 className="h-3 w-3 animate-spin" />
+                  ) : (
+                    'Clear all'
+                  )}
+                </Button>
+              )}
+            </div>
+            {entry.enabled.length > 0 && (
+              <div>
+                <p className="text-[10px] font-semibold uppercase tracking-wider text-green-700 dark:text-green-400 mb-1">
+                  Enabled (session)
+                </p>
+                <div className="flex flex-wrap gap-1">
+                  {entry.enabled.map((id) => (
+                    <span
+                      key={`en-${id}`}
+                      className="inline-flex px-1.5 py-0.5 rounded text-[10px] font-mono bg-green-100 dark:bg-green-900/30 text-green-800 dark:text-green-200"
+                    >
+                      {id}
+                    </span>
+                  ))}
+                </div>
+              </div>
+            )}
+            {entry.disabled.length > 0 && (
+              <div>
+                <p className="text-[10px] font-semibold uppercase tracking-wider text-amber-700 dark:text-amber-400 mb-1">
+                  Disabled (session)
+                </p>
+                <div className="flex flex-wrap gap-1">
+                  {entry.disabled.map((id) => (
+                    <span
+                      key={`dis-${id}`}
+                      className="inline-flex px-1.5 py-0.5 rounded text-[10px] font-mono bg-amber-100 dark:bg-amber-900/30 text-amber-800 dark:text-amber-200"
+                    >
+                      {id}
+                    </span>
+                  ))}
+                </div>
+              </div>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Effective features — what tools / prompts / resources this folder sees
 // right now, grouped by backend server so the user can see at a glance
diff --git a/apps/desktop/src/lib/api/sessionOverrides.ts b/apps/desktop/src/lib/api/sessionOverrides.ts
new file mode 100644
index 00000000..981dba52
--- /dev/null
+++ b/apps/desktop/src/lib/api/sessionOverrides.ts
@@ -0,0 +1,60 @@
+import { invoke } from '@tauri-apps/api/core';
+
+/** Session-scoped server enable/disable overrides from meta tools. */
+export interface SessionOverride {
+  session_id: string;
+  enabled: string[];
+  disabled: string[];
+  /** Reported MCP workspace roots for this session (may be empty). */
+  roots: string[];
+}
+
+/** List override state for all sessions, or one session when `sessionId` is set. */
+export async function listSessionOverrides(
+  sessionId?: string
+): Promise<SessionOverride[]> {
+  return invoke('list_session_overrides', { sessionId: sessionId ?? null });
+}
+
+/** Drop all overrides for a session and refresh its tool list. */
+export async function clearSessionOverrides(sessionId: string): Promise<void> {
+  return invoke('clear_session_overrides', { sessionId });
+}
+
+/** Whether session-scope enable/disable meta tools require approval. Default false. */
+export async function getSessionOverridesRequireApproval(): Promise<boolean> {
+  return invoke('get_session_overrides_require_approval');
+}
+
+/** Persist the session-override approval gate. */
+export async function setSessionOverridesRequireApproval(
+  requireApproval: boolean
+): Promise<void> {
+  return invoke('set_session_overrides_require_approval', { requireApproval });
+}
+
+/**
+ * True when a session's reported root relates to the workspace path shown
+ * in the inspector (exact match or parent/child prefix).
+ */
+export function sessionRootMatchesWorkspace(
+  sessionRoot: string,
+  workspaceRoot: string
+): boolean {
+  if (sessionRoot === workspaceRoot) return true;
+  const sep = sessionRoot.includes('\\') ? '\\' : '/';
+  return (
+    workspaceRoot.startsWith(`${sessionRoot}${sep}`) ||
+    sessionRoot.startsWith(`${workspaceRoot}${sep}`)
+  );
+}
+
+/** Filter overrides to sessions reporting this workspace root. */
+export function overridesForWorkspace(
+  overrides: SessionOverride[],
+  workspaceRoot: string
+): SessionOverride[] {
+  return overrides.filter((entry) =>
+    entry.roots.some((root) => sessionRootMatchesWorkspace(root, workspaceRoot))
+  );
+}
diff --git a/crates/mcpmux-gateway/src/server/mod.rs b/crates/mcpmux-gateway/src/server/mod.rs
index 8bd55dc9..64124e38 100644
--- a/crates/mcpmux-gateway/src/server/mod.rs
+++ b/crates/mcpmux-gateway/src/server/mod.rs
@@ -84,6 +84,9 @@ pub struct GatewayServer {
     config: GatewayConfig,
     state: Arc<RwLock<GatewayState>>,
     services: ServiceContainer,
+    /// Shared with the MCP handler and the desktop layer for session-scoped
+    /// list_changed pushes after override mutations.
+    notification_bridge: Arc<MCPNotifier>,
 }
 
 impl GatewayServer {
@@ -118,12 +121,19 @@ impl GatewayServer {
         // Initialize all services using DI container (pass domain event sender for non-blocking emission)
         let services = ServiceContainer::initialize(&dependencies, domain_event_tx, state.clone());
 
+        let notification_bridge = Arc::new(MCPNotifier::new(
+            services.feature_set_resolver.clone(),
+            services.pool_services.feature_service.clone(),
+            services.session_overrides.clone(),
+        ));
+
         info!("[Gateway] Services initialized successfully");
 
         Self {
             config,
             state,
             services,
+            notification_bridge,
         }
     }
 
@@ -185,6 +195,16 @@ impl GatewayServer {
         self.services.session_roots.clone()
     }
 
+    /// Session-scoped enable/disable overrides (meta-tool mutations).
+    pub fn session_overrides(&self) -> Arc<crate::services::SessionOverrideRegistry> {
+        self.services.session_overrides.clone()
+    }
+
+    /// Notification bridge for per-session list_changed after override clears.
+    pub fn notification_bridge(&self) -> Arc<MCPNotifier> {
+        self.notification_bridge.clone()
+    }
+
     /// Get the OAuth manager
     pub fn oauth_manager(&self) -> Arc<crate::pool::OutboundOAuthManager> {
         self.services.pool_services.oauth_manager.clone()
@@ -226,19 +246,11 @@ impl GatewayServer {
             base_url: self.config.base_url(),
         };
 
-        // Create MCP notifier (session-keyed fanout, consults the same
-        // FeatureSet resolver the request handlers use).
-        let notification_bridge = Arc::new(MCPNotifier::new(
-            self.services.feature_set_resolver.clone(),
-            self.services.pool_services.feature_service.clone(),
-            self.services.session_overrides.clone(),
-        ));
-
         // Start listening to DomainEvents
         {
             let gw_state = tokio::task::block_in_place(|| state.blocking_read());
             let event_rx = gw_state.subscribe_domain_events();
-            notification_bridge.clone().start(event_rx);
+            self.notification_bridge.clone().start(event_rx);
         }
 
         // Create OAuth event handler (updates oauth_connected flag on OAuth success)
@@ -256,8 +268,10 @@ impl GatewayServer {
         }
 
         // Create MCP handler
-        let handler =
-            McpMuxGatewayHandler::new(Arc::new(self.services.clone()), notification_bridge.clone());
+        let handler = McpMuxGatewayHandler::new(
+            Arc::new(self.services.clone()),
+            self.notification_bridge.clone(),
+        );
 
         // Create STATEFUL MCP service (full Streamable HTTP per spec 2025-11-25)
         // stateful_mode: true means:
diff --git a/crates/mcpmux-gateway/src/services/session_roots.rs b/crates/mcpmux-gateway/src/services/session_roots.rs
index ee8a4426..62c189a1 100644
--- a/crates/mcpmux-gateway/src/services/session_roots.rs
+++ b/crates/mcpmux-gateway/src/services/session_roots.rs
@@ -179,6 +179,17 @@ impl SessionRootsRegistry {
         out
     }
 
+    /// Snapshot of every session with reported roots (for UI inspection).
+    pub fn list_all_sessions(&self) -> Vec<(String, Vec<String>)> {
+        let mut out: Vec<(String, Vec<String>)> = self
+            .map
+            .iter()
+            .map(|entry| (entry.key().clone(), entry.value().clone()))
+            .collect();
+        out.sort_by(|a, b| a.0.cmp(&b.0));
+        out
+    }
+
     /// Current number of tracked sessions. Test helper; cheap to call but
     /// not useful in hot paths.
     #[cfg(test)]
diff --git a/docs/planning/dynamic-mcp-toggle-meta-tools.md b/docs/planning/dynamic-mcp-toggle-meta-tools.md
index adcdd7ab..cdbe63a4 100644
--- a/docs/planning/dynamic-mcp-toggle-meta-tools.md
+++ b/docs/planning/dynamic-mcp-toggle-meta-tools.md
@@ -1,7 +1,7 @@
 # Dynamic MCP Toggling via Meta Tools
 
 **Last Updated:** May 19, 2026
-**Status:** Phase 4 complete — workspace-scope enable/disable on bindings; Phase 5 pending
+**Status:** Phase 5 complete — UI surface for session overrides + settings toggle
 **Branch:** `feat/dynamic-mcp-toggle-meta-tools`
 **Base branch:** `feat/workspace-root-routing` ([upstream PR #151](https://github.com/mcpmux/mcp-mux/pull/151))
 **Issue:** TBD — file after planning review
@@ -232,11 +232,11 @@ Each write fires `tools/list_changed` per-peer via the existing `MCPNotifier::no
 
 **Effort:** 1 day
 
-- New "Active session overrides" sub-panel inside `WorkspacesPage.tsx`'s live-session inspector: lists per-session `enabled`/`disabled` server ids alongside the reported roots.
-- "Clear all overrides" button per session — calls the new `clear_session_overrides` Tauri command. Useful when a session got into a weird state and the user wants a clean default-routing read.
-- New Tauri commands: `list_session_overrides(session_id) -> { enabled: string[], disabled: string[] }`, `clear_session_overrides(session_id)`.
-- Settings checkbox under Gateway settings: "Require approval for session-scope overrides" — wires to `gateway.session_overrides_require_approval`.
-- README + CHANGELOG entries describing the new meta-tools and the manifest-driven workflow.
+- [x] New "Active session overrides" sub-panel inside `WorkspacesPage.tsx`'s live-session inspector: lists per-session `enabled`/`disabled` server ids alongside the reported roots.
+- [x] "Clear all overrides" button per session — calls the new `clear_session_overrides` Tauri command. Useful when a session got into a weird state and the user wants a clean default-routing read.
+- [x] New Tauri commands: `list_session_overrides(session_id) -> { enabled: string[], disabled: string[] }`, `clear_session_overrides(session_id)`.
+- [x] Settings checkbox under Gateway settings: "Require approval for session-scope overrides" — wires to `gateway.session_overrides_require_approval`.
+- [ ] README + CHANGELOG entries describing the new meta-tools and the manifest-driven workflow.
 
 **Outcome:** From the Workspaces tab, a user can see at a glance "session abc123 has GitHub enabled (session) and Firebase disabled (session)" and clear them with one click. The new approval-required setting is discoverable in Gateway settings without reading docs.
 

From 5730b25b518a08b9c6d7ad1e8b99d5d7c7caa4d5 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Tue, 19 May 2026 09:47:33 -0600
Subject: [PATCH 09/48] docs(meta-tools): close Phase 5 with README and
 planning reconciliation

Document the mcpmux_* manifest workflow in README, reconcile the planning
doc for validation/PR gate, and fix stale DCR and notification dedup tests.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 README.md                                     | 22 +++++++++++
 .../src/commands/session_overrides.rs         | 11 +++---
 .../src/consumers/mcp_notifier.rs             |  5 ++-
 crates/mcpmux-gateway/src/mcp/handler.rs      |  6 ++-
 .../src/services/meta_tools/registry.rs       |  4 +-
 .../src/services/meta_tools/tools.rs          | 16 +++-----
 .../services/meta_tools/workspace_server.rs   | 12 ++----
 .../src/services/session_roots.rs             |  3 +-
 .../planning/dynamic-mcp-toggle-meta-tools.md | 39 ++++++++++++++++---
 tests/rust/tests/integration/meta_tools.rs    | 24 ++++++------
 tests/rust/tests/oauth/dcr.rs                 | 15 +++++--
 .../streamable_http/gateway_notifications.rs  |  5 ++-
 12 files changed, 107 insertions(+), 55 deletions(-)

diff --git a/README.md b/README.md
index a4444377..ba825bdf 100644
--- a/README.md
+++ b/README.md
@@ -113,6 +113,28 @@ Not every AI client should have the same power. Create Feature Sets — permissi
 
 ![Feature Sets — granular per-server tool selection](docs/screenshots/featureset-detail.png)
 
+### Self-Management Meta Tools (mcpmux_*)
+
+Routing everything through one gateway endpoint means connected AI clients can see every backend tool at session start — even when the project only needs a handful. Workspace bindings pin stable per-folder toolsets, but they do not cover one-off needs ("enable Firebase for the next 15 minutes") or discovery-driven workflows where the LLM picks servers as it goes.
+
+McpMux exposes a built-in `mcpmux_*` tool namespace so the LLM can introspect and reshape its own tool surface mid-conversation:
+
+1. Call **`mcpmux_list_servers`** — server-level manifest with per-server status: `enabled_via_binding`, `enabled_via_session`, `disabled_via_session`, or `inactive`.
+2. Call **`mcpmux_enable_server`** or **`mcpmux_disable_server`** — toggle servers on or off. The gateway pushes `tools/list_changed` so the tool list refreshes without reconnecting.
+3. Use **`scope: "session"`** (default) for ephemeral overrides that die with the MCP session, or **`scope: "workspace"`** to persistently add/remove a server from the workspace binding (workspace writes always require approval).
+
+| Tool | Type | Purpose |
+| ---- | ---- | ------- |
+| `mcpmux_list_all_tools` | read | Full tool roster in the resolved Space |
+| `mcpmux_list_feature_sets` | read | FeatureSets available in the resolved Space |
+| `mcpmux_list_servers` | read | Server-level manifest with status |
+| `mcpmux_enable_server` | write | Enable a server (session or workspace scope) |
+| `mcpmux_disable_server` | write | Disable a server (session or workspace scope) |
+| `mcpmux_create_feature_set` | write | Create a custom FeatureSet |
+| `mcpmux_bind_current_workspace` | write | Bind the session's workspace root to FeatureSets |
+
+In the desktop app: **Settings → Self-management tools** toggles the whole namespace and optional approval for session-scope overrides. **Workspaces → live folder inspector → Active session overrides** shows per-session enabled/disabled servers and lets you clear overrides with one click.
+
 ### See and Manage Every Connected Client
 
 Cursor, VS Code, Windsurf, Claude Code — see every AI client connected to your gateway in real time. Click any client to manage its workspace, grant or revoke feature sets, and see exactly which tools it can access. New clients authenticate via OAuth with a one-click approval flow.
diff --git a/apps/desktop/src-tauri/src/commands/session_overrides.rs b/apps/desktop/src-tauri/src/commands/session_overrides.rs
index f6c06cd4..6d12c131 100644
--- a/apps/desktop/src-tauri/src/commands/session_overrides.rs
+++ b/apps/desktop/src-tauri/src/commands/session_overrides.rs
@@ -37,11 +37,7 @@ fn build_dtos(gateway: &GatewayAppState) -> Vec<SessionOverrideDto> {
     let roots_by_session: std::collections::HashMap<String, Vec<String>> = gateway
         .session_roots
         .as_ref()
-        .map(|reg| {
-            reg.list_all_sessions()
-                .into_iter()
-                .collect()
-        })
+        .map(|reg| reg.list_all_sessions().into_iter().collect())
         .unwrap_or_default();
 
     overrides
@@ -94,7 +90,10 @@ pub async fn clear_session_overrides(
         notifier.notify_session_lists_changed(&session_id).await;
     }
 
-    info!("[session_overrides] cleared overrides for session {}", session_id);
+    info!(
+        "[session_overrides] cleared overrides for session {}",
+        session_id
+    );
 
     if let Err(e) = app_handle.emit(
         "session-overrides-changed",
diff --git a/crates/mcpmux-gateway/src/consumers/mcp_notifier.rs b/crates/mcpmux-gateway/src/consumers/mcp_notifier.rs
index 0dfc7926..ce865e87 100644
--- a/crates/mcpmux-gateway/src/consumers/mcp_notifier.rs
+++ b/crates/mcpmux-gateway/src/consumers/mcp_notifier.rs
@@ -1100,7 +1100,10 @@ impl MCPNotifier {
             return;
         };
 
-        if self.reap_dead_sessions(&[(session_id.to_string(), peer.clone())]).contains(&session_id.to_string()) {
+        if self
+            .reap_dead_sessions(&[(session_id.to_string(), peer.clone())])
+            .contains(&session_id.to_string())
+        {
             return;
         }
 
diff --git a/crates/mcpmux-gateway/src/mcp/handler.rs b/crates/mcpmux-gateway/src/mcp/handler.rs
index b5242ef5..e3414842 100644
--- a/crates/mcpmux-gateway/src/mcp/handler.rs
+++ b/crates/mcpmux-gateway/src/mcp/handler.rs
@@ -676,7 +676,11 @@ impl ServerHandler for McpMuxGatewayHandler {
             .services
             .pool_services
             .feature_service
-            .get_tools_for_grants(&space_id.to_string(), &feature_set_ids, session_id_owned.as_deref())
+            .get_tools_for_grants(
+                &space_id.to_string(),
+                &feature_set_ids,
+                session_id_owned.as_deref(),
+            )
             .await
             .map_err(|e| McpError::internal_error(format!("Failed to get tools: {}", e), None))?;
 
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/registry.rs b/crates/mcpmux-gateway/src/services/meta_tools/registry.rs
index 4e1a82e0..85515bb3 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/registry.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/registry.rs
@@ -19,9 +19,7 @@ use tokio::sync::broadcast;
 
 use super::approval::ApprovalBroker;
 use crate::pool::FeatureService;
-use crate::services::{
-    FeatureSetResolverService, SessionOverrideRegistry, SessionRootsRegistry,
-};
+use crate::services::{FeatureSetResolverService, SessionOverrideRegistry, SessionRootsRegistry};
 
 /// App-settings key that toggles the entire `mcpmux_*` namespace.
 /// Present + "false" → hidden; missing or anything else → enabled.
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
index f16824d6..4c626423 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
@@ -386,11 +386,9 @@ async fn validate_server_in_space(
 }
 
 fn require_session_id(call: &MetaToolCall<'_>) -> Result<String, MetaToolError> {
-    call.session_id
-        .map(|s| s.to_string())
-        .ok_or_else(|| {
-            MetaToolError::InvalidArgument("session scope requires an MCP session id".into())
-        })
+    call.session_id.map(|s| s.to_string()).ok_or_else(|| {
+        MetaToolError::InvalidArgument("session scope requires an MCP session id".into())
+    })
 }
 
 // ---------------------------------------------------------------------------
@@ -472,9 +470,7 @@ impl MetaTool for EnableServerTool {
             .await;
         }
 
-        call.ctx
-            .session_overrides
-            .enable(&session_id, &server_id);
+        call.ctx.session_overrides.enable(&session_id, &server_id);
         if let Ok(mut decision) = call.audit_decision.lock() {
             *decision = Some("session_override");
         }
@@ -567,9 +563,7 @@ impl MetaTool for DisableServerTool {
             .await;
         }
 
-        call.ctx
-            .session_overrides
-            .disable(&session_id, &server_id);
+        call.ctx.session_overrides.disable(&session_id, &server_id);
         if let Ok(mut decision) = call.audit_decision.lock() {
             *decision = Some("session_override");
         }
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/workspace_server.rs b/crates/mcpmux-gateway/src/services/meta_tools/workspace_server.rs
index 9496d6c2..13434880 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/workspace_server.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/workspace_server.rs
@@ -24,14 +24,10 @@ async fn resolve_workspace_binding(
     call: &MetaToolCall<'_>,
     space_id: Uuid,
 ) -> Result<(WorkspaceBinding, String), MetaToolError> {
-    let session_id = call
-        .session_id
-        .ok_or_else(|| MetaToolError::InvalidArgument("workspace scope requires an MCP session id".into()))?;
-    let roots = call
-        .ctx
-        .session_roots
-        .get(session_id)
-        .unwrap_or_default();
+    let session_id = call.session_id.ok_or_else(|| {
+        MetaToolError::InvalidArgument("workspace scope requires an MCP session id".into())
+    })?;
+    let roots = call.ctx.session_roots.get(session_id).unwrap_or_default();
     let root = roots.into_iter().next().ok_or_else(|| {
         MetaToolError::InvalidArgument(
             "caller did not report any MCP roots; cannot resolve workspace".into(),
diff --git a/crates/mcpmux-gateway/src/services/session_roots.rs b/crates/mcpmux-gateway/src/services/session_roots.rs
index 62c189a1..71a8cf97 100644
--- a/crates/mcpmux-gateway/src/services/session_roots.rs
+++ b/crates/mcpmux-gateway/src/services/session_roots.rs
@@ -159,8 +159,7 @@ impl SessionRootsRegistry {
         if unchanged {
             return false;
         }
-        self.last_resolution
-            .insert(session_id.to_string(), new_val);
+        self.last_resolution.insert(session_id.to_string(), new_val);
         true
     }
 
diff --git a/docs/planning/dynamic-mcp-toggle-meta-tools.md b/docs/planning/dynamic-mcp-toggle-meta-tools.md
index cdbe63a4..5556e658 100644
--- a/docs/planning/dynamic-mcp-toggle-meta-tools.md
+++ b/docs/planning/dynamic-mcp-toggle-meta-tools.md
@@ -1,7 +1,7 @@
 # Dynamic MCP Toggling via Meta Tools
 
 **Last Updated:** May 19, 2026
-**Status:** Phase 5 complete — UI surface for session overrides + settings toggle
+**Status:** Feature complete — pending validation + PR
 **Branch:** `feat/dynamic-mcp-toggle-meta-tools`
 **Base branch:** `feat/workspace-root-routing` ([upstream PR #151](https://github.com/mcpmux/mcp-mux/pull/151))
 **Issue:** TBD — file after planning review
@@ -162,8 +162,12 @@ Each write fires `tools/list_changed` per-peer via the existing `MCPNotifier::no
 | [`crates/mcpmux-gateway/src/consumers/mcp_notifier.rs`](../../crates/mcpmux-gateway/src/consumers/mcp_notifier.rs) | In the session-reap pass, also call `SessionOverrideRegistry::remove(session_id)` alongside `SessionRootsRegistry::remove`. |
 | [`crates/mcpmux-core/src/domain/event.rs`](../../crates/mcpmux-core/src/domain/event.rs) | No new variant — `MetaToolInvoked` already carries `decision: String`. Document `"session_override"` as a valid value in the doc comment. |
 | [`apps/desktop/src/features/workspaces/WorkspacesPage.tsx`](../../apps/desktop/src/features/workspaces/WorkspacesPage.tsx) | New "Active session overrides" sub-panel under the live-session inspector: per-session list of enabled / disabled server_ids with a "clear" button. |
-| [`apps/desktop/src-tauri/src/commands/workspace_binding.rs`](../../apps/desktop/src-tauri/src/commands/workspace_binding.rs) | New Tauri commands: `list_session_overrides(session_id)`, `clear_session_overrides(session_id)`. Read-only + clear; mutation happens via the MCP tool, not the UI. |
-| [`apps/desktop/src/lib/api/workspaceBindings.ts`](../../apps/desktop/src/lib/api/workspaceBindings.ts) | TS wrappers for the two new commands. |
+| [`apps/desktop/src-tauri/src/commands/session_overrides.rs`](../../apps/desktop/src-tauri/src/commands/session_overrides.rs) | Tauri commands: `list_session_overrides`, `clear_session_overrides`. Read-only + clear; mutation via MCP tools. |
+| [`apps/desktop/src-tauri/src/commands/settings.rs`](../../apps/desktop/src-tauri/src/commands/settings.rs) | `get/set_session_overrides_require_approval` settings commands. |
+| [`apps/desktop/src-tauri/src/commands/gateway.rs`](../../apps/desktop/src-tauri/src/commands/gateway.rs) | Wire `session_overrides` + `mcp_notifier` into `GatewayAppState` on gateway start. |
+| [`apps/desktop/src/lib/api/sessionOverrides.ts`](../../apps/desktop/src/lib/api/sessionOverrides.ts) | TS wrappers for session override commands + workspace root matching helpers. |
+| [`crates/mcpmux-gateway/src/server/mod.rs`](../../crates/mcpmux-gateway/src/server/mod.rs) | `session_overrides()`, `notification_bridge()` accessors; shared `MCPNotifier` instance. |
+| [`README.md`](../../README.md) | Self-Management Meta Tools feature subsection. |
 
 ---
 
@@ -228,7 +232,7 @@ Each write fires `tools/list_changed` per-peer via the existing `MCPNotifier::no
 
 **Outcome:** Workspace binding gains/loses persistent server-all FeatureSet layers via meta tools.
 
-### Phase 5 — UI surface for session overrides
+### Phase 5 — UI surface for session overrides ✅
 
 **Effort:** 1 day
 
@@ -236,12 +240,31 @@ Each write fires `tools/list_changed` per-peer via the existing `MCPNotifier::no
 - [x] "Clear all overrides" button per session — calls the new `clear_session_overrides` Tauri command. Useful when a session got into a weird state and the user wants a clean default-routing read.
 - [x] New Tauri commands: `list_session_overrides(session_id) -> { enabled: string[], disabled: string[] }`, `clear_session_overrides(session_id)`.
 - [x] Settings checkbox under Gateway settings: "Require approval for session-scope overrides" — wires to `gateway.session_overrides_require_approval`.
-- [ ] README + CHANGELOG entries describing the new meta-tools and the manifest-driven workflow.
+- [x] README section describing the new meta-tools and manifest-driven workflow ([README.md](../../README.md)).
+- [x] CHANGELOG — release-please from conventional `feat(meta-tools):` commits; no manual edit to `CHANGELOG.md`.
 
 **Outcome:** From the Workspaces tab, a user can see at a glance "session abc123 has GitHub enabled (session) and Firebase disabled (session)" and clear them with one click. The new approval-required setting is discoverable in Gateway settings without reading docs.
 
 ---
 
+## Pre-PR validation
+
+Do **not** open a PR until all automated checks pass and the production build is verified manually.
+
+| Step | Command | Purpose |
+| ---- | ------- | ------- |
+| Full validate | `pnpm validate` | fmt, clippy, check, eslint, typecheck |
+| Rust tests | `pnpm test:rust` | unit + integration (`meta_tools.rs`) |
+| TS tests | `pnpm test:ts` | vitest |
+| Production build | `pnpm build` | Tauri build on current platform |
+| Manual smoke (recommended) | Run app, exercise Workspaces overrides panel + Settings toggles | UX verification |
+
+Optional (slow / env-dependent): `pnpm test:e2e`, `pnpm test:e2e:web`.
+
+**PR target:** `feat/workspace-root-routing` (stacked on [PR #151](https://github.com/mcpmux/mcp-mux/pull/151)).
+
+---
+
 ## Out of scope
 
 | Item | Reason |
@@ -283,3 +306,9 @@ Each write fires `tools/list_changed` per-peer via the existing `MCPNotifier::no
 ## Reconciliation
 
 This doc is the source of truth for what gets built. When implementation completes, update the **Status** field at the top and reconcile any deviations (extra files, dropped phases, scope changes) per [`update-planning-md`](~/.cursor/commands/update-planning-md.md).
+
+**May 19, 2026 closeout:**
+- Phases 1–5 implemented on `feat/dynamic-mcp-toggle-meta-tools`.
+- Tauri commands landed in `session_overrides.rs` (not `workspace_binding.rs` as originally planned).
+- CHANGELOG handled by release-please; README updated in-repo.
+- Pre-PR validation gate documented above; PR blocked until validate + tests + build pass.
diff --git a/tests/rust/tests/integration/meta_tools.rs b/tests/rust/tests/integration/meta_tools.rs
index 39215ab4..4e693e2c 100644
--- a/tests/rust/tests/integration/meta_tools.rs
+++ b/tests/rust/tests/integration/meta_tools.rs
@@ -285,11 +285,7 @@ async fn bind_github_only_to_session_root(f: &Fixture) -> String {
     let root = "/tmp/mcpmux-list-servers-test";
     f.session_roots.set_roots_capable(&f.session_id, true);
     f.session_roots.set(&f.session_id, [root]);
-    let binding = WorkspaceBinding::new(
-        normalize_workspace_root(root),
-        f.space_id,
-        fs_id.clone(),
-    );
+    let binding = WorkspaceBinding::new(normalize_workspace_root(root), f.space_id, fs_id.clone());
     f.binding_repo.create(&binding).await.unwrap();
     fs_id
 }
@@ -486,11 +482,7 @@ async fn disable_server_workspace_removes_server_all_from_binding() {
 
     let tools = f
         .feature_service
-        .get_tools_for_grants(
-            &f.space_id.to_string(),
-            &binding.feature_set_ids,
-            None,
-        )
+        .get_tools_for_grants(&f.space_id.to_string(), &binding.feature_set_ids, None)
         .await
         .unwrap();
     assert_eq!(tools.len(), 1);
@@ -502,7 +494,8 @@ async fn enable_server_workspace_requires_binding() {
     let f = Fixture::new().await;
     f.attach_auto_publisher(ApprovalDecision::AllowOnce);
     f.session_roots.set_roots_capable(&f.session_id, true);
-    f.session_roots.set(&f.session_id, ["/tmp/unbound-workspace"]);
+    f.session_roots
+        .set(&f.session_id, ["/tmp/unbound-workspace"]);
 
     let result = f
         .call_tool_as_handler_would(
@@ -992,7 +985,11 @@ async fn session_override_disable_mutes_bound_server() {
 
     let before = f
         .feature_service
-        .get_tools_for_grants(&f.space_id.to_string(), &[fs_id.clone()], Some(&f.session_id))
+        .get_tools_for_grants(
+            &f.space_id.to_string(),
+            &[fs_id.clone()],
+            Some(&f.session_id),
+        )
         .await
         .unwrap();
     assert_eq!(before.len(), 1);
@@ -1021,7 +1018,8 @@ async fn session_override_additive_over_binding() {
         .unwrap();
 
     assert_eq!(tools.len(), 2);
-    let servers: std::collections::HashSet<_> = tools.iter().map(|t| t.server_id.as_str()).collect();
+    let servers: std::collections::HashSet<_> =
+        tools.iter().map(|t| t.server_id.as_str()).collect();
     assert!(servers.contains("github"));
     assert!(servers.contains("firebase"));
 }
diff --git a/tests/rust/tests/oauth/dcr.rs b/tests/rust/tests/oauth/dcr.rs
index d6ca2345..7d132c59 100644
--- a/tests/rust/tests/oauth/dcr.rs
+++ b/tests/rust/tests/oauth/dcr.rs
@@ -71,11 +71,20 @@ fn test_external_https_rejected() {
 }
 
 #[test]
-fn test_mixed_valid_invalid_rejected() {
-    // One invalid URI should fail the whole validation
+fn test_mixed_valid_invalid_skips_invalid() {
+    // Invalid URIs are skipped — clients like Cursor send a mix and only use valid ones.
     let uris = vec![
         "http://127.0.0.1:8080/callback".to_string(),
-        "https://evil.com/steal".to_string(), // invalid
+        "https://evil.com/steal".to_string(),
+    ];
+    assert!(validate_redirect_uris(&uris).is_ok());
+}
+
+#[test]
+fn test_all_invalid_rejected() {
+    let uris = vec![
+        "https://evil.com/steal".to_string(),
+        "http://example.com/callback".to_string(),
     ];
     assert!(validate_redirect_uris(&uris).is_err());
 }
diff --git a/tests/rust/tests/streamable_http/gateway_notifications.rs b/tests/rust/tests/streamable_http/gateway_notifications.rs
index 5c722b53..834e0530 100644
--- a/tests/rust/tests/streamable_http/gateway_notifications.rs
+++ b/tests/rust/tests/streamable_http/gateway_notifications.rs
@@ -581,8 +581,9 @@ async fn test_gateway_content_deduping_prevents_spurious_notifications() {
     let tools_count = client_handler.tools_count.clone();
     let client = connect_client(&gw.url, client_handler).await;
 
-    // Wait for init + hash priming
+    // Wait for init + hash priming (first tools/list may fire one resolution-flip notification)
     tokio::time::sleep(std::time::Duration::from_millis(500)).await;
+    let baseline = tools_count.load(Ordering::SeqCst);
 
     // Emit ToolsChanged WITHOUT changing features (hash stays same)
     gw.emit(DomainEvent::ToolsChanged {
@@ -595,7 +596,7 @@ async fn test_gateway_content_deduping_prevents_spurious_notifications() {
 
     assert_eq!(
         tools_count.load(Ordering::SeqCst),
-        0,
+        baseline,
         "No notification should be sent when features haven't changed (content deduping)"
     );
 

From 726492efc7775c49a8add0361c3e9703d6961734 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Tue, 19 May 2026 10:49:43 -0600
Subject: [PATCH 10/48] feat(ui): add rename/edit for spaces, feature sets, and
 workspace bindings

Expose update_space and editable panels for Spaces and Feature Sets.
Add optional workspace binding labels with migration 016 so folders
can have friendly display names separate from their paths.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 .../src-tauri/src/commands/feature_set.rs     |   4 -
 apps/desktop/src-tauri/src/commands/space.rs  |  54 +++++
 .../src/commands/workspace_binding.rs         |  20 +-
 apps/desktop/src-tauri/src/lib.rs             |   1 +
 .../features/featuresets/FeatureSetPanel.tsx  | 115 ++++++++-
 .../src/features/spaces/SpacePanel.tsx        | 227 ++++++++++++++++++
 .../src/features/spaces/SpacesPage.tsx        |  86 +++----
 .../features/workspaces/WorkspacesPage.tsx    |  82 ++++++-
 apps/desktop/src/lib/api/spaces.ts            |  14 ++
 apps/desktop/src/lib/api/workspaceBindings.ts |   4 +
 .../src/domain/workspace_binding.rs           |   3 +
 .../mcpmux-core/src/service/space_service.rs  |  29 +++
 crates/mcpmux-storage/src/database.rs         |   5 +
 .../016_workspace_binding_label.sql           |   2 +
 .../workspace_binding_repository.rs           |  19 +-
 15 files changed, 592 insertions(+), 73 deletions(-)
 create mode 100644 apps/desktop/src/features/spaces/SpacePanel.tsx
 create mode 100644 crates/mcpmux-storage/src/migrations/016_workspace_binding_label.sql

diff --git a/apps/desktop/src-tauri/src/commands/feature_set.rs b/apps/desktop/src-tauri/src/commands/feature_set.rs
index 7ecd8e82..2f81a7b4 100644
--- a/apps/desktop/src-tauri/src/commands/feature_set.rs
+++ b/apps/desktop/src-tauri/src/commands/feature_set.rs
@@ -263,10 +263,6 @@ pub async fn update_feature_set(
         .map_err(|e| e.to_string())?
         .ok_or("Feature set not found")?;
 
-    if feature_set.is_builtin {
-        return Err("Cannot modify builtin feature set".to_string());
-    }
-
     if let Some(name) = input.name {
         feature_set.name = name;
     }
diff --git a/apps/desktop/src-tauri/src/commands/space.rs b/apps/desktop/src-tauri/src/commands/space.rs
index 7b547878..8d8b3ea2 100644
--- a/apps/desktop/src-tauri/src/commands/space.rs
+++ b/apps/desktop/src-tauri/src/commands/space.rs
@@ -7,6 +7,7 @@
 //! viewing in its own Zustand store (frontend-only state).
 
 use mcpmux_core::Space;
+use serde::Deserialize;
 use std::sync::Arc;
 use tauri::{AppHandle, State};
 use tokio::sync::RwLock;
@@ -103,6 +104,59 @@ pub async fn create_space(
     Ok(space)
 }
 
+/// Partial update payload for a Space (name, icon, description).
+#[derive(Debug, Deserialize)]
+pub struct UpdateSpaceInput {
+    pub name: Option<String>,
+    pub icon: Option<String>,
+    pub description: Option<String>,
+}
+
+/// Update a space's display metadata.
+#[tauri::command]
+pub async fn update_space(
+    id: String,
+    input: UpdateSpaceInput,
+    app: AppHandle,
+    state: State<'_, AppState>,
+    gateway_state: State<'_, Arc<RwLock<GatewayAppState>>>,
+) -> Result<Space, String> {
+    let uuid = Uuid::parse_str(&id).map_err(|e| e.to_string())?;
+
+    let name = input
+        .name
+        .map(|n| n.trim().to_string())
+        .filter(|n| !n.is_empty());
+    let icon = input
+        .icon
+        .map(|i| i.trim().to_string())
+        .filter(|i| !i.is_empty());
+    let description = input.description.map(|d| d.trim().to_string());
+
+    let space = state
+        .space_service
+        .update(uuid, name, icon, description)
+        .await
+        .map_err(|e| e.to_string())?;
+
+    let gw_state = gateway_state.read().await;
+    if let Some(ref gw) = gw_state.gateway_state {
+        let gw = gw.read().await;
+        gw.emit_domain_event(mcpmux_core::DomainEvent::SpaceUpdated {
+            space_id: space.id,
+            name: space.name.clone(),
+        });
+    }
+
+    if let Err(e) = tray::update_tray_spaces(&app, &state).await {
+        warn!("Failed to update tray menu: {}", e);
+    }
+
+    info!("[update_space] Space '{}' updated successfully", space.name);
+
+    Ok(space)
+}
+
 /// Delete a space.
 #[tauri::command]
 pub async fn delete_space(
diff --git a/apps/desktop/src-tauri/src/commands/workspace_binding.rs b/apps/desktop/src-tauri/src/commands/workspace_binding.rs
index 2d5a083c..7615a3d1 100644
--- a/apps/desktop/src-tauri/src/commands/workspace_binding.rs
+++ b/apps/desktop/src-tauri/src/commands/workspace_binding.rs
@@ -54,6 +54,7 @@ async fn emit_binding_changed(
 pub struct WorkspaceBindingDto {
     pub id: String,
     pub workspace_root: String,
+    pub label: Option<String>,
     pub space_id: String,
     pub feature_set_ids: Vec<String>,
     pub created_at: String,
@@ -65,6 +66,7 @@ impl From<WorkspaceBinding> for WorkspaceBindingDto {
         Self {
             id: b.id.to_string(),
             workspace_root: b.workspace_root,
+            label: b.label,
             space_id: b.space_id.to_string(),
             feature_set_ids: b.feature_set_ids,
             created_at: b.created_at.to_rfc3339(),
@@ -80,10 +82,18 @@ impl From<WorkspaceBinding> for WorkspaceBindingDto {
 #[derive(Debug, Deserialize)]
 pub struct WorkspaceBindingInput {
     pub workspace_root: String,
+    pub label: Option<String>,
     pub space_id: String,
     pub feature_set_ids: Vec<String>,
 }
 
+fn normalize_label(label: &Option<String>) -> Option<String> {
+    label
+        .as_ref()
+        .map(|s| s.trim().to_string())
+        .filter(|s| !s.is_empty())
+}
+
 fn parse_space_id(input: &WorkspaceBindingInput) -> Result<Uuid, String> {
     Uuid::parse_str(&input.space_id).map_err(|e| format!("bad space_id: {e}"))
 }
@@ -194,7 +204,8 @@ pub async fn create_workspace_binding(
     let feature_set_ids = validate_fs_list(&input)?;
     let normalized = normalize_and_validate(&input.workspace_root)?;
 
-    let binding = WorkspaceBinding::new_multi(normalized.clone(), space_id, feature_set_ids);
+    let mut binding = WorkspaceBinding::new_multi(normalized.clone(), space_id, feature_set_ids);
+    binding.label = normalize_label(&input.label);
 
     state
         .workspace_binding_repository
@@ -241,9 +252,16 @@ pub async fn update_workspace_binding(
         .ok_or_else(|| format!("binding not found: {}", id))?;
     let old_space_id = existing.space_id;
 
+    let label = if input.label.is_some() {
+        normalize_label(&input.label)
+    } else {
+        existing.label
+    };
+
     let updated = WorkspaceBinding {
         id: existing.id,
         workspace_root: normalized,
+        label,
         space_id,
         feature_set_ids,
         created_at: existing.created_at,
diff --git a/apps/desktop/src-tauri/src/lib.rs b/apps/desktop/src-tauri/src/lib.rs
index bca6e511..70069a04 100644
--- a/apps/desktop/src-tauri/src/lib.rs
+++ b/apps/desktop/src-tauri/src/lib.rs
@@ -848,6 +848,7 @@ pub fn run() {
             commands::list_spaces,
             commands::get_space,
             commands::create_space,
+            commands::update_space,
             commands::delete_space,
             commands::open_space_config_file,
             commands::read_space_config,
diff --git a/apps/desktop/src/features/featuresets/FeatureSetPanel.tsx b/apps/desktop/src/features/featuresets/FeatureSetPanel.tsx
index b9926131..38406dd3 100644
--- a/apps/desktop/src/features/featuresets/FeatureSetPanel.tsx
+++ b/apps/desktop/src/features/featuresets/FeatureSetPanel.tsx
@@ -21,7 +21,11 @@ import {
 } from 'lucide-react';
 import { Button, useToast, ToastContainer, useConfirm } from '@mcpmux/ui';
 import type { FeatureSet, AddMemberInput } from '@/lib/api/featureSets';
-import { isStarterFeatureSet, setFeatureSetMembers } from '@/lib/api/featureSets';
+import {
+  isStarterFeatureSet,
+  setFeatureSetMembers,
+  updateFeatureSet,
+} from '@/lib/api/featureSets';
 import type { ServerFeature } from '@/lib/api/serverFeatures';
 import { listServerFeatures } from '@/lib/api/serverFeatures';
 
@@ -45,6 +49,11 @@ export function FeatureSetPanel({ featureSet, spaceId, onClose, onDelete, onUpda
   const [searchQuery, setSearchQuery] = useState('');
   const [isLoading, setIsLoading] = useState(true);
   const [isSaving, setIsSaving] = useState(false);
+  const [isSavingGeneral, setIsSavingGeneral] = useState(false);
+  const [displayName, setDisplayName] = useState(featureSet.name);
+  const [editName, setEditName] = useState(featureSet.name);
+  const [editDescription, setEditDescription] = useState(featureSet.description ?? '');
+  const [editIcon, setEditIcon] = useState(featureSet.icon ?? '');
   const [error, setError] = useState<string | null>(null);
   const [expandedServers, setExpandedServers] = useState<Set<string>>(new Set());
   const { toasts, success, error: showError, dismiss } = useToast();
@@ -68,6 +77,13 @@ export function FeatureSetPanel({ featureSet, spaceId, onClose, onDelete, onUpda
   const isFeatureSelected = (featureId: string, _feature: ServerFeature) =>
     selectedFeatureIds.has(featureId);
 
+  useEffect(() => {
+    setDisplayName(featureSet.name);
+    setEditName(featureSet.name);
+    setEditDescription(featureSet.description ?? '');
+    setEditIcon(featureSet.icon ?? '');
+  }, [featureSet]);
+
   useEffect(() => {
     const loadFeatures = async () => {
       setIsLoading(true);
@@ -167,6 +183,44 @@ export function FeatureSetPanel({ featureSet, spaceId, onClose, onDelete, onUpda
     });
   };
 
+  /**
+   * Save name, description, and icon from the General Information section.
+   */
+  const handleSaveGeneral = async () => {
+    const trimmedName = editName.trim();
+    if (!trimmedName) {
+      setError('Name is required.');
+      return;
+    }
+
+    setIsSavingGeneral(true);
+    setError(null);
+    try {
+      const updated = await updateFeatureSet(featureSet.id, {
+        name: trimmedName,
+        description: editDescription.trim() || undefined,
+        icon: editIcon.trim() || undefined,
+      });
+      setDisplayName(updated.name);
+      setEditName(updated.name);
+      setEditDescription(updated.description ?? '');
+      setEditIcon(updated.icon ?? '');
+      success('Feature set updated', `"${updated.name}" has been saved`);
+      onUpdate?.();
+    } catch (e) {
+      const errorMsg = e instanceof Error ? e.message : String(e);
+      setError(errorMsg);
+      showError('Failed to save feature set', errorMsg);
+    } finally {
+      setIsSavingGeneral(false);
+    }
+  };
+
+  const hasGeneralChanges =
+    editName.trim() !== featureSet.name ||
+    editDescription.trim() !== (featureSet.description ?? '') ||
+    editIcon.trim() !== (featureSet.icon ?? '');
+
   const handleSave = async () => {
     setIsSaving(true);
     setError(null);
@@ -251,7 +305,7 @@ export function FeatureSetPanel({ featureSet, spaceId, onClose, onDelete, onUpda
             </div>
             <div className="flex-1 min-w-0">
               <h2 className="text-lg font-bold truncate flex items-center gap-2">
-                {featureSet.name}
+                {displayName}
               </h2>
               <div className="flex items-center gap-2 mt-0.5">
                 <span
@@ -327,13 +381,62 @@ export function FeatureSetPanel({ featureSet, spaceId, onClose, onDelete, onUpda
               <div className="p-4 space-y-4 border-t-2 border-[rgb(var(--border))] bg-white dark:bg-[rgb(var(--background))]">
                 <div>
                   <label className="block text-xs font-medium mb-1.5 text-[rgb(var(--muted))]">
-                    Description
+                    Name *
                   </label>
-                  <p className="text-sm">
-                    {featureSet.description || 'No description provided.'}
-                  </p>
+                  <input
+                    type="text"
+                    value={editName}
+                    onChange={(e) => setEditName(e.target.value)}
+                    className="w-full px-3 py-2 text-sm rounded-lg border border-[rgb(var(--border))] bg-[rgb(var(--background))] focus:outline-none focus:ring-2 focus:ring-primary-500"
+                    data-testid="featureset-panel-name"
+                  />
                 </div>
+
                 
+                <div>
+                  <label className="block text-xs font-medium mb-1.5 text-[rgb(var(--muted))]">
+                    Description
+                  </label>
+                  <input
+                    type="text"
+                    value={editDescription}
+                    onChange={(e) => setEditDescription(e.target.value)}
+                    placeholder="What this feature set allows..."
+                    className="w-full px-3 py-2 text-sm rounded-lg border border-[rgb(var(--border))] bg-[rgb(var(--background))] focus:outline-none focus:ring-2 focus:ring-primary-500"
+                    data-testid="featureset-panel-description"
+                  />
+                </div>
+
+                <div>
+                  <label className="block text-xs font-medium mb-1.5 text-[rgb(var(--muted))]">
+                    Icon (emoji)
+                  </label>
+                  <input
+                    type="text"
+                    value={editIcon}
+                    onChange={(e) => setEditIcon(e.target.value)}
+                    placeholder="🔧"
+                    maxLength={2}
+                    className="w-full px-3 py-2 text-sm rounded-lg border border-[rgb(var(--border))] bg-[rgb(var(--background))] focus:outline-none focus:ring-2 focus:ring-primary-500"
+                    data-testid="featureset-panel-icon"
+                  />
+                </div>
+
+                <Button
+                  variant="primary"
+                  size="sm"
+                  onClick={() => void handleSaveGeneral()}
+                  disabled={isSavingGeneral || !editName.trim() || !hasGeneralChanges}
+                  data-testid="featureset-panel-save-general"
+                >
+                  {isSavingGeneral ? (
+                    <Loader2 className="h-4 w-4 animate-spin mr-2" />
+                  ) : (
+                    <Save className="h-4 w-4 mr-2" />
+                  )}
+                  Save
+                </Button>
+
                 {isStarter && (
                   <div className="p-3 bg-yellow-50 dark:bg-yellow-900/10 border border-yellow-200 dark:border-yellow-800 rounded-lg">
                     <div className="flex gap-2">
diff --git a/apps/desktop/src/features/spaces/SpacePanel.tsx b/apps/desktop/src/features/spaces/SpacePanel.tsx
new file mode 100644
index 00000000..eedd345d
--- /dev/null
+++ b/apps/desktop/src/features/spaces/SpacePanel.tsx
@@ -0,0 +1,227 @@
+import { useEffect, useState } from 'react';
+import { Loader2, Save, Trash2, X } from 'lucide-react';
+import { Button, useConfirm, useToast, ToastContainer } from '@mcpmux/ui';
+import type { Space } from '@/lib/api/spaces';
+import { deleteSpace, updateSpace } from '@/lib/api/spaces';
+
+const SPACE_ICON_OPTIONS = ['🌐', '💻', '🚀', '🏢', '🏠', '🔒', '🧪', '📦'] as const;
+
+export interface SpacePanelProps {
+  space: Space;
+  onClose: () => void;
+  onSaved: (space: Space) => void;
+  onDeleted: (id: string) => void;
+}
+
+/**
+ * Slide-out panel for editing a Space's display metadata (name, icon, description).
+ */
+export function SpacePanel({ space, onClose, onSaved, onDeleted }: SpacePanelProps) {
+  const [name, setName] = useState(space.name);
+  const [icon, setIcon] = useState(space.icon ?? '🌐');
+  const [description, setDescription] = useState(space.description ?? '');
+  const [isSaving, setIsSaving] = useState(false);
+  const [isDeleting, setIsDeleting] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const { toasts, success, error: showError, dismiss } = useToast();
+  const { confirm, ConfirmDialogElement } = useConfirm();
+
+  useEffect(() => {
+    setName(space.name);
+    setIcon(space.icon ?? '🌐');
+    setDescription(space.description ?? '');
+    setError(null);
+  }, [space]);
+
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose();
+    };
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [onClose]);
+
+  /**
+   * Persist name, icon, and description to the backend and notify the parent.
+   */
+  const handleSave = async () => {
+    const trimmedName = name.trim();
+    if (!trimmedName) {
+      setError('Name is required.');
+      return;
+    }
+
+    setIsSaving(true);
+    setError(null);
+    try {
+      const updated = await updateSpace(space.id, {
+        name: trimmedName,
+        icon: icon.trim() || undefined,
+        description: description.trim() || undefined,
+      });
+      success('Space updated', `"${updated.name}" has been saved`);
+      onSaved(updated);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      setError(msg);
+      showError('Failed to save space', msg);
+    } finally {
+      setIsSaving(false);
+    }
+  };
+
+  /**
+   * Delete this Space after confirmation (default Space cannot be deleted).
+   */
+  const handleDelete = async () => {
+    const ok = await confirm({
+      title: 'Delete workspace',
+      message: `Are you sure you want to delete "${space.name}"? This action cannot be undone.`,
+      confirmLabel: 'Delete',
+      variant: 'danger',
+    });
+    if (!ok) return;
+
+    setIsDeleting(true);
+    try {
+      await deleteSpace(space.id);
+      success('Space deleted', `"${space.name}" has been deleted`);
+      onDeleted(space.id);
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      showError('Failed to delete space', msg);
+    } finally {
+      setIsDeleting(false);
+    }
+  };
+
+  const hasChanges =
+    name.trim() !== space.name ||
+    (icon.trim() || '🌐') !== (space.icon ?? '🌐') ||
+    description.trim() !== (space.description ?? '');
+
+  return (
+    <div
+      className="fixed right-0 top-0 bottom-0 w-full max-w-[480px] min-w-[420px] bg-[rgb(var(--surface))] border-l border-[rgb(var(--border))] shadow-2xl flex flex-col animate-in slide-in-from-right duration-300 z-50"
+      data-testid="space-panel"
+    >
+      <ToastContainer toasts={toasts} onClose={dismiss} />
+      {ConfirmDialogElement}
+
+      <div className="flex-shrink-0 p-4 border-b border-[rgb(var(--border))] bg-[rgb(var(--surface-elevated))]">
+        <div className="flex items-start justify-between">
+          <div className="flex items-center gap-3 flex-1 min-w-0">
+            <div className="w-11 h-11 flex items-center justify-center bg-[rgb(var(--background))] rounded-lg text-xl border border-[rgb(var(--border-subtle))] flex-shrink-0">
+              {icon}
+            </div>
+            <div className="flex-1 min-w-0">
+              <h2 className="text-lg font-bold truncate">{space.name}</h2>
+              {space.is_default && (
+                <span className="inline-flex mt-1 px-2 py-0.5 rounded-full text-xs font-medium bg-blue-100 dark:bg-blue-900/30 text-blue-700 dark:text-blue-400">
+                  Default
+                </span>
+              )}
+            </div>
+          </div>
+          <button
+            type="button"
+            onClick={onClose}
+            className="p-1.5 rounded-lg hover:bg-[rgb(var(--surface-hover))] transition-colors flex-shrink-0"
+            aria-label="Close panel"
+            data-testid="space-panel-close"
+          >
+            <X className="h-5 w-5" />
+          </button>
+        </div>
+      </div>
+
+      <div className="flex-1 overflow-y-auto p-6 space-y-5">
+        {error && (
+          <p className="text-sm text-red-600 dark:text-red-400" role="alert">
+            {error}
+          </p>
+        )}
+
+        <div>
+          <label className="block text-xs font-semibold uppercase tracking-wide text-[rgb(var(--muted))] mb-2">
+            Icon
+          </label>
+          <div className="flex gap-2 flex-wrap">
+            {SPACE_ICON_OPTIONS.map((emoji) => (
+              <button
+                key={emoji}
+                type="button"
+                onClick={() => setIcon(emoji)}
+                className={`w-10 h-10 flex items-center justify-center rounded-lg text-xl border transition-all ${
+                  icon === emoji
+                    ? 'bg-primary-50 dark:bg-primary-900/20 border-primary-500 ring-2 ring-primary-500/20'
+                    : 'bg-[rgb(var(--surface))] border-[rgb(var(--border))] hover:bg-[rgb(var(--surface-hover))]'
+                }`}
+              >
+                {emoji}
+              </button>
+            ))}
+          </div>
+        </div>
+
+        <div>
+          <label className="block text-xs font-semibold uppercase tracking-wide text-[rgb(var(--muted))] mb-2">
+            Name *
+          </label>
+          <input
+            type="text"
+            value={name}
+            onChange={(e) => setName(e.target.value)}
+            className="w-full px-3 py-2 rounded-lg border border-[rgb(var(--border))] bg-[rgb(var(--background))] focus:outline-none focus:ring-2 focus:ring-primary-500"
+            data-testid="space-panel-name"
+          />
+        </div>
+
+        <div>
+          <label className="block text-xs font-semibold uppercase tracking-wide text-[rgb(var(--muted))] mb-2">
+            Description
+          </label>
+          <input
+            type="text"
+            value={description}
+            onChange={(e) => setDescription(e.target.value)}
+            placeholder="Optional description for this workspace"
+            className="w-full px-3 py-2 rounded-lg border border-[rgb(var(--border))] bg-[rgb(var(--background))] focus:outline-none focus:ring-2 focus:ring-primary-500"
+            data-testid="space-panel-description"
+          />
+        </div>
+      </div>
+
+      <div className="flex-shrink-0 p-4 border-t border-[rgb(var(--border))] bg-[rgb(var(--surface-elevated))] flex flex-col gap-2">
+        <Button
+          variant="primary"
+          size="md"
+          onClick={() => void handleSave()}
+          disabled={isSaving || !name.trim() || !hasChanges}
+          className="w-full"
+          data-testid="space-panel-save"
+        >
+          {isSaving ? (
+            <Loader2 className="h-4 w-4 animate-spin mr-2" />
+          ) : (
+            <Save className="h-4 w-4 mr-2" />
+          )}
+          Save Changes
+        </Button>
+        {!space.is_default && (
+          <Button
+            variant="ghost"
+            size="sm"
+            onClick={() => void handleDelete()}
+            disabled={isDeleting || isSaving}
+            className="w-full text-red-600 hover:text-red-700 hover:bg-red-50 dark:hover:bg-red-900/20"
+            data-testid="space-panel-delete"
+          >
+            <Trash2 className="h-4 w-4 mr-2" />
+            Delete Space
+          </Button>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/apps/desktop/src/features/spaces/SpacesPage.tsx b/apps/desktop/src/features/spaces/SpacesPage.tsx
index 3521614f..ed4bd1ee 100644
--- a/apps/desktop/src/features/spaces/SpacesPage.tsx
+++ b/apps/desktop/src/features/spaces/SpacesPage.tsx
@@ -1,5 +1,5 @@
 import { useState } from 'react';
-import { Plus, Trash2, Loader2, Search, Layout, AlertCircle } from 'lucide-react';
+import { Plus, Loader2, Search, Layout, AlertCircle, Pencil } from 'lucide-react';
 import {
   Card,
   CardHeader,
@@ -11,7 +11,8 @@ import {
   useConfirm,
 } from '@mcpmux/ui';
 import { useAppStore, useSpaces, useIsLoading } from '@/stores';
-import { createSpace, deleteSpace } from '@/lib/api/spaces';
+import { createSpace } from '@/lib/api/spaces';
+import { SpacePanel } from './SpacePanel';
 
 export function SpacesPage() {
   const spaces = useSpaces();
@@ -20,12 +21,12 @@ export function SpacesPage() {
   // Store actions
   const addSpace = useAppStore((state) => state.addSpace);
   const removeSpace = useAppStore((state) => state.removeSpace);
+  const updateSpaceInStore = useAppStore((state) => state.updateSpace);
 
   // Local state
   const [searchQuery, setSearchQuery] = useState('');
   const [error, setError] = useState<string | null>(null);
-  const [isActionLoading, setIsActionLoading] = useState<string | null>(null); // ID of space being acted on
-  const { confirm, ConfirmDialogElement } = useConfirm();
+  const { ConfirmDialogElement } = useConfirm();
   const { toasts, success, error: showError, dismiss } = useToast();
 
   // Create Modal State
@@ -33,6 +34,7 @@ export function SpacesPage() {
   const [newSpaceName, setNewSpaceName] = useState('');
   const [newSpaceIcon, setNewSpaceIcon] = useState('🌐');
   const [isCreating, setIsCreating] = useState(false);
+  const [selectedSpaceId, setSelectedSpaceId] = useState<string | null>(null);
 
   const handleCreate = async () => {
     if (!newSpaceName.trim()) return;
@@ -55,30 +57,9 @@ export function SpacesPage() {
     }
   };
 
-  const handleDelete = async (id: string) => {
-    const spaceName = spaces.find(s => s.id === id)?.name || 'this space';
-    if (!await confirm({
-      title: 'Delete workspace',
-      message: `Are you sure you want to delete "${spaceName}"? This action cannot be undone.`,
-      confirmLabel: 'Delete',
-      variant: 'danger',
-    })) return;
-    
-    setIsActionLoading(id);
-    setError(null);
-    try {
-      const deletedSpace = spaces.find(s => s.id === id);
-      await deleteSpace(id);
-      removeSpace(id);
-      success('Space deleted', `"${deletedSpace?.name || 'Space'}" has been deleted`);
-    } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
-      setError(msg);
-      showError('Failed to delete space', msg);
-    } finally {
-      setIsActionLoading(null);
-    }
-  };
+  const selectedSpace = selectedSpaceId
+    ? spaces.find((s) => s.id === selectedSpaceId) ?? null
+    : null;
 
   // Filter spaces
   const filteredSpaces = spaces.filter(space => {
@@ -166,16 +147,19 @@ export function SpacesPage() {
           ) : (
             <div className="grid gap-5 auto-fill-cards">
               {filteredSpaces.map((space) => {
-                const isProcessing = isActionLoading === space.id;
+                const isSelected = selectedSpaceId === space.id;
 
                 return (
                   <Card
                     key={space.id}
-                    className="transition-all hover:shadow-lg hover:scale-[1.01]"
+                    className={`cursor-pointer transition-all hover:shadow-lg hover:scale-[1.01] group ${
+                      isSelected ? 'ring-2 ring-primary-500 shadow-lg' : ''
+                    }`}
+                    onClick={() => setSelectedSpaceId(space.id)}
                     data-testid={`space-card-${space.id}`}
                   >
                     <CardContent className="p-4">
-                      <div className="flex items-start gap-2.5 mb-3">
+                      <div className="flex items-start gap-2.5">
                         <div className="w-9 h-9 flex items-center justify-center bg-[rgb(var(--surface))] rounded-lg text-xl border border-[rgb(var(--border-subtle))] flex-shrink-0">
                           {space.icon || '🌐'}
                         </div>
@@ -185,7 +169,7 @@ export function SpacesPage() {
                             {space.description || 'No description'}
                           </p>
                         </div>
-                        <div className="flex gap-1 flex-shrink-0">
+                        <div className="flex gap-1 flex-shrink-0 items-start">
                           {space.is_default && (
                             <span
                               className="inline-flex items-center gap-1 px-2 py-0.5 rounded-full text-xs font-medium bg-blue-100 dark:bg-blue-900/30 text-blue-700 dark:text-blue-400"
@@ -194,17 +178,12 @@ export function SpacesPage() {
                               Default
                             </span>
                           )}
-                          {!space.is_default && (
-                            <button
-                              onClick={() => handleDelete(space.id)}
-                              disabled={isProcessing}
-                              className="p-1.5 text-[rgb(var(--muted))] hover:text-red-500 hover:bg-red-50 dark:hover:bg-red-900/20 rounded-lg transition-colors disabled:opacity-50 disabled:cursor-not-allowed"
-                              title="Delete Space"
-                              data-testid={`delete-space-${space.id}`}
-                            >
-                              <Trash2 className="h-4 w-4" />
-                            </button>
-                          )}
+                          <span
+                            className="p-1.5 text-[rgb(var(--muted))] opacity-0 group-hover:opacity-100 transition-opacity"
+                            title="Edit workspace"
+                          >
+                            <Pencil className="h-4 w-4" />
+                          </span>
                         </div>
                       </div>
                     </CardContent>
@@ -216,6 +195,27 @@ export function SpacesPage() {
         </div>
       </div>
 
+      {selectedSpace && (
+        <>
+          <div
+            className="fixed inset-0 bg-black/20 backdrop-blur-[2px] z-40 animate-in fade-in duration-200"
+            onClick={() => setSelectedSpaceId(null)}
+          />
+          <SpacePanel
+            space={selectedSpace}
+            onClose={() => setSelectedSpaceId(null)}
+            onSaved={(updated) => {
+              updateSpaceInStore(updated.id, updated);
+              setSelectedSpaceId(updated.id);
+            }}
+            onDeleted={(id) => {
+              removeSpace(id);
+              setSelectedSpaceId(null);
+            }}
+          />
+        </>
+      )}
+
       {/* Create Modal */}
       {showCreateModal && (
         <div className="fixed inset-0 bg-black/50 flex items-center justify-center z-50" data-testid="create-space-modal-overlay">
diff --git a/apps/desktop/src/features/workspaces/WorkspacesPage.tsx b/apps/desktop/src/features/workspaces/WorkspacesPage.tsx
index cda9b4e0..f99d64e5 100644
--- a/apps/desktop/src/features/workspaces/WorkspacesPage.tsx
+++ b/apps/desktop/src/features/workspaces/WorkspacesPage.tsx
@@ -234,8 +234,10 @@ export function WorkspacesPage() {
             .map((id) => fsById.get(id)?.name ?? '')
             .join(' ')
         : '';
+      const label = e.binding?.label?.toLowerCase() ?? '';
       return (
         e.root.toLowerCase().includes(q) ||
+        label.includes(q) ||
         spaceName.toLowerCase().includes(q) ||
         fsNames.toLowerCase().includes(q)
       );
@@ -469,11 +471,31 @@ function formatFsList(names: string[]): string {
  * a no-op edit. `feature_set_ids` order matters (it's the operator-
  * chosen render order, not just a set), so we compare positionally.
  */
+function normalizeLabel(label: string | null | undefined): string | null {
+  const trimmed = label?.trim() ?? '';
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+/**
+ * Primary title for a workspace entry — label when set, otherwise the path.
+ */
+function entryDisplayTitle(entry: Entry): string {
+  const label = entry.binding?.label?.trim();
+  if (label) return label;
+  return entry.root;
+}
+
 function sameBindingInput(
   a: WorkspaceBindingInput,
-  b: { workspace_root: string; space_id: string; feature_set_ids: string[] }
+  b: {
+    workspace_root: string;
+    label?: string | null;
+    space_id: string;
+    feature_set_ids: string[];
+  }
 ): boolean {
   if (a.workspace_root.trim() !== b.workspace_root.trim()) return false;
+  if (normalizeLabel(a.label) !== normalizeLabel(b.label)) return false;
   if (a.space_id !== b.space_id) return false;
   if (a.feature_set_ids.length !== b.feature_set_ids.length) return false;
   return a.feature_set_ids.every((id, i) => id === b.feature_set_ids[i]);
@@ -584,11 +606,18 @@ function EntryCard({
               {entry.kind === 'mapped-live' && <Pill tone="emerald">Live</Pill>}
             </div>
             <p
-              className="font-mono text-sm text-[rgb(var(--foreground))] truncate"
-              title={entry.root}
+              className={`text-sm text-[rgb(var(--foreground))] truncate ${
+                entry.binding?.label?.trim() ? 'font-semibold' : 'font-mono'
+              }`}
+              title={entryDisplayTitle(entry)}
             >
-              {entry.root}
+              {entryDisplayTitle(entry)}
             </p>
+            {entry.binding?.label?.trim() && (
+              <p className="font-mono text-xs text-[rgb(var(--muted))] truncate mt-0.5" title={entry.root}>
+                {entry.root}
+              </p>
+            )}
           </div>
         </div>
 
@@ -833,9 +862,12 @@ function InspectorPanel({
       ? 'edit'
       : 'create-from-live';
   const title = isNew ? 'New binding' : isMapped ? 'Binding' : 'Configure workspace';
+  const displayTitle = entry ? entryDisplayTitle(entry) : '';
   const subtitle = isNew
     ? 'Tell mcpmux how a folder should route.'
-    : entry?.root ?? '';
+    : displayTitle !== entry?.root
+      ? entry?.root ?? ''
+      : displayTitle;
 
   // Auto-save status drives the small pill in the Mapping section header.
   const [saveStatus, setSaveStatus] = useState<SaveStatus>({ kind: 'idle' });
@@ -858,13 +890,20 @@ function InspectorPanel({
                 {!isNew && entry && !isMapped && <Pill tone="amber">Unmapped</Pill>}
                 {!isNew && entry && isMapped && !entry.isLive && <Pill tone="neutral">Offline</Pill>}
               </div>
-              <h2 className="text-lg font-bold truncate">{title}</h2>
-              <p
-                className={`text-xs text-[rgb(var(--muted))] truncate ${!isNew ? 'font-mono' : ''}`}
-                title={subtitle}
-              >
-                {subtitle}
-              </p>
+              <h2 className="text-lg font-bold truncate" title={displayTitle || title}>
+                {!isNew && entry ? displayTitle : title}
+              </h2>
+              {!isNew && entry && displayTitle !== entry.root && (
+                <p
+                  className="text-xs text-[rgb(var(--muted))] truncate font-mono"
+                  title={entry.root}
+                >
+                  {entry.root}
+                </p>
+              )}
+              {isNew && (
+                <p className="text-xs text-[rgb(var(--muted))] truncate">{subtitle}</p>
+              )}
             </div>
           </div>
           <button
@@ -1708,6 +1747,7 @@ function BindingForm({
 
   const rootRef = useRef<HTMLInputElement | null>(null);
   const [root, setRoot] = useState(initial?.workspace_root ?? prefillRoot ?? '');
+  const [label, setLabel] = useState(initial?.label ?? '');
   const [spaceId, setSpaceId] = useState<string>(initial?.space_id ?? defaultSpaceId);
   // Multi-FS: a binding may resolve to N FeatureSets (the resolver merges
   // their members into one allow set). Order is preserved so the operator
@@ -1836,6 +1876,7 @@ function BindingForm({
     try {
       await onSubmit({
         workspace_root: root.trim(),
+        label: label.trim() || null,
         space_id: spaceId,
         feature_set_ids: fsIds,
       });
@@ -1887,6 +1928,7 @@ function BindingForm({
 
     const candidate: WorkspaceBindingInput = {
       workspace_root: root.trim(),
+      label: label.trim() || null,
       space_id: spaceId,
       feature_set_ids: fsIds,
     };
@@ -1895,6 +1937,7 @@ function BindingForm({
     // otherwise the initial payload from when the panel opened.
     const baseline = lastSavedRef.current ?? {
       workspace_root: initial.workspace_root,
+      label: initial.label,
       space_id: initial.space_id,
       feature_set_ids: initial.feature_set_ids,
     };
@@ -1934,6 +1977,7 @@ function BindingForm({
     isEdit,
     initial,
     root,
+    label,
     spaceId,
     fsIds,
     canSubmit,
@@ -1977,6 +2021,20 @@ function BindingForm({
 
   return (
     <div className="space-y-5">
+      <FormField
+        label="Label"
+        hint="Friendly name shown instead of the folder path (optional)."
+      >
+        <input
+          type="text"
+          value={label}
+          onChange={(e) => setLabel(e.target.value)}
+          placeholder="e.g., Frontend project"
+          className="w-full px-3 py-2 rounded-lg text-sm bg-[rgb(var(--background))] border border-[rgb(var(--border))] focus:outline-none focus:ring-2 focus:ring-primary-500"
+          data-testid="workspace-binding-label-input"
+        />
+      </FormField>
+
       <FormField label="Workspace root">
         <div className="flex gap-2">
           <input
diff --git a/apps/desktop/src/lib/api/spaces.ts b/apps/desktop/src/lib/api/spaces.ts
index 625df98c..40e446e5 100644
--- a/apps/desktop/src/lib/api/spaces.ts
+++ b/apps/desktop/src/lib/api/spaces.ts
@@ -30,6 +30,20 @@ export async function createSpace(name: string, icon?: string): Promise<Space> {
   return invoke('create_space', { name, icon });
 }
 
+/** Partial update payload for a Space. */
+export interface UpdateSpaceInput {
+  name?: string;
+  icon?: string;
+  description?: string;
+}
+
+/**
+ * Update a Space's display metadata (name, icon, description).
+ */
+export async function updateSpace(id: string, input: UpdateSpaceInput): Promise<Space> {
+  return invoke('update_space', { id, input });
+}
+
 export async function deleteSpace(id: string): Promise<void> {
   return invoke('delete_space', { id });
 }
diff --git a/apps/desktop/src/lib/api/workspaceBindings.ts b/apps/desktop/src/lib/api/workspaceBindings.ts
index cc23dbfd..2f2ad669 100644
--- a/apps/desktop/src/lib/api/workspaceBindings.ts
+++ b/apps/desktop/src/lib/api/workspaceBindings.ts
@@ -10,6 +10,8 @@ import { invoke } from '@tauri-apps/api/core';
 export interface WorkspaceBinding {
   id: string;
   workspace_root: string;
+  /** Friendly display name shown instead of the folder path when set. */
+  label: string | null;
   space_id: string;
   /**
    * Non-empty by construction. Order is the operator-chosen rendering
@@ -24,6 +26,7 @@ export interface WorkspaceBinding {
 /** Input payload for create / update. `feature_set_ids` must be non-empty. */
 export interface WorkspaceBindingInput {
   workspace_root: string;
+  label?: string | null;
   space_id: string;
   feature_set_ids: string[];
 }
@@ -91,6 +94,7 @@ export async function deleteWorkspaceBinding(id: string): Promise<void> {
 export function toInput(b: WorkspaceBinding): WorkspaceBindingInput {
   return {
     workspace_root: b.workspace_root,
+    label: b.label,
     space_id: b.space_id,
     feature_set_ids: b.feature_set_ids,
   };
diff --git a/crates/mcpmux-core/src/domain/workspace_binding.rs b/crates/mcpmux-core/src/domain/workspace_binding.rs
index a816cc17..495ed327 100644
--- a/crates/mcpmux-core/src/domain/workspace_binding.rs
+++ b/crates/mcpmux-core/src/domain/workspace_binding.rs
@@ -32,6 +32,8 @@ use uuid::Uuid;
 pub struct WorkspaceBinding {
     pub id: Uuid,
     pub workspace_root: String,
+    /// Optional friendly display name shown in the UI instead of the path.
+    pub label: Option<String>,
     pub space_id: Uuid,
     /// Order matters for UI rendering only — the resolver treats them as
     /// a set. Stored in the `workspace_binding_feature_sets` junction
@@ -63,6 +65,7 @@ impl WorkspaceBinding {
         Self {
             id: Uuid::new_v4(),
             workspace_root: workspace_root.into(),
+            label: None,
             space_id,
             feature_set_ids,
             created_at: now,
diff --git a/crates/mcpmux-core/src/service/space_service.rs b/crates/mcpmux-core/src/service/space_service.rs
index b5af6926..d28ef034 100644
--- a/crates/mcpmux-core/src/service/space_service.rs
+++ b/crates/mcpmux-core/src/service/space_service.rs
@@ -80,6 +80,35 @@ impl SpaceService {
         Ok(space)
     }
 
+    /// Update a space's display metadata (name, icon, description).
+    pub async fn update(
+        &self,
+        id: Uuid,
+        name: Option<String>,
+        icon: Option<String>,
+        description: Option<String>,
+    ) -> anyhow::Result<Space> {
+        let mut space = self
+            .repository
+            .get(&id)
+            .await?
+            .ok_or_else(|| anyhow::anyhow!("Space not found"))?;
+
+        if let Some(name) = name {
+            space.name = name;
+        }
+        if let Some(icon) = icon {
+            space.icon = Some(icon);
+        }
+        if let Some(description) = description {
+            space.description = Some(description);
+        }
+        space.updated_at = chrono::Utc::now();
+
+        self.repository.update(&space).await?;
+        Ok(space)
+    }
+
     /// Delete a space
     pub async fn delete(&self, id: &Uuid) -> anyhow::Result<()> {
         let space = self.repository.get(id).await?;
diff --git a/crates/mcpmux-storage/src/database.rs b/crates/mcpmux-storage/src/database.rs
index bb6fc021..1ae76ab2 100644
--- a/crates/mcpmux-storage/src/database.rs
+++ b/crates/mcpmux-storage/src/database.rs
@@ -108,6 +108,11 @@ const MIGRATIONS: &[Migration] = &[
         name: "rewrite_starter_seed_copy_v2",
         sql: include_str!("migrations/015_rewrite_starter_seed_copy_v2.sql"),
     },
+    Migration {
+        version: 16,
+        name: "workspace_binding_label",
+        sql: include_str!("migrations/016_workspace_binding_label.sql"),
+    },
 ];
 
 /// SQLite database wrapper.
diff --git a/crates/mcpmux-storage/src/migrations/016_workspace_binding_label.sql b/crates/mcpmux-storage/src/migrations/016_workspace_binding_label.sql
new file mode 100644
index 00000000..8e68ad92
--- /dev/null
+++ b/crates/mcpmux-storage/src/migrations/016_workspace_binding_label.sql
@@ -0,0 +1,2 @@
+-- Optional friendly display name for workspace bindings (separate from workspace_root).
+ALTER TABLE workspace_bindings ADD COLUMN label TEXT;
diff --git a/crates/mcpmux-storage/src/repositories/workspace_binding_repository.rs b/crates/mcpmux-storage/src/repositories/workspace_binding_repository.rs
index 7f3df1a3..22e5f3f3 100644
--- a/crates/mcpmux-storage/src/repositories/workspace_binding_repository.rs
+++ b/crates/mcpmux-storage/src/repositories/workspace_binding_repository.rs
@@ -62,13 +62,15 @@ impl SqliteWorkspaceBindingRepository {
     fn row_to_binding_no_fs(row: &rusqlite::Row<'_>) -> rusqlite::Result<WorkspaceBinding> {
         let id_str: String = row.get(0)?;
         let workspace_root: String = row.get(1)?;
-        let space_id_str: String = row.get(2)?;
-        let created_at: String = row.get(3)?;
-        let updated_at: String = row.get(4)?;
+        let label: Option<String> = row.get(2)?;
+        let space_id_str: String = row.get(3)?;
+        let created_at: String = row.get(4)?;
+        let updated_at: String = row.get(5)?;
 
         Ok(WorkspaceBinding {
             id: id_str.parse().unwrap_or_else(|_| Uuid::new_v4()),
             workspace_root,
+            label,
             space_id: space_id_str.parse().unwrap_or_else(|_| Uuid::nil()),
             feature_set_ids: Vec::new(), // filled in by caller
             created_at: Self::parse_datetime(&created_at),
@@ -138,7 +140,8 @@ impl SqliteWorkspaceBindingRepository {
         Ok(())
     }
 
-    const SELECT_COLS: &'static str = "id, workspace_root, space_id, created_at, updated_at";
+    const SELECT_COLS: &'static str =
+        "id, workspace_root, label, space_id, created_at, updated_at";
 
     /// Fetch bindings + their FeatureSet lists in two queries.
     /// `where_clause` is appended to the binding SELECT (use `""` for none);
@@ -209,11 +212,12 @@ impl WorkspaceBindingRepository for SqliteWorkspaceBindingRepository {
 
         conn.execute(
             "INSERT INTO workspace_bindings
-                (id, workspace_root, space_id, created_at, updated_at)
-             VALUES (?1, ?2, ?3, ?4, ?5)",
+                (id, workspace_root, label, space_id, created_at, updated_at)
+             VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
             params![
                 binding.id.to_string(),
                 binding.workspace_root,
+                binding.label,
                 binding.space_id.to_string(),
                 binding.created_at.to_rfc3339(),
                 binding.updated_at.to_rfc3339(),
@@ -236,11 +240,12 @@ impl WorkspaceBindingRepository for SqliteWorkspaceBindingRepository {
 
         let rows_affected = conn.execute(
             "UPDATE workspace_bindings
-             SET workspace_root = ?2, space_id = ?3, updated_at = ?4
+             SET workspace_root = ?2, label = ?3, space_id = ?4, updated_at = ?5
              WHERE id = ?1",
             params![
                 binding.id.to_string(),
                 binding.workspace_root,
+                binding.label,
                 binding.space_id.to_string(),
                 binding.updated_at.to_rfc3339(),
             ],

From 11814c46354cd458194759c0583e17e7d2e82102 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Tue, 19 May 2026 10:55:23 -0600
Subject: [PATCH 11/48] feat(ui): link dashboard stat cards to detail pages

Add Rust unit tests for workspace binding labels, label normalization,
and SpaceService::update.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 .../src/commands/workspace_binding.rs         |  20 +++
 apps/desktop/src/App.tsx                      |  64 ++++++++-
 .../mcpmux-core/src/service/space_service.rs  | 123 ++++++++++++++++++
 .../workspace_binding_repository.rs           |  25 ++++
 4 files changed, 228 insertions(+), 4 deletions(-)

diff --git a/apps/desktop/src-tauri/src/commands/workspace_binding.rs b/apps/desktop/src-tauri/src/commands/workspace_binding.rs
index 7615a3d1..b1c1fcc9 100644
--- a/apps/desktop/src-tauri/src/commands/workspace_binding.rs
+++ b/apps/desktop/src-tauri/src/commands/workspace_binding.rs
@@ -713,3 +713,23 @@ pub async fn get_workspace_effective_features(
         server_totals,
     })
 }
+
+#[cfg(test)]
+mod tests {
+    use super::normalize_label;
+
+    #[test]
+    fn normalize_label_none_and_empty() {
+        assert_eq!(normalize_label(&None), None);
+        assert_eq!(normalize_label(&Some(String::new())), None);
+        assert_eq!(normalize_label(&Some("   ".to_string())), None);
+    }
+
+    #[test]
+    fn normalize_label_trims_non_empty() {
+        assert_eq!(
+            normalize_label(&Some("  My Project  ".to_string())),
+            Some("My Project".to_string())
+        );
+    }
+}
diff --git a/apps/desktop/src/App.tsx b/apps/desktop/src/App.tsx
index aab0aaaf..cd953cb8 100644
--- a/apps/desktop/src/App.tsx
+++ b/apps/desktop/src/App.tsx
@@ -390,6 +390,7 @@ function App() {
 }
 
 function DashboardView() {
+  const navigateTo = useNavigateTo();
   const [stats, setStats] = useState({
     installedServers: 0,
     connectedServers: 0,
@@ -399,6 +400,9 @@ function DashboardView() {
   });
   const viewSpace = useViewSpace();
 
+  const statCardClass =
+    'cursor-pointer transition-all hover:shadow-lg hover:scale-[1.01] focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-primary-500/50';
+
   // Load stats on mount and when gateway changes
   const loadStats = async () => {
     try {
@@ -460,7 +464,20 @@ function DashboardView() {
 
       {/* Stats Grid */}
       <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4" data-testid="dashboard-stats-grid">
-        <Card data-testid="stat-servers">
+        <Card
+          className={statCardClass}
+          data-testid="stat-servers"
+          role="button"
+          tabIndex={0}
+          aria-label="Go to Servers"
+          onClick={() => navigateTo('servers')}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter' || e.key === ' ') {
+              e.preventDefault();
+              navigateTo('servers');
+            }
+          }}
+        >
           <CardHeader>
             <CardTitle className="flex items-center gap-2 text-base">
               <Server className="h-5 w-5 text-primary-500" />
@@ -473,7 +490,20 @@ function DashboardView() {
           </CardContent>
         </Card>
 
-        <Card data-testid="stat-featuresets">
+        <Card
+          className={statCardClass}
+          data-testid="stat-featuresets"
+          role="button"
+          tabIndex={0}
+          aria-label="Go to Feature Sets"
+          onClick={() => navigateTo('featuresets')}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter' || e.key === ' ') {
+              e.preventDefault();
+              navigateTo('featuresets');
+            }
+          }}
+        >
           <CardHeader>
             <CardTitle className="flex items-center gap-2 text-base">
               <Wrench className="h-5 w-5 text-primary-500" />
@@ -486,7 +516,20 @@ function DashboardView() {
           </CardContent>
         </Card>
 
-        <Card data-testid="stat-clients">
+        <Card
+          className={statCardClass}
+          data-testid="stat-clients"
+          role="button"
+          tabIndex={0}
+          aria-label="Go to Clients"
+          onClick={() => navigateTo('clients')}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter' || e.key === ' ') {
+              e.preventDefault();
+              navigateTo('clients');
+            }
+          }}
+        >
           <CardHeader>
             <CardTitle className="flex items-center gap-2 text-base">
               <Monitor className="h-5 w-5 text-primary-500" />
@@ -499,7 +542,20 @@ function DashboardView() {
           </CardContent>
         </Card>
 
-        <Card data-testid="stat-active-space">
+        <Card
+          className={statCardClass}
+          data-testid="stat-active-space"
+          role="button"
+          tabIndex={0}
+          aria-label="Go to Spaces"
+          onClick={() => navigateTo('spaces')}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter' || e.key === ' ') {
+              e.preventDefault();
+              navigateTo('spaces');
+            }
+          }}
+        >
           <CardHeader>
             <CardTitle className="flex items-center gap-2 text-base">
               <Globe className="h-5 w-5 text-primary-500" />
diff --git a/crates/mcpmux-core/src/service/space_service.rs b/crates/mcpmux-core/src/service/space_service.rs
index d28ef034..cbaae2ce 100644
--- a/crates/mcpmux-core/src/service/space_service.rs
+++ b/crates/mcpmux-core/src/service/space_service.rs
@@ -126,3 +126,126 @@ impl SpaceService {
         self.repository.get_default().await
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use async_trait::async_trait;
+    use std::collections::HashMap;
+    use tokio::sync::RwLock;
+
+    struct InMemorySpaceRepo {
+        spaces: RwLock<HashMap<Uuid, Space>>,
+    }
+
+    async fn repo_with_space(space: Space) -> Arc<InMemorySpaceRepo> {
+        let repo = Arc::new(InMemorySpaceRepo {
+            spaces: RwLock::new(HashMap::new()),
+        });
+        repo.spaces.write().await.insert(space.id, space);
+        repo
+    }
+
+    #[async_trait]
+    impl SpaceRepository for InMemorySpaceRepo {
+        async fn list(&self) -> crate::repository::RepoResult<Vec<Space>> {
+            Ok(self.spaces.read().await.values().cloned().collect())
+        }
+
+        async fn get(&self, id: &Uuid) -> crate::repository::RepoResult<Option<Space>> {
+            Ok(self.spaces.read().await.get(id).cloned())
+        }
+
+        async fn create(&self, space: &Space) -> crate::repository::RepoResult<()> {
+            self.spaces.write().await.insert(space.id, space.clone());
+            Ok(())
+        }
+
+        async fn update(&self, space: &Space) -> crate::repository::RepoResult<()> {
+            self.spaces.write().await.insert(space.id, space.clone());
+            Ok(())
+        }
+
+        async fn delete(&self, id: &Uuid) -> crate::repository::RepoResult<()> {
+            self.spaces.write().await.remove(id);
+            Ok(())
+        }
+
+        async fn get_default(&self) -> crate::repository::RepoResult<Option<Space>> {
+            Ok(self
+                .spaces
+                .read()
+                .await
+                .values()
+                .find(|s| s.is_default)
+                .cloned())
+        }
+
+        async fn set_default(&self, id: &Uuid) -> crate::repository::RepoResult<()> {
+            let mut spaces = self.spaces.write().await;
+            for space in spaces.values_mut() {
+                space.is_default = false;
+            }
+            if let Some(space) = spaces.get_mut(id) {
+                space.is_default = true;
+            }
+            Ok(())
+        }
+    }
+
+    #[tokio::test]
+    async fn update_changes_name_and_bumps_updated_at() {
+        let original = Space::new("Original");
+        let id = original.id;
+        let original_updated_at = original.updated_at;
+        let repo = repo_with_space(original).await;
+        let service = SpaceService::new(repo);
+
+        let updated = service
+            .update(id, Some("Renamed".to_string()), None, None)
+            .await
+            .unwrap();
+
+        assert_eq!(updated.name, "Renamed");
+        assert!(updated.updated_at >= original_updated_at);
+
+        let loaded = service.get(&id).await.unwrap().expect("space exists");
+        assert_eq!(loaded.name, "Renamed");
+    }
+
+    #[tokio::test]
+    async fn update_applies_icon_and_description() {
+        let space = Space::new("Space");
+        let id = space.id;
+        let repo = repo_with_space(space).await;
+        let service = SpaceService::new(repo);
+
+        let updated = service
+            .update(
+                id,
+                None,
+                Some("rocket".to_string()),
+                Some("Side project".to_string()),
+            )
+            .await
+            .unwrap();
+
+        assert_eq!(updated.icon.as_deref(), Some("rocket"));
+        assert_eq!(updated.description.as_deref(), Some("Side project"));
+    }
+
+    #[tokio::test]
+    async fn update_returns_not_found_for_missing_space() {
+        let repo = Arc::new(InMemorySpaceRepo {
+            spaces: RwLock::new(HashMap::new()),
+        });
+        let service = SpaceService::new(repo);
+
+        let err = service
+            .update(Uuid::new_v4(), Some("nope".to_string()), None, None)
+            .await
+            .unwrap_err();
+
+        assert!(err.to_string().contains("Space not found"));
+    }
+}
diff --git a/crates/mcpmux-storage/src/repositories/workspace_binding_repository.rs b/crates/mcpmux-storage/src/repositories/workspace_binding_repository.rs
index 22e5f3f3..0e7077bc 100644
--- a/crates/mcpmux-storage/src/repositories/workspace_binding_repository.rs
+++ b/crates/mcpmux-storage/src/repositories/workspace_binding_repository.rs
@@ -370,6 +370,31 @@ mod tests {
         assert_eq!(got.workspace_root, root);
         assert_eq!(got.space_id, space_id);
         assert_eq!(got.feature_set_ids, vec![fs_id]);
+        assert_eq!(got.label, None);
+    }
+
+    #[tokio::test]
+    async fn test_label_round_trip() {
+        let (repo, space_id, fs_id) = fixture().await;
+        let root = if cfg!(windows) { "d:\\labeled" } else { "/labeled" };
+        let mut binding = WorkspaceBinding::new(root, space_id, fs_id);
+        binding.label = Some("My Project".to_string());
+        repo.create(&binding).await.unwrap();
+
+        let got = repo.get(&binding.id).await.unwrap().unwrap();
+        assert_eq!(got.label.as_deref(), Some("My Project"));
+
+        let mut updated = got;
+        updated.label = None;
+        repo.update(&updated).await.unwrap();
+        let cleared = repo.get(&binding.id).await.unwrap().unwrap();
+        assert_eq!(cleared.label, None);
+
+        let mut relabeled = cleared;
+        relabeled.label = Some("Renamed".to_string());
+        repo.update(&relabeled).await.unwrap();
+        let final_got = repo.get(&binding.id).await.unwrap().unwrap();
+        assert_eq!(final_got.label.as_deref(), Some("Renamed"));
     }
 
     #[tokio::test]

From da91fd969213b35df2c74bd2f0cfe24352bba69a Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Tue, 19 May 2026 11:09:13 -0600
Subject: [PATCH 12/48] docs: rename build-from-source-macos.md to
 run-from-source-macos.md

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 docs/{build-from-source-macos.md => run-from-source-macos.md} | 0
 1 file changed, 0 insertions(+), 0 deletions(-)
 rename docs/{build-from-source-macos.md => run-from-source-macos.md} (100%)

diff --git a/docs/build-from-source-macos.md b/docs/run-from-source-macos.md
similarity index 100%
rename from docs/build-from-source-macos.md
rename to docs/run-from-source-macos.md

From 2edcd298b0df94fc06a71c1f0700f015cafb60b2 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Tue, 19 May 2026 11:09:41 -0600
Subject: [PATCH 13/48] docs(run-from-source): document pnpm dev watch flow

Restructure to cover both flows: pnpm dev for live HMR + Rust
auto-recompile, and build + swap into /Applications for an installed
app. Add Keychain prompt explainer and shared-data table.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 docs/run-from-source-macos.md | 124 +++++++++++++++++++++++++++-------
 1 file changed, 100 insertions(+), 24 deletions(-)

diff --git a/docs/run-from-source-macos.md b/docs/run-from-source-macos.md
index 0410fdb7..2a309216 100644
--- a/docs/run-from-source-macos.md
+++ b/docs/run-from-source-macos.md
@@ -1,12 +1,19 @@
-# Build from Source and Replace the Installed App (macOS)
+# Run McpMux from Source (macOS)
 
-Replace the release McpMux in `/Applications` with a locally built copy from this repo. Useful when running a fork, a feature branch, or patches that haven't shipped yet.
+Two flows for working against this repo, picked by what you're doing:
+
+| Flow | Use when | Speed | Cursor / Claude / VS Code see it? |
+| ---- | -------- | ----- | --------------------------------- |
+| **Dev watch mode** (`pnpm dev`) | Iterating on UI or Rust — you want HMR for React and auto-recompile for Tauri commands | Vite HMR is instant; Rust changes ~5–15s incremental | Yes — same `localhost:45818` endpoint while `pnpm dev` is running |
+| **Build + swap** (replace `/Applications/McpMux.app`) | You want a real installed app on this branch — autostart, system tray, runs without a terminal, survives reboot | Full build ~5–10 min, incremental ~1–3 min | Yes — and stays running after you close your editor |
+
+Quick rule of thumb: **`pnpm dev` while you're coding, swap when you're done** so other AI clients keep working when Cursor isn't open.
 
 ---
 
-## What survives a swap
+## What survives between flows
 
-Replacing the `.app` bundle does **not** touch your data. McpMux stores everything outside the app:
+Both dev mode and a swapped `.app` use the same `com.mcpmux.desktop` bundle identifier, so they share data:
 
 | Data | Location |
 | ---- | -------- |
@@ -16,9 +23,9 @@ Replacing the `.app` bundle does **not** touch your data. McpMux stores everythi
 | Encryption master key | macOS Keychain (`com.mcpmux.desktop` service) |
 | OAuth tokens / credentials | Encrypted in SQLite + Keychain |
 
-The app identifier (`com.mcpmux.desktop`) is unchanged between release and source builds, so the new binary reads the same data directory and keychain entries.
+The new binary reads the same data dir and keychain entries as the release. Spaces, server installs, and access keys persist across `pnpm dev` ↔ `/Applications` swaps.
 
-**What you might need to redo:** OAuth re-auth in Cursor/Claude Desktop if DCR or token validation changed on your branch. Your McpMux config, spaces, and server installs stay put.
+**What you might need to redo:** OAuth re-auth in Cursor/Claude Desktop if DCR or token validation changed on your branch.
 
 ---
 
@@ -39,11 +46,76 @@ pnpm install
 
 ---
 
-## Option A — Full build (recommended)
+## Flow 1 — Dev watch mode (`pnpm dev`)
+
+Live-reload while you code. Best for tight iteration on UI or Rust.
+
+### What it does
+
+| Layer | Behavior |
+| ----- | -------- |
+| React / Tailwind / TS | Vite dev server on `localhost:1420` with **HMR** — change a `.tsx`/`.css`, see it instantly without losing app state |
+| Rust (Tauri commands, gateway, storage) | Recompiles + relaunches the Tauri window on any `.rs` save under `src-tauri/` or `crates/` |
+| Bundle ID | Same `com.mcpmux.desktop` — reads your real DB and Keychain entries |
+
+### Run it
+
+```bash
+# Quit the installed app first so the dev gateway can bind 127.0.0.1:45818
+osascript -e 'tell application "McpMux" to quit' 2>/dev/null; sleep 2
+
+pnpm dev
+```
+
+A Tauri window opens. Edit `.tsx` files for instant HMR; edit Rust and the window will relaunch on its own after recompile.
+
+### Frontend-only iteration
+
+If you're only changing UI and want the fastest possible loop:
+
+```bash
+pnpm dev:web
+```
+
+This runs Vite alone in a browser tab — no Rust, no Tauri shell. Tauri `invoke()` calls won't work (no backend), but for pure layout/styling work it's the quickest path.
+
+### Gotchas
+
+| Symptom | Why | Fix |
+| ------- | --- | --- |
+| Keychain prompts on first launch of the dev binary | Different signer than `/Applications/McpMux.app` | Click **Always Allow** once — sticks for that built artifact. See `Keychain prompts` below for detail |
+| `Address already in use: 45818` | Installed `.app` still running | `osascript -e 'tell application "McpMux" to quit'` then retry |
+| Cursor's MCP server "disconnected" mid-session | You stopped `pnpm dev` | Cursor reconnects when the gateway is back on `localhost:45818` (either flow) |
+| Rust recompile feels slow | Big edits in `mcpmux-gateway` / `mcpmux-storage` | Expected — keep edits scoped or use `pnpm dev:web` for UI |
+| `pnpm dev` keeps crashing with "Master key not found" | DB/keychain mismatch from manual deletion | Don't manually delete keychain entries — see `Keychain prompts` below |
+
+### Keychain prompts
+
+McpMux reads two secrets from Keychain on startup:
+
+1. **Master encryption key** — every app launch (decrypts SQLite credentials)
+2. **JWT signing secret** — first time you start the gateway in a session
+
+macOS scopes Keychain access to the **specific signed binary**, not just the bundle ID. So:
+
+- First launch of a `pnpm dev` build → 1–2 prompts
+- First launch after a fresh `pnpm build` swap → 1–2 prompts
+- Subsequent launches of the **same** built binary → silent if you clicked **Always Allow**
+- Alternating between `pnpm dev` and `/Applications/McpMux.app` → may re-prompt because each is a different signer
+
+This is expected. Click **Always Allow** the first time you see each prompt for a new build.
+
+---
+
+## Flow 2 — Build and swap into `/Applications`
+
+Use when you want the source build to behave like an installed app: launch from Spotlight/Dock, autostart, run in the background without a dev terminal, survive reboots.
+
+### Option A — Full build (recommended)
 
 Rebuilds the React frontend and produces a fresh `.app` bundle. Use this when frontend or Tauri config changed, or when you want a clean bundle.
 
-### 1. Quit the running app
+#### 1. Quit the running app
 
 ```bash
 osascript -e 'tell application "McpMux" to quit' 2>/dev/null || true
@@ -51,7 +123,7 @@ osascript -e 'tell application "McpMux" to quit' 2>/dev/null || true
 sleep 2
 ```
 
-### 2. Build
+#### 2. Build
 
 ```bash
 cd /path/to/mcp-mux
@@ -67,7 +139,9 @@ target/release/bundle/macos/McpMux.app
 target/release/bundle/dmg/McpMux_*.dmg   # optional installer artifact
 ```
 
-### 3. Backup and swap
+> **Note:** the build may exit non-zero at the very end with `TAURI_SIGNING_PRIVATE_KEY` missing. That only blocks the auto-update artifact; the `.app` and `.dmg` are still produced and usable.
+
+#### 3. Backup and swap
 
 ```bash
 # Backup current install (skip if you already have a recent .bak)
@@ -80,7 +154,7 @@ sudo cp -R target/release/bundle/macos/McpMux.app /Applications/
 sudo chown -R "$(whoami):admin" /Applications/McpMux.app
 ```
 
-### 4. Re-sign (required after manual swap)
+#### 4. Re-sign (required after manual swap)
 
 macOS Gatekeeper rejects a bundle whose binary was replaced without re-signing:
 
@@ -89,17 +163,15 @@ xattr -dr com.apple.quarantine /Applications/McpMux.app 2>/dev/null || true
 codesign --force --deep --sign - /Applications/McpMux.app
 ```
 
-### 5. Launch
+#### 5. Launch
 
 ```bash
 open /Applications/McpMux.app
 ```
 
-Verify: spaces, installed servers, and gateway on `localhost:45818` should look exactly as before.
-
----
+Verify: spaces, installed servers, and gateway on `localhost:45818` should look exactly as before. First launch will trigger 1–2 Keychain prompts because the new ad-hoc signature is a different signer than the previous build — click **Always Allow** once and you're set until the next swap.
 
-## Option B — Binary-only swap (fast path)
+### Option B — Binary-only swap (fast path)
 
 When you changed **Rust only** (no frontend, no `tauri.conf.json` changes). Skips the Vite build and DMG step.
 
@@ -124,7 +196,9 @@ Keeps the existing bundle shell (icons, Info.plist, embedded frontend from last
 
 ---
 
-## Rollback
+## Rollback (Flow 2 only)
+
+If a swapped build is broken, restore the previous `/Applications/McpMux.app`. Dev-mode (`pnpm dev`) doesn't need a rollback — just stop the dev process.
 
 ### Full build rollback
 
@@ -149,13 +223,15 @@ open /Applications/McpMux.app
 
 ## Troubleshooting
 
-| Symptom | Fix |
-| ------- | --- |
-| "App is damaged" / won't open | Re-run `codesign --force --deep --sign - /Applications/McpMux.app` |
-| Gateway port already in use | Old process still running — `pkill -f mcpmux` then relaunch |
-| Cursor OAuth fails after swap | Re-trigger MCP OAuth in Cursor (DCR redirect URI validation may have changed) |
-| Empty app / missing UI | You used binary-only swap but frontend changed — run Option A (full build) |
-| Permission denied on `/Applications` | Use `sudo` for mv/cp/chown, or install to `~/Applications/` and skip sudo |
+| Symptom | Applies to | Fix |
+| ------- | ---------- | --- |
+| "App is damaged" / won't open | Flow 2 | Re-run `codesign --force --deep --sign - /Applications/McpMux.app` |
+| Gateway port already in use | Both | Old process still running — `pkill -f mcpmux` then relaunch |
+| Cursor OAuth fails after swap | Both | Re-trigger MCP OAuth in Cursor (DCR redirect URI validation may have changed) |
+| Empty app / missing UI | Flow 2 (Option B) | You used binary-only swap but frontend changed — run Option A (full build) |
+| Permission denied on `/Applications` | Flow 2 | Use `sudo` for mv/cp/chown, or install to `~/Applications/` and skip sudo |
+| Keychain prompts on every launch of the same binary | Both | Click **Always Allow** (not just **Allow**); check Keychain Access for duplicate `master-encryption-key` / `jwt-signing-secret` entries from old signers |
+| `pnpm dev` won't start — `EADDRINUSE 45818` | Flow 1 | The installed `.app` is still running — quit it before `pnpm dev` |
 
 ---
 

From 5269a189085457d041b678c18b560ac1b50d5441 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Fri, 22 May 2026 10:41:54 -0600
Subject: [PATCH 14/48] fix(gateway): apply session overrides in call_tool
 authorization

RoutingService::call_tool used resolve_feature_sets without session
context, so session-enabled servers passed list_servers but failed at
call time. Pass session_id and use get_tools_for_grants instead.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 crates/mcpmux-gateway/src/mcp/handler.rs  | 1 +
 crates/mcpmux-gateway/src/pool/routing.rs | 5 +++--
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/crates/mcpmux-gateway/src/mcp/handler.rs b/crates/mcpmux-gateway/src/mcp/handler.rs
index e3414842..800c7021 100644
--- a/crates/mcpmux-gateway/src/mcp/handler.rs
+++ b/crates/mcpmux-gateway/src/mcp/handler.rs
@@ -793,6 +793,7 @@ impl ServerHandler for McpMuxGatewayHandler {
             .call_tool(
                 space_id,
                 &feature_set_ids,
+                session_id,
                 &params.name,
                 serde_json::to_value(params.arguments.unwrap_or_default()).unwrap_or_default(),
             )
diff --git a/crates/mcpmux-gateway/src/pool/routing.rs b/crates/mcpmux-gateway/src/pool/routing.rs
index 0c5b21fb..7fd98c96 100644
--- a/crates/mcpmux-gateway/src/pool/routing.rs
+++ b/crates/mcpmux-gateway/src/pool/routing.rs
@@ -187,6 +187,7 @@ impl RoutingService {
         &self,
         space_id: Uuid,
         feature_set_ids: &[String],
+        session_id: Option<&str>,
         tool_name: &str,
         arguments: Value,
     ) -> Result<ToolCallResult> {
@@ -199,10 +200,10 @@ impl RoutingService {
             .await?
             .ok_or_else(|| anyhow!("Tool '{}' not found", tool_name))?;
 
-        // 2. Check if the tool is allowed by grants
+        // 2. Check if the tool is allowed by grants (session overrides included)
         let allowed_features = self
             .feature_service
-            .resolve_feature_sets(&space_id_str, feature_set_ids)
+            .get_tools_for_grants(&space_id_str, feature_set_ids, session_id)
             .await?;
 
         info!(

From d519a792857d3d26b005560cedc91e9e826e5c74 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Sat, 23 May 2026 10:25:16 -0600
Subject: [PATCH 15/48] fix(gateway): forward structuredContent in proxied tool
 results

Tools with output schemas (e.g. Google Workspace MCP) return structuredContent
alongside text content. The gateway was dropping this field when proxying
CallToolResult, causing clients to reject otherwise successful tool calls.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 crates/mcpmux-gateway/src/mcp/handler.rs  | 3 ++-
 crates/mcpmux-gateway/src/pool/routing.rs | 2 ++
 2 files changed, 4 insertions(+), 1 deletion(-)

diff --git a/crates/mcpmux-gateway/src/mcp/handler.rs b/crates/mcpmux-gateway/src/mcp/handler.rs
index 800c7021..1c9b3b9b 100644
--- a/crates/mcpmux-gateway/src/mcp/handler.rs
+++ b/crates/mcpmux-gateway/src/mcp/handler.rs
@@ -852,11 +852,12 @@ impl ServerHandler for McpMuxGatewayHandler {
             "call_tool result"
         );
 
-        let result = if tool_result.is_error {
+        let mut result = if tool_result.is_error {
             CallToolResult::error(content)
         } else {
             CallToolResult::success(content)
         };
+        result.structured_content = tool_result.structured_content;
 
         Ok(result)
     }
diff --git a/crates/mcpmux-gateway/src/pool/routing.rs b/crates/mcpmux-gateway/src/pool/routing.rs
index 7fd98c96..a2f02a37 100644
--- a/crates/mcpmux-gateway/src/pool/routing.rs
+++ b/crates/mcpmux-gateway/src/pool/routing.rs
@@ -51,6 +51,7 @@ pub struct RoutedResource {
 #[derive(Debug)]
 pub struct ToolCallResult {
     pub content: Vec<Value>,
+    pub structured_content: Option<Value>,
     pub is_error: bool,
 }
 
@@ -304,6 +305,7 @@ impl RoutingService {
 
                     Ok(ToolCallResult {
                         content,
+                        structured_content: res.structured_content,
                         is_error: res.is_error.unwrap_or(false),
                     })
                 }

From 7d762a81b9b4841555f4e6b98d84535e2ccb0048 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Sat, 23 May 2026 10:32:18 -0600
Subject: [PATCH 16/48] docs(planning): add server account clones
 implementation plan

Documents UI-assisted multi-account installs (Option 2) with optional
first-class instances deferred to a later phase.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 docs/planning/server-account-clones.md | 268 +++++++++++++++++++++++++
 1 file changed, 268 insertions(+)
 create mode 100644 docs/planning/server-account-clones.md

diff --git a/docs/planning/server-account-clones.md b/docs/planning/server-account-clones.md
new file mode 100644
index 00000000..3c0df921
--- /dev/null
+++ b/docs/planning/server-account-clones.md
@@ -0,0 +1,268 @@
+# Server Account Clones (UI-Assisted Multi-Account)
+
+**Last Updated:** May 23, 2026
+**Status:** Planning — decisions locked, not started
+**Branch:** TBD — file after planning review
+**Base branch:** `main`
+**Issue:** TBD — file after planning review
+**Depends on:** None (orthogonal to session meta-tools; benefits from but does not require PR #154)
+**Unblocks:** Personal MCP migration (`jsg-tech-check/docs/setup/mcpmux-server-migration.md`) — Gmail, Sheets, PostHog ×2, Firebase ×4, and other single-account stdio servers
+
+---
+
+## Problem
+
+McpMux installs servers once per `(space_id, server_id)` — enforced by `UNIQUE(space_id, server_id)` on `installed_servers`, `credentials`, and `outbound_oauth_clients`. That model works when one Space maps to one account (Personal vs S2H vs GAIT), but breaks down when a user needs **two accounts for the same MCP in the same Space**:
+
+| Server type | Example need | Current workaround |
+| ----------- | ------------ | ------------------ |
+| Native multi-account | Google Workspace (`user_google_email` per call) | One install — works today |
+| Single-account stdio | PostHog personal + work in Personal Space | Hand-edit user space JSON with suffixed IDs (`posthog-personal`, `posthog-work`) |
+| Single-account OAuth HTTP | Two Notion workspaces in one Space | Same JSON hack or split Spaces |
+| Env-at-startup servers | Firebase ×4 projects | Four manual JSON entries with different env paths |
+
+The workaround **works** — custom entries with unique IDs get separate processes, credential rows, and tool prefixes — but it is undiscoverable, error-prone, and regresses the "click Install" UX. Users migrating from a 40-entry `~/.cursor/mcp.json` hit this immediately.
+
+Spaces remain the canonical answer for **context-level** separation (work vs personal repos). This feature targets **account-level** duplication inside a Space when context splitting is wrong or insufficient.
+
+---
+
+## Decisions
+
+| # | Decision | Choice | Rationale |
+| - | -------- | ------ | --------- |
+| 1 | Primary approach | **Option 2: UI-assisted clone** — new `server_id` + `manual_entry`, no schema migration | Highest value-to-effort. Removes JSON-editing pain without touching OAuth/credential layer mid-migration. |
+| 2 | Schema change | **Defer Option 3** (`instance_label` column) to optional Phase 5 | Architecturally cleaner long-term, but 2–3 weeks of migration risk across 5+ tables. Ship clones first; revisit when migration volume justifies it. |
+| 3 | Clone identity | **`{base_server_id}-{suffix}`** where suffix is user-chosen (default suggestions: `work`, `personal`, `prod`) | Satisfies unique constraint. Hyphen suffix only — underscores are stripped by `normalize_server_id` and reserved as the tool-name delimiter. |
+| 4 | Definition source | **Copy `cached_definition` from source install** into clone at creation time | Clone is self-contained for offline/gateway startup. Registry updates do not auto-propagate — acceptable tradeoff for v1; document in UI. |
+| 5 | Prefix / alias | **Auto-set alias = suffix** (e.g. `posthog-work` → tools prefixed `posthog-work_*`) | Reuses `PrefixCacheService` first-come assignment. User can override alias in configure step. |
+| 6 | Credentials | **Never copy secrets** — clone starts with empty `input_values` / no OAuth; user configures fresh | Prevents accidental credential sharing. Clone wizard opens configure flow immediately after create. |
+| 7 | Source tracking | **`InstallationSource::ManualEntry`** + optional `cloned_from: Option<String>` metadata on `InstalledServer` | Distinguishes registry installs from clones in UI (`SourceBadge`). `cloned_from` is display-only in v1 — not a FK. |
+| 8 | Registry dedup UX | **"Add another account" disabled when source is already a clone-of-clone** (max depth 1) or when suffix collision detected | Prevents unbounded ID sprawl (`posthog-work-work-work`). Clones clone from registry/original only. |
+| 9 | Spaces unchanged | **No change to Space model** — clone is per-Space like any install | Work/personal split via Spaces stays documented as primary pattern; clones are the escape hatch. |
+
+---
+
+## The Model
+
+### What a clone is
+
+A clone is a **new `InstalledServer` row** in the same Space as the source, with:
+
+```text
+InstalledServer {
+  server_id:     "{base_id}-{suffix}",     // e.g. "posthog-work"
+  server_name:   "{display} ({suffix})",   // e.g. "PostHog (work)"
+  cached_definition: <copy from source>,
+  input_values:  {},                       // empty — user fills in configure step
+  source:        ManualEntry,
+  cloned_from:   Some("{base_id}"),        // new optional field, v1 display-only
+  enabled:       false,                    // same default as registry install
+}
+```
+
+Prefix resolution treats the clone as an independent server. Tool names become `{alias}_{tool}` (e.g. `posthog-work_capture_event`).
+
+### What a clone is NOT
+
+- Not a second OAuth session on the same `server_id` row
+- Not a runtime credential swap (stdio env is fixed at process spawn)
+- Not a registry duplicate — the registry still has one definition for `posthog`; clones are local installs
+
+### Composition with existing patterns
+
+```text
+Multi-account need?
+├─ MCP has per-call account param (Google Workspace)
+│   └─ ONE install — no clone needed
+├─ Accounts map to repo context (Personal / S2H / GAIT)
+│   └─ Spaces — no clone needed
+└─ Two+ accounts in SAME Space, single-account MCP
+    └─ Clone via "Add another account" (this feature)
+```
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  My Servers UI                                                  │
+│                                                                 │
+│  [PostHog ▼]  Connected                                       │
+│    ├─ Configure / Logs / …                                      │
+│    └─ "Add another account…"  ─────────────────────┐            │
+└────────────────────────────────────────────────────│────────────┘
+                                                     │
+                                                     ▼
+                              ┌──────────────────────────────────┐
+                              │  CloneAccountModal                 │
+                              │  • suffix input (work/personal/…)  │
+                              │  • alias preview (posthog-work)    │
+                              │  • collision check                 │
+                              └──────────────────────────────────┘
+                                                     │
+                                                     ▼
+                              ┌──────────────────────────────────┐
+                              │  ServerAppService::clone_server  │
+                              │  1. validate unique server_id    │
+                              │  2. copy cached_definition       │
+                              │  3. set alias in definition JSON │
+                              │  4. install as ManualEntry       │
+                              │  5. emit ServerInstalled         │
+                              └──────────────────────────────────┘
+                                                     │
+                    ┌────────────────────────────────┴───────────────┐
+                    ▼                                                ▼
+         installed_servers row                          credentials row(s)
+         (new server_id)                                (empty until configure)
+                    │
+                    ▼
+         PrefixCache assigns alias on first enable/connect
+                    │
+                    ▼
+         Separate stdio process / OAuth flow with clone's creds
+```
+
+- **No gateway routing changes** — clone is a distinct `server_id`; existing prefix cache + routing already handle multiple servers in one Space.
+- **FeatureSets** see clones as separate servers — user adds `posthog-work` to a FeatureSet independently. Future Option 3 could add "all instances of server X" grouping.
+- **Meta tools** (`mcpmux_enable_server`) already accept any `server_id` string — clones work with session enable once the user knows the suffixed ID. Phase 3 adds optional `cloned_from` hint in `mcpmux_list_servers` response.
+
+---
+
+## Files to create
+
+| File | Purpose |
+| ---- | ------- |
+| `apps/desktop/src/features/servers/CloneAccountModal.tsx` | Suffix input, alias preview, collision feedback, submit → Tauri command |
+| `apps/desktop/src/lib/api/serverClone.ts` | TS wrappers: `cloneServer`, `suggestCloneSuffix`, `isCloneIdAvailable` |
+| `apps/desktop/src-tauri/src/commands/server_clone.rs` | Tauri commands delegating to `ServerAppService::clone_server` |
+| `tests/rust/tests/integration/server_clone.rs` | Clone creates distinct install, empty creds, unique prefix, collision rejection |
+| `docs/planning/server-account-clones.md` | This doc |
+
+## Files to modify
+
+| File | Change |
+| ---- | ------ |
+| [`crates/mcpmux-core/src/domain/installed_server.rs`](../../crates/mcpmux-core/src/domain/installed_server.rs) | Add optional `cloned_from: Option<String>`. Builder `with_cloned_from`. |
+| [`crates/mcpmux-core/src/application/server.rs`](../../crates/mcpmux-core/src/application/server.rs) | `clone_server(space_id, source_server_id, suffix, alias_override?)` — copy definition, derive new ID, install as `ManualEntry`. |
+| [`crates/mcpmux-storage/src/repositories/installed_server_repository.rs`](../../crates/mcpmux-storage/src/repositories/installed_server_repository.rs) | Serialize/deserialize `cloned_from` (new nullable column or JSON in existing row — see Phase 1). |
+| [`crates/mcpmux-storage/src/migrations/`](../../crates/mcpmux-storage/src/migrations/) | New migration: `cloned_from TEXT` nullable on `installed_servers`. |
+| [`apps/desktop/src/features/servers/ServerActionMenu.tsx`](../../apps/desktop/src/features/servers/ServerActionMenu.tsx) | Add "Add another account…" action; hidden for clones-of-clones. |
+| [`apps/desktop/src/features/servers/ServersPage.tsx`](../../apps/desktop/src/features/servers/ServersPage.tsx) | Wire modal, group clones visually under source (optional Phase 2 polish). |
+| [`apps/desktop/src/components/SourceBadge.tsx`](../../apps/desktop/src/components/SourceBadge.tsx) | Badge variant for cloned servers ("Clone of posthog"). |
+| [`apps/desktop/src-tauri/src/lib.rs`](../../apps/desktop/src-tauri/src/lib.rs) | Register `clone_server`, `suggest_clone_suffix`, `is_clone_id_available` commands. |
+| [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | (Phase 3) Optional `cloned_from` field in `mcpmux_list_servers` payload. |
+| [`docs/guide/servers.mdx`](../../docs/guide/servers.mdx) | Document multi-account patterns: Spaces vs native params vs clones. |
+
+---
+
+## Phasing
+
+### Phase 1 — Core clone API + storage
+
+**Effort:** ~1 day
+
+- [ ] Migration: `cloned_from TEXT NULL` on `installed_servers`
+- [ ] `InstalledServer.cloned_from` field + repo round-trip
+- [ ] `ServerAppService::clone_server`:
+  - Load source install + definition from `cached_definition`
+  - Derive `new_id = "{base}-{suffix}"` using same normalization as `UserServerEntry::normalize_server_id`
+  - Reject if `(space_id, new_id)` exists or source is missing
+  - Patch definition `alias` to suffix (or user override)
+  - Install via existing `install()` path with `ManualEntry` + `with_cloned_from(source_id)`
+- [ ] Unit tests: happy path, collision, missing source, suffix normalization (no underscores)
+- [ ] Tauri command `clone_server(space_id, source_server_id, suffix, alias?)`
+
+**Outcome:** `clone_server` from Tauri creates a disabled `posthog-work` install with copied definition, empty creds, and `cloned_from = "posthog"`. Verifiable via `list_installed_servers` and SQLite inspection. No UI yet.
+
+### Phase 2 — Clone wizard UI
+
+**Effort:** ~1 day
+
+- [ ] `CloneAccountModal` — suffix field with suggestions (`work`, `personal`, `prod`, `staging`), live alias preview, inline collision error
+- [ ] `ServerActionMenu` → "Add another account…" on registry and manual installs (not on clones)
+- [ ] Post-clone flow: open existing `ConfigEditorModal` for credential entry before enable
+- [ ] `SourceBadge` shows clone lineage
+- [ ] Optional: collapsed "Accounts" group on `ServersPage` when `cloned_from` matches same base (visual only, no schema)
+
+**Outcome:** User clicks "Add another account" on PostHog, enters suffix `work`, gets `posthog-work` card in My Servers, configures API key, enables — tools appear as `posthog-work_*` in gateway. No JSON editing.
+
+### Phase 3 — Meta-tool + docs surfacing
+
+**Effort:** ~0.5 day
+
+- [ ] `mcpmux_list_servers` returns optional `cloned_from` for clone rows
+- [ ] `docs/guide/servers.mdx` section: "Multiple accounts" — decision tree (Spaces / native param / clone)
+- [ ] Migration doc update in `jsg-tech-check` with concrete clone targets (PostHog, Gmail, Sheets, Firebase)
+
+**Outcome:** LLM manifest shows clone lineage. Docs explain when to clone vs use a Space. Migration checklist has explicit suffix naming convention.
+
+### Phase 4 — Validation + edge cases
+
+**Effort:** ~0.5 day
+
+- [ ] Integration test: two clones in one Space, distinct prefixes, both connect with different env
+- [ ] Uninstall clone does not affect source
+- [ ] Uninstall source warns if clones exist (list dependents, offer bulk uninstall)
+- [ ] Prefix collision: two different registry servers cannot claim same alias (existing behavior — verify clones don't break it)
+- [ ] `pnpm validate` + targeted Rust/TS tests
+
+**Outcome:** Clone lifecycle is safe through install → configure → enable → uninstall. Source/uninstall warnings prevent orphaned expectations.
+
+### Phase 5 — (Optional) First-class instances (Option 3)
+
+**Effort:** ~2–3 weeks — **defer until clone UX proves demand**
+
+- [ ] Schema: replace `UNIQUE(space_id, server_id)` with `UNIQUE(space_id, server_id, instance_label)` on `installed_servers`, `credentials`, `outbound_oauth_clients`, `server_features`
+- [ ] `instance_label` default `"default"` for existing rows; migration backfills
+- [ ] UI: one registry card with N instance sub-cards instead of flat clone list
+- [ ] FeatureSet member type: `ServerInstance { server_id, instance_label }` for grouped grants
+- [ ] Data migration: existing clones (`posthog-work`) → `(posthog, instance_label=work)`
+- [ ] Log paths, OAuth refresh, event payloads gain instance dimension
+
+**Outcome:** Registry server is the template; instances are first-class. Clone IDs like `posthog-work` become legacy format migrated to structured instances. Only pursue if Phase 1–4 adoption shows ID-suffix sprawl or FeatureSet pain.
+
+---
+
+## Out of scope
+
+| Item | Reason |
+| ---- | ------ |
+| Auto-sync clone definition when registry updates | Requires shared definition store or periodic refresh job. Defer; document "clone may drift from registry" in UI. Option 3 addresses properly. |
+| Credential copy / "duplicate with same secrets" | Security footgun. User always re-enters creds on clone. |
+| Runtime account switching on one process | Impossible for stdio env-at-startup servers. Not McpMux's layer to fix. |
+| Wrapper MCP shims per backend | Per-server maintenance burden (Option 5 from brainstorm). Rejected. |
+| Cross-Space clone | Install separately per Space — already works via Spaces. "Clone to another Space" is a nice follow-up, not v1. |
+| Tool-level account selection injection | Would require MCP spec / client header support. Out of scope. |
+
+---
+
+## Key files referenced
+
+| File | Why |
+| ---- | --- |
+| [`crates/mcpmux-core/src/application/server.rs`](../../crates/mcpmux-core/src/application/server.rs) | `install()` uniqueness check — clone must use a new `server_id`. |
+| [`crates/mcpmux-core/src/domain/config.rs`](../../crates/mcpmux-core/src/domain/config.rs) | `normalize_server_id` / `normalize_alias` — suffix rules (no underscores). |
+| [`crates/mcpmux-storage/src/migrations/001_initial.sql`](../../crates/mcpmux-storage/src/migrations/001_initial.sql) | Current `UNIQUE(space_id, server_id)` constraints clone works around. |
+| [`crates/mcpmux-gateway/src/services/prefix_cache.rs`](../../crates/mcpmux-gateway/src/services/prefix_cache.rs) | Prefix assignment for clone's alias at connect time. |
+| [`apps/desktop/src/features/servers/ServersPage.tsx`](../../apps/desktop/src/features/servers/ServersPage.tsx) | Primary UI surface for install/configure/enable flow. |
+| [`apps/desktop/src/components/ConfigEditorModal.tsx`](../../apps/desktop/src/components/ConfigEditorModal.tsx) | Reused post-clone credential entry. |
+| [`docs/guide/spaces.mdx`](../../docs/guide/spaces.mdx) | Canonical work/personal separation — clones complement, not replace. |
+
+---
+
+## Related documentation
+
+- [`docs/planning/dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) — session enable works with clone `server_id`s once user knows the suffixed name; Phase 3 links them.
+- [`docs/guide/servers.mdx`](../../docs/guide/servers.mdx) — server management baseline; gets multi-account section in Phase 3.
+- [`docs/guide/spaces.mdx`](../../docs/guide/spaces.mdx) — primary pattern for context-level account separation.
+- Personal migration tracker: `jsg-tech-check/docs/setup/mcpmux-server-migration.md` — consuming checklist for PostHog, Gmail, Sheets, Firebase clones.
+
+---
+
+## Reconciliation
+
+This doc is the source of truth for server account clones. When implementation starts, update **Status** and **Branch** at the top. Phase 5 remains optional — do not block Phases 1–4 on it.
+
+**Decision record (May 23, 2026):** Option 2 (UI-assisted clone) selected over status quo, first-class instances (deferred Phase 5), per-client credential override (rejected), and wrapper meta-servers (rejected). Brainstorm source: Cursor session on multi-account MCP patterns.

From 55d0758568b87c6ec419901677d67877fc18940a Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Sat, 23 May 2026 10:36:39 -0600
Subject: [PATCH 17/48] =?UTF-8?q?feat(server-clone):=20Phase=201=20?=
 =?UTF-8?q?=E2=80=94=20Core=20clone=20API=20+=20storage?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Autonomous decisions:
- Made normalize_server_id/normalize_alias public — clone_server must reuse the same ID rules as user-space imports
- Registered server_clone in commands/mod.rs — required for lib.rs command wiring
- Added suggest_clone_suffix/is_clone_id_available on ServerAppService — straightforward helpers for Phase 2 UI collision checks

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 apps/desktop/src-tauri/src/commands/mod.rs    |   2 +
 .../src-tauri/src/commands/server_clone.rs    |  75 +++
 apps/desktop/src-tauri/src/lib.rs             |   3 +
 crates/mcpmux-core/src/application/server.rs  | 445 +++++++++++++++++-
 crates/mcpmux-core/src/domain/config.rs       |   4 +-
 .../src/domain/installed_server.rs            |  11 +
 crates/mcpmux-storage/src/database.rs         |   5 +
 .../017_installed_server_cloned_from.sql      |   2 +
 .../installed_server_repository.rs            |  10 +-
 9 files changed, 551 insertions(+), 6 deletions(-)
 create mode 100644 apps/desktop/src-tauri/src/commands/server_clone.rs
 create mode 100644 crates/mcpmux-storage/src/migrations/017_installed_server_cloned_from.sql

diff --git a/apps/desktop/src-tauri/src/commands/mod.rs b/apps/desktop/src-tauri/src/commands/mod.rs
index 692c5bd3..6d8ff479 100644
--- a/apps/desktop/src-tauri/src/commands/mod.rs
+++ b/apps/desktop/src-tauri/src/commands/mod.rs
@@ -14,6 +14,7 @@ pub mod logs;
 pub mod meta_tool_approval;
 pub mod oauth;
 pub mod server;
+pub mod server_clone;
 pub mod server_discovery;
 pub mod server_feature;
 pub mod server_manager;
@@ -33,6 +34,7 @@ pub use logs::*;
 pub use meta_tool_approval::*;
 pub use oauth::*;
 pub use server::*;
+pub use server_clone::*;
 pub use server_discovery::*;
 pub use server_feature::*;
 pub use server_manager::*;
diff --git a/apps/desktop/src-tauri/src/commands/server_clone.rs b/apps/desktop/src-tauri/src/commands/server_clone.rs
new file mode 100644
index 00000000..3f9dc664
--- /dev/null
+++ b/apps/desktop/src-tauri/src/commands/server_clone.rs
@@ -0,0 +1,75 @@
+//! Server clone commands
+
+use mcpmux_core::application::ServerAppService;
+use mcpmux_core::domain::InstalledServer;
+use std::sync::Arc;
+use tauri::State;
+use tokio::sync::RwLock;
+
+/// Clone an installed server into a new suffixed manual-entry install in the same space.
+#[tauri::command]
+pub async fn clone_server(
+    app_service: State<'_, Arc<RwLock<Option<ServerAppService>>>>,
+    space_id: String,
+    source_server_id: String,
+    suffix: String,
+    alias: Option<String>,
+) -> Result<InstalledServer, String> {
+    let service_lock = app_service.read().await;
+    let service = service_lock
+        .as_ref()
+        .ok_or("ServerAppService not initialized")?;
+
+    let space_uuid = uuid::Uuid::parse_str(&space_id).map_err(|e| e.to_string())?;
+
+    service
+        .clone_server(
+            space_uuid,
+            &source_server_id,
+            &suffix,
+            alias.as_deref(),
+        )
+        .await
+        .map_err(|e| e.to_string())
+}
+
+/// Return whether a suffixed clone ID is available in the given space.
+#[tauri::command]
+pub async fn is_clone_id_available(
+    app_service: State<'_, Arc<RwLock<Option<ServerAppService>>>>,
+    space_id: String,
+    source_server_id: String,
+    suffix: String,
+) -> Result<bool, String> {
+    let service_lock = app_service.read().await;
+    let service = service_lock
+        .as_ref()
+        .ok_or("ServerAppService not initialized")?;
+
+    let space_uuid = uuid::Uuid::parse_str(&space_id).map_err(|e| e.to_string())?;
+
+    service
+        .is_clone_id_available(space_uuid, &source_server_id, &suffix)
+        .await
+        .map_err(|e| e.to_string())
+}
+
+/// Suggest the first available default suffix for cloning a server.
+#[tauri::command]
+pub async fn suggest_clone_suffix(
+    app_service: State<'_, Arc<RwLock<Option<ServerAppService>>>>,
+    space_id: String,
+    source_server_id: String,
+) -> Result<String, String> {
+    let service_lock = app_service.read().await;
+    let service = service_lock
+        .as_ref()
+        .ok_or("ServerAppService not initialized")?;
+
+    let space_uuid = uuid::Uuid::parse_str(&space_id).map_err(|e| e.to_string())?;
+
+    service
+        .suggest_clone_suffix(space_uuid, &source_server_id)
+        .await
+        .map_err(|e| e.to_string())
+}
diff --git a/apps/desktop/src-tauri/src/lib.rs b/apps/desktop/src-tauri/src/lib.rs
index 70069a04..9b4b4491 100644
--- a/apps/desktop/src-tauri/src/lib.rs
+++ b/apps/desktop/src-tauri/src/lib.rs
@@ -870,6 +870,9 @@ pub fn run() {
             commands::set_server_enabled,
             commands::set_server_oauth_connected,
             commands::save_server_inputs,
+            commands::clone_server,
+            commands::is_clone_id_available,
+            commands::suggest_clone_suffix,
             // FeatureSet commands
             commands::list_feature_sets,
             commands::list_feature_sets_by_space,
diff --git a/crates/mcpmux-core/src/application/server.rs b/crates/mcpmux-core/src/application/server.rs
index 80181b03..757b7472 100644
--- a/crates/mcpmux-core/src/application/server.rs
+++ b/crates/mcpmux-core/src/application/server.rs
@@ -8,7 +8,7 @@ use std::sync::Arc;
 use tracing::{info, warn};
 use uuid::Uuid;
 
-use crate::domain::{DomainEvent, InstallationSource, InstalledServer, ServerDefinition};
+use crate::domain::{DomainEvent, InstallationSource, InstalledServer, ServerDefinition, UserServerEntry};
 use crate::event_bus::EventSender;
 use crate::repository::{CredentialRepository, InstalledServerRepository, ServerFeatureRepository};
 
@@ -97,6 +97,133 @@ impl ServerAppService {
         Ok(server)
     }
 
+    /// Clone an installed server into a new manual-entry install in the same space.
+    ///
+    /// Copies the source `cached_definition`, assigns a suffixed `server_id`, clears credentials,
+    /// and records lineage in `cloned_from`. Emits: `ServerInstalled`
+    pub async fn clone_server(
+        &self,
+        space_id: Uuid,
+        source_server_id: &str,
+        suffix: &str,
+        alias_override: Option<&str>,
+    ) -> Result<InstalledServer> {
+        let space_id_str = space_id.to_string();
+        let new_server_id = Self::derive_clone_server_id(source_server_id, suffix)?;
+
+        let source = self
+            .server_repo
+            .get_by_server_id(&space_id_str, source_server_id)
+            .await?
+            .ok_or_else(|| anyhow!("Source server not installed"))?;
+
+        if self
+            .server_repo
+            .get_by_server_id(&space_id_str, &new_server_id)
+            .await?
+            .is_some()
+        {
+            return Err(anyhow!("Clone server ID already exists in this space"));
+        }
+
+        let mut definition = source
+            .get_definition()
+            .ok_or_else(|| anyhow!("Source server has no cached definition"))?;
+
+        let normalized_suffix = UserServerEntry::normalize_server_id(suffix);
+        let alias = alias_override
+            .map(UserServerEntry::normalize_alias)
+            .unwrap_or_else(|| normalized_suffix.clone());
+
+        definition.id = new_server_id.clone();
+        definition.name = format!("{} ({})", source.display_name(), normalized_suffix);
+        definition.alias = Some(alias);
+
+        let server = InstalledServer::new(&space_id_str, &new_server_id)
+            .with_definition(&definition)
+            .with_source(InstallationSource::ManualEntry)
+            .with_cloned_from(source_server_id)
+            .with_enabled(false);
+
+        self.server_repo.install(&server).await?;
+
+        info!(
+            space_id = %space_id,
+            source_server_id = source_server_id,
+            server_id = %new_server_id,
+            "[ServerAppService] Cloned server"
+        );
+
+        self.event_sender.emit(DomainEvent::ServerInstalled {
+            space_id,
+            server_id: new_server_id.clone(),
+            server_name: definition.name.clone(),
+        });
+
+        Ok(server)
+    }
+
+    /// Return whether a suffixed clone ID is available in the given space.
+    pub async fn is_clone_id_available(
+        &self,
+        space_id: Uuid,
+        source_server_id: &str,
+        suffix: &str,
+    ) -> Result<bool> {
+        let space_id_str = space_id.to_string();
+        let new_server_id = match Self::derive_clone_server_id(source_server_id, suffix) {
+            Ok(id) => id,
+            Err(_) => return Ok(false),
+        };
+
+        Ok(self
+            .server_repo
+            .get_by_server_id(&space_id_str, &new_server_id)
+            .await?
+            .is_none())
+    }
+
+    /// Suggest the first available default suffix for cloning a server.
+    pub async fn suggest_clone_suffix(
+        &self,
+        space_id: Uuid,
+        source_server_id: &str,
+    ) -> Result<String> {
+        const DEFAULT_SUFFIXES: &[&str] = &["work", "personal", "prod", "staging"];
+
+        for suffix in DEFAULT_SUFFIXES {
+            if self
+                .is_clone_id_available(space_id, source_server_id, suffix)
+                .await?
+            {
+                return Ok((*suffix).to_string());
+            }
+        }
+
+        for index in 2..100 {
+            let suffix = index.to_string();
+            if self
+                .is_clone_id_available(space_id, source_server_id, &suffix)
+                .await?
+            {
+                return Ok(suffix);
+            }
+        }
+
+        Err(anyhow!("No available clone suffix"))
+    }
+
+    /// Derive the normalized clone server ID from a base install ID and user suffix.
+    fn derive_clone_server_id(base_server_id: &str, suffix: &str) -> Result<String> {
+        let normalized_suffix = UserServerEntry::normalize_server_id(suffix);
+        if normalized_suffix.is_empty() {
+            return Err(anyhow!("Clone suffix cannot be empty"));
+        }
+
+        let composite = format!("{base_server_id}-{normalized_suffix}");
+        Ok(UserServerEntry::normalize_server_id(&composite))
+    }
+
     /// Uninstall a server
     ///
     /// For UserConfig servers, this also removes the entry from the source JSON file.
@@ -343,3 +470,319 @@ impl ServerAppService {
         Ok(())
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use async_trait::async_trait;
+    use std::collections::HashMap;
+    use std::sync::RwLock;
+
+    use crate::domain::{ServerSource, TransportConfig, TransportMetadata};
+    use crate::event_bus::EventBus;
+    use crate::repository::InstalledServerRepository;
+
+    struct InMemoryInstalledServerRepo {
+        servers: RwLock<HashMap<Uuid, InstalledServer>>,
+    }
+
+    impl InMemoryInstalledServerRepo {
+        fn new() -> Self {
+            Self {
+                servers: RwLock::new(HashMap::new()),
+            }
+        }
+
+        fn with_server(self, server: InstalledServer) -> Self {
+            self.servers.write().unwrap().insert(server.id, server);
+            self
+        }
+    }
+
+    #[async_trait]
+    impl InstalledServerRepository for InMemoryInstalledServerRepo {
+        async fn list(&self) -> crate::repository::RepoResult<Vec<InstalledServer>> {
+            Ok(self.servers.read().unwrap().values().cloned().collect())
+        }
+
+        async fn list_for_space(
+            &self,
+            space_id: &str,
+        ) -> crate::repository::RepoResult<Vec<InstalledServer>> {
+            Ok(self
+                .servers
+                .read()
+                .unwrap()
+                .values()
+                .filter(|server| server.space_id == space_id)
+                .cloned()
+                .collect())
+        }
+
+        async fn list_by_source_file(
+            &self,
+            _file_path: &std::path::Path,
+        ) -> crate::repository::RepoResult<Vec<InstalledServer>> {
+            Ok(vec![])
+        }
+
+        async fn get(&self, id: &Uuid) -> crate::repository::RepoResult<Option<InstalledServer>> {
+            Ok(self.servers.read().unwrap().get(id).cloned())
+        }
+
+        async fn get_by_server_id(
+            &self,
+            space_id: &str,
+            server_id: &str,
+        ) -> crate::repository::RepoResult<Option<InstalledServer>> {
+            Ok(self
+                .servers
+                .read()
+                .unwrap()
+                .values()
+                .find(|server| server.space_id == space_id && server.server_id == server_id)
+                .cloned())
+        }
+
+        async fn install(&self, server: &InstalledServer) -> crate::repository::RepoResult<()> {
+            self.servers
+                .write()
+                .unwrap()
+                .insert(server.id, server.clone());
+            Ok(())
+        }
+
+        async fn update(&self, server: &InstalledServer) -> crate::repository::RepoResult<()> {
+            self.servers
+                .write()
+                .unwrap()
+                .insert(server.id, server.clone());
+            Ok(())
+        }
+
+        async fn uninstall(&self, id: &Uuid) -> crate::repository::RepoResult<()> {
+            self.servers.write().unwrap().remove(id);
+            Ok(())
+        }
+
+        async fn list_enabled(
+            &self,
+            space_id: &str,
+        ) -> crate::repository::RepoResult<Vec<InstalledServer>> {
+            Ok(self
+                .servers
+                .read()
+                .unwrap()
+                .values()
+                .filter(|server| server.space_id == space_id && server.enabled)
+                .cloned()
+                .collect())
+        }
+
+        async fn list_enabled_all(&self) -> crate::repository::RepoResult<Vec<InstalledServer>> {
+            Ok(self
+                .servers
+                .read()
+                .unwrap()
+                .values()
+                .filter(|server| server.enabled)
+                .cloned()
+                .collect())
+        }
+
+        async fn set_enabled(&self, id: &Uuid, enabled: bool) -> crate::repository::RepoResult<()> {
+            if let Some(server) = self.servers.write().unwrap().get_mut(id) {
+                server.enabled = enabled;
+            }
+            Ok(())
+        }
+
+        async fn set_oauth_connected(
+            &self,
+            id: &Uuid,
+            connected: bool,
+        ) -> crate::repository::RepoResult<()> {
+            if let Some(server) = self.servers.write().unwrap().get_mut(id) {
+                server.oauth_connected = connected;
+            }
+            Ok(())
+        }
+
+        async fn update_inputs(
+            &self,
+            id: &Uuid,
+            input_values: HashMap<String, String>,
+        ) -> crate::repository::RepoResult<()> {
+            if let Some(server) = self.servers.write().unwrap().get_mut(id) {
+                server.input_values = input_values;
+            }
+            Ok(())
+        }
+
+        async fn update_cached_definition(
+            &self,
+            id: &Uuid,
+            server_name: Option<String>,
+            cached_definition: Option<String>,
+        ) -> crate::repository::RepoResult<()> {
+            if let Some(server) = self.servers.write().unwrap().get_mut(id) {
+                server.server_name = server_name;
+                server.cached_definition = cached_definition;
+            }
+            Ok(())
+        }
+    }
+
+    fn sample_definition(server_id: &str, name: &str) -> ServerDefinition {
+        ServerDefinition {
+            id: server_id.to_string(),
+            name: name.to_string(),
+            description: None,
+            alias: None,
+            auth: None,
+            icon: None,
+            transport: TransportConfig::Stdio {
+                command: "npx".to_string(),
+                args: vec!["-y".to_string(), "posthog-mcp".to_string()],
+                env: HashMap::new(),
+                metadata: TransportMetadata::default(),
+            },
+            categories: vec![],
+            publisher: None,
+            source: ServerSource::Bundled,
+            badges: vec![],
+            hosting_type: Default::default(),
+            license: None,
+            license_url: None,
+            installation: None,
+            capabilities: None,
+            sponsored: None,
+            media: None,
+            changelog_url: None,
+        }
+    }
+
+    fn build_service(repo: Arc<dyn InstalledServerRepository>) -> ServerAppService {
+        ServerAppService::new(repo, None, None, EventBus::new().sender())
+    }
+
+    #[tokio::test]
+    async fn clone_server_happy_path() {
+        let space_id = Uuid::new_v4();
+        let space_id_str = space_id.to_string();
+        let source = InstalledServer::new(&space_id_str, "posthog")
+            .with_definition(&sample_definition("posthog", "PostHog"))
+            .with_input("API_KEY", "secret");
+
+        let repo = Arc::new(InMemoryInstalledServerRepo::new().with_server(source));
+        let service = build_service(repo.clone());
+
+        let cloned = service
+            .clone_server(space_id, "posthog", "work", None)
+            .await
+            .expect("clone should succeed");
+
+        assert_eq!(cloned.server_id, "posthog-work");
+        assert_eq!(cloned.cloned_from.as_deref(), Some("posthog"));
+        assert_eq!(cloned.source, InstallationSource::ManualEntry);
+        assert!(!cloned.enabled);
+        assert!(cloned.input_values.is_empty());
+        assert_eq!(cloned.server_name.as_deref(), Some("PostHog (work)"));
+
+        let definition = cloned.get_definition().expect("definition cached");
+        assert_eq!(definition.id, "posthog-work");
+        assert_eq!(definition.alias.as_deref(), Some("work"));
+
+        let stored = repo
+            .get_by_server_id(&space_id_str, "posthog-work")
+            .await
+            .expect("repo lookup")
+            .expect("clone persisted");
+        assert_eq!(stored.cloned_from.as_deref(), Some("posthog"));
+    }
+
+    #[tokio::test]
+    async fn clone_server_rejects_collision() {
+        let space_id = Uuid::new_v4();
+        let space_id_str = space_id.to_string();
+        let source = InstalledServer::new(&space_id_str, "posthog")
+            .with_definition(&sample_definition("posthog", "PostHog"));
+        let existing_clone = InstalledServer::new(&space_id_str, "posthog-work")
+            .with_definition(&sample_definition("posthog-work", "PostHog (work)"));
+
+        let repo = Arc::new(
+            InMemoryInstalledServerRepo::new()
+                .with_server(source)
+                .with_server(existing_clone),
+        );
+        let service = build_service(repo);
+
+        let error = service
+            .clone_server(space_id, "posthog", "work", None)
+            .await
+            .expect_err("collision should fail");
+
+        assert!(error.to_string().contains("already exists"));
+    }
+
+    #[tokio::test]
+    async fn clone_server_rejects_missing_source() {
+        let space_id = Uuid::new_v4();
+        let repo = Arc::new(InMemoryInstalledServerRepo::new());
+        let service = build_service(repo);
+
+        let error = service
+            .clone_server(space_id, "posthog", "work", None)
+            .await
+            .expect_err("missing source should fail");
+
+        assert!(error.to_string().contains("Source server not installed"));
+    }
+
+    #[tokio::test]
+    async fn clone_server_normalizes_suffix_without_underscores() {
+        let space_id = Uuid::new_v4();
+        let space_id_str = space_id.to_string();
+        let source = InstalledServer::new(&space_id_str, "posthog")
+            .with_definition(&sample_definition("posthog", "PostHog"));
+
+        let repo = Arc::new(InMemoryInstalledServerRepo::new().with_server(source));
+        let service = build_service(repo);
+
+        let cloned = service
+            .clone_server(space_id, "posthog", "my_work", None)
+            .await
+            .expect("clone should succeed");
+
+        assert_eq!(cloned.server_id, "posthog-mywork");
+        assert_eq!(
+            cloned.get_definition()
+                .and_then(|definition| definition.alias),
+            Some("mywork".to_string())
+        );
+    }
+
+    #[tokio::test]
+    async fn suggest_clone_suffix_skips_taken_ids() {
+        let space_id = Uuid::new_v4();
+        let space_id_str = space_id.to_string();
+        let source = InstalledServer::new(&space_id_str, "posthog")
+            .with_definition(&sample_definition("posthog", "PostHog"));
+        let existing_clone = InstalledServer::new(&space_id_str, "posthog-work")
+            .with_definition(&sample_definition("posthog-work", "PostHog (work)"));
+
+        let repo = Arc::new(
+            InMemoryInstalledServerRepo::new()
+                .with_server(source)
+                .with_server(existing_clone),
+        );
+        let service = build_service(repo);
+
+        let suffix = service
+            .suggest_clone_suffix(space_id, "posthog")
+            .await
+            .expect("suffix suggestion");
+
+        assert_eq!(suffix, "personal");
+    }
+}
diff --git a/crates/mcpmux-core/src/domain/config.rs b/crates/mcpmux-core/src/domain/config.rs
index d306edcd..afa25333 100644
--- a/crates/mcpmux-core/src/domain/config.rs
+++ b/crates/mcpmux-core/src/domain/config.rs
@@ -140,7 +140,7 @@ impl UserServerEntry {
     /// Normalize a server ID for prefix compatibility
     /// Removes spaces and special characters, converts to lowercase
     /// IMPORTANT: No underscores - underscore is reserved as delimiter in qualified names (prefix_toolname)
-    fn normalize_server_id(id: &str) -> String {
+    pub fn normalize_server_id(id: &str) -> String {
         id.chars()
             .filter_map(|c| {
                 if c.is_alphanumeric() {
@@ -156,7 +156,7 @@ impl UserServerEntry {
 
     /// Normalize an alias to be underscore-free
     /// Underscores are replaced with hyphens since underscore is the prefix_toolname delimiter
-    fn normalize_alias(alias: &str) -> String {
+    pub fn normalize_alias(alias: &str) -> String {
         alias
             .chars()
             .map(|c| {
diff --git a/crates/mcpmux-core/src/domain/installed_server.rs b/crates/mcpmux-core/src/domain/installed_server.rs
index 8c5422f7..41d9d493 100644
--- a/crates/mcpmux-core/src/domain/installed_server.rs
+++ b/crates/mcpmux-core/src/domain/installed_server.rs
@@ -81,6 +81,10 @@ pub struct InstalledServer {
     #[serde(default)]
     pub source: InstallationSource,
 
+    /// Source server ID when this install was cloned from another server in the same space
+    #[serde(default)]
+    pub cloned_from: Option<String>,
+
     /// Creation timestamp
     pub created_at: DateTime<Utc>,
 
@@ -107,6 +111,7 @@ impl InstalledServer {
             extra_headers: HashMap::new(),
             oauth_connected: false,
             source: InstallationSource::default(),
+            cloned_from: None,
             created_at: now,
             updated_at: now,
         }
@@ -160,6 +165,12 @@ impl InstalledServer {
         self
     }
 
+    /// Set the source server ID when this install is a clone
+    pub fn with_cloned_from(mut self, source_server_id: impl Into<String>) -> Self {
+        self.cloned_from = Some(source_server_id.into());
+        self
+    }
+
     /// Update OAuth connected state
     pub fn set_oauth_connected(&mut self, connected: bool) {
         self.oauth_connected = connected;
diff --git a/crates/mcpmux-storage/src/database.rs b/crates/mcpmux-storage/src/database.rs
index 1ae76ab2..630b4b25 100644
--- a/crates/mcpmux-storage/src/database.rs
+++ b/crates/mcpmux-storage/src/database.rs
@@ -113,6 +113,11 @@ const MIGRATIONS: &[Migration] = &[
         name: "workspace_binding_label",
         sql: include_str!("migrations/016_workspace_binding_label.sql"),
     },
+    Migration {
+        version: 17,
+        name: "installed_server_cloned_from",
+        sql: include_str!("migrations/017_installed_server_cloned_from.sql"),
+    },
 ];
 
 /// SQLite database wrapper.
diff --git a/crates/mcpmux-storage/src/migrations/017_installed_server_cloned_from.sql b/crates/mcpmux-storage/src/migrations/017_installed_server_cloned_from.sql
new file mode 100644
index 00000000..a1616bb9
--- /dev/null
+++ b/crates/mcpmux-storage/src/migrations/017_installed_server_cloned_from.sql
@@ -0,0 +1,2 @@
+-- Track clone lineage on installed servers (display-only in v1).
+ALTER TABLE installed_servers ADD COLUMN cloned_from TEXT;
diff --git a/crates/mcpmux-storage/src/repositories/installed_server_repository.rs b/crates/mcpmux-storage/src/repositories/installed_server_repository.rs
index 3ddef0cc..33805568 100644
--- a/crates/mcpmux-storage/src/repositories/installed_server_repository.rs
+++ b/crates/mcpmux-storage/src/repositories/installed_server_repository.rs
@@ -30,6 +30,7 @@ struct RawServerRow {
     created_at: String,
     updated_at: String,
     source: Option<String>,
+    cloned_from: Option<String>,
 }
 
 /// SQLite-backed implementation of InstalledServerRepository.
@@ -131,7 +132,7 @@ impl SqliteInstalledServerRepository {
     /// Standard column list for SELECT queries
     const SELECT_COLUMNS: &'static str =
         "id, space_id, server_id, server_name, cached_definition, input_values, enabled, env_overrides,
-         args_append, extra_headers, oauth_connected, created_at, updated_at, source";
+         args_append, extra_headers, oauth_connected, created_at, updated_at, source, cloned_from";
 
     /// Extract raw row data (used in the closure passed to rusqlite).
     fn extract_row(row: &rusqlite::Row) -> rusqlite::Result<RawServerRow> {
@@ -150,6 +151,7 @@ impl SqliteInstalledServerRepository {
             created_at: row.get(11)?,
             updated_at: row.get(12)?,
             source: row.get(13)?,
+            cloned_from: row.get(14)?,
         })
     }
 
@@ -168,6 +170,7 @@ impl SqliteInstalledServerRepository {
             extra_headers: Self::parse_json_map(row.extra_headers),
             oauth_connected: row.oauth_connected,
             source: Self::parse_source(row.source),
+            cloned_from: row.cloned_from,
             created_at: Self::parse_datetime(&row.created_at),
             updated_at: Self::parse_datetime(&row.updated_at),
         }
@@ -275,8 +278,8 @@ impl InstalledServerRepository for SqliteInstalledServerRepository {
         conn.execute(
             "INSERT INTO installed_servers
              (id, space_id, server_id, server_name, cached_definition, input_values, enabled, env_overrides,
-              args_append, extra_headers, oauth_connected, created_at, updated_at, source)
-             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14)",
+              args_append, extra_headers, oauth_connected, created_at, updated_at, source, cloned_from)
+             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?15)",
             params![
                 server.id.to_string(),
                 server.space_id,
@@ -292,6 +295,7 @@ impl InstalledServerRepository for SqliteInstalledServerRepository {
                 server.created_at.to_rfc3339(),
                 server.updated_at.to_rfc3339(),
                 Self::serialize_source(&server.source),
+                server.cloned_from,
             ],
         )?;
         Ok(())

From 94decc828ae5935351a6c0d9951e2ea41dafcbc4 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Sat, 23 May 2026 10:37:53 -0600
Subject: [PATCH 18/48] =?UTF-8?q?feat(server-clone):=20Phase=202=20?=
 =?UTF-8?q?=E2=80=94=20Clone=20wizard=20UI?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Autonomous decisions:
- Post-clone configure uses ServersPage inline config modal — ConfigEditorModal is for space JSON, not per-server credentials
- cloned_from typed via local ServerViewModelWithClone extension — kept Phase 2 scope off types/registry.ts
- Clone badge replaces Manual badge when clonedFrom is set — lineage is more useful than generic Manual label

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 apps/desktop/src/components/SourceBadge.tsx   |  16 +-
 .../features/servers/CloneAccountModal.tsx    | 287 ++++++++++++++++++
 .../src/features/servers/ServerActionMenu.tsx |  20 +-
 .../src/features/servers/ServersPage.tsx      | 112 ++++++-
 apps/desktop/src/lib/api/serverClone.ts       |  88 ++++++
 5 files changed, 515 insertions(+), 8 deletions(-)
 create mode 100644 apps/desktop/src/features/servers/CloneAccountModal.tsx
 create mode 100644 apps/desktop/src/lib/api/serverClone.ts

diff --git a/apps/desktop/src/components/SourceBadge.tsx b/apps/desktop/src/components/SourceBadge.tsx
index 6dd139a9..40e1f6de 100644
--- a/apps/desktop/src/components/SourceBadge.tsx
+++ b/apps/desktop/src/components/SourceBadge.tsx
@@ -6,6 +6,8 @@ import type { InstallationSource } from '@/types/registry';
 
 interface SourceBadgeProps {
   source: InstallationSource | undefined;
+  /** Source server ID when this install is a clone (display-only lineage). */
+  clonedFrom?: string | null;
   className?: string;
 }
 
@@ -16,7 +18,19 @@ interface SourceBadgeProps {
  * - Config File: Green badge - synced from user's JSON config file
  * - Manual: Gray badge - manually entered via UI
  */
-export function SourceBadge({ source, className = '' }: SourceBadgeProps) {
+export function SourceBadge({ source, clonedFrom, className = '' }: SourceBadgeProps) {
+  if (clonedFrom) {
+    return (
+      <span
+        className={`inline-flex items-center px-2 py-0.5 rounded text-xs font-medium bg-indigo-100 text-indigo-800 dark:bg-indigo-900 dark:text-indigo-200 ${className}`}
+        title={`Cloned from ${clonedFrom}`}
+        data-testid="source-badge-clone"
+      >
+        Clone of {clonedFrom}
+      </span>
+    );
+  }
+
   if (!source) {
     return null;
   }
diff --git a/apps/desktop/src/features/servers/CloneAccountModal.tsx b/apps/desktop/src/features/servers/CloneAccountModal.tsx
new file mode 100644
index 00000000..a07967ef
--- /dev/null
+++ b/apps/desktop/src/features/servers/CloneAccountModal.tsx
@@ -0,0 +1,287 @@
+/**
+ * CloneAccountModal — wizard for adding another account of an installed MCP server.
+ */
+
+import { useCallback, useEffect, useState } from 'react';
+import { Copy, Loader2, X } from 'lucide-react';
+import type { ServerViewModel } from '@/types/registry';
+import {
+  CLONE_SUFFIX_SUGGESTIONS,
+  cloneServer,
+  deriveCloneAlias,
+  deriveCloneServerId,
+  isCloneIdAvailable,
+  suggestCloneSuffix,
+  type ClonedInstalledServer,
+} from '@/lib/api/serverClone';
+
+export interface CloneAccountModalProps {
+  open: boolean;
+  spaceId: string;
+  sourceServer: ServerViewModel;
+  onClose: () => void;
+  /** Called after a successful clone with the new install row. */
+  onCloned: (cloned: ClonedInstalledServer) => void;
+}
+
+/**
+ * Modal for creating a suffixed clone of an installed server in the same space.
+ */
+export function CloneAccountModal({
+  open,
+  spaceId,
+  sourceServer,
+  onClose,
+  onCloned,
+}: CloneAccountModalProps) {
+  const [suffix, setSuffix] = useState('');
+  const [isChecking, setIsChecking] = useState(false);
+  const [isAvailable, setIsAvailable] = useState<boolean | null>(null);
+  const [isSubmitting, setIsSubmitting] = useState(false);
+  const [submitError, setSubmitError] = useState<string | null>(null);
+  const [isLoadingSuggestion, setIsLoadingSuggestion] = useState(false);
+
+  const previewId = deriveCloneServerId(sourceServer.id, suffix);
+  const previewAlias = deriveCloneAlias(suffix);
+  const hasSuffix = suffix.trim().length > 0;
+  const hasCollision = hasSuffix && isAvailable === false;
+
+  /**
+   * Load the first available suggested suffix when the modal opens.
+   */
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+
+    let cancelled = false;
+
+    const loadSuggestion = async () => {
+      setIsLoadingSuggestion(true);
+      setSubmitError(null);
+      try {
+        const suggested = await suggestCloneSuffix(spaceId, sourceServer.id);
+        if (!cancelled) {
+          setSuffix(suggested);
+        }
+      } catch (e) {
+        if (!cancelled) {
+          setSuffix(CLONE_SUFFIX_SUGGESTIONS[0]);
+          setSubmitError(String(e));
+        }
+      } finally {
+        if (!cancelled) {
+          setIsLoadingSuggestion(false);
+        }
+      }
+    };
+
+    loadSuggestion();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [open, spaceId, sourceServer.id]);
+
+  /**
+   * Debounced collision check against the backend.
+   */
+  useEffect(() => {
+    if (!open || !hasSuffix) {
+      setIsAvailable(null);
+      setIsChecking(false);
+      return;
+    }
+
+    let cancelled = false;
+    setIsChecking(true);
+
+    const timer = setTimeout(async () => {
+      try {
+        const available = await isCloneIdAvailable(spaceId, sourceServer.id, suffix);
+        if (!cancelled) {
+          setIsAvailable(available);
+        }
+      } catch {
+        if (!cancelled) {
+          setIsAvailable(null);
+        }
+      } finally {
+        if (!cancelled) {
+          setIsChecking(false);
+        }
+      }
+    }, 300);
+
+    return () => {
+      cancelled = true;
+      clearTimeout(timer);
+    };
+  }, [open, spaceId, sourceServer.id, suffix, hasSuffix]);
+
+  /**
+   * Submit the clone request.
+   */
+  const handleSubmit = useCallback(async () => {
+    if (!hasSuffix || hasCollision || isChecking) {
+      return;
+    }
+
+    setIsSubmitting(true);
+    setSubmitError(null);
+
+    try {
+      const cloned = await cloneServer(spaceId, sourceServer.id, suffix);
+      onCloned(cloned);
+      onClose();
+    } catch (e) {
+      setSubmitError(String(e));
+    } finally {
+      setIsSubmitting(false);
+    }
+  }, [hasSuffix, hasCollision, isChecking, spaceId, sourceServer.id, suffix, onCloned, onClose]);
+
+  if (!open) {
+    return null;
+  }
+
+  const canSubmit = hasSuffix && !hasCollision && !isChecking && !isSubmitting && !isLoadingSuggestion;
+
+  return (
+    <div
+      className="fixed inset-0 bg-black/60 backdrop-blur-sm flex items-center justify-center z-50 p-4"
+      data-testid="clone-account-modal-overlay"
+    >
+      <div
+        className="dropdown-menu w-full max-w-md p-6 animate-in fade-in scale-in duration-150"
+        data-testid="clone-account-modal"
+      >
+        <div className="flex items-start justify-between gap-3 mb-4">
+          <div className="flex items-center gap-3">
+            <div className="p-2 rounded-lg bg-[rgb(var(--primary))]/10">
+              <Copy className="h-5 w-5 text-[rgb(var(--primary))]" />
+            </div>
+            <div>
+              <h3 className="text-lg font-semibold text-[rgb(var(--foreground))]">
+                Add another account
+              </h3>
+              <p className="text-sm text-[rgb(var(--muted))]">
+                Clone {sourceServer.name} with a separate credential set
+              </p>
+            </div>
+          </div>
+          <button
+            onClick={onClose}
+            className="p-1 rounded hover:bg-[rgb(var(--surface-hover))] text-[rgb(var(--muted))] transition-colors"
+            aria-label="Close"
+            data-testid="clone-account-close-btn"
+          >
+            <X className="h-5 w-5" />
+          </button>
+        </div>
+
+        <div className="space-y-4">
+          <div>
+            <label
+              htmlFor="clone-suffix"
+              className="block text-sm font-medium text-[rgb(var(--foreground))] mb-1"
+            >
+              Account label
+            </label>
+            <p className="text-xs text-[rgb(var(--muted))] mb-2">
+              Used in the server ID and tool prefix (e.g. work, personal)
+            </p>
+            <input
+              id="clone-suffix"
+              type="text"
+              value={suffix}
+              onChange={(e) => setSuffix(e.target.value)}
+              placeholder="work"
+              className={`input w-full ${hasCollision ? 'border-[rgb(var(--error))]' : ''}`}
+              disabled={isLoadingSuggestion || isSubmitting}
+              data-testid="clone-suffix-input"
+            />
+            {hasCollision && (
+              <p className="text-xs text-[rgb(var(--error))] mt-1" data-testid="clone-collision-error">
+                An account with this label already exists in this space
+              </p>
+            )}
+          </div>
+
+          <div>
+            <p className="text-xs font-medium text-[rgb(var(--muted))] mb-2">Suggestions</p>
+            <div className="flex flex-wrap gap-2">
+              {CLONE_SUFFIX_SUGGESTIONS.map((suggestion) => (
+                <button
+                  key={suggestion}
+                  type="button"
+                  onClick={() => setSuffix(suggestion)}
+                  className={`px-2.5 py-1 text-xs rounded-md border transition-colors ${
+                    suffix === suggestion
+                      ? 'border-[rgb(var(--primary))] bg-[rgb(var(--primary))]/10 text-[rgb(var(--primary))]'
+                      : 'border-[rgb(var(--border))] text-[rgb(var(--muted))] hover:bg-[rgb(var(--surface-hover))]'
+                  }`}
+                  data-testid={`clone-suffix-suggestion-${suggestion}`}
+                >
+                  {suggestion}
+                </button>
+              ))}
+            </div>
+          </div>
+
+          {hasSuffix && (
+            <div className="rounded-lg border border-[rgb(var(--border-subtle))] bg-[rgb(var(--surface-dim))] p-3 space-y-2">
+              <div className="flex items-center justify-between gap-2 text-sm">
+                <span className="text-[rgb(var(--muted))]">Server ID</span>
+                <code className="text-xs font-mono text-[rgb(var(--foreground))]">{previewId || '—'}</code>
+              </div>
+              <div className="flex items-center justify-between gap-2 text-sm">
+                <span className="text-[rgb(var(--muted))]">Tool prefix</span>
+                <code className="text-xs font-mono text-[rgb(var(--foreground))]">
+                  {previewAlias ? `${previewAlias}_*` : '—'}
+                </code>
+              </div>
+              {isChecking && (
+                <div className="flex items-center gap-2 text-xs text-[rgb(var(--muted))]">
+                  <Loader2 className="h-3 w-3 animate-spin" />
+                  Checking availability…
+                </div>
+              )}
+            </div>
+          )}
+
+          <p className="text-xs text-[rgb(var(--muted))]">
+            The clone copies the server definition but not credentials. You will configure this
+            account before enabling it.
+          </p>
+
+          {submitError && (
+            <p className="text-sm text-[rgb(var(--error))]" data-testid="clone-submit-error">
+              {submitError}
+            </p>
+          )}
+
+          <div className="flex justify-end gap-2 pt-2">
+            <button
+              onClick={onClose}
+              className="px-4 py-2 text-sm rounded-lg border border-[rgb(var(--border))] text-[rgb(var(--muted))] hover:bg-[rgb(var(--surface-hover))] transition-colors"
+              disabled={isSubmitting}
+              data-testid="clone-cancel-btn"
+            >
+              Cancel
+            </button>
+            <button
+              onClick={handleSubmit}
+              disabled={!canSubmit}
+              className="px-4 py-2 text-sm rounded-lg bg-[rgb(var(--primary))] text-[rgb(var(--primary-foreground))] hover:bg-[rgb(var(--primary-hover))] disabled:opacity-50 transition-colors flex items-center gap-2"
+              data-testid="clone-submit-btn"
+            >
+              {isSubmitting && <Loader2 className="h-4 w-4 animate-spin" />}
+              {isSubmitting ? 'Creating…' : 'Create account'}
+            </button>
+          </div>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/desktop/src/features/servers/ServerActionMenu.tsx b/apps/desktop/src/features/servers/ServerActionMenu.tsx
index bbec31e9..fe85261f 100644
--- a/apps/desktop/src/features/servers/ServerActionMenu.tsx
+++ b/apps/desktop/src/features/servers/ServerActionMenu.tsx
@@ -11,7 +11,7 @@
  */
 
 import { useState, useRef, useEffect } from 'react';
-import { MoreVertical, Settings, RefreshCw, RotateCcw, FileText, Code, Trash2 } from 'lucide-react';
+import { MoreVertical, Settings, RefreshCw, RotateCcw, FileText, Code, Trash2, Copy } from 'lucide-react';
 
 export interface ServerActionMenuProps {
   serverId: string;
@@ -20,11 +20,14 @@ export interface ServerActionMenuProps {
   isOAuth: boolean;
   isEnabled: boolean;
   isConnected: boolean;
+  /** Show "Add another account…" for registry/manual installs (not clones-of-clones). */
+  canCloneAccount?: boolean;
   onConfigure: () => void;
   onRefresh: () => void;
   onReconnect: () => void;
   onViewLogs: () => void;
   onViewDefinition: () => void;
+  onCloneAccount?: () => void;
   onUninstall: () => void;
 }
 
@@ -35,11 +38,13 @@ export function ServerActionMenu({
   isOAuth,
   isEnabled,
   isConnected: _isConnected,
+  canCloneAccount = false,
   onConfigure,
   onRefresh,
   onReconnect,
   onViewLogs,
   onViewDefinition,
+  onCloneAccount,
   onUninstall,
 }: ServerActionMenuProps) {
   const [isOpen, setIsOpen] = useState(false);
@@ -163,6 +168,19 @@ export function ServerActionMenu({
             View Definition
           </button>
 
+          {/* Add another account - registry/manual installs only, not clones-of-clones */}
+          {canCloneAccount && onCloneAccount && (
+            <button
+              onClick={() => handleAction(onCloneAccount)}
+              className="w-full flex items-center gap-2 px-3 py-2 text-sm text-[rgb(var(--foreground))] hover:bg-[rgb(var(--surface-hover))] transition-colors"
+              role="menuitem"
+              data-testid={`clone-account-${serverId}`}
+            >
+              <Copy className="h-4 w-4 text-[rgb(var(--muted))]" />
+              Add another account…
+            </button>
+          )}
+
           {/* Separator */}
           <div className="my-1 border-t border-[rgb(var(--border-subtle))]" />
 
diff --git a/apps/desktop/src/features/servers/ServersPage.tsx b/apps/desktop/src/features/servers/ServersPage.tsx
index 9ae658c0..5ff631fb 100644
--- a/apps/desktop/src/features/servers/ServersPage.tsx
+++ b/apps/desktop/src/features/servers/ServersPage.tsx
@@ -21,6 +21,7 @@ import {
   FolderOpen,
 } from 'lucide-react';
 import { ServerActionMenu } from './ServerActionMenu';
+import { CloneAccountModal } from './CloneAccountModal';
 import type { ServerViewModel, ServerDefinition, InstalledServerState, InputDefinition } from '../../types/registry';
 import type { ServerFeature } from '@/lib/api/serverFeatures';
 import { listServerFeaturesByServer } from '@/lib/api/serverFeatures';
@@ -36,12 +37,36 @@ import { ServerLogViewer } from '@/components/ServerLogViewer';
 import { ConfigEditorModal } from '@/components/ConfigEditorModal';
 import { ServerDefinitionModal } from '@/components/ServerDefinitionModal';
 import { SourceBadge } from '@/components/SourceBadge';
+import type { ClonedInstalledServer } from '@/lib/api/serverClone';
+
+/** Server view model extended with optional clone lineage from the backend. */
+type ServerViewModelWithClone = ServerViewModel & { cloned_from?: string };
+
+/**
+ * Read clone lineage from an installed-server row when the TS type has not caught up yet.
+ */
+function getInstalledCloneLineage(state: InstalledServerState): string | undefined {
+  const clonedFrom = (state as InstalledServerState & { cloned_from?: string | null }).cloned_from;
+  return clonedFrom ?? undefined;
+}
+
+/**
+ * Whether the overflow menu should offer "Add another account…".
+ */
+function canCloneServer(server: ServerViewModelWithClone): boolean {
+  if (server.cloned_from) {
+    return false;
+  }
+
+  const sourceType = server.installation_source?.type;
+  return sourceType === 'registry' || sourceType === 'manual_entry';
+}
 
 // Helper to merge definitions with states (same as registryStore)
 function mergeDefinitionsWithStates(
   definitions: ServerDefinition[],
   states: InstalledServerState[]
-): ServerViewModel[] {
+): ServerViewModelWithClone[] {
   const stateMap = new Map(states.map(s => [s.server_id, s]));
   
   return definitions.map(def => {
@@ -70,6 +95,7 @@ function mergeDefinitionsWithStates(
       last_error: null, // Runtime-only, will be set by ServerManager events
       created_at: state?.created_at, // Include for sorting
       installation_source: state?.source, // Track how server was installed
+      cloned_from: state ? getInstalledCloneLineage(state) : undefined,
       env_overrides: state?.env_overrides ?? {},
       args_append: state?.args_append ?? [],
       extra_headers: state?.extra_headers ?? {},
@@ -79,7 +105,7 @@ function mergeDefinitionsWithStates(
 
 // Helper to create ServerViewModel from installed state when registry is unavailable
 // Uses cached_definition if available (proper offline support), otherwise falls back to minimal data
-function createOfflineServerViewModel(state: InstalledServerState): ServerViewModel {
+function createOfflineServerViewModel(state: InstalledServerState): ServerViewModelWithClone {
   // Try to use cached definition first (proper offline support)
   if (state.cached_definition) {
     try {
@@ -104,6 +130,7 @@ function createOfflineServerViewModel(state: InstalledServerState): ServerViewMo
         last_error: null,
         created_at: state.created_at,
         installation_source: state.source,
+        cloned_from: getInstalledCloneLineage(state),
         env_overrides: state.env_overrides ?? {},
         args_append: state.args_append ?? [],
         extra_headers: state.extra_headers ?? {},
@@ -140,6 +167,7 @@ function createOfflineServerViewModel(state: InstalledServerState): ServerViewMo
     last_error: null,
     created_at: state.created_at,
     installation_source: state.source,
+    cloned_from: getInstalledCloneLineage(state),
     env_overrides: state.env_overrides ?? {},
     args_append: state.args_append ?? [],
     extra_headers: state.extra_headers ?? {},
@@ -162,7 +190,7 @@ interface ConfigModalState {
 }
 
 export function ServersPage() {
-  const [installedServers, setInstalledServers] = useState<ServerViewModel[]>([]);
+  const [installedServers, setInstalledServers] = useState<ServerViewModelWithClone[]>([]);
   const [gatewayRunning, setGatewayRunning] = useState(false);
   const [gatewayUrl, setGatewayUrl] = useState<string | null>(null);
   const [isLoading, setIsLoading] = useState(true);
@@ -189,6 +217,9 @@ export function ServersPage() {
 
   // Definition viewer state
   const [definitionServer, setDefinitionServer] = useState<{ id: string; name: string } | null>(null);
+
+  // Clone account wizard state
+  const [cloneModalServer, setCloneModalServer] = useState<ServerViewModelWithClone | null>(null);
   
   // Config editor state
   const [editConfigSpace, setEditConfigSpace] = useState<{ id: string; name: string } | null>(null);
@@ -327,7 +358,7 @@ export function ServersPage() {
       
       // Merge definitions with installed states
       // If definitions are missing, create minimal ServerViewModels from installed states
-      let mergedServers: ServerViewModel[];
+      let mergedServers: ServerViewModelWithClone[];
       
       if (definitions.length > 0) {
         // Normal case: merge definitions with states
@@ -595,7 +626,6 @@ export function ServersPage() {
     }
   };
 
-  // Handle Configure button click (from overflow menu or pending_config state)
   const handleConfigureClick = (server: ServerViewModel) => {
     const serverInputs = server.transport.metadata?.inputs ?? [];
     const initialValues: Record<string, string> = {};
@@ -613,6 +643,60 @@ export function ServersPage() {
     });
   };
 
+  /**
+   * Build a view model from a freshly cloned install row for the configure step.
+   */
+  const createViewModelFromClone = (cloned: ClonedInstalledServer): ServerViewModelWithClone | null => {
+    if (!cloned.cached_definition) {
+      return null;
+    }
+
+    try {
+      const definition: ServerDefinition = JSON.parse(cloned.cached_definition);
+      const inputValues = cloned.input_values ?? {};
+      const inputs = definition.transport.metadata?.inputs ?? [];
+      const missing_required_inputs = inputs.some(
+        (input: InputDefinition) => input.required && !inputValues[input.id]
+      );
+
+      return {
+        ...definition,
+        is_installed: true,
+        enabled: cloned.enabled,
+        oauth_connected: cloned.oauth_connected,
+        input_values: inputValues,
+        connection_status: 'disconnected',
+        missing_required_inputs,
+        last_error: null,
+        created_at: cloned.created_at,
+        installation_source: cloned.source,
+        cloned_from: cloned.cloned_from ?? undefined,
+        env_overrides: cloned.env_overrides ?? {},
+        args_append: cloned.args_append ?? [],
+        extra_headers: cloned.extra_headers ?? {},
+      };
+    } catch (e) {
+      console.warn('[ServersPage] Failed to parse cloned server definition:', e);
+      return null;
+    }
+  };
+
+  /**
+   * Open the configure modal after a successful clone so the user can enter credentials.
+   */
+  const handleCloneComplete = async (cloned: ClonedInstalledServer) => {
+    await loadData();
+
+    const clonedViewModel = createViewModelFromClone(cloned);
+    if (clonedViewModel) {
+      handleConfigureClick(clonedViewModel);
+      showToast(`Created ${clonedViewModel.name}`, 'success');
+      return;
+    }
+
+    showToast('Account created — configure it from My Servers', 'success');
+  };
+
   const handleSaveConfig = async () => {
     if (!configModal.server) return;
     
@@ -1028,7 +1112,10 @@ export function ServersPage() {
                           <span className="text-xs text-[rgb(var(--muted))]">{server.transport.type}</span>
                           
                           {/* Installation Source Badge */}
-                          <SourceBadge source={server.installation_source} />
+                          <SourceBadge
+                            source={server.installation_source}
+                            clonedFrom={server.cloned_from}
+                          />
                         </div>
                         
                         {/* Show runtime message inline (from ServerManager events) */}
@@ -1169,11 +1256,13 @@ export function ServersPage() {
                         }
                         isEnabled={server.enabled}
                         isConnected={serverAction === 'running' || serverAction === 'connected_auto'}
+                        canCloneAccount={canCloneServer(server)}
                         onConfigure={() => handleConfigureClick(server)}
                         onRefresh={() => handleRefresh(server)}
                         onReconnect={() => handleReconnect(server)}
                         onViewLogs={() => setLogViewerServer({ id: server.id, name: server.name })}
                         onViewDefinition={() => setDefinitionServer({ id: server.id, name: server.name })}
+                        onCloneAccount={() => setCloneModalServer(server)}
                         onUninstall={() => handleUninstall(server)}
                       />
                     </div>
@@ -1291,6 +1380,17 @@ export function ServersPage() {
         </div>
       )}
 
+      {/* Clone Account Modal */}
+      {cloneModalServer && viewSpace && (
+        <CloneAccountModal
+          open={!!cloneModalServer}
+          spaceId={viewSpace.id}
+          sourceServer={cloneModalServer}
+          onClose={() => setCloneModalServer(null)}
+          onCloned={handleCloneComplete}
+        />
+      )}
+
       {/* Configuration Modal */}
       {configModal.open && configModal.server && (
         <div className="fixed inset-0 bg-black/60 backdrop-blur-sm flex items-center justify-center z-50 p-4" data-testid="config-modal-overlay">
diff --git a/apps/desktop/src/lib/api/serverClone.ts b/apps/desktop/src/lib/api/serverClone.ts
new file mode 100644
index 00000000..a1131d14
--- /dev/null
+++ b/apps/desktop/src/lib/api/serverClone.ts
@@ -0,0 +1,88 @@
+/**
+ * Server clone API — Tauri wrappers for multi-account cloning.
+ */
+
+import { invoke } from '@tauri-apps/api/core';
+import type { InstalledServerState } from '@/types/registry';
+
+/** Default suffix suggestions shown in the clone wizard */
+export const CLONE_SUFFIX_SUGGESTIONS = ['work', 'personal', 'prod', 'staging'] as const;
+
+/** Installed server row returned by clone_server (includes clone lineage). */
+export interface ClonedInstalledServer extends InstalledServerState {
+  cloned_from?: string | null;
+}
+
+/**
+ * Clone an installed server into a new suffixed manual-entry install in the same space.
+ */
+export async function cloneServer(
+  spaceId: string,
+  sourceServerId: string,
+  suffix: string,
+  alias?: string
+): Promise<ClonedInstalledServer> {
+  return invoke<ClonedInstalledServer>('clone_server', {
+    spaceId,
+    sourceServerId,
+    suffix,
+    alias: alias ?? null,
+  });
+}
+
+/**
+ * Return whether a suffixed clone ID is available in the given space.
+ */
+export async function isCloneIdAvailable(
+  spaceId: string,
+  sourceServerId: string,
+  suffix: string
+): Promise<boolean> {
+  return invoke<boolean>('is_clone_id_available', {
+    spaceId,
+    sourceServerId,
+    suffix,
+  });
+}
+
+/**
+ * Suggest the first available default suffix for cloning a server.
+ */
+export async function suggestCloneSuffix(
+  spaceId: string,
+  sourceServerId: string
+): Promise<string> {
+  return invoke<string>('suggest_clone_suffix', {
+    spaceId,
+    sourceServerId,
+  });
+}
+
+/**
+ * Normalize a server ID the same way the backend does (lowercase, strip underscores/spaces).
+ */
+export function normalizeServerId(id: string): string {
+  return id
+    .split('')
+    .filter((c) => /[a-zA-Z0-9]/.test(c) || c === '-' || c === '.')
+    .map((c) => (/[a-zA-Z0-9]/.test(c) ? c.toLowerCase() : c))
+    .join('');
+}
+
+/**
+ * Derive the clone server ID preview from a base install ID and user suffix.
+ */
+export function deriveCloneServerId(baseServerId: string, suffix: string): string {
+  const normalizedSuffix = normalizeServerId(suffix);
+  if (!normalizedSuffix) {
+    return '';
+  }
+  return normalizeServerId(`${baseServerId}-${normalizedSuffix}`);
+}
+
+/**
+ * Derive the tool-name alias preview for a clone suffix.
+ */
+export function deriveCloneAlias(suffix: string): string {
+  return normalizeServerId(suffix).replace(/_/g, '-');
+}

From a45d34c10f8ffb1c338b48ce25d33aa3df4cc91c Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Sat, 23 May 2026 10:39:12 -0600
Subject: [PATCH 19/48] =?UTF-8?q?feat(server-clone):=20Phase=203=20?=
 =?UTF-8?q?=E2=80=94=20Meta-tool=20+=20docs=20surfacing?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Autonomous decisions:
- Added InstalledServerRepository to MetaToolContext so mcpmux_list_servers
  can resolve cloned_from without a core type change (field already on InstalledServer)
- Omitted cloned_from from non-clone rows rather than emitting null
- Skipped jsg-tech-check migration doc (out of repo per orchestrator)
- Updated planning doc status/checkboxes to match Phases 1–3 completion

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 .../src/server/service_container.rs           |  1 +
 .../src/services/meta_tools/mod.rs            |  2 +
 .../src/services/meta_tools/registry.rs       |  5 +-
 .../src/services/meta_tools/tools.rs          | 22 ++++-
 docs/guide/servers.mdx                        | 27 ++++++
 docs/planning/server-account-clones.md        | 28 +++---
 tests/rust/tests/integration/meta_tools.rs    | 91 ++++++++++++++++++-
 7 files changed, 152 insertions(+), 24 deletions(-)

diff --git a/crates/mcpmux-gateway/src/server/service_container.rs b/crates/mcpmux-gateway/src/server/service_container.rs
index 1273fa79..54e39b6b 100644
--- a/crates/mcpmux-gateway/src/server/service_container.rs
+++ b/crates/mcpmux-gateway/src/server/service_container.rs
@@ -131,6 +131,7 @@ impl ServiceContainer {
             deps.feature_set_repo.clone(),
             deps.workspace_binding_repo.clone(),
             deps.feature_repo.clone(),
+            deps.installed_server_repo.clone(),
             feature_set_resolver.clone(),
             pool_services.feature_service.clone(),
             session_roots.clone(),
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/mod.rs b/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
index e4fc7908..1c0a39ef 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
@@ -56,6 +56,7 @@ pub fn build_default_registry(
     feature_set_repo: std::sync::Arc<dyn mcpmux_core::FeatureSetRepository>,
     binding_repo: std::sync::Arc<dyn mcpmux_core::WorkspaceBindingRepository>,
     server_feature_repo: std::sync::Arc<dyn mcpmux_core::ServerFeatureRepository>,
+    installed_server_repo: std::sync::Arc<dyn mcpmux_core::InstalledServerRepository>,
     resolver: std::sync::Arc<crate::services::FeatureSetResolverService>,
     feature_service: std::sync::Arc<crate::pool::FeatureService>,
     session_roots: std::sync::Arc<crate::services::SessionRootsRegistry>,
@@ -70,6 +71,7 @@ pub fn build_default_registry(
         feature_set_repo,
         binding_repo,
         server_feature_repo,
+        installed_server_repo,
         resolver,
         feature_service,
         session_roots,
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/registry.rs b/crates/mcpmux-gateway/src/services/meta_tools/registry.rs
index 85515bb3..583b9eaa 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/registry.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/registry.rs
@@ -9,8 +9,8 @@ use std::sync::{Arc, Mutex};
 
 use async_trait::async_trait;
 use mcpmux_core::{
-    DomainEvent, FeatureSetRepository, InboundMcpClientRepository, ServerFeatureRepository,
-    SpaceRepository, WorkspaceBindingRepository,
+    DomainEvent, FeatureSetRepository, InboundMcpClientRepository, InstalledServerRepository,
+    ServerFeatureRepository, SpaceRepository, WorkspaceBindingRepository,
 };
 use rmcp::model::{CallToolResult, Tool};
 use serde_json::Value;
@@ -41,6 +41,7 @@ pub struct MetaToolContext {
     pub feature_set_repo: Arc<dyn FeatureSetRepository>,
     pub binding_repo: Arc<dyn WorkspaceBindingRepository>,
     pub server_feature_repo: Arc<dyn ServerFeatureRepository>,
+    pub installed_server_repo: Arc<dyn InstalledServerRepository>,
     pub resolver: Arc<FeatureSetResolverService>,
     pub feature_service: Arc<FeatureService>,
     pub session_roots: Arc<SessionRootsRegistry>,
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
index 4c626423..e0d0170c 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
@@ -211,7 +211,8 @@ impl MetaTool for ListServersTool {
     fn description(&self) -> &'static str {
         "List every MCP server installed in the caller's resolved Space with \
          a coarse status per server: enabled_via_binding, enabled_via_session, \
-         disabled_via_session, or inactive. Use before enable/disable to see \
+         disabled_via_session, or inactive. Clone installs include optional \
+         `cloned_from` (source server_id). Use before enable/disable to see \
          current routing state without loading every tool."
     }
 
@@ -250,6 +251,17 @@ impl MetaTool for ListServersTool {
             .list_for_space(&space_id.to_string())
             .await?;
 
+        let installed = call
+            .ctx
+            .installed_server_repo
+            .list_for_space(&space_id.to_string())
+            .await
+            .map_err(|e| MetaToolError::Internal(e.to_string()))?;
+        let cloned_from_by_server: HashMap<String, Option<String>> = installed
+            .into_iter()
+            .map(|s| (s.server_id, s.cloned_from))
+            .collect();
+
         let mut by_server: HashMap<String, (Option<String>, usize)> = HashMap::new();
         for feature in &features {
             if feature.feature_type != FeatureType::Tool {
@@ -274,12 +286,16 @@ impl MetaTool for ListServersTool {
                     &session_enabled,
                     &session_disabled,
                 );
-                json!({
+                let mut entry = json!({
                     "id": id,
                     "name": name,
                     "tool_count": tool_count,
                     "status": status,
-                })
+                });
+                if let Some(cloned_from) = cloned_from_by_server.get(&id).and_then(|v| v.as_ref()) {
+                    entry["cloned_from"] = json!(cloned_from);
+                }
+                entry
             })
             .collect();
         servers.sort_by(|a, b| {
diff --git a/docs/guide/servers.mdx b/docs/guide/servers.mdx
index 6f68ebe5..49bdbf0e 100644
--- a/docs/guide/servers.mdx
+++ b/docs/guide/servers.mdx
@@ -100,6 +100,33 @@ Disabling a server immediately disconnects it and removes its tools from connect
 
 ![Expanded server view showing available tools and prompts for each connected server](https://mcpmux.com/screenshots/server-expanded.png)
 
+## Multiple Accounts
+
+Some MCP servers only support one account per process. Others accept a per-call account parameter, or you may simply want work and personal credentials in separate contexts. Use this decision tree:
+
+```text
+Need more than one account for the same MCP?
+├─ The MCP accepts a per-call account parameter (e.g. Google Workspace `user_google_email`)
+│   └─ Install once — pass the account on each tool call. No clone needed.
+├─ Accounts map to different repo or project context (work vs personal vs client)
+│   └─ Use [Spaces](/docs/spaces/) — one install per Space with separate credentials.
+└─ Two or more accounts in the SAME Space for a single-account MCP
+    └─ Clone via **Add another account…** on the server card in My Servers.
+```
+
+### Cloning a server
+
+When you need two PostHog workspaces, Firebase projects, or Gmail accounts in one Space:
+
+1. Open **My Servers** and use the server menu → **Add another account…**
+2. Choose a suffix (`work`, `personal`, `prod`, etc.) — the clone ID becomes `{server}-{suffix}` (e.g. `posthog-work`)
+3. Configure credentials for the clone (secrets are never copied from the source)
+4. Enable the clone — tools appear with the clone prefix (e.g. `posthog-work_capture`)
+
+Clones are independent installs: separate credentials, OAuth sessions, and tool prefixes. The source server is unchanged. You cannot clone a clone (max depth 1).
+
+When using [meta tools](/docs/feature-sets/) (`mcpmux_list_servers`), clone rows include an optional `cloned_from` field with the source server ID so an LLM can see lineage.
+
 ## Connection Status
 
 The **My Servers** page shows real-time connection status for each server:
diff --git a/docs/planning/server-account-clones.md b/docs/planning/server-account-clones.md
index 3c0df921..1883ad16 100644
--- a/docs/planning/server-account-clones.md
+++ b/docs/planning/server-account-clones.md
@@ -1,8 +1,8 @@
 # Server Account Clones (UI-Assisted Multi-Account)
 
 **Last Updated:** May 23, 2026
-**Status:** Planning — decisions locked, not started
-**Branch:** TBD — file after planning review
+**Status:** In progress — Phases 1–3 complete, Phase 4 pending
+**Branch:** `feat/server-account-clones`
 **Base branch:** `main`
 **Issue:** TBD — file after planning review
 **Depends on:** None (orthogonal to session meta-tools; benefits from but does not require PR #154)
@@ -163,16 +163,16 @@ Multi-account need?
 
 **Effort:** ~1 day
 
-- [ ] Migration: `cloned_from TEXT NULL` on `installed_servers`
-- [ ] `InstalledServer.cloned_from` field + repo round-trip
-- [ ] `ServerAppService::clone_server`:
+- [x] Migration: `cloned_from TEXT NULL` on `installed_servers`
+- [x] `InstalledServer.cloned_from` field + repo round-trip
+- [x] `ServerAppService::clone_server`:
   - Load source install + definition from `cached_definition`
   - Derive `new_id = "{base}-{suffix}"` using same normalization as `UserServerEntry::normalize_server_id`
   - Reject if `(space_id, new_id)` exists or source is missing
   - Patch definition `alias` to suffix (or user override)
   - Install via existing `install()` path with `ManualEntry` + `with_cloned_from(source_id)`
-- [ ] Unit tests: happy path, collision, missing source, suffix normalization (no underscores)
-- [ ] Tauri command `clone_server(space_id, source_server_id, suffix, alias?)`
+- [x] Unit tests: happy path, collision, missing source, suffix normalization (no underscores)
+- [x] Tauri command `clone_server(space_id, source_server_id, suffix, alias?)`
 
 **Outcome:** `clone_server` from Tauri creates a disabled `posthog-work` install with copied definition, empty creds, and `cloned_from = "posthog"`. Verifiable via `list_installed_servers` and SQLite inspection. No UI yet.
 
@@ -180,10 +180,10 @@ Multi-account need?
 
 **Effort:** ~1 day
 
-- [ ] `CloneAccountModal` — suffix field with suggestions (`work`, `personal`, `prod`, `staging`), live alias preview, inline collision error
-- [ ] `ServerActionMenu` → "Add another account…" on registry and manual installs (not on clones)
-- [ ] Post-clone flow: open existing `ConfigEditorModal` for credential entry before enable
-- [ ] `SourceBadge` shows clone lineage
+- [x] `CloneAccountModal` — suffix field with suggestions (`work`, `personal`, `prod`, `staging`), live alias preview, inline collision error
+- [x] `ServerActionMenu` → "Add another account…" on registry and manual installs (not on clones)
+- [x] Post-clone flow: open existing `ConfigEditorModal` for credential entry before enable
+- [x] `SourceBadge` shows clone lineage
 - [ ] Optional: collapsed "Accounts" group on `ServersPage` when `cloned_from` matches same base (visual only, no schema)
 
 **Outcome:** User clicks "Add another account" on PostHog, enters suffix `work`, gets `posthog-work` card in My Servers, configures API key, enables — tools appear as `posthog-work_*` in gateway. No JSON editing.
@@ -192,9 +192,9 @@ Multi-account need?
 
 **Effort:** ~0.5 day
 
-- [ ] `mcpmux_list_servers` returns optional `cloned_from` for clone rows
-- [ ] `docs/guide/servers.mdx` section: "Multiple accounts" — decision tree (Spaces / native param / clone)
-- [ ] Migration doc update in `jsg-tech-check` with concrete clone targets (PostHog, Gmail, Sheets, Firebase)
+- [x] `mcpmux_list_servers` returns optional `cloned_from` for clone rows
+- [x] `docs/guide/servers.mdx` section: "Multiple accounts" — decision tree (Spaces / native param / clone)
+- [ ] Migration doc update in `jsg-tech-check` with concrete clone targets (PostHog, Gmail, Sheets, Firebase) — out of repo; deferred
 
 **Outcome:** LLM manifest shows clone lineage. Docs explain when to clone vs use a Space. Migration checklist has explicit suffix naming convention.
 
diff --git a/tests/rust/tests/integration/meta_tools.rs b/tests/rust/tests/integration/meta_tools.rs
index 4e693e2c..f8329b03 100644
--- a/tests/rust/tests/integration/meta_tools.rs
+++ b/tests/rust/tests/integration/meta_tools.rs
@@ -12,8 +12,9 @@ use std::time::Duration;
 use futures::FutureExt;
 use mcpmux_core::{
     normalize_workspace_root, Client, DomainEvent, FeatureSet, FeatureSetMember,
-    FeatureSetRepository, InboundMcpClientRepository, MemberMode, MemberType, ServerFeature,
-    ServerFeatureRepository, SpaceRepository, WorkspaceBindingRepository,
+    FeatureSetRepository, InboundMcpClientRepository, InstalledServer, InstalledServerRepository,
+    MemberMode, MemberType, ServerFeature, ServerFeatureRepository, SpaceRepository,
+    WorkspaceBindingRepository,
 };
 use mcpmux_gateway::pool::FeatureService;
 use mcpmux_gateway::services::{
@@ -22,9 +23,9 @@ use mcpmux_gateway::services::{
     SessionRootsRegistry,
 };
 use mcpmux_storage::{
-    Database, InboundClientRepository, SqliteFeatureSetRepository,
-    SqliteInboundMcpClientRepository, SqliteServerFeatureRepository, SqliteSpaceRepository,
-    SqliteWorkspaceBindingRepository,
+    generate_master_key, Database, FieldEncryptor, InboundClientRepository,
+    SqliteFeatureSetRepository, SqliteInboundMcpClientRepository, SqliteInstalledServerRepository,
+    SqliteServerFeatureRepository, SqliteSpaceRepository, SqliteWorkspaceBindingRepository,
 };
 use serde_json::{json, Value};
 use tokio::sync::{broadcast, Mutex};
@@ -37,6 +38,7 @@ struct Fixture {
     client_repo: Arc<dyn InboundMcpClientRepository>,
     feature_set_repo: Arc<dyn FeatureSetRepository>,
     binding_repo: Arc<dyn WorkspaceBindingRepository>,
+    installed_server_repo: Arc<dyn InstalledServerRepository>,
     session_roots: Arc<SessionRootsRegistry>,
     session_overrides: Arc<SessionOverrideRegistry>,
     feature_service: Arc<FeatureService>,
@@ -50,6 +52,11 @@ struct Fixture {
     event_rx: broadcast::Receiver<DomainEvent>,
 }
 
+fn test_encryptor() -> Arc<FieldEncryptor> {
+    let key = generate_master_key().expect("generate key");
+    Arc::new(FieldEncryptor::new(&key).expect("create encryptor"))
+}
+
 impl Fixture {
     async fn new() -> Self {
         let db = Arc::new(Mutex::new(Database::open_in_memory().unwrap()));
@@ -63,6 +70,9 @@ impl Fixture {
             Arc::new(SqliteWorkspaceBindingRepository::new(db.clone()));
         let server_feature_repo: Arc<dyn ServerFeatureRepository> =
             Arc::new(SqliteServerFeatureRepository::new(db.clone()));
+        let installed_server_repo: Arc<dyn InstalledServerRepository> = Arc::new(
+            SqliteInstalledServerRepository::new(db.clone(), test_encryptor()),
+        );
 
         let default_space = space_repo.get_default().await.unwrap().unwrap();
         let space_id = default_space.id;
@@ -127,6 +137,7 @@ impl Fixture {
             feature_set_repo.clone(),
             binding_repo.clone(),
             server_feature_repo.clone(),
+            installed_server_repo.clone(),
             resolver,
             feature_service.clone(),
             session_roots.clone(),
@@ -142,6 +153,7 @@ impl Fixture {
             client_repo,
             feature_set_repo,
             binding_repo,
+            installed_server_repo,
             session_roots,
             session_overrides,
             feature_service,
@@ -353,6 +365,67 @@ async fn list_servers_shows_session_override_statuses() {
     assert_eq!(server_status(&body, "firebase"), "enabled_via_session");
 }
 
+#[tokio::test(flavor = "multi_thread")]
+async fn list_servers_includes_cloned_from_for_clone_installs() {
+    let f = Fixture::new().await;
+    let space_id = f.space_id.to_string();
+
+    let posthog = InstalledServer::new(&space_id, "posthog");
+    f.installed_server_repo
+        .install(&posthog)
+        .await
+        .unwrap();
+    let posthog_work = InstalledServer::new(&space_id, "posthog-work")
+        .with_cloned_from("posthog");
+    f.installed_server_repo
+        .install(&posthog_work)
+        .await
+        .unwrap();
+
+    let mut clone_tool = ServerFeature::tool(f.space_id, "posthog-work", "capture");
+    clone_tool.display_name = Some("PostHog (work)".into());
+    f.registry
+        .context()
+        .server_feature_repo
+        .upsert(&clone_tool)
+        .await
+        .unwrap();
+
+    let result = f
+        .registry
+        .call(
+            "mcpmux_list_servers",
+            &f.client_id,
+            Some(&f.session_id),
+            json!({}),
+        )
+        .await
+        .unwrap();
+    let body = Fixture::result_json(&result);
+    let clone_entry = body
+        .get("servers")
+        .unwrap()
+        .as_array()
+        .unwrap()
+        .iter()
+        .find(|s| s.get("id").and_then(|v| v.as_str()) == Some("posthog-work"))
+        .expect("clone server in manifest");
+    assert_eq!(
+        clone_entry.get("cloned_from").and_then(|v| v.as_str()),
+        Some("posthog")
+    );
+
+    let github_entry = body
+        .get("servers")
+        .unwrap()
+        .as_array()
+        .unwrap()
+        .iter()
+        .find(|s| s.get("id").and_then(|v| v.as_str()) == Some("github"))
+        .expect("github in manifest");
+    assert!(github_entry.get("cloned_from").is_none());
+}
+
 #[tokio::test(flavor = "multi_thread")]
 async fn enable_server_adds_tools_on_next_list() {
     let f = Fixture::new().await;
@@ -774,6 +847,9 @@ async fn bare_registry(
         Arc::new(SqliteWorkspaceBindingRepository::new(db.clone()));
     let server_feature_repo: Arc<dyn ServerFeatureRepository> =
         Arc::new(SqliteServerFeatureRepository::new(db.clone()));
+    let installed_server_repo: Arc<dyn InstalledServerRepository> = Arc::new(
+        SqliteInstalledServerRepository::new(db.clone(), test_encryptor()),
+    );
 
     let _space = space_repo.get_default().await.unwrap().unwrap();
     let client = Client::new("c", "t");
@@ -801,6 +877,7 @@ async fn bare_registry(
         feature_set_repo,
         binding_repo,
         server_feature_repo,
+        installed_server_repo,
         resolver,
         feature_service,
         SessionRootsRegistry::new(),
@@ -894,6 +971,9 @@ async fn master_switch_toggles_registry_visibility() {
         Arc::new(SqliteWorkspaceBindingRepository::new(db.clone()));
     let server_feature_repo: Arc<dyn ServerFeatureRepository> =
         Arc::new(SqliteServerFeatureRepository::new(db.clone()));
+    let installed_server_repo: Arc<dyn InstalledServerRepository> = Arc::new(
+        SqliteInstalledServerRepository::new(db.clone(), test_encryptor()),
+    );
     let inbound_client_repo = Arc::new(InboundClientRepository::new(db.clone()));
     let resolver = Arc::new(FeatureSetResolverService::new(
         space_repo.clone(),
@@ -915,6 +995,7 @@ async fn master_switch_toggles_registry_visibility() {
         feature_set_repo,
         binding_repo,
         server_feature_repo,
+        installed_server_repo,
         resolver,
         feature_service,
         SessionRootsRegistry::new(),

From c090948b111b64a0790cf29b34714c8a2c341e8b Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Sat, 23 May 2026 10:42:06 -0600
Subject: [PATCH 20/48] =?UTF-8?q?feat(server-clone):=20Phase=204=20?=
 =?UTF-8?q?=E2=80=94=20Validation=20+=20edge=20cases?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Autonomous decisions:
- PrefixCache reads alias from cached_definition before registry lookup so clone suffix aliases resolve at connect time
- Uninstall-source UX: three-action modal (cancel / source-only / uninstall all) via UninstallSourceWithClonesDialog
- list_clone_dependents filters list_for_space by cloned_from — no new repo method needed

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 .../src-tauri/src/commands/server_clone.rs    |  18 +
 apps/desktop/src-tauri/src/lib.rs             |   1 +
 .../src/features/servers/ServersPage.tsx      | 128 +++++-
 .../UninstallSourceWithClonesDialog.tsx       |  92 +++++
 apps/desktop/src/lib/api/serverClone.ts       |  13 +
 crates/mcpmux-core/src/application/server.rs  |  84 ++++
 .../src/services/prefix_cache.rs              |  51 ++-
 docs/planning/server-account-clones.md        |  12 +-
 tests/rust/tests/integration/mod.rs           |   1 +
 tests/rust/tests/integration/server_clone.rs  | 378 ++++++++++++++++++
 10 files changed, 740 insertions(+), 38 deletions(-)
 create mode 100644 apps/desktop/src/features/servers/UninstallSourceWithClonesDialog.tsx
 create mode 100644 tests/rust/tests/integration/server_clone.rs

diff --git a/apps/desktop/src-tauri/src/commands/server_clone.rs b/apps/desktop/src-tauri/src/commands/server_clone.rs
index 3f9dc664..91344ba5 100644
--- a/apps/desktop/src-tauri/src/commands/server_clone.rs
+++ b/apps/desktop/src-tauri/src/commands/server_clone.rs
@@ -73,3 +73,21 @@ pub async fn suggest_clone_suffix(
         .await
         .map_err(|e| e.to_string())
 }
+
+/// List installed servers in a space that were cloned from the given source.
+#[tauri::command]
+pub async fn list_clone_dependents(
+    app_service: State<'_, Arc<RwLock<Option<ServerAppService>>>>,
+    space_id: String,
+    source_server_id: String,
+) -> Result<Vec<InstalledServer>, String> {
+    let service_lock = app_service.read().await;
+    let service = service_lock
+        .as_ref()
+        .ok_or("ServerAppService not initialized")?;
+
+    service
+        .list_clone_dependents(&space_id, &source_server_id)
+        .await
+        .map_err(|e| e.to_string())
+}
diff --git a/apps/desktop/src-tauri/src/lib.rs b/apps/desktop/src-tauri/src/lib.rs
index 9b4b4491..03d17b96 100644
--- a/apps/desktop/src-tauri/src/lib.rs
+++ b/apps/desktop/src-tauri/src/lib.rs
@@ -873,6 +873,7 @@ pub fn run() {
             commands::clone_server,
             commands::is_clone_id_available,
             commands::suggest_clone_suffix,
+            commands::list_clone_dependents,
             // FeatureSet commands
             commands::list_feature_sets,
             commands::list_feature_sets_by_space,
diff --git a/apps/desktop/src/features/servers/ServersPage.tsx b/apps/desktop/src/features/servers/ServersPage.tsx
index 5ff631fb..b2341730 100644
--- a/apps/desktop/src/features/servers/ServersPage.tsx
+++ b/apps/desktop/src/features/servers/ServersPage.tsx
@@ -22,6 +22,7 @@ import {
 } from 'lucide-react';
 import { ServerActionMenu } from './ServerActionMenu';
 import { CloneAccountModal } from './CloneAccountModal';
+import { UninstallSourceWithClonesDialog } from './UninstallSourceWithClonesDialog';
 import type { ServerViewModel, ServerDefinition, InstalledServerState, InputDefinition } from '../../types/registry';
 import type { ServerFeature } from '@/lib/api/serverFeatures';
 import { listServerFeaturesByServer } from '@/lib/api/serverFeatures';
@@ -38,6 +39,7 @@ import { ConfigEditorModal } from '@/components/ConfigEditorModal';
 import { ServerDefinitionModal } from '@/components/ServerDefinitionModal';
 import { SourceBadge } from '@/components/SourceBadge';
 import type { ClonedInstalledServer } from '@/lib/api/serverClone';
+import { listCloneDependents } from '@/lib/api/serverClone';
 
 /** Server view model extended with optional clone lineage from the backend. */
 type ServerViewModelWithClone = ServerViewModel & { cloned_from?: string };
@@ -220,6 +222,12 @@ export function ServersPage() {
 
   // Clone account wizard state
   const [cloneModalServer, setCloneModalServer] = useState<ServerViewModelWithClone | null>(null);
+
+  // Uninstall source-with-clones confirmation
+  const [uninstallClonesDialog, setUninstallClonesDialog] = useState<{
+    server: ServerViewModelWithClone;
+    dependents: ClonedInstalledServer[];
+  } | null>(null);
   
   // Config editor state
   const [editConfigSpace, setEditConfigSpace] = useState<{ id: string; name: string } | null>(null);
@@ -795,31 +803,103 @@ export function ServersPage() {
     }
   };
 
-  const handleUninstall = async (server: ServerViewModel) => {
+  const performUninstall = async (serverIds: string[]) => {
+    const { uninstallServer } = await import('@/lib/api/registry');
+    const { disconnectServer } = await import('@/lib/api/gateway');
+
+    if (gatewayRunning && viewSpace) {
+      for (const serverId of serverIds) {
+        const target = installedServers.find((entry) => entry.id === serverId);
+        if (!target?.enabled) {
+          continue;
+        }
+
+        try {
+          await disconnectServer(serverId, viewSpace.id);
+        } catch (error) {
+          console.warn(`[ServersPage] Failed to disconnect server from gateway:`, error);
+        }
+      }
+    }
+
+    for (const serverId of serverIds) {
+      await uninstallServer(serverId, viewSpace?.id ?? '');
+    }
+
+    await loadData();
+  };
+
+  const handleUninstall = async (server: ServerViewModelWithClone) => {
+    if (!viewSpace) {
+      return;
+    }
+
+    if (!server.cloned_from) {
+      try {
+        const dependents = await listCloneDependents(viewSpace.id, server.id);
+        if (dependents.length > 0) {
+          setUninstallClonesDialog({ server, dependents });
+          return;
+        }
+      } catch (error) {
+        showToast(String(error), 'error');
+        return;
+      }
+    }
+
     const { getUninstallLabel } = await import('@/components/SourceBadge');
     const actionLabel = getUninstallLabel(server.installation_source);
 
     setActionLoading(`uninstall-${server.id}`);
     try {
-      const { uninstallServer } = await import('@/lib/api/registry');
-      const { disconnectServer } = await import('@/lib/api/gateway');
-      
-      if (gatewayRunning && server.enabled && viewSpace) {
-        try {
-          await disconnectServer(server.id, viewSpace.id);
-        } catch (e) {
-          console.warn(`[ServersPage] Failed to disconnect server from gateway:`, e);
-        }
-      }
-      
-      // ServerAppService handles source-aware cleanup automatically:
-      // - UserConfig: removes from JSON file + DB
-      // - Registry/ManualEntry: just removes from DB
-      await uninstallServer(server.id, viewSpace?.id ?? '');
-      await loadData();
+      await performUninstall([server.id]);
       showToast(`${server.name} ${actionLabel.toLowerCase()}ed`, 'success');
-    } catch (e) {
-      showToast(String(e), 'error');
+    } catch (error) {
+      showToast(String(error), 'error');
+    } finally {
+      setActionLoading(null);
+    }
+  };
+
+  const handleUninstallSourceOnly = async () => {
+    if (!uninstallClonesDialog) {
+      return;
+    }
+
+    const { server } = uninstallClonesDialog;
+    const { getUninstallLabel } = await import('@/components/SourceBadge');
+    const actionLabel = getUninstallLabel(server.installation_source);
+
+    setUninstallClonesDialog(null);
+    setActionLoading(`uninstall-${server.id}`);
+    try {
+      await performUninstall([server.id]);
+      showToast(`${server.name} ${actionLabel.toLowerCase()}ed`, 'success');
+    } catch (error) {
+      showToast(String(error), 'error');
+    } finally {
+      setActionLoading(null);
+    }
+  };
+
+  const handleUninstallAllWithClones = async () => {
+    if (!uninstallClonesDialog) {
+      return;
+    }
+
+    const { server, dependents } = uninstallClonesDialog;
+    const serverIds = [...dependents.map((dependent) => dependent.server_id), server.id];
+
+    setUninstallClonesDialog(null);
+    setActionLoading(`uninstall-${server.id}`);
+    try {
+      await performUninstall(serverIds);
+      showToast(
+        `${server.name} and ${dependents.length} clone${dependents.length === 1 ? '' : 's'} uninstalled`,
+        'success'
+      );
+    } catch (error) {
+      showToast(String(error), 'error');
     } finally {
       setActionLoading(null);
     }
@@ -930,6 +1010,16 @@ export function ServersPage() {
   return (
     <div className="space-y-6" data-testid="servers-page">
       {gatewayControl.ConfirmDialogElement}
+      {uninstallClonesDialog && (
+        <UninstallSourceWithClonesDialog
+          open
+          sourceName={uninstallClonesDialog.server.name}
+          dependents={uninstallClonesDialog.dependents}
+          onCancel={() => setUninstallClonesDialog(null)}
+          onUninstallSourceOnly={handleUninstallSourceOnly}
+          onUninstallAll={handleUninstallAllWithClones}
+        />
+      )}
       {/* Header */}
       <div className="flex items-center justify-between">
         <div>
diff --git a/apps/desktop/src/features/servers/UninstallSourceWithClonesDialog.tsx b/apps/desktop/src/features/servers/UninstallSourceWithClonesDialog.tsx
new file mode 100644
index 00000000..92b393fb
--- /dev/null
+++ b/apps/desktop/src/features/servers/UninstallSourceWithClonesDialog.tsx
@@ -0,0 +1,92 @@
+import { AlertCircle } from 'lucide-react';
+
+export interface CloneDependentSummary {
+  server_id: string;
+  server_name?: string | null;
+}
+
+interface UninstallSourceWithClonesDialogProps {
+  open: boolean;
+  sourceName: string;
+  dependents: CloneDependentSummary[];
+  onCancel: () => void;
+  onUninstallSourceOnly: () => void;
+  onUninstallAll: () => void;
+}
+
+/**
+ * Warn when uninstalling a source server that still has account clones in the same space.
+ */
+export function UninstallSourceWithClonesDialog({
+  open,
+  sourceName,
+  dependents,
+  onCancel,
+  onUninstallSourceOnly,
+  onUninstallAll,
+}: UninstallSourceWithClonesDialogProps) {
+  if (!open) {
+    return null;
+  }
+
+  const dependentLabels = dependents.map(
+    (dependent) => dependent.server_name ?? dependent.server_id
+  );
+  const dependentList = dependentLabels.join(', ');
+  const totalCount = dependents.length + 1;
+
+  return (
+    <div
+      className="fixed inset-0 z-50 flex items-center justify-center bg-black/50 backdrop-blur-sm"
+      onClick={onCancel}
+      data-testid="uninstall-clones-dialog-overlay"
+    >
+      <div
+        className="mx-4 w-full max-w-md rounded-xl border border-[rgb(var(--border))] bg-[rgb(var(--card))] p-6 shadow-xl animate-in fade-in zoom-in-95 duration-200"
+        onClick={(event) => event.stopPropagation()}
+        data-testid="uninstall-clones-dialog"
+      >
+        <div className="mb-4 flex items-start gap-3">
+          <div className="flex-shrink-0 rounded-full bg-amber-500/10 p-2">
+            <AlertCircle className="h-5 w-5 text-amber-500" />
+          </div>
+          <div>
+            <h3 className="text-base font-semibold">Uninstall server with account clones?</h3>
+            <p className="mt-2 text-sm text-[rgb(var(--muted))]">
+              <span className="font-medium text-[rgb(var(--foreground))]">{sourceName}</span> has{' '}
+              {dependents.length} account clone{dependents.length === 1 ? '' : 's'} in this space:{' '}
+              <span className="font-medium text-[rgb(var(--foreground))]">{dependentList}</span>.
+            </p>
+            <p className="mt-2 text-sm text-[rgb(var(--muted))]">
+              Uninstalling the source leaves clones installed and working. You can also remove
+              everything at once.
+            </p>
+          </div>
+        </div>
+        <div className="flex flex-wrap justify-end gap-3">
+          <button
+            onClick={onCancel}
+            className="rounded-lg border border-[rgb(var(--border))] bg-[rgb(var(--surface-active))] px-4 py-2 text-sm font-medium text-[rgb(var(--foreground))] transition-colors hover:bg-[rgb(var(--surface-hover))]"
+            data-testid="uninstall-clones-cancel"
+          >
+            Cancel
+          </button>
+          <button
+            onClick={onUninstallSourceOnly}
+            className="rounded-lg border border-[rgb(var(--border))] bg-[rgb(var(--surface-active))] px-4 py-2 text-sm font-medium text-[rgb(var(--foreground))] transition-colors hover:bg-[rgb(var(--surface-hover))]"
+            data-testid="uninstall-clones-source-only"
+          >
+            Uninstall source only
+          </button>
+          <button
+            onClick={onUninstallAll}
+            className="rounded-lg bg-red-600 px-4 py-2 text-sm font-medium text-white shadow-sm transition-colors hover:bg-red-700"
+            data-testid="uninstall-clones-all"
+          >
+            Uninstall all ({totalCount})
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+}
diff --git a/apps/desktop/src/lib/api/serverClone.ts b/apps/desktop/src/lib/api/serverClone.ts
index a1131d14..21943685 100644
--- a/apps/desktop/src/lib/api/serverClone.ts
+++ b/apps/desktop/src/lib/api/serverClone.ts
@@ -58,6 +58,19 @@ export async function suggestCloneSuffix(
   });
 }
 
+/**
+ * List account clones that were created from the given source server in a space.
+ */
+export async function listCloneDependents(
+  spaceId: string,
+  sourceServerId: string
+): Promise<ClonedInstalledServer[]> {
+  return invoke<ClonedInstalledServer[]>('list_clone_dependents', {
+    spaceId,
+    sourceServerId,
+  });
+}
+
 /**
  * Normalize a server ID the same way the backend does (lowercase, strip underscores/spaces).
  */
diff --git a/crates/mcpmux-core/src/application/server.rs b/crates/mcpmux-core/src/application/server.rs
index 757b7472..8e20458c 100644
--- a/crates/mcpmux-core/src/application/server.rs
+++ b/crates/mcpmux-core/src/application/server.rs
@@ -183,6 +183,19 @@ impl ServerAppService {
             .is_none())
     }
 
+    /// List installed servers in a space that were cloned from the given source.
+    pub async fn list_clone_dependents(
+        &self,
+        space_id: &str,
+        source_server_id: &str,
+    ) -> Result<Vec<InstalledServer>> {
+        let servers = self.server_repo.list_for_space(space_id).await?;
+        Ok(servers
+            .into_iter()
+            .filter(|server| server.cloned_from.as_deref() == Some(source_server_id))
+            .collect())
+    }
+
     /// Suggest the first available default suffix for cloning a server.
     pub async fn suggest_clone_suffix(
         &self,
@@ -785,4 +798,75 @@ mod tests {
 
         assert_eq!(suffix, "personal");
     }
+
+    #[tokio::test]
+    async fn list_clone_dependents_returns_matching_clones() {
+        let space_id = Uuid::new_v4();
+        let space_id_str = space_id.to_string();
+        let source = InstalledServer::new(&space_id_str, "posthog")
+            .with_definition(&sample_definition("posthog", "PostHog"));
+        let clone_work = InstalledServer::new(&space_id_str, "posthog-work")
+            .with_definition(&sample_definition("posthog-work", "PostHog (work)"))
+            .with_cloned_from("posthog");
+        let clone_personal = InstalledServer::new(&space_id_str, "posthog-personal")
+            .with_definition(&sample_definition("posthog-personal", "PostHog (personal)"))
+            .with_cloned_from("posthog");
+        let unrelated = InstalledServer::new(&space_id_str, "github")
+            .with_definition(&sample_definition("github", "GitHub"));
+
+        let repo = Arc::new(
+            InMemoryInstalledServerRepo::new()
+                .with_server(source)
+                .with_server(clone_work)
+                .with_server(clone_personal)
+                .with_server(unrelated),
+        );
+        let service = build_service(repo);
+
+        let dependents = service
+            .list_clone_dependents(&space_id_str, "posthog")
+            .await
+            .expect("dependents lookup");
+
+        assert_eq!(dependents.len(), 2);
+        let ids: Vec<_> = dependents.iter().map(|server| server.server_id.as_str()).collect();
+        assert!(ids.contains(&"posthog-work"));
+        assert!(ids.contains(&"posthog-personal"));
+    }
+
+    #[tokio::test]
+    async fn uninstall_clone_preserves_source() {
+        let space_id = Uuid::new_v4();
+        let space_id_str = space_id.to_string();
+        let source = InstalledServer::new(&space_id_str, "posthog")
+            .with_definition(&sample_definition("posthog", "PostHog"));
+        let clone_work = InstalledServer::new(&space_id_str, "posthog-work")
+            .with_definition(&sample_definition("posthog-work", "PostHog (work)"))
+            .with_cloned_from("posthog");
+
+        let repo = Arc::new(
+            InMemoryInstalledServerRepo::new()
+                .with_server(source)
+                .with_server(clone_work),
+        );
+        let service = build_service(repo.clone());
+
+        service
+            .uninstall(space_id, "posthog-work")
+            .await
+            .expect("clone uninstall");
+
+        assert!(
+            repo.get_by_server_id(&space_id_str, "posthog")
+                .await
+                .expect("lookup source")
+                .is_some()
+        );
+        assert!(
+            repo.get_by_server_id(&space_id_str, "posthog-work")
+                .await
+                .expect("lookup clone")
+                .is_none()
+        );
+    }
 }
diff --git a/crates/mcpmux-gateway/src/services/prefix_cache.rs b/crates/mcpmux-gateway/src/services/prefix_cache.rs
index 2a85d95b..e631252f 100644
--- a/crates/mcpmux-gateway/src/services/prefix_cache.rs
+++ b/crates/mcpmux-gateway/src/services/prefix_cache.rs
@@ -159,11 +159,16 @@ impl PrefixCacheService {
                 continue;
             }
 
-            // Get desired alias from server discovery
-            let desired_alias = server_discovery
-                .get(&server.server_id)
-                .await
-                .and_then(|s| s.alias.clone());
+            let desired_alias = match server
+                .get_definition()
+                .and_then(|definition| definition.alias.clone())
+            {
+                Some(alias) => Some(alias),
+                None => server_discovery
+                    .get(&server.server_id)
+                    .await
+                    .and_then(|definition| definition.alias),
+            };
 
             // Try to assign alias, fallback to server_id if taken
             let prefix = if let Some(ref alias) = desired_alias {
@@ -286,18 +291,38 @@ impl PrefixCacheService {
     /// This is the recommended method for runtime prefix assignment.
     /// Returns the actual prefix assigned.
     pub async fn assign_prefix_for_server(&self, space_id: &str, server_id: &str) -> String {
-        // Fetch alias from server discovery if available
-        let desired_alias = if let Some(ref discovery) = self.server_discovery {
-            discovery.get(server_id).await.and_then(|s| s.alias.clone())
-        } else {
-            None
-        };
-
-        // Delegate to existing assign_prefix_runtime
+        let desired_alias = self.resolve_desired_alias(space_id, server_id).await;
         self.assign_prefix_runtime(space_id, server_id, desired_alias.as_deref())
             .await
     }
 
+    /// Resolve the preferred tool prefix alias for an installed server.
+    async fn resolve_desired_alias(&self, space_id: &str, server_id: &str) -> Option<String> {
+        if let Some(ref installed_server_repo) = self.installed_server_repo {
+            if let Ok(Some(server)) = installed_server_repo
+                .get_by_server_id(space_id, server_id)
+                .await
+            {
+                if let Some(alias) = server
+                    .get_definition()
+                    .and_then(|definition| definition.alias)
+                    .filter(|alias| !alias.is_empty())
+                {
+                    return Some(alias);
+                }
+            }
+        }
+
+        if let Some(ref discovery) = self.server_discovery {
+            return discovery
+                .get(server_id)
+                .await
+                .and_then(|definition| definition.alias);
+        }
+
+        None
+    }
+
     /// Release a server's prefix (runtime only - no reassignment)
     pub async fn release_prefix_runtime(&self, space_id: &str, server_id: &str) {
         let mut caches = self.caches.write().await;
diff --git a/docs/planning/server-account-clones.md b/docs/planning/server-account-clones.md
index 1883ad16..83c91ee7 100644
--- a/docs/planning/server-account-clones.md
+++ b/docs/planning/server-account-clones.md
@@ -1,7 +1,7 @@
 # Server Account Clones (UI-Assisted Multi-Account)
 
 **Last Updated:** May 23, 2026
-**Status:** In progress — Phases 1–3 complete, Phase 4 pending
+**Status:** In progress — Phases 1–4 complete, Phase 5 optional
 **Branch:** `feat/server-account-clones`
 **Base branch:** `main`
 **Issue:** TBD — file after planning review
@@ -202,11 +202,11 @@ Multi-account need?
 
 **Effort:** ~0.5 day
 
-- [ ] Integration test: two clones in one Space, distinct prefixes, both connect with different env
-- [ ] Uninstall clone does not affect source
-- [ ] Uninstall source warns if clones exist (list dependents, offer bulk uninstall)
-- [ ] Prefix collision: two different registry servers cannot claim same alias (existing behavior — verify clones don't break it)
-- [ ] `pnpm validate` + targeted Rust/TS tests
+- [x] Integration test: two clones in one Space, distinct prefixes, both connect with different env
+- [x] Uninstall clone does not affect source
+- [x] Uninstall source warns if clones exist (list dependents, offer bulk uninstall)
+- [x] Prefix collision: two different registry servers cannot claim same alias (existing behavior — verify clones don't break it)
+- [x] `pnpm validate` + targeted Rust/TS tests
 
 **Outcome:** Clone lifecycle is safe through install → configure → enable → uninstall. Source/uninstall warnings prevent orphaned expectations.
 
diff --git a/tests/rust/tests/integration/mod.rs b/tests/rust/tests/integration/mod.rs
index c1f1acb3..15e23754 100644
--- a/tests/rust/tests/integration/mod.rs
+++ b/tests/rust/tests/integration/mod.rs
@@ -12,4 +12,5 @@ mod feature_routing;
 mod feature_set_resolver;
 mod mcp_flows;
 mod meta_tools;
+mod server_clone;
 mod workspace_binding_events;
diff --git a/tests/rust/tests/integration/server_clone.rs b/tests/rust/tests/integration/server_clone.rs
new file mode 100644
index 00000000..4ced4658
--- /dev/null
+++ b/tests/rust/tests/integration/server_clone.rs
@@ -0,0 +1,378 @@
+//! Integration tests for server account clones — lifecycle, prefixes, and uninstall edges.
+
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use mcpmux_core::{
+    application::ServerAppService, EventBus, InstalledServer, InstalledServerRepository,
+    ServerDefinition, ServerDiscoveryService, ServerFeature, ServerFeatureRepository,
+    ServerSource, SpaceRepository, TransportConfig, TransportMetadata,
+};
+use mcpmux_gateway::{FeatureService, PrefixCacheService, SessionOverrideRegistry};
+use mcpmux_storage::{
+    generate_master_key, FieldEncryptor, SqliteInstalledServerRepository,
+    SqliteServerFeatureRepository, SqliteSpaceRepository,
+};
+use tests::db::TestDatabase;
+use tests::fixtures;
+use tokio::sync::Mutex;
+use uuid::Uuid;
+
+struct CloneFixture {
+    service: ServerAppService,
+    installed_server_repo: Arc<dyn InstalledServerRepository>,
+    feature_repo: Arc<dyn ServerFeatureRepository>,
+    prefix_cache: Arc<PrefixCacheService>,
+    feature_service: Arc<FeatureService>,
+    space_id: Uuid,
+}
+
+impl CloneFixture {
+    async fn new() -> Self {
+        let test_db = TestDatabase::in_memory();
+        let db = Arc::new(Mutex::new(test_db.db));
+        let key = generate_master_key().expect("generate key");
+        let encryptor = Arc::new(FieldEncryptor::new(&key).expect("create encryptor"));
+
+        let space_repo = SqliteSpaceRepository::new(db.clone());
+        let default_space = space_repo.get_default().await.unwrap().unwrap();
+        let space_id = default_space.id;
+
+        let installed_server_repo: Arc<dyn InstalledServerRepository> = Arc::new(
+            SqliteInstalledServerRepository::new(db.clone(), encryptor),
+        );
+        let feature_repo: Arc<dyn ServerFeatureRepository> =
+            Arc::new(SqliteServerFeatureRepository::new(db));
+
+        let prefix_cache = Arc::new(
+            PrefixCacheService::new().with_dependencies(
+                installed_server_repo.clone(),
+                Arc::new(ServerDiscoveryService::new(
+                    std::env::temp_dir().join(format!("mcpmux-clone-test-{}", Uuid::new_v4())),
+                    std::env::temp_dir().join(format!("mcpmux-clone-spaces-{}", Uuid::new_v4())),
+                )),
+            ),
+        );
+        let feature_service = Arc::new(FeatureService::new(
+            feature_repo.clone(),
+            Arc::new(tests::mocks::MockFeatureSetRepository::new()),
+            prefix_cache.clone(),
+            SessionOverrideRegistry::new(),
+        ));
+
+        let service = ServerAppService::new(
+            installed_server_repo.clone(),
+            Some(feature_repo.clone()),
+            None,
+            EventBus::new().sender(),
+        );
+
+        Self {
+            service,
+            installed_server_repo,
+            feature_repo,
+            prefix_cache,
+            feature_service,
+            space_id,
+        }
+    }
+
+    fn space_id_str(&self) -> String {
+        self.space_id.to_string()
+    }
+}
+
+fn env_stdio_definition(server_id: &str, name: &str, alias: &str) -> ServerDefinition {
+    ServerDefinition {
+        id: server_id.to_string(),
+        name: name.to_string(),
+        description: None,
+        alias: Some(alias.to_string()),
+        auth: None,
+        icon: None,
+        transport: TransportConfig::Stdio {
+            command: "echo".to_string(),
+            args: vec!["mcp".to_string()],
+            env: HashMap::from([("ACCOUNT".to_string(), "${ACCOUNT}".to_string())]),
+            metadata: TransportMetadata::default(),
+        },
+        categories: vec![],
+        publisher: None,
+        source: ServerSource::Bundled,
+        badges: vec![],
+        hosting_type: Default::default(),
+        license: None,
+        license_url: None,
+        installation: None,
+        capabilities: None,
+        sponsored: None,
+        media: None,
+        changelog_url: None,
+    }
+}
+
+async fn seed_tool(
+    feature_repo: &Arc<dyn ServerFeatureRepository>,
+    space_id: &str,
+    server_id: &str,
+    tool_name: &str,
+) {
+    let mut feature = ServerFeature::tool(space_id, server_id, tool_name);
+    feature.is_available = true;
+    feature_repo.upsert(&feature).await.unwrap();
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn two_clones_have_distinct_prefixes_and_env() {
+    let fixture = CloneFixture::new().await;
+    let space_id = fixture.space_id;
+    let space_id_str = fixture.space_id_str();
+
+    let source = fixtures::test_installed_server(&space_id_str, "posthog")
+        .with_definition(&env_stdio_definition("posthog", "PostHog", "posthog"));
+    fixture
+        .installed_server_repo
+        .install(&source)
+        .await
+        .unwrap();
+
+    let clone_work = fixture
+        .service
+        .clone_server(space_id, "posthog", "work", None)
+        .await
+        .expect("clone work");
+    let clone_personal = fixture
+        .service
+        .clone_server(space_id, "posthog", "personal", None)
+        .await
+        .expect("clone personal");
+
+    fixture
+        .service
+        .update_config(
+            space_id,
+            "posthog-work",
+            HashMap::from([("ACCOUNT".to_string(), "work-account".to_string())]),
+            Some(HashMap::from([(
+                "ACCOUNT".to_string(),
+                "work-account".to_string(),
+            )])),
+            None,
+            None,
+        )
+        .await
+        .unwrap();
+    fixture
+        .service
+        .update_config(
+            space_id,
+            "posthog-personal",
+            HashMap::from([("ACCOUNT".to_string(), "personal-account".to_string())]),
+            Some(HashMap::from([(
+                "ACCOUNT".to_string(),
+                "personal-account".to_string(),
+            )])),
+            None,
+            None,
+        )
+        .await
+        .unwrap();
+
+    seed_tool(
+        &fixture.feature_repo,
+        &space_id_str,
+        "posthog-work",
+        "capture",
+    )
+    .await;
+    seed_tool(
+        &fixture.feature_repo,
+        &space_id_str,
+        "posthog-personal",
+        "capture",
+    )
+    .await;
+
+    let work_prefix = fixture
+        .prefix_cache
+        .assign_prefix_for_server(&space_id_str, "posthog-work")
+        .await;
+    let personal_prefix = fixture
+        .prefix_cache
+        .assign_prefix_for_server(&space_id_str, "posthog-personal")
+        .await;
+
+    assert_eq!(work_prefix, "work");
+    assert_eq!(personal_prefix, "personal");
+    assert_ne!(work_prefix, personal_prefix);
+
+    let work_resolved = fixture
+        .feature_service
+        .find_server_for_qualified_tool(&space_id_str, "work_capture")
+        .await
+        .unwrap()
+        .expect("work tool resolves");
+    let personal_resolved = fixture
+        .feature_service
+        .find_server_for_qualified_tool(&space_id_str, "personal_capture")
+        .await
+        .unwrap()
+        .expect("personal tool resolves");
+
+    assert_eq!(work_resolved.0, "posthog-work");
+    assert_eq!(personal_resolved.0, "posthog-personal");
+
+    let stored_work = fixture
+        .installed_server_repo
+        .get_by_server_id(&space_id_str, "posthog-work")
+        .await
+        .unwrap()
+        .unwrap();
+    let stored_personal = fixture
+        .installed_server_repo
+        .get_by_server_id(&space_id_str, "posthog-personal")
+        .await
+        .unwrap()
+        .unwrap();
+
+    assert_eq!(
+        stored_work.input_values.get("ACCOUNT").map(String::as_str),
+        Some("work-account")
+    );
+    assert_eq!(
+        stored_personal.input_values.get("ACCOUNT").map(String::as_str),
+        Some("personal-account")
+    );
+    assert_eq!(clone_work.cloned_from.as_deref(), Some("posthog"));
+    assert_eq!(clone_personal.cloned_from.as_deref(), Some("posthog"));
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn uninstall_clone_does_not_affect_source() {
+    let fixture = CloneFixture::new().await;
+    let space_id = fixture.space_id;
+    let space_id_str = fixture.space_id_str();
+
+    let source = fixtures::test_installed_server(&space_id_str, "posthog")
+        .with_definition(&env_stdio_definition("posthog", "PostHog", "posthog"));
+    fixture
+        .installed_server_repo
+        .install(&source)
+        .await
+        .unwrap();
+    fixture
+        .service
+        .clone_server(space_id, "posthog", "work", None)
+        .await
+        .unwrap();
+
+    fixture
+        .service
+        .uninstall(space_id, "posthog-work")
+        .await
+        .expect("clone uninstall");
+
+    assert!(
+        fixture
+            .installed_server_repo
+            .get_by_server_id(&space_id_str, "posthog")
+            .await
+            .unwrap()
+            .is_some()
+    );
+    assert!(
+        fixture
+            .installed_server_repo
+            .get_by_server_id(&space_id_str, "posthog-work")
+            .await
+            .unwrap()
+            .is_none()
+    );
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn list_clone_dependents_returns_source_clones() {
+    let fixture = CloneFixture::new().await;
+    let space_id = fixture.space_id;
+    let space_id_str = fixture.space_id_str();
+
+    let source = fixtures::test_installed_server(&space_id_str, "posthog")
+        .with_definition(&env_stdio_definition("posthog", "PostHog", "posthog"));
+    fixture
+        .installed_server_repo
+        .install(&source)
+        .await
+        .unwrap();
+    fixture
+        .service
+        .clone_server(space_id, "posthog", "work", None)
+        .await
+        .unwrap();
+    fixture
+        .service
+        .clone_server(space_id, "posthog", "personal", None)
+        .await
+        .unwrap();
+
+    let dependents = fixture
+        .service
+        .list_clone_dependents(&space_id_str, "posthog")
+        .await
+        .unwrap();
+
+    assert_eq!(dependents.len(), 2);
+    let ids: Vec<_> = dependents
+        .iter()
+        .map(|server| server.server_id.as_str())
+        .collect();
+    assert!(ids.contains(&"posthog-work"));
+    assert!(ids.contains(&"posthog-personal"));
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn clone_prefixes_do_not_break_existing_alias_uniqueness() {
+    let fixture = CloneFixture::new().await;
+    let space_id_str = fixture.space_id_str();
+
+    let posthog = fixtures::test_installed_server(&space_id_str, "posthog")
+        .with_definition(&env_stdio_definition("posthog", "PostHog", "api"));
+    let other = fixtures::test_installed_server(&space_id_str, "other-server")
+        .with_definition(&env_stdio_definition("other-server", "Other", "api"));
+
+    fixture.installed_server_repo.install(&posthog).await.unwrap();
+    fixture.installed_server_repo.install(&other).await.unwrap();
+
+    let clone = InstalledServer::new(&space_id_str, "posthog-work")
+        .with_definition(&env_stdio_definition("posthog-work", "PostHog (work)", "work"))
+        .with_cloned_from("posthog");
+    fixture.installed_server_repo.install(&clone).await.unwrap();
+
+    let posthog_prefix = fixture
+        .prefix_cache
+        .assign_prefix_runtime(&space_id_str, "posthog", Some("api"))
+        .await;
+    let clone_prefix = fixture
+        .prefix_cache
+        .assign_prefix_runtime(&space_id_str, "posthog-work", Some("work"))
+        .await;
+    let other_prefix = fixture
+        .prefix_cache
+        .assign_prefix_runtime(&space_id_str, "other-server", Some("api"))
+        .await;
+
+    assert_eq!(posthog_prefix, "api");
+    assert_eq!(clone_prefix, "work");
+    assert_eq!(other_prefix, "other-server");
+    assert!(
+        !fixture
+            .prefix_cache
+            .is_prefix_available(&space_id_str, "api")
+            .await
+    );
+    assert!(
+        !fixture
+            .prefix_cache
+            .is_prefix_available(&space_id_str, "work")
+            .await
+    );
+}

From b7016de4b155d2954d01dac01448379f777de573 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Sat, 23 May 2026 10:42:48 -0600
Subject: [PATCH 21/48] chore(fmt): apply cargo fmt after validate sweep

Autonomous decisions:
- Commit fmt-only diffs from pnpm validate cargo fmt --all

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 .../src-tauri/src/commands/server_clone.rs    |  7 +-
 crates/mcpmux-core/src/application/server.rs  | 34 +++++----
 .../workspace_binding_repository.rs           |  9 ++-
 tests/rust/tests/integration/meta_tools.rs    |  8 +--
 tests/rust/tests/integration/server_clone.rs  | 70 ++++++++++---------
 5 files changed, 65 insertions(+), 63 deletions(-)

diff --git a/apps/desktop/src-tauri/src/commands/server_clone.rs b/apps/desktop/src-tauri/src/commands/server_clone.rs
index 91344ba5..4b8c0778 100644
--- a/apps/desktop/src-tauri/src/commands/server_clone.rs
+++ b/apps/desktop/src-tauri/src/commands/server_clone.rs
@@ -23,12 +23,7 @@ pub async fn clone_server(
     let space_uuid = uuid::Uuid::parse_str(&space_id).map_err(|e| e.to_string())?;
 
     service
-        .clone_server(
-            space_uuid,
-            &source_server_id,
-            &suffix,
-            alias.as_deref(),
-        )
+        .clone_server(space_uuid, &source_server_id, &suffix, alias.as_deref())
         .await
         .map_err(|e| e.to_string())
 }
diff --git a/crates/mcpmux-core/src/application/server.rs b/crates/mcpmux-core/src/application/server.rs
index 8e20458c..63477909 100644
--- a/crates/mcpmux-core/src/application/server.rs
+++ b/crates/mcpmux-core/src/application/server.rs
@@ -8,7 +8,9 @@ use std::sync::Arc;
 use tracing::{info, warn};
 use uuid::Uuid;
 
-use crate::domain::{DomainEvent, InstallationSource, InstalledServer, ServerDefinition, UserServerEntry};
+use crate::domain::{
+    DomainEvent, InstallationSource, InstalledServer, ServerDefinition, UserServerEntry,
+};
 use crate::event_bus::EventSender;
 use crate::repository::{CredentialRepository, InstalledServerRepository, ServerFeatureRepository};
 
@@ -769,7 +771,8 @@ mod tests {
 
         assert_eq!(cloned.server_id, "posthog-mywork");
         assert_eq!(
-            cloned.get_definition()
+            cloned
+                .get_definition()
                 .and_then(|definition| definition.alias),
             Some("mywork".to_string())
         );
@@ -829,7 +832,10 @@ mod tests {
             .expect("dependents lookup");
 
         assert_eq!(dependents.len(), 2);
-        let ids: Vec<_> = dependents.iter().map(|server| server.server_id.as_str()).collect();
+        let ids: Vec<_> = dependents
+            .iter()
+            .map(|server| server.server_id.as_str())
+            .collect();
         assert!(ids.contains(&"posthog-work"));
         assert!(ids.contains(&"posthog-personal"));
     }
@@ -856,17 +862,15 @@ mod tests {
             .await
             .expect("clone uninstall");
 
-        assert!(
-            repo.get_by_server_id(&space_id_str, "posthog")
-                .await
-                .expect("lookup source")
-                .is_some()
-        );
-        assert!(
-            repo.get_by_server_id(&space_id_str, "posthog-work")
-                .await
-                .expect("lookup clone")
-                .is_none()
-        );
+        assert!(repo
+            .get_by_server_id(&space_id_str, "posthog")
+            .await
+            .expect("lookup source")
+            .is_some());
+        assert!(repo
+            .get_by_server_id(&space_id_str, "posthog-work")
+            .await
+            .expect("lookup clone")
+            .is_none());
     }
 }
diff --git a/crates/mcpmux-storage/src/repositories/workspace_binding_repository.rs b/crates/mcpmux-storage/src/repositories/workspace_binding_repository.rs
index 0e7077bc..d03b3774 100644
--- a/crates/mcpmux-storage/src/repositories/workspace_binding_repository.rs
+++ b/crates/mcpmux-storage/src/repositories/workspace_binding_repository.rs
@@ -140,8 +140,7 @@ impl SqliteWorkspaceBindingRepository {
         Ok(())
     }
 
-    const SELECT_COLS: &'static str =
-        "id, workspace_root, label, space_id, created_at, updated_at";
+    const SELECT_COLS: &'static str = "id, workspace_root, label, space_id, created_at, updated_at";
 
     /// Fetch bindings + their FeatureSet lists in two queries.
     /// `where_clause` is appended to the binding SELECT (use `""` for none);
@@ -376,7 +375,11 @@ mod tests {
     #[tokio::test]
     async fn test_label_round_trip() {
         let (repo, space_id, fs_id) = fixture().await;
-        let root = if cfg!(windows) { "d:\\labeled" } else { "/labeled" };
+        let root = if cfg!(windows) {
+            "d:\\labeled"
+        } else {
+            "/labeled"
+        };
         let mut binding = WorkspaceBinding::new(root, space_id, fs_id);
         binding.label = Some("My Project".to_string());
         repo.create(&binding).await.unwrap();
diff --git a/tests/rust/tests/integration/meta_tools.rs b/tests/rust/tests/integration/meta_tools.rs
index f8329b03..f75c23b4 100644
--- a/tests/rust/tests/integration/meta_tools.rs
+++ b/tests/rust/tests/integration/meta_tools.rs
@@ -371,12 +371,8 @@ async fn list_servers_includes_cloned_from_for_clone_installs() {
     let space_id = f.space_id.to_string();
 
     let posthog = InstalledServer::new(&space_id, "posthog");
-    f.installed_server_repo
-        .install(&posthog)
-        .await
-        .unwrap();
-    let posthog_work = InstalledServer::new(&space_id, "posthog-work")
-        .with_cloned_from("posthog");
+    f.installed_server_repo.install(&posthog).await.unwrap();
+    let posthog_work = InstalledServer::new(&space_id, "posthog-work").with_cloned_from("posthog");
     f.installed_server_repo
         .install(&posthog_work)
         .await
diff --git a/tests/rust/tests/integration/server_clone.rs b/tests/rust/tests/integration/server_clone.rs
index 4ced4658..2eb0bae1 100644
--- a/tests/rust/tests/integration/server_clone.rs
+++ b/tests/rust/tests/integration/server_clone.rs
@@ -5,8 +5,8 @@ use std::sync::Arc;
 
 use mcpmux_core::{
     application::ServerAppService, EventBus, InstalledServer, InstalledServerRepository,
-    ServerDefinition, ServerDiscoveryService, ServerFeature, ServerFeatureRepository,
-    ServerSource, SpaceRepository, TransportConfig, TransportMetadata,
+    ServerDefinition, ServerDiscoveryService, ServerFeature, ServerFeatureRepository, ServerSource,
+    SpaceRepository, TransportConfig, TransportMetadata,
 };
 use mcpmux_gateway::{FeatureService, PrefixCacheService, SessionOverrideRegistry};
 use mcpmux_storage::{
@@ -38,21 +38,18 @@ impl CloneFixture {
         let default_space = space_repo.get_default().await.unwrap().unwrap();
         let space_id = default_space.id;
 
-        let installed_server_repo: Arc<dyn InstalledServerRepository> = Arc::new(
-            SqliteInstalledServerRepository::new(db.clone(), encryptor),
-        );
+        let installed_server_repo: Arc<dyn InstalledServerRepository> =
+            Arc::new(SqliteInstalledServerRepository::new(db.clone(), encryptor));
         let feature_repo: Arc<dyn ServerFeatureRepository> =
             Arc::new(SqliteServerFeatureRepository::new(db));
 
-        let prefix_cache = Arc::new(
-            PrefixCacheService::new().with_dependencies(
-                installed_server_repo.clone(),
-                Arc::new(ServerDiscoveryService::new(
-                    std::env::temp_dir().join(format!("mcpmux-clone-test-{}", Uuid::new_v4())),
-                    std::env::temp_dir().join(format!("mcpmux-clone-spaces-{}", Uuid::new_v4())),
-                )),
-            ),
-        );
+        let prefix_cache = Arc::new(PrefixCacheService::new().with_dependencies(
+            installed_server_repo.clone(),
+            Arc::new(ServerDiscoveryService::new(
+                std::env::temp_dir().join(format!("mcpmux-clone-test-{}", Uuid::new_v4())),
+                std::env::temp_dir().join(format!("mcpmux-clone-spaces-{}", Uuid::new_v4())),
+            )),
+        ));
         let feature_service = Arc::new(FeatureService::new(
             feature_repo.clone(),
             Arc::new(tests::mocks::MockFeatureSetRepository::new()),
@@ -240,7 +237,10 @@ async fn two_clones_have_distinct_prefixes_and_env() {
         Some("work-account")
     );
     assert_eq!(
-        stored_personal.input_values.get("ACCOUNT").map(String::as_str),
+        stored_personal
+            .input_values
+            .get("ACCOUNT")
+            .map(String::as_str),
         Some("personal-account")
     );
     assert_eq!(clone_work.cloned_from.as_deref(), Some("posthog"));
@@ -272,22 +272,18 @@ async fn uninstall_clone_does_not_affect_source() {
         .await
         .expect("clone uninstall");
 
-    assert!(
-        fixture
-            .installed_server_repo
-            .get_by_server_id(&space_id_str, "posthog")
-            .await
-            .unwrap()
-            .is_some()
-    );
-    assert!(
-        fixture
-            .installed_server_repo
-            .get_by_server_id(&space_id_str, "posthog-work")
-            .await
-            .unwrap()
-            .is_none()
-    );
+    assert!(fixture
+        .installed_server_repo
+        .get_by_server_id(&space_id_str, "posthog")
+        .await
+        .unwrap()
+        .is_some());
+    assert!(fixture
+        .installed_server_repo
+        .get_by_server_id(&space_id_str, "posthog-work")
+        .await
+        .unwrap()
+        .is_none());
 }
 
 #[tokio::test(flavor = "multi_thread")]
@@ -339,11 +335,19 @@ async fn clone_prefixes_do_not_break_existing_alias_uniqueness() {
     let other = fixtures::test_installed_server(&space_id_str, "other-server")
         .with_definition(&env_stdio_definition("other-server", "Other", "api"));
 
-    fixture.installed_server_repo.install(&posthog).await.unwrap();
+    fixture
+        .installed_server_repo
+        .install(&posthog)
+        .await
+        .unwrap();
     fixture.installed_server_repo.install(&other).await.unwrap();
 
     let clone = InstalledServer::new(&space_id_str, "posthog-work")
-        .with_definition(&env_stdio_definition("posthog-work", "PostHog (work)", "work"))
+        .with_definition(&env_stdio_definition(
+            "posthog-work",
+            "PostHog (work)",
+            "work",
+        ))
         .with_cloned_from("posthog");
     fixture.installed_server_repo.install(&clone).await.unwrap();
 

From 308963b64f69b1b098ed0d769f4b8ce3dd301f44 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Sat, 23 May 2026 12:13:58 -0600
Subject: [PATCH 22/48] fix(desktop): restore custom titlebar window dragging

Replace Electron-style -webkit-app-region with Tauri 2 data-tauri-drag-region
and enable acceptFirstMouse for drag on unfocused macOS windows.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 apps/desktop/src-tauri/tauri.conf.json        |  3 ++-
 apps/desktop/src/App.tsx                      | 22 ++++++++++++-------
 apps/desktop/src/index.css                    |  5 ++++-
 .../ui/src/components/layout/AppShell.tsx     |  4 ++--
 4 files changed, 22 insertions(+), 12 deletions(-)

diff --git a/apps/desktop/src-tauri/tauri.conf.json b/apps/desktop/src-tauri/tauri.conf.json
index d3e1ab02..ffd8cc04 100644
--- a/apps/desktop/src-tauri/tauri.conf.json
+++ b/apps/desktop/src-tauri/tauri.conf.json
@@ -36,7 +36,8 @@
         "minHeight": 600,
         "center": true,
         "preventOverflow": true,
-        "decorations": false
+        "decorations": false,
+        "acceptFirstMouse": true
       }
     ],
     "security": {
diff --git a/apps/desktop/src/App.tsx b/apps/desktop/src/App.tsx
index cd953cb8..50351835 100644
--- a/apps/desktop/src/App.tsx
+++ b/apps/desktop/src/App.tsx
@@ -296,16 +296,22 @@ function AppContent() {
   );
 
   const titleBar = (
-    <div className="flex items-center gap-1.5 pl-3">
-      <McpMuxGlyph className="h-4 w-4 shrink-0" />
-      <span className="text-sm font-bold tracking-tight select-none">
-        <span style={{ color: 'var(--brand-light)' }}>Mcp</span>
-        <span style={{ color: 'var(--brand-dark)' }}>Mux</span>
-      </span>
-      <div className="mx-2 h-4 w-px bg-[rgb(var(--border))]" />
+    <div className="flex h-full w-full items-center pl-3">
+      <div
+        data-tauri-drag-region
+        className="flex h-full min-w-0 flex-1 items-center gap-1.5"
+      >
+        <McpMuxGlyph className="pointer-events-none h-4 w-4 shrink-0" />
+        <span className="pointer-events-none select-none text-sm font-bold tracking-tight">
+          <span style={{ color: 'var(--brand-light)' }}>Mcp</span>
+          <span style={{ color: 'var(--brand-dark)' }}>Mux</span>
+        </span>
+        <div className="pointer-events-none mx-2 h-4 w-px bg-[rgb(var(--border))]" />
+      </div>
       <button
+        type="button"
         onClick={toggleDarkMode}
-        className="p-1 rounded-md hover:bg-[rgb(var(--surface-hover))] transition-colors"
+        className="no-drag rounded-md p-1 transition-colors hover:bg-[rgb(var(--surface-hover))]"
         title={theme === 'dark' ? 'Light mode' : 'Dark mode'}
       >
         {theme === 'dark' ? <Sun className="h-3.5 w-3.5 text-[rgb(var(--muted))]" /> : <Moon className="h-3.5 w-3.5 text-[rgb(var(--muted))]" />}
diff --git a/apps/desktop/src/index.css b/apps/desktop/src/index.css
index 54d48ea8..0dbf714b 100644
--- a/apps/desktop/src/index.css
+++ b/apps/desktop/src/index.css
@@ -194,10 +194,13 @@
 }
 
 @layer utilities {
-  .drag-region {
+  /* Tauri 2 custom titlebar — see https://v2.tauri.app/learn/window-customization/ */
+  [data-tauri-drag-region] {
+    app-region: drag;
     -webkit-app-region: drag;
   }
   .no-drag {
+    app-region: no-drag;
     -webkit-app-region: no-drag;
   }
 
diff --git a/packages/ui/src/components/layout/AppShell.tsx b/packages/ui/src/components/layout/AppShell.tsx
index 2175e28b..994c304f 100644
--- a/packages/ui/src/components/layout/AppShell.tsx
+++ b/packages/ui/src/components/layout/AppShell.tsx
@@ -16,8 +16,8 @@ export function AppShell({ sidebar, children, statusBar, titleBar, windowControl
       {/* Custom title bar */}
       {titleBar && (
         <div className="h-9 flex-shrink-0 bg-[rgb(var(--surface))] border-b border-[rgb(var(--border-subtle))] flex items-center">
-          {/* Draggable area — fills space between logo and window controls */}
-          <div className="drag-region flex-1 h-full flex items-center">
+          {/* Draggable area — titleBar marks regions with data-tauri-drag-region (Tauri 2) */}
+          <div className="flex-1 h-full flex items-center min-w-0">
             {titleBar}
           </div>
           {/* Window controls — outside drag region so clicks work */}

From 36a4922696786f66add7e3fbe4d37820e83b641d Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Sat, 23 May 2026 13:28:28 -0600
Subject: [PATCH 23/48] feat(desktop): add copy-all to server log viewer

Also reconcile May 23 closeout notes in meta-tools and account-clones
planning docs.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 .../src/components/ServerLogViewer.tsx        | 64 ++++++++++++++++---
 .../planning/dynamic-mcp-toggle-meta-tools.md |  9 ++-
 docs/planning/server-account-clones.md        |  6 +-
 3 files changed, 64 insertions(+), 15 deletions(-)

diff --git a/apps/desktop/src/components/ServerLogViewer.tsx b/apps/desktop/src/components/ServerLogViewer.tsx
index 7905496d..8524867f 100644
--- a/apps/desktop/src/components/ServerLogViewer.tsx
+++ b/apps/desktop/src/components/ServerLogViewer.tsx
@@ -1,5 +1,5 @@
 import { useEffect, useState, useRef } from 'react';
-import { X, Download, Trash2, RefreshCw } from 'lucide-react';
+import { X, Download, Trash2, RefreshCw, Copy } from 'lucide-react';
 import { useToast, ToastContainer, useConfirm } from '@mcpmux/ui';
 import { getServerLogs, clearServerLogs, getServerLogFile, type ServerLogEntry } from '@/lib/api/logs';
 
@@ -32,6 +32,30 @@ const SOURCE_COLORS: Record<string, string> = {
   server: 'text-cyan-400',
 };
 
+/**
+ * Formats an ISO timestamp for log display and export.
+ */
+function formatTimestamp(ts: string): string {
+  const date = new Date(ts);
+  const hours = date.getHours().toString().padStart(2, '0');
+  const minutes = date.getMinutes().toString().padStart(2, '0');
+  const seconds = date.getSeconds().toString().padStart(2, '0');
+  const ms = date.getMilliseconds().toString().padStart(3, '0');
+  return `${hours}:${minutes}:${seconds}.${ms}`;
+}
+
+/**
+ * Formats a log entry as a single plain-text line for display export.
+ */
+function formatLogLine(log: ServerLogEntry): string {
+  const level = log.level.toUpperCase().padEnd(5);
+  const base = `${formatTimestamp(log.timestamp)}  ${level}  ${log.source}  ${log.message}`;
+  if (!log.metadata) {
+    return base;
+  }
+  return `${base}  ${JSON.stringify(log.metadata)}`;
+}
+
 export function ServerLogViewer({ serverId, serverName, onClose }: ServerLogViewerProps) {
   const [logs, setLogs] = useState<ServerLogEntry[]>([]);
   const [loading, setLoading] = useState(true);
@@ -122,15 +146,6 @@ export function ServerLogViewer({ serverId, serverName, onClose }: ServerLogView
     }
   };
 
-  const formatTimestamp = (ts: string) => {
-    const date = new Date(ts);
-    const hours = date.getHours().toString().padStart(2, '0');
-    const minutes = date.getMinutes().toString().padStart(2, '0');
-    const seconds = date.getSeconds().toString().padStart(2, '0');
-    const ms = date.getMilliseconds().toString().padStart(3, '0');
-    return `${hours}:${minutes}:${seconds}.${ms}`;
-  };
-
   const filteredLogs = logs.filter(log => {
     if (levelFilter === 'all') return true;
     const logLevelIndex = LOG_LEVELS.indexOf(log.level as LogLevel);
@@ -138,6 +153,25 @@ export function ServerLogViewer({ serverId, serverName, onClose }: ServerLogView
     return logLevelIndex >= filterLevelIndex;
   });
 
+  /** Copies all currently visible (filtered) log lines to the clipboard. */
+  const handleCopyAll = async () => {
+    if (filteredLogs.length === 0) {
+      showError('Nothing to copy', 'No logs match the current filter');
+      return;
+    }
+
+    try {
+      const text = filteredLogs.map((log) => formatLogLine(log)).join('\n');
+      await navigator.clipboard.writeText(text);
+      success(
+        'Logs copied',
+        `${filteredLogs.length} log${filteredLogs.length !== 1 ? 's' : ''} copied to clipboard`
+      );
+    } catch (e) {
+      showError('Failed to copy logs', e instanceof Error ? e.message : String(e));
+    }
+  };
+
   return (
     <div className="fixed inset-0 z-50 flex items-center justify-center bg-black/50">
       <ToastContainer toasts={toasts} onClose={dismiss} />
@@ -195,6 +229,16 @@ export function ServerLogViewer({ serverId, serverName, onClose }: ServerLogView
             >
               <Download className="h-4 w-4" />
             </button>
+
+            {/* Copy All */}
+            <button
+              onClick={handleCopyAll}
+              disabled={filteredLogs.length === 0}
+              className="p-1.5 rounded-lg hover:bg-[rgb(var(--surface-hover))] transition-colors disabled:opacity-40 disabled:pointer-events-none"
+              title="Copy all visible logs to clipboard"
+            >
+              <Copy className="h-4 w-4" />
+            </button>
             
             {/* Clear Logs */}
             <button
diff --git a/docs/planning/dynamic-mcp-toggle-meta-tools.md b/docs/planning/dynamic-mcp-toggle-meta-tools.md
index 5556e658..540080c6 100644
--- a/docs/planning/dynamic-mcp-toggle-meta-tools.md
+++ b/docs/planning/dynamic-mcp-toggle-meta-tools.md
@@ -1,7 +1,7 @@
 # Dynamic MCP Toggling via Meta Tools
 
-**Last Updated:** May 19, 2026
-**Status:** Feature complete — pending validation + PR
+**Last Updated:** May 23, 2026
+**Status:** Feature complete on fork — session grants + structuredContent fixes verified; pending upstream PR merge
 **Branch:** `feat/dynamic-mcp-toggle-meta-tools`
 **Base branch:** `feat/workspace-root-routing` ([upstream PR #151](https://github.com/mcpmux/mcp-mux/pull/151))
 **Issue:** TBD — file after planning review
@@ -298,6 +298,7 @@ Optional (slow / env-dependent): `pnpm test:e2e`, `pnpm test:e2e:web`.
 
 - [mcpmux/mcp-mux PR #151](https://github.com/mcpmux/mcp-mux/pull/151) — workspace-root-driven FeatureSet routing + the `mcpmux_*` meta-tool namespace this PR builds on. Must merge (or be consumed via fork) first.
 - [`docs/planning/issue-52-secret-text-input-syntax.md`](./issue-52-secret-text-input-syntax.md) — sibling planning doc; same conventions used here. Independent feature, no functional overlap.
+- [`docs/planning/server-account-clones.md`](./server-account-clones.md) — multi-account installs via UI clone; branched after meta-tools + gateway fixes.
 - [`jsg-tech-check` homelab plan](../../../jsg-tech-check/docs/setup/home-lab-overview.md#mcp-strategy--current-state) — the consuming use case. The "Personal vs Work" Spaces + bundled `set-times-app` / `sync2hire-platform` model leans on bindings; this doc adds the "no, actually just enable this one MCP for the next 10 minutes" escape valve.
 - [MCP spec — Tools `list_changed`](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#list-changed-notification) — the protocol mechanism that makes the post-write tool-list refresh observable mid-conversation. Already wired by PR #151.
 
@@ -307,8 +308,10 @@ Optional (slow / env-dependent): `pnpm test:e2e`, `pnpm test:e2e:web`.
 
 This doc is the source of truth for what gets built. When implementation completes, update the **Status** field at the top and reconcile any deviations (extra files, dropped phases, scope changes) per [`update-planning-md`](~/.cursor/commands/update-planning-md.md).
 
-**May 19, 2026 closeout:**
+**May 23, 2026 closeout:**
 - Phases 1–5 implemented on `feat/dynamic-mcp-toggle-meta-tools`.
+- Post-ship fixes on same branch: session-grant routing in `call_tool` (`5269a18`), `structuredContent` forwarding for proxied tool results (`d519a79`) — required for Google Workspace MCP through mux.
 - Tauri commands landed in `session_overrides.rs` (not `workspace_binding.rs` as originally planned).
 - CHANGELOG handled by release-please; README updated in-repo.
 - Pre-PR validation gate documented above; PR blocked until validate + tests + build pass.
+- Follow-on: [server-account-clones.md](./server-account-clones.md) branched from this work for multi-account migration.
diff --git a/docs/planning/server-account-clones.md b/docs/planning/server-account-clones.md
index 83c91ee7..603fab2b 100644
--- a/docs/planning/server-account-clones.md
+++ b/docs/planning/server-account-clones.md
@@ -1,8 +1,8 @@
 # Server Account Clones (UI-Assisted Multi-Account)
 
 **Last Updated:** May 23, 2026
-**Status:** In progress — Phases 1–4 complete, Phase 5 optional
-**Branch:** `feat/server-account-clones`
+**Status:** Complete — Phases 1–4 shipped; Phase 5 (first-class instances) optional/deferred
+**Branch:** `feat/server-account-clones` (merged or ready to merge)
 **Base branch:** `main`
 **Issue:** TBD — file after planning review
 **Depends on:** None (orthogonal to session meta-tools; benefits from but does not require PR #154)
@@ -266,3 +266,5 @@ Multi-account need?
 This doc is the source of truth for server account clones. When implementation starts, update **Status** and **Branch** at the top. Phase 5 remains optional — do not block Phases 1–4 on it.
 
 **Decision record (May 23, 2026):** Option 2 (UI-assisted clone) selected over status quo, first-class instances (deferred Phase 5), per-client credential override (rejected), and wrapper meta-servers (rejected). Brainstorm source: Cursor session on multi-account MCP patterns.
+
+**May 23, 2026 closeout:** Phases 1–4 implemented and verified in dev. Consumed by [mcpmux-server-migration.md](../../../jsg-tech-check/docs/setup/mcpmux-server-migration.md) Phase B2 (clone sprint). Phase 5 remains optional until clone ID sprawl or FeatureSet grouping pain justifies schema migration.

From 8ff352bbf7198787d18c35cd70ee2a0c9ea00218 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Sat, 23 May 2026 14:04:16 -0600
Subject: [PATCH 24/48] feat(desktop): expand/collapse all servers and disable
 on error

Add My Servers header controls to expand or collapse connected rows,
and show Disable alongside Retry when a server is stuck in error state.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 .../src/features/servers/ServersPage.tsx      | 77 ++++++++++++++++---
 1 file changed, 68 insertions(+), 9 deletions(-)

diff --git a/apps/desktop/src/features/servers/ServersPage.tsx b/apps/desktop/src/features/servers/ServersPage.tsx
index b2341730..0c390bf4 100644
--- a/apps/desktop/src/features/servers/ServersPage.tsx
+++ b/apps/desktop/src/features/servers/ServersPage.tsx
@@ -19,6 +19,8 @@ import {
   Clock,
   FileJson,
   FolderOpen,
+  UnfoldVertical,
+  FoldVertical,
 } from 'lucide-react';
 import { ServerActionMenu } from './ServerActionMenu';
 import { CloneAccountModal } from './CloneAccountModal';
@@ -525,6 +527,31 @@ export function ServersPage() {
     return 'connected_auto';
   };
 
+  /** Connected servers that show the expand/collapse chevron in the list. */
+  const isServerExpandable = (server: ServerViewModel): boolean => {
+    const action = getServerAction(server);
+    return action === 'running' || action === 'connected_auto';
+  };
+
+  /** Expands every connected server row and loads features for any not yet fetched. */
+  const expandAllServers = () => {
+    const expandableIds = installedServers.filter(isServerExpandable).map((s) => s.id);
+    setExpandedServers(new Set(expandableIds));
+    for (const serverId of expandableIds) {
+      if (!serverFeatures[serverId]) {
+        loadFeaturesForServer(serverId);
+      }
+    }
+  };
+
+  /** Collapses every expanded server row. */
+  const collapseAllServers = () => {
+    setExpandedServers(new Set());
+  };
+
+  const expandableServerCount = installedServers.filter(isServerExpandable).length;
+  const hasExpandedServers = expandedServers.size > 0;
+
   // Get display status for UI
   const getDisplayStatus = (server: ServerViewModel): string => {
     const action = getServerAction(server);
@@ -1029,13 +1056,42 @@ export function ServersPage() {
           </p>
         </div>
         {viewSpace && (
-          <button
-            onClick={() => setEditConfigSpace({ id: viewSpace.id, name: viewSpace.name })}
-            className="flex items-center gap-2 px-4 py-2.5 text-sm font-medium rounded-lg bg-[rgb(var(--surface-elevated))] border border-[rgb(var(--border))] hover:bg-[rgb(var(--surface-hover))] hover:border-[rgb(var(--border-subtle))] shadow-sm hover:shadow transition-all"
-          >
-            <FileJson className="h-4 w-4 text-[rgb(var(--primary))]" />
-            Add Custom Server
-          </button>
+          <div className="flex items-center gap-2">
+            {installedServers.length > 0 && (
+              <>
+                <button
+                  type="button"
+                  onClick={expandAllServers}
+                  disabled={expandableServerCount === 0}
+                  className="flex items-center gap-2 px-3 py-2.5 text-sm font-medium rounded-lg bg-[rgb(var(--surface-elevated))] border border-[rgb(var(--border))] hover:bg-[rgb(var(--surface-hover))] hover:border-[rgb(var(--border-subtle))] shadow-sm hover:shadow transition-all disabled:opacity-40 disabled:pointer-events-none"
+                  title="Expand all connected servers"
+                  data-testid="expand-all-servers"
+                >
+                  <UnfoldVertical className="h-4 w-4 text-[rgb(var(--muted))]" />
+                  Expand all
+                </button>
+                <button
+                  type="button"
+                  onClick={collapseAllServers}
+                  disabled={!hasExpandedServers}
+                  className="flex items-center gap-2 px-3 py-2.5 text-sm font-medium rounded-lg bg-[rgb(var(--surface-elevated))] border border-[rgb(var(--border))] hover:bg-[rgb(var(--surface-hover))] hover:border-[rgb(var(--border-subtle))] shadow-sm hover:shadow transition-all disabled:opacity-40 disabled:pointer-events-none"
+                  title="Collapse all servers"
+                  data-testid="collapse-all-servers"
+                >
+                  <FoldVertical className="h-4 w-4 text-[rgb(var(--muted))]" />
+                  Collapse all
+                </button>
+              </>
+            )}
+            <button
+              type="button"
+              onClick={() => setEditConfigSpace({ id: viewSpace.id, name: viewSpace.name })}
+              className="flex items-center gap-2 px-4 py-2.5 text-sm font-medium rounded-lg bg-[rgb(var(--surface-elevated))] border border-[rgb(var(--border))] hover:bg-[rgb(var(--surface-hover))] hover:border-[rgb(var(--border-subtle))] shadow-sm hover:shadow transition-all"
+            >
+              <FileJson className="h-4 w-4 text-[rgb(var(--primary))]" />
+              Add Custom Server
+            </button>
+          </div>
         )}
       </div>
 
@@ -1321,8 +1377,11 @@ export function ServersPage() {
                         </button>
                       )}
 
-                      {/* Disable button - shown when enabled and connected/running */}
-                      {server.enabled && (serverAction === 'running' || serverAction === 'connected_auto') && (
+                      {/* Disable button - enabled servers that are connected, idle, or stuck in error */}
+                      {server.enabled &&
+                        (serverAction === 'running' ||
+                          serverAction === 'connected_auto' ||
+                          serverAction === 'error') && (
                         <button
                           onClick={() => handleDisableClick(server)}
                           disabled={disableLoading}

From b641acd95bdf983a6a7b0974ee702eea8d0ac9c3 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 09:33:40 -0600
Subject: [PATCH 25/48] feat(desktop): My Servers search, filters popover, and
 shared UI primitives

Add DropdownMenu, ChipButton, SearchField, and HoverTooltip to @mcpmux/ui.
Refactor My Servers with transport/status filters, tool-aware search,
row-click expand, inline gateway status, and Add Server discover/custom menu.

Signed-off-by: Joe Sangiorgio <jsangio1@gmail.com>
Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 apps/desktop/src/components/Contribute.tsx    |  77 ++---
 .../src/features/servers/AddServerMenu.tsx    |  48 +++
 .../src/features/servers/ServerActionMenu.tsx | 227 +++++----------
 .../servers/ServersFiltersPopover.tsx         | 144 +++++++++
 .../src/features/servers/ServersPage.tsx      | 273 +++++++++++++-----
 .../features/servers/servers-page.helpers.ts  | 166 +++++++++++
 .../ui/src/components/common/ChipButton.tsx   |  44 +++
 .../ui/src/components/common/DropdownMenu.tsx | 259 +++++++++++++++++
 .../ui/src/components/common/HoverTooltip.tsx |  49 ++++
 .../ui/src/components/common/SearchField.tsx  |  50 ++++
 packages/ui/src/hooks/useClickOutside.ts      |  27 ++
 packages/ui/src/index.ts                      |  21 ++
 12 files changed, 1093 insertions(+), 292 deletions(-)
 create mode 100644 apps/desktop/src/features/servers/AddServerMenu.tsx
 create mode 100644 apps/desktop/src/features/servers/ServersFiltersPopover.tsx
 create mode 100644 apps/desktop/src/features/servers/servers-page.helpers.ts
 create mode 100644 packages/ui/src/components/common/ChipButton.tsx
 create mode 100644 packages/ui/src/components/common/DropdownMenu.tsx
 create mode 100644 packages/ui/src/components/common/HoverTooltip.tsx
 create mode 100644 packages/ui/src/components/common/SearchField.tsx
 create mode 100644 packages/ui/src/hooks/useClickOutside.ts

diff --git a/apps/desktop/src/components/Contribute.tsx b/apps/desktop/src/components/Contribute.tsx
index b6ba1acf..f8f4ed93 100644
--- a/apps/desktop/src/components/Contribute.tsx
+++ b/apps/desktop/src/components/Contribute.tsx
@@ -1,6 +1,11 @@
-import { useEffect, useRef, useState } from 'react';
 import { Bug, Github, Heart, Lightbulb, Package, SendHorizontal } from 'lucide-react';
-import { Button } from '@mcpmux/ui';
+import {
+  Button,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@mcpmux/ui';
 import { CONTRIBUTE, openExternal } from '@/lib/contribute';
 
 /**
@@ -71,18 +76,6 @@ export function ContributeMenu({
   variant?: 'primary' | 'secondary' | 'ghost';
   size?: 'sm' | 'md';
 }) {
-  const [open, setOpen] = useState(false);
-  const ref = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    if (!open) return;
-    const handler = (e: MouseEvent) => {
-      if (ref.current && !ref.current.contains(e.target as Node)) setOpen(false);
-    };
-    document.addEventListener('mousedown', handler);
-    return () => document.removeEventListener('mousedown', handler);
-  }, [open]);
-
   const items = [
     {
       label: 'Request a new server',
@@ -111,42 +104,24 @@ export function ContributeMenu({
   ];
 
   return (
-    <div className="relative inline-block" ref={ref}>
-      <Button
-        variant={variant}
-        size={size}
-        onClick={() => setOpen((v) => !v)}
-        data-testid="contribute-menu-trigger"
-      >
-        <Heart className="h-4 w-4 mr-1.5" />
-        Contribute
-      </Button>
-      {open && (
-        <div
-          className="absolute right-0 mt-2 z-20 w-72 rounded-xl border border-[rgb(var(--border))] bg-white dark:bg-zinc-900 shadow-xl p-1"
-          data-testid="contribute-menu"
-        >
-          {items.map((item) => (
-            <button
-              key={item.label}
-              type="button"
-              onClick={() => {
-                setOpen(false);
-                openExternal(item.href);
-              }}
-              className="w-full text-left flex items-start gap-3 px-3 py-2.5 rounded-lg hover:bg-[rgb(var(--surface))] transition-colors"
-            >
-              <item.icon className="h-4 w-4 mt-0.5 text-[rgb(var(--muted))] flex-shrink-0" />
-              <div className="flex-1 min-w-0">
-                <p className="text-sm font-medium">{item.label}</p>
-                <p className="text-[11px] text-[rgb(var(--muted))] leading-snug">
-                  {item.caption}
-                </p>
-              </div>
-            </button>
-          ))}
-        </div>
-      )}
-    </div>
+    <DropdownMenu>
+      <DropdownMenuTrigger data-testid="contribute-menu-trigger">
+        <Button variant={variant} size={size} type="button">
+          <Heart className="h-4 w-4 mr-1.5" />
+          Contribute
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="w-72 p-1.5" data-testid="contribute-menu">
+        {items.map((item) => (
+          <DropdownMenuItem
+            key={item.label}
+            icon={item.icon}
+            label={item.label}
+            description={item.caption}
+            onSelect={() => openExternal(item.href)}
+          />
+        ))}
+      </DropdownMenuContent>
+    </DropdownMenu>
   );
 }
diff --git a/apps/desktop/src/features/servers/AddServerMenu.tsx b/apps/desktop/src/features/servers/AddServerMenu.tsx
new file mode 100644
index 00000000..15bafe2d
--- /dev/null
+++ b/apps/desktop/src/features/servers/AddServerMenu.tsx
@@ -0,0 +1,48 @@
+import { ChevronDown, Compass, FileJson, Plus } from 'lucide-react';
+import {
+  Button,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from '@mcpmux/ui';
+
+interface AddServerMenuProps {
+  /** Opens the Discover page to browse the community server registry. */
+  onDiscover: () => void;
+  /** Opens the Space JSON editor to add a custom server definition. */
+  onCustom: () => void;
+}
+
+/**
+ * Dropdown for the two ways to add MCP servers: registry discover vs custom JSON.
+ */
+export function AddServerMenu({ onDiscover, onCustom }: AddServerMenuProps) {
+  return (
+    <DropdownMenu>
+      <DropdownMenuTrigger data-testid="add-server-menu-trigger">
+        <Button variant="primary" size="md" type="button">
+          <Plus className="h-4 w-4" />
+          Add Server
+          <ChevronDown className="h-4 w-4" />
+        </Button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="w-80 p-1.5" data-testid="add-server-menu">
+        <DropdownMenuItem
+          icon={Compass}
+          label="Discover from registry"
+          description="Browse the community catalog — install with guided setup, OAuth, and credential fields."
+          onSelect={onDiscover}
+          data-testid="add-server-option-discover"
+        />
+        <DropdownMenuItem
+          icon={FileJson}
+          label="Add custom server"
+          description="Edit your Space JSON config for local CLIs, private servers, or anything not in the registry."
+          onSelect={onCustom}
+          data-testid="add-server-option-custom"
+        />
+      </DropdownMenuContent>
+    </DropdownMenu>
+  );
+}
diff --git a/apps/desktop/src/features/servers/ServerActionMenu.tsx b/apps/desktop/src/features/servers/ServerActionMenu.tsx
index fe85261f..6e0116e4 100644
--- a/apps/desktop/src/features/servers/ServerActionMenu.tsx
+++ b/apps/desktop/src/features/servers/ServerActionMenu.tsx
@@ -1,17 +1,11 @@
-/**
- * ServerActionMenu - Overflow menu for server actions
- * 
- * Actions:
- * - Configure: Edit server inputs
- * - Refresh: Quick reconnect with existing credentials
- * - Reconnect: Logout + re-authenticate (OAuth only)
- * - View Logs: Open log viewer
- * - View Definition: View server definition JSON
- * - Uninstall: Remove server
- */
-
-import { useState, useRef, useEffect } from 'react';
 import { MoreVertical, Settings, RefreshCw, RotateCcw, FileText, Code, Trash2, Copy } from 'lucide-react';
+import {
+  DropdownMenu,
+  DropdownMenuAction,
+  DropdownMenuContent,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '@mcpmux/ui';
 
 export interface ServerActionMenuProps {
   serverId: string;
@@ -31,6 +25,9 @@ export interface ServerActionMenuProps {
   onUninstall: () => void;
 }
 
+/**
+ * Overflow menu for per-server actions (configure, logs, uninstall, etc.).
+ */
 export function ServerActionMenu({
   serverId,
   serverName: _serverName,
@@ -47,155 +44,63 @@ export function ServerActionMenu({
   onCloneAccount,
   onUninstall,
 }: ServerActionMenuProps) {
-  const [isOpen, setIsOpen] = useState(false);
-  const menuRef = useRef<HTMLDivElement>(null);
-  const buttonRef = useRef<HTMLButtonElement>(null);
-
-  // Close menu when clicking outside
-  useEffect(() => {
-    function handleClickOutside(event: MouseEvent) {
-      if (
-        menuRef.current &&
-        !menuRef.current.contains(event.target as Node) &&
-        buttonRef.current &&
-        !buttonRef.current.contains(event.target as Node)
-      ) {
-        setIsOpen(false);
-      }
-    }
-
-    if (isOpen) {
-      document.addEventListener('mousedown', handleClickOutside);
-      return () => document.removeEventListener('mousedown', handleClickOutside);
-    }
-  }, [isOpen]);
-
-  // Close menu on escape
-  useEffect(() => {
-    function handleEscape(event: KeyboardEvent) {
-      if (event.key === 'Escape') {
-        setIsOpen(false);
-      }
-    }
-
-    if (isOpen) {
-      document.addEventListener('keydown', handleEscape);
-      return () => document.removeEventListener('keydown', handleEscape);
-    }
-  }, [isOpen]);
-
-  const handleAction = (action: () => void) => {
-    setIsOpen(false);
-    action();
-  };
-
   return (
-    <div className="relative">
-      <button
-        ref={buttonRef}
-        onClick={() => setIsOpen(!isOpen)}
-        className="p-2 text-sm rounded-lg bg-[rgb(var(--surface-hover))] border border-[rgb(var(--border))] text-[rgb(var(--foreground))]/70 hover:bg-[rgb(var(--surface-elevated))] hover:text-[rgb(var(--foreground))] transition-colors"
-        title="More actions"
-        aria-label="More actions"
-        aria-expanded={isOpen}
-        aria-haspopup="menu"
-        data-testid={`action-menu-${serverId}`}
-      >
-        <MoreVertical className="h-4 w-4" />
-      </button>
-
-      {isOpen && (
-        <div
-          ref={menuRef}
-          className="absolute right-0 mt-1 w-48 py-1 bg-[rgb(var(--surface-elevated))] border border-[rgb(var(--border))] rounded-lg shadow-lg z-50 animate-in fade-in slide-in-from-top-1 duration-150"
-          role="menu"
+    <DropdownMenu>
+      <DropdownMenuTrigger>
+        <button
+          type="button"
+          className="p-2 text-sm rounded-lg bg-[rgb(var(--surface-hover))] border border-[rgb(var(--border))] text-[rgb(var(--foreground))]/70 hover:bg-[rgb(var(--surface-elevated))] hover:text-[rgb(var(--foreground))] transition-colors"
+          title="More actions"
+          aria-label="More actions"
+          data-testid={`action-menu-${serverId}`}
         >
-          {/* Configure - visible if server has inputs */}
-          {hasInputs && (
-            <button
-              onClick={() => handleAction(onConfigure)}
-              className="w-full flex items-center gap-2 px-3 py-2 text-sm text-[rgb(var(--foreground))] hover:bg-[rgb(var(--surface-hover))] transition-colors"
-              role="menuitem"
-            >
-              <Settings className="h-4 w-4 text-[rgb(var(--muted))]" />
-              Configure
-            </button>
-          )}
-
-          {/* Refresh - visible when enabled (quick reconnect with existing creds) */}
-          {isEnabled && (
-            <button
-              onClick={() => handleAction(onRefresh)}
-              className="w-full flex items-center gap-2 px-3 py-2 text-sm text-[rgb(var(--foreground))] hover:bg-[rgb(var(--surface-hover))] transition-colors"
-              role="menuitem"
-            >
-              <RefreshCw className="h-4 w-4 text-[rgb(var(--muted))]" />
-              Refresh
-            </button>
-          )}
-
-          {/* Reconnect - OAuth only (logout + re-auth) */}
-          {isOAuth && isEnabled && (
-            <button
-              onClick={() => handleAction(onReconnect)}
-              className="w-full flex items-center gap-2 px-3 py-2 text-sm text-[rgb(var(--warning))] hover:bg-[rgb(var(--surface-hover))] transition-colors"
-              role="menuitem"
-            >
-              <RotateCcw className="h-4 w-4" />
-              Reconnect
-            </button>
-          )}
-
-          {/* View Logs - always visible */}
-          <button
-            onClick={() => handleAction(onViewLogs)}
-            className="w-full flex items-center gap-2 px-3 py-2 text-sm text-[rgb(var(--foreground))] hover:bg-[rgb(var(--surface-hover))] transition-colors"
-            role="menuitem"
-            data-testid={`view-logs-${serverId}`}
-          >
-            <FileText className="h-4 w-4 text-[rgb(var(--muted))]" />
-            View Logs
-          </button>
-
-          {/* View Definition - always visible */}
-          <button
-            onClick={() => handleAction(onViewDefinition)}
-            className="w-full flex items-center gap-2 px-3 py-2 text-sm text-[rgb(var(--foreground))] hover:bg-[rgb(var(--surface-hover))] transition-colors"
-            role="menuitem"
-            data-testid={`view-definition-${serverId}`}
-          >
-            <Code className="h-4 w-4 text-[rgb(var(--muted))]" />
-            View Definition
-          </button>
-
-          {/* Add another account - registry/manual installs only, not clones-of-clones */}
-          {canCloneAccount && onCloneAccount && (
-            <button
-              onClick={() => handleAction(onCloneAccount)}
-              className="w-full flex items-center gap-2 px-3 py-2 text-sm text-[rgb(var(--foreground))] hover:bg-[rgb(var(--surface-hover))] transition-colors"
-              role="menuitem"
-              data-testid={`clone-account-${serverId}`}
-            >
-              <Copy className="h-4 w-4 text-[rgb(var(--muted))]" />
-              Add another account…
-            </button>
-          )}
-
-          {/* Separator */}
-          <div className="my-1 border-t border-[rgb(var(--border-subtle))]" />
-
-          {/* Uninstall - always visible, destructive */}
-          <button
-            onClick={() => handleAction(onUninstall)}
-            className="w-full flex items-center gap-2 px-3 py-2 text-sm text-[rgb(var(--error))] hover:bg-[rgb(var(--error))]/10 transition-colors"
-            role="menuitem"
-            data-testid={`uninstall-menu-${serverId}`}
-          >
-            <Trash2 className="h-4 w-4" />
-            Uninstall
-          </button>
-        </div>
-      )}
-    </div>
+          <MoreVertical className="h-4 w-4" />
+        </button>
+      </DropdownMenuTrigger>
+      <DropdownMenuContent align="end" className="w-48 py-1 p-1">
+        {hasInputs && (
+          <DropdownMenuAction icon={Settings} label="Configure" onSelect={onConfigure} />
+        )}
+        {isEnabled && (
+          <DropdownMenuAction icon={RefreshCw} label="Refresh" onSelect={onRefresh} />
+        )}
+        {isOAuth && isEnabled && (
+          <DropdownMenuAction
+            icon={RotateCcw}
+            label="Reconnect"
+            onSelect={onReconnect}
+            variant="warning"
+          />
+        )}
+        <DropdownMenuAction
+          icon={FileText}
+          label="View Logs"
+          onSelect={onViewLogs}
+          data-testid={`view-logs-${serverId}`}
+        />
+        <DropdownMenuAction
+          icon={Code}
+          label="View Definition"
+          onSelect={onViewDefinition}
+          data-testid={`view-definition-${serverId}`}
+        />
+        {canCloneAccount && onCloneAccount && (
+          <DropdownMenuAction
+            icon={Copy}
+            label="Add another account…"
+            onSelect={onCloneAccount}
+            data-testid={`clone-account-${serverId}`}
+          />
+        )}
+        <DropdownMenuSeparator />
+        <DropdownMenuAction
+          icon={Trash2}
+          label="Uninstall"
+          onSelect={onUninstall}
+          variant="danger"
+          data-testid={`uninstall-menu-${serverId}`}
+        />
+      </DropdownMenuContent>
+    </DropdownMenu>
   );
 }
diff --git a/apps/desktop/src/features/servers/ServersFiltersPopover.tsx b/apps/desktop/src/features/servers/ServersFiltersPopover.tsx
new file mode 100644
index 00000000..5c803255
--- /dev/null
+++ b/apps/desktop/src/features/servers/ServersFiltersPopover.tsx
@@ -0,0 +1,144 @@
+import { useState } from 'react';
+import { ChevronDown, SlidersHorizontal } from 'lucide-react';
+import {
+  Button,
+  ChipButton,
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuTrigger,
+  HoverTooltip,
+} from '@mcpmux/ui';
+import {
+  STATUS_FILTERS,
+  TRANSPORT_FILTERS,
+  countActiveServerFilters,
+  describeAppliedServerFilters,
+  type StatusFilterKey,
+  type TransportFilter,
+} from './servers-page.helpers';
+
+interface ServersFiltersPopoverProps {
+  transportFilter: TransportFilter;
+  onTransportFilterChange: (filter: TransportFilter) => void;
+  activeStatusFilters: Set<StatusFilterKey>;
+  onToggleStatusFilter: (statusKey: StatusFilterKey) => void;
+  onClearStatusFilters: () => void;
+  onClearAllFilters: () => void;
+}
+
+/**
+ * Popover for transport (stdio/http) and Beeper-style multi-select status filters.
+ */
+export function ServersFiltersPopover({
+  transportFilter,
+  onTransportFilterChange,
+  activeStatusFilters,
+  onToggleStatusFilter,
+  onClearStatusFilters,
+  onClearAllFilters,
+}: ServersFiltersPopoverProps) {
+  const [open, setOpen] = useState(false);
+  const activeCount = countActiveServerFilters(transportFilter, activeStatusFilters);
+  const appliedFilterLines = describeAppliedServerFilters(transportFilter, activeStatusFilters);
+
+  return (
+    <HoverTooltip
+      title="Applied filters"
+      lines={appliedFilterLines}
+      hidden={open}
+      data-testid="servers-filters-tooltip"
+      className="flex-shrink-0"
+    >
+      <DropdownMenu open={open} onOpenChange={setOpen}>
+        <DropdownMenuTrigger data-testid="servers-filters-trigger">
+          <Button
+            variant="secondary"
+            size="md"
+            type="button"
+            className={
+              activeCount > 0
+                ? 'bg-[rgb(var(--primary))]/10 text-[rgb(var(--primary))] border-[rgb(var(--primary))]/40'
+                : undefined
+            }
+          >
+            <SlidersHorizontal className="h-4 w-4" />
+            Filters
+            {activeCount > 0 && (
+              <span
+                className="min-w-[1.25rem] px-1.5 py-0.5 text-xs font-semibold rounded-full bg-[rgb(var(--primary))] text-[rgb(var(--primary-foreground))]"
+                data-testid="servers-filters-count"
+              >
+                {activeCount}
+              </span>
+            )}
+            <ChevronDown
+              className={`h-4 w-4 text-[rgb(var(--muted))] transition-transform ${open ? 'rotate-180' : ''}`}
+            />
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end" className="w-72 p-4 space-y-4" data-testid="servers-filters-popover">
+          <div className="space-y-2">
+            <p className="text-xs font-medium text-[rgb(var(--muted))]">Transport</p>
+            <div className="flex flex-wrap gap-2">
+              {TRANSPORT_FILTERS.map((filter) => (
+                <ChipButton
+                  key={filter.id}
+                  active={transportFilter === filter.id}
+                  variant="fill"
+                  onClick={() => onTransportFilterChange(filter.id)}
+                  data-testid={`servers-transport-filter-${filter.id}`}
+                >
+                  {filter.label}
+                </ChipButton>
+              ))}
+            </div>
+          </div>
+
+          <div className="space-y-2">
+            <p className="text-xs font-medium text-[rgb(var(--muted))]">Status</p>
+            <div className="flex flex-wrap gap-2">
+              <ChipButton
+                active={activeStatusFilters.size === 0}
+                variant="fill"
+                onClick={onClearStatusFilters}
+                data-testid="servers-status-filter-all"
+              >
+                All
+              </ChipButton>
+              {STATUS_FILTERS.map((filter) => (
+                <ChipButton
+                  key={filter.id}
+                  active={activeStatusFilters.has(filter.id)}
+                  variant="outline"
+                  onClick={() => onToggleStatusFilter(filter.id)}
+                  data-testid={`servers-status-filter-${filter.id}`}
+                >
+                  {filter.label}
+                </ChipButton>
+              ))}
+            </div>
+            <p className="text-xs text-[rgb(var(--muted))]">
+              Combine status filters (e.g. Connected + Error). All = no status filter.
+            </p>
+          </div>
+
+          {activeCount > 0 && (
+            <Button
+              variant="ghost"
+              size="sm"
+              type="button"
+              className="w-full"
+              onClick={() => {
+                onClearAllFilters();
+                setOpen(false);
+              }}
+              data-testid="servers-filters-clear-all"
+            >
+              Clear all filters
+            </Button>
+          )}
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </HoverTooltip>
+  );
+}
diff --git a/apps/desktop/src/features/servers/ServersPage.tsx b/apps/desktop/src/features/servers/ServersPage.tsx
index 0c390bf4..d7016e65 100644
--- a/apps/desktop/src/features/servers/ServersPage.tsx
+++ b/apps/desktop/src/features/servers/ServersPage.tsx
@@ -21,13 +21,24 @@ import {
   FolderOpen,
   UnfoldVertical,
   FoldVertical,
+  Search,
 } from 'lucide-react';
+import { Button, SearchField } from '@mcpmux/ui';
 import { ServerActionMenu } from './ServerActionMenu';
 import { CloneAccountModal } from './CloneAccountModal';
+import { AddServerMenu } from './AddServerMenu';
+import { ServersFiltersPopover } from './ServersFiltersPopover';
 import { UninstallSourceWithClonesDialog } from './UninstallSourceWithClonesDialog';
 import type { ServerViewModel, ServerDefinition, InstalledServerState, InputDefinition } from '../../types/registry';
 import type { ServerFeature } from '@/lib/api/serverFeatures';
-import { listServerFeaturesByServer } from '@/lib/api/serverFeatures';
+import { listServerFeatures, listServerFeaturesByServer } from '@/lib/api/serverFeatures';
+import {
+  groupFeaturesByServerId,
+  serverMatchesFilters,
+  type ServerActionKey,
+  type StatusFilterKey,
+  type TransportFilter,
+} from './servers-page.helpers';
 import type { ConnectionStatus, ServerStatusResponse } from '@/lib/api/serverManager';
 import { getServerStatuses as fetchServerStatuses } from '@/lib/api/serverManager';
 import { useViewSpace, useNavigateTo } from '@/stores';
@@ -195,6 +206,9 @@ interface ConfigModalState {
 
 export function ServersPage() {
   const [installedServers, setInstalledServers] = useState<ServerViewModelWithClone[]>([]);
+  const [searchQuery, setSearchQuery] = useState('');
+  const [transportFilter, setTransportFilter] = useState<TransportFilter>('all');
+  const [activeStatusFilters, setActiveStatusFilters] = useState<Set<StatusFilterKey>>(new Set());
   const [gatewayRunning, setGatewayRunning] = useState(false);
   const [gatewayUrl, setGatewayUrl] = useState<string | null>(null);
   const [isLoading, setIsLoading] = useState(true);
@@ -412,6 +426,15 @@ export function ServersPage() {
       setInstalledServers(mergedServers);
       setGatewayRunning(gateway.running);
       setGatewayUrl(gateway.url);
+
+      if (viewSpace?.id) {
+        try {
+          const allFeatures = await listServerFeatures(viewSpace.id);
+          setServerFeatures(groupFeaturesByServerId(allFeatures));
+        } catch (featureError) {
+          console.warn('[ServersPage] Failed to load server features for search:', featureError);
+        }
+      }
     } catch (e) {
       console.error('Failed to load data:', e);
     } finally {
@@ -552,6 +575,45 @@ export function ServersPage() {
   const expandableServerCount = installedServers.filter(isServerExpandable).length;
   const hasExpandedServers = expandedServers.size > 0;
 
+  /** Installed servers matching transport, status, and search filters. */
+  const filteredServers = installedServers.filter((server) =>
+    serverMatchesFilters(
+      server,
+      searchQuery,
+      serverFeatures[server.id] ?? [],
+      transportFilter,
+      activeStatusFilters,
+      getServerAction(server) as ServerActionKey
+    )
+  );
+
+  /** Toggle a Beeper-style status filter chip on or off. */
+  const toggleStatusFilter = (statusKey: StatusFilterKey) => {
+    setActiveStatusFilters((previous) => {
+      const next = new Set(previous);
+      if (next.has(statusKey)) {
+        next.delete(statusKey);
+      } else {
+        next.add(statusKey);
+      }
+      return next;
+    });
+  };
+
+  /** Reset transport and status filters to defaults. */
+  const clearAllServerFilters = () => {
+    setTransportFilter('all');
+    setActiveStatusFilters(new Set());
+  };
+
+  /** Expand or collapse a connected server row; loads features on first expand. */
+  const handleServerRowActivate = (server: ServerViewModel) => {
+    if (!isServerExpandable(server)) {
+      return;
+    }
+    toggleExpanded(server.id);
+  };
+
   // Get display status for UI
   const getDisplayStatus = (server: ServerViewModel): string => {
     const action = getServerAction(server);
@@ -1048,82 +1110,105 @@ export function ServersPage() {
         />
       )}
       {/* Header */}
-      <div className="flex items-center justify-between">
-        <div>
-          <h1 className="text-2xl font-bold" data-testid="servers-title">My Servers</h1>
-          <p className="text-sm text-[rgb(var(--muted))]">
-            Manage your installed MCP servers
-          </p>
-        </div>
-        {viewSpace && (
-          <div className="flex items-center gap-2">
-            {installedServers.length > 0 && (
-              <>
-                <button
+      <div className="space-y-4">
+        <div className="flex items-center justify-between gap-4">
+          <div className="flex-shrink-0">
+            <h1 className="text-2xl font-bold" data-testid="servers-title">My Servers</h1>
+            <p className="text-sm text-[rgb(var(--muted))]">
+              Manage your installed MCP servers
+            </p>
+          </div>
+
+          <div
+            className={`flex items-center gap-2 px-3 py-2 rounded-lg border text-sm flex-shrink-0 ${
+              gatewayRunning
+                ? 'bg-[rgb(var(--success))]/10 border-[rgb(var(--success))]/30'
+                : 'bg-[rgb(var(--warning))]/10 border-[rgb(var(--warning))]/30'
+            }`}
+            data-testid="gateway-status-chip"
+          >
+            <span
+              className={`h-2.5 w-2.5 rounded-full flex-shrink-0 ${
+                gatewayRunning ? 'bg-[rgb(var(--success))] animate-pulse' : 'bg-[rgb(var(--warning))]'
+              }`}
+            />
+            <span className="font-medium whitespace-nowrap">
+              {gatewayRunning ? 'Gateway Running' : 'Gateway Stopped'}
+            </span>
+            {gatewayRunning && gatewayUrl && (
+              <code className="text-xs bg-[rgb(var(--surface-elevated))] px-2 py-0.5 rounded text-[rgb(var(--primary))] truncate max-w-[200px]">
+                {gatewayUrl}
+              </code>
+            )}
+            {!gatewayRunning && viewSpace && (
+              <button
+                type="button"
+                onClick={handleStartGateway}
+                className="px-2.5 py-1 text-xs font-medium bg-[rgb(var(--primary))] text-[rgb(var(--primary-foreground))] rounded-md hover:bg-[rgb(var(--primary-hover))] transition-colors whitespace-nowrap"
+              >
+                Start Gateway
+              </button>
+            )}
+          </div>
+
+          {viewSpace && (
+            <div className="flex items-center gap-2 flex-shrink-0">
+              {installedServers.length > 0 && (
+                <>
+                <Button
+                  variant="secondary"
+                  size="md"
                   type="button"
                   onClick={expandAllServers}
                   disabled={expandableServerCount === 0}
-                  className="flex items-center gap-2 px-3 py-2.5 text-sm font-medium rounded-lg bg-[rgb(var(--surface-elevated))] border border-[rgb(var(--border))] hover:bg-[rgb(var(--surface-hover))] hover:border-[rgb(var(--border-subtle))] shadow-sm hover:shadow transition-all disabled:opacity-40 disabled:pointer-events-none"
                   title="Expand all connected servers"
                   data-testid="expand-all-servers"
                 >
                   <UnfoldVertical className="h-4 w-4 text-[rgb(var(--muted))]" />
                   Expand all
-                </button>
-                <button
+                </Button>
+                <Button
+                  variant="secondary"
+                  size="md"
                   type="button"
                   onClick={collapseAllServers}
                   disabled={!hasExpandedServers}
-                  className="flex items-center gap-2 px-3 py-2.5 text-sm font-medium rounded-lg bg-[rgb(var(--surface-elevated))] border border-[rgb(var(--border))] hover:bg-[rgb(var(--surface-hover))] hover:border-[rgb(var(--border-subtle))] shadow-sm hover:shadow transition-all disabled:opacity-40 disabled:pointer-events-none"
                   title="Collapse all servers"
                   data-testid="collapse-all-servers"
                 >
                   <FoldVertical className="h-4 w-4 text-[rgb(var(--muted))]" />
                   Collapse all
-                </button>
-              </>
-            )}
-            <button
-              type="button"
-              onClick={() => setEditConfigSpace({ id: viewSpace.id, name: viewSpace.name })}
-              className="flex items-center gap-2 px-4 py-2.5 text-sm font-medium rounded-lg bg-[rgb(var(--surface-elevated))] border border-[rgb(var(--border))] hover:bg-[rgb(var(--surface-hover))] hover:border-[rgb(var(--border-subtle))] shadow-sm hover:shadow transition-all"
-            >
-              <FileJson className="h-4 w-4 text-[rgb(var(--primary))]" />
-              Add Custom Server
-            </button>
-          </div>
-        )}
-      </div>
-
-      {/* Gateway Status */}
-      <div
-        className={`p-4 rounded-xl border ${
-          gatewayRunning
-            ? 'bg-[rgb(var(--success))]/10 border-[rgb(var(--success))]/30'
-            : 'bg-[rgb(var(--warning))]/10 border-[rgb(var(--warning))]/30'
-        }`}
-      >
-        <div className="flex items-center justify-between">
-          <div className="flex items-center gap-3">
-            <span className={`h-3 w-3 rounded-full ${gatewayRunning ? 'bg-[rgb(var(--success))] animate-pulse' : 'bg-[rgb(var(--warning))]'}`} />
-            <span className="font-medium">
-              {gatewayRunning ? 'Gateway Running' : 'Gateway Stopped'}
-            </span>
-            {gatewayRunning && (
-              <code className="text-xs bg-[rgb(var(--surface-elevated))] px-2 py-1 rounded text-[rgb(var(--primary))]">
-                {gatewayUrl}
-              </code>
-            )}
-          </div>
-          {!gatewayRunning && (
-            <button
-              onClick={handleStartGateway}
-              className="px-4 py-2 text-sm bg-[rgb(var(--primary))] text-[rgb(var(--primary-foreground))] rounded-lg hover:bg-[rgb(var(--primary-hover))] transition-colors"
-            >
-              Start Gateway
-            </button>
+                </Button>
+                </>
+              )}
+              <AddServerMenu
+                onDiscover={() => navigateTo('registry')}
+                onCustom={() => setEditConfigSpace({ id: viewSpace.id, name: viewSpace.name })}
+              />
+            </div>
           )}
         </div>
+
+        {viewSpace && installedServers.length > 0 && (
+          <div className="flex items-center gap-2 w-full">
+            <SearchField
+              className="flex-1 min-w-0"
+              placeholder="Search servers or tools…"
+              value={searchQuery}
+              onChange={(e) => setSearchQuery(e.target.value)}
+              onClear={() => setSearchQuery('')}
+              data-testid="servers-search"
+            />
+            <ServersFiltersPopover
+              transportFilter={transportFilter}
+              onTransportFilterChange={setTransportFilter}
+              activeStatusFilters={activeStatusFilters}
+              onToggleStatusFilter={toggleStatusFilter}
+              onClearStatusFilters={() => setActiveStatusFilters(new Set())}
+              onClearAllFilters={clearAllServerFilters}
+            />
+          </div>
+        )}
       </div>
 
       {/* Server List */}
@@ -1131,18 +1216,27 @@ export function ServersPage() {
         <div className="text-center py-12 text-[rgb(var(--muted))]">
           <div className="text-5xl mb-4">📦</div>
           <p className="text-lg mb-2">No servers installed</p>
-          <button
-            onClick={() => navigateTo('registry')}
-            className="mt-3 inline-flex items-center gap-2 px-5 py-2.5 rounded-lg text-sm font-medium bg-[rgb(var(--primary))] text-[rgb(var(--primary-foreground))] hover:bg-[rgb(var(--primary-hover))] shadow-sm hover:shadow transition-all"
-            data-testid="discover-servers-btn"
-          >
-            Discover MCP Servers
-            <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M5 12h14"/><path d="m12 5 7 7-7 7"/></svg>
-          </button>
+          <p className="text-sm max-w-md mx-auto mb-4">
+            Add from the community registry or define a custom server in your Space config.
+          </p>
+          {viewSpace && (
+            <div className="flex justify-center">
+              <AddServerMenu
+                onDiscover={() => navigateTo('registry')}
+                onCustom={() => setEditConfigSpace({ id: viewSpace.id, name: viewSpace.name })}
+              />
+            </div>
+          )}
+        </div>
+      ) : filteredServers.length === 0 ? (
+        <div className="text-center py-12 text-[rgb(var(--muted))]">
+          <Search className="h-12 w-12 mx-auto mb-4 opacity-40" />
+          <p className="text-lg mb-2">No servers match your filters</p>
+          <p className="text-sm">Try adjusting your search or filters</p>
         </div>
       ) : (
         <div className="space-y-3">
-          {installedServers.map((server) => {
+          {filteredServers.map((server) => {
             const serverAction = getServerAction(server);
             const displayStatus = getDisplayStatus(server);
             const enableLoading = actionLoading === `enable-${server.id}`;
@@ -1166,21 +1260,33 @@ export function ServersPage() {
               >
                 {/* Server Header */}
                 <div className="p-4">
-                  <div className="flex items-center justify-between">
-                    <div className={`flex items-center gap-4 ${!server.enabled ? 'opacity-60' : ''}`}>
-                      {/* Expand/Collapse button for connected servers */}
-                      {isConnected && (
-                        <button
-                          onClick={() => toggleExpanded(server.id)}
-                          className="p-1 rounded hover:bg-[rgb(var(--surface-hover))] transition-colors"
-                          data-testid={`expand-server-${server.id}`}
-                        >
+                  <div className="flex items-center justify-between gap-4">
+                    <div
+                      role={isServerExpandable(server) ? 'button' : undefined}
+                      tabIndex={isServerExpandable(server) ? 0 : undefined}
+                      onClick={() => handleServerRowActivate(server)}
+                      onKeyDown={(event) => {
+                        if (!isServerExpandable(server)) {
+                          return;
+                        }
+                        if (event.key === 'Enter' || event.key === ' ') {
+                          event.preventDefault();
+                          handleServerRowActivate(server);
+                        }
+                      }}
+                      className={`flex items-center gap-4 flex-1 min-w-0 ${
+                        !server.enabled ? 'opacity-60' : ''
+                      } ${isServerExpandable(server) ? 'cursor-pointer rounded-lg hover:bg-[rgb(var(--surface-hover))]/60 -m-2 p-2 transition-colors' : ''}`}
+                      data-testid={`server-row-${server.id}`}
+                    >
+                      {isServerExpandable(server) && (
+                        <span className="p-1" data-testid={`expand-server-${server.id}`}>
                           {isExpanded ? (
                             <ChevronDown className="h-5 w-5 text-[rgb(var(--muted))]" />
                           ) : (
                             <ChevronRight className="h-5 w-5 text-[rgb(var(--muted))]" />
                           )}
-                        </button>
+                        </span>
                       )}
                       
                       <div className="text-3xl flex items-center justify-center">
@@ -1280,7 +1386,11 @@ export function ServersPage() {
                             <span className="font-medium">Connection error</span>
                             <span className="text-[rgb(var(--muted))]">·</span>
                             <button
-                              onClick={() => setLogViewerServer({ id: server.id, name: server.name })}
+                              type="button"
+                              onClick={(event) => {
+                                event.stopPropagation();
+                                setLogViewerServer({ id: server.id, name: server.name });
+                              }}
                               className="text-[rgb(var(--muted))] hover:text-[rgb(var(--foreground))] underline cursor-pointer transition-colors"
                             >
                               View logs for details
@@ -1291,7 +1401,10 @@ export function ServersPage() {
                     </div>
 
                     {/* Actions - horizontal row with primary and secondary actions */}
-                    <div className="flex items-center gap-2">
+                    <div
+                      className="flex items-center gap-2 flex-shrink-0"
+                      onClick={(event) => event.stopPropagation()}
+                    >
                       {/* Primary action button */}
                       {serverAction === 'enable' && (
                         <button
diff --git a/apps/desktop/src/features/servers/servers-page.helpers.ts b/apps/desktop/src/features/servers/servers-page.helpers.ts
new file mode 100644
index 00000000..c60ea45e
--- /dev/null
+++ b/apps/desktop/src/features/servers/servers-page.helpers.ts
@@ -0,0 +1,166 @@
+import type { ServerFeature } from '@/lib/api/serverFeatures';
+import type { ServerViewModel } from '../../types/registry';
+
+/** Runtime action used to derive status filter buckets. */
+export type ServerActionKey =
+  | 'enable'
+  | 'configure'
+  | 'connecting'
+  | 'authenticating'
+  | 'auth_required'
+  | 'running'
+  | 'error'
+  | 'connected_auto';
+
+/** Transport filter for installed servers. */
+export type TransportFilter = 'all' | 'stdio' | 'http';
+
+/** Status bucket for Beeper-style multi-select filters. */
+export type StatusFilterKey = 'connected' | 'disabled' | 'error' | 'needs_setup';
+
+export const TRANSPORT_FILTERS: { id: TransportFilter; label: string }[] = [
+  { id: 'all', label: 'All' },
+  { id: 'stdio', label: 'stdio' },
+  { id: 'http', label: 'http' },
+];
+
+export const STATUS_FILTERS: { id: StatusFilterKey; label: string }[] = [
+  { id: 'connected', label: 'Connected' },
+  { id: 'disabled', label: 'Disabled' },
+  { id: 'error', label: 'Error' },
+  { id: 'needs_setup', label: 'Needs setup' },
+];
+
+/** Group discovered features by installed server id. */
+export function groupFeaturesByServerId(features: ServerFeature[]): Record<string, ServerFeature[]> {
+  return features.reduce<Record<string, ServerFeature[]>>((acc, feature) => {
+    const bucket = acc[feature.server_id] ?? [];
+    bucket.push(feature);
+    acc[feature.server_id] = bucket;
+    return acc;
+  }, {});
+}
+
+/**
+ * Map a server action to the status filter bucket it belongs in.
+ */
+export function statusKeyFromAction(action: ServerActionKey): StatusFilterKey {
+  switch (action) {
+    case 'running':
+    case 'connected_auto':
+      return 'connected';
+    case 'enable':
+      return 'disabled';
+    case 'error':
+      return 'error';
+    default:
+      return 'needs_setup';
+  }
+}
+
+/** Whether a server matches the selected transport filter. */
+export function matchesTransport(server: ServerViewModel, transportFilter: TransportFilter): boolean {
+  if (transportFilter === 'all') {
+    return true;
+  }
+
+  return server.transport.type === transportFilter;
+}
+
+/**
+ * Whether a server matches active status toggles.
+ * Empty set means show all (Beeper-style: no status filter applied).
+ */
+export function matchesStatus(
+  action: ServerActionKey,
+  activeStatusFilters: ReadonlySet<StatusFilterKey>
+): boolean {
+  if (activeStatusFilters.size === 0) {
+    return true;
+  }
+
+  return activeStatusFilters.has(statusKeyFromAction(action));
+}
+
+/** Whether a feature name or description matches the search query. */
+function featureMatchesQuery(feature: ServerFeature, query: string): boolean {
+  return (
+    feature.feature_name.toLowerCase().includes(query) ||
+    (feature.display_name?.toLowerCase().includes(query) ?? false) ||
+    (feature.description?.toLowerCase().includes(query) ?? false)
+  );
+}
+
+/**
+ * Whether an installed server matches transport, status, and search filters.
+ */
+export function serverMatchesFilters(
+  server: ServerViewModel,
+  searchQuery: string,
+  features: ServerFeature[],
+  transportFilter: TransportFilter,
+  activeStatusFilters: ReadonlySet<StatusFilterKey>,
+  serverAction: ServerActionKey
+): boolean {
+  if (!matchesTransport(server, transportFilter)) {
+    return false;
+  }
+
+  if (!matchesStatus(serverAction, activeStatusFilters)) {
+    return false;
+  }
+
+  const query = searchQuery.trim().toLowerCase();
+  if (!query) {
+    return true;
+  }
+
+  const metadataMatch =
+    server.name.toLowerCase().includes(query) ||
+    server.id.toLowerCase().includes(query) ||
+    (server.description?.toLowerCase().includes(query) ?? false);
+
+  if (metadataMatch) {
+    return true;
+  }
+
+  return features.some((feature) => featureMatchesQuery(feature, query));
+}
+
+/**
+ * Count non-default transport and status filters for the Filters button badge.
+ */
+export function countActiveServerFilters(
+  transportFilter: TransportFilter,
+  activeStatusFilters: ReadonlySet<StatusFilterKey>
+): number {
+  let count = activeStatusFilters.size;
+  if (transportFilter !== 'all') {
+    count += 1;
+  }
+  return count;
+}
+
+/**
+ * Human-readable lines describing the currently applied server list filters.
+ */
+export function describeAppliedServerFilters(
+  transportFilter: TransportFilter,
+  activeStatusFilters: ReadonlySet<StatusFilterKey>
+): string[] {
+  const transportLabel =
+    TRANSPORT_FILTERS.find((filter) => filter.id === transportFilter)?.label ?? transportFilter;
+
+  const statusLabel =
+    activeStatusFilters.size === 0
+      ? 'All'
+      : STATUS_FILTERS.filter((filter) => activeStatusFilters.has(filter.id))
+          .map((filter) => filter.label)
+          .join(', ');
+
+  if (countActiveServerFilters(transportFilter, activeStatusFilters) === 0) {
+    return ['No filters applied', 'Showing all servers'];
+  }
+
+  return [`Transport: ${transportLabel}`, `Status: ${statusLabel}`];
+}
diff --git a/packages/ui/src/components/common/ChipButton.tsx b/packages/ui/src/components/common/ChipButton.tsx
new file mode 100644
index 00000000..93b40de4
--- /dev/null
+++ b/packages/ui/src/components/common/ChipButton.tsx
@@ -0,0 +1,44 @@
+import { type ButtonHTMLAttributes, forwardRef } from 'react';
+import { cn } from '../../lib/cn';
+
+export type ChipButtonVariant = 'fill' | 'outline';
+
+export interface ChipButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  active?: boolean;
+  variant?: ChipButtonVariant;
+}
+
+/**
+ * Small pill toggle used for transport/status filter chips.
+ */
+export const ChipButton = forwardRef<HTMLButtonElement, ChipButtonProps>(
+  ({ className, active = false, variant = 'fill', children, type = 'button', ...props }, ref) => {
+    return (
+      <button
+        ref={ref}
+        type={type}
+        className={cn(
+          'px-3 py-1.5 text-xs font-medium rounded-lg border transition-all',
+          active && variant === 'fill' && [
+            'bg-[rgb(var(--primary))] text-[rgb(var(--primary-foreground))] border-[rgb(var(--primary))]',
+          ],
+          active &&
+            variant === 'outline' && [
+              'bg-[rgb(var(--primary))]/15 text-[rgb(var(--primary))] border-[rgb(var(--primary))]/40',
+              'ring-1 ring-[rgb(var(--primary))]/30',
+            ],
+          !active && [
+            'bg-[rgb(var(--surface-elevated))] text-[rgb(var(--muted))] border-[rgb(var(--border))]',
+            'hover:bg-[rgb(var(--surface-hover))] hover:text-[rgb(var(--foreground))]',
+          ],
+          className
+        )}
+        {...props}
+      >
+        {children}
+      </button>
+    );
+  }
+);
+
+ChipButton.displayName = 'ChipButton';
diff --git a/packages/ui/src/components/common/DropdownMenu.tsx b/packages/ui/src/components/common/DropdownMenu.tsx
new file mode 100644
index 00000000..31d34835
--- /dev/null
+++ b/packages/ui/src/components/common/DropdownMenu.tsx
@@ -0,0 +1,259 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useId,
+  useRef,
+  useState,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react';
+import type { LucideIcon } from 'lucide-react';
+import { cn } from '../../lib/cn';
+import { useClickOutside } from '../../hooks/useClickOutside';
+
+interface DropdownMenuContextValue {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  menuId: string;
+}
+
+const DropdownMenuContext = createContext<DropdownMenuContextValue | null>(null);
+
+function useDropdownMenu(): DropdownMenuContextValue {
+  const context = useContext(DropdownMenuContext);
+  if (!context) {
+    throw new Error('DropdownMenu components must be used within DropdownMenu');
+  }
+  return context;
+}
+
+export interface DropdownMenuProps {
+  children: ReactNode;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  className?: string;
+}
+
+/**
+ * Root dropdown container with open state and click-outside handling.
+ */
+export function DropdownMenu({
+  children,
+  open: controlledOpen,
+  onOpenChange,
+  className,
+}: DropdownMenuProps) {
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(false);
+  const rootRef = useRef<HTMLDivElement>(null);
+  const menuId = useId();
+
+  const open = controlledOpen ?? uncontrolledOpen;
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (controlledOpen === undefined) {
+        setUncontrolledOpen(next);
+      }
+      onOpenChange?.(next);
+    },
+    [controlledOpen, onOpenChange]
+  );
+
+  useClickOutside([rootRef], () => setOpen(false), open);
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+
+    function handleEscape(event: KeyboardEvent) {
+      if (event.key === 'Escape') {
+        setOpen(false);
+      }
+    }
+
+    document.addEventListener('keydown', handleEscape);
+    return () => document.removeEventListener('keydown', handleEscape);
+  }, [open, setOpen]);
+
+  return (
+    <DropdownMenuContext.Provider value={{ open, setOpen, menuId }}>
+      <div ref={rootRef} className={cn('relative inline-flex', className)}>
+        {children}
+      </div>
+    </DropdownMenuContext.Provider>
+  );
+}
+
+export interface DropdownMenuTriggerProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode;
+}
+
+/**
+ * Wraps the element that toggles the dropdown open state.
+ */
+export function DropdownMenuTrigger({ children, className, ...props }: DropdownMenuTriggerProps) {
+  const { open, setOpen, menuId } = useDropdownMenu();
+
+  return (
+    <div
+      className={cn('inline-flex', className)}
+      onClick={() => setOpen(!open)}
+      aria-expanded={open}
+      aria-haspopup="menu"
+      aria-controls={menuId}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
+
+export interface DropdownMenuContentProps extends HTMLAttributes<HTMLDivElement> {
+  children: ReactNode;
+  align?: 'start' | 'end';
+}
+
+/**
+ * Panel shown below the trigger when the menu is open.
+ */
+export function DropdownMenuContent({
+  children,
+  align = 'end',
+  className,
+  ...props
+}: DropdownMenuContentProps) {
+  const { open, menuId } = useDropdownMenu();
+
+  if (!open) {
+    return null;
+  }
+
+  return (
+    <div
+      id={menuId}
+      role="menu"
+      className={cn(
+        'dropdown-menu absolute top-full mt-1.5 z-50 animate-in fade-in slide-in-from-top-1 duration-150',
+        align === 'end' ? 'right-0' : 'left-0',
+        className
+      )}
+      {...props}
+    >
+      {children}
+    </div>
+  );
+}
+
+export interface DropdownMenuItemProps {
+  icon?: LucideIcon;
+  label: string;
+  description?: string;
+  onSelect: () => void;
+  variant?: 'default' | 'warning' | 'danger';
+  className?: string;
+  'data-testid'?: string;
+}
+
+/**
+ * Menu row with optional icon, title, and description (for discover/custom style items).
+ */
+export function DropdownMenuItem({
+  icon: Icon,
+  label,
+  description,
+  onSelect,
+  variant = 'default',
+  className,
+  'data-testid': testId,
+}: DropdownMenuItemProps) {
+  const { setOpen } = useDropdownMenu();
+
+  const labelClass =
+    variant === 'danger'
+      ? 'text-[rgb(var(--error))]'
+      : variant === 'warning'
+        ? 'text-[rgb(var(--warning))]'
+        : 'text-[rgb(var(--foreground))]';
+
+  return (
+    <button
+      type="button"
+      role="menuitem"
+      onClick={() => {
+        setOpen(false);
+        onSelect();
+      }}
+      className={cn(
+        'w-full text-left flex items-start gap-3 px-3 py-2.5 rounded-lg hover:bg-[rgb(var(--surface-hover))] transition-colors',
+        variant === 'danger' && 'hover:bg-[rgb(var(--error))]/10',
+        className
+      )}
+      data-testid={testId}
+    >
+      {Icon && (
+        <Icon
+          className={cn(
+            'h-4 w-4 mt-0.5 flex-shrink-0',
+            variant === 'default' ? 'text-[rgb(var(--muted))]' : labelClass
+          )}
+        />
+      )}
+      <div className="flex-1 min-w-0">
+        <p className={cn('text-sm font-medium', labelClass)}>{label}</p>
+        {description && (
+          <p className="text-xs text-[rgb(var(--muted))] mt-0.5 leading-relaxed">{description}</p>
+        )}
+      </div>
+    </button>
+  );
+}
+
+/**
+ * Simple compact menu row (icon + label) for action menus.
+ */
+export function DropdownMenuAction({
+  icon: Icon,
+  label,
+  onSelect,
+  variant = 'default',
+  className,
+  'data-testid': testId,
+}: Omit<DropdownMenuItemProps, 'description'>) {
+  const { setOpen } = useDropdownMenu();
+
+  const labelClass =
+    variant === 'danger'
+      ? 'text-[rgb(var(--error))]'
+      : variant === 'warning'
+        ? 'text-[rgb(var(--warning))]'
+        : 'text-[rgb(var(--foreground))]';
+
+  return (
+    <button
+      type="button"
+      role="menuitem"
+      onClick={() => {
+        setOpen(false);
+        onSelect();
+      }}
+      className={cn(
+        'w-full flex items-center gap-2 px-3 py-2 text-sm hover:bg-[rgb(var(--surface-hover))] transition-colors',
+        variant === 'danger' && 'hover:bg-[rgb(var(--error))]/10',
+        className
+      )}
+      data-testid={testId}
+    >
+      {Icon && (
+        <Icon className={cn('h-4 w-4', variant === 'default' ? 'text-[rgb(var(--muted))]' : labelClass)} />
+      )}
+      <span className={labelClass}>{label}</span>
+    </button>
+  );
+}
+
+export function DropdownMenuSeparator() {
+  return <div className="my-1 border-t border-[rgb(var(--border-subtle))]" role="separator" />;
+}
diff --git a/packages/ui/src/components/common/HoverTooltip.tsx b/packages/ui/src/components/common/HoverTooltip.tsx
new file mode 100644
index 00000000..3097d7b9
--- /dev/null
+++ b/packages/ui/src/components/common/HoverTooltip.tsx
@@ -0,0 +1,49 @@
+import { type ReactNode } from 'react';
+import { cn } from '../../lib/cn';
+
+export interface HoverTooltipProps {
+  children: ReactNode;
+  title: string;
+  lines?: string[];
+  side?: 'top' | 'bottom';
+  className?: string;
+  hidden?: boolean;
+  'data-testid'?: string;
+}
+
+/**
+ * Wraps a control and shows a tooltip panel on hover (hidden while `hidden` is true).
+ */
+export function HoverTooltip({
+  children,
+  title,
+  lines = [],
+  side = 'top',
+  className,
+  hidden = false,
+  'data-testid': testId,
+}: HoverTooltipProps) {
+  return (
+    <div className={cn('relative group', className)}>
+      <div
+        role="tooltip"
+        className={cn(
+          'pointer-events-none absolute z-[60] min-w-[10rem] max-w-xs dropdown-menu px-3 py-2 text-left',
+          'transition-opacity duration-150',
+          side === 'top' ? 'bottom-full mb-2' : 'top-full mt-2',
+          'right-0',
+          hidden ? 'opacity-0' : 'opacity-0 group-hover:opacity-100 group-focus-within:opacity-100'
+        )}
+        data-testid={testId}
+      >
+        <p className="text-xs font-medium text-[rgb(var(--foreground))] mb-1">{title}</p>
+        {lines.map((line) => (
+          <p key={line} className="text-xs text-[rgb(var(--muted))] leading-relaxed">
+            {line}
+          </p>
+        ))}
+      </div>
+      {children}
+    </div>
+  );
+}
diff --git a/packages/ui/src/components/common/SearchField.tsx b/packages/ui/src/components/common/SearchField.tsx
new file mode 100644
index 00000000..97066783
--- /dev/null
+++ b/packages/ui/src/components/common/SearchField.tsx
@@ -0,0 +1,50 @@
+import { forwardRef, type InputHTMLAttributes } from 'react';
+import { Search, X, type LucideIcon } from 'lucide-react';
+import { cn } from '../../lib/cn';
+
+export interface SearchFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
+  onClear?: () => void;
+  icon?: LucideIcon;
+  'data-testid'?: string;
+}
+
+/**
+ * Search input with leading icon and optional clear control.
+ */
+export const SearchField = forwardRef<HTMLInputElement, SearchFieldProps>(
+  ({ className, value, onClear, icon: Icon = Search, 'data-testid': testId, ...props }, ref) => {
+    const hasValue = String(value ?? '').length > 0;
+
+    return (
+      <div className={cn('relative min-w-0', className)}>
+        <Icon className="absolute left-3 top-1/2 -translate-y-1/2 h-4 w-4 text-[rgb(var(--muted))] pointer-events-none" />
+        <input
+          ref={ref}
+          type="text"
+          value={value}
+          data-testid={testId}
+          className={cn(
+            'w-full pl-9 py-2.5 text-sm bg-[rgb(var(--surface))] border border-[rgb(var(--border))] rounded-lg',
+            'focus:outline-none focus:ring-2 focus:ring-primary-500 focus:border-primary-500 transition-all',
+            'placeholder:text-[rgb(var(--muted))]',
+            hasValue ? 'pr-9' : 'pr-3'
+          )}
+          {...props}
+        />
+        {hasValue && onClear && (
+          <button
+            type="button"
+            onClick={onClear}
+            className="absolute right-2 top-1/2 -translate-y-1/2 p-1 rounded-md text-[rgb(var(--muted))] hover:text-[rgb(var(--foreground))] hover:bg-[rgb(var(--surface-hover))] transition-colors"
+            aria-label="Clear search"
+            data-testid={testId ? `${testId}-clear` : undefined}
+          >
+            <X className="h-4 w-4" />
+          </button>
+        )}
+      </div>
+    );
+  }
+);
+
+SearchField.displayName = 'SearchField';
diff --git a/packages/ui/src/hooks/useClickOutside.ts b/packages/ui/src/hooks/useClickOutside.ts
new file mode 100644
index 00000000..7af00eeb
--- /dev/null
+++ b/packages/ui/src/hooks/useClickOutside.ts
@@ -0,0 +1,27 @@
+import { useEffect, type RefObject } from 'react';
+
+/**
+ * Invoke a callback when the user clicks outside all provided element refs.
+ */
+export function useClickOutside(
+  refs: RefObject<HTMLElement | null>[],
+  onClickOutside: () => void,
+  enabled: boolean
+): void {
+  useEffect(() => {
+    if (!enabled) {
+      return;
+    }
+
+    function handlePointerDown(event: MouseEvent) {
+      const target = event.target as Node;
+      const isInside = refs.some((ref) => ref.current?.contains(target));
+      if (!isInside) {
+        onClickOutside();
+      }
+    }
+
+    document.addEventListener('mousedown', handlePointerDown);
+    return () => document.removeEventListener('mousedown', handlePointerDown);
+  }, [refs, onClickOutside, enabled]);
+}
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index ffcf9745..f27fc6ab 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -12,6 +12,26 @@ export { StatusBar, StatusBarItem } from './components/layout/StatusBar';
 // Common components
 export { Button } from './components/common/Button';
 export { Input } from './components/common/Input';
+export { SearchField } from './components/common/SearchField';
+export type { SearchFieldProps } from './components/common/SearchField';
+export { ChipButton } from './components/common/ChipButton';
+export type { ChipButtonProps, ChipButtonVariant } from './components/common/ChipButton';
+export {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuAction,
+  DropdownMenuSeparator,
+} from './components/common/DropdownMenu';
+export type {
+  DropdownMenuProps,
+  DropdownMenuTriggerProps,
+  DropdownMenuContentProps,
+  DropdownMenuItemProps,
+} from './components/common/DropdownMenu';
+export { HoverTooltip } from './components/common/HoverTooltip';
+export type { HoverTooltipProps } from './components/common/HoverTooltip';
 export { Card, CardHeader, CardTitle, CardDescription, CardContent } from './components/common/Card';
 export { Switch } from './components/common/Switch';
 export { Toast, ToastContainer } from './components/common/Toast';
@@ -22,6 +42,7 @@ export type { ConfirmDialogState, ConfirmDialogProps } from './components/common
 // Hooks
 export { useToast } from './hooks/useToast';
 export type { ToastOptions } from './hooks/useToast';
+export { useClickOutside } from './hooks/useClickOutside';
 
 // Utilities
 export { cn } from './lib/cn';

From 621563309a5d2e4813163411cb11f6441f120a3e Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 09:49:57 -0600
Subject: [PATCH 26/48] feat(desktop): add server count summary and smarter
 hover tooltips

Show installed/connected/disabled/error counts beside My Servers, move filter
clear-all outside the popover, and flip HoverTooltip placement from viewport space.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 .../features/servers/ServersCountSummary.tsx  |  35 ++++
 .../servers/ServersFiltersPopover.tsx         |  79 +++++----
 .../src/features/servers/ServersPage.tsx      |  14 +-
 .../features/servers/servers-page.helpers.ts  |  70 ++++++++
 .../ui/src/components/common/HoverTooltip.tsx | 155 +++++++++++++++++-
 packages/ui/src/index.ts                      |   2 +-
 6 files changed, 303 insertions(+), 52 deletions(-)
 create mode 100644 apps/desktop/src/features/servers/ServersCountSummary.tsx

diff --git a/apps/desktop/src/features/servers/ServersCountSummary.tsx b/apps/desktop/src/features/servers/ServersCountSummary.tsx
new file mode 100644
index 00000000..1d4ba97b
--- /dev/null
+++ b/apps/desktop/src/features/servers/ServersCountSummary.tsx
@@ -0,0 +1,35 @@
+import { HoverTooltip } from '@mcpmux/ui';
+import {
+  describeServerCountSummary,
+  formatServerCountSummary,
+  type ServerCountSummary,
+} from './servers-page.helpers';
+
+interface ServersCountSummaryProps {
+  summary: ServerCountSummary;
+}
+
+/**
+ * Inline installed-server counts beside the My Servers title, with hover breakdown.
+ */
+export function ServersCountSummary({ summary }: ServersCountSummaryProps) {
+  if (summary.installed === 0) {
+    return null;
+  }
+
+  return (
+    <HoverTooltip
+      title="Installed servers"
+      lines={describeServerCountSummary(summary)}
+      data-testid="servers-count-tooltip"
+      className="flex-shrink min-w-0"
+    >
+      <p
+        className="text-sm text-[rgb(var(--muted))] truncate cursor-default"
+        data-testid="servers-count-summary"
+      >
+        {formatServerCountSummary(summary)}
+      </p>
+    </HoverTooltip>
+  );
+}
diff --git a/apps/desktop/src/features/servers/ServersFiltersPopover.tsx b/apps/desktop/src/features/servers/ServersFiltersPopover.tsx
index 5c803255..9ad723ef 100644
--- a/apps/desktop/src/features/servers/ServersFiltersPopover.tsx
+++ b/apps/desktop/src/features/servers/ServersFiltersPopover.tsx
@@ -49,34 +49,46 @@ export function ServersFiltersPopover({
       data-testid="servers-filters-tooltip"
       className="flex-shrink-0"
     >
-      <DropdownMenu open={open} onOpenChange={setOpen}>
-        <DropdownMenuTrigger data-testid="servers-filters-trigger">
+      <div className="inline-flex items-center gap-2">
+        {activeCount > 0 && (
           <Button
-            variant="secondary"
+            variant="ghost"
             size="md"
             type="button"
-            className={
-              activeCount > 0
-                ? 'bg-[rgb(var(--primary))]/10 text-[rgb(var(--primary))] border-[rgb(var(--primary))]/40'
-                : undefined
-            }
+            onClick={onClearAllFilters}
+            data-testid="servers-filters-clear-all"
           >
-            <SlidersHorizontal className="h-4 w-4" />
-            Filters
-            {activeCount > 0 && (
-              <span
-                className="min-w-[1.25rem] px-1.5 py-0.5 text-xs font-semibold rounded-full bg-[rgb(var(--primary))] text-[rgb(var(--primary-foreground))]"
-                data-testid="servers-filters-count"
-              >
-                {activeCount}
-              </span>
-            )}
-            <ChevronDown
-              className={`h-4 w-4 text-[rgb(var(--muted))] transition-transform ${open ? 'rotate-180' : ''}`}
-            />
+            Clear all
           </Button>
-        </DropdownMenuTrigger>
-        <DropdownMenuContent align="end" className="w-72 p-4 space-y-4" data-testid="servers-filters-popover">
+        )}
+        <DropdownMenu open={open} onOpenChange={setOpen}>
+          <DropdownMenuTrigger data-testid="servers-filters-trigger">
+            <Button
+              variant="secondary"
+              size="md"
+              type="button"
+              className={
+                activeCount > 0
+                  ? 'bg-[rgb(var(--primary))]/10 text-[rgb(var(--primary))] border-[rgb(var(--primary))]/40'
+                  : undefined
+              }
+            >
+              <SlidersHorizontal className="h-4 w-4" />
+              Filters
+              {activeCount > 0 && (
+                <span
+                  className="min-w-[1.25rem] px-1.5 py-0.5 text-xs font-semibold rounded-full bg-[rgb(var(--primary))] text-[rgb(var(--primary-foreground))]"
+                  data-testid="servers-filters-count"
+                >
+                  {activeCount}
+                </span>
+              )}
+              <ChevronDown
+                className={`h-4 w-4 text-[rgb(var(--muted))] transition-transform ${open ? 'rotate-180' : ''}`}
+              />
+            </Button>
+          </DropdownMenuTrigger>
+          <DropdownMenuContent align="end" className="w-72 p-4 space-y-4" data-testid="servers-filters-popover">
           <div className="space-y-2">
             <p className="text-xs font-medium text-[rgb(var(--muted))]">Transport</p>
             <div className="flex flex-wrap gap-2">
@@ -121,24 +133,9 @@ export function ServersFiltersPopover({
               Combine status filters (e.g. Connected + Error). All = no status filter.
             </p>
           </div>
-
-          {activeCount > 0 && (
-            <Button
-              variant="ghost"
-              size="sm"
-              type="button"
-              className="w-full"
-              onClick={() => {
-                onClearAllFilters();
-                setOpen(false);
-              }}
-              data-testid="servers-filters-clear-all"
-            >
-              Clear all filters
-            </Button>
-          )}
-        </DropdownMenuContent>
-      </DropdownMenu>
+          </DropdownMenuContent>
+        </DropdownMenu>
+      </div>
     </HoverTooltip>
   );
 }
diff --git a/apps/desktop/src/features/servers/ServersPage.tsx b/apps/desktop/src/features/servers/ServersPage.tsx
index d7016e65..fdc486d0 100644
--- a/apps/desktop/src/features/servers/ServersPage.tsx
+++ b/apps/desktop/src/features/servers/ServersPage.tsx
@@ -28,11 +28,13 @@ import { ServerActionMenu } from './ServerActionMenu';
 import { CloneAccountModal } from './CloneAccountModal';
 import { AddServerMenu } from './AddServerMenu';
 import { ServersFiltersPopover } from './ServersFiltersPopover';
+import { ServersCountSummary } from './ServersCountSummary';
 import { UninstallSourceWithClonesDialog } from './UninstallSourceWithClonesDialog';
 import type { ServerViewModel, ServerDefinition, InstalledServerState, InputDefinition } from '../../types/registry';
 import type { ServerFeature } from '@/lib/api/serverFeatures';
 import { listServerFeatures, listServerFeaturesByServer } from '@/lib/api/serverFeatures';
 import {
+  computeServerCountSummary,
   groupFeaturesByServerId,
   serverMatchesFilters,
   type ServerActionKey,
@@ -574,6 +576,9 @@ export function ServersPage() {
 
   const expandableServerCount = installedServers.filter(isServerExpandable).length;
   const hasExpandedServers = expandedServers.size > 0;
+  const serverCountSummary = computeServerCountSummary(installedServers, (server) =>
+    getServerAction(server)
+  );
 
   /** Installed servers matching transport, status, and search filters. */
   const filteredServers = installedServers.filter((server) =>
@@ -1112,8 +1117,13 @@ export function ServersPage() {
       {/* Header */}
       <div className="space-y-4">
         <div className="flex items-center justify-between gap-4">
-          <div className="flex-shrink-0">
-            <h1 className="text-2xl font-bold" data-testid="servers-title">My Servers</h1>
+          <div className="flex-shrink min-w-0">
+            <div className="flex flex-wrap items-baseline gap-x-2 gap-y-1">
+              <h1 className="text-2xl font-bold" data-testid="servers-title">
+                My Servers
+              </h1>
+              <ServersCountSummary summary={serverCountSummary} />
+            </div>
             <p className="text-sm text-[rgb(var(--muted))]">
               Manage your installed MCP servers
             </p>
diff --git a/apps/desktop/src/features/servers/servers-page.helpers.ts b/apps/desktop/src/features/servers/servers-page.helpers.ts
index c60ea45e..6976c450 100644
--- a/apps/desktop/src/features/servers/servers-page.helpers.ts
+++ b/apps/desktop/src/features/servers/servers-page.helpers.ts
@@ -144,6 +144,76 @@ export function countActiveServerFilters(
 /**
  * Human-readable lines describing the currently applied server list filters.
  */
+/** Per-status counts for the My Servers header summary. */
+export type ServerCountSummary = {
+  installed: number;
+  connected: number;
+  disabled: number;
+  error: number;
+  needsSetup: number;
+};
+
+/**
+ * Aggregate installed-server counts by status bucket (same buckets as status filters).
+ */
+export function computeServerCountSummary(
+  servers: ServerViewModel[],
+  getAction: (server: ServerViewModel) => ServerActionKey
+): ServerCountSummary {
+  const summary: ServerCountSummary = {
+    installed: servers.length,
+    connected: 0,
+    disabled: 0,
+    error: 0,
+    needsSetup: 0,
+  };
+
+  for (const server of servers) {
+    switch (statusKeyFromAction(getAction(server))) {
+      case 'connected':
+        summary.connected += 1;
+        break;
+      case 'disabled':
+        summary.disabled += 1;
+        break;
+      case 'error':
+        summary.error += 1;
+        break;
+      case 'needs_setup':
+        summary.needsSetup += 1;
+        break;
+    }
+  }
+
+  return summary;
+}
+
+/** Compact inline summary next to the My Servers title. */
+export function formatServerCountSummary(summary: ServerCountSummary): string {
+  return [
+    `${summary.installed} installed`,
+    `${summary.connected} connected`,
+    `${summary.disabled} disabled`,
+    `${summary.error} error`,
+  ].join(', ');
+}
+
+/** Tooltip lines for the server count hover panel. */
+export function describeServerCountSummary(summary: ServerCountSummary): string[] {
+  const lines = [
+    `${summary.installed} installed`,
+    `${summary.connected} connected`,
+    `${summary.disabled} disabled`,
+    `${summary.error} error`,
+  ];
+
+  if (summary.needsSetup > 0) {
+    lines.push(`${summary.needsSetup} needs setup`);
+  }
+
+  return lines;
+}
+
 export function describeAppliedServerFilters(
   transportFilter: TransportFilter,
   activeStatusFilters: ReadonlySet<StatusFilterKey>
diff --git a/packages/ui/src/components/common/HoverTooltip.tsx b/packages/ui/src/components/common/HoverTooltip.tsx
index 3097d7b9..a17cff6f 100644
--- a/packages/ui/src/components/common/HoverTooltip.tsx
+++ b/packages/ui/src/components/common/HoverTooltip.tsx
@@ -1,39 +1,178 @@
-import { type ReactNode } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useRef, useState, type ReactNode } from 'react';
 import { cn } from '../../lib/cn';
 
+export type HoverTooltipSide = 'top' | 'bottom' | 'auto';
+
+const VIEWPORT_PADDING = 8;
+const GAP = 8;
+
 export interface HoverTooltipProps {
   children: ReactNode;
   title: string;
   lines?: string[];
-  side?: 'top' | 'bottom';
+  /** Preferred placement; `auto` flips based on available viewport space. */
+  side?: HoverTooltipSide;
   className?: string;
   hidden?: boolean;
   'data-testid'?: string;
 }
 
+/**
+ * Pick top or bottom placement from viewport space around the trigger.
+ */
+function resolveTooltipSide(
+  preferred: HoverTooltipSide,
+  triggerRect: DOMRect,
+  tooltipHeight: number
+): 'top' | 'bottom' {
+  const spaceAbove = triggerRect.top;
+  const spaceBelow = window.innerHeight - triggerRect.bottom;
+  const needed = tooltipHeight + GAP;
+
+  if (preferred === 'top') {
+    if (spaceAbove >= needed) {
+      return 'top';
+    }
+    if (spaceBelow >= needed) {
+      return 'bottom';
+    }
+    return spaceBelow > spaceAbove ? 'bottom' : 'top';
+  }
+
+  if (preferred === 'bottom') {
+    if (spaceBelow >= needed) {
+      return 'bottom';
+    }
+    if (spaceAbove >= needed) {
+      return 'top';
+    }
+    return spaceAbove > spaceBelow ? 'top' : 'bottom';
+  }
+
+  if (spaceAbove >= needed && spaceBelow >= needed) {
+    return spaceAbove >= spaceBelow ? 'top' : 'bottom';
+  }
+  if (spaceBelow >= needed) {
+    return 'bottom';
+  }
+  if (spaceAbove >= needed) {
+    return 'top';
+  }
+  return spaceBelow > spaceAbove ? 'bottom' : 'top';
+}
+
+/**
+ * Compute fixed viewport coordinates for the tooltip panel.
+ */
+function computeTooltipCoords(
+  triggerRect: DOMRect,
+  tooltipWidth: number,
+  tooltipHeight: number,
+  placement: 'top' | 'bottom'
+): { top: number; left: number } {
+  let top =
+    placement === 'top'
+      ? triggerRect.top - tooltipHeight - GAP
+      : triggerRect.bottom + GAP;
+
+  top = Math.max(
+    VIEWPORT_PADDING,
+    Math.min(top, window.innerHeight - tooltipHeight - VIEWPORT_PADDING)
+  );
+
+  let left = triggerRect.right - tooltipWidth;
+  left = Math.max(
+    VIEWPORT_PADDING,
+    Math.min(left, window.innerWidth - tooltipWidth - VIEWPORT_PADDING)
+  );
+
+  return { top, left };
+}
+
 /**
  * Wraps a control and shows a tooltip panel on hover (hidden while `hidden` is true).
+ * Placement flips above/below based on viewport space when `side` is `auto`.
  */
 export function HoverTooltip({
   children,
   title,
   lines = [],
-  side = 'top',
+  side = 'auto',
   className,
   hidden = false,
   'data-testid': testId,
 }: HoverTooltipProps) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const tooltipRef = useRef<HTMLDivElement>(null);
+  const [active, setActive] = useState(false);
+  const [coords, setCoords] = useState<{ top: number; left: number } | null>(null);
+
+  const updateCoords = useCallback(() => {
+    const container = containerRef.current;
+    const tooltip = tooltipRef.current;
+    if (!container || !tooltip) {
+      return;
+    }
+
+    const triggerRect = container.getBoundingClientRect();
+    const tooltipRect = tooltip.getBoundingClientRect();
+    const tooltipWidth = tooltipRect.width > 0 ? tooltipRect.width : tooltip.scrollWidth;
+    const tooltipHeight = tooltipRect.height > 0 ? tooltipRect.height : tooltip.scrollHeight;
+
+    const placement = resolveTooltipSide(side, triggerRect, tooltipHeight);
+    setCoords(computeTooltipCoords(triggerRect, tooltipWidth, tooltipHeight, placement));
+  }, [side]);
+
+  useLayoutEffect(() => {
+    if (!active || hidden) {
+      setCoords(null);
+      return;
+    }
+    updateCoords();
+  }, [active, hidden, updateCoords, title, lines]);
+
+  useEffect(() => {
+    if (!active || hidden) {
+      return;
+    }
+
+    const handleReposition = () => updateCoords();
+    window.addEventListener('resize', handleReposition);
+    window.addEventListener('scroll', handleReposition, true);
+    return () => {
+      window.removeEventListener('resize', handleReposition);
+      window.removeEventListener('scroll', handleReposition, true);
+    };
+  }, [active, hidden, updateCoords]);
+
+  const showTooltip = active && !hidden && coords !== null;
+
   return (
-    <div className={cn('relative group', className)}>
+    <div
+      ref={containerRef}
+      className={cn('relative', className)}
+      onMouseEnter={() => setActive(true)}
+      onMouseLeave={() => setActive(false)}
+      onFocusCapture={() => setActive(true)}
+      onBlurCapture={(event) => {
+        if (!event.currentTarget.contains(event.relatedTarget as Node | null)) {
+          setActive(false);
+        }
+      }}
+    >
       <div
+        ref={tooltipRef}
         role="tooltip"
         className={cn(
-          'pointer-events-none absolute z-[60] min-w-[10rem] max-w-xs dropdown-menu px-3 py-2 text-left',
+          'pointer-events-none fixed z-[60] min-w-[10rem] max-w-xs dropdown-menu px-3 py-2 text-left',
           'transition-opacity duration-150',
-          side === 'top' ? 'bottom-full mb-2' : 'top-full mt-2',
-          'right-0',
-          hidden ? 'opacity-0' : 'opacity-0 group-hover:opacity-100 group-focus-within:opacity-100'
+          showTooltip ? 'opacity-100' : 'opacity-0'
         )}
+        style={
+          coords
+            ? { top: coords.top, left: coords.left }
+            : { top: -9999, left: -9999, visibility: 'hidden' as const }
+        }
         data-testid={testId}
       >
         <p className="text-xs font-medium text-[rgb(var(--foreground))] mb-1">{title}</p>
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
index f27fc6ab..c68a6c2d 100644
--- a/packages/ui/src/index.ts
+++ b/packages/ui/src/index.ts
@@ -31,7 +31,7 @@ export type {
   DropdownMenuItemProps,
 } from './components/common/DropdownMenu';
 export { HoverTooltip } from './components/common/HoverTooltip';
-export type { HoverTooltipProps } from './components/common/HoverTooltip';
+export type { HoverTooltipProps, HoverTooltipSide } from './components/common/HoverTooltip';
 export { Card, CardHeader, CardTitle, CardDescription, CardContent } from './components/common/Card';
 export { Switch } from './components/common/Switch';
 export { Toast, ToastContainer } from './components/common/Toast';

From 6b70c0f4e245ea90d5b0d988f8bb841b5586b4fa Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 10:37:10 -0600
Subject: [PATCH 27/48] feat(servers): add per-install display name override

Lets users distinguish multiple installs of the same MCP (e.g. two Google
Calendars) with a friendly label that survives user-config sync, without
changing server_id, alias, or tool prefixes.

- Migration 018 + InstalledServer.display_name_override; display_name()
  precedence: override -> server_name -> server_id tail.
- ServerAppService gains set_display_name_override and accepts an optional
  override on update_config and clone_server. New set_server_display_name
  Tauri command; save_server_inputs and clone_server extended.
- Frontend resolveInstalledDisplayName helper used in every merge path;
  Configure modal exposes a Display name field and ServerActionMenu always
  shows Configure (Settings when no inputs); CloneAccountModal adds an
  optional Display name input.
- mcpmux_list_servers reports the effective installed display name so
  agents see the user's label instead of the catalog name.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 apps/desktop/src-tauri/src/commands/server.rs |  27 +++
 .../src-tauri/src/commands/server_clone.rs    |  13 +-
 apps/desktop/src-tauri/src/lib.rs             |   1 +
 .../features/servers/CloneAccountModal.tsx    |  87 +++++--
 .../src/features/servers/ServerActionMenu.tsx |  10 +-
 .../src/features/servers/ServersPage.tsx      | 106 +++++++--
 .../UninstallSourceWithClonesDialog.tsx       |  12 +-
 .../servers/server-display-name.helpers.ts    |  32 +++
 apps/desktop/src/lib/api/registry.ts          |  37 ++-
 apps/desktop/src/lib/api/serverClone.ts       |  13 +-
 apps/desktop/src/stores/registryStore.ts      |   2 +
 apps/desktop/src/types/registry.ts            |   2 +
 crates/mcpmux-core/src/application/server.rs  | 214 +++++++++++++++++-
 .../src/domain/installed_server.rs            |  76 ++++++-
 crates/mcpmux-core/src/repository/mod.rs      |   6 +
 .../src/services/meta_tools/tools.rs          |  32 ++-
 crates/mcpmux-storage/src/database.rs         |   5 +
 ...installed_server_display_name_override.sql |   2 +
 .../installed_server_repository.rs            |  26 ++-
 docs/planning/server-display-rename.md        | 132 +++++++++++
 tests/rust/src/mocks.rs                       |   7 +
 tests/rust/tests/integration/server_clone.rs  |  12 +-
 22 files changed, 773 insertions(+), 81 deletions(-)
 create mode 100644 apps/desktop/src/features/servers/server-display-name.helpers.ts
 create mode 100644 crates/mcpmux-storage/src/migrations/018_installed_server_display_name_override.sql
 create mode 100644 docs/planning/server-display-rename.md

diff --git a/apps/desktop/src-tauri/src/commands/server.rs b/apps/desktop/src-tauri/src/commands/server.rs
index e2c8f44a..73f97a43 100644
--- a/apps/desktop/src-tauri/src/commands/server.rs
+++ b/apps/desktop/src-tauri/src/commands/server.rs
@@ -127,6 +127,7 @@ pub async fn set_server_oauth_connected(
         .map_err(|e| e.to_string())
 }
 
+#[allow(clippy::too_many_arguments)]
 #[tauri::command]
 pub async fn save_server_inputs(
     app_service: State<'_, Arc<RwLock<Option<ServerAppService>>>>,
@@ -136,6 +137,7 @@ pub async fn save_server_inputs(
     env_overrides: Option<HashMap<String, String>>,
     args_append: Option<Vec<String>>,
     extra_headers: Option<HashMap<String, String>>,
+    display_name_override: Option<String>,
 ) -> Result<InstalledServer, String> {
     let service_lock = app_service.read().await;
     let service = service_lock
@@ -152,7 +154,32 @@ pub async fn save_server_inputs(
             env_overrides,
             args_append,
             extra_headers,
+            display_name_override,
         )
         .await
         .map_err(|e| e.to_string())
 }
+
+/// Set or clear the user-supplied display label on an installed server.
+///
+/// Empty/whitespace clears the override and the UI falls back to the cached
+/// definition name. Does not change `server_id`, alias, or tool prefixes.
+#[tauri::command]
+pub async fn set_server_display_name(
+    app_service: State<'_, Arc<RwLock<Option<ServerAppService>>>>,
+    id: String,
+    space_id: String,
+    display_name: Option<String>,
+) -> Result<InstalledServer, String> {
+    let service_lock = app_service.read().await;
+    let service = service_lock
+        .as_ref()
+        .ok_or("ServerAppService not initialized")?;
+
+    let space_uuid = uuid::Uuid::parse_str(&space_id).map_err(|e| e.to_string())?;
+
+    service
+        .set_display_name_override(space_uuid, &id, display_name)
+        .await
+        .map_err(|e| e.to_string())
+}
diff --git a/apps/desktop/src-tauri/src/commands/server_clone.rs b/apps/desktop/src-tauri/src/commands/server_clone.rs
index 4b8c0778..ac7b30ca 100644
--- a/apps/desktop/src-tauri/src/commands/server_clone.rs
+++ b/apps/desktop/src-tauri/src/commands/server_clone.rs
@@ -7,6 +7,10 @@ use tauri::State;
 use tokio::sync::RwLock;
 
 /// Clone an installed server into a new suffixed manual-entry install in the same space.
+///
+/// `display_name` (optional) is stored as `display_name_override` so the user-supplied
+/// label survives later definition refreshes (e.g. user-config sync). When omitted, the
+/// auto `"Source (suffix)"` label on the cached definition is used as fallback.
 #[tauri::command]
 pub async fn clone_server(
     app_service: State<'_, Arc<RwLock<Option<ServerAppService>>>>,
@@ -14,6 +18,7 @@ pub async fn clone_server(
     source_server_id: String,
     suffix: String,
     alias: Option<String>,
+    display_name: Option<String>,
 ) -> Result<InstalledServer, String> {
     let service_lock = app_service.read().await;
     let service = service_lock
@@ -23,7 +28,13 @@ pub async fn clone_server(
     let space_uuid = uuid::Uuid::parse_str(&space_id).map_err(|e| e.to_string())?;
 
     service
-        .clone_server(space_uuid, &source_server_id, &suffix, alias.as_deref())
+        .clone_server(
+            space_uuid,
+            &source_server_id,
+            &suffix,
+            alias.as_deref(),
+            display_name.as_deref(),
+        )
         .await
         .map_err(|e| e.to_string())
 }
diff --git a/apps/desktop/src-tauri/src/lib.rs b/apps/desktop/src-tauri/src/lib.rs
index 03d17b96..a7e62ff0 100644
--- a/apps/desktop/src-tauri/src/lib.rs
+++ b/apps/desktop/src-tauri/src/lib.rs
@@ -870,6 +870,7 @@ pub fn run() {
             commands::set_server_enabled,
             commands::set_server_oauth_connected,
             commands::save_server_inputs,
+            commands::set_server_display_name,
             commands::clone_server,
             commands::is_clone_id_available,
             commands::suggest_clone_suffix,
diff --git a/apps/desktop/src/features/servers/CloneAccountModal.tsx b/apps/desktop/src/features/servers/CloneAccountModal.tsx
index a07967ef..7faaebe2 100644
--- a/apps/desktop/src/features/servers/CloneAccountModal.tsx
+++ b/apps/desktop/src/features/servers/CloneAccountModal.tsx
@@ -35,12 +35,19 @@ export function CloneAccountModal({
   onCloned,
 }: CloneAccountModalProps) {
   const [suffix, setSuffix] = useState('');
+  const [displayName, setDisplayName] = useState('');
   const [isChecking, setIsChecking] = useState(false);
   const [isAvailable, setIsAvailable] = useState<boolean | null>(null);
   const [isSubmitting, setIsSubmitting] = useState(false);
   const [submitError, setSubmitError] = useState<string | null>(null);
   const [isLoadingSuggestion, setIsLoadingSuggestion] = useState(false);
 
+  const trimmedSuffix = suffix.trim();
+  const trimmedDisplayName = displayName.trim();
+  const displayNamePlaceholder = trimmedSuffix
+    ? `${sourceServer.name} (${trimmedSuffix})`
+    : `${sourceServer.name} (work)`;
+
   const previewId = deriveCloneServerId(sourceServer.id, suffix);
   const previewAlias = deriveCloneAlias(suffix);
   const hasSuffix = suffix.trim().length > 0;
@@ -131,7 +138,13 @@ export function CloneAccountModal({
     setSubmitError(null);
 
     try {
-      const cloned = await cloneServer(spaceId, sourceServer.id, suffix);
+      const cloned = await cloneServer(
+        spaceId,
+        sourceServer.id,
+        suffix,
+        undefined,
+        trimmedDisplayName.length > 0 ? trimmedDisplayName : undefined
+      );
       onCloned(cloned);
       onClose();
     } catch (e) {
@@ -139,26 +152,37 @@ export function CloneAccountModal({
     } finally {
       setIsSubmitting(false);
     }
-  }, [hasSuffix, hasCollision, isChecking, spaceId, sourceServer.id, suffix, onCloned, onClose]);
+  }, [
+    hasSuffix,
+    hasCollision,
+    isChecking,
+    spaceId,
+    sourceServer.id,
+    suffix,
+    trimmedDisplayName,
+    onCloned,
+    onClose,
+  ]);
 
   if (!open) {
     return null;
   }
 
-  const canSubmit = hasSuffix && !hasCollision && !isChecking && !isSubmitting && !isLoadingSuggestion;
+  const canSubmit =
+    hasSuffix && !hasCollision && !isChecking && !isSubmitting && !isLoadingSuggestion;
 
   return (
     <div
-      className="fixed inset-0 bg-black/60 backdrop-blur-sm flex items-center justify-center z-50 p-4"
+      className="fixed inset-0 z-50 flex items-center justify-center bg-black/60 p-4 backdrop-blur-sm"
       data-testid="clone-account-modal-overlay"
     >
       <div
-        className="dropdown-menu w-full max-w-md p-6 animate-in fade-in scale-in duration-150"
+        className="dropdown-menu animate-in fade-in scale-in w-full max-w-md p-6 duration-150"
         data-testid="clone-account-modal"
       >
-        <div className="flex items-start justify-between gap-3 mb-4">
+        <div className="mb-4 flex items-start justify-between gap-3">
           <div className="flex items-center gap-3">
-            <div className="p-2 rounded-lg bg-[rgb(var(--primary))]/10">
+            <div className="rounded-lg bg-[rgb(var(--primary))]/10 p-2">
               <Copy className="h-5 w-5 text-[rgb(var(--primary))]" />
             </div>
             <div>
@@ -172,7 +196,7 @@ export function CloneAccountModal({
           </div>
           <button
             onClick={onClose}
-            className="p-1 rounded hover:bg-[rgb(var(--surface-hover))] text-[rgb(var(--muted))] transition-colors"
+            className="rounded p-1 text-[rgb(var(--muted))] transition-colors hover:bg-[rgb(var(--surface-hover))]"
             aria-label="Close"
             data-testid="clone-account-close-btn"
           >
@@ -181,14 +205,36 @@ export function CloneAccountModal({
         </div>
 
         <div className="space-y-4">
+          <div>
+            <label
+              htmlFor="clone-display-name"
+              className="mb-1 block text-sm font-medium text-[rgb(var(--foreground))]"
+            >
+              Display name
+            </label>
+            <p className="mb-2 text-xs text-[rgb(var(--muted))]">
+              Shown in My Servers only. Leave blank to use the default.
+            </p>
+            <input
+              id="clone-display-name"
+              type="text"
+              value={displayName}
+              onChange={(e) => setDisplayName(e.target.value)}
+              placeholder={displayNamePlaceholder}
+              className="input w-full"
+              disabled={isSubmitting}
+              data-testid="clone-display-name-input"
+            />
+          </div>
+
           <div>
             <label
               htmlFor="clone-suffix"
-              className="block text-sm font-medium text-[rgb(var(--foreground))] mb-1"
+              className="mb-1 block text-sm font-medium text-[rgb(var(--foreground))]"
             >
               Account label
             </label>
-            <p className="text-xs text-[rgb(var(--muted))] mb-2">
+            <p className="mb-2 text-xs text-[rgb(var(--muted))]">
               Used in the server ID and tool prefix (e.g. work, personal)
             </p>
             <input
@@ -202,21 +248,24 @@ export function CloneAccountModal({
               data-testid="clone-suffix-input"
             />
             {hasCollision && (
-              <p className="text-xs text-[rgb(var(--error))] mt-1" data-testid="clone-collision-error">
+              <p
+                className="mt-1 text-xs text-[rgb(var(--error))]"
+                data-testid="clone-collision-error"
+              >
                 An account with this label already exists in this space
               </p>
             )}
           </div>
 
           <div>
-            <p className="text-xs font-medium text-[rgb(var(--muted))] mb-2">Suggestions</p>
+            <p className="mb-2 text-xs font-medium text-[rgb(var(--muted))]">Suggestions</p>
             <div className="flex flex-wrap gap-2">
               {CLONE_SUFFIX_SUGGESTIONS.map((suggestion) => (
                 <button
                   key={suggestion}
                   type="button"
                   onClick={() => setSuffix(suggestion)}
-                  className={`px-2.5 py-1 text-xs rounded-md border transition-colors ${
+                  className={`rounded-md border px-2.5 py-1 text-xs transition-colors ${
                     suffix === suggestion
                       ? 'border-[rgb(var(--primary))] bg-[rgb(var(--primary))]/10 text-[rgb(var(--primary))]'
                       : 'border-[rgb(var(--border))] text-[rgb(var(--muted))] hover:bg-[rgb(var(--surface-hover))]'
@@ -230,14 +279,16 @@ export function CloneAccountModal({
           </div>
 
           {hasSuffix && (
-            <div className="rounded-lg border border-[rgb(var(--border-subtle))] bg-[rgb(var(--surface-dim))] p-3 space-y-2">
+            <div className="space-y-2 rounded-lg border border-[rgb(var(--border-subtle))] bg-[rgb(var(--surface-dim))] p-3">
               <div className="flex items-center justify-between gap-2 text-sm">
                 <span className="text-[rgb(var(--muted))]">Server ID</span>
-                <code className="text-xs font-mono text-[rgb(var(--foreground))]">{previewId || '—'}</code>
+                <code className="font-mono text-xs text-[rgb(var(--foreground))]">
+                  {previewId || '—'}
+                </code>
               </div>
               <div className="flex items-center justify-between gap-2 text-sm">
                 <span className="text-[rgb(var(--muted))]">Tool prefix</span>
-                <code className="text-xs font-mono text-[rgb(var(--foreground))]">
+                <code className="font-mono text-xs text-[rgb(var(--foreground))]">
                   {previewAlias ? `${previewAlias}_*` : '—'}
                 </code>
               </div>
@@ -264,7 +315,7 @@ export function CloneAccountModal({
           <div className="flex justify-end gap-2 pt-2">
             <button
               onClick={onClose}
-              className="px-4 py-2 text-sm rounded-lg border border-[rgb(var(--border))] text-[rgb(var(--muted))] hover:bg-[rgb(var(--surface-hover))] transition-colors"
+              className="rounded-lg border border-[rgb(var(--border))] px-4 py-2 text-sm text-[rgb(var(--muted))] transition-colors hover:bg-[rgb(var(--surface-hover))]"
               disabled={isSubmitting}
               data-testid="clone-cancel-btn"
             >
@@ -273,7 +324,7 @@ export function CloneAccountModal({
             <button
               onClick={handleSubmit}
               disabled={!canSubmit}
-              className="px-4 py-2 text-sm rounded-lg bg-[rgb(var(--primary))] text-[rgb(var(--primary-foreground))] hover:bg-[rgb(var(--primary-hover))] disabled:opacity-50 transition-colors flex items-center gap-2"
+              className="flex items-center gap-2 rounded-lg bg-[rgb(var(--primary))] px-4 py-2 text-sm text-[rgb(var(--primary-foreground))] transition-colors hover:bg-[rgb(var(--primary-hover))] disabled:opacity-50"
               data-testid="clone-submit-btn"
             >
               {isSubmitting && <Loader2 className="h-4 w-4 animate-spin" />}
diff --git a/apps/desktop/src/features/servers/ServerActionMenu.tsx b/apps/desktop/src/features/servers/ServerActionMenu.tsx
index 6e0116e4..f157ce8a 100644
--- a/apps/desktop/src/features/servers/ServerActionMenu.tsx
+++ b/apps/desktop/src/features/servers/ServerActionMenu.tsx
@@ -10,6 +10,8 @@ import {
 export interface ServerActionMenuProps {
   serverId: string;
   serverName: string;
+  /** Whether the server has credential / config inputs. Servers with no inputs still show
+   *  Configure so the display name can be edited. */
   hasInputs: boolean;
   isOAuth: boolean;
   isEnabled: boolean;
@@ -58,9 +60,11 @@ export function ServerActionMenu({
         </button>
       </DropdownMenuTrigger>
       <DropdownMenuContent align="end" className="w-48 py-1 p-1">
-        {hasInputs && (
-          <DropdownMenuAction icon={Settings} label="Configure" onSelect={onConfigure} />
-        )}
+        <DropdownMenuAction
+          icon={Settings}
+          label={hasInputs ? 'Configure' : 'Settings'}
+          onSelect={onConfigure}
+        />
         {isEnabled && (
           <DropdownMenuAction icon={RefreshCw} label="Refresh" onSelect={onRefresh} />
         )}
diff --git a/apps/desktop/src/features/servers/ServersPage.tsx b/apps/desktop/src/features/servers/ServersPage.tsx
index fdc486d0..2e49aacf 100644
--- a/apps/desktop/src/features/servers/ServersPage.tsx
+++ b/apps/desktop/src/features/servers/ServersPage.tsx
@@ -41,6 +41,7 @@ import {
   type StatusFilterKey,
   type TransportFilter,
 } from './servers-page.helpers';
+import { resolveInstalledDisplayName } from './server-display-name.helpers';
 import type { ConnectionStatus, ServerStatusResponse } from '@/lib/api/serverManager';
 import { getServerStatuses as fetchServerStatuses } from '@/lib/api/serverManager';
 import { useViewSpace, useNavigateTo } from '@/stores';
@@ -88,30 +89,28 @@ function mergeDefinitionsWithStates(
   
   return definitions.map(def => {
     const state = stateMap.get(def.id);
-    
-    // Check if any required inputs are missing
+
     const inputs = def.transport.metadata?.inputs ?? [];
     const inputValues = state?.input_values ?? {};
     const missing_required_inputs = inputs.some((input: InputDefinition) =>
       input.required && !inputValues[input.id]
     );
-    
-    // Calculate initial connection_status based on enabled state
-    // Calculate initial connection_status based on enabled state
-    // Actual runtime status comes from ServerManager events via useServerManager hook
+
     const connection_status = state?.enabled ? 'connecting' : 'disconnected';
-    
+    const displayName = state ? resolveInstalledDisplayName(state, def) : def.name;
+
     return {
       ...def,
+      name: displayName,
       is_installed: !!state,
       enabled: state?.enabled ?? false,
       oauth_connected: state?.oauth_connected ?? false,
       input_values: inputValues,
-      connection_status, // Initial status, will be overridden by runtime events
+      connection_status,
       missing_required_inputs,
-      last_error: null, // Runtime-only, will be set by ServerManager events
-      created_at: state?.created_at, // Include for sorting
-      installation_source: state?.source, // Track how server was installed
+      last_error: null,
+      created_at: state?.created_at,
+      installation_source: state?.source,
       cloned_from: state ? getInstalledCloneLineage(state) : undefined,
       env_overrides: state?.env_overrides ?? {},
       args_append: state?.args_append ?? [],
@@ -123,7 +122,6 @@ function mergeDefinitionsWithStates(
 // Helper to create ServerViewModel from installed state when registry is unavailable
 // Uses cached_definition if available (proper offline support), otherwise falls back to minimal data
 function createOfflineServerViewModel(state: InstalledServerState): ServerViewModelWithClone {
-  // Try to use cached definition first (proper offline support)
   if (state.cached_definition) {
     try {
       const definition: ServerDefinition = JSON.parse(state.cached_definition);
@@ -138,6 +136,7 @@ function createOfflineServerViewModel(state: InstalledServerState): ServerViewMo
 
       return {
         ...definition,
+        name: resolveInstalledDisplayName(state, definition),
         is_installed: true,
         enabled: state.enabled,
         oauth_connected: state.oauth_connected,
@@ -157,10 +156,9 @@ function createOfflineServerViewModel(state: InstalledServerState): ServerViewMo
     }
   }
 
-  // Fallback: minimal view model when no cached definition available
   return {
     id: state.server_id,
-    name: state.server_name || state.server_id.split('/').pop() || state.server_id,
+    name: resolveInstalledDisplayName(state),
     description: '(Server definition not cached)',
     alias: null,
     icon: null,
@@ -204,6 +202,10 @@ interface ConfigModalState {
   argsAppend: string[];
   /** Extra HTTP headers (http only) */
   extraHeaders: Record<string, string>;
+  /** User-supplied display label (empty string = clear override). */
+  displayName: string;
+  /** Display name when the modal opened — used to detect changes on save. */
+  initialDisplayName: string;
 }
 
 export function ServersPage() {
@@ -225,6 +227,8 @@ export function ServersPage() {
     envOverrides: {},
     argsAppend: [],
     extraHeaders: {},
+    displayName: '',
+    initialDisplayName: '',
   });
 
   // Features state
@@ -664,14 +668,17 @@ export function ServersPage() {
       serverInputs.forEach((input: InputDefinition) => {
         initialValues[input.id] = server.input_values[input.id] || '';
       });
+      const initialDisplayName = server.name ?? '';
       setConfigModal({
         open: true,
         server,
         inputValues: initialValues,
-        enableOnSave: true, // This is from Enable flow
+        enableOnSave: true,
         envOverrides: { ...(server.env_overrides ?? {}) },
         argsAppend: [...(server.args_append ?? [])],
         extraHeaders: { ...(server.extra_headers ?? {}) },
+        displayName: initialDisplayName,
+        initialDisplayName,
       });
       return;
     }
@@ -734,14 +741,17 @@ export function ServersPage() {
     serverInputs.forEach((input: InputDefinition) => {
       initialValues[input.id] = server.input_values[input.id] || '';
     });
+    const initialDisplayName = server.name ?? '';
     setConfigModal({
       open: true,
       server,
       inputValues: initialValues,
-      enableOnSave: false, // Just configure, don't enable
+      enableOnSave: false,
       envOverrides: { ...(server.env_overrides ?? {}) },
       argsAppend: [...(server.args_append ?? [])],
       extraHeaders: { ...(server.extra_headers ?? {}) },
+      displayName: initialDisplayName,
+      initialDisplayName,
     });
   };
 
@@ -763,6 +773,7 @@ export function ServersPage() {
 
       return {
         ...definition,
+        name: resolveInstalledDisplayName(cloned, definition),
         is_installed: true,
         enabled: cloned.enabled,
         oauth_connected: cloned.oauth_connected,
@@ -801,19 +812,22 @@ export function ServersPage() {
 
   const handleSaveConfig = async () => {
     if (!configModal.server) return;
-    
+
     const server = configModal.server;
     const serverId = server.id;
     const shouldEnable = configModal.enableOnSave ?? false;
-    
+
     setActionLoading(`config-${serverId}`);
     try {
       const { saveServerInputs } = await import('@/lib/api/registry');
 
-      // Save input values with env overrides, args, and headers.
-      // Always send the values (even if empty) so that clearing them works.
-      // Backend treats None as "keep existing", so we must send Some({}/[])
-      // to actually clear fields the user removed.
+      const trimmedDisplayName = configModal.displayName.trim();
+      const trimmedInitial = configModal.initialDisplayName.trim();
+      // Only send a value when the user actually edited the field; otherwise pass
+      // undefined so the backend leaves the existing override untouched.
+      const displayNameOverride =
+        trimmedDisplayName === trimmedInitial ? undefined : trimmedDisplayName;
+
       await saveServerInputs(
         serverId,
         configModal.inputValues,
@@ -821,9 +835,19 @@ export function ServersPage() {
         configModal.envOverrides,
         configModal.argsAppend,
         configModal.extraHeaders,
+        displayNameOverride,
       );
 
-      setConfigModal({ open: false, server: null, inputValues: {}, envOverrides: {}, argsAppend: [], extraHeaders: {} });
+      setConfigModal({
+        open: false,
+        server: null,
+        inputValues: {},
+        envOverrides: {},
+        argsAppend: [],
+        extraHeaders: {},
+        displayName: '',
+        initialDisplayName: '',
+      });
       
       // Only enable if requested (from Enable flow)
       if (shouldEnable && !server.enabled) {
@@ -861,7 +885,16 @@ export function ServersPage() {
       // Set the server to pending_config state by enabling but not connecting
       // Actually, we just close the modal - the UI already shows Configure button for missing inputs
     }
-    setConfigModal({ open: false, server: null, inputValues: {}, envOverrides: {}, argsAppend: [], extraHeaders: {} });
+    setConfigModal({
+      open: false,
+      server: null,
+      inputValues: {},
+      envOverrides: {},
+      argsAppend: [],
+      extraHeaders: {},
+      displayName: '',
+      initialDisplayName: '',
+    });
   };
 
   // Cancel OAuth flow - uses new ServerManager v2
@@ -1673,8 +1706,31 @@ export function ServersPage() {
             <p className="text-sm text-[rgb(var(--muted))] mb-4">
               {(configModal.server.auth && 'instructions' in configModal.server.auth ? configModal.server.auth.instructions : null) || 'Enter the required configuration to enable this server.'}
             </p>
-            
+
             <div className="space-y-4">
+              <div>
+                <label
+                  htmlFor="config-display-name"
+                  className="block text-sm font-medium text-[rgb(var(--foreground))] mb-1"
+                >
+                  Display name
+                </label>
+                <p className="text-xs text-[rgb(var(--muted))] mb-2">
+                  Shown in My Servers only. Does not change the server ID or tool names.
+                </p>
+                <input
+                  id="config-display-name"
+                  type="text"
+                  value={configModal.displayName}
+                  onChange={(e) =>
+                    setConfigModal({ ...configModal, displayName: e.target.value })
+                  }
+                  placeholder={configModal.server.name}
+                  className="input w-full"
+                  data-testid="config-display-name"
+                />
+              </div>
+
               {(configModal.server.transport.metadata?.inputs ?? []).map((input: InputDefinition) => {
                 const obtainUrl = input.obtain_url || input.obtain?.url;
                 const obtainInstructions = input.obtain_instructions || input.obtain?.instructions;
diff --git a/apps/desktop/src/features/servers/UninstallSourceWithClonesDialog.tsx b/apps/desktop/src/features/servers/UninstallSourceWithClonesDialog.tsx
index 92b393fb..0ac1c14b 100644
--- a/apps/desktop/src/features/servers/UninstallSourceWithClonesDialog.tsx
+++ b/apps/desktop/src/features/servers/UninstallSourceWithClonesDialog.tsx
@@ -1,8 +1,10 @@
 import { AlertCircle } from 'lucide-react';
+import { resolveInstalledDisplayName } from './server-display-name.helpers';
 
 export interface CloneDependentSummary {
   server_id: string;
   server_name?: string | null;
+  display_name_override?: string | null;
 }
 
 interface UninstallSourceWithClonesDialogProps {
@@ -29,8 +31,12 @@ export function UninstallSourceWithClonesDialog({
     return null;
   }
 
-  const dependentLabels = dependents.map(
-    (dependent) => dependent.server_name ?? dependent.server_id
+  const dependentLabels = dependents.map((dependent) =>
+    resolveInstalledDisplayName({
+      server_id: dependent.server_id,
+      server_name: dependent.server_name ?? null,
+      display_name_override: dependent.display_name_override ?? null,
+    })
   );
   const dependentList = dependentLabels.join(', ');
   const totalCount = dependents.length + 1;
@@ -42,7 +48,7 @@ export function UninstallSourceWithClonesDialog({
       data-testid="uninstall-clones-dialog-overlay"
     >
       <div
-        className="mx-4 w-full max-w-md rounded-xl border border-[rgb(var(--border))] bg-[rgb(var(--card))] p-6 shadow-xl animate-in fade-in zoom-in-95 duration-200"
+        className="animate-in fade-in zoom-in-95 mx-4 w-full max-w-md rounded-xl border border-[rgb(var(--border))] bg-[rgb(var(--card))] p-6 shadow-xl duration-200"
         onClick={(event) => event.stopPropagation()}
         data-testid="uninstall-clones-dialog"
       >
diff --git a/apps/desktop/src/features/servers/server-display-name.helpers.ts b/apps/desktop/src/features/servers/server-display-name.helpers.ts
new file mode 100644
index 00000000..7a3eadf9
--- /dev/null
+++ b/apps/desktop/src/features/servers/server-display-name.helpers.ts
@@ -0,0 +1,32 @@
+import type { InstalledServerState, ServerDefinition } from '@/types/registry';
+
+/**
+ * Resolve the effective display label for an installed server.
+ *
+ * Mirrors the Rust `InstalledServer::display_name()` precedence so the UI and
+ * meta-tools agree on what to show. Order:
+ * 1. `display_name_override` (user-supplied, survives user-config sync)
+ * 2. `server_name` cached from the definition at install time
+ * 3. `definition.name` if a parsed registry definition is provided
+ * 4. Final segment of `server_id`
+ */
+export function resolveInstalledDisplayName(
+  state: Pick<InstalledServerState, 'server_id' | 'server_name' | 'display_name_override'>,
+  definition?: Pick<ServerDefinition, 'name'> | null
+): string {
+  const override = state.display_name_override?.trim();
+  if (override) {
+    return override;
+  }
+
+  if (state.server_name && state.server_name.length > 0) {
+    return state.server_name;
+  }
+
+  if (definition?.name) {
+    return definition.name;
+  }
+
+  const tail = state.server_id.split('/').pop();
+  return tail && tail.length > 0 ? tail : state.server_id;
+}
diff --git a/apps/desktop/src/lib/api/registry.ts b/apps/desktop/src/lib/api/registry.ts
index 4128f0ee..cce4a258 100644
--- a/apps/desktop/src/lib/api/registry.ts
+++ b/apps/desktop/src/lib/api/registry.ts
@@ -3,7 +3,13 @@
  */
 
 import { invoke } from '@tauri-apps/api/core';
-import type { RegistryCategory, ServerDefinition, InstalledServerState, UiConfig, HomeConfig } from '../../types/registry';
+import type {
+  RegistryCategory,
+  ServerDefinition,
+  InstalledServerState,
+  UiConfig,
+  HomeConfig,
+} from '../../types/registry';
 
 /** Discover all servers (definitions from all sources) */
 export async function discoverServers(): Promise<ServerDefinition[]> {
@@ -25,7 +31,7 @@ export async function isRegistryOffline(): Promise<boolean> {
   return invoke<boolean>('is_registry_offline');
 }
 
-/** Force refresh server discovery from all sources (ignores cache) 
+/** Force refresh server discovery from all sources (ignores cache)
  * Returns number of newly auto-installed user-configured servers */
 export async function refreshRegistry(): Promise<number> {
   return invoke<number>('refresh_registry');
@@ -87,7 +93,30 @@ export async function saveServerInputs(
   spaceId: string,
   envOverrides?: Record<string, string>,
   argsAppend?: string[],
-  extraHeaders?: Record<string, string>
+  extraHeaders?: Record<string, string>,
+  displayNameOverride?: string
 ): Promise<void> {
-  return invoke<void>('save_server_inputs', { id, inputValues, spaceId, envOverrides, argsAppend, extraHeaders });
+  return invoke<void>('save_server_inputs', {
+    id,
+    inputValues,
+    spaceId,
+    envOverrides,
+    argsAppend,
+    extraHeaders,
+    displayNameOverride,
+  });
+}
+
+/**
+ * Set or clear the user-supplied display label for an installed server.
+ *
+ * Pass an empty string to clear the override; the UI then falls back to the cached
+ * definition name. Does not change `server_id`, alias, or tool prefixes.
+ */
+export async function setServerDisplayName(
+  id: string,
+  spaceId: string,
+  displayName: string
+): Promise<void> {
+  return invoke<void>('set_server_display_name', { id, spaceId, displayName });
 }
diff --git a/apps/desktop/src/lib/api/serverClone.ts b/apps/desktop/src/lib/api/serverClone.ts
index 21943685..a32cc06e 100644
--- a/apps/desktop/src/lib/api/serverClone.ts
+++ b/apps/desktop/src/lib/api/serverClone.ts
@@ -15,18 +15,24 @@ export interface ClonedInstalledServer extends InstalledServerState {
 
 /**
  * Clone an installed server into a new suffixed manual-entry install in the same space.
+ *
+ * `displayName` is optional; when set, it is stored as the user-supplied display label
+ * (`display_name_override`) and survives later definition refreshes. When omitted, the
+ * UI falls back to the auto `"Source (suffix)"` cached definition name.
  */
 export async function cloneServer(
   spaceId: string,
   sourceServerId: string,
   suffix: string,
-  alias?: string
+  alias?: string,
+  displayName?: string
 ): Promise<ClonedInstalledServer> {
   return invoke<ClonedInstalledServer>('clone_server', {
     spaceId,
     sourceServerId,
     suffix,
     alias: alias ?? null,
+    displayName: displayName ?? null,
   });
 }
 
@@ -48,10 +54,7 @@ export async function isCloneIdAvailable(
 /**
  * Suggest the first available default suffix for cloning a server.
  */
-export async function suggestCloneSuffix(
-  spaceId: string,
-  sourceServerId: string
-): Promise<string> {
+export async function suggestCloneSuffix(spaceId: string, sourceServerId: string): Promise<string> {
   return invoke<string>('suggest_clone_suffix', {
     spaceId,
     sourceServerId,
diff --git a/apps/desktop/src/stores/registryStore.ts b/apps/desktop/src/stores/registryStore.ts
index 98bba9cd..e0cf2d4c 100644
--- a/apps/desktop/src/stores/registryStore.ts
+++ b/apps/desktop/src/stores/registryStore.ts
@@ -16,6 +16,7 @@ import type {
   SortOption,
 } from '../types/registry';
 import * as api from '../lib/api/registry';
+import { resolveInstalledDisplayName } from '../features/servers/server-display-name.helpers';
 
 // ============================================
 // State & Actions Types
@@ -368,6 +369,7 @@ function mergeServers(defs: ServerDefinition[], states: InstalledServerState[]):
     
     return {
       ...def,
+      name: state ? resolveInstalledDisplayName(state, def) : def.name,
       is_installed: !!state,
       enabled: state?.enabled ?? false,
       oauth_connected: state?.oauth_connected ?? false,
diff --git a/apps/desktop/src/types/registry.ts b/apps/desktop/src/types/registry.ts
index 991b7bce..4a1b42da 100644
--- a/apps/desktop/src/types/registry.ts
+++ b/apps/desktop/src/types/registry.ts
@@ -101,6 +101,8 @@ export interface InstalledServerState {
   extra_headers: Record<string, string>;
   oauth_connected: boolean;
   source: InstallationSource; // How this server was installed
+  /** User-supplied display label that survives user-config sync. */
+  display_name_override?: string | null;
   created_at: string;
   updated_at: string;
 }
diff --git a/crates/mcpmux-core/src/application/server.rs b/crates/mcpmux-core/src/application/server.rs
index 63477909..dc344170 100644
--- a/crates/mcpmux-core/src/application/server.rs
+++ b/crates/mcpmux-core/src/application/server.rs
@@ -102,13 +102,18 @@ impl ServerAppService {
     /// Clone an installed server into a new manual-entry install in the same space.
     ///
     /// Copies the source `cached_definition`, assigns a suffixed `server_id`, clears credentials,
-    /// and records lineage in `cloned_from`. Emits: `ServerInstalled`
+    /// and records lineage in `cloned_from`. When `display_name_override` is provided it is
+    /// stored as the user-supplied label (UI / meta tools prefer it); otherwise the auto
+    /// `"Source (suffix)"` label on `definition.name` is used as fallback.
+    ///
+    /// Emits: `ServerInstalled`
     pub async fn clone_server(
         &self,
         space_id: Uuid,
         source_server_id: &str,
         suffix: &str,
         alias_override: Option<&str>,
+        display_name_override: Option<&str>,
     ) -> Result<InstalledServer> {
         let space_id_str = space_id.to_string();
         let new_server_id = Self::derive_clone_server_id(source_server_id, suffix)?;
@@ -145,6 +150,7 @@ impl ServerAppService {
             .with_definition(&definition)
             .with_source(InstallationSource::ManualEntry)
             .with_cloned_from(source_server_id)
+            .with_display_name_override(display_name_override)
             .with_enabled(false);
 
         self.server_repo.install(&server).await?;
@@ -156,10 +162,15 @@ impl ServerAppService {
             "[ServerAppService] Cloned server"
         );
 
+        let event_name = server
+            .display_name_override
+            .clone()
+            .unwrap_or_else(|| definition.name.clone());
+
         self.event_sender.emit(DomainEvent::ServerInstalled {
             space_id,
             server_id: new_server_id.clone(),
-            server_name: definition.name.clone(),
+            server_name: event_name,
         });
 
         Ok(server)
@@ -349,9 +360,15 @@ impl ServerAppService {
         Ok(())
     }
 
-    /// Update server configuration (inputs, env overrides, args, headers)
+    /// Update server configuration (inputs, env overrides, args, headers, display label).
+    ///
+    /// `display_name_override` semantics:
+    /// - `None` — leave existing override unchanged.
+    /// - `Some(value)` — normalize via [`InstalledServer::with_display_name_override`] so
+    ///   empty/whitespace clears the override and any other value replaces it.
     ///
     /// Emits: `ServerConfigUpdated`
+    #[allow(clippy::too_many_arguments)]
     pub async fn update_config(
         &self,
         space_id: Uuid,
@@ -360,6 +377,7 @@ impl ServerAppService {
         env_overrides: Option<HashMap<String, String>>,
         args_append: Option<Vec<String>>,
         extra_headers: Option<HashMap<String, String>>,
+        display_name_override: Option<String>,
     ) -> Result<InstalledServer> {
         let space_id_str = space_id.to_string();
 
@@ -379,6 +397,11 @@ impl ServerAppService {
         if let Some(headers) = extra_headers {
             server.extra_headers = headers;
         }
+        if let Some(value) = display_name_override {
+            server.display_name_override = Some(value)
+                .map(|s| s.trim().to_string())
+                .filter(|s| !s.is_empty());
+        }
         server.updated_at = chrono::Utc::now();
 
         self.server_repo.update(&server).await?;
@@ -398,6 +421,49 @@ impl ServerAppService {
         Ok(server)
     }
 
+    /// Set or clear the user-supplied display name for an installed server.
+    ///
+    /// Empty/whitespace values clear the override. Emits `ServerConfigUpdated` so the UI
+    /// re-renders the server list with the new label.
+    pub async fn set_display_name_override(
+        &self,
+        space_id: Uuid,
+        server_id: &str,
+        value: Option<String>,
+    ) -> Result<InstalledServer> {
+        let space_id_str = space_id.to_string();
+
+        let server = self
+            .server_repo
+            .get_by_server_id(&space_id_str, server_id)
+            .await?
+            .ok_or_else(|| anyhow!("Server not installed"))?;
+
+        let normalized = value
+            .map(|s| s.trim().to_string())
+            .filter(|s| !s.is_empty());
+
+        self.server_repo
+            .set_display_name_override(&server.id, normalized.clone())
+            .await?;
+
+        info!(
+            space_id = %space_id,
+            server_id = server_id,
+            has_override = normalized.is_some(),
+            "[ServerAppService] Updated display name override"
+        );
+
+        self.event_sender.emit(DomainEvent::ServerConfigUpdated {
+            space_id,
+            server_id: server_id.to_string(),
+        });
+
+        let mut updated = server;
+        updated.display_name_override = normalized;
+        Ok(updated)
+    }
+
     /// Enable a server
     ///
     /// Emits: `ServerEnabled`
@@ -646,6 +712,17 @@ mod tests {
             }
             Ok(())
         }
+
+        async fn set_display_name_override(
+            &self,
+            id: &Uuid,
+            value: Option<String>,
+        ) -> crate::repository::RepoResult<()> {
+            if let Some(server) = self.servers.write().unwrap().get_mut(id) {
+                server.display_name_override = value;
+            }
+            Ok(())
+        }
     }
 
     fn sample_definition(server_id: &str, name: &str) -> ServerDefinition {
@@ -693,7 +770,7 @@ mod tests {
         let service = build_service(repo.clone());
 
         let cloned = service
-            .clone_server(space_id, "posthog", "work", None)
+            .clone_server(space_id, "posthog", "work", None, None)
             .await
             .expect("clone should succeed");
 
@@ -703,6 +780,7 @@ mod tests {
         assert!(!cloned.enabled);
         assert!(cloned.input_values.is_empty());
         assert_eq!(cloned.server_name.as_deref(), Some("PostHog (work)"));
+        assert!(cloned.display_name_override.is_none());
 
         let definition = cloned.get_definition().expect("definition cached");
         assert_eq!(definition.id, "posthog-work");
@@ -733,7 +811,7 @@ mod tests {
         let service = build_service(repo);
 
         let error = service
-            .clone_server(space_id, "posthog", "work", None)
+            .clone_server(space_id, "posthog", "work", None, None)
             .await
             .expect_err("collision should fail");
 
@@ -747,7 +825,7 @@ mod tests {
         let service = build_service(repo);
 
         let error = service
-            .clone_server(space_id, "posthog", "work", None)
+            .clone_server(space_id, "posthog", "work", None, None)
             .await
             .expect_err("missing source should fail");
 
@@ -765,7 +843,7 @@ mod tests {
         let service = build_service(repo);
 
         let cloned = service
-            .clone_server(space_id, "posthog", "my_work", None)
+            .clone_server(space_id, "posthog", "my_work", None, None)
             .await
             .expect("clone should succeed");
 
@@ -840,6 +918,128 @@ mod tests {
         assert!(ids.contains(&"posthog-personal"));
     }
 
+    #[tokio::test]
+    async fn clone_server_with_display_name_persists_override() {
+        let space_id = Uuid::new_v4();
+        let space_id_str = space_id.to_string();
+        let source = InstalledServer::new(&space_id_str, "posthog")
+            .with_definition(&sample_definition("posthog", "PostHog"));
+
+        let repo = Arc::new(InMemoryInstalledServerRepo::new().with_server(source));
+        let service = build_service(repo.clone());
+
+        let cloned = service
+            .clone_server(space_id, "posthog", "work", None, Some("Work account"))
+            .await
+            .expect("clone with display name");
+
+        assert_eq!(cloned.server_id, "posthog-work");
+        assert_eq!(
+            cloned.display_name_override.as_deref(),
+            Some("Work account")
+        );
+        assert_eq!(cloned.display_name(), "Work account");
+        assert_eq!(cloned.server_name.as_deref(), Some("PostHog (work)"));
+    }
+
+    #[tokio::test]
+    async fn set_display_name_override_sets_and_clears() {
+        let space_id = Uuid::new_v4();
+        let space_id_str = space_id.to_string();
+        let source = InstalledServer::new(&space_id_str, "posthog")
+            .with_definition(&sample_definition("posthog", "PostHog"));
+
+        let repo = Arc::new(InMemoryInstalledServerRepo::new().with_server(source));
+        let service = build_service(repo.clone());
+
+        let renamed = service
+            .set_display_name_override(space_id, "posthog", Some("  Joe Calendar  ".into()))
+            .await
+            .expect("set override");
+        assert_eq!(
+            renamed.display_name_override.as_deref(),
+            Some("Joe Calendar")
+        );
+
+        let stored = repo
+            .get_by_server_id(&space_id_str, "posthog")
+            .await
+            .unwrap()
+            .expect("server persisted");
+        assert_eq!(
+            stored.display_name_override.as_deref(),
+            Some("Joe Calendar")
+        );
+
+        let cleared = service
+            .set_display_name_override(space_id, "posthog", Some("   ".into()))
+            .await
+            .expect("clear override");
+        assert!(cleared.display_name_override.is_none());
+
+        let stored = repo
+            .get_by_server_id(&space_id_str, "posthog")
+            .await
+            .unwrap()
+            .expect("server persisted");
+        assert!(stored.display_name_override.is_none());
+        assert_eq!(stored.display_name(), "PostHog");
+    }
+
+    #[tokio::test]
+    async fn update_config_with_display_name_override_persists() {
+        let space_id = Uuid::new_v4();
+        let space_id_str = space_id.to_string();
+        let source = InstalledServer::new(&space_id_str, "posthog")
+            .with_definition(&sample_definition("posthog", "PostHog"));
+
+        let repo = Arc::new(InMemoryInstalledServerRepo::new().with_server(source));
+        let service = build_service(repo.clone());
+
+        let updated = service
+            .update_config(
+                space_id,
+                "posthog",
+                HashMap::new(),
+                None,
+                None,
+                None,
+                Some("My Calendar".into()),
+            )
+            .await
+            .expect("update with display name");
+
+        assert_eq!(
+            updated.display_name_override.as_deref(),
+            Some("My Calendar")
+        );
+
+        // None leaves the existing override untouched.
+        let untouched = service
+            .update_config(space_id, "posthog", HashMap::new(), None, None, None, None)
+            .await
+            .expect("update without display name");
+        assert_eq!(
+            untouched.display_name_override.as_deref(),
+            Some("My Calendar")
+        );
+
+        // Empty string clears.
+        let cleared = service
+            .update_config(
+                space_id,
+                "posthog",
+                HashMap::new(),
+                None,
+                None,
+                None,
+                Some("   ".into()),
+            )
+            .await
+            .expect("clear override via update_config");
+        assert!(cleared.display_name_override.is_none());
+    }
+
     #[tokio::test]
     async fn uninstall_clone_preserves_source() {
         let space_id = Uuid::new_v4();
diff --git a/crates/mcpmux-core/src/domain/installed_server.rs b/crates/mcpmux-core/src/domain/installed_server.rs
index 41d9d493..2e58c76c 100644
--- a/crates/mcpmux-core/src/domain/installed_server.rs
+++ b/crates/mcpmux-core/src/domain/installed_server.rs
@@ -85,6 +85,14 @@ pub struct InstalledServer {
     #[serde(default)]
     pub cloned_from: Option<String>,
 
+    /// User-supplied display label that survives user-config sync.
+    ///
+    /// When set, the UI and meta tools prefer this over `server_name` /
+    /// `cached_definition.name`. The `server_id`, alias, and tool prefixes are
+    /// unaffected.
+    #[serde(default)]
+    pub display_name_override: Option<String>,
+
     /// Creation timestamp
     pub created_at: DateTime<Utc>,
 
@@ -112,6 +120,7 @@ impl InstalledServer {
             oauth_connected: false,
             source: InstallationSource::default(),
             cloned_from: None,
+            display_name_override: None,
             created_at: now,
             updated_at: now,
         }
@@ -131,8 +140,14 @@ impl InstalledServer {
             .and_then(|json| serde_json::from_str(json).ok())
     }
 
-    /// Get display name (from cached definition or server_id fallback)
+    /// Get effective display name.
+    ///
+    /// Precedence: `display_name_override` (user-supplied) → `server_name`
+    /// (cached at install time) → final segment of `server_id`.
     pub fn display_name(&self) -> &str {
+        if let Some(override_name) = self.display_name_override.as_deref() {
+            return override_name;
+        }
         self.server_name.as_deref().unwrap_or_else(|| {
             self.server_id
                 .split('/')
@@ -141,6 +156,15 @@ impl InstalledServer {
         })
     }
 
+    /// Set the user-supplied display override (None or empty/whitespace clears it).
+    pub fn with_display_name_override(mut self, value: Option<impl Into<String>>) -> Self {
+        self.display_name_override = value
+            .map(Into::into)
+            .map(|s| s.trim().to_string())
+            .filter(|s| !s.is_empty());
+        self
+    }
+
     /// Set input values
     pub fn with_inputs(mut self, inputs: HashMap<String, String>) -> Self {
         self.input_values = inputs;
@@ -461,4 +485,54 @@ mod tests {
         assert_eq!(deserialized.args_append.len(), 100);
         assert_eq!(deserialized.args_append[99], "--arg-99");
     }
+
+    #[test]
+    fn test_display_name_override_takes_precedence() {
+        let mut server = InstalledServer::new("space_default", "google.com/calendar");
+        server.server_name = Some("Google Calendar".to_string());
+
+        assert_eq!(server.display_name(), "Google Calendar");
+
+        server.display_name_override = Some("Joe Calendar".to_string());
+        assert_eq!(server.display_name(), "Joe Calendar");
+    }
+
+    #[test]
+    fn test_with_display_name_override_trims_and_clears() {
+        let server = InstalledServer::new("space_default", "test-server")
+            .with_display_name_override(Some("  Work Account  "));
+        assert_eq!(
+            server.display_name_override.as_deref(),
+            Some("Work Account")
+        );
+
+        let cleared = server.with_display_name_override(Some("   "));
+        assert!(cleared.display_name_override.is_none());
+
+        let none_clears = InstalledServer::new("space_default", "test-server")
+            .with_display_name_override(Some("Name"))
+            .with_display_name_override(Option::<String>::None);
+        assert!(none_clears.display_name_override.is_none());
+    }
+
+    #[test]
+    fn test_display_name_override_default_on_deserialize() {
+        let json = r#"{
+            "id": "00000000-0000-0000-0000-000000000001",
+            "space_id": "space_default",
+            "server_id": "test-server",
+            "server_name": "Catalog Name",
+            "cached_definition": null,
+            "input_values": {},
+            "enabled": false,
+            "oauth_connected": false,
+            "source": {"type": "registry"},
+            "created_at": "2025-01-01T00:00:00Z",
+            "updated_at": "2025-01-01T00:00:00Z"
+        }"#;
+
+        let server: InstalledServer = serde_json::from_str(json).expect("Failed to deserialize");
+        assert!(server.display_name_override.is_none());
+        assert_eq!(server.display_name(), "Catalog Name");
+    }
 }
diff --git a/crates/mcpmux-core/src/repository/mod.rs b/crates/mcpmux-core/src/repository/mod.rs
index 409ce6d9..73381d51 100644
--- a/crates/mcpmux-core/src/repository/mod.rs
+++ b/crates/mcpmux-core/src/repository/mod.rs
@@ -99,6 +99,12 @@ pub trait InstalledServerRepository: Send + Sync {
         server_name: Option<String>,
         cached_definition: Option<String>,
     ) -> RepoResult<()>;
+
+    /// Set or clear the user-supplied display name override for an installed server.
+    ///
+    /// Pass `None` to clear the override (UI falls back to `server_name` /
+    /// `cached_definition.name` / `server_id` tail).
+    async fn set_display_name_override(&self, id: &Uuid, value: Option<String>) -> RepoResult<()>;
 }
 
 /// ServerFeature repository trait
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
index e0d0170c..1c651d94 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
@@ -257,9 +257,24 @@ impl MetaTool for ListServersTool {
             .list_for_space(&space_id.to_string())
             .await
             .map_err(|e| MetaToolError::Internal(e.to_string()))?;
-        let cloned_from_by_server: HashMap<String, Option<String>> = installed
+        // Per-server lookup of effective display name (override → server_name → tail)
+        // and clone lineage. Centralized so JSON output and UI agree on the label.
+        struct InstalledMeta {
+            display_name: String,
+            cloned_from: Option<String>,
+        }
+        let installed_meta_by_server: HashMap<String, InstalledMeta> = installed
             .into_iter()
-            .map(|s| (s.server_id, s.cloned_from))
+            .map(|s| {
+                let display_name = s.display_name().to_string();
+                (
+                    s.server_id,
+                    InstalledMeta {
+                        display_name,
+                        cloned_from: s.cloned_from,
+                    },
+                )
+            })
             .collect();
 
         let mut by_server: HashMap<String, (Option<String>, usize)> = HashMap::new();
@@ -278,8 +293,14 @@ impl MetaTool for ListServersTool {
 
         let mut servers: Vec<Value> = by_server
             .into_iter()
-            .map(|(id, (display_name, tool_count))| {
-                let name = display_name.unwrap_or_else(|| id.clone());
+            .map(|(id, (feature_display_name, tool_count))| {
+                // Prefer the installed row's effective display name (override or
+                // server_name) so users see "Joe Calendar" instead of the catalog name.
+                let installed_meta = installed_meta_by_server.get(&id);
+                let name = installed_meta
+                    .map(|meta| meta.display_name.clone())
+                    .or(feature_display_name)
+                    .unwrap_or_else(|| id.clone());
                 let status = derive_server_status(
                     &id,
                     &binding_servers,
@@ -292,7 +313,8 @@ impl MetaTool for ListServersTool {
                     "tool_count": tool_count,
                     "status": status,
                 });
-                if let Some(cloned_from) = cloned_from_by_server.get(&id).and_then(|v| v.as_ref()) {
+                if let Some(cloned_from) = installed_meta.and_then(|meta| meta.cloned_from.as_ref())
+                {
                     entry["cloned_from"] = json!(cloned_from);
                 }
                 entry
diff --git a/crates/mcpmux-storage/src/database.rs b/crates/mcpmux-storage/src/database.rs
index 630b4b25..ce160c52 100644
--- a/crates/mcpmux-storage/src/database.rs
+++ b/crates/mcpmux-storage/src/database.rs
@@ -118,6 +118,11 @@ const MIGRATIONS: &[Migration] = &[
         name: "installed_server_cloned_from",
         sql: include_str!("migrations/017_installed_server_cloned_from.sql"),
     },
+    Migration {
+        version: 18,
+        name: "installed_server_display_name_override",
+        sql: include_str!("migrations/018_installed_server_display_name_override.sql"),
+    },
 ];
 
 /// SQLite database wrapper.
diff --git a/crates/mcpmux-storage/src/migrations/018_installed_server_display_name_override.sql b/crates/mcpmux-storage/src/migrations/018_installed_server_display_name_override.sql
new file mode 100644
index 00000000..868380a8
--- /dev/null
+++ b/crates/mcpmux-storage/src/migrations/018_installed_server_display_name_override.sql
@@ -0,0 +1,2 @@
+-- User-supplied display name that survives user-config sync (UI-preferred label).
+ALTER TABLE installed_servers ADD COLUMN display_name_override TEXT;
diff --git a/crates/mcpmux-storage/src/repositories/installed_server_repository.rs b/crates/mcpmux-storage/src/repositories/installed_server_repository.rs
index 33805568..7256eaf2 100644
--- a/crates/mcpmux-storage/src/repositories/installed_server_repository.rs
+++ b/crates/mcpmux-storage/src/repositories/installed_server_repository.rs
@@ -31,6 +31,7 @@ struct RawServerRow {
     updated_at: String,
     source: Option<String>,
     cloned_from: Option<String>,
+    display_name_override: Option<String>,
 }
 
 /// SQLite-backed implementation of InstalledServerRepository.
@@ -132,7 +133,8 @@ impl SqliteInstalledServerRepository {
     /// Standard column list for SELECT queries
     const SELECT_COLUMNS: &'static str =
         "id, space_id, server_id, server_name, cached_definition, input_values, enabled, env_overrides,
-         args_append, extra_headers, oauth_connected, created_at, updated_at, source, cloned_from";
+         args_append, extra_headers, oauth_connected, created_at, updated_at, source, cloned_from,
+         display_name_override";
 
     /// Extract raw row data (used in the closure passed to rusqlite).
     fn extract_row(row: &rusqlite::Row) -> rusqlite::Result<RawServerRow> {
@@ -152,6 +154,7 @@ impl SqliteInstalledServerRepository {
             updated_at: row.get(12)?,
             source: row.get(13)?,
             cloned_from: row.get(14)?,
+            display_name_override: row.get(15)?,
         })
     }
 
@@ -171,6 +174,7 @@ impl SqliteInstalledServerRepository {
             oauth_connected: row.oauth_connected,
             source: Self::parse_source(row.source),
             cloned_from: row.cloned_from,
+            display_name_override: row.display_name_override,
             created_at: Self::parse_datetime(&row.created_at),
             updated_at: Self::parse_datetime(&row.updated_at),
         }
@@ -278,8 +282,9 @@ impl InstalledServerRepository for SqliteInstalledServerRepository {
         conn.execute(
             "INSERT INTO installed_servers
              (id, space_id, server_id, server_name, cached_definition, input_values, enabled, env_overrides,
-              args_append, extra_headers, oauth_connected, created_at, updated_at, source, cloned_from)
-             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?15)",
+              args_append, extra_headers, oauth_connected, created_at, updated_at, source, cloned_from,
+              display_name_override)
+             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, ?13, ?14, ?15, ?16)",
             params![
                 server.id.to_string(),
                 server.space_id,
@@ -296,6 +301,7 @@ impl InstalledServerRepository for SqliteInstalledServerRepository {
                 server.updated_at.to_rfc3339(),
                 Self::serialize_source(&server.source),
                 server.cloned_from,
+                server.display_name_override,
             ],
         )?;
         Ok(())
@@ -311,7 +317,7 @@ impl InstalledServerRepository for SqliteInstalledServerRepository {
             "UPDATE installed_servers
              SET server_name = ?2, cached_definition = ?3, input_values = ?4, enabled = ?5,
                  env_overrides = ?6, args_append = ?7, extra_headers = ?8, oauth_connected = ?9,
-                 updated_at = ?10, source = ?11
+                 updated_at = ?10, source = ?11, display_name_override = ?12
              WHERE id = ?1",
             params![
                 server.id.to_string(),
@@ -325,6 +331,7 @@ impl InstalledServerRepository for SqliteInstalledServerRepository {
                 server.oauth_connected,
                 Utc::now().to_rfc3339(),
                 Self::serialize_source(&server.source),
+                server.display_name_override,
             ],
         )?;
         Ok(())
@@ -443,4 +450,15 @@ impl InstalledServerRepository for SqliteInstalledServerRepository {
         )?;
         Ok(())
     }
+
+    async fn set_display_name_override(&self, id: &Uuid, value: Option<String>) -> Result<()> {
+        let db = self.db.lock().await;
+        let conn = db.connection();
+
+        conn.execute(
+            "UPDATE installed_servers SET display_name_override = ?2, updated_at = ?3 WHERE id = ?1",
+            params![id.to_string(), value, Utc::now().to_rfc3339()],
+        )?;
+        Ok(())
+    }
 }
diff --git a/docs/planning/server-display-rename.md b/docs/planning/server-display-rename.md
new file mode 100644
index 00000000..88a60004
--- /dev/null
+++ b/docs/planning/server-display-rename.md
@@ -0,0 +1,132 @@
+# Server Display Rename
+
+**Last Updated:** May 25, 2026
+**Status:** Complete — Phases 1–4 shipped
+**Branch:** `feat/server-account-clones` (continuation of clone work)
+**Base branch:** `main`
+**Depends on:** [Server Account Clones](server-account-clones.md) (Phase 1–4 shipped)
+**Unblocks:** Multi-account UX — distinguishing two installs of the same MCP (e.g. two Google Calendars) without renaming `server_id`
+
+---
+
+## Problem
+
+Once a Space has multiple installs of the same MCP — either via the clone wizard or a hand-edited user-config JSON — the only thing telling them apart in the UI is the cached definition name (`Google Calendar`, `Google Calendar (work)`). That string lives on `cached_definition` and `server_name`, both of which the user cannot edit and both of which `user_space_sync` overwrites on every config sync.
+
+Users want a friendly per-install label that:
+
+- They can edit any time, not just at clone time.
+- Survives later definition refreshes (registry pulls, user-config sync).
+- Does not affect routing — `server_id`, alias, or tool prefixes stay locked once chosen, otherwise existing tool names break.
+
+---
+
+## Decisions
+
+| # | Decision | Choice | Rationale |
+| - | -------- | ------ | --------- |
+| 1 | Identity vs label | **Display label only now**; `server_id` / alias / tool prefixes unchanged | Renaming the ID would invalidate every prompt, binding, and tool name referencing the server. Labels are reversible; IDs are not. |
+| 2 | Storage shape | New nullable `display_name_override` column on `installed_servers` (migration 018) | `server_name` is overwritten on every user-config sync, so the override needs its own column to survive. |
+| 3 | Eligible installs | Registry, manual, clones, and user-config installs are all renamable | Users want to label *any* install — not just clones. |
+| 4 | Uniqueness | Duplicate display names allowed in a space | The `server_id` is already unique; labels are pure UX. |
+| 5 | Configure surface | Display name field at top of the Configure modal, with helper text "Shown in My Servers only. Does not change the server ID or tool names." | Single place users already go to edit a server. |
+| 6 | Clone wizard | Optional freeform display name + existing suffix (suffix still drives `server_id` / alias) | Lets users pick a friendly name at clone time without giving up suffix-driven routing. |
+| 7 | Always-show Configure | Action menu shows Configure (renamed to "Settings" when there are no inputs) for every installed server | Servers without credential inputs still need a way to be renamed. |
+| 8 | Meta-tool surfacing | `mcpmux_list_servers` reports the effective display name (override → `server_name` → `server_id` tail) | Agents see "Joe Calendar" instead of the catalog name when the user has renamed an install. |
+
+---
+
+## The Model
+
+```mermaid
+flowchart LR
+  subgraph storage [Storage]
+    override["display_name_override"]
+    server_name["server_name / cached_definition"]
+  end
+  subgraph ui [Desktop UI]
+    configure["Configure modal"]
+    clone["Clone wizard"]
+    list["My Servers list / search"]
+  end
+  subgraph api [API]
+    save["save_server_inputs"]
+    set_name["set_server_display_name"]
+    clone_api["clone_server"]
+  end
+  configure --> save --> override
+  clone --> clone_api --> override
+  configure --> set_name --> override
+  override --> list
+  server_name --> list
+```
+
+`InstalledServer::display_name()` is the single source of truth for the effective label:
+
+```rust
+override
+  .or(server_name)
+  .or(server_id.split('/').last())
+```
+
+The frontend `resolveInstalledDisplayName` mirrors that precedence so every code path agrees on what to render.
+
+---
+
+## File Inventory
+
+### Phase 1 — Storage and domain (✅)
+
+- `crates/mcpmux-storage/src/migrations/018_installed_server_display_name_override.sql` — new column.
+- `crates/mcpmux-storage/src/database.rs` — register migration 018.
+- `crates/mcpmux-core/src/domain/installed_server.rs` — `display_name_override` field, `display_name()` precedence, `with_display_name_override` helper, unit tests.
+- `crates/mcpmux-storage/src/repositories/installed_server_repository.rs` — INSERT/UPDATE/SELECT round-trip and `set_display_name_override`.
+- `crates/mcpmux-core/src/repository/mod.rs` — trait method `set_display_name_override`.
+- `tests/rust/src/mocks.rs` — mock repo impl.
+
+### Phase 2 — Application service and Tauri (✅)
+
+- `crates/mcpmux-core/src/application/server.rs` — `clone_server` accepts optional `display_name_override`; `update_config` accepts optional `display_name_override` (None = leave alone, Some(empty) = clear, Some(value) = set); new `set_display_name_override` service method; unit tests covering set/clear via update_config and the dedicated method, plus clone-with-display-name.
+- `apps/desktop/src-tauri/src/commands/server.rs` — `save_server_inputs` extended with `display_name_override`; new `set_server_display_name` command.
+- `apps/desktop/src-tauri/src/commands/server_clone.rs` — `clone_server` extended with optional `display_name`.
+- `apps/desktop/src-tauri/src/lib.rs` — register `set_server_display_name`.
+
+### Phase 3 — Frontend (✅)
+
+- `apps/desktop/src/types/registry.ts` — `display_name_override` on `InstalledServerState`.
+- `apps/desktop/src/features/servers/server-display-name.helpers.ts` — new `resolveInstalledDisplayName` helper.
+- `apps/desktop/src/features/servers/ServersPage.tsx` — view-model merge paths (`mergeDefinitionsWithStates`, `createOfflineServerViewModel`, `createViewModelFromClone`) use the helper; `ConfigModalState` carries `displayName` / `initialDisplayName`; modal seeds and persists the field via `saveServerInputs`.
+- `apps/desktop/src/features/servers/ServerActionMenu.tsx` — Configure action always shown ("Settings" when no inputs).
+- `apps/desktop/src/features/servers/CloneAccountModal.tsx` — optional Display name field, defaults to `{Source} ({suffix})` placeholder, sent to `clone_server`.
+- `apps/desktop/src/features/servers/UninstallSourceWithClonesDialog.tsx` — dependent labels resolved through the helper.
+- `apps/desktop/src/lib/api/registry.ts` — extended `saveServerInputs`; new `setServerDisplayName`.
+- `apps/desktop/src/lib/api/serverClone.ts` — `cloneServer` accepts `displayName`.
+- `apps/desktop/src/stores/registryStore.ts` — `mergeServers` uses the helper for installed rows.
+
+### Phase 4 — Meta tools (✅)
+
+- `crates/mcpmux-gateway/src/services/meta_tools/tools.rs` — `mcpmux_list_servers` builds `server_id → InstalledServer.display_name()` lookup and prefers it over feature-derived names.
+
+---
+
+## Out of scope
+
+- Changing `server_id`, clone suffix, or tool prefix (`alias_*`) via rename UI.
+- Phase 5 "first-class instances" (`instance_label` schema) from [server-account-clones.md](server-account-clones.md).
+- Syncing the override back into user-space JSON `label` field (future enhancement).
+
+## Risks and mitigations
+
+| Risk | Mitigation |
+|------|------------|
+| UI still shows catalog name in some surface | Centralized `resolveInstalledDisplayName` + every merge path fixed |
+| User-config sync clobbers the label | `display_name_override` lives in its own column; sync only refreshes `server_name` / `cached_definition` |
+| Configure unreachable for no-input servers | Action menu always shows Configure (renamed to "Settings") |
+| Tool names break after rename | Rename only updates the label; `server_id` and alias are immutable in v1 |
+
+## Validation
+
+- `cargo nextest run -p mcpmux-core -p mcpmux-storage` — all tests including new override coverage pass.
+- `cargo nextest run -p tests --test integration server_clone` — clone integration tests still pass with the new parameter.
+- `pnpm typecheck` — passes.
+- `pnpm validate` should be re-run before merge for full clippy + ESLint + formatting coverage.
diff --git a/tests/rust/src/mocks.rs b/tests/rust/src/mocks.rs
index 57ab83b8..2baa1fae 100644
--- a/tests/rust/src/mocks.rs
+++ b/tests/rust/src/mocks.rs
@@ -223,6 +223,13 @@ impl InstalledServerRepository for MockInstalledServerRepository {
         }
         Ok(())
     }
+
+    async fn set_display_name_override(&self, id: &Uuid, value: Option<String>) -> RepoResult<()> {
+        if let Some(server) = self.servers.write().unwrap().get_mut(id) {
+            server.display_name_override = value;
+        }
+        Ok(())
+    }
 }
 
 // ============================================================================
diff --git a/tests/rust/tests/integration/server_clone.rs b/tests/rust/tests/integration/server_clone.rs
index 2eb0bae1..78cfedc5 100644
--- a/tests/rust/tests/integration/server_clone.rs
+++ b/tests/rust/tests/integration/server_clone.rs
@@ -135,12 +135,12 @@ async fn two_clones_have_distinct_prefixes_and_env() {
 
     let clone_work = fixture
         .service
-        .clone_server(space_id, "posthog", "work", None)
+        .clone_server(space_id, "posthog", "work", None, None)
         .await
         .expect("clone work");
     let clone_personal = fixture
         .service
-        .clone_server(space_id, "posthog", "personal", None)
+        .clone_server(space_id, "posthog", "personal", None, None)
         .await
         .expect("clone personal");
 
@@ -156,6 +156,7 @@ async fn two_clones_have_distinct_prefixes_and_env() {
             )])),
             None,
             None,
+            None,
         )
         .await
         .unwrap();
@@ -171,6 +172,7 @@ async fn two_clones_have_distinct_prefixes_and_env() {
             )])),
             None,
             None,
+            None,
         )
         .await
         .unwrap();
@@ -262,7 +264,7 @@ async fn uninstall_clone_does_not_affect_source() {
         .unwrap();
     fixture
         .service
-        .clone_server(space_id, "posthog", "work", None)
+        .clone_server(space_id, "posthog", "work", None, None)
         .await
         .unwrap();
 
@@ -301,12 +303,12 @@ async fn list_clone_dependents_returns_source_clones() {
         .unwrap();
     fixture
         .service
-        .clone_server(space_id, "posthog", "work", None)
+        .clone_server(space_id, "posthog", "work", None, None)
         .await
         .unwrap();
     fixture
         .service
-        .clone_server(space_id, "posthog", "personal", None)
+        .clone_server(space_id, "posthog", "personal", None, None)
         .await
         .unwrap();
 

From cc50654d4112a776fc9eda289083affab5b9437f Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 11:11:53 -0600
Subject: [PATCH 28/48] feat(servers): smarter OAuth startup and sticky My
 Servers toolbar

Auto-connect OAuth servers on gateway boot when mux already has tokens
(stdio OAuth always attempts connect; HTTP only prompts Connect when
unauthenticated). Bootstrap oauth_connected after credential-based connect.

Pin the My Servers search/actions header while scrolling the server list.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 .../desktop/src-tauri/src/commands/gateway.rs | 18 +++-
 .../src/features/servers/ServersPage.tsx      |  9 +-
 crates/mcpmux-gateway/src/server/startup.rs   | 91 +++++++++++++++++--
 3 files changed, 103 insertions(+), 15 deletions(-)

diff --git a/apps/desktop/src-tauri/src/commands/gateway.rs b/apps/desktop/src-tauri/src/commands/gateway.rs
index f23d88e8..6150fce1 100644
--- a/apps/desktop/src-tauri/src/commands/gateway.rs
+++ b/apps/desktop/src-tauri/src/commands/gateway.rs
@@ -1575,11 +1575,12 @@ pub async fn connect_all_enabled_servers(
         errors: vec![],
     };
 
-    for (server_info, transport, _server_definition, _installed) in servers_to_connect {
+    for (server_info, transport, _server_definition, installed) in servers_to_connect {
         let space_uuid = server_info.space_id;
         let server_id = server_info.server_id.clone();
 
-        let ctx = ConnectionContext::new(space_uuid, server_id.clone(), transport);
+        let ctx = ConnectionContext::new(space_uuid, server_id.clone(), transport)
+            .with_auto_reconnect(true);
         match pool_service.connect_server(&ctx).await {
             ConnectionResult::Connected { reused, features } => {
                 if reused {
@@ -1588,6 +1589,19 @@ pub async fn connect_all_enabled_servers(
                     result.connected += 1;
                 }
 
+                if server_info.requires_oauth && !installed.oauth_connected {
+                    if let Err(e) = app_state
+                        .installed_server_repository
+                        .set_oauth_connected(&installed.id, true)
+                        .await
+                    {
+                        warn!(
+                            "[Gateway] Connected {} but failed to set oauth_connected: {}",
+                            server_id, e
+                        );
+                    }
+                }
+
                 info!(
                     "[Gateway] Connected {} (reused: {}, features: {})",
                     server_id,
diff --git a/apps/desktop/src/features/servers/ServersPage.tsx b/apps/desktop/src/features/servers/ServersPage.tsx
index 2e49aacf..a829d61c 100644
--- a/apps/desktop/src/features/servers/ServersPage.tsx
+++ b/apps/desktop/src/features/servers/ServersPage.tsx
@@ -1135,7 +1135,7 @@ export function ServersPage() {
   }
 
   return (
-    <div className="space-y-6" data-testid="servers-page">
+    <div data-testid="servers-page">
       {gatewayControl.ConfirmDialogElement}
       {uninstallClonesDialog && (
         <UninstallSourceWithClonesDialog
@@ -1147,8 +1147,11 @@ export function ServersPage() {
           onUninstallAll={handleUninstallAllWithClones}
         />
       )}
-      {/* Header */}
-      <div className="space-y-4">
+      {/* Toolbar — stays visible while the server list scrolls in <main> */}
+      <div
+        className="sticky -top-6 z-20 -mx-6 mb-4 space-y-4 border-b border-[rgb(var(--border-subtle))] bg-[rgb(var(--background))] px-6 pt-6 pb-4"
+        data-testid="servers-page-toolbar"
+      >
         <div className="flex items-center justify-between gap-4">
           <div className="flex-shrink min-w-0">
             <div className="flex flex-wrap items-baseline gap-x-2 gap-y-1">
diff --git a/crates/mcpmux-gateway/src/server/startup.rs b/crates/mcpmux-gateway/src/server/startup.rs
index 9c431441..4edb1190 100644
--- a/crates/mcpmux-gateway/src/server/startup.rs
+++ b/crates/mcpmux-gateway/src/server/startup.rs
@@ -6,6 +6,7 @@
 use std::sync::Arc;
 
 use anyhow::Result;
+use mcpmux_core::domain::{AuthConfig, CredentialType, ServerDefinition, TransportConfig};
 use mcpmux_core::InstalledServer;
 use tracing::{info, warn};
 
@@ -230,16 +231,17 @@ impl StartupOrchestrator {
         let space_id = uuid::Uuid::parse_str(&server.space_id)
             .map_err(|e| anyhow::anyhow!("Invalid space_id: {}", e))?;
 
-        // Check if server requires OAuth but hasn't been approved yet
-        // This prevents auto-connect from setting "Connected" status without user approval
-        let requires_oauth = matches!(
-            definition.auth,
-            Some(mcpmux_core::domain::AuthConfig::Oauth)
-        );
+        let requires_oauth = matches!(definition.auth, Some(AuthConfig::Oauth));
 
-        if requires_oauth && !server.oauth_connected {
+        if should_skip_oauth_autoconnect(
+            requires_oauth,
+            server.oauth_connected,
+            is_stdio_transport(&definition),
+            self.has_mux_oauth_credentials(space_id, &server.server_id)
+                .await?,
+        ) {
             info!(
-                "[Startup] Skipping {}/{} - requires OAuth approval",
+                "[Startup] Skipping {}/{} - HTTP OAuth with no stored credentials and no prior approval",
                 server.space_id, server.server_id
             );
             let key = crate::pool::ServerKey::new(space_id, server.server_id.clone());
@@ -270,10 +272,27 @@ impl StartupOrchestrator {
 
         match connection_result {
             ConnectionResult::Connected { reused, features } => {
-                // Explicitly update ServerManager status to Connected
-                // While PoolService might update instance state, ServerManager is the source of truth for UI events
                 self.server_manager.set_connected(&key, features).await;
 
+                if requires_oauth && !server.oauth_connected {
+                    if let Err(e) = self
+                        .dependencies
+                        .installed_server_repo
+                        .set_oauth_connected(&server.id, true)
+                        .await
+                    {
+                        warn!(
+                            "[Startup] Connected {}/{} but failed to set oauth_connected: {}",
+                            server.space_id, server.server_id, e
+                        );
+                    } else {
+                        info!(
+                            "[Startup] Bootstrapped oauth_connected for {}/{} after credential-based connect",
+                            server.space_id, server.server_id
+                        );
+                    }
+                }
+
                 if reused {
                     Ok(ConnectOutcome::AlreadyConnected)
                 } else {
@@ -317,3 +336,55 @@ enum ConnectOutcome {
     AlreadyConnected,
     NeedsOAuth,
 }
+
+impl StartupOrchestrator {
+    /// Whether mux has a stored OAuth access token for this install.
+    async fn has_mux_oauth_credentials(
+        &self,
+        space_id: uuid::Uuid,
+        server_id: &str,
+    ) -> Result<bool> {
+        Ok(self
+            .dependencies
+            .credential_repo
+            .get(&space_id, server_id, &CredentialType::AccessToken)
+            .await?
+            .is_some())
+    }
+}
+
+/// Stdio MCPs manage auth inside the child process; do not gate on `oauth_connected`.
+fn is_stdio_transport(definition: &ServerDefinition) -> bool {
+    matches!(definition.transport, TransportConfig::Stdio { .. })
+}
+
+/// Skip auto-connect and show Connect Required only for HTTP OAuth with no mux tokens
+/// and no prior user approval (`oauth_connected`).
+fn should_skip_oauth_autoconnect(
+    requires_oauth: bool,
+    oauth_connected: bool,
+    is_stdio: bool,
+    has_mux_credentials: bool,
+) -> bool {
+    if !requires_oauth {
+        return false;
+    }
+    if is_stdio {
+        return false;
+    }
+    !oauth_connected && !has_mux_credentials
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn skip_only_http_oauth_without_credentials_or_approval() {
+        assert!(!should_skip_oauth_autoconnect(false, false, false, false));
+        assert!(!should_skip_oauth_autoconnect(true, false, true, false));
+        assert!(!should_skip_oauth_autoconnect(true, true, false, false));
+        assert!(!should_skip_oauth_autoconnect(true, false, false, true));
+        assert!(should_skip_oauth_autoconnect(true, false, false, false));
+    }
+}

From d3940bbe9bcdf45ee0996d98c089aac69c081d99 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 11:42:53 -0600
Subject: [PATCH 29/48] docs(planning): tool-level session pin meta tool

Planning doc for `mcpmux_pin_this_session` + `mcpmux_clear_session_pin`
- ephemeral session-scope tool-list pin with optional workspace persistence.
Revisits the deferred tool-level-granularity decision from
dynamic-mcp-toggle-meta-tools in light of the 240-tool context bloat
exposed by the Google Workspace clone case.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 docs/planning/tool-level-session-pin.md | 327 ++++++++++++++++++++++++
 1 file changed, 327 insertions(+)
 create mode 100644 docs/planning/tool-level-session-pin.md

diff --git a/docs/planning/tool-level-session-pin.md b/docs/planning/tool-level-session-pin.md
new file mode 100644
index 00000000..27bd76b1
--- /dev/null
+++ b/docs/planning/tool-level-session-pin.md
@@ -0,0 +1,327 @@
+# Tool-Level Session Pin Meta Tool (`mcpmux_pin_this_session`)
+
+**Last Updated:** May 25, 2026
+**Status:** Planning
+**Branch:** TBD — branch off `main` once [`dynamic-mcp-toggle-meta-tools`](./dynamic-mcp-toggle-meta-tools.md) merges
+**Base branch:** `main` (depends on the meta-tools infrastructure shipped via the dynamic-toggle PR being live)
+**Issue:** TBD — file after planning review
+**Depends on:** [`dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) — provides `SessionOverrideRegistry`, `MetaToolContext`, per-peer `tools/list_changed` plumbing, and the `gateway.session_overrides_require_approval` setting reused here
+**Supersedes:** Out-of-Scope row #1 in [`dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) — *"Tool-level granularity… no real evidence yet that tool-level matters more than server-level for token budget"*
+**Unblocks:** Per-chat tool-budget control for high-tool-count installs (Google Workspace 120 tools, cloned ×2 = 240) — see [`server-account-clones.md`](./server-account-clones.md)
+
+---
+
+## Problem
+
+The May 23 `dynamic-mcp-toggle-meta-tools` planning doc deferred tool-level granularity on the grounds that *server-level enable/disable covered the user's stated use case* and there was *no real evidence yet that tool-level mattered more than server-level for token budget*. That evidence now exists.
+
+[`server-account-clones.md`](./server-account-clones.md) shipped Phase 1–4 in mid-May, and the first heavy real-world install — Google Workspace cloned for a Personal + S2H account split — exposed the gap:
+
+| Symptom | Concrete number |
+| ------- | --------------- |
+| Tools per Google Workspace install | 120 |
+| Installs after the account clone | 2 |
+| Tools surfaced to a Cursor session that needs both accounts | 240 |
+| Approximate system-prompt tokens consumed by those 240 tool definitions | ~30–50k |
+
+Server-level overrides do not help here: both clones are wanted in the session, so neither can be disabled. `mcpmux_create_feature_set` + `mcpmux_bind_current_workspace` can carve a persistent subset, but persisting a tool list per workspace is the wrong shape for *"for the next 10 minutes I only need Gmail send + read + 8 calendar tools, drop the other 230"* — the LLM needs an ephemeral knob it can flip per task, not a binding.
+
+This doc fills that gap with **one new write tool plus a small clear tool**, both session-scoped (with an opt-in workspace-scope path that reuses the existing FeatureSet + binding plumbing). The killer detail: the plumbing for this is already wired — `SessionOverrideRegistry` exists, `FeatureService::get_tools_for_grants` is already the materialization chokepoint, per-peer `tools/list_changed` already fires after meta-tool writes. The change is additive: one new field on the registry, one new filter step at the bottom of the existing composition rule, two new `MetaTool` impls.
+
+A note on naming: `mcpmux_pin_this_session` is referenced verbatim in the meta-tools module docstring, in `SettingsPage.tsx`, in the approval-broker tests, and in the WDIO meta-tools spec — leftover from an early draft when the tool was intended to ship with the original meta-tools work. Reusing the name keeps every existing reference truthful instead of forcing a docs-only renaming pass.
+
+---
+
+## Decisions
+
+| # | Decision | Choice | Rationale |
+| - | -------- | ------ | --------- |
+| 1 | New tool vs extend existing | **One new write tool (`mcpmux_pin_this_session`) + one new write tool (`mcpmux_clear_session_pin`)** — do not overload `enable_server`/`disable_server` | Server-level and tool-level have different composition semantics (additive overlay vs exclusive replacement). Conflating them would force every call site to disambiguate. Two narrowly-scoped tools keep the surface clean. |
+| 2 | Composition with existing overrides | **Exclusive replacement applied AFTER server-level composition.** Effective = `(binding_servers ∪ session_on) − session_off`, materialize tools, then if `pinned_tools` non-empty: filter to `tools ∩ pinned_tools`. | Pin semantically means "lock to this set." Layering it on top means a pin to `["github_create_issue"]` works whether `github` is enabled via binding, via session-enable, or both — the user expresses intent (which tools they want) without caring about how those tools got into the candidate pool. |
+| 3 | Empty list semantics | **Empty `tool_qualified_names` rejected as invalid argument** — clearing is done via `mcpmux_clear_session_pin` | Avoids two paths for the same operation. Reject-on-empty matches `mcpmux_create_feature_set` which already rejects empty `tool_qualified_names`. |
+| 4 | Explicit clear vs implicit | **Dedicated `mcpmux_clear_session_pin` tool** — no args, operates on caller's session | Forces an intentional unpin, audited like any other write. Letting "pin with full list" act as clear would require the LLM to call `list_all_tools` first just to undo — wasteful and ambiguous. |
+| 5 | Naming | **`mcpmux_pin_this_session`** | Matches every existing stale reference (mod.rs docstring, SettingsPage copy, approval tests, WDIO spec). The "this_session" suffix makes scope intuitive — ergonomic mirror to the existing `mcpmux_bind_current_workspace`. |
+| 6 | Scope support | **`scope: "session"` (default) + `scope: "workspace"`** mirroring `mcpmux_enable_server` | Session is the ephemeral knob. Workspace persists the same pin set via a new auto-named custom FeatureSet bound to the caller's first reported root — single approval-gated atomic op instead of two-step `create_feature_set` + `bind_current_workspace`. |
+| 7 | Workspace-scope FeatureSet naming | **Auto-named `"Pinned: {root_basename} {YYYY-MM-DD HH:MM}"`** unless caller supplies optional `name` arg | Discoverable in the Workspaces UI after creation. Optional override lets the LLM name it meaningfully (`"Gmail send-only"`) when the user prompt makes intent clear. |
+| 8 | Approval default | **Session: auto-allow, gated by existing `gateway.session_overrides_require_approval`. Workspace: always required via `ApprovalBroker`.** | Reuses the existing setting — no new toggle. Session pin is ephemeral (dies with the MCP session) so the same risk profile as `enable_server`/`disable_server` applies. Workspace persists state, so it always shows the approval dialog with the full tool list in the diff. |
+| 9 | Override store layout | **Extend `SessionOverrideRegistry` with `pinned_tools: DashMap<SessionId, HashSet<QualifiedName>>`** — do not introduce a sibling registry | Same lifecycle (process-only, dies with session reap), same factory, same GC hook in `MCPNotifier`. Keeping it co-located concentrates session-scoped override state in one struct so `reap_dead_sessions` only needs to know about one type. |
+| 10 | Validation timing | **Validate every qualified name exists in caller's resolved Space at call time** (look up via `server_feature_repo::list_for_space`) | Rejects typos and stale tool names up-front with a clear error. Storing unresolved names would let the pin silently shrink to nothing if a server becomes unavailable. |
+| 11 | Audit decision string | **`"session_pin"` for session-scope writes, `"allow_once"` for workspace-scope approvals** | Distinct from `"session_override"` used by enable/disable so the audit log + Workspaces UI can render pin-specific rows ("pinned 12 tools" vs "enabled github"). |
+
+---
+
+## The Model
+
+### Override store extension
+
+```text
+SessionOverrideRegistry {
+    enabled       : DashMap<SessionId, HashSet<ServerId>>,        // existing
+    disabled      : DashMap<SessionId, HashSet<ServerId>>,        // existing
+    pinned_tools  : DashMap<SessionId, HashSet<QualifiedName>>,   // NEW
+}
+```
+
+`pinned_tools[sid]` stores fully qualified tool names (e.g. `"github_create_issue"`, `"google-workspace-mcp-uvx_send_email"`) — the same format `mcpmux_list_all_tools` returns and `mcpmux_create_feature_set` accepts. Empty/missing = no pin = pass-through.
+
+GC: `SessionOverrideRegistry::remove(session_id)` extended to drop `pinned_tools[sid]` alongside the existing two sets. `MCPNotifier::reap_dead_sessions` already calls `remove` per reaped session — no notifier change needed.
+
+### Composition rule
+
+The existing composition in `FeatureService::get_tools_for_grants` runs steps 1–6; this doc adds steps 7–8:
+
+```text
+1. (space, feature_set_ids) ← FeatureSetResolverService::resolve(...)
+2. binding_servers          ← FeatureService::servers_for(space, feature_set_ids)
+3. session_on               ← SessionOverrideRegistry.enabled[session_id]
+4. session_off              ← SessionOverrideRegistry.disabled[session_id]
+5. effective_servers        ← (binding_servers ∪ session_on) − session_off
+6. base_tools               ← every Tool feature whose server_id ∈ effective_servers AND is_available
+
+7. pinned ← SessionOverrideRegistry.pinned_tools[session_id]
+8. if pinned is non-empty:
+       tools ← base_tools.filter(qualified_name ∈ pinned)
+   else:
+       tools ← base_tools
+```
+
+The pin filter applies only to **tools**. Prompts and resources are unaffected — pinning is a tool-budget concept, not a capability-restriction concept. `get_prompts_for_grants` and `get_resources_for_grants` skip steps 7–8.
+
+A pin that resolves to zero matches (every name filtered out by `is_available`) returns an empty tool list. The caller's `tools/list` will show no tools; calling `mcpmux_clear_session_pin` is the recovery path. This is intentional — silent fall-through to `base_tools` on empty intersection would mask user error.
+
+### Tool surface
+
+Two new tools registered in `build_default_registry`:
+
+| Tool | Type | Approval (default) | Purpose |
+| ---- | ---- | ------------------ | ------- |
+| `mcpmux_pin_this_session` | write | session: auto-allow (configurable via `gateway.session_overrides_require_approval`); workspace: required | Replace the caller's session tool list with the explicit qualified-name set. Optional `scope: "workspace"` persists as a custom FeatureSet + binding. |
+| `mcpmux_clear_session_pin` | write | auto-allow | Drop the caller's pin; next `tools/list` returns the full default-routed set. |
+
+Both fire `MCPNotifier::notify_session_lists_changed(session_id)` after a successful write — the calling LLM sees the new (or restored) tool list on its next `tools/list` poll.
+
+### Workspace-scope variant flow
+
+`mcpmux_pin_this_session({ tool_qualified_names: [...], scope: "workspace", name?: "..." })` is sugar for the two-call sequence the user would otherwise run:
+
+```text
+1. Validate every qualified_name exists in caller's Space
+2. Resolve caller's first reported workspace root (require session_roots; reject if missing)
+3. Open approval dialog with diff: { root, new FS name, full tool list }
+4. On allow:
+   a. Create custom FeatureSet with the matched ServerFeature ids (using add_feature_member + MemberMode::Include)
+   b. Create WorkspaceBinding(root, space_id, feature_set_id)
+   c. Emit FeatureSetMembersChanged and WorkspaceBindingChanged so the resolver picks it up
+5. Return { ok: true, feature_set_id, binding_id, scope: "workspace" }
+```
+
+The same path `create_feature_set` + `bind_current_workspace` exercises, run atomically as one approval. Failure between (4a) and (4b) leaves a custom FeatureSet without a binding — the existing Workspaces UI already handles unbound custom FSes (they appear in the list and can be bound or deleted), so no compensating cleanup is needed.
+
+### What McpMux stores
+
+| Item | Storage | Persistence |
+| ---- | ------- | ----------- |
+| `pinned_tools` set | `SessionOverrideRegistry` (in-memory `DashMap`) | Process-lifetime; dies with session reap |
+| Workspace-scope pin | new custom `FeatureSet` row + new `workspace_bindings` row | Persistent (uses existing schema) |
+| Audit trail | `DomainEvent::MetaToolInvoked` with `decision: "session_pin"` or `"allow_once"` | Persistent via existing audit log |
+
+No new tables, columns, or migrations.
+
+---
+
+## Architecture
+
+```
+                ┌──────────────────────────────────────────────┐
+                │  FeatureService::get_tools_for_grants        │
+                │                                              │
+                │  1–6. Server composition (existing)          │
+                │       effective_servers =                    │
+                │         (binding ∪ session_on) − session_off │
+                │       base_tools = tools for servers         │
+                │                                              │
+                │  7–8. NEW: tool-pin filter                   │
+                │       if pinned_tools[sid] non-empty:        │
+                │         tools = base_tools ∩ pinned_tools    │
+                │       else:                                  │
+                │         tools = base_tools                   │
+                └──────────────────────────────────────────────┘
+                                    ▲
+                                    │
+                    ┌───────────────┴───────────────┐
+                    │                               │
+                    ▼                               ▼
+        ┌──────────────────────┐    ┌──────────────────────────────┐
+        │ SessionOverride-     │    │ Meta tool writes mutate this │
+        │ Registry (extended)  │    │ registry directly.           │
+        │                      │    │                              │
+        │ enabled              │    │ mcpmux_pin_this_session      │
+        │ disabled             │    │ mcpmux_clear_session_pin     │
+        │ pinned_tools  ← NEW  │    │                              │
+        └──────────────────────┘    └──────────────────────────────┘
+```
+
+- `SessionOverrideRegistry` lives where it already does (`crates/mcpmux-gateway/src/services/session_overrides.rs`). One new field, three new methods (`pin`, `clear_pin`, `pinned_set`). Existing `remove(session_id)` extended to clear the new map.
+- `FeatureService::get_tools_for_grants` gains steps 7–8. The sibling `get_prompts_for_grants` / `get_resources_for_grants` are intentionally untouched — pin is tool-only.
+- The two new `MetaTool` impls land in `meta_tools/tools.rs` alongside the existing five write tools. Same `with_approval()` template, same `caller_space_id` / `validate_server_in_space` helpers — workspace variant calls into a new `workspace_pin::pin_workspace` helper module mirroring `workspace_server.rs`.
+
+---
+
+## Files to create
+
+| File | Purpose |
+| ---- | ------- |
+| [`crates/mcpmux-gateway/src/services/meta_tools/workspace_pin.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/workspace_pin.rs) | `pin_workspace(call, space_id, qualified_names, name) -> CallToolResult` — atomic create-FS + bind-workspace under one approval, mirroring `workspace_server.rs` |
+| [`tests/rust/tests/integration/tool_pin.rs`](../../tests/rust/tests/integration/tool_pin.rs) | E2E composition + meta-tool tests for pin / clear / workspace-scope |
+
+## Files to modify
+
+| File | Change |
+| ---- | ------ |
+| [`crates/mcpmux-gateway/src/services/session_overrides.rs`](../../crates/mcpmux-gateway/src/services/session_overrides.rs) | Add `pinned_tools: DashMap<String, HashSet<String>>` field. Methods: `pin(session_id, names)`, `clear_pin(session_id)`, `pinned_set(session_id) -> HashSet<String>`. Extend `remove()` to drop the entry. Extend `list_all()` to surface pinned counts for UI |
+| [`crates/mcpmux-gateway/src/pool/features/facade.rs`](../../crates/mcpmux-gateway/src/pool/features/facade.rs) | `get_tools_for_grants` applies the pin filter as the final step. `get_prompts_for_grants` / `get_resources_for_grants` unchanged |
+| [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | Implement `PinThisSessionTool` and `ClearSessionPinTool`. Session path mirrors `EnableServerTool` (optional approval). Workspace path delegates to `workspace_pin::pin_workspace`. Validation via existing `server_feature_repo::list_for_space` |
+| [`crates/mcpmux-gateway/src/services/meta_tools/mod.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/mod.rs) | `pub mod workspace_pin;` + `registry.register(Box::new(tools::PinThisSessionTool))` and `registry.register(Box::new(tools::ClearSessionPinTool))` in `build_default_registry`. Update module-level docstring example (currently references `mcpmux_pin_this_session` aspirationally — now real) |
+| [`crates/mcpmux-gateway/src/services/meta_tools/registry.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/registry.rs) | Document `"session_pin"` as a valid `decision` value in the audit-emission block; no other change |
+| [`apps/desktop/src/features/settings/SettingsPage.tsx`](../../apps/desktop/src/features/settings/SettingsPage.tsx) | Update meta-tools description from `"mcpmux_list_all_tools, mcpmux_pin_this_session, and 6 others"` to `"mcpmux_list_all_tools, mcpmux_pin_this_session, and 7 others"` (count goes from 7 → 9 registered tools) |
+| [`apps/desktop/src/features/workspaces/WorkspacesPage.tsx`](../../apps/desktop/src/features/workspaces/WorkspacesPage.tsx) | Extend "Active session overrides" panel with a "Pinned tools" row per session — shows count + expandable list, plus a "Clear pin" button calling a new Tauri command |
+| [`apps/desktop/src-tauri/src/commands/session_overrides.rs`](../../apps/desktop/src-tauri/src/commands/session_overrides.rs) | Extend `list_session_overrides` return shape with `pinned_tools: string[]`. Add `clear_session_pin(session_id)` Tauri command |
+| [`apps/desktop/src/lib/api/sessionOverrides.ts`](../../apps/desktop/src/lib/api/sessionOverrides.ts) | TS wrapper update: extend return type with `pinned_tools` field; add `clearSessionPin(sessionId)` |
+| [`README.md`](../../README.md) | Self-management meta tools section gains the pin tool — keep the section format the existing dynamic-toggle work established |
+
+---
+
+## Phasing
+
+### Phase 1 — Registry extension + composition wiring
+
+**Effort:** 1 evening
+
+- [ ] Add `pinned_tools: DashMap<String, HashSet<String>>` to `SessionOverrideRegistry`
+- [ ] Methods: `pin(session_id, names)` (replaces any existing pin), `clear_pin(session_id)`, `pinned_set(session_id) -> HashSet<String>`
+- [ ] Extend `remove(session_id)` to drop `pinned_tools` alongside `enabled` / `disabled`
+- [ ] Extend `list_all()` snapshot to include pinned counts so the UI panel can render without extra calls
+- [ ] `FeatureService::get_tools_for_grants(session_id)` applies the pin filter as the final step (steps 7–8 in the composition rule above)
+- [ ] Unit tests on the registry; composition test in `tests/rust/tests/integration/tool_pin.rs` exercising: no pin → full list, pin with subset → filtered, pin with non-matching names → empty, clear → restored
+
+**Outcome:** Direct registry mutation (`registry.pin("sess-1", ["github_create_issue"])`) causes the next `get_tools_for_grants("sess-1", grants)` to return exactly one tool, regardless of the binding's normal output. Meta tools and UI unchanged.
+
+### Phase 2 — `mcpmux_pin_this_session` (session scope only)
+
+**Effort:** 1 evening
+
+- [ ] `PinThisSessionTool` in `meta_tools/tools.rs` — args `{ tool_qualified_names: string[], scope?: "session" | "workspace", name?: string }`
+- [ ] Validate `tool_qualified_names` non-empty (else `InvalidArgument`)
+- [ ] Validate every qualified name resolves to an available `Tool` feature in the caller's resolved Space — collect the mismatches and surface them in the error message so the LLM can recover without guessing
+- [ ] Session path: optional approval via `gateway.session_overrides_require_approval` → `registry.pin(sid, names)` → set audit decision to `"session_pin"` → emit per-peer `tools/list_changed` via `MCPNotifier::notify_session_lists_changed`
+- [ ] Workspace path: return `InvalidArgument("workspace scope ships in Phase 4")` for now
+- [ ] Register in `build_default_registry`
+- [ ] Integration tests: pin reduces tool list, `list_changed` fires, invalid name returns descriptive error, approval-required setting routes through `ApprovalBroker`
+
+**Outcome:** LLM calls `mcpmux_pin_this_session({ tool_qualified_names: ["google-workspace-mcp-uvx_send_email", "google-workspace-mcp-uvx_list_calendar_events"] })` and the next `tools/list` returns exactly those two tools instead of 240. Cursor's UI updates without restarting the session.
+
+### Phase 3 — `mcpmux_clear_session_pin`
+
+**Effort:** 1 hour
+
+- [ ] `ClearSessionPinTool` — no args; operates on caller's `session_id`
+- [ ] Calls `registry.clear_pin(sid)`; idempotent (clearing an unpinned session is `ok: true` with `was_pinned: false`)
+- [ ] No approval gate even when `session_overrides_require_approval` is on — clear is always safe (broadens scope)
+- [ ] Audit decision `"session_pin_cleared"`
+- [ ] Emit per-peer `tools/list_changed`
+- [ ] Register in `build_default_registry`
+- [ ] Integration test: pin then clear restores full set
+
+**Outcome:** LLM can recover from a bad pin (e.g. pinned the wrong tool name and now has 0 visible tools) without restarting the session.
+
+### Phase 4 — Workspace-scope variant
+
+**Effort:** 1 day
+
+- [ ] `crates/mcpmux-gateway/src/services/meta_tools/workspace_pin.rs` — `pin_workspace(call, space_id, qualified_names, name)`
+- [ ] Resolve caller's first reported root via `session_roots.get(sid)` — reject with descriptive error if no roots reported
+- [ ] Auto-name FS as `"Pinned: {root_basename} {YYYY-MM-DD HH:MM}"` unless caller supplied `name`
+- [ ] Build approval diff payload: `{ workspace_root, feature_set_name, added_tools: [first ~10 qualified names], total_count }`
+- [ ] `with_approval` → on allow: create custom `FeatureSet` with matched `ServerFeature` ids (using `add_feature_member` + `MemberMode::Include`) → create `WorkspaceBinding` → emit `FeatureSetMembersChanged` and `WorkspaceBindingChanged`
+- [ ] Audit decision `"allow_once"` (matches workspace writes)
+- [ ] Return `{ ok: true, feature_set_id, binding_id, workspace_root, scope: "workspace", tool_count }`
+- [ ] Integration test: workspace-scope pin survives simulated session restart (new session for the same root resolves through the new binding), unbound caller rejected, name override respected
+
+**Outcome:** A single approval-gated tool call persists a custom tool subset for the caller's workspace cwd. Equivalent to `create_feature_set` + `bind_current_workspace` chained, with one approval and one audit row instead of two.
+
+### Phase 5 — UI surface + doc cleanup
+
+**Effort:** 0.5 day
+
+- [ ] Workspaces page session inspector gains "Pinned tools (N)" row per session; expanding shows the full qualified-name list
+- [ ] "Clear pin" button next to the existing per-session "Clear all overrides" button — calls `clearSessionPin` from `lib/api/sessionOverrides.ts`
+- [ ] Settings copy update in `SettingsPage.tsx`: bump "and 6 others" to "and 7 others" so the displayed count matches the registry
+- [ ] `meta_tools/mod.rs` module docstring no longer needs the aspirational `mcpmux_pin_this_session` reference qualifier — leave it as-is (the example is now accurate)
+- [ ] README self-management meta-tools section gains `mcpmux_pin_this_session` + `mcpmux_clear_session_pin` entries; keep the table format the existing dynamic-toggle work established
+- [ ] CHANGELOG: release-please handles it via conventional `feat(meta-tools): add tool-level session pin` commit — no manual edit
+
+**Outcome:** A user viewing the Workspaces page can see "session abc123 is pinned to 12 tools" with the tool names expandable and a one-click clear. Settings copy is honest about the registered tool count. README and module docs no longer reference a tool that doesn't exist.
+
+---
+
+## Pre-PR validation
+
+Do **not** open a PR until all automated checks pass and the production build is verified manually.
+
+| Step | Command | Purpose |
+| ---- | ------- | ------- |
+| Full validate | `pnpm validate` | fmt, clippy, check, eslint, typecheck |
+| Rust tests | `pnpm test:rust` | unit + integration (`tool_pin.rs`) |
+| TS tests | `pnpm test:ts` | vitest |
+| Production build | `pnpm build` | Tauri build on current platform |
+| Manual smoke | Run app, exercise pin + clear from a real MCP client (Cursor), verify Workspaces panel reflects state, verify approval dialog content for workspace scope | UX verification — the diff payload's tool-list rendering is easy to regress |
+
+Optional (slow / env-dependent): `pnpm test:e2e`, `pnpm test:e2e:web`.
+
+**PR target:** `main` (assumes `dynamic-mcp-toggle-meta-tools` is already merged).
+
+---
+
+## Out of scope
+
+| Item | Reason |
+| ---- | ------ |
+| Pin expiry / TTL | Sessions are already ephemeral. Explicit `mcpmux_clear_session_pin` covers the cleanup path. A TTL would be a different concept and isn't asked for. |
+| Wildcard / glob support in pin lists (`google-workspace-mcp-uvx_*`) | Explicit qualified names are unambiguous and the LLM can produce them by reading `mcpmux_list_all_tools` first. Wildcard support is additive — defer until a real use case shows up. |
+| Multi-pin layering (stack multiple pin sets, additive) | Single replacement set keeps semantics crisp. Layering would need ordering rules and conflict resolution — not justified by the current evidence. |
+| Pin export to a portable template (across workspaces or users) | Workspace-scope variant already creates a persisted custom FeatureSet; sharing those across workspaces is a separate "FeatureSet templates" feature not yet scoped. |
+| LLM-driven pin recommendations (host suggests "based on this prompt, here are the 10 tools you need") | That's a host-side concern (Cursor / Claude Code), not a gateway concern. Gateway exposes the mechanism; host decides when to use it. |
+| Pin applied to prompts / resources | Pin is tool-budget-shaped. Prompts/resources are not the bottleneck. Keep the surface narrow. |
+| Settings UI toggle for `mcpmux_pin_this_session` independent of other session overrides | Reuses the existing `gateway.session_overrides_require_approval` setting deliberately — adding per-tool toggles balloons the settings surface for no clear benefit. Revisit if user feedback diverges. |
+
+---
+
+## Key files referenced
+
+| File | Why |
+| ---- | --- |
+| [`crates/mcpmux-gateway/src/services/session_overrides.rs`](../../crates/mcpmux-gateway/src/services/session_overrides.rs) | Registry being extended. Existing `enabled` / `disabled` field shape and `remove()` GC contract are the template for the new `pinned_tools` field |
+| [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | Where the two new `MetaTool` impls land. `EnableServerTool` / `DisableServerTool` are the closest templates (session-scope short-circuit + workspace delegation pattern) |
+| [`crates/mcpmux-gateway/src/services/meta_tools/workspace_server.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/workspace_server.rs) | Pattern reference for `workspace_pin.rs` — shows how workspace-scope writes resolve roots, build approval payloads, and create/modify bindings atomically |
+| [`crates/mcpmux-gateway/src/services/meta_tools/mod.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/mod.rs) | `build_default_registry` factory — registration site for the new tools. Module-level docstring already mentions `mcpmux_pin_this_session` as the canonical example; this PR makes that mention accurate |
+| [`crates/mcpmux-gateway/src/services/meta_tools/registry.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/registry.rs) | `MetaToolContext` + `MetaToolRegistry::call` dispatch. Audit-decision string list extended with `"session_pin"` / `"session_pin_cleared"` |
+| [`crates/mcpmux-gateway/src/pool/features/facade.rs`](../../crates/mcpmux-gateway/src/pool/features/facade.rs) | `FeatureService::get_tools_for_grants` is the materialization chokepoint where the pin filter applies. Existing server composition logic stays untouched — the filter is one new conditional block at the bottom |
+| [`crates/mcpmux-gateway/src/consumers/mcp_notifier.rs`](../../crates/mcpmux-gateway/src/consumers/mcp_notifier.rs) | Session-reap pass already calls `SessionOverrideRegistry::remove` per reaped session — automatically picks up the new `pinned_tools` field, no notifier change needed |
+| [`docs/planning/dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) | Direct predecessor — defines the SessionOverrideRegistry pattern, approval flow conventions, and Out-of-Scope row #1 this doc supersedes |
+| [`docs/planning/server-account-clones.md`](./server-account-clones.md) | Origin of the 240-tool context-bloat evidence that justifies revisiting tool-level granularity |
+
+---
+
+## Related work
+
+- [`docs/planning/dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) — defines the meta-tools infrastructure and the session-override registry pattern. Supersedes its Out-of-Scope row #1.
+- [`docs/planning/server-account-clones.md`](./server-account-clones.md) — clone feature that created the 240-tool context-bloat evidence. This doc is a natural follow-on for users who hit that ceiling.
+- [MikkoParkkola/mcp-gateway](https://github.com/MikkoParkkola/mcp-gateway) and [abdullah1854/MCPGateway](https://github.com/abdullah1854/MCPGateway) — alternative architectural answer (search-then-invoke meta gateway, ~95% context reduction). Considered and rejected for this PR: their model hides all backend tools by default and requires the LLM to discover via `gateway_search_tools` on every call. The McpMux approach keeps the LLM's mental model of named tools intact and lets the user (via the LLM) opt in to budget reduction per session. Worth revisiting as a separate planning doc if the pin-based approach proves insufficient.
+- [MCP spec — Tools `list_changed` notification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#list-changed-notification) — protocol mechanism that makes the post-pin tool-list refresh observable mid-conversation. Already wired by [`dynamic-mcp-toggle-meta-tools`](./dynamic-mcp-toggle-meta-tools.md).
+- [modelcontextprotocol/servers#2173](https://github.com/modelcontextprotocol/servers/issues/2173) — upstream tracking issue for server-side multi-tenancy. Pin is a gateway-side workaround for the same underlying problem (tool surface scaling poorly with multi-account use).
+
+---
+
+## Reconciliation
+
+This doc is the source of truth for what gets built. When implementation completes, update the **Status** field at the top and reconcile any deviations (extra files, dropped phases, scope changes) per [`update-planning-md`](~/.cursor/commands/update-planning-md.md).

From 9e4c3cd88ffd27a537173b281dc2519b65c7abf2 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 11:50:37 -0600
Subject: [PATCH 30/48] docs(planning): web admin mode for remote UI access

Define phased plan for serving the admin UI over HTTP behind CF Access,
separate from the MCP gateway tunnel.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 docs/planning/web-admin-remote-access.md | 317 +++++++++++++++++++++++
 1 file changed, 317 insertions(+)
 create mode 100644 docs/planning/web-admin-remote-access.md

diff --git a/docs/planning/web-admin-remote-access.md b/docs/planning/web-admin-remote-access.md
new file mode 100644
index 00000000..c2fd2ce8
--- /dev/null
+++ b/docs/planning/web-admin-remote-access.md
@@ -0,0 +1,317 @@
+# Web Admin Mode (Remote UI via HTTP)
+
+**Last Updated:** May 25, 2026
+**Status:** Planning
+**Branch:** TBD — branch off `main` (or current fork head)
+**Base branch:** `main`
+**Issue:** TBD — file after planning review
+**Depends on:** None for core admin HTTP layer; benefits from merged fork features (session meta-tools, account clones) but does not require them
+**Unblocks:** [`jsg-tech-check` homelab wiring Step 6](../../../jsg-tech-check/docs/setup/home-lab-wiring-plan.md) — remote McpMux admin UI from Weathertop / Rohan at `https://mux.joe-hassio.com`
+
+---
+
+## Problem
+
+The McpMux admin UI (Spaces, servers, credentials, workspace bindings, FeatureSets, OAuth consent) is a Tauri desktop app. The React frontend talks to Rust exclusively via Tauri `invoke()` — ~80 calls across 15 API modules, backed by ~110 Tauri commands in 19 command modules. There is no HTTP admin surface.
+
+The homelab wiring plan already exposes two public endpoints via Cloudflare Tunnel on Gondor:
+
+| Hostname | Target | What it serves |
+| -------- | ------ | -------------- |
+| `mcp.joe-hassio.com` | `localhost:45818` | MCP gateway (`/mcp`) for AI clients |
+| `code.joe-hassio.com` | `localhost:3001` | ClaudeCodeUI |
+
+Neither exposes the admin UI. Tunneling Vite dev (`:1420`) serves a React shell with no backend — every action fails because nothing answers `invoke()`. Tunneling the MCP gateway (`:45818`) serves the protocol endpoint, not admin pages.
+
+The user-facing ask:
+
+> I want to be able to reach the UI — that's the main point.
+
+Screen sharing / VNC behind CF Access works today but is not a web UI. This doc defines a **web admin mode**: an optional HTTP server that serves the built React SPA and exposes a REST API mirroring Tauri commands, gated by Cloudflare Access at the edge.
+
+---
+
+## Decisions
+
+| # | Decision | Choice | Rationale |
+| - | -------- | ------ | --------- |
+| 1 | Deployment model | **Single-user homelab** — one McpMux instance on Gondor, one operator | Avoids multi-tenant auth, cloud KMS, and per-user DB isolation. The Rust process still runs locally with OS keychain access. |
+| 2 | Auth | **Cloudflare Access at the tunnel edge** — app trusts `CF-Access-Jwt-Assertion` when `gateway.admin_trust_cf_access` is enabled | No login UI to build. Same pattern as `b.joe-hassio.com` (Beeper). Reject requests without a valid JWT when admin mode is enabled. |
+| 3 | Admin server placement | **Separate Axum router on configurable port** (default `45819`), not mixed into MCP gateway routes | Keeps MCP protocol surface unchanged. Admin and MCP can be tunneled independently (`mux.joe-hassio.com` vs `mcp.joe-hassio.com`). Easier to disable admin without stopping the gateway. |
+| 4 | Static UI | **Serve `frontendDist` from the Tauri build** at `/` with SPA fallback | Reuses the existing React app. No separate web bundle. |
+| 5 | API shape | **REST JSON at `/api/v1/*`** mirroring Tauri command names (kebab → snake mapping) | Predictable mapping: `get_gateway_status` → `GET /api/v1/gateway/status`. One handler module per Tauri command group. |
+| 6 | Frontend transport | **Transport abstraction in `lib/api/`** — `invoke()` in Tauri, `fetch()` in web mode | Detect via `window.__TAURI__` or build-time `import.meta.env.VITE_ADMIN_WEB`. Same function signatures, different backend. |
+| 7 | OAuth consent | **Re-enable guarded HTTP consent endpoint** for web admin only — `POST /api/v1/oauth/consent/approve` behind CF Access + CSRF token | Production desktop keeps Tauri-IPC-only consent (existing security model). Web mode needs an HTTP path because there is no Tauri shell on Weathertop. |
+| 8 | Bind address | **Default `127.0.0.1:45819`** — same loopback-first posture as MCP gateway | CF tunnel reaches localhost; no need to bind `0.0.0.0`. `AGENTS.md` loopback rule preserved. |
+| 9 | Event streaming | **SSE at `/api/v1/events`** bridging existing `EventBus` | Replaces Tauri event listeners (`useDomainEvents`) in web mode. Desktop keeps Tauri events. |
+| 10 | Scope phasing | **Read-only views first, then writes, then OAuth** | Each phase is independently testable behind CF Access. Avoids a big-bang API dump. |
+
+---
+
+## The Model
+
+### What web admin mode is
+
+An optional HTTP server started alongside (or instead of) the Tauri window when `gateway.admin_enabled` is true:
+
+```text
+AdminServer (Axum, :45819)
+├── GET  /*                    → SPA static files (frontendDist)
+├── GET  /api/v1/health       → { status: "ok", gateway_running: bool }
+├── GET  /api/v1/events       → SSE stream (EventBus bridge)
+├── /api/v1/gateway/*         → gateway commands
+├── /api/v1/spaces/*          → space commands
+├── /api/v1/servers/*         → server manager + install + clone
+├── /api/v1/workspaces/*      → workspace bindings + session overrides
+├── /api/v1/feature-sets/*    → feature sets + members
+├── /api/v1/clients/*         → inbound MCP clients
+├── /api/v1/oauth/*           → consent approve/reject (web only)
+└── /api/v1/settings/*        → app settings
+```
+
+All handlers delegate to the same `ApplicationServices` / command-layer logic Tauri uses today — no duplicated business logic.
+
+### What web admin mode is NOT
+
+- Not a hosted multi-tenant SaaS ("McpMux Cloud")
+- Not a replacement for the Tauri desktop app on Gondor (desktop remains primary for local use)
+- Not exposing the MCP gateway without separate hardening (that route stays on `:45818` with its own OAuth JWT model)
+- Not moving secrets off OS keychain — encryption keys stay local
+
+### Homelab tunnel layout (target)
+
+```yaml
+# gondor cloudflared config (addition to home-lab-wiring-plan.md Step 5)
+ingress:
+  - hostname: mux.joe-hassio.com
+    service: http://localhost:45819    # NEW — admin UI
+  - hostname: mcp.joe-hassio.com
+    service: http://localhost:45818    # existing — MCP clients
+  - hostname: code.joe-hassio.com
+    service: http://localhost:3001     # existing — ClaudeCodeUI
+  - service: http_status:404
+```
+
+CF Access policy on `mux.joe-hassio.com`: allow `jsangio1@gmail.com` (or equivalent Zero Trust rule).
+
+---
+
+## Architecture
+
+```
+Weathertop / Rohan browser
+        │
+        │ HTTPS + CF Access (Google login)
+        ▼
+  mux.joe-hassio.com ──── cloudflared tunnel ────► localhost:45819
+                                                          │
+                              ┌───────────────────────────┤
+                              │                           │
+                              ▼                           ▼
+                    ┌──────────────────┐        ┌──────────────────┐
+                    │  Static SPA      │        │  /api/v1/* REST  │
+                    │  (frontendDist)  │        │  + SSE /events   │
+                    └──────────────────┘        └────────┬─────────┘
+                                                         │
+                                                         ▼
+                                              ┌──────────────────────┐
+                                              │ ApplicationServices  │
+                                              │ (same as Tauri cmds) │
+                                              └──────────┬───────────┘
+                                                         │
+                    ┌────────────────────────────────────┼────────────────────┐
+                    ▼                                    ▼                    ▼
+              SQLite +                           OS Keychain              Gateway :45818
+              AES-256-GCM                          JWT secret              (unchanged)
+```
+
+**Middleware stack (admin router):**
+
+1. `CF-Access-Jwt-Assertion` validation (when enabled)
+2. CSRF token check on mutating routes (web OAuth consent)
+3. Request logging (sanitized — no secrets)
+4. CORS: deny by default; allow same-origin only (SPA served from same host)
+
+**Frontend transport switch:**
+
+```typescript
+// lib/api/transport.ts (new)
+export async function apiCall<T>(command: string, args?: Record<string, unknown>): Promise<T> {
+  if (isTauri()) {
+    return invoke(command, args);
+  }
+  return fetchApi<T>(command, args);
+}
+```
+
+Existing `lib/api/*.ts` modules swap `invoke(...)` → `apiCall(...)` with no signature changes.
+
+---
+
+## Files to create
+
+| File | Purpose |
+| ---- | ------- |
+| `crates/mcpmux-gateway/src/admin/mod.rs` | Admin router module entry |
+| `crates/mcpmux-gateway/src/admin/server.rs` | `AdminServer` — bind, static file serving, route mounting |
+| `crates/mcpmux-gateway/src/admin/middleware/cf_access.rs` | Validate `CF-Access-Jwt-Assertion` against CF team domain certs |
+| `crates/mcpmux-gateway/src/admin/middleware/csrf.rs` | CSRF token generation + validation for mutating routes |
+| `crates/mcpmux-gateway/src/admin/handlers/mod.rs` | Handler module tree |
+| `crates/mcpmux-gateway/src/admin/handlers/gateway.rs` | Gateway status/start/stop REST handlers |
+| `crates/mcpmux-gateway/src/admin/handlers/spaces.rs` | Space CRUD handlers |
+| `crates/mcpmux-gateway/src/admin/handlers/servers.rs` | Server manager + install + clone handlers |
+| `crates/mcpmux-gateway/src/admin/handlers/workspaces.rs` | Workspace binding + session override handlers |
+| `crates/mcpmux-gateway/src/admin/handlers/feature_sets.rs` | FeatureSet + member handlers |
+| `crates/mcpmux-gateway/src/admin/handlers/clients.rs` | Inbound MCP client handlers |
+| `crates/mcpmux-gateway/src/admin/handlers/oauth.rs` | Web consent approve/reject handlers |
+| `crates/mcpmux-gateway/src/admin/handlers/settings.rs` | App settings handlers |
+| `crates/mcpmux-gateway/src/admin/handlers/events.rs` | SSE EventBus bridge |
+| `crates/mcpmux-gateway/src/admin/command_bridge.rs` | Shared helper: call Tauri command logic without Tauri runtime |
+| `apps/desktop/src/lib/api/transport.ts` | Tauri vs fetch transport abstraction |
+| `apps/desktop/src/lib/api/fetch-api.ts` | REST client mapping command names → HTTP paths |
+| `apps/desktop/src/hooks/useDomainEventsWeb.ts` | SSE-based event listener for web mode |
+| `tests/rust/tests/integration/admin_api.rs` | Admin API integration tests (health, auth rejection, read endpoints) |
+| `docs/planning/web-admin-remote-access.md` | This doc |
+
+## Files to modify
+
+| File | Change |
+| ---- | ------ |
+| [`crates/mcpmux-gateway/src/lib.rs`](../../crates/mcpmux-gateway/src/lib.rs) | `pub mod admin;` |
+| [`crates/mcpmux-gateway/src/server/mod.rs`](../../crates/mcpmux-gateway/src/server/mod.rs) | `GatewayConfig` gains `admin_enabled`, `admin_port`, `admin_trust_cf_access`, `admin_cf_team_domain` |
+| [`apps/desktop/src-tauri/src/lib.rs`](../../apps/desktop/src-tauri/src/lib.rs) | Start `AdminServer` when setting enabled; share `ApplicationServices` Arc |
+| [`apps/desktop/src-tauri/src/commands/gateway.rs`](../../apps/desktop/src-tauri/src/commands/gateway.rs) | Extract shared gateway logic callable from admin handlers |
+| [`apps/desktop/src/lib/api/*.ts`](../../apps/desktop/src/lib/api/) | Replace direct `invoke()` with `apiCall()` from transport layer |
+| [`apps/desktop/src/hooks/useDomainEvents.ts`](../../apps/desktop/src/hooks/useDomainEvents.ts) | Delegate to SSE hook in web mode |
+| [`apps/desktop/src/features/oauth/OAuthConsentModal.tsx`](../../apps/desktop/src/features/oauth/OAuthConsentModal.tsx) | Web mode: POST to `/api/v1/oauth/consent/approve` instead of Tauri command |
+| [`apps/desktop/src/features/settings/SettingsPage.tsx`](../../apps/desktop/src/features/settings/SettingsPage.tsx) | Admin mode toggle + port setting |
+| [`apps/desktop/vite.config.ts`](../../apps/desktop/vite.config.ts) | `VITE_ADMIN_WEB` build flag for web-only builds |
+| [`apps/desktop/package.json`](../../apps/desktop/package.json) | `build:web:admin` script — production SPA build for admin serving |
+| [`tests/e2e/playwright.config.ts`](../../tests/e2e/playwright.config.ts) | Optional admin web E2E project against `:45819` with mocked CF JWT |
+| [`AGENTS.md`](../../AGENTS.md) | Document admin server loopback binding + CF Access requirement |
+
+---
+
+## Phasing
+
+### Phase 1 — Admin server skeleton + static SPA + CF Access gate
+
+**Effort:** ~2 days
+
+- [ ] `AdminServer` Axum router on `127.0.0.1:45819` (configurable)
+- [ ] Serve `frontendDist` with SPA fallback (`index.html` for unknown routes)
+- [ ] `GET /api/v1/health` — returns gateway running status
+- [ ] CF Access middleware: validate `CF-Access-Jwt-Assertion` when `admin_trust_cf_access` is true; 401 without it
+- [ ] Settings: `gateway.admin_enabled` (default `false`), `gateway.admin_port` (default `45819`)
+- [ ] Start admin server from Tauri app when setting enabled (alongside gateway)
+- [ ] Unit test: health endpoint returns 200; unauthenticated request returns 401 when CF Access enabled
+
+**Outcome:** With admin mode enabled and a valid CF Access JWT, `https://mux.joe-hassio.com` (via tunnel) loads the McpMux UI shell. API calls still fail (no handlers yet), but static assets render and auth gate works.
+
+### Phase 2 — Transport abstraction + read-only API
+
+**Effort:** ~3 days
+
+- [ ] `transport.ts` + `fetch-api.ts` — command name → HTTP path mapping
+- [ ] Refactor all `lib/api/*.ts` modules to use `apiCall()`
+- [ ] `command_bridge.rs` — extract shared logic from Tauri commands into functions callable from both IPC and HTTP
+- [ ] Read-only handlers: gateway status, list spaces, list installed servers, list workspace bindings, list feature sets, list clients, list session overrides, get settings
+- [ ] `GET /api/v1/events` — SSE bridge from `EventBus`
+- [ ] `useDomainEventsWeb.ts` — SSE listener; `useDomainEvents` switches on environment
+- [ ] Integration tests for each read endpoint
+
+**Outcome:** From Weathertop, authenticated user can browse Spaces, My Servers, Workspaces, FeatureSets, Clients, and Settings in read-only mode. Domain events (server connected, gateway started) stream via SSE. No writes yet.
+
+### Phase 3 — Write API (config mutations)
+
+**Effort:** ~4 days
+
+- [ ] Write handlers: install/uninstall server, enable/disable, configure inputs, clone server, CRUD spaces, CRUD workspace bindings, CRUD feature sets + members, gateway start/stop, export config, clear session overrides, update settings
+- [ ] CSRF middleware on all `POST`/`PUT`/`DELETE` routes
+- [ ] Error mapping: domain errors → HTTP status codes with JSON body
+- [ ] Integration tests: install + configure + enable round-trip via HTTP
+- [ ] Playwright admin web E2E: smoke test install flow against `:45819`
+
+**Outcome:** Full admin CRUD works from the browser. User can install servers, edit credentials, manage bindings and FeatureSets, start/stop gateway — all remote. OAuth consent still requires Phase 4.
+
+### Phase 4 — Web OAuth consent
+
+**Effort:** ~2 days
+
+- [ ] `POST /api/v1/oauth/consent/approve` and `/reject` — guarded HTTP endpoints (web admin only; desktop keeps Tauri IPC)
+- [ ] CSRF + consent token validation (reuse existing cryptographic consent token from gateway)
+- [ ] `OAuthConsentModal.tsx` — web path posts to HTTP endpoint; desktop path unchanged
+- [ ] Deep link bridge: `mcpmux://` URLs on Gondor still work for desktop; web mode polls consent pending state via SSE
+- [ ] Integration test: OAuth authorize → consent approve via HTTP → token issued
+
+**Outcome:** Remote user can complete OAuth flows (Notion, GitHub, Google Workspace, etc.) from the browser without needing the Tauri shell on Gondor.
+
+### Phase 5 — Homelab integration + docs
+
+**Effort:** ~1 day
+
+- [ ] Update [`jsg-tech-check/docs/setup/home-lab-wiring-plan.md`](../../../jsg-tech-check/docs/setup/home-lab-wiring-plan.md) Step 5 with `mux.joe-hassio.com` ingress rule
+- [ ] Document CF Access policy setup for `mux.joe-hassio.com`
+- [ ] Add admin mode section to [`docs/guide/gateway.mdx`](../../docs/guide/gateway.mdx)
+- [ ] `pnpm build:web:admin` + verify production SPA served correctly from admin server
+- [ ] End-to-end smoke from Weathertop: open `https://mux.joe-hassio.com`, manage a server, approve OAuth
+
+**Outcome:** Homelab wiring plan reflects the third public hostname. Operator can manage McpMux from phone/laptop browser with CF Access auth.
+
+---
+
+## Pre-PR validation
+
+| Step | Command | Purpose |
+| ---- | ------- | ------- |
+| Full validate | `pnpm validate` | fmt, clippy, check, eslint, typecheck |
+| Rust tests | `pnpm test:rust` | unit + integration (`admin_api.rs`) |
+| TS tests | `pnpm test:ts` | vitest (transport layer) |
+| Admin web E2E | `pnpm test:e2e:web:admin` (new) | Playwright against `:45819` |
+| Manual smoke | Enable admin mode, tunnel `mux.joe-hassio.com`, browse from phone | UX + CF Access verification |
+
+---
+
+## Out of scope
+
+| Item | Reason |
+| ---- | ------ |
+| Multi-tenant / per-user accounts | Single-user homelab. Adding user management is a different product. |
+| Cloud KMS / secrets off OS keychain | Admin server runs on Gondor; keychain access is preserved. No remote secret vault needed. |
+| Binding admin server to `0.0.0.0` | Loopback + CF tunnel is the access path. Direct internet bind violates `AGENTS.md` posture. |
+| Replacing Tauri desktop app | Desktop remains primary on Gondor. Web admin is for remote access only. |
+| Mobile-optimized responsive UI | React app works in mobile browser but no dedicated mobile layout pass. Acceptable for v1 homelab use. |
+| Public MCP gateway hardening (`mcp.joe-hassio.com`) | Separate concern — OAuth JWT auth exists but unauthenticated admin routes on `:45818` need CF Access too. Track as follow-up, not blocked on this doc. |
+| WebSocket transport (instead of SSE) | SSE is sufficient for EventBus fan-out. WebSocket adds complexity with no v1 benefit. |
+| Headless-only mode (no Tauri window) | v1 starts admin server from Tauri app. Headless/systemd mode is a follow-up for Rivendell-style deployment. |
+
+---
+
+## Key files referenced
+
+| File | Why |
+| ---- | --- |
+| [`apps/desktop/src/lib/api/gateway.ts`](../../apps/desktop/src/lib/api/gateway.ts) | Largest API module (~20 invokes) — template for transport refactor |
+| [`apps/desktop/src-tauri/src/commands/mod.rs`](../../apps/desktop/src-tauri/src/commands/mod.rs) | Command module registry — each module gets a corresponding admin handler |
+| [`crates/mcpmux-gateway/src/server/mod.rs`](../../crates/mcpmux-gateway/src/server/mod.rs) | Existing Axum gateway — pattern reference for admin router |
+| [`crates/mcpmux-gateway/src/server/mod.rs`](../../crates/mcpmux-gateway/src/server/mod.rs) (lines 340–365) | OAuth consent removed from HTTP for security — web admin re-adds guarded version |
+| [`apps/desktop/src/hooks/useDomainEvents.ts`](../../apps/desktop/src/hooks/useDomainEvents.ts) | Tauri event listener — needs SSE equivalent for web mode |
+| [`jsg-tech-check/docs/setup/home-lab-wiring-plan.md`](../../../jsg-tech-check/docs/setup/home-lab-wiring-plan.md) | CF tunnel config — gets `mux.joe-hassio.com` ingress in Phase 5 |
+
+---
+
+## Related documentation
+
+- [`jsg-tech-check/docs/setup/home-lab-wiring-plan.md`](../../../jsg-tech-check/docs/setup/home-lab-wiring-plan.md) — Step 5 (CF tunnel), Step 6 (McpMux on Gondor), cross-device MCP access
+- [`jsg-tech-check/docs/setup/mcpmux-server-migration.md`](../../../jsg-tech-check/docs/setup/mcpmux-server-migration.md) — server/bundle/binding migration tracker (orthogonal to web admin)
+- [`docs/guide/security.mdx`](../../docs/guide/security.mdx) — credential encryption model (unchanged by web admin)
+- [`docs/planning/dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) — session override UI that web admin must expose via HTTP
+- [`docs/planning/server-account-clones.md`](./server-account-clones.md) — clone wizard that web admin must expose via HTTP
+
+---
+
+## Reconciliation
+
+This doc is the source of truth for web admin mode. When implementation starts, update **Status** and **Branch** at the top. Phase 5 homelab doc updates live in `jsg-tech-check` — track cross-repo separately.
+
+**Decision record (May 25, 2026):** Web admin mode on fork selected over screen sharing (immediate but not web UI), tunneling `:1420` (broken), and full "McpMux Cloud" multi-tenant SaaS (months of work). CF Access at edge replaces building login UI. Separate admin port (`45819`) keeps MCP gateway surface unchanged.

From 2052bcca51c62fd3c5030341e0fab50064261c8b Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 11:53:24 -0600
Subject: [PATCH 31/48] feat(servers): replace enable/disable buttons with
 labeled toggle

Use a leftmost Enabled switch on server rows for clearer state and fewer action buttons.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 .../features/servers/ServerEnabledToggle.tsx  | 34 ++++++++++++++
 .../src/features/servers/ServersPage.tsx      | 46 +++++++++----------
 2 files changed, 55 insertions(+), 25 deletions(-)
 create mode 100644 apps/desktop/src/features/servers/ServerEnabledToggle.tsx

diff --git a/apps/desktop/src/features/servers/ServerEnabledToggle.tsx b/apps/desktop/src/features/servers/ServerEnabledToggle.tsx
new file mode 100644
index 00000000..5e0807f4
--- /dev/null
+++ b/apps/desktop/src/features/servers/ServerEnabledToggle.tsx
@@ -0,0 +1,34 @@
+import { Switch } from '@mcpmux/ui';
+
+interface ServerEnabledToggleProps {
+  serverId: string;
+  enabled: boolean;
+  isLoading: boolean;
+  disabled?: boolean;
+  onToggle: (enabled: boolean) => void;
+}
+
+/**
+ * Labeled enable/disable control for an installed server row.
+ */
+export function ServerEnabledToggle({
+  serverId,
+  enabled,
+  isLoading,
+  disabled = false,
+  onToggle,
+}: ServerEnabledToggleProps) {
+  const label = isLoading ? (enabled ? 'Disabling…' : 'Enabling…') : enabled ? 'Enabled' : 'Disabled';
+
+  return (
+    <div className="flex items-center gap-2">
+      <span className="text-sm text-[rgb(var(--muted))] whitespace-nowrap">{label}</span>
+      <Switch
+        checked={enabled}
+        onCheckedChange={onToggle}
+        disabled={disabled || isLoading}
+        data-testid={enabled ? `disable-server-${serverId}` : `enable-server-${serverId}`}
+      />
+    </div>
+  );
+}
diff --git a/apps/desktop/src/features/servers/ServersPage.tsx b/apps/desktop/src/features/servers/ServersPage.tsx
index a829d61c..c49880f9 100644
--- a/apps/desktop/src/features/servers/ServersPage.tsx
+++ b/apps/desktop/src/features/servers/ServersPage.tsx
@@ -25,6 +25,7 @@ import {
 } from 'lucide-react';
 import { Button, SearchField } from '@mcpmux/ui';
 import { ServerActionMenu } from './ServerActionMenu';
+import { ServerEnabledToggle } from './ServerEnabledToggle';
 import { CloneAccountModal } from './CloneAccountModal';
 import { AddServerMenu } from './AddServerMenu';
 import { ServersFiltersPopover } from './ServersFiltersPopover';
@@ -1451,16 +1452,26 @@ export function ServersPage() {
                       className="flex items-center gap-2 flex-shrink-0"
                       onClick={(event) => event.stopPropagation()}
                     >
-                      {/* Primary action button */}
-                      {serverAction === 'enable' && (
-                        <button
-                          onClick={() => handleEnableClick(server)}
-                          disabled={enableLoading}
-                          className="px-4 py-2 text-sm font-medium rounded-lg bg-[rgb(var(--success))] text-white hover:bg-[rgb(var(--success))]/80 shadow-sm transition-colors disabled:opacity-50"
-                          data-testid={`enable-server-${server.id}`}
-                        >
-                          {enableLoading ? 'Enabling...' : 'Enable'}
-                        </button>
+                      {(serverAction === 'enable' ||
+                        (server.enabled &&
+                          (serverAction === 'running' ||
+                            serverAction === 'connected_auto' ||
+                            serverAction === 'error'))) && (
+                        <ServerEnabledToggle
+                          serverId={server.id}
+                          enabled={server.enabled}
+                          isLoading={enableLoading || disableLoading}
+                          disabled={
+                            serverAction === 'connecting' || serverAction === 'authenticating'
+                          }
+                          onToggle={(checked) => {
+                            if (checked) {
+                              handleEnableClick(server);
+                            } else {
+                              handleDisableClick(server);
+                            }
+                          }}
+                        />
                       )}
 
                       {serverAction === 'configure' && (
@@ -1536,21 +1547,6 @@ export function ServersPage() {
                         </button>
                       )}
 
-                      {/* Disable button - enabled servers that are connected, idle, or stuck in error */}
-                      {server.enabled &&
-                        (serverAction === 'running' ||
-                          serverAction === 'connected_auto' ||
-                          serverAction === 'error') && (
-                        <button
-                          onClick={() => handleDisableClick(server)}
-                          disabled={disableLoading}
-                          className="px-4 py-2 text-sm rounded-lg border border-[rgb(var(--border))] text-[rgb(var(--muted))] hover:bg-[rgb(var(--surface-hover))] transition-colors disabled:opacity-50"
-                          data-testid={`disable-server-${server.id}`}
-                        >
-                          {disableLoading ? '...' : 'Disable'}
-                        </button>
-                      )}
-
                       {/* Overflow menu with secondary actions */}
                       <ServerActionMenu
                         serverId={server.id}

From f767e7923bd86de5bc1c99ff8ccbd47b768ecc8d Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 12:08:38 -0600
Subject: [PATCH 32/48] docs(planning): add meta-gateway invoke model for agent
 tool discovery
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Define search → schema → invoke as the primary agent path with a hard cut
away from exposing backend tools in tools/list. Defer session pin in favor
of this approach.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 docs/planning/meta-gateway-invoke.md    | 312 ++++++++++++++++++++++++
 docs/planning/tool-level-session-pin.md |   2 +-
 2 files changed, 313 insertions(+), 1 deletion(-)
 create mode 100644 docs/planning/meta-gateway-invoke.md

diff --git a/docs/planning/meta-gateway-invoke.md b/docs/planning/meta-gateway-invoke.md
new file mode 100644
index 00000000..c391939f
--- /dev/null
+++ b/docs/planning/meta-gateway-invoke.md
@@ -0,0 +1,312 @@
+# Meta-Gateway Invoke (Search → Schema → Invoke)
+
+**Last Updated:** May 25, 2026
+**Status:** Planning
+**Branch:** TBD — branch off `main`
+**Base branch:** `main`
+**Issue:** TBD — file after planning review
+**Depends on:** [`dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) (session overrides + meta-tool registry); benefits from workspace bindings / FeatureSets from PR #151
+**Supersedes:** Token-budget approach in [`tool-level-session-pin.md`](./tool-level-session-pin.md) — pin filtered a bloated `tools/list`; this doc replaces that model with a fixed meta surface + invoke path. Session pin may return as an invoke ACL in Phase F (very optional, last).
+**Unblocks:** Agent-usable McpMux sessions at scale (240+ backend tools installed, ~12 tools in client context); homelab + multi-clone installs without context-window collapse
+
+---
+
+## Problem
+
+Routing every AI client through one McpMux gateway endpoint solved config duplication and credential sprawl. It introduced a different bottleneck: **tool definition bloat in the client context window**.
+
+Concrete symptoms from a May 2026 Cursor session against a real install:
+
+| Symptom | Number |
+| ------- | ------ |
+| Installed servers in Space | 34 |
+| Tools in `mcpmux_list_all_tools` dump | 1,581 (~855 KB JSON) |
+| Tools exposed in Cursor session (GWorkspace × 2 clones) | 240 |
+| GitHub tools available but usable only after `mcpmux_enable_server` | 41 |
+| GitHub tool schemas in Cursor MCP descriptor folder | 0 |
+| Approximate tokens consumed by 240 tool definitions | ~30–50k |
+
+Session meta-tools ([`dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md)) let the LLM enable/disable servers mid-conversation, but **`tools/list` still advertises every backend tool** once a server is in the effective set. The LLM must guess parameter names (`issueNumber` vs `issue_number`) because schemas are not exposed through discovery APIs — only through client-side descriptor files that lag behind dynamic enablement.
+
+Competing gateways ([MikkoParkkola/mcp-gateway](https://github.com/MikkoParkkola/mcp-gateway), [abdullah1854/MCPGateway](https://github.com/abdullah1854/MCPGateway)) solve this with a **fixed meta surface** (~14–19 tools) and **progressive disclosure**: search → load schema → invoke. McpMux already has half the plumbing (`mcpmux_list_servers`, `mcpmux_enable_server`, `mcpmux_list_all_tools`) but lacks search-with-schema and a single invoke entry point.
+
+The user-facing ask (May 2026 session):
+
+> I'd rather 1–2 more calls that actually work well than hundreds of tool defs I can't call correctly.
+
+This doc defines that model for McpMux while preserving its product strengths: OS keychain credentials, Spaces, FeatureSets, per-client auth, and the server registry.
+
+---
+
+## Decisions
+
+| # | Decision | Choice | Rationale |
+| - | -------- | ------ | --------- |
+| 1 | Client `tools/list` shape | **Meta tools + optional surfaced backend tools only** — never the full backend catalog | Fixes context bloat. Backend tools are invoked through `mcpmux_invoke_tool`, not registered in the client tool list (except surfaced exceptions). |
+| 2 | Discovery API | **`mcpmux_search_tools` with `detail_level`**: `name` \| `description` \| `schema`** | Replaces dumping `mcpmux_list_all_tools` for agent workflows. Supports server_id filter, pagination, and query string. Start with substring + server_id filter; TF-IDF semantic rank is Phase D optional. |
+| 3 | Schema API | **`mcpmux_get_tool_schema`** — single or batch, optional `compact: true`** | Agents must read schemas before invoke without relying on Cursor descriptor JSON files. Batch load for multi-tool workflows (e.g. issue read + comment write). |
+| 4 | Invoke API | **`mcpmux_invoke_tool({ server_id, tool, args, filter? })`** — one entry point for all backend calls | Mirrors `gateway_invoke`. Routes through existing `RoutingService::call_tool` after permission checks. Optional `filter` arg activates result shaping (Phase B). |
+| 5 | FeatureSet semantics | **FeatureSets define what is *invokable*, not what appears in `tools/list`** | Binding / grant / session-enable controls the candidate pool for search + invoke. Security boundary stays meaningful without polluting client context. |
+| 6 | Surfaced tools escape hatch | **FeatureSet members may mark tools `surfaced: true` (0–N per set)** — promoted into `tools/list` for one-hop hot paths | Default: **zero surfaced everywhere**, including built-in bundles. No bundle auto-promotes backend tools. Opt-in only via FeatureSet editor (Phase C). |
+| 7 | Invoke authorization | **Fail closed** — `invoke_tool` rejects when target server/tool is outside effective permission set | Same composition as today: `(binding_servers ∪ session_enabled) − session_disabled`, then FeatureSet member filter. Empty effective set → invoke denied with actionable error, not silent proxy. |
+| 8 | Session enable/disable | **Keep existing `mcpmux_enable_server` / `mcpmux_disable_server`** — they gate invoke/search eligibility, not `tools/list` size | Mental model unchanged: "turn on github" expands what search/invoke can reach. `tools/list` size stays ~constant. |
+| 9 | Error messages | **Actionable, bounded errors** — no dumping full available-tool lists | e.g. `"github inactive → mcpmux_enable_server('github')"`, `"unknown tool → did you mean github_list_issues?"`. Optional Levenshtein suggestions (Phase D). |
+| 10 | Rollout | **Hard cut — no legacy opt-out** | Backend tools never appear in `tools/list`. Direct `call_tool` on backend qualified names is rejected with an actionable redirect to `mcpmux_invoke_tool`. No `expose_backend_tools_in_list` setting. Ship in one release; document migration in CHANGELOG. |
+| 11 | `mcpmux_list_all_tools` | **Keep as operator/diagnostic tool** — not the primary agent discovery path | Still useful for FeatureSet authoring and UI. Doc + descriptions steer agents to `search_tools`. Consider server_id filter arg in Phase A to avoid 855 KB dumps. |
+| 12 | Result shaping scope | **Phase B only on `invoke_tool`** — `max_rows`, `max_bytes`, `fields`, `format: summary`** | Highest ROI after invoke model. Defer delta responses, auto-summarize, sandbox code exec to Phase D. |
+| 13 | REST / OpenAPI capabilities | **Out of scope here** — Phase E / separate planning doc | [`web-admin-remote-access.md`](./web-admin-remote-access.md) covers admin REST, not REST→MCP capability YAML. No conflict; different layer. |
+
+---
+
+## The Model
+
+### What the agent sees
+
+```text
+tools/list (fixed ~10–15 tools)
+├── mcpmux_list_servers
+├── mcpmux_enable_server / mcpmux_disable_server
+├── mcpmux_search_tools
+├── mcpmux_get_tool_schema
+├── mcpmux_invoke_tool
+├── mcpmux_list_feature_sets / mcpmux_create_feature_set / mcpmux_bind_current_workspace
+├── mcpmux_list_all_tools          (diagnostic — not primary discovery)
+└── [0–N surfaced backend tools]   (optional, from FeatureSet)
+```
+
+### Agent workflow (GitHub read example)
+
+```text
+1. mcpmux_list_servers                          → github: inactive
+2. mcpmux_enable_server({ server_id: "github" })
+3. mcpmux_search_tools({
+     query: "list issues",
+     server_id: "github",
+     detail_level: "description"
+   })
+4. mcpmux_get_tool_schema({ tools: ["github_list_issues"] })
+5. mcpmux_invoke_tool({
+     server_id: "github",
+     tool: "github_list_issues",
+     args: { owner: "mcpmux", repo: "mcp-mux" }
+   })
+```
+
+Three to four meta calls before the backend call — predictable schemas, bounded context.
+
+### Permission composition (unchanged server layer, new tool-list layer)
+
+```text
+1. (space, feature_set_ids) ← FeatureSetResolverService
+2. binding_servers          ← servers_for(space, feature_set_ids)
+3. session_on/off           ← SessionOverrideRegistry
+4. effective_servers        ← (binding ∪ session_on) − session_off
+5. invokable_tools          ← Tool features for effective_servers ∩ FeatureSet members
+6. tools/list               ← meta_tools ∪ surfaced(invokable_tools)
+7. search_tools / invoke    ← scoped to invokable_tools only
+```
+
+Prompts and resources: unchanged — still materialized per grants. Invoke model is tool-specific.
+
+### What this is NOT
+
+- Not replacing the desktop app, registry, or Spaces model
+- Not removing FeatureSets — they become invoke ACLs
+- Not implementing abdullah's full 15-layer optimization stack in v1
+- Not REST capability YAML / OpenAPI import (separate future doc)
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Cursor / Claude / VS Code                                      │
+│  tools/list → ~12 meta tools (+ optional surfaced)              │
+└────────────────────────────┬────────────────────────────────────┘
+                             │
+                             ▼
+┌─────────────────────────────────────────────────────────────────┐
+│  McpMux Gateway (:45818)                                        │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │ MetaToolRegistry                                          │  │
+│  │  search_tools → ToolDiscoveryService (index from Space)   │  │
+│  │  get_tool_schema → ServerFeature.input_schema             │  │
+│  │  invoke_tool → RoutingService::call_tool (existing path)  │  │
+│  └───────────────────────────────────────────────────────────┘  │
+│  ┌───────────────────────────────────────────────────────────┐  │
+│  │ FeatureService::get_tools_for_grants                      │  │
+│  │  → meta tools + surfaced only (hard cut — no backend list)  │  │
+│  └───────────────────────────────────────────────────────────┘  │
+└────────────────────────────┬────────────────────────────────────┘
+                             │
+         ┌───────────────────┼───────────────────┐
+         ▼                   ▼                   ▼
+    github (stdio)    google-workspace     posthog-personal
+```
+
+**New components:**
+
+- `ToolDiscoveryService` — in-memory index built from `server_feature_repo::list_for_space`, rebuilt on feature change events. Powers search + schema lookup.
+- `InvokeToolTool` — validates invokable set, forwards to `RoutingService::call_tool`, maps errors to actionable messages.
+
+**Chokepoints (existing):**
+
+- `FeatureService::get_tools_for_grants` — change what gets advertised in `tools/list`
+- `RoutingService::call_tool` — reuse for invoke; add invokable-set check if not already covered by grant lookup
+- `MetaToolRegistry` — register three new tools
+
+---
+
+## Files to create
+
+| File | Purpose |
+| ---- | ------- |
+| `crates/mcpmux-gateway/src/services/tool_discovery.rs` | Index + search + schema lookup over Space tool features |
+| `crates/mcpmux-gateway/src/services/meta_tools/invoke.rs` | `InvokeToolTool` impl — permission check, routing, error mapping |
+| `tests/rust/tests/integration/meta_gateway_invoke.rs` | Search, schema, invoke, permission deny, surfaced tools, direct backend call rejected |
+| `docs/planning/meta-gateway-invoke.md` | This doc |
+
+## Files to modify
+
+| File | Change |
+| ---- | ------ |
+| [`crates/mcpmux-gateway/src/services/mod.rs`](../../crates/mcpmux-gateway/src/services/mod.rs) | `pub mod tool_discovery;` |
+| [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | `SearchToolsTool`, `GetToolSchemaTool`; extend `ListAllToolsTool` with optional `server_id` filter |
+| [`crates/mcpmux-gateway/src/services/meta_tools/mod.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/mod.rs) | Register new tools; wire `ToolDiscoveryService` + `RoutingService` into `MetaToolContext` |
+| [`crates/mcpmux-gateway/src/services/meta_tools/registry.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/registry.rs) | Extend `MetaToolContext` with discovery + routing handles |
+| [`crates/mcpmux-gateway/src/pool/features/facade.rs`](../../crates/mcpmux-gateway/src/pool/features/facade.rs) | Split `get_tools_for_grants` into advertised (meta + surfaced) vs invokable (full set for search/invoke ACL) |
+| [`crates/mcpmux-gateway/src/pool/routing.rs`](../../crates/mcpmux-gateway/src/pool/routing.rs) | Shared invokable-set helper; ensure `call_tool` errors are actionable |
+| [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) | `tools/list` uses advertised set only; direct backend `call_tool` rejected with invoke redirect |
+| [`crates/mcpmux-storage/`](../../crates/mcpmux-storage/) or core domain | Optional `surfaced` flag on FeatureSet member rows (Phase C) — if schema change needed |
+| [`apps/desktop/src/features/settings/SettingsPage.tsx`](../../apps/desktop/src/features/settings/SettingsPage.tsx) | Update meta-tools copy for search → schema → invoke workflow |
+| [`apps/desktop/src/features/feature-sets/`](../../apps/desktop/src/features/feature-sets/) | UI to mark tools as surfaced (Phase C) |
+| [`README.md`](../../README.md) | Replace "every tool available right now" agent-facing claim; document search → schema → invoke flow |
+
+---
+
+## Phasing
+
+### Phase A — Meta invoke core
+
+**Effort:** ~3–4 days
+
+- [ ] `ToolDiscoveryService` — build index from Space features; search by query + optional `server_id`; return matches at `detail_level`
+- [ ] `mcpmux_search_tools` meta tool — pagination (`limit`, `cursor`), `detail_level` enum
+- [ ] `mcpmux_get_tool_schema` — single + batch; `compact` strips descriptions/examples
+- [ ] `mcpmux_invoke_tool` — `{ server_id, tool, args }`; delegates to `RoutingService::call_tool`; fail closed on permission miss
+- [ ] `FeatureService` split: **advertised** = meta tools + surfaced only (hard cut — no backend tools in list)
+- [ ] Handler rejects direct backend `call_tool` — return actionable error pointing to `mcpmux_invoke_tool`
+- [ ] Actionable error mapping: inactive server, unknown tool, permission denied, param validation passthrough from backend
+- [ ] Optional `server_id` filter on `mcpmux_list_all_tools`
+- [ ] Integration tests: GitHub read path (enable → search → schema → invoke); deny when server inactive; direct `github_*` call rejected
+
+**Outcome:** Cursor session shows ~12 `mcpmux_*` tools. Agent completes `github_list_issues` on `mcpmux/mcp-mux` in 4 meta calls + invoke with zero param guessing. Token footprint for tool definitions drops from ~30–50k to ~1–2k.
+
+### Phase B — Result shaping on invoke
+
+**Effort:** ~2 days
+
+- [ ] Extend `mcpmux_invoke_tool` args with optional `filter: { max_rows?, max_bytes?, fields?, format? }`
+- [ ] Post-process JSON/text results in gateway before returning to client
+- [ ] Default smart truncation for known-heavy patterns (large arrays) when filter omitted
+- [ ] Integration tests: truncated list response includes `{ returned, total, truncated: true }`
+
+**Outcome:** Posthog/Firebase/GWorkspace list calls return bounded payloads. Agent can query large backends without blowing context on results.
+
+### Phase C — FeatureSet as invoke ACL + surfaced tools
+
+**Effort:** ~3 days
+
+- [ ] FeatureSet member model: tools invokable by default when server in set; optional `surfaced: true` promotes into `tools/list`
+- [ ] Search + invoke respect FeatureSet member filter (not just server-all)
+- [ ] Workspaces UI: per-tool "Surface in client" toggle in FeatureSet editor
+- [ ] Update `mcpmux_create_feature_set` to accept optional `surfaced_tools[]`
+- [ ] Integration tests: binding with partial tool set → search only finds allowed tools; surfaced tool appears in `tools/list`
+
+**Outcome:** Bundles ship with zero surfaced tools by default. Users may opt in per FeatureSet. Invoke ACL semantics are unambiguous: **permission + optional promotion**.
+
+### Phase D — Advanced optimizations (defer)
+
+**Effort:** TBD
+
+- [ ] Levenshtein "did you mean?" on invoke errors
+- [ ] TF-IDF / semantic rank in search
+- [ ] Delta responses, auto-summarize, parallel invoke batching
+- [ ] Sandboxed code execution (abdullah-style `gateway_execute_code`)
+
+**Outcome:** Incremental token/latency wins for power users. Each item is independently shippable.
+
+### Phase E — REST capabilities (separate initiative)
+
+**Effort:** TBD — requires its own planning doc
+
+- [ ] OpenAPI → capability definition in registry or gateway-local YAML
+- [ ] Invoke through same `mcpmux_invoke_tool` path
+
+**Outcome:** Non-MCP HTTP APIs join the gateway without a separate MCP server process. Not blocked by Phases A–D.
+
+### Phase F — Session pin as invoke ACL (very optional)
+
+**Effort:** ~1 day — **only if** a concrete use case remains after Phases A–C
+
+- [ ] Re-scope [`tool-level-session-pin.md`](./tool-level-session-pin.md): `mcpmux_pin_this_session` restricts **invokable set** for the session, not `tools/list` membership
+- [ ] Ship only on evidence that search + invoke + FeatureSet ACL is insufficient (e.g. agent repeatedly invokes disallowed tools and needs a tighter session knob)
+
+**Outcome:** Temporary invoke ACL ("only these 12 tools invokable for this session") without re-expanding `tools/list`. Skip entirely if Phase A–C covers the GWorkspace clone case.
+
+---
+
+## Pre-PR validation
+
+| Step | Command | Purpose |
+| ---- | ------- | ------- |
+| Full validate | `pnpm validate` | fmt, clippy, check, eslint, typecheck |
+| Rust tests | `pnpm test:rust` | unit + `meta_gateway_invoke.rs` integration |
+| TS tests | `pnpm test:ts` | vitest |
+| Manual smoke | Cursor against live gateway: GitHub read, GWorkspace invoke, permission deny | Agent UX verification |
+
+---
+
+## Out of scope
+
+| Item | Reason |
+| ---- | ------ |
+| [`web-admin-remote-access.md`](./web-admin-remote-access.md) | Remote admin UI — parallel track, no overlap |
+| Full abdullah 15-layer stack | Phase D picks winners after A+B prove value |
+| Removing `mcpmux_enable_server` | Still gates invoke eligibility; still needed when server not in binding |
+| Auto-enable server on failed invoke | Silent enable defeats audit trail — rejected in dynamic-toggle doc |
+| Tool-poisoning validator / SHA-256 pinning | MikkoParkkola feature; valuable follow-up for registry trust, not invoke core |
+| Cursor descriptor JSON sync | Client-side concern; schema-on-demand makes it non-blocking |
+
+---
+
+## Key files referenced
+
+| File | Why |
+| ---- | --- |
+| [`crates/mcpmux-gateway/src/pool/features/facade.rs`](../../crates/mcpmux-gateway/src/pool/features/facade.rs) | Materialization chokepoint — must split advertised vs invokable |
+| [`crates/mcpmux-gateway/src/pool/routing.rs`](../../crates/mcpmux-gateway/src/pool/routing.rs) | Existing `call_tool` path invoke reuses |
+| [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | New meta tool impls land here |
+| [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) | `tools/list` + `call_tool` handler — legacy direct call blocking |
+| [`docs/planning/dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) | Session enable/disable — kept, semantics updated |
+| [`docs/planning/tool-level-session-pin.md`](./tool-level-session-pin.md) | Superseded for token budget; Phase F very optional rework |
+
+---
+
+## Related documentation
+
+- [`docs/planning/dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) — session overrides (complete)
+- [`docs/planning/tool-level-session-pin.md`](./tool-level-session-pin.md) — superseded; Phase F may revive as invoke ACL only if needed
+- [`docs/planning/server-account-clones.md`](./server-account-clones.md) — origin of 240-tool bloat evidence
+- [`docs/planning/web-admin-remote-access.md`](./web-admin-remote-access.md) — remote operator UI (orthogonal)
+- [MikkoParkkola/mcp-gateway](https://github.com/MikkoParkkola/mcp-gateway) — `gateway_search_tools` / `gateway_invoke` reference
+- [abdullah1854/MCPGateway](https://github.com/abdullah1854/MCPGateway) — `gateway_get_tool_schema` / result filtering reference
+
+---
+
+## Reconciliation
+
+This doc is the source of truth for the meta-gateway invoke model. When implementation starts, update **Status** and **Branch** at the top. Mark [`tool-level-session-pin.md`](./tool-level-session-pin.md) **Status** as *Superseded* once Phase A ships.
+
+**Decision record (May 25, 2026):** Hard cut to invoke-only — no legacy direct backend exposure. Surfaced tools default zero everywhere (bundles included). FeatureSets redefine as invoke ACL + optional surfaced promotion. Session pin deferred to Phase F (very optional, last). Competitor analysis (MikkoParkkola + abdullah1854) informed Phase A–B scope; REST capabilities in Phase E / separate doc.
diff --git a/docs/planning/tool-level-session-pin.md b/docs/planning/tool-level-session-pin.md
index 27bd76b1..31abeee2 100644
--- a/docs/planning/tool-level-session-pin.md
+++ b/docs/planning/tool-level-session-pin.md
@@ -1,7 +1,7 @@
 # Tool-Level Session Pin Meta Tool (`mcpmux_pin_this_session`)
 
 **Last Updated:** May 25, 2026
-**Status:** Planning
+**Status:** Deferred — superseded by [`meta-gateway-invoke.md`](./meta-gateway-invoke.md) for token budget. May revive as Phase F (invoke ACL only) if search + invoke proves insufficient.
 **Branch:** TBD — branch off `main` once [`dynamic-mcp-toggle-meta-tools`](./dynamic-mcp-toggle-meta-tools.md) merges
 **Base branch:** `main` (depends on the meta-tools infrastructure shipped via the dynamic-toggle PR being live)
 **Issue:** TBD — file after planning review

From 4978d70d811c648e071a9ba798d255bf6c2683ae Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 12:13:42 -0600
Subject: [PATCH 33/48] =?UTF-8?q?feat(gateway):=20Phase=20A=20=E2=80=94=20?=
 =?UTF-8?q?Meta=20invoke=20core?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Autonomous decisions:
- routing_service as Option in MetaToolContext — existing meta_tools tests stay lightweight without PoolService wiring
- Updated service_container.rs and meta_tools.rs fixtures — mechanical compile wiring for build_default_registry signature change
- mcpmux_invoke_tool is_read (not write) — backend invoke is not a gateway state mutation and must not require approval
- get_advertised_tools_for_grants returns empty until Phase C surfaced flag — hard cut keeps tools/list meta-only now

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 crates/mcpmux-gateway/src/mcp/handler.rs      |  27 +-
 .../src/pool/features/facade.rs               |  34 +-
 crates/mcpmux-gateway/src/pool/mod.rs         |   5 +-
 crates/mcpmux-gateway/src/pool/routing.rs     |  53 ++-
 .../src/server/service_container.rs           |   1 +
 .../src/services/meta_tools/invoke.rs         | 198 +++++++++++
 .../src/services/meta_tools/mod.rs            |  11 +
 .../src/services/meta_tools/registry.rs       |   9 +-
 .../src/services/meta_tools/tools.rs          | 196 ++++++++++-
 crates/mcpmux-gateway/src/services/mod.rs     |   2 +
 .../src/services/tool_discovery.rs            | 221 ++++++++++++
 .../tests/integration/meta_gateway_invoke.rs  | 315 ++++++++++++++++++
 tests/rust/tests/integration/meta_tools.rs    |   3 +
 tests/rust/tests/integration/mod.rs           |   1 +
 14 files changed, 1060 insertions(+), 16 deletions(-)
 create mode 100644 crates/mcpmux-gateway/src/services/meta_tools/invoke.rs
 create mode 100644 crates/mcpmux-gateway/src/services/tool_discovery.rs
 create mode 100644 tests/rust/tests/integration/meta_gateway_invoke.rs

diff --git a/crates/mcpmux-gateway/src/mcp/handler.rs b/crates/mcpmux-gateway/src/mcp/handler.rs
index 1c9b3b9b..43acaa25 100644
--- a/crates/mcpmux-gateway/src/mcp/handler.rs
+++ b/crates/mcpmux-gateway/src/mcp/handler.rs
@@ -671,12 +671,12 @@ impl ServerHandler for McpMuxGatewayHandler {
             .resolve_routing(session_id_owned.as_deref(), &oauth_ctx.client_id)
             .await?;
 
-        // Get tools via FeatureService — using the *resolved* space.
+        // Get advertised tools (meta + surfaced only) for client tools/list.
         let tools = self
             .services
             .pool_services
             .feature_service
-            .get_tools_for_grants(
+            .get_advertised_tools_for_grants(
                 &space_id.to_string(),
                 &feature_set_ids,
                 session_id_owned.as_deref(),
@@ -785,6 +785,29 @@ impl ServerHandler for McpMuxGatewayHandler {
             .resolve_routing(session_id, &oauth_ctx.client_id)
             .await?;
 
+        // Hard cut: reject direct backend tool calls — agents must use mcpmux_invoke_tool.
+        let space_id_str = space_id.to_string();
+        if let Ok(Some((server_id, actual_tool_name))) = self
+            .services
+            .pool_services
+            .feature_service
+            .find_server_for_qualified_tool(&space_id_str, &params.name)
+            .await
+        {
+            let message = crate::pool::format_direct_call_redirect(
+                &params.name,
+                &server_id,
+                &actual_tool_name,
+            );
+            return Ok(CallToolResult::error(vec![Content::text(
+                serde_json::json!({
+                    "error": "use_invoke_tool",
+                    "message": message,
+                })
+                .to_string(),
+            )]));
+        }
+
         // Call tool via routing service (handles auth and routing)
         let tool_result = self
             .services
diff --git a/crates/mcpmux-gateway/src/pool/features/facade.rs b/crates/mcpmux-gateway/src/pool/features/facade.rs
index c3a6d461..7b6d8100 100644
--- a/crates/mcpmux-gateway/src/pool/features/facade.rs
+++ b/crates/mcpmux-gateway/src/pool/features/facade.rs
@@ -90,8 +90,8 @@ impl FeatureService {
             .await
     }
 
-    /// Resolve granted feature sets to tools, applying session server overrides.
-    pub async fn get_tools_for_grants(
+    /// Resolve granted feature sets to tools invokable via search/invoke ACL.
+    pub async fn get_invokable_tools_for_grants(
         &self,
         space_id: &str,
         feature_set_ids: &[String],
@@ -106,6 +106,36 @@ impl FeatureService {
         .await
     }
 
+    /// Tools promoted into client `tools/list` (surfaced backend tools only).
+    ///
+    /// Phase C adds per-member `surfaced: true`; until then this returns an
+    /// empty list so clients see meta tools only.
+    pub async fn get_advertised_tools_for_grants(
+        &self,
+        space_id: &str,
+        feature_set_ids: &[String],
+        session_id: Option<&str>,
+    ) -> Result<Vec<ServerFeature>> {
+        let invokable = self
+            .get_invokable_tools_for_grants(space_id, feature_set_ids, session_id)
+            .await?;
+        Ok(invokable
+            .into_iter()
+            .filter(|_| false) // Phase C: filter surfaced members
+            .collect())
+    }
+
+    /// Resolve granted feature sets to tools, applying session server overrides.
+    pub async fn get_tools_for_grants(
+        &self,
+        space_id: &str,
+        feature_set_ids: &[String],
+        session_id: Option<&str>,
+    ) -> Result<Vec<ServerFeature>> {
+        self.get_invokable_tools_for_grants(space_id, feature_set_ids, session_id)
+            .await
+    }
+
     /// Resolve granted feature sets to prompts, applying session server overrides.
     pub async fn get_prompts_for_grants(
         &self,
diff --git a/crates/mcpmux-gateway/src/pool/mod.rs b/crates/mcpmux-gateway/src/pool/mod.rs
index 3a4b366a..cfbb4e8e 100644
--- a/crates/mcpmux-gateway/src/pool/mod.rs
+++ b/crates/mcpmux-gateway/src/pool/mod.rs
@@ -42,7 +42,10 @@ pub use oauth::{
 // SOLID Services
 pub use connection::{ConnectionResult, ConnectionService};
 pub use features::{CachedFeatures, FeatureService};
-pub use routing::{RoutedPrompt, RoutedResource, RoutedTool, RoutingService};
+pub use routing::{
+    format_direct_call_redirect, format_invoke_permission_denied, format_server_inactive_error,
+    RoutedPrompt, RoutedResource, RoutedTool, RoutingService,
+};
 pub use service::{InstalledServerInfo, PoolService, PoolStats, ReconnectResult};
 pub use token::TokenService;
 pub use transport::{ResolvedTransport, Transport, TransportConnectResult, TransportFactory};
diff --git a/crates/mcpmux-gateway/src/pool/routing.rs b/crates/mcpmux-gateway/src/pool/routing.rs
index a2f02a37..2bed2dfb 100644
--- a/crates/mcpmux-gateway/src/pool/routing.rs
+++ b/crates/mcpmux-gateway/src/pool/routing.rs
@@ -58,6 +58,45 @@ pub struct ToolCallResult {
 /// Default timeout for MCP tool calls (60 seconds)
 const TOOL_CALL_TIMEOUT: Duration = Duration::from_secs(60);
 
+/// Actionable error when a server is not in the effective enable set.
+pub fn format_server_inactive_error(server_id: &str) -> String {
+    format!(
+        "server '{server_id}' is inactive → mcpmux_enable_server({{ \"server_id\": \"{server_id}\" }})"
+    )
+}
+
+/// Actionable error when invoke targets a tool outside the permission set.
+pub fn format_invoke_permission_denied(
+    qualified_name: &str,
+    server_id: &str,
+    tool_name: &str,
+    suggestions: &[String],
+) -> String {
+    if suggestions.is_empty() {
+        format!(
+            "tool '{qualified_name}' is not invokable with current grants (server_id='{server_id}', tool='{tool_name}')"
+        )
+    } else {
+        format!(
+            "tool '{qualified_name}' is not invokable — did you mean {}?",
+            suggestions.join(", ")
+        )
+    }
+}
+
+/// Redirect message for direct backend `call_tool` attempts.
+pub fn format_direct_call_redirect(
+    qualified_name: &str,
+    server_id: &str,
+    tool_name: &str,
+) -> String {
+    format!(
+        "Direct backend tool calls are not supported. Use mcpmux_invoke_tool instead: \
+         mcpmux_invoke_tool({{ \"server_id\": \"{server_id}\", \"tool\": \"{tool_name}\", \"args\": {{}} }}) \
+         (qualified name was '{qualified_name}')"
+    )
+}
+
 /// RoutingService dispatches requests to backend MCP servers
 pub struct RoutingService {
     feature_service: Arc<FeatureService>,
@@ -92,7 +131,7 @@ impl RoutingService {
         // Resolve feature sets to allowed features
         let allowed_features = self
             .feature_service
-            .get_tools_for_grants(&space_id_str, feature_set_ids, session_id)
+            .get_invokable_tools_for_grants(&space_id_str, feature_set_ids, session_id)
             .await?;
 
         // Filter to just tools
@@ -204,7 +243,7 @@ impl RoutingService {
         // 2. Check if the tool is allowed by grants (session overrides included)
         let allowed_features = self
             .feature_service
-            .get_tools_for_grants(&space_id_str, feature_set_ids, session_id)
+            .get_invokable_tools_for_grants(&space_id_str, feature_set_ids, session_id)
             .await?;
 
         info!(
@@ -240,10 +279,12 @@ impl RoutingService {
                 "[RoutingService] Tool '{}' NOT allowed. Looking for server_id='{}', feature_name='{}', is_available=true",
                 tool_name, server_id, actual_tool_name
             );
-            return Err(anyhow!(
-                "Tool '{}' is not allowed by the current grants",
-                tool_name
-            ));
+            return Err(anyhow!(format_invoke_permission_denied(
+                tool_name,
+                &server_id,
+                &actual_tool_name,
+                &[],
+            )));
         }
 
         info!("[RoutingService] Tool '{}' is ALLOWED", tool_name);
diff --git a/crates/mcpmux-gateway/src/server/service_container.rs b/crates/mcpmux-gateway/src/server/service_container.rs
index 54e39b6b..805b5ac8 100644
--- a/crates/mcpmux-gateway/src/server/service_container.rs
+++ b/crates/mcpmux-gateway/src/server/service_container.rs
@@ -134,6 +134,7 @@ impl ServiceContainer {
             deps.installed_server_repo.clone(),
             feature_set_resolver.clone(),
             pool_services.feature_service.clone(),
+            Some(pool_services.routing_service.clone()),
             session_roots.clone(),
             session_overrides.clone(),
             approval_broker.clone(),
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/invoke.rs b/crates/mcpmux-gateway/src/services/meta_tools/invoke.rs
new file mode 100644
index 00000000..9ca32aef
--- /dev/null
+++ b/crates/mcpmux-gateway/src/services/meta_tools/invoke.rs
@@ -0,0 +1,198 @@
+//! `mcpmux_invoke_tool` — permission-checked gateway into backend MCP tools.
+
+use async_trait::async_trait;
+use rmcp::model::{CallToolResult, Content};
+use serde_json::{json, Value};
+
+use super::registry::{MetaTool, MetaToolCall, MetaToolError};
+use super::tools::{caller_resolution, caller_space_id};
+use crate::pool::{format_invoke_permission_denied, format_server_inactive_error};
+use crate::services::tool_discovery::ToolDiscoveryService;
+use mcpmux_core::FeatureType;
+
+/// Meta tool that forwards invocations to [`RoutingService::call_tool`].
+pub struct InvokeToolTool;
+
+#[async_trait]
+impl MetaTool for InvokeToolTool {
+    fn name(&self) -> &'static str {
+        "mcpmux_invoke_tool"
+    }
+
+    fn description(&self) -> &'static str {
+        "Invoke a backend MCP tool by server_id and tool name. Requires the \
+         server to be active (binding or session enable) and the tool to be \
+         in the current permission set. Use mcpmux_search_tools and \
+         mcpmux_get_tool_schema before calling."
+    }
+
+    fn input_schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "required": ["server_id", "tool"],
+            "properties": {
+                "server_id": {
+                    "type": "string",
+                    "description": "Registry server id (e.g. github)"
+                },
+                "tool": {
+                    "type": "string",
+                    "description": "Bare tool name on that server (e.g. list_issues), not the qualified name"
+                },
+                "args": {
+                    "type": "object",
+                    "description": "Arguments object passed to the backend tool",
+                    "default": {}
+                }
+            }
+        })
+    }
+
+    fn is_write(&self) -> bool {
+        false
+    }
+
+    async fn call(&self, call: MetaToolCall<'_>) -> Result<CallToolResult, MetaToolError> {
+        let server_id = call
+            .args
+            .get("server_id")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| MetaToolError::InvalidArgument("missing `server_id`".into()))?
+            .to_string();
+        let tool_name = call
+            .args
+            .get("tool")
+            .and_then(|v| v.as_str())
+            .ok_or_else(|| MetaToolError::InvalidArgument("missing `tool`".into()))?
+            .to_string();
+        let args = call.args.get("args").cloned().unwrap_or_else(|| json!({}));
+
+        let resolved = caller_resolution(&call).await?;
+        let space_id = caller_space_id(&call).await?;
+        let session_id = call.session_id;
+
+        let invokable = call
+            .ctx
+            .feature_service
+            .get_invokable_tools_for_grants(
+                &space_id.to_string(),
+                &resolved.feature_set_ids,
+                session_id,
+            )
+            .await
+            .map_err(|e| MetaToolError::Internal(e.to_string()))?;
+
+        let binding_features = call
+            .ctx
+            .feature_service
+            .resolve_feature_sets(&space_id.to_string(), &resolved.feature_set_ids)
+            .await
+            .map_err(|e| MetaToolError::Internal(e.to_string()))?;
+        let binding_servers: std::collections::HashSet<String> = binding_features
+            .iter()
+            .map(|f| f.server_id.clone())
+            .collect();
+        let session_enabled = session_id
+            .map(|sid| call.ctx.session_overrides.enabled_set(sid))
+            .unwrap_or_default();
+        let session_disabled = session_id
+            .map(|sid| call.ctx.session_overrides.disabled_set(sid))
+            .unwrap_or_default();
+
+        let is_server_active = binding_servers.contains(&server_id)
+            || (session_enabled.contains(&server_id) && !session_disabled.contains(&server_id));
+
+        if session_disabled.contains(&server_id) {
+            return Ok(invoke_error(format!(
+                "server '{server_id}' is disabled for this session → mcpmux_enable_server({{ \"server_id\": \"{server_id}\" }})"
+            )));
+        }
+
+        if !is_server_active {
+            return Ok(invoke_error(format_server_inactive_error(&server_id)));
+        }
+
+        let qualified_name = invokable
+            .iter()
+            .find(|f| f.server_id == server_id && f.feature_name == tool_name)
+            .map(|f| f.qualified_name())
+            .unwrap_or_else(|| format!("{server_id}_{tool_name}"));
+        let is_invokable = invokable.iter().any(|f| {
+            f.feature_type == FeatureType::Tool
+                && f.server_id == server_id
+                && f.feature_name == tool_name
+                && f.is_available
+        });
+
+        if !is_invokable {
+            let index = call
+                .ctx
+                .tool_discovery
+                .build_index(&space_id.to_string(), &invokable)
+                .await
+                .map_err(|e| MetaToolError::Internal(e.to_string()))?;
+            let suggestions: Vec<String> = ToolDiscoveryService::search(
+                &index,
+                Some(&tool_name),
+                Some(&server_id),
+                crate::services::tool_discovery::DetailLevel::Name,
+                5,
+                None,
+            )
+            .tools
+            .iter()
+            .filter_map(|v| {
+                v.get("qualified_name")
+                    .and_then(|n| n.as_str().map(String::from))
+            })
+            .collect();
+            return Ok(invoke_error(format_invoke_permission_denied(
+                &qualified_name,
+                &server_id,
+                &tool_name,
+                &suggestions,
+            )));
+        }
+
+        let routing = call
+            .ctx
+            .routing_service
+            .as_ref()
+            .ok_or_else(|| MetaToolError::Internal("invoke routing not configured".into()))?;
+        match routing
+            .call_tool(
+                space_id,
+                &resolved.feature_set_ids,
+                session_id,
+                &qualified_name,
+                args,
+            )
+            .await
+        {
+            Ok(result) => {
+                let content: Vec<Content> = result
+                    .content
+                    .into_iter()
+                    .filter_map(|v| serde_json::from_value(v).ok())
+                    .collect();
+                let mut mcp_result = if result.is_error {
+                    CallToolResult::error(content)
+                } else {
+                    CallToolResult::success(content)
+                };
+                mcp_result.structured_content = result.structured_content;
+                Ok(mcp_result)
+            }
+            Err(e) => Ok(invoke_error(e.to_string())),
+        }
+    }
+}
+
+/// Build a structured MCP error payload for invoke failures.
+fn invoke_error(message: String) -> CallToolResult {
+    let payload = json!({
+        "error": "invoke_failed",
+        "message": message,
+    });
+    CallToolResult::error(vec![Content::text(payload.to_string())])
+}
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/mod.rs b/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
index 1c0a39ef..f0bf984f 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
@@ -22,6 +22,7 @@
 
 pub mod approval;
 pub mod diff;
+mod invoke;
 mod registry;
 mod tools;
 mod workspace_server;
@@ -36,6 +37,8 @@ pub use registry::{
     SESSION_OVERRIDES_REQUIRE_APPROVAL_KEY,
 };
 
+use crate::services::ToolDiscoveryService;
+
 /// Every built-in tool's name must start with this prefix so the handler
 /// can intercept it before routing to backend servers.
 pub const MCPMUX_PREFIX: &str = "mcpmux_";
@@ -59,12 +62,15 @@ pub fn build_default_registry(
     installed_server_repo: std::sync::Arc<dyn mcpmux_core::InstalledServerRepository>,
     resolver: std::sync::Arc<crate::services::FeatureSetResolverService>,
     feature_service: std::sync::Arc<crate::pool::FeatureService>,
+    routing_service: Option<std::sync::Arc<crate::pool::RoutingService>>,
     session_roots: std::sync::Arc<crate::services::SessionRootsRegistry>,
     session_overrides: std::sync::Arc<crate::services::SessionOverrideRegistry>,
     approval_broker: std::sync::Arc<ApprovalBroker>,
     domain_event_tx: tokio::sync::broadcast::Sender<mcpmux_core::DomainEvent>,
     settings_repo: Option<std::sync::Arc<dyn mcpmux_core::AppSettingsRepository>>,
 ) -> std::sync::Arc<MetaToolRegistry> {
+    let tool_discovery =
+        std::sync::Arc::new(ToolDiscoveryService::new(server_feature_repo.clone()));
     let ctx = MetaToolContext {
         client_repo,
         space_repo,
@@ -74,6 +80,8 @@ pub fn build_default_registry(
         installed_server_repo,
         resolver,
         feature_service,
+        routing_service,
+        tool_discovery,
         session_roots,
         session_overrides,
         approval_broker,
@@ -86,6 +94,9 @@ pub fn build_default_registry(
     registry.register(Box::new(tools::ListAllToolsTool));
     registry.register(Box::new(tools::ListFeatureSetsTool));
     registry.register(Box::new(tools::ListServersTool));
+    registry.register(Box::new(tools::SearchToolsTool));
+    registry.register(Box::new(tools::GetToolSchemaTool));
+    registry.register(Box::new(invoke::InvokeToolTool));
     // Writes — gated by ApprovalBroker (or auto-allowed for session overrides).
     registry.register(Box::new(tools::EnableServerTool));
     registry.register(Box::new(tools::DisableServerTool));
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/registry.rs b/crates/mcpmux-gateway/src/services/meta_tools/registry.rs
index 583b9eaa..eb692f4a 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/registry.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/registry.rs
@@ -18,8 +18,10 @@ use thiserror::Error;
 use tokio::sync::broadcast;
 
 use super::approval::ApprovalBroker;
-use crate::pool::FeatureService;
-use crate::services::{FeatureSetResolverService, SessionOverrideRegistry, SessionRootsRegistry};
+use crate::pool::{FeatureService, RoutingService};
+use crate::services::{
+    FeatureSetResolverService, SessionOverrideRegistry, SessionRootsRegistry, ToolDiscoveryService,
+};
 
 /// App-settings key that toggles the entire `mcpmux_*` namespace.
 /// Present + "false" → hidden; missing or anything else → enabled.
@@ -44,6 +46,9 @@ pub struct MetaToolContext {
     pub installed_server_repo: Arc<dyn InstalledServerRepository>,
     pub resolver: Arc<FeatureSetResolverService>,
     pub feature_service: Arc<FeatureService>,
+    /// Backend invoke path — required for `mcpmux_invoke_tool`.
+    pub routing_service: Option<Arc<RoutingService>>,
+    pub tool_discovery: Arc<ToolDiscoveryService>,
     pub session_roots: Arc<SessionRootsRegistry>,
     pub session_overrides: Arc<SessionOverrideRegistry>,
     pub approval_broker: Arc<ApprovalBroker>,
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
index 1c651d94..bcc73452 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
@@ -52,7 +52,7 @@ pub(crate) fn text_result(v: Value) -> CallToolResult {
 /// to them, and prevents an LLM in workspace A from mutating FSes in
 /// workspace B just because both sit under the same default-Space-flagged
 /// row in the DB.
-async fn caller_space_id(call: &MetaToolCall<'_>) -> Result<Uuid, MetaToolError> {
+pub(crate) async fn caller_space_id(call: &MetaToolCall<'_>) -> Result<Uuid, MetaToolError> {
     let resolved = call
         .ctx
         .resolver
@@ -69,7 +69,9 @@ async fn caller_space_id(call: &MetaToolCall<'_>) -> Result<Uuid, MetaToolError>
 }
 
 /// Full resolver output for the caller — space + binding FS ids + source.
-async fn caller_resolution(call: &MetaToolCall<'_>) -> Result<ResolvedFeatureSet, MetaToolError> {
+pub(crate) async fn caller_resolution(
+    call: &MetaToolCall<'_>,
+) -> Result<ResolvedFeatureSet, MetaToolError> {
     call.ctx
         .resolver
         .resolve(call.session_id, Some(call.client_id))
@@ -115,11 +117,20 @@ impl MetaTool for ListAllToolsTool {
     }
 
     fn input_schema(&self) -> Value {
-        json!({ "type": "object", "properties": {} })
+        json!({
+            "type": "object",
+            "properties": {
+                "server_id": {
+                    "type": "string",
+                    "description": "Optional filter to one server id"
+                }
+            }
+        })
     }
 
     async fn call(&self, call: MetaToolCall<'_>) -> Result<CallToolResult, MetaToolError> {
         let space_id = caller_space_id(&call).await?;
+        let server_filter = call.args.get("server_id").and_then(|v| v.as_str());
         let features = call
             .ctx
             .server_feature_repo
@@ -128,6 +139,7 @@ impl MetaTool for ListAllToolsTool {
         let tools: Vec<_> = features
             .iter()
             .filter(|f| f.feature_type == FeatureType::Tool)
+            .filter(|f| server_filter.is_none_or(|sid| f.server_id == sid))
             .map(|f| {
                 json!({
                     "server_id": f.server_id,
@@ -331,6 +343,184 @@ impl MetaTool for ListServersTool {
     }
 }
 
+// ---------------------------------------------------------------------------
+// mcpmux_search_tools — read
+// ---------------------------------------------------------------------------
+
+pub struct SearchToolsTool;
+
+#[async_trait]
+impl MetaTool for SearchToolsTool {
+    fn name(&self) -> &'static str {
+        "mcpmux_search_tools"
+    }
+
+    fn description(&self) -> &'static str {
+        "Search invokable backend tools in the caller's resolved Space. \
+         Supports query substring match, optional server_id filter, \
+         detail_level (name | description | schema), and pagination."
+    }
+
+    fn input_schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "properties": {
+                "query": { "type": "string" },
+                "server_id": { "type": "string" },
+                "detail_level": {
+                    "type": "string",
+                    "enum": ["name", "description", "schema"],
+                    "default": "description"
+                },
+                "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 },
+                "cursor": { "type": "string" }
+            }
+        })
+    }
+
+    async fn call(&self, call: MetaToolCall<'_>) -> Result<CallToolResult, MetaToolError> {
+        let resolved = caller_resolution(&call).await?;
+        let space_id = caller_space_id(&call).await?;
+
+        let detail_level = call
+            .args
+            .get("detail_level")
+            .and_then(|v| v.as_str())
+            .and_then(crate::services::tool_discovery::DetailLevel::parse)
+            .unwrap_or(crate::services::tool_discovery::DetailLevel::Description);
+
+        let limit = call
+            .args
+            .get("limit")
+            .and_then(|v| v.as_u64())
+            .unwrap_or(20) as usize;
+
+        let invokable = call
+            .ctx
+            .feature_service
+            .get_invokable_tools_for_grants(
+                &space_id.to_string(),
+                &resolved.feature_set_ids,
+                call.session_id,
+            )
+            .await
+            .map_err(|e| MetaToolError::Internal(e.to_string()))?;
+
+        let index = call
+            .ctx
+            .tool_discovery
+            .build_index(&space_id.to_string(), &invokable)
+            .await
+            .map_err(|e| MetaToolError::Internal(e.to_string()))?;
+
+        let result = crate::services::tool_discovery::ToolDiscoveryService::search(
+            &index,
+            call.args.get("query").and_then(|v| v.as_str()),
+            call.args.get("server_id").and_then(|v| v.as_str()),
+            detail_level,
+            limit,
+            call.args.get("cursor").and_then(|v| v.as_str()),
+        );
+
+        Ok(text_result(json!({
+            "tools": result.tools,
+            "next_cursor": result.next_cursor,
+            "total": result.total,
+        })))
+    }
+}
+
+// ---------------------------------------------------------------------------
+// mcpmux_get_tool_schema — read
+// ---------------------------------------------------------------------------
+
+pub struct GetToolSchemaTool;
+
+#[async_trait]
+impl MetaTool for GetToolSchemaTool {
+    fn name(&self) -> &'static str {
+        "mcpmux_get_tool_schema"
+    }
+
+    fn description(&self) -> &'static str {
+        "Load input schemas for one or more qualified tool names before \
+         invoking via mcpmux_invoke_tool. Pass tools as a string or array. \
+         Set compact: true to omit descriptions."
+    }
+
+    fn input_schema(&self) -> Value {
+        json!({
+            "type": "object",
+            "required": ["tools"],
+            "properties": {
+                "tools": {
+                    "oneOf": [
+                        { "type": "string" },
+                        { "type": "array", "items": { "type": "string" } }
+                    ]
+                },
+                "compact": { "type": "boolean", "default": false }
+            }
+        })
+    }
+
+    async fn call(&self, call: MetaToolCall<'_>) -> Result<CallToolResult, MetaToolError> {
+        let resolved = caller_resolution(&call).await?;
+        let space_id = caller_space_id(&call).await?;
+
+        let tool_names: Vec<String> = match call.args.get("tools") {
+            Some(Value::String(s)) => vec![s.clone()],
+            Some(Value::Array(arr)) => arr
+                .iter()
+                .filter_map(|v| v.as_str().map(String::from))
+                .collect(),
+            _ => {
+                return Err(MetaToolError::InvalidArgument(
+                    "missing or invalid `tools` — expected string or string array".into(),
+                ));
+            }
+        };
+
+        if tool_names.is_empty() {
+            return Err(MetaToolError::InvalidArgument(
+                "`tools` must contain at least one qualified name".into(),
+            ));
+        }
+
+        let compact = call
+            .args
+            .get("compact")
+            .and_then(|v| v.as_bool())
+            .unwrap_or(false);
+
+        let invokable = call
+            .ctx
+            .feature_service
+            .get_invokable_tools_for_grants(
+                &space_id.to_string(),
+                &resolved.feature_set_ids,
+                call.session_id,
+            )
+            .await
+            .map_err(|e| MetaToolError::Internal(e.to_string()))?;
+
+        let index = call
+            .ctx
+            .tool_discovery
+            .build_index(&space_id.to_string(), &invokable)
+            .await
+            .map_err(|e| MetaToolError::Internal(e.to_string()))?;
+
+        let schemas = crate::services::tool_discovery::ToolDiscoveryService::get_schemas(
+            &index,
+            &tool_names,
+            compact,
+        );
+
+        Ok(text_result(json!({ "schemas": schemas })))
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Writes — each goes through the ApprovalBroker before mutating state.
 // ---------------------------------------------------------------------------
diff --git a/crates/mcpmux-gateway/src/services/mod.rs b/crates/mcpmux-gateway/src/services/mod.rs
index 387b6739..5b39ac09 100644
--- a/crates/mcpmux-gateway/src/services/mod.rs
+++ b/crates/mcpmux-gateway/src/services/mod.rs
@@ -16,6 +16,7 @@ mod prefix_cache;
 mod session_overrides;
 mod session_roots;
 mod space_resolver;
+pub mod tool_discovery;
 
 pub use authorization::AuthorizationService;
 pub use client_metadata_service::ClientMetadataService;
@@ -31,3 +32,4 @@ pub use prefix_cache::PrefixCacheService;
 pub use session_overrides::{SessionOverrideEntry, SessionOverrideRegistry};
 pub use session_roots::SessionRootsRegistry;
 pub use space_resolver::SpaceResolverService;
+pub use tool_discovery::{DetailLevel, ToolDiscoveryService, ToolIndexEntry};
diff --git a/crates/mcpmux-gateway/src/services/tool_discovery.rs b/crates/mcpmux-gateway/src/services/tool_discovery.rs
new file mode 100644
index 00000000..f99e37f8
--- /dev/null
+++ b/crates/mcpmux-gateway/src/services/tool_discovery.rs
@@ -0,0 +1,221 @@
+//! In-memory tool index for meta-gateway search and schema lookup.
+//!
+//! Built from Space [`ServerFeature`] rows and filtered to the caller's
+//! invokable tool set before search/schema operations run.
+
+use std::collections::HashSet;
+use std::sync::Arc;
+
+use anyhow::Result;
+use mcpmux_core::{FeatureType, ServerFeature, ServerFeatureRepository};
+use serde_json::{json, Value};
+
+/// How much detail search results include per matched tool.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum DetailLevel {
+    Name,
+    Description,
+    Schema,
+}
+
+impl DetailLevel {
+    /// Parse a wire-level detail level string.
+    pub fn parse(s: &str) -> Option<Self> {
+        match s {
+            "name" => Some(Self::Name),
+            "description" => Some(Self::Description),
+            "schema" => Some(Self::Schema),
+            _ => None,
+        }
+    }
+}
+
+/// One searchable tool entry in the Space index.
+#[derive(Debug, Clone)]
+pub struct ToolIndexEntry {
+    pub server_id: String,
+    pub feature_name: String,
+    pub qualified_name: String,
+    pub description: Option<String>,
+    pub input_schema: Option<Value>,
+    pub is_available: bool,
+}
+
+/// Paginated search output.
+#[derive(Debug, Clone)]
+pub struct SearchToolsResult {
+    pub tools: Vec<Value>,
+    pub next_cursor: Option<String>,
+    pub total: usize,
+}
+
+/// Service that builds and queries a tool index for a Space.
+pub struct ToolDiscoveryService {
+    server_feature_repo: Arc<dyn ServerFeatureRepository>,
+}
+
+impl ToolDiscoveryService {
+    /// Create a discovery service backed by the Space feature repository.
+    pub fn new(server_feature_repo: Arc<dyn ServerFeatureRepository>) -> Self {
+        Self {
+            server_feature_repo,
+        }
+    }
+
+    /// Build an index for `space_id`, retaining only tools present in `invokable`.
+    pub async fn build_index(
+        &self,
+        space_id: &str,
+        invokable: &[ServerFeature],
+    ) -> Result<Vec<ToolIndexEntry>> {
+        let invokable_keys: HashSet<(String, String)> = invokable
+            .iter()
+            .filter(|f| f.feature_type == FeatureType::Tool)
+            .map(|f| (f.server_id.clone(), f.feature_name.clone()))
+            .collect();
+
+        let features = self.server_feature_repo.list_for_space(space_id).await?;
+        let mut index: Vec<ToolIndexEntry> = features
+            .into_iter()
+            .filter(|f| {
+                f.feature_type == FeatureType::Tool
+                    && invokable_keys.contains(&(f.server_id.clone(), f.feature_name.clone()))
+            })
+            .map(|f| ToolIndexEntry {
+                server_id: f.server_id.clone(),
+                feature_name: f.feature_name.clone(),
+                qualified_name: f.qualified_name(),
+                description: f.description.clone(),
+                input_schema: extract_input_schema(f.raw_json.as_ref()),
+                is_available: f.is_available,
+            })
+            .collect();
+
+        index.sort_by(|a, b| a.qualified_name.cmp(&b.qualified_name));
+        Ok(index)
+    }
+
+    /// Search the index with optional query, server filter, and pagination.
+    pub fn search(
+        index: &[ToolIndexEntry],
+        query: Option<&str>,
+        server_id: Option<&str>,
+        detail_level: DetailLevel,
+        limit: usize,
+        cursor: Option<&str>,
+    ) -> SearchToolsResult {
+        let limit = limit.clamp(1, 100);
+        let offset = cursor.and_then(|c| c.parse::<usize>().ok()).unwrap_or(0);
+
+        let query_lower = query.map(|q| q.to_lowercase());
+        let filtered: Vec<&ToolIndexEntry> = index
+            .iter()
+            .filter(|entry| {
+                if let Some(sid) = server_id {
+                    if entry.server_id != sid {
+                        return false;
+                    }
+                }
+                if let Some(ref q) = query_lower {
+                    let haystack = format!(
+                        "{} {} {}",
+                        entry.qualified_name,
+                        entry.feature_name,
+                        entry.description.as_deref().unwrap_or("")
+                    )
+                    .to_lowercase();
+                    if !haystack.contains(q.as_str()) {
+                        return false;
+                    }
+                }
+                true
+            })
+            .collect();
+
+        let total = filtered.len();
+        let page: Vec<Value> = filtered
+            .iter()
+            .skip(offset)
+            .take(limit)
+            .map(|entry| entry_to_json(entry, detail_level))
+            .collect();
+
+        let next_offset = offset + page.len();
+        let next_cursor = if next_offset < total {
+            Some(next_offset.to_string())
+        } else {
+            None
+        };
+
+        SearchToolsResult {
+            tools: page,
+            next_cursor,
+            total,
+        }
+    }
+
+    /// Resolve schemas for one or more qualified tool names.
+    pub fn get_schemas(
+        index: &[ToolIndexEntry],
+        tool_names: &[String],
+        compact: bool,
+    ) -> Vec<Value> {
+        tool_names
+            .iter()
+            .filter_map(|name| {
+                let entry = index.iter().find(|e| e.qualified_name == *name)?;
+                Some(schema_entry_to_json(entry, compact))
+            })
+            .collect()
+    }
+}
+
+/// Extract MCP `inputSchema` from a cached tool JSON blob.
+fn extract_input_schema(raw_json: Option<&Value>) -> Option<Value> {
+    raw_json.and_then(|json| {
+        json.get("inputSchema")
+            .or_else(|| json.get("input_schema"))
+            .cloned()
+    })
+}
+
+fn entry_to_json(entry: &ToolIndexEntry, detail_level: DetailLevel) -> Value {
+    let mut obj = json!({
+        "server_id": entry.server_id,
+        "qualified_name": entry.qualified_name,
+        "available": entry.is_available,
+    });
+    match detail_level {
+        DetailLevel::Name => {}
+        DetailLevel::Description | DetailLevel::Schema => {
+            if let Some(desc) = &entry.description {
+                obj["description"] = json!(desc);
+            }
+        }
+    }
+    if detail_level == DetailLevel::Schema {
+        if let Some(schema) = &entry.input_schema {
+            obj["input_schema"] = schema.clone();
+        }
+    }
+    obj
+}
+
+fn schema_entry_to_json(entry: &ToolIndexEntry, compact: bool) -> Value {
+    let mut obj = json!({
+        "qualified_name": entry.qualified_name,
+        "server_id": entry.server_id,
+        "feature_name": entry.feature_name,
+    });
+    if !compact {
+        if let Some(desc) = &entry.description {
+            obj["description"] = json!(desc);
+        }
+    }
+    if let Some(schema) = &entry.input_schema {
+        obj["input_schema"] = schema.clone();
+    } else {
+        obj["input_schema"] = json!({"type": "object", "properties": {}});
+    }
+    obj
+}
diff --git a/tests/rust/tests/integration/meta_gateway_invoke.rs b/tests/rust/tests/integration/meta_gateway_invoke.rs
new file mode 100644
index 00000000..9b99b03d
--- /dev/null
+++ b/tests/rust/tests/integration/meta_gateway_invoke.rs
@@ -0,0 +1,315 @@
+//! Integration tests for meta-gateway invoke (search → schema → invoke).
+
+use std::sync::Arc;
+use std::time::Duration;
+
+use mcpmux_core::{
+    Client, DomainEvent, FeatureSet, FeatureSetMember, FeatureSetRepository,
+    InboundMcpClientRepository, InstalledServerRepository, MemberMode, MemberType, ServerFeature,
+    ServerFeatureRepository, SpaceRepository, WorkspaceBindingRepository,
+};
+use mcpmux_gateway::pool::{format_direct_call_redirect, FeatureService};
+use mcpmux_gateway::services::{
+    meta_tools, ApprovalBroker, FeatureSetResolverService, MetaToolRegistry, PrefixCacheService,
+    SessionOverrideRegistry, SessionRootsRegistry,
+};
+use mcpmux_storage::{
+    generate_master_key, Database, FieldEncryptor, InboundClientRepository,
+    SqliteFeatureSetRepository, SqliteInboundMcpClientRepository, SqliteInstalledServerRepository,
+    SqliteServerFeatureRepository, SqliteSpaceRepository, SqliteWorkspaceBindingRepository,
+};
+use serde_json::{json, Value};
+use tokio::sync::{broadcast, Mutex};
+use uuid::Uuid;
+
+struct Fixture {
+    registry: Arc<MetaToolRegistry>,
+    feature_service: Arc<FeatureService>,
+    session_overrides: Arc<SessionOverrideRegistry>,
+    server_feature_repo: Arc<dyn ServerFeatureRepository>,
+    feature_set_repo: Arc<dyn FeatureSetRepository>,
+    space_id: Uuid,
+    client_id: String,
+    session_id: String,
+}
+
+fn test_encryptor() -> Arc<FieldEncryptor> {
+    let key = generate_master_key().expect("generate key");
+    Arc::new(FieldEncryptor::new(&key).expect("create encryptor"))
+}
+
+impl Fixture {
+    async fn new() -> Self {
+        let db = Arc::new(Mutex::new(Database::open_in_memory().unwrap()));
+
+        let space_repo: Arc<dyn SpaceRepository> = Arc::new(SqliteSpaceRepository::new(db.clone()));
+        let feature_set_repo: Arc<dyn FeatureSetRepository> =
+            Arc::new(SqliteFeatureSetRepository::new(db.clone()));
+        let client_repo: Arc<dyn InboundMcpClientRepository> =
+            Arc::new(SqliteInboundMcpClientRepository::new(db.clone()));
+        let binding_repo: Arc<dyn WorkspaceBindingRepository> =
+            Arc::new(SqliteWorkspaceBindingRepository::new(db.clone()));
+        let server_feature_repo: Arc<dyn ServerFeatureRepository> =
+            Arc::new(SqliteServerFeatureRepository::new(db.clone()));
+        let installed_server_repo: Arc<dyn InstalledServerRepository> = Arc::new(
+            SqliteInstalledServerRepository::new(db.clone(), test_encryptor()),
+        );
+
+        let default_space = space_repo.get_default().await.unwrap().unwrap();
+        let space_id = default_space.id;
+
+        let client = Client::new("InvokeTestClient", "test-type");
+        let client_id = client.id.to_string();
+        client_repo.create(&client).await.unwrap();
+
+        let mut list_issues = ServerFeature::tool(space_id, "github", "list_issues");
+        list_issues.description = Some("List issues in a repository".into());
+        list_issues.raw_json = Some(json!({
+            "name": "list_issues",
+            "description": "List issues in a repository",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    "owner": { "type": "string" },
+                    "repo": { "type": "string" }
+                },
+                "required": ["owner", "repo"]
+            }
+        }));
+        server_feature_repo.upsert(&list_issues).await.unwrap();
+
+        let mut grant_all = FeatureSet::new_custom("Grant GitHub", space_id.to_string());
+        grant_all.members.push(FeatureSetMember {
+            id: Uuid::new_v4().to_string(),
+            feature_set_id: grant_all.id.clone(),
+            member_type: MemberType::Feature,
+            member_id: list_issues.id.to_string(),
+            mode: MemberMode::Include,
+        });
+        feature_set_repo.create(&grant_all).await.unwrap();
+
+        let session_roots = SessionRootsRegistry::new();
+        let session_overrides = SessionOverrideRegistry::new();
+        let session_id = "sess-invoke".to_string();
+
+        let inbound_client_repo = Arc::new(InboundClientRepository::new(db.clone()));
+        let resolver = Arc::new(FeatureSetResolverService::new(
+            space_repo.clone(),
+            binding_repo.clone(),
+            session_roots.clone(),
+            inbound_client_repo.clone(),
+        ));
+
+        let prefix_cache = Arc::new(PrefixCacheService::new());
+        let feature_service = Arc::new(FeatureService::new(
+            server_feature_repo.clone(),
+            feature_set_repo.clone(),
+            prefix_cache,
+            session_overrides.clone(),
+        ));
+
+        let broker = Arc::new(ApprovalBroker::new().with_timeout(Duration::from_millis(500)));
+        let (tx, _event_rx) = broadcast::channel::<DomainEvent>(32);
+
+        let registry = meta_tools::build_default_registry(
+            client_repo,
+            space_repo,
+            feature_set_repo.clone(),
+            binding_repo,
+            server_feature_repo.clone(),
+            installed_server_repo,
+            resolver,
+            feature_service.clone(),
+            None,
+            session_roots,
+            session_overrides.clone(),
+            broker,
+            tx,
+            None,
+        );
+
+        Self {
+            registry,
+            feature_service,
+            session_overrides,
+            server_feature_repo,
+            feature_set_repo,
+            space_id,
+            client_id,
+            session_id,
+        }
+    }
+
+    fn result_json(result: &rmcp::model::CallToolResult) -> Value {
+        let raw = serde_json::to_value(result).unwrap();
+        raw.get("content")
+            .and_then(|c| c.as_array())
+            .and_then(|arr| arr.first())
+            .and_then(|v| v.get("text"))
+            .and_then(|t| t.as_str())
+            .and_then(|s| serde_json::from_str::<Value>(s).ok())
+            .unwrap_or(raw)
+    }
+
+    async fn call(&self, name: &str, args: Value) -> rmcp::model::CallToolResult {
+        match self
+            .registry
+            .call(name, &self.client_id, Some(&self.session_id), args)
+            .await
+        {
+            Ok(r) => r,
+            Err(e) => e.into_call_tool_result(),
+        }
+    }
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn advertised_tools_empty_while_invokable_has_backend_tools() {
+    let f = Fixture::new().await;
+    let fs_ids = vec![
+        f.feature_set_repo
+            .list_by_space(&f.space_id.to_string())
+            .await
+            .unwrap()
+            .into_iter()
+            .find(|fs| fs.name == "Grant GitHub")
+            .unwrap()
+            .id,
+    ];
+
+    let advertised = f
+        .feature_service
+        .get_advertised_tools_for_grants(&f.space_id.to_string(), &fs_ids, Some(&f.session_id))
+        .await
+        .unwrap();
+    assert!(advertised.is_empty(), "Phase A: no surfaced tools yet");
+
+    f.session_overrides.enable(&f.session_id, "github");
+    let invokable = f
+        .feature_service
+        .get_invokable_tools_for_grants(&f.space_id.to_string(), &fs_ids, Some(&f.session_id))
+        .await
+        .unwrap();
+    assert_eq!(invokable.len(), 1);
+    assert_eq!(invokable[0].feature_name, "list_issues");
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn github_read_path_enable_search_schema() {
+    let f = Fixture::new().await;
+
+    let servers = f.call("mcpmux_list_servers", json!({})).await;
+    let body = Fixture::result_json(&servers);
+    let github = body
+        .get("servers")
+        .and_then(|s| s.as_array())
+        .and_then(|arr| arr.iter().find(|s| s.get("id") == Some(&json!("github"))))
+        .expect("github server listed");
+    assert_eq!(github.get("status"), Some(&json!("inactive")));
+
+    f.session_overrides.enable(&f.session_id, "github");
+
+    let search = f
+        .call(
+            "mcpmux_search_tools",
+            json!({
+                "query": "list issues",
+                "server_id": "github",
+                "detail_level": "description"
+            }),
+        )
+        .await;
+    let search_body = Fixture::result_json(&search);
+    let tools = search_body.get("tools").unwrap().as_array().unwrap();
+    assert_eq!(tools.len(), 1);
+    assert_eq!(
+        tools[0].get("qualified_name"),
+        Some(&json!("github_list_issues"))
+    );
+
+    let schema = f
+        .call(
+            "mcpmux_get_tool_schema",
+            json!({ "tools": "github_list_issues" }),
+        )
+        .await;
+    let schema_body = Fixture::result_json(&schema);
+    let schemas = schema_body.get("schemas").unwrap().as_array().unwrap();
+    assert_eq!(schemas.len(), 1);
+    assert!(schemas[0].get("input_schema").is_some());
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn invoke_denied_when_server_inactive() {
+    let f = Fixture::new().await;
+    let result = f
+        .call(
+            "mcpmux_invoke_tool",
+            json!({
+                "server_id": "github",
+                "tool": "list_issues",
+                "args": { "owner": "mcpmux", "repo": "mcp-mux" }
+            }),
+        )
+        .await;
+    assert!(result.is_error.unwrap_or(false));
+    let body = Fixture::result_json(&result);
+    let message = body.get("message").and_then(|m| m.as_str()).unwrap_or("");
+    assert!(message.contains("inactive"));
+    assert!(message.contains("mcpmux_enable_server"));
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn search_empty_when_server_inactive() {
+    let f = Fixture::new().await;
+    let search = f
+        .call(
+            "mcpmux_search_tools",
+            json!({ "query": "list", "server_id": "github" }),
+        )
+        .await;
+    let body = Fixture::result_json(&search);
+    assert_eq!(body.get("total"), Some(&json!(0)));
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn list_all_tools_filters_by_server_id() {
+    let f = Fixture::new().await;
+
+    let other = ServerFeature::tool(f.space_id, "firebase", "deploy");
+    f.server_feature_repo.upsert(&other).await.unwrap();
+
+    let all = f.call("mcpmux_list_all_tools", json!({})).await;
+    let all_body = Fixture::result_json(&all);
+    assert_eq!(all_body.get("tools").unwrap().as_array().unwrap().len(), 2);
+
+    let filtered = f
+        .call("mcpmux_list_all_tools", json!({ "server_id": "github" }))
+        .await;
+    let filtered_body = Fixture::result_json(&filtered);
+    let tools = filtered_body.get("tools").unwrap().as_array().unwrap();
+    assert_eq!(tools.len(), 1);
+    assert_eq!(tools[0].get("server_id"), Some(&json!("github")));
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn direct_backend_call_redirect_message() {
+    let msg = format_direct_call_redirect("github_list_issues", "github", "list_issues");
+    assert!(msg.contains("mcpmux_invoke_tool"));
+    assert!(msg.contains("github"));
+    assert!(msg.contains("list_issues"));
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn registry_lists_new_meta_tools() {
+    let f = Fixture::new().await;
+    let names: Vec<String> = f
+        .registry
+        .list_as_tools()
+        .into_iter()
+        .map(|t| t.name.to_string())
+        .collect();
+    assert!(names.iter().any(|n| n == "mcpmux_search_tools"));
+    assert!(names.iter().any(|n| n == "mcpmux_get_tool_schema"));
+    assert!(names.iter().any(|n| n == "mcpmux_invoke_tool"));
+}
diff --git a/tests/rust/tests/integration/meta_tools.rs b/tests/rust/tests/integration/meta_tools.rs
index f75c23b4..bd980826 100644
--- a/tests/rust/tests/integration/meta_tools.rs
+++ b/tests/rust/tests/integration/meta_tools.rs
@@ -140,6 +140,7 @@ impl Fixture {
             installed_server_repo.clone(),
             resolver,
             feature_service.clone(),
+            None,
             session_roots.clone(),
             session_overrides.clone(),
             broker.clone(),
@@ -876,6 +877,7 @@ async fn bare_registry(
         installed_server_repo,
         resolver,
         feature_service,
+        None,
         SessionRootsRegistry::new(),
         SessionOverrideRegistry::new(),
         Arc::new(ApprovalBroker::new()),
@@ -994,6 +996,7 @@ async fn master_switch_toggles_registry_visibility() {
         installed_server_repo,
         resolver,
         feature_service,
+        None,
         SessionRootsRegistry::new(),
         SessionOverrideRegistry::new(),
         Arc::new(ApprovalBroker::new()),
diff --git a/tests/rust/tests/integration/mod.rs b/tests/rust/tests/integration/mod.rs
index 15e23754..eaf1640a 100644
--- a/tests/rust/tests/integration/mod.rs
+++ b/tests/rust/tests/integration/mod.rs
@@ -11,6 +11,7 @@
 mod feature_routing;
 mod feature_set_resolver;
 mod mcp_flows;
+mod meta_gateway_invoke;
 mod meta_tools;
 mod server_clone;
 mod workspace_binding_events;

From 4d11112dcf5e7c91ccfc81b96e4416fc9ef48aac Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 12:16:43 -0600
Subject: [PATCH 34/48] =?UTF-8?q?feat(gateway):=20Phase=20B=20=E2=80=94=20?=
 =?UTF-8?q?Result=20shaping=20on=20invoke?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Autonomous decisions:
- DEFAULT_MAX_ROWS=50 and DEFAULT_MAX_BYTES=65536 — balances context savings with usable samples for smart default truncation
- pub mod invoke — external integration tests need public access to shaping helpers
- Hoist returned/total/truncated to parent object for nested list keys — keeps truncation metadata visible without extra nesting

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 .../src/services/meta_tools/invoke.rs         | 359 +++++++++++++++++-
 .../src/services/meta_tools/mod.rs            |   2 +-
 .../tests/integration/meta_gateway_invoke.rs  |  64 ++++
 3 files changed, 414 insertions(+), 11 deletions(-)

diff --git a/crates/mcpmux-gateway/src/services/meta_tools/invoke.rs b/crates/mcpmux-gateway/src/services/meta_tools/invoke.rs
index 9ca32aef..9365f584 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/invoke.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/invoke.rs
@@ -2,7 +2,7 @@
 
 use async_trait::async_trait;
 use rmcp::model::{CallToolResult, Content};
-use serde_json::{json, Value};
+use serde_json::{json, Map, Value};
 
 use super::registry::{MetaTool, MetaToolCall, MetaToolError};
 use super::tools::{caller_resolution, caller_space_id};
@@ -10,6 +10,88 @@ use crate::pool::{format_invoke_permission_denied, format_server_inactive_error}
 use crate::services::tool_discovery::ToolDiscoveryService;
 use mcpmux_core::FeatureType;
 
+/// Default row cap for smart truncation when `filter` is omitted.
+pub const DEFAULT_MAX_ROWS: usize = 50;
+
+/// Default byte cap for smart truncation when `filter` is omitted.
+pub const DEFAULT_MAX_BYTES: usize = 65_536;
+
+/// Object keys that commonly hold large list payloads from backend tools.
+const HEAVY_ARRAY_KEYS: &[&str] = &[
+    "items", "data", "results", "rows", "records", "issues", "entries", "values", "list",
+];
+
+/// Optional post-processing controls for invoke results.
+#[derive(Debug, Clone, Default, PartialEq, Eq)]
+pub struct InvokeResultFilter {
+    pub max_rows: Option<usize>,
+    pub max_bytes: Option<usize>,
+    pub fields: Option<Vec<String>>,
+    pub format: Option<String>,
+}
+
+/// Parse the optional `filter` object from `mcpmux_invoke_tool` arguments.
+pub fn parse_invoke_filter(value: Option<&Value>) -> Option<InvokeResultFilter> {
+    let filter = value?;
+    if !filter.is_object() {
+        return None;
+    }
+
+    Some(InvokeResultFilter {
+        max_rows: filter
+            .get("max_rows")
+            .and_then(|v| v.as_u64())
+            .map(|n| n as usize),
+        max_bytes: filter
+            .get("max_bytes")
+            .and_then(|v| v.as_u64())
+            .map(|n| n as usize),
+        fields: filter.get("fields").and_then(|v| {
+            v.as_array().map(|arr| {
+                arr.iter()
+                    .filter_map(|item| item.as_str().map(str::to_string))
+                    .collect()
+            })
+        }),
+        format: filter
+            .get("format")
+            .and_then(|v| v.as_str())
+            .map(str::to_string),
+    })
+}
+
+impl InvokeResultFilter {
+    fn effective_max_rows(&self, use_defaults: bool) -> Option<usize> {
+        self.max_rows
+            .or_else(|| use_defaults.then_some(DEFAULT_MAX_ROWS))
+    }
+
+    fn effective_max_bytes(&self, use_defaults: bool) -> Option<usize> {
+        self.max_bytes
+            .or_else(|| use_defaults.then_some(DEFAULT_MAX_BYTES))
+    }
+
+    fn is_summary(&self) -> bool {
+        self.format.as_deref() == Some("summary")
+    }
+}
+
+/// Post-process routed tool output before returning it to the MCP client.
+pub fn apply_invoke_result_filter(
+    content: Vec<Value>,
+    structured_content: Option<Value>,
+    filter: Option<&InvokeResultFilter>,
+    use_defaults: bool,
+) -> (Vec<Value>, Option<Value>) {
+    let filter = filter.cloned().unwrap_or_default();
+    let shaped_structured = structured_content.map(|value| shape_json_value(value, &filter, use_defaults));
+    let shaped_content = content
+        .into_iter()
+        .map(|block| shape_content_block(block, &filter, use_defaults))
+        .collect();
+    (shaped_content, shaped_structured)
+}
+
 /// Meta tool that forwards invocations to [`RoutingService::call_tool`].
 pub struct InvokeToolTool;
 
@@ -23,7 +105,8 @@ impl MetaTool for InvokeToolTool {
         "Invoke a backend MCP tool by server_id and tool name. Requires the \
          server to be active (binding or session enable) and the tool to be \
          in the current permission set. Use mcpmux_search_tools and \
-         mcpmux_get_tool_schema before calling."
+         mcpmux_get_tool_schema before calling. Large list payloads are \
+         truncated by default; pass an optional filter object to control shaping."
     }
 
     fn input_schema(&self) -> Value {
@@ -43,6 +126,32 @@ impl MetaTool for InvokeToolTool {
                     "type": "object",
                     "description": "Arguments object passed to the backend tool",
                     "default": {}
+                },
+                "filter": {
+                    "type": "object",
+                    "description": "Optional result shaping. When omitted, large arrays are truncated with returned/total/truncated metadata.",
+                    "properties": {
+                        "max_rows": {
+                            "type": "integer",
+                            "minimum": 1,
+                            "description": "Maximum rows/items to return from large arrays"
+                        },
+                        "max_bytes": {
+                            "type": "integer",
+                            "minimum": 1,
+                            "description": "Maximum UTF-8 bytes for text or serialized JSON payloads"
+                        },
+                        "fields": {
+                            "type": "array",
+                            "items": { "type": "string" },
+                            "description": "When set, keep only these fields on each object in list results"
+                        },
+                        "format": {
+                            "type": "string",
+                            "enum": ["summary", "full"],
+                            "description": "summary keeps metadata plus a bounded sample; full returns truncated rows"
+                        }
+                    }
                 }
             }
         })
@@ -66,6 +175,8 @@ impl MetaTool for InvokeToolTool {
             .ok_or_else(|| MetaToolError::InvalidArgument("missing `tool`".into()))?
             .to_string();
         let args = call.args.get("args").cloned().unwrap_or_else(|| json!({}));
+        let filter = parse_invoke_filter(call.args.get("filter"));
+        let use_defaults = call.args.get("filter").is_none();
 
         let resolved = caller_resolution(&call).await?;
         let space_id = caller_space_id(&call).await?;
@@ -170,17 +281,29 @@ impl MetaTool for InvokeToolTool {
             .await
         {
             Ok(result) => {
-                let content: Vec<Content> = result
-                    .content
+                if result.is_error {
+                    let content: Vec<Content> = result
+                        .content
+                        .into_iter()
+                        .filter_map(|v| serde_json::from_value(v).ok())
+                        .collect();
+                    let mut mcp_result = CallToolResult::error(content);
+                    mcp_result.structured_content = result.structured_content;
+                    return Ok(mcp_result);
+                }
+
+                let (content, structured_content) = apply_invoke_result_filter(
+                    result.content,
+                    result.structured_content,
+                    filter.as_ref(),
+                    use_defaults,
+                );
+                let parsed_content: Vec<Content> = content
                     .into_iter()
                     .filter_map(|v| serde_json::from_value(v).ok())
                     .collect();
-                let mut mcp_result = if result.is_error {
-                    CallToolResult::error(content)
-                } else {
-                    CallToolResult::success(content)
-                };
-                mcp_result.structured_content = result.structured_content;
+                let mut mcp_result = CallToolResult::success(parsed_content);
+                mcp_result.structured_content = structured_content;
                 Ok(mcp_result)
             }
             Err(e) => Ok(invoke_error(e.to_string())),
@@ -188,6 +311,179 @@ impl MetaTool for InvokeToolTool {
     }
 }
 
+/// Shape one MCP content block (typically `{ "type": "text", "text": "..." }`).
+fn shape_content_block(block: Value, filter: &InvokeResultFilter, use_defaults: bool) -> Value {
+    let Some(text) = block.get("text").and_then(|v| v.as_str()) else {
+        return block;
+    };
+
+    if let Ok(parsed) = serde_json::from_str::<Value>(text) {
+        let shaped = shape_json_value(parsed, filter, use_defaults);
+        return json!({
+            "type": "text",
+            "text": shaped.to_string(),
+        });
+    }
+
+    let max_bytes = filter.effective_max_bytes(use_defaults);
+    let Some(max_bytes) = max_bytes else {
+        return block;
+    };
+    if text.len() <= max_bytes {
+        return block;
+    }
+
+    let mut truncated = text[..max_bytes].to_string();
+    truncated.push_str("\n...[truncated]");
+    json!({
+        "type": "text",
+        "text": truncated,
+    })
+}
+
+/// Shape a JSON value, applying smart truncation for large arrays when enabled.
+pub fn shape_json_value(value: Value, filter: &InvokeResultFilter, use_defaults: bool) -> Value {
+    match value {
+        Value::Array(items) => shape_array(items, filter, use_defaults, "items"),
+        Value::Object(map) => shape_object(map, filter, use_defaults),
+        other => enforce_byte_limit(other, filter, use_defaults),
+    }
+}
+
+fn shape_object(map: Map<String, Value>, filter: &InvokeResultFilter, use_defaults: bool) -> Value {
+    for key in HEAVY_ARRAY_KEYS {
+        if let Some(Value::Array(items)) = map.get(*key).cloned() {
+            if should_truncate(items.len(), filter, use_defaults) {
+                return shape_object_with_truncated_array(map, key, items, filter, use_defaults);
+            }
+        }
+    }
+
+    for (key, value) in &map {
+        if let Value::Array(items) = value {
+            if should_truncate(items.len(), filter, use_defaults) {
+                return shape_object_with_truncated_array(map.clone(), key, items.clone(), filter, use_defaults);
+            }
+        }
+    }
+
+    enforce_byte_limit(Value::Object(map), filter, use_defaults)
+}
+
+fn shape_object_with_truncated_array(
+    mut map: Map<String, Value>,
+    array_key: &str,
+    items: Vec<Value>,
+    filter: &InvokeResultFilter,
+    use_defaults: bool,
+) -> Value {
+    let shaped_array = shape_array(items, filter, use_defaults, array_key);
+    if let Value::Object(truncation) = &shaped_array {
+        if truncation.get("truncated") == Some(&Value::Bool(true)) {
+            for (meta_key, meta_value) in truncation {
+                if meta_key != array_key {
+                    map.insert(meta_key.clone(), meta_value.clone());
+                }
+            }
+            if let Some(data) = truncation.get(array_key) {
+                map.insert(array_key.to_string(), data.clone());
+            }
+            return enforce_byte_limit(Value::Object(map), filter, use_defaults);
+        }
+    }
+
+    map.insert(array_key.to_string(), shaped_array);
+    enforce_byte_limit(Value::Object(map), filter, use_defaults)
+}
+
+fn shape_array(
+    items: Vec<Value>,
+    filter: &InvokeResultFilter,
+    use_defaults: bool,
+    data_key: &str,
+) -> Value {
+    let total = items.len();
+    let filtered_items = apply_fields_filter(items, filter);
+    let max_rows = filter.effective_max_rows(use_defaults);
+
+    let Some(max_rows) = max_rows else {
+        return Value::Array(filtered_items);
+    };
+
+    if total <= max_rows {
+        return Value::Array(filtered_items);
+    }
+
+    let sample_size = if filter.is_summary() {
+        max_rows.min(5)
+    } else {
+        max_rows
+    };
+    let sample: Vec<Value> = filtered_items.into_iter().take(sample_size).collect();
+    let returned = sample.len();
+
+    json!({
+        "returned": returned,
+        "total": total,
+        "truncated": true,
+        data_key: sample,
+    })
+}
+
+fn apply_fields_filter(items: Vec<Value>, filter: &InvokeResultFilter) -> Vec<Value> {
+    let Some(fields) = &filter.fields else {
+        return items;
+    };
+
+    items
+        .into_iter()
+        .map(|item| pick_fields(item, fields))
+        .collect()
+}
+
+fn pick_fields(value: Value, fields: &[String]) -> Value {
+    let Value::Object(map) = value else {
+        return value;
+    };
+
+    let mut picked = Map::new();
+    for field in fields {
+        if let Some(v) = map.get(field) {
+            picked.insert(field.clone(), v.clone());
+        }
+    }
+    Value::Object(picked)
+}
+
+fn should_truncate(length: usize, filter: &InvokeResultFilter, use_defaults: bool) -> bool {
+    match filter.effective_max_rows(use_defaults) {
+        Some(max_rows) => length > max_rows,
+        None => false,
+    }
+}
+
+fn enforce_byte_limit(value: Value, filter: &InvokeResultFilter, use_defaults: bool) -> Value {
+    let Some(max_bytes) = filter.effective_max_bytes(use_defaults) else {
+        return value;
+    };
+
+    let serialized = value.to_string();
+    if serialized.len() <= max_bytes {
+        return value;
+    }
+
+    let total_bytes = serialized.len();
+    let mut truncated = serialized;
+    truncated.truncate(max_bytes);
+    truncated.push_str("...[truncated]");
+    json!({
+        "returned": truncated.len(),
+        "total": total_bytes,
+        "truncated": true,
+        "text": truncated,
+    })
+}
+
 /// Build a structured MCP error payload for invoke failures.
 fn invoke_error(message: String) -> CallToolResult {
     let payload = json!({
@@ -196,3 +492,46 @@ fn invoke_error(message: String) -> CallToolResult {
     });
     CallToolResult::error(vec![Content::text(payload.to_string())])
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn default_truncates_large_top_level_array() {
+        let items: Vec<Value> = (0..100).map(|i| json!({ "id": i, "name": format!("n{i}") })).collect();
+        let shaped = shape_json_value(Value::Array(items), &InvokeResultFilter::default(), true);
+        assert_eq!(shaped.get("returned"), Some(&json!(50)));
+        assert_eq!(shaped.get("total"), Some(&json!(100)));
+        assert_eq!(shaped.get("truncated"), Some(&json!(true)));
+    }
+
+    #[test]
+    fn explicit_max_rows_overrides_default() {
+        let items: Vec<Value> = (0..20).map(|i| json!({ "id": i })).collect();
+        let filter = InvokeResultFilter {
+            max_rows: Some(3),
+            ..Default::default()
+        };
+        let shaped = shape_json_value(Value::Array(items), &filter, false);
+        assert_eq!(shaped.get("returned"), Some(&json!(3)));
+        assert_eq!(shaped.get("total"), Some(&json!(20)));
+        assert_eq!(shaped.get("truncated"), Some(&json!(true)));
+    }
+
+    #[test]
+    fn fields_filter_keeps_only_requested_columns() {
+        let items = vec![
+            json!({ "id": 1, "name": "a", "secret": "x" }),
+            json!({ "id": 2, "name": "b", "secret": "y" }),
+        ];
+        let filter = InvokeResultFilter {
+            fields: Some(vec!["id".into(), "name".into()]),
+            ..Default::default()
+        };
+        let shaped = shape_json_value(Value::Array(items), &filter, false);
+        let kept = shaped.as_array().unwrap();
+        assert_eq!(kept[0], json!({ "id": 1, "name": "a" }));
+        assert_eq!(kept[1], json!({ "id": 2, "name": "b" }));
+    }
+}
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/mod.rs b/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
index f0bf984f..b0becf7c 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
@@ -22,7 +22,7 @@
 
 pub mod approval;
 pub mod diff;
-mod invoke;
+pub mod invoke;
 mod registry;
 mod tools;
 mod workspace_server;
diff --git a/tests/rust/tests/integration/meta_gateway_invoke.rs b/tests/rust/tests/integration/meta_gateway_invoke.rs
index 9b99b03d..f5778c88 100644
--- a/tests/rust/tests/integration/meta_gateway_invoke.rs
+++ b/tests/rust/tests/integration/meta_gateway_invoke.rs
@@ -9,6 +9,10 @@ use mcpmux_core::{
     ServerFeatureRepository, SpaceRepository, WorkspaceBindingRepository,
 };
 use mcpmux_gateway::pool::{format_direct_call_redirect, FeatureService};
+use mcpmux_gateway::services::meta_tools::invoke::{
+    apply_invoke_result_filter, parse_invoke_filter, shape_json_value, InvokeResultFilter,
+    DEFAULT_MAX_ROWS,
+};
 use mcpmux_gateway::services::{
     meta_tools, ApprovalBroker, FeatureSetResolverService, MetaToolRegistry, PrefixCacheService,
     SessionOverrideRegistry, SessionRootsRegistry,
@@ -313,3 +317,63 @@ async fn registry_lists_new_meta_tools() {
     assert!(names.iter().any(|n| n == "mcpmux_get_tool_schema"));
     assert!(names.iter().any(|n| n == "mcpmux_invoke_tool"));
 }
+
+#[tokio::test(flavor = "multi_thread")]
+async fn invoke_input_schema_includes_filter() {
+    let f = Fixture::new().await;
+    let invoke = f
+        .registry
+        .list_as_tools()
+        .into_iter()
+        .find(|t| t.name.as_ref() == "mcpmux_invoke_tool")
+        .expect("invoke tool registered");
+    let schema = invoke.input_schema;
+    assert!(schema.get("properties").and_then(|p| p.get("filter")).is_some());
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn invoke_result_default_truncates_large_list() {
+    let items: Vec<Value> = (0..100).map(|i| json!({ "id": i })).collect();
+    let payload = json!({ "items": items });
+
+    let shaped = shape_json_value(payload, &InvokeResultFilter::default(), true);
+
+    assert_eq!(shaped.get("returned"), Some(&json!(DEFAULT_MAX_ROWS)));
+    assert_eq!(shaped.get("total"), Some(&json!(100)));
+    assert_eq!(shaped.get("truncated"), Some(&json!(true)));
+    let truncated_items = shaped.get("items").and_then(|v| v.as_array()).unwrap();
+    assert_eq!(truncated_items.len(), DEFAULT_MAX_ROWS);
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn invoke_result_explicit_filter_limits_rows() {
+    let items: Vec<Value> = (0..30).map(|i| json!({ "id": i, "label": format!("row-{i}") })).collect();
+    let filter = parse_invoke_filter(Some(&json!({ "max_rows": 5, "fields": ["id"] }))).unwrap();
+
+    let shaped = shape_json_value(Value::Array(items), &filter, false);
+
+    assert_eq!(shaped.get("returned"), Some(&json!(5)));
+    assert_eq!(shaped.get("total"), Some(&json!(30)));
+    assert_eq!(shaped.get("truncated"), Some(&json!(true)));
+    let sample = shaped.get("items").and_then(|v| v.as_array()).unwrap();
+    assert_eq!(sample.len(), 5);
+    assert_eq!(sample[0], json!({ "id": 0 }));
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn invoke_result_filter_shapes_text_content_blocks() {
+    let rows: Vec<Value> = (0..80).map(|i| json!({ "n": i })).collect();
+    let content = vec![json!({
+        "type": "text",
+        "text": json!({ "results": rows }).to_string(),
+    })];
+    let filter = parse_invoke_filter(Some(&json!({ "max_rows": 10 }))).unwrap();
+
+    let (shaped_content, _) = apply_invoke_result_filter(content, None, Some(&filter), false);
+    let text = shaped_content[0].get("text").and_then(|t| t.as_str()).unwrap();
+    let parsed: Value = serde_json::from_str(text).unwrap();
+
+    assert_eq!(parsed.get("returned"), Some(&json!(10)));
+    assert_eq!(parsed.get("total"), Some(&json!(80)));
+    assert_eq!(parsed.get("truncated"), Some(&json!(true)));
+}

From 270921d64c740a4932fa6dacd4a66b3c4833d4a9 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 12:20:13 -0600
Subject: [PATCH 35/48] =?UTF-8?q?feat(gateway):=20Phase=20C=20=E2=80=94=20?=
 =?UTF-8?q?FeatureSet=20invoke=20ACL=20+=20surfaced=20tools?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Autonomous decisions:
- Keep session-enable all-tools expansion only when no FeatureSet is bound — preserves Phase A bootstrap path while member filter is authoritative once bound
- Add migration 019 surfaced column on feature_set_members — matches existing ALTER TABLE pattern, default 0
- Surface toggle UI only on selected tools in FeatureSetPanel — surfaced without include is meaningless

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 README.md                                     |  21 +--
 .../src-tauri/src/commands/feature_set.rs     |   5 +
 .../features/featuresets/FeatureSetPanel.tsx  | 114 +++++++++++-----
 .../src/features/settings/SettingsPage.tsx    |  13 +-
 apps/desktop/src/lib/api/featureSets.ts       |   2 +
 crates/mcpmux-core/src/domain/feature_set.rs  |   6 +
 .../src/pool/features/facade.rs               |  35 +++--
 .../src/pool/features/resolution.rs           |  42 ++++++
 .../src/services/meta_tools/tools.rs          |  36 +++++-
 crates/mcpmux-storage/src/database.rs         |   5 +
 .../019_feature_set_member_surfaced.sql       |   2 +
 .../repositories/feature_set_repository.rs    |  23 ++--
 tests/rust/src/mocks.rs                       |   1 +
 tests/rust/tests/integration/mcp_flows.rs     |   4 +
 .../tests/integration/meta_gateway_invoke.rs  | 122 +++++++++++++++++-
 tests/rust/tests/integration/meta_tools.rs    |   1 +
 16 files changed, 360 insertions(+), 72 deletions(-)
 create mode 100644 crates/mcpmux-storage/src/migrations/019_feature_set_member_surfaced.sql

diff --git a/README.md b/README.md
index ba825bdf..025a29a0 100644
--- a/README.md
+++ b/README.md
@@ -77,7 +77,7 @@ Lightweight and cross-platform — built in Rust with Tauri 2, McpMux uses minim
 }
 ```
 
-**3.** Done. Every tool from every server is available in every client, right now.
+**3.** Done. Connected clients see a small fixed meta-tool surface (~12 `mcpmux_*` tools). Backend tools are discovered via **`mcpmux_search_tools`** → **`mcpmux_get_tool_schema`** → **`mcpmux_invoke_tool`**, keeping context windows lean. Optionally surface individual hot-path tools into `tools/list` per FeatureSet.
 
 McpMux routes calls to the right server, refreshes OAuth tokens automatically, and keeps credentials encrypted in your OS keychain — you never think about it again.
 
@@ -109,28 +109,33 @@ Create isolated Spaces — each with their own servers, credentials, and permiss
 
 ### Control What Each Client Can Do
 
-Not every AI client should have the same power. Create Feature Sets — permission bundles that control exactly which tools, prompts, and resources a client can access. Build a "Read Only" set for cautious workflows, a "React Development" set with just GitHub and Filesystem, or a "Full Stack Dev" set with everything. Assign them per-client so each tool only goes where you want it.
+Not every AI client should have the same power. Create Feature Sets — permission bundles that control exactly which tools a client can **invoke** (search + invoke ACL), plus optional per-tool **Surface in client** promotion for one-hop hot paths. Build a "Read Only" set for cautious workflows, a "React Development" set with just GitHub and Filesystem, or a "Full Stack Dev" set with everything. Assign them per-client so each tool only goes where you want it.
 
 ![Feature Sets — granular per-server tool selection](docs/screenshots/featureset-detail.png)
 
 ### Self-Management Meta Tools (mcpmux_*)
 
-Routing everything through one gateway endpoint means connected AI clients can see every backend tool at session start — even when the project only needs a handful. Workspace bindings pin stable per-folder toolsets, but they do not cover one-off needs ("enable Firebase for the next 15 minutes") or discovery-driven workflows where the LLM picks servers as it goes.
+Connected AI clients see a fixed ~12-tool meta surface instead of every backend tool definition. FeatureSets define what is **invokable**; optional **surfaced** tools (0–N per set) can be promoted into `tools/list` for one-hop hot paths. Workspace bindings pin stable per-folder toolsets; session enable/disable gates server activity without bloating context.
 
-McpMux exposes a built-in `mcpmux_*` tool namespace so the LLM can introspect and reshape its own tool surface mid-conversation:
+McpMux exposes a built-in `mcpmux_*` tool namespace for search → schema → invoke workflows:
 
 1. Call **`mcpmux_list_servers`** — server-level manifest with per-server status: `enabled_via_binding`, `enabled_via_session`, `disabled_via_session`, or `inactive`.
-2. Call **`mcpmux_enable_server`** or **`mcpmux_disable_server`** — toggle servers on or off. The gateway pushes `tools/list_changed` so the tool list refreshes without reconnecting.
-3. Use **`scope: "session"`** (default) for ephemeral overrides that die with the MCP session, or **`scope: "workspace"`** to persistently add/remove a server from the workspace binding (workspace writes always require approval).
+2. Call **`mcpmux_enable_server`** or **`mcpmux_disable_server`** — toggle servers on or off for the session or workspace.
+3. Call **`mcpmux_search_tools`** — find invokable tools by query (respects FeatureSet ACL).
+4. Call **`mcpmux_get_tool_schema`** — load parameter schemas before invoking.
+5. Call **`mcpmux_invoke_tool`** — invoke any permitted backend tool through one entry point.
 
 | Tool | Type | Purpose |
 | ---- | ---- | ------- |
-| `mcpmux_list_all_tools` | read | Full tool roster in the resolved Space |
+| `mcpmux_list_all_tools` | read | Full tool roster in the resolved Space (diagnostic) |
 | `mcpmux_list_feature_sets` | read | FeatureSets available in the resolved Space |
 | `mcpmux_list_servers` | read | Server-level manifest with status |
+| `mcpmux_search_tools` | read | Search invokable tools with optional schema detail |
+| `mcpmux_get_tool_schema` | read | Load input schemas before invoke |
+| `mcpmux_invoke_tool` | read | Invoke a backend tool by server_id + tool name |
 | `mcpmux_enable_server` | write | Enable a server (session or workspace scope) |
 | `mcpmux_disable_server` | write | Disable a server (session or workspace scope) |
-| `mcpmux_create_feature_set` | write | Create a custom FeatureSet |
+| `mcpmux_create_feature_set` | write | Create a custom FeatureSet (optional `surfaced_tools[]`) |
 | `mcpmux_bind_current_workspace` | write | Bind the session's workspace root to FeatureSets |
 
 In the desktop app: **Settings → Self-management tools** toggles the whole namespace and optional approval for session-scope overrides. **Workspaces → live folder inspector → Active session overrides** shows per-session enabled/disabled servers and lets you clear overrides with one click.
diff --git a/apps/desktop/src-tauri/src/commands/feature_set.rs b/apps/desktop/src-tauri/src/commands/feature_set.rs
index 2f81a7b4..ae132c0c 100644
--- a/apps/desktop/src-tauri/src/commands/feature_set.rs
+++ b/apps/desktop/src-tauri/src/commands/feature_set.rs
@@ -22,6 +22,7 @@ pub struct FeatureSetMemberResponse {
     pub member_type: String,
     pub member_id: String,
     pub mode: String,
+    pub surfaced: bool,
 }
 
 impl From<&FeatureSetMember> for FeatureSetMemberResponse {
@@ -32,6 +33,7 @@ impl From<&FeatureSetMember> for FeatureSetMemberResponse {
             member_type: m.member_type.as_str().to_string(),
             member_id: m.member_id.clone(),
             mode: m.mode.as_str().to_string(),
+            surfaced: m.surfaced,
         }
     }
 }
@@ -92,6 +94,7 @@ pub struct AddMemberInput {
     pub member_type: String, // "feature" or "feature_set"
     pub member_id: String,
     pub mode: Option<String>, // "include" or "exclude", defaults to "include"
+    pub surfaced: Option<bool>,
 }
 
 /// List all feature sets.
@@ -368,6 +371,7 @@ pub async fn add_feature_set_member(
         member_type,
         member_id: input.member_id,
         mode,
+        surfaced: input.surfaced.unwrap_or(false),
     };
 
     feature_set.members.push(member);
@@ -492,6 +496,7 @@ pub async fn set_feature_set_members(
                 member_type,
                 member_id: input.member_id,
                 mode,
+                surfaced: input.surfaced.unwrap_or(false),
             }
         })
         .collect();
diff --git a/apps/desktop/src/features/featuresets/FeatureSetPanel.tsx b/apps/desktop/src/features/featuresets/FeatureSetPanel.tsx
index 38406dd3..a1fd5008 100644
--- a/apps/desktop/src/features/featuresets/FeatureSetPanel.tsx
+++ b/apps/desktop/src/features/featuresets/FeatureSetPanel.tsx
@@ -18,6 +18,7 @@ import {
   Star,
   Shield,
   Save,
+  Monitor,
 } from 'lucide-react';
 import { Button, useToast, ToastContainer, useConfirm } from '@mcpmux/ui';
 import type { FeatureSet, AddMemberInput } from '@/lib/api/featureSets';
@@ -46,6 +47,7 @@ interface ServerGroup {
 export function FeatureSetPanel({ featureSet, spaceId, onClose, onDelete, onUpdate }: FeatureSetPanelProps) {
   const [allFeatures, setAllFeatures] = useState<ServerFeature[]>([]);
   const [selectedFeatureIds, setSelectedFeatureIds] = useState<Set<string>>(new Set());
+  const [surfacedFeatureIds, setSurfacedFeatureIds] = useState<Set<string>>(new Set());
   const [searchQuery, setSearchQuery] = useState('');
   const [isLoading, setIsLoading] = useState(true);
   const [isSaving, setIsSaving] = useState(false);
@@ -93,13 +95,18 @@ export function FeatureSetPanel({ featureSet, spaceId, onClose, onDelete, onUpda
         
         // Seed from the set's include-mode feature members.
         const currentIds = new Set<string>();
+        const surfacedIds = new Set<string>();
         featureSet.members?.forEach((m) => {
           if (m.member_type === 'feature' && m.mode === 'include') {
             currentIds.add(m.member_id);
+            if (m.surfaced) {
+              surfacedIds.add(m.member_id);
+            }
           }
         });
 
         setSelectedFeatureIds(currentIds);
+        setSurfacedFeatureIds(surfacedIds);
         
         // Start with all servers collapsed
         setExpandedServers(new Set());
@@ -143,6 +150,28 @@ export function FeatureSetPanel({ featureSet, spaceId, onClose, onDelete, onUpda
   const toggleFeature = (featureId: string) => {
     if (!isConfigurable) return;
     setSelectedFeatureIds((prev) => {
+      const next = new Set(prev);
+      if (next.has(featureId)) {
+        next.delete(featureId);
+        setSurfacedFeatureIds((surfaced) => {
+          const nextSurfaced = new Set(surfaced);
+          nextSurfaced.delete(featureId);
+          return nextSurfaced;
+        });
+      } else {
+        next.add(featureId);
+      }
+      return next;
+    });
+  };
+
+  /**
+   * Toggle whether an included tool is promoted into client tools/list.
+   */
+  const toggleSurfaced = (featureId: string, event: React.MouseEvent) => {
+    event.stopPropagation();
+    if (!isConfigurable || !selectedFeatureIds.has(featureId)) return;
+    setSurfacedFeatureIds((prev) => {
       const next = new Set(prev);
       if (next.has(featureId)) {
         next.delete(featureId);
@@ -230,6 +259,7 @@ export function FeatureSetPanel({ featureSet, spaceId, onClose, onDelete, onUpda
         member_type: 'feature' as const,
         member_id: id,
         mode: 'include' as const,
+        surfaced: surfacedFeatureIds.has(id),
       }));
       
       await setFeatureSetMembers(featureSet.id, members);
@@ -613,42 +643,64 @@ export function FeatureSetPanel({ featureSet, spaceId, onClose, onDelete, onUpda
                               <div className="bg-[rgb(var(--background))] border-t border-[rgb(var(--border))]">
                                 {group.features.map((feature) => {
                                   const isSelected = isFeatureSelected(feature.id, feature);
-                                  
+                                  const isSurfaced = surfacedFeatureIds.has(feature.id);
+                                  const isTool = feature.feature_type === 'tool';
+
                                   return (
-                                    <button
+                                    <div
                                       key={feature.id}
-                                      onClick={() => toggleFeature(feature.id)}
-                                      disabled={!isConfigurable}
-                                      className={`w-full flex items-center gap-3 px-4 py-2.5 pl-12 text-left border-b border-[rgb(var(--border))] last:border-b-0 transition-colors
-                                        ${isConfigurable ? 'hover:bg-[rgb(var(--surface-hover))]' : 'cursor-default'}
+                                      className={`flex items-center gap-2 border-b border-[rgb(var(--border))] last:border-b-0 transition-colors
                                         ${isSelected ? 'bg-primary-50 dark:bg-primary-900/10' : ''}`}
                                     >
-                                      <div className={`flex-shrink-0 w-4 h-4 rounded border flex items-center justify-center transition-colors ${
-                                        isSelected 
-                                          ? 'bg-primary-500 border-primary-500' 
-                                          : 'border-[rgb(var(--border))] bg-white dark:bg-[rgb(var(--surface))]'
-                                      }`}>
-                                        {isSelected && <Check className="h-3 w-3 text-white" />}
-                                      </div>
-                                      
-                                      {getFeatureIcon(feature.feature_type)}
-                                      
-                                      <div className="flex-1 min-w-0">
-                                        <div className="flex items-center gap-2">
-                                          <span className="font-medium text-sm truncate">
-                                            {feature.display_name || feature.feature_name}
-                                          </span>
-                                          <span className={`text-[10px] px-1.5 py-0.5 rounded ${getTypeColor(feature.feature_type)}`}>
-                                            {feature.feature_type}
-                                          </span>
+                                      <button
+                                        onClick={() => toggleFeature(feature.id)}
+                                        disabled={!isConfigurable}
+                                        className={`flex-1 flex items-center gap-3 px-4 py-2.5 pl-12 text-left transition-colors
+                                          ${isConfigurable ? 'hover:bg-[rgb(var(--surface-hover))]' : 'cursor-default'}`}
+                                      >
+                                        <div className={`flex-shrink-0 w-4 h-4 rounded border flex items-center justify-center transition-colors ${
+                                          isSelected
+                                            ? 'bg-primary-500 border-primary-500'
+                                            : 'border-[rgb(var(--border))] bg-white dark:bg-[rgb(var(--surface))]'
+                                        }`}>
+                                          {isSelected && <Check className="h-3 w-3 text-white" />}
+                                        </div>
+
+                                        {getFeatureIcon(feature.feature_type)}
+
+                                        <div className="flex-1 min-w-0">
+                                          <div className="flex items-center gap-2">
+                                            <span className="font-medium text-sm truncate">
+                                              {feature.display_name || feature.feature_name}
+                                            </span>
+                                            <span className={`text-[10px] px-1.5 py-0.5 rounded ${getTypeColor(feature.feature_type)}`}>
+                                              {feature.feature_type}
+                                            </span>
+                                          </div>
+                                          {feature.description && (
+                                            <p className="text-xs text-[rgb(var(--muted))] mt-0.5 line-clamp-1">
+                                              {feature.description}
+                                            </p>
+                                          )}
                                         </div>
-                                        {feature.description && (
-                                          <p className="text-xs text-[rgb(var(--muted))] mt-0.5 line-clamp-1">
-                                            {feature.description}
-                                          </p>
-                                        )}
-                                      </div>
-                                    </button>
+                                      </button>
+
+                                      {isConfigurable && isTool && isSelected && (
+                                        <button
+                                          type="button"
+                                          onClick={(event) => toggleSurfaced(feature.id, event)}
+                                          className={`mr-3 flex items-center gap-1.5 px-2 py-1 rounded-md text-xs font-medium transition-colors flex-shrink-0
+                                            ${isSurfaced
+                                              ? 'bg-blue-100 dark:bg-blue-900/30 text-blue-700 dark:text-blue-300'
+                                              : 'text-[rgb(var(--muted))] hover:bg-[rgb(var(--surface-hover))]'}`}
+                                          title="Surface in client tools/list"
+                                          data-testid={`surface-toggle-${feature.id}`}
+                                        >
+                                          <Monitor className="h-3.5 w-3.5" />
+                                          Surface
+                                        </button>
+                                      )}
+                                    </div>
                                   );
                                 })}
                               </div>
diff --git a/apps/desktop/src/features/settings/SettingsPage.tsx b/apps/desktop/src/features/settings/SettingsPage.tsx
index 7ea6a0f8..89b48e56 100644
--- a/apps/desktop/src/features/settings/SettingsPage.tsx
+++ b/apps/desktop/src/features/settings/SettingsPage.tsx
@@ -638,9 +638,10 @@ export function SettingsPage() {
             Self-management tools (mcpmux_*)
           </CardTitle>
           <CardDescription>
-            When enabled, connected MCP clients see a small built-in toolset that lets
-            LLMs introspect and — with your approval — reshape the FeatureSet they see.
-            Writes always trigger a native approval dialog; reads are silent.
+            When enabled, connected MCP clients see a fixed meta-tool surface (~12 tools)
+            for search → schema → invoke workflows. FeatureSets control what is invokable;
+            optional surfaced tools can appear directly in tools/list. Writes always trigger
+            a native approval dialog; reads are silent.
           </CardDescription>
         </CardHeader>
         <CardContent className="space-y-6">
@@ -650,9 +651,9 @@ export function SettingsPage() {
               <div>
                 <label className="text-sm font-medium">Advertise self-management tools</label>
                 <p className="text-xs text-[rgb(var(--muted))] mt-1">
-                  Shows <code className="font-mono">mcpmux_list_all_tools</code>,&nbsp;
-                  <code className="font-mono">mcpmux_pin_this_session</code>, and 6 others to
-                  every connected MCP client. Turn off to hide the whole namespace.
+                  Shows <code className="font-mono">mcpmux_search_tools</code>,&nbsp;
+                  <code className="font-mono">mcpmux_invoke_tool</code>, and other meta tools
+                  to every connected MCP client. Turn off to hide the whole namespace.
                 </p>
               </div>
             </div>
diff --git a/apps/desktop/src/lib/api/featureSets.ts b/apps/desktop/src/lib/api/featureSets.ts
index 64bf8e2b..4c1a750f 100644
--- a/apps/desktop/src/lib/api/featureSets.ts
+++ b/apps/desktop/src/lib/api/featureSets.ts
@@ -45,6 +45,7 @@ export interface FeatureSetMember {
   member_type: MemberType;
   member_id: string;
   mode: MemberMode;
+  surfaced?: boolean;
 }
 
 /**
@@ -89,6 +90,7 @@ export interface AddMemberInput {
   member_type: MemberType;
   member_id: string;
   mode?: MemberMode;
+  surfaced?: boolean;
 }
 
 /**
diff --git a/crates/mcpmux-core/src/domain/feature_set.rs b/crates/mcpmux-core/src/domain/feature_set.rs
index 53bd950c..84f4653a 100644
--- a/crates/mcpmux-core/src/domain/feature_set.rs
+++ b/crates/mcpmux-core/src/domain/feature_set.rs
@@ -119,6 +119,9 @@ pub struct FeatureSetMember {
     pub member_id: String,
     /// Include or exclude
     pub mode: MemberMode,
+    /// When true on an included tool member, promote into client `tools/list`.
+    #[serde(default)]
+    pub surfaced: bool,
 }
 
 impl FeatureSetMember {
@@ -130,6 +133,7 @@ impl FeatureSetMember {
             member_type: MemberType::Feature,
             member_id: feature_id.to_string(),
             mode: MemberMode::Include,
+            surfaced: false,
         }
     }
 
@@ -141,6 +145,7 @@ impl FeatureSetMember {
             member_type: MemberType::Feature,
             member_id: feature_id.to_string(),
             mode: MemberMode::Exclude,
+            surfaced: false,
         }
     }
 
@@ -152,6 +157,7 @@ impl FeatureSetMember {
             member_type: MemberType::FeatureSet,
             member_id: included_featureset_id.to_string(),
             mode: MemberMode::Include,
+            surfaced: false,
         }
     }
 }
diff --git a/crates/mcpmux-gateway/src/pool/features/facade.rs b/crates/mcpmux-gateway/src/pool/features/facade.rs
index 7b6d8100..4ccef995 100644
--- a/crates/mcpmux-gateway/src/pool/features/facade.rs
+++ b/crates/mcpmux-gateway/src/pool/features/facade.rs
@@ -107,21 +107,27 @@ impl FeatureService {
     }
 
     /// Tools promoted into client `tools/list` (surfaced backend tools only).
-    ///
-    /// Phase C adds per-member `surfaced: true`; until then this returns an
-    /// empty list so clients see meta tools only.
     pub async fn get_advertised_tools_for_grants(
         &self,
         space_id: &str,
         feature_set_ids: &[String],
         session_id: Option<&str>,
     ) -> Result<Vec<ServerFeature>> {
+        if feature_set_ids.is_empty() {
+            return Ok(Vec::new());
+        }
+
         let invokable = self
             .get_invokable_tools_for_grants(space_id, feature_set_ids, session_id)
             .await?;
+        let surfaced_ids = self
+            .resolution
+            .resolve_surfaced_feature_ids(feature_set_ids)
+            .await?;
+
         Ok(invokable
             .into_iter()
-            .filter(|_| false) // Phase C: filter surfaced members
+            .filter(|f| surfaced_ids.contains(&f.id.to_string()))
             .collect())
     }
 
@@ -192,14 +198,25 @@ impl FeatureService {
             return Ok(binding_features);
         }
 
-        let mut binding_servers: HashSet<String> = binding_features
+        // Bound FeatureSets: member filter is authoritative — session overrides
+        // only gate server activity, they do not expand to all server tools.
+        if !feature_set_ids.is_empty() {
+            return Ok(binding_features
+                .into_iter()
+                .filter(|f| !disabled.contains(&f.server_id))
+                .collect());
+        }
+
+        // Unbound session (no FS): session-enabled servers expose all tools so
+        // meta tools can bootstrap before bind/grant.
+        let mut active_servers: HashSet<String> = binding_features
             .iter()
             .map(|f| f.server_id.clone())
             .collect();
-        binding_servers.extend(enabled.iter().cloned());
-        binding_servers.retain(|server_id| !disabled.contains(server_id));
+        active_servers.extend(enabled.iter().cloned());
+        active_servers.retain(|server_id| !disabled.contains(server_id));
 
-        if binding_servers.is_empty() {
+        if active_servers.is_empty() {
             return Ok(Vec::new());
         }
 
@@ -210,7 +227,7 @@ impl FeatureService {
 
         Ok(all_features
             .into_iter()
-            .filter(|f| f.is_available && binding_servers.contains(&f.server_id))
+            .filter(|f| f.is_available && active_servers.contains(&f.server_id))
             .collect())
     }
 
diff --git a/crates/mcpmux-gateway/src/pool/features/resolution.rs b/crates/mcpmux-gateway/src/pool/features/resolution.rs
index 7f779b8d..1709ac81 100644
--- a/crates/mcpmux-gateway/src/pool/features/resolution.rs
+++ b/crates/mcpmux-gateway/src/pool/features/resolution.rs
@@ -163,6 +163,48 @@ impl FeatureResolutionService {
         Ok(result)
     }
 
+    /// Collect feature IDs marked `surfaced: true` across the given FeatureSets.
+    pub async fn resolve_surfaced_feature_ids(
+        &self,
+        feature_set_ids: &[String],
+    ) -> Result<HashSet<String>> {
+        let mut surfaced = HashSet::new();
+        for fs_id in feature_set_ids {
+            let Some(feature_set) = self.feature_set_repo.get_with_members(fs_id).await? else {
+                continue;
+            };
+            self.collect_surfaced_members(&feature_set, &mut surfaced)
+                .await?;
+        }
+        Ok(surfaced)
+    }
+
+    async fn collect_surfaced_members(
+        &self,
+        feature_set: &FeatureSet,
+        surfaced: &mut HashSet<String>,
+    ) -> Result<()> {
+        for member in &feature_set.members {
+            match member.member_type {
+                MemberType::Feature => {
+                    if member.mode == MemberMode::Include && member.surfaced {
+                        surfaced.insert(member.member_id.clone());
+                    }
+                }
+                MemberType::FeatureSet => {
+                    if let Some(nested_fs) = self
+                        .feature_set_repo
+                        .get_with_members(&member.member_id)
+                        .await?
+                    {
+                        Box::pin(self.collect_surfaced_members(&nested_fs, surfaced)).await?;
+                    }
+                }
+            }
+        }
+        Ok(())
+    }
+
     async fn resolve_members(
         &self,
         feature_set: &FeatureSet,
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
index bcc73452..c12a5e88 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
@@ -5,7 +5,7 @@
 
 use async_trait::async_trait;
 use mcpmux_core::{
-    normalize_workspace_root, DomainEvent, FeatureType, MemberMode, WorkspaceBinding,
+    normalize_workspace_root, DomainEvent, FeatureType, WorkspaceBinding,
 };
 use rmcp::model::{CallToolResult, Content};
 use serde_json::{json, Value};
@@ -823,7 +823,8 @@ impl MetaTool for CreateFeatureSetTool {
     fn description(&self) -> &'static str {
         "Create a new custom FeatureSet in the caller's resolved Space from \
          an explicit list of qualified tool names (e.g. ['github_create_issue', \
-         'firebase_deploy']). Returns the new FS id. To make a workspace \
+         'firebase_deploy']). Optional surfaced_tools promotes a subset into \
+         client tools/list. Returns the new FS id. To make a workspace \
          actually route through this FeatureSet, follow up with \
          `mcpmux_bind_current_workspace`."
     }
@@ -838,6 +839,11 @@ impl MetaTool for CreateFeatureSetTool {
                 "tool_qualified_names": {
                     "type": "array",
                     "items": { "type": "string" }
+                },
+                "surfaced_tools": {
+                    "type": "array",
+                    "items": { "type": "string" },
+                    "description": "Optional subset of tool_qualified_names to promote into client tools/list"
                 }
             }
         })
@@ -875,6 +881,17 @@ impl MetaTool for CreateFeatureSetTool {
             ));
         }
 
+        let surfaced_names: HashSet<String> = call
+            .args
+            .get("surfaced_tools")
+            .and_then(|v| v.as_array())
+            .map(|arr| {
+                arr.iter()
+                    .filter_map(|v| v.as_str().map(str::to_string))
+                    .collect()
+            })
+            .unwrap_or_default();
+
         let space_id = caller_space_id(&call).await?;
 
         // Resolve qualified names → ServerFeature ids up-front so the
@@ -916,17 +933,24 @@ impl MetaTool for CreateFeatureSetTool {
                 let mut fs =
                     mcpmux_core::FeatureSet::new_custom(&name_for_closure, space_id.to_string());
                 fs.description = description_for_closure;
-                fs_repo.create(&fs).await?;
                 for feature in &matched {
-                    fs_repo
-                        .add_feature_member(&fs.id, &feature.id.to_string(), MemberMode::Include)
-                        .await?;
+                    let mut member = mcpmux_core::FeatureSetMember::include_feature(
+                        &fs.id,
+                        &feature.id.to_string(),
+                    );
+                    if surfaced_names.contains(&feature.qualified_name()) {
+                        member.surfaced = true;
+                    }
+                    fs.members.push(member);
                 }
+                fs_repo.create(&fs).await?;
+                let surfaced_count = fs.members.iter().filter(|m| m.surfaced).count();
                 info!(fs_id = %fs.id, name = %name_for_closure, "[meta_tools] create_feature_set applied");
                 Ok(text_result(json!({
                     "ok": true,
                     "feature_set_id": fs.id,
                     "tool_count": matched.len(),
+                    "surfaced_count": surfaced_count,
                 })))
             },
         )
diff --git a/crates/mcpmux-storage/src/database.rs b/crates/mcpmux-storage/src/database.rs
index ce160c52..13c96d00 100644
--- a/crates/mcpmux-storage/src/database.rs
+++ b/crates/mcpmux-storage/src/database.rs
@@ -123,6 +123,11 @@ const MIGRATIONS: &[Migration] = &[
         name: "installed_server_display_name_override",
         sql: include_str!("migrations/018_installed_server_display_name_override.sql"),
     },
+    Migration {
+        version: 19,
+        name: "feature_set_member_surfaced",
+        sql: include_str!("migrations/019_feature_set_member_surfaced.sql"),
+    },
 ];
 
 /// SQLite database wrapper.
diff --git a/crates/mcpmux-storage/src/migrations/019_feature_set_member_surfaced.sql b/crates/mcpmux-storage/src/migrations/019_feature_set_member_surfaced.sql
new file mode 100644
index 00000000..aa114a59
--- /dev/null
+++ b/crates/mcpmux-storage/src/migrations/019_feature_set_member_surfaced.sql
@@ -0,0 +1,2 @@
+-- Per-member flag: when set on an included tool, promote into client tools/list.
+ALTER TABLE feature_set_members ADD COLUMN surfaced INTEGER NOT NULL DEFAULT 0;
diff --git a/crates/mcpmux-storage/src/repositories/feature_set_repository.rs b/crates/mcpmux-storage/src/repositories/feature_set_repository.rs
index aaf2b436..2971d5e3 100644
--- a/crates/mcpmux-storage/src/repositories/feature_set_repository.rs
+++ b/crates/mcpmux-storage/src/repositories/feature_set_repository.rs
@@ -67,6 +67,7 @@ impl SqliteFeatureSetRepository {
                 .unwrap_or(MemberType::Feature),
             member_id: row.get(3)?,
             mode: MemberMode::parse(&row.get::<_, String>(4)?).unwrap_or(MemberMode::Include),
+            surfaced: row.get::<_, i32>(5).unwrap_or(0) == 1,
         })
     }
 
@@ -76,7 +77,7 @@ impl SqliteFeatureSetRepository {
         let conn = db.connection();
 
         let mut stmt = conn.prepare(
-            "SELECT id, feature_set_id, member_type, member_id, mode
+            "SELECT id, feature_set_id, member_type, member_id, mode, surfaced
              FROM feature_set_members
              WHERE feature_set_id = ?
              ORDER BY id",
@@ -95,7 +96,7 @@ impl SqliteFeatureSetRepository {
         feature_set_id: &str,
     ) -> Result<Vec<FeatureSetMember>> {
         let mut stmt = conn.prepare(
-            "SELECT id, feature_set_id, member_type, member_id, mode
+            "SELECT id, feature_set_id, member_type, member_id, mode, surfaced
              FROM feature_set_members
              WHERE feature_set_id = ?
              ORDER BY id",
@@ -210,14 +211,15 @@ impl FeatureSetRepository for SqliteFeatureSetRepository {
         let now = chrono::Utc::now().to_rfc3339();
         for member in &feature_set.members {
             conn.execute(
-                "INSERT INTO feature_set_members (id, feature_set_id, member_type, member_id, mode, created_at)
-                 VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
+                "INSERT INTO feature_set_members (id, feature_set_id, member_type, member_id, mode, surfaced, created_at)
+                 VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)",
                 params![
                     member.id,
                     member.feature_set_id,
                     member.member_type.as_str(),
                     member.member_id,
                     member.mode.as_str(),
+                    if member.surfaced { 1 } else { 0 },
                     now,
                 ],
             )?;
@@ -256,14 +258,15 @@ impl FeatureSetRepository for SqliteFeatureSetRepository {
         let now = chrono::Utc::now().to_rfc3339();
         for member in &feature_set.members {
             conn.execute(
-                "INSERT INTO feature_set_members (id, feature_set_id, member_type, member_id, mode, created_at)
-                 VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
+                "INSERT INTO feature_set_members (id, feature_set_id, member_type, member_id, mode, surfaced, created_at)
+                 VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)",
                 params![
                     member.id,
                     member.feature_set_id,
                     member.member_type.as_str(),
                     member.member_id,
                     member.mode.as_str(),
+                    if member.surfaced { 1 } else { 0 },
                     now,
                 ],
             )?;
@@ -345,17 +348,19 @@ impl FeatureSetRepository for SqliteFeatureSetRepository {
             member_type: MemberType::Feature,
             member_id: feature_id.to_string(),
             mode,
+            surfaced: false,
         };
 
         conn.execute(
-            "INSERT INTO feature_set_members (id, feature_set_id, member_type, member_id, mode, created_at)
-             VALUES (?1, ?2, ?3, ?4, ?5, ?6)",
+            "INSERT INTO feature_set_members (id, feature_set_id, member_type, member_id, mode, surfaced, created_at)
+             VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7)",
             params![
                 member.id,
                 member.feature_set_id,
                 member.member_type.as_str(),
                 member.member_id,
                 member.mode.as_str(),
+                if member.surfaced { 1 } else { 0 },
                 chrono::Utc::now().to_rfc3339(),
             ],
         )?;
@@ -383,7 +388,7 @@ impl FeatureSetRepository for SqliteFeatureSetRepository {
         let conn = db.connection();
 
         let mut stmt = conn.prepare(
-            "SELECT id, feature_set_id, member_type, member_id, mode
+            "SELECT id, feature_set_id, member_type, member_id, mode, surfaced
              FROM feature_set_members
              WHERE feature_set_id = ?1 AND member_type = 'feature'
              ORDER BY id",
diff --git a/tests/rust/src/mocks.rs b/tests/rust/src/mocks.rs
index 2baa1fae..a4869122 100644
--- a/tests/rust/src/mocks.rs
+++ b/tests/rust/src/mocks.rs
@@ -439,6 +439,7 @@ impl FeatureSetRepository for MockFeatureSetRepository {
             member_type: MemberType::Feature,
             member_id: feature_id.to_string(),
             mode,
+            surfaced: false,
         };
         self.members
             .write()
diff --git a/tests/rust/tests/integration/mcp_flows.rs b/tests/rust/tests/integration/mcp_flows.rs
index 04f23d40..2953e009 100644
--- a/tests/rust/tests/integration/mcp_flows.rs
+++ b/tests/rust/tests/integration/mcp_flows.rs
@@ -105,6 +105,7 @@ impl TestContext {
                 member_type: MemberType::Feature,
                 member_id: feature.id.to_string(),
                 mode: MemberMode::Include,
+                surfaced: false,
             });
         }
         fs
@@ -129,6 +130,7 @@ impl TestContext {
                 member_type: MemberType::Feature,
                 member_id: feature.id.to_string(),
                 mode: MemberMode::Include,
+                surfaced: false,
             });
         }
         fs
@@ -188,6 +190,7 @@ async fn test_list_tools_with_restricted_grant() {
         member_id: tool_a_id.to_string(),
         member_type: MemberType::Feature,
         mode: MemberMode::Include,
+        surfaced: false,
     });
     let custom_fs_id = ctx.add_feature_set(custom_fs).await;
 
@@ -512,6 +515,7 @@ async fn test_features_dont_leak_between_spaces() {
         member_type: MemberType::Feature,
         member_id: work_tool.id.to_string(),
         mode: MemberMode::Include,
+        surfaced: false,
     });
     let work_all_id = work_all.id.clone();
     feature_set_repo.create(&work_all).await.unwrap();
diff --git a/tests/rust/tests/integration/meta_gateway_invoke.rs b/tests/rust/tests/integration/meta_gateway_invoke.rs
index f5778c88..7b09e5c6 100644
--- a/tests/rust/tests/integration/meta_gateway_invoke.rs
+++ b/tests/rust/tests/integration/meta_gateway_invoke.rs
@@ -30,6 +30,8 @@ struct Fixture {
     registry: Arc<MetaToolRegistry>,
     feature_service: Arc<FeatureService>,
     session_overrides: Arc<SessionOverrideRegistry>,
+    session_roots: Arc<SessionRootsRegistry>,
+    inbound_client_repo: Arc<InboundClientRepository>,
     server_feature_repo: Arc<dyn ServerFeatureRepository>,
     feature_set_repo: Arc<dyn FeatureSetRepository>,
     space_id: Uuid,
@@ -89,6 +91,7 @@ impl Fixture {
             member_type: MemberType::Feature,
             member_id: list_issues.id.to_string(),
             mode: MemberMode::Include,
+            surfaced: false,
         });
         feature_set_repo.create(&grant_all).await.unwrap();
 
@@ -125,7 +128,7 @@ impl Fixture {
             resolver,
             feature_service.clone(),
             None,
-            session_roots,
+            session_roots.clone(),
             session_overrides.clone(),
             broker,
             tx,
@@ -136,6 +139,8 @@ impl Fixture {
             registry,
             feature_service,
             session_overrides,
+            session_roots,
+            inbound_client_repo,
             server_feature_repo,
             feature_set_repo,
             space_id,
@@ -144,6 +149,20 @@ impl Fixture {
         }
     }
 
+    /// Grant a FeatureSet to the fixture client (Tier-2 resolver path).
+    async fn grant_feature_set(&self, feature_set_id: &str) {
+        self.inbound_client_repo
+            .grant_feature_set(
+                &self.client_id,
+                &self.space_id.to_string(),
+                feature_set_id,
+            )
+            .await
+            .unwrap();
+        self.session_roots
+            .set_roots_capable(&self.session_id, false);
+    }
+
     fn result_json(result: &rmcp::model::CallToolResult) -> Value {
         let raw = serde_json::to_value(result).unwrap();
         raw.get("content")
@@ -168,7 +187,7 @@ impl Fixture {
 }
 
 #[tokio::test(flavor = "multi_thread")]
-async fn advertised_tools_empty_while_invokable_has_backend_tools() {
+async fn advertised_tools_empty_without_surfaced_members() {
     let f = Fixture::new().await;
     let fs_ids = vec![
         f.feature_set_repo
@@ -186,7 +205,7 @@ async fn advertised_tools_empty_while_invokable_has_backend_tools() {
         .get_advertised_tools_for_grants(&f.space_id.to_string(), &fs_ids, Some(&f.session_id))
         .await
         .unwrap();
-    assert!(advertised.is_empty(), "Phase A: no surfaced tools yet");
+    assert!(advertised.is_empty(), "no surfaced members by default");
 
     f.session_overrides.enable(&f.session_id, "github");
     let invokable = f
@@ -377,3 +396,100 @@ async fn invoke_result_filter_shapes_text_content_blocks() {
     assert_eq!(parsed.get("total"), Some(&json!(80)));
     assert_eq!(parsed.get("truncated"), Some(&json!(true)));
 }
+
+#[tokio::test(flavor = "multi_thread")]
+async fn partial_feature_set_binding_limits_search_and_invoke() {
+    let f = Fixture::new().await;
+
+    let mut create_issue = ServerFeature::tool(f.space_id, "github", "create_issue");
+    create_issue.description = Some("Create an issue".into());
+    create_issue.raw_json = Some(json!({
+        "name": "create_issue",
+        "description": "Create an issue",
+        "inputSchema": { "type": "object" }
+    }));
+    f.server_feature_repo.upsert(&create_issue).await.unwrap();
+
+    let list_issues = f
+        .server_feature_repo
+        .list_for_space(&f.space_id.to_string())
+        .await
+        .unwrap()
+        .into_iter()
+        .find(|feat| feat.feature_name == "list_issues")
+        .unwrap();
+
+    let mut partial_fs = FeatureSet::new_custom("Partial GitHub", f.space_id.to_string());
+    partial_fs.members.push(FeatureSetMember {
+        id: Uuid::new_v4().to_string(),
+        feature_set_id: partial_fs.id.clone(),
+        member_type: MemberType::Feature,
+        member_id: list_issues.id.to_string(),
+        mode: MemberMode::Include,
+        surfaced: false,
+    });
+    f.feature_set_repo.create(&partial_fs).await.unwrap();
+    f.grant_feature_set(&partial_fs.id).await;
+    f.session_overrides.enable(&f.session_id, "github");
+
+    let fs_ids = vec![partial_fs.id.clone()];
+    let invokable = f
+        .feature_service
+        .get_invokable_tools_for_grants(&f.space_id.to_string(), &fs_ids, Some(&f.session_id))
+        .await
+        .unwrap();
+    assert_eq!(invokable.len(), 1);
+    assert_eq!(invokable[0].feature_name, "list_issues");
+
+    let search = f
+        .call(
+            "mcpmux_search_tools",
+            json!({ "query": "issue", "server_id": "github" }),
+        )
+        .await;
+    let search_body = Fixture::result_json(&search);
+    let tools = search_body.get("tools").unwrap().as_array().unwrap();
+    assert_eq!(tools.len(), 1);
+    assert_eq!(
+        tools[0].get("qualified_name"),
+        Some(&json!("github_list_issues"))
+    );
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn surfaced_tool_appears_in_advertised_set() {
+    let f = Fixture::new().await;
+
+    let list_issues = f
+        .server_feature_repo
+        .list_for_space(&f.space_id.to_string())
+        .await
+        .unwrap()
+        .into_iter()
+        .find(|feat| feat.feature_name == "list_issues")
+        .unwrap();
+
+    let mut surfaced_fs = FeatureSet::new_custom("Surfaced GitHub", f.space_id.to_string());
+    surfaced_fs.members.push(FeatureSetMember {
+        id: Uuid::new_v4().to_string(),
+        feature_set_id: surfaced_fs.id.clone(),
+        member_type: MemberType::Feature,
+        member_id: list_issues.id.to_string(),
+        mode: MemberMode::Include,
+        surfaced: true,
+    });
+    f.feature_set_repo.create(&surfaced_fs).await.unwrap();
+
+    f.session_overrides.enable(&f.session_id, "github");
+
+    let fs_ids = vec![surfaced_fs.id.clone()];
+    let advertised = f
+        .feature_service
+        .get_advertised_tools_for_grants(&f.space_id.to_string(), &fs_ids, Some(&f.session_id))
+        .await
+        .unwrap();
+
+    assert_eq!(advertised.len(), 1);
+    assert_eq!(advertised[0].feature_name, "list_issues");
+    assert_eq!(advertised[0].qualified_name(), "github_list_issues");
+}
diff --git a/tests/rust/tests/integration/meta_tools.rs b/tests/rust/tests/integration/meta_tools.rs
index bd980826..d9a56a13 100644
--- a/tests/rust/tests/integration/meta_tools.rs
+++ b/tests/rust/tests/integration/meta_tools.rs
@@ -1036,6 +1036,7 @@ async fn github_only_fs(f: &Fixture) -> String {
         member_type: MemberType::Feature,
         member_id: f.github_tool_id.to_string(),
         mode: MemberMode::Include,
+        surfaced: false,
     });
     let id = fs.id.clone();
     f.feature_set_repo.create(&fs).await.unwrap();

From ed8a5fbbc9323fffdac16ecacf1833a74b11bb2d Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 14:36:56 -0600
Subject: [PATCH 36/48] fix(gateway): upsert workspace binding in
 bind_current_workspace

Rebind an existing workspace root via update instead of insert, avoiding
UNIQUE constraint failures when Starter or UI bindings already exist.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 .../src/services/meta_tools/tools.rs          | 48 ++++++++++++----
 .../services/meta_tools/workspace_server.rs   |  2 +-
 tests/rust/tests/integration/meta_tools.rs    | 57 ++++++++++++++++++-
 3 files changed, 95 insertions(+), 12 deletions(-)

diff --git a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
index c12a5e88..13d28435 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
@@ -18,6 +18,7 @@ use super::approval::{ApprovalPayload, ApprovalScope};
 use super::registry::{
     MetaTool, MetaToolCall, MetaToolError, SESSION_OVERRIDES_REQUIRE_APPROVAL_KEY,
 };
+use super::workspace_server::emit_workspace_binding_changed;
 use crate::services::ResolvedFeatureSet;
 
 /// Fire a `FeatureSetMembersChanged` event so MCPNotifier pushes a
@@ -1030,19 +1031,46 @@ impl MetaTool for BindCurrentWorkspaceTool {
             true,
             call.args.clone(),
             || async move {
-                let binding =
-                    WorkspaceBinding::new(normalized.clone(), space_id, fs_id.to_string());
-                binding_repo.create(&binding).await?;
-                info!(
-                    %space_id,
-                    workspace_root = %normalized,
-                    feature_set_id = %fs_id,
-                    "[meta_tools] bind_current_workspace applied",
-                );
+                let fs_id_str = fs_id.to_string();
+                let existing = binding_repo
+                    .list()
+                    .await?
+                    .into_iter()
+                    .find(|b| b.workspace_root == normalized);
+
+                let binding_id = if let Some(mut binding) = existing {
+                    binding.space_id = space_id;
+                    binding.feature_set_ids = vec![fs_id_str.clone()];
+                    binding.updated_at = chrono::Utc::now();
+                    binding_repo.update(&binding).await?;
+                    emit_workspace_binding_changed(&event_tx, space_id, &normalized);
+                    info!(
+                        %space_id,
+                        binding_id = %binding.id,
+                        workspace_root = %normalized,
+                        feature_set_id = %fs_id,
+                        "[meta_tools] bind_current_workspace updated existing binding",
+                    );
+                    binding.id
+                } else {
+                    let binding =
+                        WorkspaceBinding::new(normalized.clone(), space_id, fs_id_str.clone());
+                    let binding_id = binding.id;
+                    binding_repo.create(&binding).await?;
+                    info!(
+                        %space_id,
+                        binding_id = %binding_id,
+                        workspace_root = %normalized,
+                        feature_set_id = %fs_id,
+                        "[meta_tools] bind_current_workspace created binding",
+                    );
+                    binding_id
+                };
+
                 emit_tools_list_changed(&event_tx, space_id);
                 Ok(text_result(json!({
                     "ok": true,
-                    "binding_id": binding.id,
+                    "binding_id": binding_id,
                     "workspace_root": normalized,
                     "feature_set_id": fs_id,
                 })))
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/workspace_server.rs b/crates/mcpmux-gateway/src/services/meta_tools/workspace_server.rs
index 13434880..b2683a9b 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/workspace_server.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/workspace_server.rs
@@ -50,7 +50,7 @@ async fn resolve_workspace_binding(
     Ok((binding, normalized))
 }
 
-fn emit_workspace_binding_changed(
+pub(crate) fn emit_workspace_binding_changed(
     event_tx: &broadcast::Sender<DomainEvent>,
     space_id: Uuid,
     workspace_root: &str,
diff --git a/tests/rust/tests/integration/meta_tools.rs b/tests/rust/tests/integration/meta_tools.rs
index d9a56a13..c0e00fe0 100644
--- a/tests/rust/tests/integration/meta_tools.rs
+++ b/tests/rust/tests/integration/meta_tools.rs
@@ -14,7 +14,7 @@ use mcpmux_core::{
     normalize_workspace_root, Client, DomainEvent, FeatureSet, FeatureSetMember,
     FeatureSetRepository, InboundMcpClientRepository, InstalledServer, InstalledServerRepository,
     MemberMode, MemberType, ServerFeature, ServerFeatureRepository, SpaceRepository,
-    WorkspaceBindingRepository,
+    WorkspaceBinding, WorkspaceBindingRepository,
 };
 use mcpmux_gateway::pool::FeatureService;
 use mcpmux_gateway::services::{
@@ -759,6 +759,61 @@ async fn bind_current_workspace_creates_binding_with_normalized_root() {
     );
 }
 
+#[tokio::test(flavor = "multi_thread")]
+async fn bind_current_workspace_updates_existing_binding_for_same_root() {
+    let f = Fixture::new().await;
+    f.attach_auto_publisher(ApprovalDecision::AllowOnce);
+    let input = if cfg!(windows) {
+        "D:\\Projects\\Android\\MyApp\\"
+    } else {
+        "/home/me/projects/android/myapp/"
+    };
+    let normalized = normalize_workspace_root(input);
+    f.session_roots.set(&f.session_id, [input]);
+
+    let fs_full_id = {
+        let sets = f
+            .feature_set_repo
+            .list_by_space(&f.space_id.to_string())
+            .await
+            .unwrap();
+        let full = sets
+            .iter()
+            .find(|fs| fs.name == "Full Access")
+            .expect("Full Access FS");
+        Uuid::parse_str(&full.id).unwrap()
+    };
+
+    // Seed an existing binding (simulates Workspaces UI or prior bind).
+    let starter = WorkspaceBinding::new(
+        normalized.clone(),
+        f.space_id,
+        f.fs_android_id.to_string(),
+    );
+    f.binding_repo.create(&starter).await.unwrap();
+
+    let result = f
+        .registry
+        .call(
+            "mcpmux_bind_current_workspace",
+            &f.client_id,
+            Some(&f.session_id),
+            json!({ "feature_set_id": fs_full_id.to_string() }),
+        )
+        .await
+        .unwrap();
+    assert!(!Fixture::is_error(&result));
+
+    let bindings = f.binding_repo.list_for_space(&f.space_id).await.unwrap();
+    assert_eq!(bindings.len(), 1, "must not insert a second binding row");
+    assert_eq!(bindings[0].id, starter.id, "must reuse existing binding id");
+    assert_eq!(bindings[0].workspace_root, normalized);
+    assert_eq!(
+        bindings[0].feature_set_ids,
+        vec![fs_full_id.to_string()]
+    );
+}
+
 #[tokio::test(flavor = "multi_thread")]
 async fn invalid_feature_set_argument_rejected() {
     let f = Fixture::new().await;

From 993f378324ace3a2843ed9c6385e64f0323a5a9d Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 14:37:17 -0600
Subject: [PATCH 37/48] docs(planning): add meta-gateway invoke manual QA
 runbook
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Single-session checklist with copy-paste prompts for Phases A–C validation.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 docs/planning/meta-gateway-invoke-qa.md | 299 ++++++++++++++++++++++++
 1 file changed, 299 insertions(+)
 create mode 100644 docs/planning/meta-gateway-invoke-qa.md

diff --git a/docs/planning/meta-gateway-invoke-qa.md b/docs/planning/meta-gateway-invoke-qa.md
new file mode 100644
index 00000000..f4fba68d
--- /dev/null
+++ b/docs/planning/meta-gateway-invoke-qa.md
@@ -0,0 +1,299 @@
+# Meta-Gateway Invoke — Manual QA Runbook
+
+**Last Updated:** May 25, 2026  
+**Branch:** `feat/meta-gateway-invoke`  
+**Related:** [`meta-gateway-invoke.md`](./meta-gateway-invoke.md)
+
+One-session checklist for validating Phases A–C (search → schema → invoke, result shaping, FeatureSet ACL + surfaced tools).
+
+---
+
+## Quick prep
+
+- [ ] Rebuild/restart gateway if you haven't since the branch (`pnpm dev` or run the built app)
+- [ ] Cursor → MCP → **Reload tools**
+- [ ] Confirm McpMux endpoint: `http://localhost:45818/mcp`
+- [ ] Have at least one OAuth server (GitHub) **installed and connected** but **inactive** in session (for enable-flow tests)
+- [ ] Optional for Phase C tests: create a FeatureSet with 1–2 GitHub tools, bind to workspace; leave surfaced off until test 7
+
+**Tester:** _______________  
+**Date:** _______________  
+**McpMux version / commit:** _______________
+
+---
+
+## 0. Sanity — meta-only surface
+
+**Prompt:**
+
+```
+You have McpMux meta tools only — no direct backend tools like github_*.
+
+1. Call mcpmux_list_servers and show installed servers and active/inactive status.
+2. Tell me how many tools you see in your available tool list total, and list their names.
+```
+
+| Check | Pass | Fail | Notes |
+| ----- | ---- | ---- | ----- |
+| `mcpmux_list_servers` returns installed servers | ☐ | ☐ | |
+| Only **10** `mcpmux_*` tools exposed (no backend names) | ☐ | ☐ | Expected: bind, create_feature_set, disable/enable_server, get_tool_schema, invoke_tool, list_all_tools, list_feature_sets, list_servers, search_tools |
+| Backend servers show **inactive** until enabled | ☐ | ☐ | |
+| Tool list count stable (~10 meta + Cursor/plugin tools) | ☐ | ☐ | |
+
+---
+
+## 1. Happy path — GitHub read (Phase A)
+
+**Prompt** (swap repo if needed):
+
+```
+Use ONLY the McpMux meta workflow — do not guess backend tool names or params.
+
+Goal: list open issues in mcpmux/mcp-mux.
+
+Steps you must follow explicitly:
+1. mcpmux_list_servers — check if github is active
+2. If inactive: mcpmux_enable_server for github
+3. mcpmux_search_tools with query "list issues", server_id "github", detail_level "description"
+4. mcpmux_get_tool_schema for the best match
+5. mcpmux_invoke_tool with exact args from the schema
+
+Show each step briefly, then the first 5 issues.
+```
+
+| Check | Pass | Fail | Notes |
+| ----- | ---- | ---- | ----- |
+| Agent enabled github when inactive | ☐ | ☐ | |
+| Search before invoke (no param guessing) | ☐ | ☐ | |
+| Schema read before invoke | ☐ | ☐ | |
+| Invoke succeeded with correct param names | ☐ | ☐ | |
+| `tools/list` still ~10 meta tools after enable | ☐ | ☐ | |
+
+---
+
+## 2. Fail-closed + recovery (Phase A errors)
+
+**Prompt:**
+
+```
+Try to invoke a GitHub tool WITHOUT enabling github first (disable it if needed).
+
+1. mcpmux_invoke_tool on github with tool list_issues and dummy args
+2. Show the exact error message
+3. Follow whatever it tells you to do
+4. Retry invoke successfully
+```
+
+| Check | Pass | Fail | Notes |
+| ----- | ---- | ---- | ----- |
+| Invoke denied when server inactive | ☐ | ☐ | |
+| Error mentions `mcpmux_enable_server` with server_id | ☐ | ☐ | |
+| Recovery via enable → retry works | ☐ | ☐ | |
+
+---
+
+## 3. Search detail levels + compact schema (Phase A)
+
+**Prompt:**
+
+```
+On github (enabled):
+
+1. mcpmux_search_tools query "list" detail_level "name" limit 5
+2. Same query detail_level "description"
+3. Pick one tool — mcpmux_get_tool_schema compact: true
+4. Same tool — compact: false
+
+What did compact strip?
+```
+
+| Check | Pass | Fail | Notes |
+| ----- | ---- | ---- | ----- |
+| `name` level omits descriptions | ☐ | ☐ | |
+| `description` level includes descriptions | ☐ | ☐ | |
+| `compact: true` strips descriptions/examples | ☐ | ☐ | |
+| Batch schema (array of tools) works if agent tries it | ☐ | ☐ | |
+
+---
+
+## 4. Session toggle — list size unchanged (Phase A)
+
+**Prompt:**
+
+```
+1. Enable github — confirm search finds github tools
+2. Disable github via mcpmux_disable_server
+3. Search again for github tools
+4. Report tools/list count before and after — must stay the same
+```
+
+| Check | Pass | Fail | Notes |
+| ----- | ---- | ---- | ----- |
+| Search empty / no github matches when disabled | ☐ | ☐ | |
+| Meta tool count unchanged across enable/disable | ☐ | ☐ | |
+
+---
+
+## 5. Default truncation (Phase B)
+
+**Setup:** Enable a heavy server — `posthog-personal`, `firebase-dev`, or GWorkspace clone.
+
+**Prompt:**
+
+```
+Enable [heavy server]. Find a list/analytics tool via search, read schema, invoke WITHOUT filter.
+
+Show whether response includes { returned, total, truncated: true } or similar metadata.
+Paste payload size estimate (rough char count is fine).
+```
+
+| Check | Pass | Fail | Notes |
+| ----- | ---- | ---- | ----- |
+| Large array auto-truncated | ☐ | ☐ | Default ~50 rows / 64KB |
+| Truncation metadata present | ☐ | ☐ | |
+
+---
+
+## 6. Explicit filter (Phase B)
+
+**Prompt:**
+
+```
+Same tool as test 5. Invoke with filter: { "max_rows": 3, "format": "summary" }
+
+Then again with fields projection if the tool returns objects with id/name/title fields.
+```
+
+| Check | Pass | Fail | Notes |
+| ----- | ---- | ---- | ----- |
+| `max_rows: 3` honored | ☐ | ☐ | |
+| `format: summary` applied | ☐ | ☐ | |
+| `fields` projection limits keys per row (if tested) | ☐ | ☐ | |
+
+---
+
+## 7. Clone disambiguation (server_id filter)
+
+**Setup:** You have GWorkspace ×2 clones — enable **only one**.
+
+**Prompt:**
+
+```
+Enable ONLY taylorwilsdon.google-workspace-mcp-uvx (not the s2h clone).
+
+mcpmux_search_tools query "drive" or "list files" with server_id set explicitly.
+Confirm results are scoped to that server_id only.
+```
+
+| Check | Pass | Fail | Notes |
+| ----- | ---- | ---- | ----- |
+| `server_id` filter scopes search | ☐ | ☐ | |
+| Other clone's tools not in results | ☐ | ☐ | |
+
+---
+
+## 8. FeatureSet ACL — partial tool set (Phase C)
+
+**Setup:** FeatureSet with 1–2 GitHub tools included, bound to workspace, surfaced **off**.
+
+**Prompt:**
+
+```
+I bound a FeatureSet that only allows specific GitHub tools.
+
+1. mcpmux_search_tools query "github" detail_level "name"
+2. Try mcpmux_invoke_tool on a tool NOT in the FeatureSet
+3. Invoke one tool that IS included
+```
+
+| Check | Pass | Fail | Notes |
+| ----- | ---- | ---- | ----- |
+| Search only finds allowed tools | ☐ | ☐ | |
+| Invoke denied for disallowed tool | ☐ | ☐ | |
+| Invoke succeeds for allowed tool | ☐ | ☐ | |
+
+---
+
+## 9. Surfaced tool promotion (Phase C)
+
+**Setup:** In FeatureSet editor, toggle **Surface in client** on one included tool. Reload MCP tools.
+
+**Prompt:**
+
+```
+1. List all tools available — identify mcpmux_* vs surfaced backend
+2. Call the surfaced tool directly (one hop)
+3. Call a different tool on same server via mcpmux_invoke_tool
+```
+
+| Check | Pass | Fail | Notes |
+| ----- | ---- | ---- | ----- |
+| Surfaced tool appears in client tool list | ☐ | ☐ | |
+| Surfaced tool callable without invoke wrapper | ☐ | ☐ | |
+| Non-surfaced backend still requires invoke | ☐ | ☐ | |
+
+---
+
+## 10. Diagnostic — list_all_tools vs search
+
+**Prompt:**
+
+```
+mcpmux_list_all_tools with server_id "github" (or one enabled server).
+Compare count to mcpmux_search_tools with query "" and same server_id.
+Explain why agents should prefer search.
+```
+
+| Check | Pass | Fail | Notes |
+| ----- | ---- | ---- | ----- |
+| `server_id` filter on list_all_tools works | ☐ | ☐ | |
+| Agent recommends search over full dump | ☐ | ☐ | |
+
+---
+
+## 11. End-to-end agent task (realism)
+
+**Prompt:**
+
+```
+Brief status report on mcpmux/mcp-mux repo:
+- open issue count
+- 3 most recent issue titles
+- one paragraph summary
+
+Rules: McpMux meta tools only, read schemas before invoke, note truncation if any.
+```
+
+| Check | Pass | Fail | Notes |
+| ----- | ---- | ---- | ----- |
+| Completed without backend tool name guessing | ☐ | ☐ | |
+| Schema-first invoke pattern | ☐ | ☐ | |
+| Sensible output despite truncation | ☐ | ☐ | |
+
+---
+
+## Red flags (stop and file a bug)
+
+- [ ] Backend tools (`github_*`, etc.) appear in `tools/list` without surfacing
+- [ ] Agent can call backend tools directly (bypassing `mcpmux_invoke_tool`)
+- [ ] Enable server expands `tools/list` beyond meta + surfaced
+- [ ] Search returns tools from inactive or unbound servers
+- [ ] Invoke succeeds for tools outside FeatureSet ACL
+- [ ] Large list invoke returns unbounded payload with no truncation metadata
+- [ ] Opaque errors (no enable/invoke redirect hints)
+
+---
+
+## Sign-off
+
+| Area | Result |
+| ---- | ------ |
+| Phase A — meta invoke core | ☐ Pass ☐ Fail |
+| Phase B — result shaping | ☐ Pass ☐ Fail |
+| Phase C — ACL + surfaced | ☐ Pass ☐ Fail ☐ Skipped |
+| Overall | ☐ Ship ☐ Block |
+
+**Blockers / issues filed:**
+
+```
+```

From c505b0755c80fa45b01163531c86e6faec6d1e49 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 14:41:15 -0600
Subject: [PATCH 38/48] docs(planning): reconcile meta-gateway invoke QA
 progress
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Mark Phases A–C implementation status in the planning doc and record
manual QA results for runbook sections 0–3.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 docs/planning/meta-gateway-invoke-qa.md |  48 +++++------
 docs/planning/meta-gateway-invoke.md    | 105 +++++++++++++-----------
 2 files changed, 83 insertions(+), 70 deletions(-)

diff --git a/docs/planning/meta-gateway-invoke-qa.md b/docs/planning/meta-gateway-invoke-qa.md
index f4fba68d..42ce099f 100644
--- a/docs/planning/meta-gateway-invoke-qa.md
+++ b/docs/planning/meta-gateway-invoke-qa.md
@@ -10,15 +10,15 @@ One-session checklist for validating Phases A–C (search → schema → invoke,
 
 ## Quick prep
 
-- [ ] Rebuild/restart gateway if you haven't since the branch (`pnpm dev` or run the built app)
-- [ ] Cursor → MCP → **Reload tools**
-- [ ] Confirm McpMux endpoint: `http://localhost:45818/mcp`
-- [ ] Have at least one OAuth server (GitHub) **installed and connected** but **inactive** in session (for enable-flow tests)
-- [ ] Optional for Phase C tests: create a FeatureSet with 1–2 GitHub tools, bind to workspace; leave surfaced off until test 7
+- [x] Rebuild/restart gateway if you haven't since the branch (`pnpm dev` or run the built app)
+- [x] Cursor → MCP → **Reload tools**
+- [x] Confirm McpMux endpoint: `http://localhost:45818/mcp`
+- [ ] Have at least one OAuth server (GitHub) **installed and connected** but **inactive** in session (for enable-flow tests) — github is `enabled_via_binding`; use session disable for test 2
+- [ ] Optional for Phase C tests: create a FeatureSet with 1–2 GitHub tools, bind to workspace; leave surfaced off until test 8
 
-**Tester:** _______________  
-**Date:** _______________  
-**McpMux version / commit:** _______________
+**Tester:** Cursor agent (Composer)  
+**Date:** May 25, 2026  
+**McpMux version / commit:** `feat/meta-gateway-invoke` @ `993f378`
 
 ---
 
@@ -35,10 +35,10 @@ You have McpMux meta tools only — no direct backend tools like github_*.
 
 | Check | Pass | Fail | Notes |
 | ----- | ---- | ---- | ----- |
-| `mcpmux_list_servers` returns installed servers | ☐ | ☐ | |
-| Only **10** `mcpmux_*` tools exposed (no backend names) | ☐ | ☐ | Expected: bind, create_feature_set, disable/enable_server, get_tool_schema, invoke_tool, list_all_tools, list_feature_sets, list_servers, search_tools |
-| Backend servers show **inactive** until enabled | ☐ | ☐ | |
-| Tool list count stable (~10 meta + Cursor/plugin tools) | ☐ | ☐ | |
+| `mcpmux_list_servers` returns installed servers | ☑ | ☐ | 34 servers returned |
+| Only **10** `mcpmux_*` tools exposed (no backend names) | ☑ | ☐ | Verified via MCP descriptor folder |
+| Backend servers show **inactive** until enabled | ☑ | ☐ | All inactive at session start |
+| Tool list count stable (~10 meta + Cursor/plugin tools) | ☑ | ☐ | No backend tools leaked |
 
 ---
 
@@ -63,11 +63,11 @@ Show each step briefly, then the first 5 issues.
 
 | Check | Pass | Fail | Notes |
 | ----- | ---- | ---- | ----- |
-| Agent enabled github when inactive | ☐ | ☐ | |
-| Search before invoke (no param guessing) | ☐ | ☐ | |
-| Schema read before invoke | ☐ | ☐ | |
-| Invoke succeeded with correct param names | ☐ | ☐ | |
-| `tools/list` still ~10 meta tools after enable | ☐ | ☐ | |
+| Agent enabled github when inactive | ☐ | ☐ | N/A — github was `enabled_via_binding` |
+| Search before invoke (no param guessing) | ☑ | ☐ | Found `github_list_issues` via search |
+| Schema read before invoke | ☑ | ☐ | Used `owner`/`repo`/`state`/`perPage` from schema |
+| Invoke succeeded with correct param names | ☑ | ☐ | 5 open issues returned for mcpmux/mcp-mux |
+| `tools/list` still ~10 meta tools after enable | ☑ | ☐ | Still exactly 10 `mcpmux_*` tools |
 
 ---
 
@@ -86,9 +86,9 @@ Try to invoke a GitHub tool WITHOUT enabling github first (disable it if needed)
 
 | Check | Pass | Fail | Notes |
 | ----- | ---- | ---- | ----- |
-| Invoke denied when server inactive | ☐ | ☐ | |
-| Error mentions `mcpmux_enable_server` with server_id | ☐ | ☐ | |
-| Recovery via enable → retry works | ☐ | ☐ | |
+| Invoke denied when server inactive | ☑ | ☐ | After `mcpmux_disable_server` → `disabled_via_session` |
+| Error mentions `mcpmux_enable_server` with server_id | ☑ | ☐ | `server 'github' is disabled for this session → mcpmux_enable_server({ "server_id": "github" })` |
+| Recovery via enable → retry works | ☑ | ☐ | enable + invoke returned 3 issues |
 
 ---
 
@@ -109,10 +109,10 @@ What did compact strip?
 
 | Check | Pass | Fail | Notes |
 | ----- | ---- | ---- | ----- |
-| `name` level omits descriptions | ☐ | ☐ | |
-| `description` level includes descriptions | ☐ | ☐ | |
-| `compact: true` strips descriptions/examples | ☐ | ☐ | |
-| Batch schema (array of tools) works if agent tries it | ☐ | ☐ | |
+| `name` level omits descriptions | ☑ | ☐ | `github_list_issues` — no `description` key |
+| `description` level includes descriptions | ☑ | ☐ | Full tool description present |
+| `compact: true` strips descriptions/examples | ☑ | ☐ | Strips **top-level** tool `description`; property descriptions in `input_schema` kept |
+| Batch schema (array of tools) works if agent tries it | ☑ | ☐ | `tools: ["github_list_issues"]` returned schemas array |
 
 ---
 
diff --git a/docs/planning/meta-gateway-invoke.md b/docs/planning/meta-gateway-invoke.md
index c391939f..fa4bad87 100644
--- a/docs/planning/meta-gateway-invoke.md
+++ b/docs/planning/meta-gateway-invoke.md
@@ -1,8 +1,8 @@
 # Meta-Gateway Invoke (Search → Schema → Invoke)
 
 **Last Updated:** May 25, 2026
-**Status:** Planning
-**Branch:** TBD — branch off `main`
+**Status:** Implemented on branch — manual QA in progress ([`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md))
+**Branch:** `feat/meta-gateway-invoke`
 **Base branch:** `main`
 **Issue:** TBD — file after planning review
 **Depends on:** [`dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) (session overrides + meta-tool registry); benefits from workspace bindings / FeatureSets from PR #151
@@ -160,28 +160,30 @@ Prompts and resources: unchanged — still materialized per grants. Invoke model
 
 ## Files to create
 
-| File | Purpose |
-| ---- | ------- |
-| `crates/mcpmux-gateway/src/services/tool_discovery.rs` | Index + search + schema lookup over Space tool features |
-| `crates/mcpmux-gateway/src/services/meta_tools/invoke.rs` | `InvokeToolTool` impl — permission check, routing, error mapping |
-| `tests/rust/tests/integration/meta_gateway_invoke.rs` | Search, schema, invoke, permission deny, surfaced tools, direct backend call rejected |
-| `docs/planning/meta-gateway-invoke.md` | This doc |
+| File | Purpose | Status |
+| ---- | ------- | ------ |
+| `crates/mcpmux-gateway/src/services/tool_discovery.rs` | Index + search + schema lookup over Space tool features | ✅ Done |
+| `crates/mcpmux-gateway/src/services/meta_tools/invoke.rs` | `InvokeToolTool` impl — permission check, routing, error mapping, result shaping | ✅ Done |
+| `tests/rust/tests/integration/meta_gateway_invoke.rs` | Search, schema, invoke, permission deny, surfaced tools, direct backend call rejected | ✅ Done (13 tests) |
+| `docs/planning/meta-gateway-invoke-qa.md` | Manual QA runbook for Phases A–C | ✅ Done |
+| `docs/planning/meta-gateway-invoke.md` | This doc | ✅ Done |
 
 ## Files to modify
 
-| File | Change |
-| ---- | ------ |
-| [`crates/mcpmux-gateway/src/services/mod.rs`](../../crates/mcpmux-gateway/src/services/mod.rs) | `pub mod tool_discovery;` |
-| [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | `SearchToolsTool`, `GetToolSchemaTool`; extend `ListAllToolsTool` with optional `server_id` filter |
-| [`crates/mcpmux-gateway/src/services/meta_tools/mod.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/mod.rs) | Register new tools; wire `ToolDiscoveryService` + `RoutingService` into `MetaToolContext` |
-| [`crates/mcpmux-gateway/src/services/meta_tools/registry.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/registry.rs) | Extend `MetaToolContext` with discovery + routing handles |
-| [`crates/mcpmux-gateway/src/pool/features/facade.rs`](../../crates/mcpmux-gateway/src/pool/features/facade.rs) | Split `get_tools_for_grants` into advertised (meta + surfaced) vs invokable (full set for search/invoke ACL) |
-| [`crates/mcpmux-gateway/src/pool/routing.rs`](../../crates/mcpmux-gateway/src/pool/routing.rs) | Shared invokable-set helper; ensure `call_tool` errors are actionable |
-| [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) | `tools/list` uses advertised set only; direct backend `call_tool` rejected with invoke redirect |
-| [`crates/mcpmux-storage/`](../../crates/mcpmux-storage/) or core domain | Optional `surfaced` flag on FeatureSet member rows (Phase C) — if schema change needed |
-| [`apps/desktop/src/features/settings/SettingsPage.tsx`](../../apps/desktop/src/features/settings/SettingsPage.tsx) | Update meta-tools copy for search → schema → invoke workflow |
-| [`apps/desktop/src/features/feature-sets/`](../../apps/desktop/src/features/feature-sets/) | UI to mark tools as surfaced (Phase C) |
-| [`README.md`](../../README.md) | Replace "every tool available right now" agent-facing claim; document search → schema → invoke flow |
+| File | Change | Status |
+| ---- | ------ | ------ |
+| [`crates/mcpmux-gateway/src/services/mod.rs`](../../crates/mcpmux-gateway/src/services/mod.rs) | `pub mod tool_discovery;` | ✅ Done |
+| [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | `SearchToolsTool`, `GetToolSchemaTool`; extend `ListAllToolsTool` with optional `server_id` filter | ✅ Done |
+| [`crates/mcpmux-gateway/src/services/meta_tools/mod.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/mod.rs) | Register new tools; wire `ToolDiscoveryService` + `RoutingService` into `MetaToolContext` | ✅ Done |
+| [`crates/mcpmux-gateway/src/services/meta_tools/registry.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/registry.rs) | Extend `MetaToolContext` with discovery + routing handles | ✅ Done |
+| [`crates/mcpmux-gateway/src/pool/features/facade.rs`](../../crates/mcpmux-gateway/src/pool/features/facade.rs) | Split into `get_advertised_tools_for_grants` vs `get_invokable_tools_for_grants` | ✅ Done |
+| [`crates/mcpmux-gateway/src/pool/features/resolution.rs`](../../crates/mcpmux-gateway/src/pool/features/resolution.rs) | `resolve_surfaced_feature_ids` for surfaced promotion | ✅ Done |
+| [`crates/mcpmux-gateway/src/pool/routing.rs`](../../crates/mcpmux-gateway/src/pool/routing.rs) | `format_direct_call_redirect`; actionable invoke errors | ✅ Done |
+| [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) | `tools/list` uses advertised set only; direct backend `call_tool` rejected with invoke redirect | ✅ Done |
+| [`crates/mcpmux-core/src/domain/feature_set.rs`](../../crates/mcpmux-core/src/domain/feature_set.rs) | `surfaced: bool` on `FeatureSetMember` | ✅ Done |
+| [`apps/desktop/src/features/featuresets/FeatureSetPanel.tsx`](../../apps/desktop/src/features/featuresets/FeatureSetPanel.tsx) | Per-tool "Surface in client" toggle | ✅ Done |
+| [`apps/desktop/src/features/settings/SettingsPage.tsx`](../../apps/desktop/src/features/settings/SettingsPage.tsx) | Update meta-tools copy for search → schema → invoke workflow | ⬜ Pending |
+| [`README.md`](../../README.md) | Replace "every tool available right now" agent-facing claim; document search → schema → invoke flow | ⬜ Pending |
 
 ---
 
@@ -189,42 +191,43 @@ Prompts and resources: unchanged — still materialized per grants. Invoke model
 
 ### Phase A — Meta invoke core
 
-**Effort:** ~3–4 days
+**Effort:** ~3–4 days  
+**Status:** ✅ Implemented — manual QA sections 0–1 pass; sections 2–4 pending ([`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md))
 
-- [ ] `ToolDiscoveryService` — build index from Space features; search by query + optional `server_id`; return matches at `detail_level`
-- [ ] `mcpmux_search_tools` meta tool — pagination (`limit`, `cursor`), `detail_level` enum
-- [ ] `mcpmux_get_tool_schema` — single + batch; `compact` strips descriptions/examples
-- [ ] `mcpmux_invoke_tool` — `{ server_id, tool, args }`; delegates to `RoutingService::call_tool`; fail closed on permission miss
-- [ ] `FeatureService` split: **advertised** = meta tools + surfaced only (hard cut — no backend tools in list)
-- [ ] Handler rejects direct backend `call_tool` — return actionable error pointing to `mcpmux_invoke_tool`
-- [ ] Actionable error mapping: inactive server, unknown tool, permission denied, param validation passthrough from backend
-- [ ] Optional `server_id` filter on `mcpmux_list_all_tools`
-- [ ] Integration tests: GitHub read path (enable → search → schema → invoke); deny when server inactive; direct `github_*` call rejected
+- [x] `ToolDiscoveryService` — build index from Space features; search by query + optional `server_id`; return matches at `detail_level`
+- [x] `mcpmux_search_tools` meta tool — pagination (`limit`, `cursor`), `detail_level` enum
+- [x] `mcpmux_get_tool_schema` — single + batch; `compact` strips descriptions/examples
+- [x] `mcpmux_invoke_tool` — `{ server_id, tool, args }`; delegates to `RoutingService::call_tool`; fail closed on permission miss
+- [x] `FeatureService` split: **advertised** = meta tools + surfaced only (hard cut — no backend tools in list)
+- [x] Handler rejects direct backend `call_tool` — return actionable error pointing to `mcpmux_invoke_tool`
+- [x] Actionable error mapping: inactive server, unknown tool, permission denied, param validation passthrough from backend
+- [x] Optional `server_id` filter on `mcpmux_list_all_tools`
+- [x] Integration tests: GitHub read path (enable → search → schema → invoke); deny when server inactive; direct `github_*` call rejected
 
-**Outcome:** Cursor session shows ~12 `mcpmux_*` tools. Agent completes `github_list_issues` on `mcpmux/mcp-mux` in 4 meta calls + invoke with zero param guessing. Token footprint for tool definitions drops from ~30–50k to ~1–2k.
+**Outcome:** Cursor session shows **10** `mcpmux_*` tools (verified May 25, 2026). Agent completes `github_list_issues` on `mcpmux/mcp-mux` via search → schema → invoke with zero param guessing.
 
 ### Phase B — Result shaping on invoke
 
-**Effort:** ~2 days
+**Effort:** ~2 days  
+**Status:** ✅ Implemented — manual QA sections 5–6 pending
 
-- [ ] Extend `mcpmux_invoke_tool` args with optional `filter: { max_rows?, max_bytes?, fields?, format? }`
-- [ ] Post-process JSON/text results in gateway before returning to client
-- [ ] Default smart truncation for known-heavy patterns (large arrays) when filter omitted
-- [ ] Integration tests: truncated list response includes `{ returned, total, truncated: true }`
+- [x] Extend `mcpmux_invoke_tool` args with optional `filter: { max_rows?, max_bytes?, fields?, format? }`
+- [x] Post-process JSON/text results in gateway before returning to client
+- [x] Default smart truncation for known-heavy patterns (large arrays) when filter omitted (`DEFAULT_MAX_ROWS` = 50)
+- [x] Integration tests: truncated list response includes `{ returned, total, truncated: true }`
 
 **Outcome:** Posthog/Firebase/GWorkspace list calls return bounded payloads. Agent can query large backends without blowing context on results.
 
 ### Phase C — FeatureSet as invoke ACL + surfaced tools
 
-**Effort:** ~3 days
-
-- [ ] FeatureSet member model: tools invokable by default when server in set; optional `surfaced: true` promotes into `tools/list`
-- [ ] Search + invoke respect FeatureSet member filter (not just server-all)
-- [ ] Workspaces UI: per-tool "Surface in client" toggle in FeatureSet editor
-- [ ] Update `mcpmux_create_feature_set` to accept optional `surfaced_tools[]`
-- [ ] Integration tests: binding with partial tool set → search only finds allowed tools; surfaced tool appears in `tools/list`
+**Effort:** ~3 days  
+**Status:** ✅ Implemented — manual QA sections 8–9 pending
 
-**Outcome:** Bundles ship with zero surfaced tools by default. Users may opt in per FeatureSet. Invoke ACL semantics are unambiguous: **permission + optional promotion**.
+- [x] FeatureSet member model: tools invokable by default when server in set; optional `surfaced: true` promotes into `tools/list`
+- [x] Search + invoke respect FeatureSet member filter (not just server-all)
+- [x] Workspaces UI: per-tool "Surface in client" toggle in FeatureSet editor (`FeatureSetPanel.tsx`)
+- [ ] Update `mcpmux_create_feature_set` to accept optional `surfaced_tools[]` (UI path done; meta-tool arg deferred)
+- [x] Integration tests: binding with partial tool set → search only finds allowed tools; surfaced tool appears in `tools/list`
 
 ### Phase D — Advanced optimizations (defer)
 
@@ -307,6 +310,16 @@ Prompts and resources: unchanged — still materialized per grants. Invoke model
 
 ## Reconciliation
 
-This doc is the source of truth for the meta-gateway invoke model. When implementation starts, update **Status** and **Branch** at the top. Mark [`tool-level-session-pin.md`](./tool-level-session-pin.md) **Status** as *Superseded* once Phase A ships.
+This doc is the source of truth for the meta-gateway invoke model. Phases A–C are implemented on `feat/meta-gateway-invoke`; manual QA tracked in [`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md). Mark [`tool-level-session-pin.md`](./tool-level-session-pin.md) **Status** as *Superseded* once Phase A ships to main.
 
 **Decision record (May 25, 2026):** Hard cut to invoke-only — no legacy direct backend exposure. Surfaced tools default zero everywhere (bundles included). FeatureSets redefine as invoke ACL + optional surfaced promotion. Session pin deferred to Phase F (very optional, last). Competitor analysis (MikkoParkkola + abdullah1854) informed Phase A–B scope; REST capabilities in Phase E / separate doc.
+
+**Manual QA progress (May 25, 2026):**
+
+| QA section | Result | Notes |
+| ---------- | ------ | ----- |
+| 0 — Sanity (meta-only surface) | ✅ Pass | 10 `mcpmux_*` tools; 34 servers listed; all inactive until enabled |
+| 1 — Happy path (GitHub read) | ✅ Pass | search → schema → invoke returned 5 open issues; enable step N/A (`enabled_via_binding`) |
+| 2 — Fail-closed + recovery | ✅ Pass | Session disable → actionable error → enable → retry |
+| 3 — Search detail levels + compact schema | ✅ Pass | compact omits top-level description only |
+| 4–11 | ⬜ Pending | In progress |

From 433e7bdbf5b7fd860ea7fc350f15b36ef16d42bf Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 14:53:51 -0600
Subject: [PATCH 39/48] fix(gateway): make invoke result truncation opt-in via
 filter

Remove default row/byte shaping when filter is omitted so backends
return payloads as-is. Explicit filter still bounds JSON arrays and
plain text with returned/total/truncated metadata.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 .../src/services/meta_tools/invoke.rs         | 138 ++++++++----------
 docs/planning/meta-gateway-invoke-qa.md       |  31 ++--
 docs/planning/meta-gateway-invoke.md          |  16 +-
 .../tests/integration/meta_gateway_invoke.rs  |  32 ++--
 4 files changed, 112 insertions(+), 105 deletions(-)

diff --git a/crates/mcpmux-gateway/src/services/meta_tools/invoke.rs b/crates/mcpmux-gateway/src/services/meta_tools/invoke.rs
index 9365f584..598b6efa 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/invoke.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/invoke.rs
@@ -10,12 +10,6 @@ use crate::pool::{format_invoke_permission_denied, format_server_inactive_error}
 use crate::services::tool_discovery::ToolDiscoveryService;
 use mcpmux_core::FeatureType;
 
-/// Default row cap for smart truncation when `filter` is omitted.
-pub const DEFAULT_MAX_ROWS: usize = 50;
-
-/// Default byte cap for smart truncation when `filter` is omitted.
-pub const DEFAULT_MAX_BYTES: usize = 65_536;
-
 /// Object keys that commonly hold large list payloads from backend tools.
 const HEAVY_ARRAY_KEYS: &[&str] = &[
     "items", "data", "results", "rows", "records", "issues", "entries", "values", "list",
@@ -61,16 +55,6 @@ pub fn parse_invoke_filter(value: Option<&Value>) -> Option<InvokeResultFilter>
 }
 
 impl InvokeResultFilter {
-    fn effective_max_rows(&self, use_defaults: bool) -> Option<usize> {
-        self.max_rows
-            .or_else(|| use_defaults.then_some(DEFAULT_MAX_ROWS))
-    }
-
-    fn effective_max_bytes(&self, use_defaults: bool) -> Option<usize> {
-        self.max_bytes
-            .or_else(|| use_defaults.then_some(DEFAULT_MAX_BYTES))
-    }
-
     fn is_summary(&self) -> bool {
         self.format.as_deref() == Some("summary")
     }
@@ -80,14 +64,12 @@ impl InvokeResultFilter {
 pub fn apply_invoke_result_filter(
     content: Vec<Value>,
     structured_content: Option<Value>,
-    filter: Option<&InvokeResultFilter>,
-    use_defaults: bool,
+    filter: &InvokeResultFilter,
 ) -> (Vec<Value>, Option<Value>) {
-    let filter = filter.cloned().unwrap_or_default();
-    let shaped_structured = structured_content.map(|value| shape_json_value(value, &filter, use_defaults));
+    let shaped_structured = structured_content.map(|value| shape_json_value(value, filter));
     let shaped_content = content
         .into_iter()
-        .map(|block| shape_content_block(block, &filter, use_defaults))
+        .map(|block| shape_content_block(block, filter))
         .collect();
     (shaped_content, shaped_structured)
 }
@@ -105,8 +87,8 @@ impl MetaTool for InvokeToolTool {
         "Invoke a backend MCP tool by server_id and tool name. Requires the \
          server to be active (binding or session enable) and the tool to be \
          in the current permission set. Use mcpmux_search_tools and \
-         mcpmux_get_tool_schema before calling. Large list payloads are \
-         truncated by default; pass an optional filter object to control shaping."
+         mcpmux_get_tool_schema before calling. Pass an optional filter object \
+         to bound large payloads; omit filter to return the backend response as-is."
     }
 
     fn input_schema(&self) -> Value {
@@ -129,7 +111,7 @@ impl MetaTool for InvokeToolTool {
                 },
                 "filter": {
                     "type": "object",
-                    "description": "Optional result shaping. When omitted, large arrays are truncated with returned/total/truncated metadata.",
+                    "description": "Optional result shaping (max_rows, max_bytes, fields, format). Omit to return the backend response as-is.",
                     "properties": {
                         "max_rows": {
                             "type": "integer",
@@ -176,7 +158,6 @@ impl MetaTool for InvokeToolTool {
             .to_string();
         let args = call.args.get("args").cloned().unwrap_or_else(|| json!({}));
         let filter = parse_invoke_filter(call.args.get("filter"));
-        let use_defaults = call.args.get("filter").is_none();
 
         let resolved = caller_resolution(&call).await?;
         let space_id = caller_space_id(&call).await?;
@@ -292,12 +273,11 @@ impl MetaTool for InvokeToolTool {
                     return Ok(mcp_result);
                 }
 
-                let (content, structured_content) = apply_invoke_result_filter(
-                    result.content,
-                    result.structured_content,
-                    filter.as_ref(),
-                    use_defaults,
-                );
+                let (content, structured_content) = if let Some(ref filter) = filter {
+                    apply_invoke_result_filter(result.content, result.structured_content, filter)
+                } else {
+                    (result.content, result.structured_content)
+                };
                 let parsed_content: Vec<Content> = content
                     .into_iter()
                     .filter_map(|v| serde_json::from_value(v).ok())
@@ -312,62 +292,60 @@ impl MetaTool for InvokeToolTool {
 }
 
 /// Shape one MCP content block (typically `{ "type": "text", "text": "..." }`).
-fn shape_content_block(block: Value, filter: &InvokeResultFilter, use_defaults: bool) -> Value {
+fn shape_content_block(block: Value, filter: &InvokeResultFilter) -> Value {
     let Some(text) = block.get("text").and_then(|v| v.as_str()) else {
         return block;
     };
 
     if let Ok(parsed) = serde_json::from_str::<Value>(text) {
-        let shaped = shape_json_value(parsed, filter, use_defaults);
+        let shaped = shape_json_value(parsed, filter);
         return json!({
             "type": "text",
             "text": shaped.to_string(),
         });
     }
 
-    let max_bytes = filter.effective_max_bytes(use_defaults);
-    let Some(max_bytes) = max_bytes else {
+    let Some(max_bytes) = filter.max_bytes else {
         return block;
     };
     if text.len() <= max_bytes {
         return block;
     }
 
-    let mut truncated = text[..max_bytes].to_string();
-    truncated.push_str("\n...[truncated]");
+    let envelope = byte_truncation_envelope(text, max_bytes);
     json!({
         "type": "text",
-        "text": truncated,
+        "text": envelope.to_string(),
     })
 }
 
-/// Shape a JSON value, applying smart truncation for large arrays when enabled.
-pub fn shape_json_value(value: Value, filter: &InvokeResultFilter, use_defaults: bool) -> Value {
+/// Shape a JSON value, applying truncation when explicit filter limits are set.
+pub fn shape_json_value(value: Value, filter: &InvokeResultFilter) -> Value {
     match value {
-        Value::Array(items) => shape_array(items, filter, use_defaults, "items"),
-        Value::Object(map) => shape_object(map, filter, use_defaults),
-        other => enforce_byte_limit(other, filter, use_defaults),
+        Value::Array(items) => shape_array(items, filter, "items"),
+        Value::Object(map) => shape_object(map, filter),
+        other => enforce_byte_limit(other, filter),
     }
 }
 
-fn shape_object(map: Map<String, Value>, filter: &InvokeResultFilter, use_defaults: bool) -> Value {
+fn shape_object(map: Map<String, Value>, filter: &InvokeResultFilter) -> Value {
     for key in HEAVY_ARRAY_KEYS {
         if let Some(Value::Array(items)) = map.get(*key).cloned() {
-            if should_truncate(items.len(), filter, use_defaults) {
-                return shape_object_with_truncated_array(map, key, items, filter, use_defaults);
+            if should_truncate(items.len(), filter) {
+                return shape_object_with_truncated_array(map, key, items, filter);
             }
         }
     }
 
     for (key, value) in &map {
         if let Value::Array(items) = value {
-            if should_truncate(items.len(), filter, use_defaults) {
-                return shape_object_with_truncated_array(map.clone(), key, items.clone(), filter, use_defaults);
+            if should_truncate(items.len(), filter) {
+                return shape_object_with_truncated_array(map.clone(), key, items.clone(), filter);
             }
         }
     }
 
-    enforce_byte_limit(Value::Object(map), filter, use_defaults)
+    enforce_byte_limit(Value::Object(map), filter)
 }
 
 fn shape_object_with_truncated_array(
@@ -375,9 +353,8 @@ fn shape_object_with_truncated_array(
     array_key: &str,
     items: Vec<Value>,
     filter: &InvokeResultFilter,
-    use_defaults: bool,
 ) -> Value {
-    let shaped_array = shape_array(items, filter, use_defaults, array_key);
+    let shaped_array = shape_array(items, filter, array_key);
     if let Value::Object(truncation) = &shaped_array {
         if truncation.get("truncated") == Some(&Value::Bool(true)) {
             for (meta_key, meta_value) in truncation {
@@ -388,25 +365,19 @@ fn shape_object_with_truncated_array(
             if let Some(data) = truncation.get(array_key) {
                 map.insert(array_key.to_string(), data.clone());
             }
-            return enforce_byte_limit(Value::Object(map), filter, use_defaults);
+            return enforce_byte_limit(Value::Object(map), filter);
         }
     }
 
     map.insert(array_key.to_string(), shaped_array);
-    enforce_byte_limit(Value::Object(map), filter, use_defaults)
+    enforce_byte_limit(Value::Object(map), filter)
 }
 
-fn shape_array(
-    items: Vec<Value>,
-    filter: &InvokeResultFilter,
-    use_defaults: bool,
-    data_key: &str,
-) -> Value {
+fn shape_array(items: Vec<Value>, filter: &InvokeResultFilter, data_key: &str) -> Value {
     let total = items.len();
     let filtered_items = apply_fields_filter(items, filter);
-    let max_rows = filter.effective_max_rows(use_defaults);
 
-    let Some(max_rows) = max_rows else {
+    let Some(max_rows) = filter.max_rows else {
         return Value::Array(filtered_items);
     };
 
@@ -455,15 +426,15 @@ fn pick_fields(value: Value, fields: &[String]) -> Value {
     Value::Object(picked)
 }
 
-fn should_truncate(length: usize, filter: &InvokeResultFilter, use_defaults: bool) -> bool {
-    match filter.effective_max_rows(use_defaults) {
+fn should_truncate(length: usize, filter: &InvokeResultFilter) -> bool {
+    match filter.max_rows {
         Some(max_rows) => length > max_rows,
         None => false,
     }
 }
 
-fn enforce_byte_limit(value: Value, filter: &InvokeResultFilter, use_defaults: bool) -> Value {
-    let Some(max_bytes) = filter.effective_max_bytes(use_defaults) else {
+fn enforce_byte_limit(value: Value, filter: &InvokeResultFilter) -> Value {
+    let Some(max_bytes) = filter.max_bytes else {
         return value;
     };
 
@@ -472,8 +443,13 @@ fn enforce_byte_limit(value: Value, filter: &InvokeResultFilter, use_defaults: b
         return value;
     }
 
-    let total_bytes = serialized.len();
-    let mut truncated = serialized;
+    byte_truncation_envelope(&serialized, max_bytes)
+}
+
+/// Build a `{ returned, total, truncated, text }` envelope for byte-capped plain text or JSON.
+fn byte_truncation_envelope(text: &str, max_bytes: usize) -> Value {
+    let total_bytes = text.len();
+    let mut truncated = text.to_string();
     truncated.truncate(max_bytes);
     truncated.push_str("...[truncated]");
     json!({
@@ -498,22 +474,20 @@ mod tests {
     use super::*;
 
     #[test]
-    fn default_truncates_large_top_level_array() {
+    fn no_filter_passes_through_large_array() {
         let items: Vec<Value> = (0..100).map(|i| json!({ "id": i, "name": format!("n{i}") })).collect();
-        let shaped = shape_json_value(Value::Array(items), &InvokeResultFilter::default(), true);
-        assert_eq!(shaped.get("returned"), Some(&json!(50)));
-        assert_eq!(shaped.get("total"), Some(&json!(100)));
-        assert_eq!(shaped.get("truncated"), Some(&json!(true)));
+        let shaped = shape_json_value(Value::Array(items.clone()), &InvokeResultFilter::default());
+        assert_eq!(shaped, Value::Array(items));
     }
 
     #[test]
-    fn explicit_max_rows_overrides_default() {
+    fn explicit_max_rows_truncates() {
         let items: Vec<Value> = (0..20).map(|i| json!({ "id": i })).collect();
         let filter = InvokeResultFilter {
             max_rows: Some(3),
             ..Default::default()
         };
-        let shaped = shape_json_value(Value::Array(items), &filter, false);
+        let shaped = shape_json_value(Value::Array(items), &filter);
         assert_eq!(shaped.get("returned"), Some(&json!(3)));
         assert_eq!(shaped.get("total"), Some(&json!(20)));
         assert_eq!(shaped.get("truncated"), Some(&json!(true)));
@@ -529,9 +503,23 @@ mod tests {
             fields: Some(vec!["id".into(), "name".into()]),
             ..Default::default()
         };
-        let shaped = shape_json_value(Value::Array(items), &filter, false);
+        let shaped = shape_json_value(Value::Array(items), &filter);
         let kept = shaped.as_array().unwrap();
         assert_eq!(kept[0], json!({ "id": 1, "name": "a" }));
         assert_eq!(kept[1], json!({ "id": 2, "name": "b" }));
     }
+
+    #[test]
+    fn plain_text_byte_trunc_includes_metadata() {
+        let text = "x".repeat(100);
+        let filter = InvokeResultFilter {
+            max_bytes: Some(50),
+            ..Default::default()
+        };
+        let block = json!({ "type": "text", "text": text });
+        let shaped = shape_content_block(block, &filter);
+        let parsed: Value = serde_json::from_str(shaped.get("text").unwrap().as_str().unwrap()).unwrap();
+        assert_eq!(parsed.get("truncated"), Some(&json!(true)));
+        assert_eq!(parsed.get("total"), Some(&json!(100)));
+    }
 }
diff --git a/docs/planning/meta-gateway-invoke-qa.md b/docs/planning/meta-gateway-invoke-qa.md
index 42ce099f..fcab4067 100644
--- a/docs/planning/meta-gateway-invoke-qa.md
+++ b/docs/planning/meta-gateway-invoke-qa.md
@@ -129,44 +129,49 @@ What did compact strip?
 
 | Check | Pass | Fail | Notes |
 | ----- | ---- | ---- | ----- |
-| Search empty / no github matches when disabled | ☐ | ☐ | |
-| Meta tool count unchanged across enable/disable | ☐ | ☐ | |
+| Search empty / no github matches when disabled | ☑ | ☐ | `total: 0`, `tools: []` after session disable |
+| Meta tool count unchanged across enable/disable | ☑ | ☐ | 10 `mcpmux_*` before and after |
 
 ---
 
-## 5. Default truncation (Phase B)
+## 5. Pass-through without filter (Phase B)
 
-**Setup:** Enable a heavy server — `posthog-personal`, `firebase-dev`, or GWorkspace clone.
+**Setup:** GWorkspace Personal bound (`taylorwilsdon.google-workspace-mcp-uvx`) or any heavy server in FeatureSet ACL.
 
 **Prompt:**
 
 ```
-Enable [heavy server]. Find a list/analytics tool via search, read schema, invoke WITHOUT filter.
+Find a list tool via search (e.g. GWorkspace list_drive_items), read schema, invoke WITHOUT filter.
 
-Show whether response includes { returned, total, truncated: true } or similar metadata.
-Paste payload size estimate (rough char count is fine).
+Confirm the full backend response is returned with no { returned, total, truncated } metadata.
+Paste rough char count.
 ```
 
 | Check | Pass | Fail | Notes |
 | ----- | ---- | ---- | ----- |
-| Large array auto-truncated | ☐ | ☐ | Default ~50 rows / 64KB |
-| Truncation metadata present | ☐ | ☐ | |
+| Full backend response returned | ☐ | ☐ | |
+| No truncation metadata without filter | ☐ | ☐ | Design: opt-in filter only (May 25) |
 
 ---
 
 ## 6. Explicit filter (Phase B)
 
+**Setup:** Same tool as test 5, or GitHub `list_issues` for JSON row truncation.
+
 **Prompt:**
 
 ```
-Same tool as test 5. Invoke with filter: { "max_rows": 3, "format": "summary" }
+Invoke with filter: { "max_rows": 3, "format": "summary" }
+
+For plain-text tools (GWorkspace), also try filter: { "max_bytes": 4096 }.
 
-Then again with fields projection if the tool returns objects with id/name/title fields.
+Then fields projection if the tool returns JSON objects with id/name/title fields.
 ```
 
 | Check | Pass | Fail | Notes |
 | ----- | ---- | ---- | ----- |
-| `max_rows: 3` honored | ☐ | ☐ | |
+| `max_rows: 3` honored (JSON tools) | ☐ | ☐ | |
+| `max_bytes` honored with metadata (plain text) | ☐ | ☐ | |
 | `format: summary` applied | ☐ | ☐ | |
 | `fields` projection limits keys per row (if tested) | ☐ | ☐ | |
 
@@ -279,7 +284,7 @@ Rules: McpMux meta tools only, read schemas before invoke, note truncation if an
 - [ ] Enable server expands `tools/list` beyond meta + surfaced
 - [ ] Search returns tools from inactive or unbound servers
 - [ ] Invoke succeeds for tools outside FeatureSet ACL
-- [ ] Large list invoke returns unbounded payload with no truncation metadata
+- [ ] Invoke with explicit filter fails to truncate or return metadata
 - [ ] Opaque errors (no enable/invoke redirect hints)
 
 ---
diff --git a/docs/planning/meta-gateway-invoke.md b/docs/planning/meta-gateway-invoke.md
index fa4bad87..5f32c0d6 100644
--- a/docs/planning/meta-gateway-invoke.md
+++ b/docs/planning/meta-gateway-invoke.md
@@ -53,7 +53,7 @@ This doc defines that model for McpMux while preserving its product strengths: O
 | 9 | Error messages | **Actionable, bounded errors** — no dumping full available-tool lists | e.g. `"github inactive → mcpmux_enable_server('github')"`, `"unknown tool → did you mean github_list_issues?"`. Optional Levenshtein suggestions (Phase D). |
 | 10 | Rollout | **Hard cut — no legacy opt-out** | Backend tools never appear in `tools/list`. Direct `call_tool` on backend qualified names is rejected with an actionable redirect to `mcpmux_invoke_tool`. No `expose_backend_tools_in_list` setting. Ship in one release; document migration in CHANGELOG. |
 | 11 | `mcpmux_list_all_tools` | **Keep as operator/diagnostic tool** — not the primary agent discovery path | Still useful for FeatureSet authoring and UI. Doc + descriptions steer agents to `search_tools`. Consider server_id filter arg in Phase A to avoid 855 KB dumps. |
-| 12 | Result shaping scope | **Phase B only on `invoke_tool`** — `max_rows`, `max_bytes`, `fields`, `format: summary`** | Highest ROI after invoke model. Defer delta responses, auto-summarize, sandbox code exec to Phase D. |
+| 12 | Result shaping scope | **Phase B only on `invoke_tool`** — opt-in via explicit `filter`: `max_rows`, `max_bytes`, `fields`, `format: summary`. Omit filter → backend response as-is. | Agents pass `filter` when they know a tool returns large payloads. No default truncation. |
 | 13 | REST / OpenAPI capabilities | **Out of scope here** — Phase E / separate planning doc | [`web-admin-remote-access.md`](./web-admin-remote-access.md) covers admin REST, not REST→MCP capability YAML. No conflict; different layer. |
 
 ---
@@ -212,11 +212,11 @@ Prompts and resources: unchanged — still materialized per grants. Invoke model
 **Status:** ✅ Implemented — manual QA sections 5–6 pending
 
 - [x] Extend `mcpmux_invoke_tool` args with optional `filter: { max_rows?, max_bytes?, fields?, format? }`
-- [x] Post-process JSON/text results in gateway before returning to client
-- [x] Default smart truncation for known-heavy patterns (large arrays) when filter omitted (`DEFAULT_MAX_ROWS` = 50)
-- [x] Integration tests: truncated list response includes `{ returned, total, truncated: true }`
+- [x] Post-process JSON/text results in gateway when `filter` is provided
+- [x] Opt-in truncation only — omit `filter` to return backend response unchanged (May 25 design revision)
+- [x] Integration tests: explicit filter returns `{ returned, total, truncated: true }`; no filter pass-through
 
-**Outcome:** Posthog/Firebase/GWorkspace list calls return bounded payloads. Agent can query large backends without blowing context on results.
+**Outcome:** Agents pass `filter` on known-heavy tools (GWorkspace drive lists, GitHub issues, PostHog events). Plain-text and JSON backends both supported when filter is explicit.
 
 ### Phase C — FeatureSet as invoke ACL + surfaced tools
 
@@ -314,6 +314,8 @@ This doc is the source of truth for the meta-gateway invoke model. Phases A–C
 
 **Decision record (May 25, 2026):** Hard cut to invoke-only — no legacy direct backend exposure. Surfaced tools default zero everywhere (bundles included). FeatureSets redefine as invoke ACL + optional surfaced promotion. Session pin deferred to Phase F (very optional, last). Competitor analysis (MikkoParkkola + abdullah1854) informed Phase A–B scope; REST capabilities in Phase E / separate doc.
 
+**Design revision (May 25, 2026):** Removed default smart truncation — `filter` is opt-in only. Rationale: plain-text MCP backends (GWorkspace) don't map cleanly to JSON row truncation; agents should explicitly bound payloads when needed.
+
 **Manual QA progress (May 25, 2026):**
 
 | QA section | Result | Notes |
@@ -322,4 +324,6 @@ This doc is the source of truth for the meta-gateway invoke model. Phases A–C
 | 1 — Happy path (GitHub read) | ✅ Pass | search → schema → invoke returned 5 open issues; enable step N/A (`enabled_via_binding`) |
 | 2 — Fail-closed + recovery | ✅ Pass | Session disable → actionable error → enable → retry |
 | 3 — Search detail levels + compact schema | ✅ Pass | compact omits top-level description only |
-| 4–11 | ⬜ Pending | In progress |
+| 4 — Session toggle (list size unchanged) | ✅ Pass | search empty when disabled; 10 meta tools stable |
+| 5 — Pass-through without filter (Phase B) | ⬜ Pending | invoke without filter → full backend response, no metadata |
+| 6 — Explicit filter (Phase B) | ⬜ Pending | primary truncation test path |
diff --git a/tests/rust/tests/integration/meta_gateway_invoke.rs b/tests/rust/tests/integration/meta_gateway_invoke.rs
index 7b09e5c6..2964ecc5 100644
--- a/tests/rust/tests/integration/meta_gateway_invoke.rs
+++ b/tests/rust/tests/integration/meta_gateway_invoke.rs
@@ -11,7 +11,6 @@ use mcpmux_core::{
 use mcpmux_gateway::pool::{format_direct_call_redirect, FeatureService};
 use mcpmux_gateway::services::meta_tools::invoke::{
     apply_invoke_result_filter, parse_invoke_filter, shape_json_value, InvokeResultFilter,
-    DEFAULT_MAX_ROWS,
 };
 use mcpmux_gateway::services::{
     meta_tools, ApprovalBroker, FeatureSetResolverService, MetaToolRegistry, PrefixCacheService,
@@ -351,17 +350,14 @@ async fn invoke_input_schema_includes_filter() {
 }
 
 #[tokio::test(flavor = "multi_thread")]
-async fn invoke_result_default_truncates_large_list() {
+async fn invoke_result_no_filter_passes_through() {
     let items: Vec<Value> = (0..100).map(|i| json!({ "id": i })).collect();
-    let payload = json!({ "items": items });
+    let payload = json!({ "items": items.clone() });
 
-    let shaped = shape_json_value(payload, &InvokeResultFilter::default(), true);
+    let shaped = shape_json_value(payload, &InvokeResultFilter::default());
 
-    assert_eq!(shaped.get("returned"), Some(&json!(DEFAULT_MAX_ROWS)));
-    assert_eq!(shaped.get("total"), Some(&json!(100)));
-    assert_eq!(shaped.get("truncated"), Some(&json!(true)));
-    let truncated_items = shaped.get("items").and_then(|v| v.as_array()).unwrap();
-    assert_eq!(truncated_items.len(), DEFAULT_MAX_ROWS);
+    assert_eq!(shaped.get("items").and_then(|v| v.as_array()).unwrap().len(), 100);
+    assert!(shaped.get("truncated").is_none());
 }
 
 #[tokio::test(flavor = "multi_thread")]
@@ -369,7 +365,7 @@ async fn invoke_result_explicit_filter_limits_rows() {
     let items: Vec<Value> = (0..30).map(|i| json!({ "id": i, "label": format!("row-{i}") })).collect();
     let filter = parse_invoke_filter(Some(&json!({ "max_rows": 5, "fields": ["id"] }))).unwrap();
 
-    let shaped = shape_json_value(Value::Array(items), &filter, false);
+    let shaped = shape_json_value(Value::Array(items), &filter);
 
     assert_eq!(shaped.get("returned"), Some(&json!(5)));
     assert_eq!(shaped.get("total"), Some(&json!(30)));
@@ -388,7 +384,7 @@ async fn invoke_result_filter_shapes_text_content_blocks() {
     })];
     let filter = parse_invoke_filter(Some(&json!({ "max_rows": 10 }))).unwrap();
 
-    let (shaped_content, _) = apply_invoke_result_filter(content, None, Some(&filter), false);
+    let (shaped_content, _) = apply_invoke_result_filter(content, None, &filter);
     let text = shaped_content[0].get("text").and_then(|t| t.as_str()).unwrap();
     let parsed: Value = serde_json::from_str(text).unwrap();
 
@@ -397,6 +393,20 @@ async fn invoke_result_filter_shapes_text_content_blocks() {
     assert_eq!(parsed.get("truncated"), Some(&json!(true)));
 }
 
+#[tokio::test(flavor = "multi_thread")]
+async fn invoke_result_explicit_max_bytes_plain_text() {
+    let text = "x".repeat(200);
+    let content = vec![json!({ "type": "text", "text": text })];
+    let filter = parse_invoke_filter(Some(&json!({ "max_bytes": 80 }))).unwrap();
+
+    let (shaped_content, _) = apply_invoke_result_filter(content, None, &filter);
+    let parsed: Value =
+        serde_json::from_str(shaped_content[0].get("text").and_then(|t| t.as_str()).unwrap()).unwrap();
+
+    assert_eq!(parsed.get("truncated"), Some(&json!(true)));
+    assert_eq!(parsed.get("total"), Some(&json!(200)));
+}
+
 #[tokio::test(flavor = "multi_thread")]
 async fn partial_feature_set_binding_limits_search_and_invoke() {
     let f = Fixture::new().await;

From 01b60e3fc496645623633663fd175d1afad50360 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 14:57:30 -0600
Subject: [PATCH 40/48] docs(planning): record Phase 5 QA pass and PR #155

Reconcile invoke planning docs with manual QA through section 5 and
opt-in filter truncation at 433e7bd.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 docs/planning/meta-gateway-invoke-qa.md | 11 ++++++-----
 docs/planning/meta-gateway-invoke.md    | 15 +++++++++------
 2 files changed, 15 insertions(+), 11 deletions(-)

diff --git a/docs/planning/meta-gateway-invoke-qa.md b/docs/planning/meta-gateway-invoke-qa.md
index fcab4067..feb7a88a 100644
--- a/docs/planning/meta-gateway-invoke-qa.md
+++ b/docs/planning/meta-gateway-invoke-qa.md
@@ -14,11 +14,12 @@ One-session checklist for validating Phases A–C (search → schema → invoke,
 - [x] Cursor → MCP → **Reload tools**
 - [x] Confirm McpMux endpoint: `http://localhost:45818/mcp`
 - [ ] Have at least one OAuth server (GitHub) **installed and connected** but **inactive** in session (for enable-flow tests) — github is `enabled_via_binding`; use session disable for test 2
+- [x] Workspace binding with GWorkspace (or target server) configured in UI — **not** via agent `mcpmux_bind_current_workspace`
 - [ ] Optional for Phase C tests: create a FeatureSet with 1–2 GitHub tools, bind to workspace; leave surfaced off until test 8
 
 **Tester:** Cursor agent (Composer)  
 **Date:** May 25, 2026  
-**McpMux version / commit:** `feat/meta-gateway-invoke` @ `993f378`
+**McpMux version / commit:** `feat/meta-gateway-invoke` @ `433e7bd` (PR [#155](https://github.com/mcpmux/mcp-mux/pull/155))
 
 ---
 
@@ -149,8 +150,8 @@ Paste rough char count.
 
 | Check | Pass | Fail | Notes |
 | ----- | ---- | ---- | ----- |
-| Full backend response returned | ☐ | ☐ | |
-| No truncation metadata without filter | ☐ | ☐ | Design: opt-in filter only (May 25) |
+| Full backend response returned | ☑ | ☐ | GWorkspace `list_drive_items` `page_size: 100` → 100 items + `nextPageToken` |
+| No truncation metadata without filter | ☑ | ☐ | Plain text only; no `{ returned, total, truncated }` (opt-in filter @ `433e7bd`) |
 
 ---
 
@@ -293,8 +294,8 @@ Rules: McpMux meta tools only, read schemas before invoke, note truncation if an
 
 | Area | Result |
 | ---- | ------ |
-| Phase A — meta invoke core | ☐ Pass ☐ Fail |
-| Phase B — result shaping | ☐ Pass ☐ Fail |
+| Phase A — meta invoke core | ☑ Pass ☐ Fail |
+| Phase B — result shaping | ☐ Pass ☐ Fail (section 5 pass; section 6 pending) |
 | Phase C — ACL + surfaced | ☐ Pass ☐ Fail ☐ Skipped |
 | Overall | ☐ Ship ☐ Block |
 
diff --git a/docs/planning/meta-gateway-invoke.md b/docs/planning/meta-gateway-invoke.md
index 5f32c0d6..104628f4 100644
--- a/docs/planning/meta-gateway-invoke.md
+++ b/docs/planning/meta-gateway-invoke.md
@@ -4,7 +4,7 @@
 **Status:** Implemented on branch — manual QA in progress ([`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md))
 **Branch:** `feat/meta-gateway-invoke`
 **Base branch:** `main`
-**Issue:** TBD — file after planning review
+**Issue:** [#155](https://github.com/mcpmux/mcp-mux/pull/155)
 **Depends on:** [`dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) (session overrides + meta-tool registry); benefits from workspace bindings / FeatureSets from PR #151
 **Supersedes:** Token-budget approach in [`tool-level-session-pin.md`](./tool-level-session-pin.md) — pin filtered a bloated `tools/list`; this doc replaces that model with a fixed meta surface + invoke path. Session pin may return as an invoke ACL in Phase F (very optional, last).
 **Unblocks:** Agent-usable McpMux sessions at scale (240+ backend tools installed, ~12 tools in client context); homelab + multi-clone installs without context-window collapse
@@ -164,7 +164,7 @@ Prompts and resources: unchanged — still materialized per grants. Invoke model
 | ---- | ------- | ------ |
 | `crates/mcpmux-gateway/src/services/tool_discovery.rs` | Index + search + schema lookup over Space tool features | ✅ Done |
 | `crates/mcpmux-gateway/src/services/meta_tools/invoke.rs` | `InvokeToolTool` impl — permission check, routing, error mapping, result shaping | ✅ Done |
-| `tests/rust/tests/integration/meta_gateway_invoke.rs` | Search, schema, invoke, permission deny, surfaced tools, direct backend call rejected | ✅ Done (13 tests) |
+| `tests/rust/tests/integration/meta_gateway_invoke.rs` | Search, schema, invoke, permission deny, surfaced tools, direct backend call rejected, filter shaping | ✅ Done (14 tests) |
 | `docs/planning/meta-gateway-invoke-qa.md` | Manual QA runbook for Phases A–C | ✅ Done |
 | `docs/planning/meta-gateway-invoke.md` | This doc | ✅ Done |
 
@@ -192,7 +192,7 @@ Prompts and resources: unchanged — still materialized per grants. Invoke model
 ### Phase A — Meta invoke core
 
 **Effort:** ~3–4 days  
-**Status:** ✅ Implemented — manual QA sections 0–1 pass; sections 2–4 pending ([`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md))
+**Status:** ✅ Implemented — manual QA sections 0–4 pass; section 5 pass; section 6 pending ([`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md))
 
 - [x] `ToolDiscoveryService` — build index from Space features; search by query + optional `server_id`; return matches at `detail_level`
 - [x] `mcpmux_search_tools` meta tool — pagination (`limit`, `cursor`), `detail_level` enum
@@ -209,7 +209,7 @@ Prompts and resources: unchanged — still materialized per grants. Invoke model
 ### Phase B — Result shaping on invoke
 
 **Effort:** ~2 days  
-**Status:** ✅ Implemented — manual QA sections 5–6 pending
+**Status:** ✅ Implemented — manual QA section 5 pass; section 6 pending
 
 - [x] Extend `mcpmux_invoke_tool` args with optional `filter: { max_rows?, max_bytes?, fields?, format? }`
 - [x] Post-process JSON/text results in gateway when `filter` is provided
@@ -316,6 +316,8 @@ This doc is the source of truth for the meta-gateway invoke model. Phases A–C
 
 **Design revision (May 25, 2026):** Removed default smart truncation — `filter` is opt-in only. Rationale: plain-text MCP backends (GWorkspace) don't map cleanly to JSON row truncation; agents should explicitly bound payloads when needed.
 
+**QA ergonomics (May 25, 2026):** Bind FeatureSets in Workspaces UI before agent QA — session enable alone is insufficient without binding ACL. Do **not** call `mcpmux_bind_current_workspace` during routine QA (triggers Space-wide approval modal). Reload MCP tools after UI binding changes.
+
 **Manual QA progress (May 25, 2026):**
 
 | QA section | Result | Notes |
@@ -325,5 +327,6 @@ This doc is the source of truth for the meta-gateway invoke model. Phases A–C
 | 2 — Fail-closed + recovery | ✅ Pass | Session disable → actionable error → enable → retry |
 | 3 — Search detail levels + compact schema | ✅ Pass | compact omits top-level description only |
 | 4 — Session toggle (list size unchanged) | ✅ Pass | search empty when disabled; 10 meta tools stable |
-| 5 — Pass-through without filter (Phase B) | ⬜ Pending | invoke without filter → full backend response, no metadata |
-| 6 — Explicit filter (Phase B) | ⬜ Pending | primary truncation test path |
+| 5 — Pass-through without filter (Phase B) | ✅ Pass | GWorkspace `list_drive_items` @ `433e7bd`: 100 items, ~45k chars, no metadata |
+| 6 — Explicit filter (Phase B) | ⬜ Pending | `max_rows` / `max_bytes` with metadata |
+| 7–11 | ⬜ Pending | |

From 3bc4dc918a390329e95bc01e54689555eacf2d66 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 15:05:19 -0600
Subject: [PATCH 41/48] test(gateway): cover invoke filter shaping with unit
 and e2e tests

Add InvokeToolBackend for pluggable routing, expand filter unit tests,
and prove mcpmux_invoke_tool applies filters via CannedInvokeBackend.
Reconcile Phase B planning docs after manual github_list_issues pass.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 crates/mcpmux-gateway/src/lib.rs              |   6 +-
 crates/mcpmux-gateway/src/pool/mod.rs         |   2 +-
 crates/mcpmux-gateway/src/pool/routing.rs     |   2 +-
 .../src/server/service_container.rs           |   4 +-
 .../src/services/meta_tools/invoke.rs         | 165 +++++++++++++++++-
 .../src/services/meta_tools/invoke_backend.rs |  51 ++++++
 .../src/services/meta_tools/mod.rs            |   6 +-
 .../src/services/meta_tools/registry.rs       |   5 +-
 crates/mcpmux-gateway/src/services/mod.rs     |   5 +-
 docs/planning/meta-gateway-invoke-qa.md       |  22 +--
 docs/planning/meta-gateway-invoke.md          |  41 ++++-
 tests/rust/src/canned_invoke_backend.rs       |  58 ++++++
 tests/rust/src/lib.rs                         |   2 +
 .../tests/integration/meta_gateway_invoke.rs  |  86 ++++++++-
 14 files changed, 417 insertions(+), 38 deletions(-)
 create mode 100644 crates/mcpmux-gateway/src/services/meta_tools/invoke_backend.rs
 create mode 100644 tests/rust/src/canned_invoke_backend.rs

diff --git a/crates/mcpmux-gateway/src/lib.rs b/crates/mcpmux-gateway/src/lib.rs
index 92ada347..3841ec26 100644
--- a/crates/mcpmux-gateway/src/lib.rs
+++ b/crates/mcpmux-gateway/src/lib.rs
@@ -70,13 +70,17 @@ pub use pool::{
     ServerState,
     ServiceFactory,
     TokenService,
+    ToolCallResult,
     TransportConnectResult,
     TransportFactory,
     TransportType,
 };
 
 // Services module
-pub use services::{EventEmitter, GrantService, PrefixCacheService, SessionOverrideRegistry};
+pub use services::{
+    EventEmitter, GrantService, InvokeToolBackend, PrefixCacheService, SessionOverrideRegistry,
+    routing_as_invoke_backend,
+};
 
 // MCP module (rmcp-based implementation)
 pub use mcp::McpMuxGatewayHandler;
diff --git a/crates/mcpmux-gateway/src/pool/mod.rs b/crates/mcpmux-gateway/src/pool/mod.rs
index cfbb4e8e..e3ab01df 100644
--- a/crates/mcpmux-gateway/src/pool/mod.rs
+++ b/crates/mcpmux-gateway/src/pool/mod.rs
@@ -44,7 +44,7 @@ pub use connection::{ConnectionResult, ConnectionService};
 pub use features::{CachedFeatures, FeatureService};
 pub use routing::{
     format_direct_call_redirect, format_invoke_permission_denied, format_server_inactive_error,
-    RoutedPrompt, RoutedResource, RoutedTool, RoutingService,
+    RoutedPrompt, RoutedResource, RoutedTool, RoutingService, ToolCallResult,
 };
 pub use service::{InstalledServerInfo, PoolService, PoolStats, ReconnectResult};
 pub use token::TokenService;
diff --git a/crates/mcpmux-gateway/src/pool/routing.rs b/crates/mcpmux-gateway/src/pool/routing.rs
index 2bed2dfb..18f00fa9 100644
--- a/crates/mcpmux-gateway/src/pool/routing.rs
+++ b/crates/mcpmux-gateway/src/pool/routing.rs
@@ -48,7 +48,7 @@ pub struct RoutedResource {
 }
 
 /// Result of a tool call
-#[derive(Debug)]
+#[derive(Debug, Clone)]
 pub struct ToolCallResult {
     pub content: Vec<Value>,
     pub structured_content: Option<Value>,
diff --git a/crates/mcpmux-gateway/src/server/service_container.rs b/crates/mcpmux-gateway/src/server/service_container.rs
index 805b5ac8..8189c2dd 100644
--- a/crates/mcpmux-gateway/src/server/service_container.rs
+++ b/crates/mcpmux-gateway/src/server/service_container.rs
@@ -134,7 +134,9 @@ impl ServiceContainer {
             deps.installed_server_repo.clone(),
             feature_set_resolver.clone(),
             pool_services.feature_service.clone(),
-            Some(pool_services.routing_service.clone()),
+            Some(meta_tools::routing_as_invoke_backend(
+                pool_services.routing_service.clone(),
+            )),
             session_roots.clone(),
             session_overrides.clone(),
             approval_broker.clone(),
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/invoke.rs b/crates/mcpmux-gateway/src/services/meta_tools/invoke.rs
index 598b6efa..b33a42b2 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/invoke.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/invoke.rs
@@ -131,7 +131,7 @@ impl MetaTool for InvokeToolTool {
                         "format": {
                             "type": "string",
                             "enum": ["summary", "full"],
-                            "description": "summary keeps metadata plus a bounded sample; full returns truncated rows"
+                            "description": "When max_rows is set: summary caps the sample at min(max_rows, 5); full returns up to max_rows rows. Ignored when max_rows is omitted."
                         }
                     }
                 }
@@ -246,12 +246,12 @@ impl MetaTool for InvokeToolTool {
             )));
         }
 
-        let routing = call
+        let backend = call
             .ctx
-            .routing_service
+            .invoke_backend
             .as_ref()
             .ok_or_else(|| MetaToolError::Internal("invoke routing not configured".into()))?;
-        match routing
+        match backend
             .call_tool(
                 space_id,
                 &resolved.feature_set_ids,
@@ -473,6 +473,18 @@ fn invoke_error(message: String) -> CallToolResult {
 mod tests {
     use super::*;
 
+    fn issue_rows(count: usize) -> Vec<Value> {
+        (0..count)
+            .map(|i| {
+                json!({
+                    "id": i,
+                    "title": format!("issue-{i}"),
+                    "body": format!("body-{i}")
+                })
+            })
+            .collect()
+    }
+
     #[test]
     fn no_filter_passes_through_large_array() {
         let items: Vec<Value> = (0..100).map(|i| json!({ "id": i, "name": format!("n{i}") })).collect();
@@ -481,8 +493,8 @@ mod tests {
     }
 
     #[test]
-    fn explicit_max_rows_truncates() {
-        let items: Vec<Value> = (0..20).map(|i| json!({ "id": i })).collect();
+    fn explicit_max_rows_truncates_top_level_array() {
+        let items: Vec<Value> = issue_rows(20);
         let filter = InvokeResultFilter {
             max_rows: Some(3),
             ..Default::default()
@@ -491,6 +503,70 @@ mod tests {
         assert_eq!(shaped.get("returned"), Some(&json!(3)));
         assert_eq!(shaped.get("total"), Some(&json!(20)));
         assert_eq!(shaped.get("truncated"), Some(&json!(true)));
+        let sample = shaped.get("items").and_then(|v| v.as_array()).unwrap();
+        assert_eq!(sample.len(), 3);
+    }
+
+    #[test]
+    fn explicit_max_rows_truncates_nested_issues_key() {
+        let issues = issue_rows(20);
+        let filter = InvokeResultFilter {
+            max_rows: Some(3),
+            ..Default::default()
+        };
+        let shaped = shape_json_value(json!({ "issues": issues }), &filter);
+        assert_eq!(shaped.get("returned"), Some(&json!(3)));
+        assert_eq!(shaped.get("total"), Some(&json!(20)));
+        assert_eq!(shaped.get("truncated"), Some(&json!(true)));
+        let sample = shaped.get("issues").and_then(|v| v.as_array()).unwrap();
+        assert_eq!(sample.len(), 3);
+    }
+
+    #[test]
+    fn json_in_text_block_truncates_with_metadata() {
+        let rows: Vec<Value> = (0..80).map(|i| json!({ "n": i })).collect();
+        let content = vec![json!({
+            "type": "text",
+            "text": json!({ "results": rows }).to_string(),
+        })];
+        let filter = parse_invoke_filter(Some(&json!({ "max_rows": 10 }))).unwrap();
+
+        let (shaped_content, _) = apply_invoke_result_filter(content, None, &filter);
+        let text = shaped_content[0].get("text").and_then(|t| t.as_str()).unwrap();
+        let parsed: Value = serde_json::from_str(text).unwrap();
+
+        assert_eq!(parsed.get("returned"), Some(&json!(10)));
+        assert_eq!(parsed.get("total"), Some(&json!(80)));
+        assert_eq!(parsed.get("truncated"), Some(&json!(true)));
+    }
+
+    #[test]
+    fn structured_content_and_text_both_shaped() {
+        let items = issue_rows(20);
+        let structured = json!({ "items": items });
+        let content = vec![json!({
+            "type": "text",
+            "text": structured.to_string(),
+        })];
+        let filter = InvokeResultFilter {
+            max_rows: Some(5),
+            fields: Some(vec!["id".into(), "title".into()]),
+            ..Default::default()
+        };
+
+        let (shaped_content, shaped_structured) =
+            apply_invoke_result_filter(content, Some(structured), &filter);
+
+        let parsed_text: Value =
+            serde_json::from_str(shaped_content[0].get("text").and_then(|t| t.as_str()).unwrap())
+                .unwrap();
+        assert_eq!(parsed_text.get("returned"), Some(&json!(5)));
+        assert_eq!(parsed_text.get("total"), Some(&json!(20)));
+
+        let shaped = shaped_structured.unwrap();
+        let structured_sample = shaped.get("items").and_then(|v| v.as_array()).unwrap();
+        assert_eq!(structured_sample.len(), 5);
+        assert_eq!(structured_sample[0], json!({ "id": 0, "title": "issue-0" }));
     }
 
     #[test]
@@ -509,6 +585,83 @@ mod tests {
         assert_eq!(kept[1], json!({ "id": 2, "name": "b" }));
     }
 
+    #[test]
+    fn max_rows_and_fields_together() {
+        let items: Vec<Value> = (0..30)
+            .map(|i| json!({ "id": i, "label": format!("row-{i}") }))
+            .collect();
+        let filter = parse_invoke_filter(Some(&json!({ "max_rows": 5, "fields": ["id"] }))).unwrap();
+        let shaped = shape_json_value(Value::Array(items), &filter);
+
+        assert_eq!(shaped.get("returned"), Some(&json!(5)));
+        assert_eq!(shaped.get("total"), Some(&json!(30)));
+        assert_eq!(shaped.get("truncated"), Some(&json!(true)));
+        let sample = shaped.get("items").and_then(|v| v.as_array()).unwrap();
+        assert_eq!(sample.len(), 5);
+        assert_eq!(sample[0], json!({ "id": 0 }));
+    }
+
+    #[test]
+    fn summary_format_no_op_when_max_rows_at_most_five() {
+        let items = issue_rows(20);
+        let filter = InvokeResultFilter {
+            max_rows: Some(3),
+            format: Some("summary".into()),
+            ..Default::default()
+        };
+        let shaped = shape_json_value(Value::Array(items), &filter);
+        assert_eq!(shaped.get("returned"), Some(&json!(3)));
+    }
+
+    #[test]
+    fn summary_format_caps_sample_at_five() {
+        let items = issue_rows(20);
+        let filter = InvokeResultFilter {
+            max_rows: Some(10),
+            format: Some("summary".into()),
+            ..Default::default()
+        };
+        let shaped = shape_json_value(Value::Array(items), &filter);
+        assert_eq!(shaped.get("returned"), Some(&json!(5)));
+        assert_eq!(shaped.get("total"), Some(&json!(20)));
+    }
+
+    #[test]
+    fn full_format_returns_up_to_max_rows() {
+        let items = issue_rows(20);
+        let filter = InvokeResultFilter {
+            max_rows: Some(10),
+            format: Some("full".into()),
+            ..Default::default()
+        };
+        let shaped = shape_json_value(Value::Array(items), &filter);
+        assert_eq!(shaped.get("returned"), Some(&json!(10)));
+        let sample = shaped.get("items").and_then(|v| v.as_array()).unwrap();
+        assert_eq!(sample.len(), 10);
+    }
+
+    #[test]
+    fn parse_invoke_filter_ignores_invalid_types() {
+        let filter = parse_invoke_filter(Some(&json!({
+            "max_rows": "not-a-number",
+            "max_bytes": true,
+            "fields": "id",
+            "format": 123
+        })))
+        .unwrap();
+        assert_eq!(filter.max_rows, None);
+        assert_eq!(filter.max_bytes, None);
+        assert_eq!(filter.fields, None);
+        assert_eq!(filter.format, None);
+    }
+
+    #[test]
+    fn parse_invoke_filter_accepts_partial_objects() {
+        let filter = parse_invoke_filter(Some(&json!({ "max_rows": 3 }))).unwrap();
+        assert_eq!(filter.max_rows, Some(3));
+        assert_eq!(filter.max_bytes, None);
+    }
+
     #[test]
     fn plain_text_byte_trunc_includes_metadata() {
         let text = "x".repeat(100);
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/invoke_backend.rs b/crates/mcpmux-gateway/src/services/meta_tools/invoke_backend.rs
new file mode 100644
index 00000000..d781fb8a
--- /dev/null
+++ b/crates/mcpmux-gateway/src/services/meta_tools/invoke_backend.rs
@@ -0,0 +1,51 @@
+//! Pluggable backend for `mcpmux_invoke_tool` routing.
+
+use std::sync::Arc;
+
+use anyhow::Result;
+use async_trait::async_trait;
+use serde_json::Value;
+use uuid::Uuid;
+
+use crate::pool::{RoutingService, ToolCallResult};
+
+/// Dispatches permission-checked tool calls to a backend MCP server.
+#[async_trait]
+pub trait InvokeToolBackend: Send + Sync {
+    /// Invoke a qualified backend tool and return raw MCP content.
+    async fn call_tool(
+        &self,
+        space_id: Uuid,
+        feature_set_ids: &[String],
+        session_id: Option<&str>,
+        qualified_name: &str,
+        arguments: Value,
+    ) -> Result<ToolCallResult>;
+}
+
+#[async_trait]
+impl InvokeToolBackend for RoutingService {
+    async fn call_tool(
+        &self,
+        space_id: Uuid,
+        feature_set_ids: &[String],
+        session_id: Option<&str>,
+        qualified_name: &str,
+        arguments: Value,
+    ) -> Result<ToolCallResult> {
+        RoutingService::call_tool(
+            self,
+            space_id,
+            feature_set_ids,
+            session_id,
+            qualified_name,
+            arguments,
+        )
+        .await
+    }
+}
+
+/// Wrap a [`RoutingService`] as an [`InvokeToolBackend`] trait object.
+pub fn routing_as_invoke_backend(routing: Arc<RoutingService>) -> Arc<dyn InvokeToolBackend> {
+    routing
+}
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/mod.rs b/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
index b0becf7c..5a646ddb 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/mod.rs
@@ -23,6 +23,7 @@
 pub mod approval;
 pub mod diff;
 pub mod invoke;
+pub mod invoke_backend;
 mod registry;
 mod tools;
 mod workspace_server;
@@ -32,6 +33,7 @@ pub use approval::{
     ApprovalScope,
 };
 pub use diff::ToolDiff;
+pub use invoke_backend::{routing_as_invoke_backend, InvokeToolBackend};
 pub use registry::{
     MetaToolContext, MetaToolError, MetaToolRegistry, META_TOOLS_ENABLED_KEY,
     SESSION_OVERRIDES_REQUIRE_APPROVAL_KEY,
@@ -62,7 +64,7 @@ pub fn build_default_registry(
     installed_server_repo: std::sync::Arc<dyn mcpmux_core::InstalledServerRepository>,
     resolver: std::sync::Arc<crate::services::FeatureSetResolverService>,
     feature_service: std::sync::Arc<crate::pool::FeatureService>,
-    routing_service: Option<std::sync::Arc<crate::pool::RoutingService>>,
+    invoke_backend: Option<std::sync::Arc<dyn invoke_backend::InvokeToolBackend>>,
     session_roots: std::sync::Arc<crate::services::SessionRootsRegistry>,
     session_overrides: std::sync::Arc<crate::services::SessionOverrideRegistry>,
     approval_broker: std::sync::Arc<ApprovalBroker>,
@@ -80,7 +82,7 @@ pub fn build_default_registry(
         installed_server_repo,
         resolver,
         feature_service,
-        routing_service,
+        invoke_backend,
         tool_discovery,
         session_roots,
         session_overrides,
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/registry.rs b/crates/mcpmux-gateway/src/services/meta_tools/registry.rs
index eb692f4a..b6c12923 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/registry.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/registry.rs
@@ -18,7 +18,8 @@ use thiserror::Error;
 use tokio::sync::broadcast;
 
 use super::approval::ApprovalBroker;
-use crate::pool::{FeatureService, RoutingService};
+use super::invoke_backend::InvokeToolBackend;
+use crate::pool::FeatureService;
 use crate::services::{
     FeatureSetResolverService, SessionOverrideRegistry, SessionRootsRegistry, ToolDiscoveryService,
 };
@@ -47,7 +48,7 @@ pub struct MetaToolContext {
     pub resolver: Arc<FeatureSetResolverService>,
     pub feature_service: Arc<FeatureService>,
     /// Backend invoke path — required for `mcpmux_invoke_tool`.
-    pub routing_service: Option<Arc<RoutingService>>,
+    pub invoke_backend: Option<Arc<dyn InvokeToolBackend>>,
     pub tool_discovery: Arc<ToolDiscoveryService>,
     pub session_roots: Arc<SessionRootsRegistry>,
     pub session_overrides: Arc<SessionOverrideRegistry>,
diff --git a/crates/mcpmux-gateway/src/services/mod.rs b/crates/mcpmux-gateway/src/services/mod.rs
index 5b39ac09..00d41c8e 100644
--- a/crates/mcpmux-gateway/src/services/mod.rs
+++ b/crates/mcpmux-gateway/src/services/mod.rs
@@ -24,8 +24,9 @@ pub use event_emitter::EventEmitter;
 pub use feature_set_resolver::{FeatureSetResolverService, ResolutionSource, ResolvedFeatureSet};
 pub use grant_service::GrantService;
 pub use meta_tools::{
-    is_meta_tool, ApprovalBroker, ApprovalDecision, ApprovalPayload, ApprovalPublisher,
-    ApprovalRequest, ApprovalScope, MetaToolRegistry, MCPMUX_PREFIX,
+    is_meta_tool, routing_as_invoke_backend, ApprovalBroker, ApprovalDecision, ApprovalPayload,
+    ApprovalPublisher, ApprovalRequest, ApprovalScope, InvokeToolBackend, MetaToolRegistry,
+    MCPMUX_PREFIX,
 };
 pub use notification_emitter::NotificationEmitter;
 pub use prefix_cache::PrefixCacheService;
diff --git a/docs/planning/meta-gateway-invoke-qa.md b/docs/planning/meta-gateway-invoke-qa.md
index feb7a88a..d23a901d 100644
--- a/docs/planning/meta-gateway-invoke-qa.md
+++ b/docs/planning/meta-gateway-invoke-qa.md
@@ -13,7 +13,7 @@ One-session checklist for validating Phases A–C (search → schema → invoke,
 - [x] Rebuild/restart gateway if you haven't since the branch (`pnpm dev` or run the built app)
 - [x] Cursor → MCP → **Reload tools**
 - [x] Confirm McpMux endpoint: `http://localhost:45818/mcp`
-- [ ] Have at least one OAuth server (GitHub) **installed and connected** but **inactive** in session (for enable-flow tests) — github is `enabled_via_binding`; use session disable for test 2
+- [x] Have at least one OAuth server (GitHub) **installed and connected** — `QA: meta-gateway invoke` FeatureSet bound in UI (May 25)
 - [x] Workspace binding with GWorkspace (or target server) configured in UI — **not** via agent `mcpmux_bind_current_workspace`
 - [ ] Optional for Phase C tests: create a FeatureSet with 1–2 GitHub tools, bind to workspace; leave surfaced off until test 8
 
@@ -171,10 +171,10 @@ Then fields projection if the tool returns JSON objects with id/name/title field
 
 | Check | Pass | Fail | Notes |
 | ----- | ---- | ---- | ----- |
-| `max_rows: 3` honored (JSON tools) | ☐ | ☐ | |
-| `max_bytes` honored with metadata (plain text) | ☐ | ☐ | |
-| `format: summary` applied | ☐ | ☐ | |
-| `fields` projection limits keys per row (if tested) | ☐ | ☐ | |
+| `max_rows: 3` honored (JSON tools) | ☑ | ☐ | Live `github_list_issues` → `{ returned: 3, total: 5, truncated: true, issues: [3 items] }` (5 open issues in repo) |
+| `max_bytes` honored with metadata (plain text) | ☑ | ☐ | GWorkspace `list_drive_items` `max_bytes: 4096` → `{ returned: 4110, total: 7660, truncated: true, text: "…[truncated]" }` |
+| `format: summary` applied | ☑ | ☐ | JSON: metadata envelope present; with 5 total issues and `max_rows: 3` → 3 returned (summary no-op when max_rows ≤ 5) |
+| `fields` projection limits keys per row (if tested) | ☑ | ☐ | `fields: ["id","title","number"]` → rows kept `title` + `number` only (`id` absent in GitHub payload) |
 
 ---
 
@@ -193,8 +193,8 @@ Confirm results are scoped to that server_id only.
 
 | Check | Pass | Fail | Notes |
 | ----- | ---- | ---- | ----- |
-| `server_id` filter scopes search | ☐ | ☐ | |
-| Other clone's tools not in results | ☐ | ☐ | |
+| `server_id` filter scopes search | ☑ | ☐ | `server_id: taylorwilsdon.google-workspace-mcp-uvx` + query `"drive"` → 24 hits, all Personal prefix |
+| Other clone's tools not in results | ☑ | ☐ | S2H clone inactive; search with `server_id: …-s2h` → `total: 0` |
 
 ---
 
@@ -252,8 +252,8 @@ Explain why agents should prefer search.
 
 | Check | Pass | Fail | Notes |
 | ----- | ---- | ---- | ----- |
-| `server_id` filter on list_all_tools works | ☐ | ☐ | |
-| Agent recommends search over full dump | ☐ | ☐ | |
+| `server_id` filter on list_all_tools works | ☑ | ☐ | GWorkspace Personal: 120 tools; all `server_id` matches filter |
+| Agent recommends search over full dump | ☑ | ☐ | Same count (120); search supports query/detail_level/pagination — list_all_tools dumps ~42 KB with full descriptions |
 
 ---
 
@@ -295,11 +295,13 @@ Rules: McpMux meta tools only, read schemas before invoke, note truncation if an
 | Area | Result |
 | ---- | ------ |
 | Phase A — meta invoke core | ☑ Pass ☐ Fail |
-| Phase B — result shaping | ☐ Pass ☐ Fail (section 5 pass; section 6 pending) |
+| Phase B — result shaping | ☑ Pass ☐ Fail |
 | Phase C — ACL + surfaced | ☐ Pass ☐ Fail ☐ Skipped |
 | Overall | ☐ Ship ☐ Block |
 
 **Blockers / issues filed:**
 
 ```
+- section 6 JSON rows: manual pass May 25 after binding QA FeatureSet — github_list_issues filter verified live
+- beeper 401 on get_accounts/search_chats — auth expired; not blocking meta-gateway QA
 ```
diff --git a/docs/planning/meta-gateway-invoke.md b/docs/planning/meta-gateway-invoke.md
index 104628f4..539f7555 100644
--- a/docs/planning/meta-gateway-invoke.md
+++ b/docs/planning/meta-gateway-invoke.md
@@ -164,7 +164,9 @@ Prompts and resources: unchanged — still materialized per grants. Invoke model
 | ---- | ------- | ------ |
 | `crates/mcpmux-gateway/src/services/tool_discovery.rs` | Index + search + schema lookup over Space tool features | ✅ Done |
 | `crates/mcpmux-gateway/src/services/meta_tools/invoke.rs` | `InvokeToolTool` impl — permission check, routing, error mapping, result shaping | ✅ Done |
-| `tests/rust/tests/integration/meta_gateway_invoke.rs` | Search, schema, invoke, permission deny, surfaced tools, direct backend call rejected, filter shaping | ✅ Done (14 tests) |
+| `crates/mcpmux-gateway/src/services/meta_tools/invoke_backend.rs` | `InvokeToolBackend` trait + `RoutingService` adapter for testable invoke routing | ✅ Done |
+| `tests/rust/src/canned_invoke_backend.rs` | Canned backend for filter e2e integration tests | ✅ Done |
+| `tests/rust/tests/integration/meta_gateway_invoke.rs` | Search, schema, invoke, permission deny, surfaced tools, filter shaping, e2e filter via canned backend | ✅ Done (17 tests) |
 | `docs/planning/meta-gateway-invoke-qa.md` | Manual QA runbook for Phases A–C | ✅ Done |
 | `docs/planning/meta-gateway-invoke.md` | This doc | ✅ Done |
 
@@ -174,8 +176,8 @@ Prompts and resources: unchanged — still materialized per grants. Invoke model
 | ---- | ------ | ------ |
 | [`crates/mcpmux-gateway/src/services/mod.rs`](../../crates/mcpmux-gateway/src/services/mod.rs) | `pub mod tool_discovery;` | ✅ Done |
 | [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | `SearchToolsTool`, `GetToolSchemaTool`; extend `ListAllToolsTool` with optional `server_id` filter | ✅ Done |
-| [`crates/mcpmux-gateway/src/services/meta_tools/mod.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/mod.rs) | Register new tools; wire `ToolDiscoveryService` + `RoutingService` into `MetaToolContext` | ✅ Done |
-| [`crates/mcpmux-gateway/src/services/meta_tools/registry.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/registry.rs) | Extend `MetaToolContext` with discovery + routing handles | ✅ Done |
+| [`crates/mcpmux-gateway/src/services/meta_tools/mod.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/mod.rs) | Register new tools; wire `ToolDiscoveryService` + `InvokeToolBackend` into `MetaToolContext` | ✅ Done |
+| [`crates/mcpmux-gateway/src/services/meta_tools/registry.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/registry.rs) | Extend `MetaToolContext` with discovery + invoke backend handles | ✅ Done |
 | [`crates/mcpmux-gateway/src/pool/features/facade.rs`](../../crates/mcpmux-gateway/src/pool/features/facade.rs) | Split into `get_advertised_tools_for_grants` vs `get_invokable_tools_for_grants` | ✅ Done |
 | [`crates/mcpmux-gateway/src/pool/features/resolution.rs`](../../crates/mcpmux-gateway/src/pool/features/resolution.rs) | `resolve_surfaced_feature_ids` for surfaced promotion | ✅ Done |
 | [`crates/mcpmux-gateway/src/pool/routing.rs`](../../crates/mcpmux-gateway/src/pool/routing.rs) | `format_direct_call_redirect`; actionable invoke errors | ✅ Done |
@@ -209,15 +211,33 @@ Prompts and resources: unchanged — still materialized per grants. Invoke model
 ### Phase B — Result shaping on invoke
 
 **Effort:** ~2 days  
-**Status:** ✅ Implemented — manual QA section 5 pass; section 6 pending
+**Status:** ✅ Implemented — manual QA section 6 pass (May 25)
 
 - [x] Extend `mcpmux_invoke_tool` args with optional `filter: { max_rows?, max_bytes?, fields?, format? }`
 - [x] Post-process JSON/text results in gateway when `filter` is provided
 - [x] Opt-in truncation only — omit `filter` to return backend response unchanged (May 25 design revision)
-- [x] Integration tests: explicit filter returns `{ returned, total, truncated: true }`; no filter pass-through
+- [x] Unit tests (13): top-level arrays, nested `issues`/`items` keys, JSON-in-text blocks, `structured_content`, `fields`, `format: summary` vs `full`, `parse_invoke_filter` edge cases
+- [x] Integration tests: pure-fn filter shaping + `invoke_tool_applies_filter_end_to_end` via `CannedInvokeBackend`
 
 **Outcome:** Agents pass `filter` on known-heavy tools (GWorkspace drive lists, GitHub issues, PostHog events). Plain-text and JSON backends both supported when filter is explicit.
 
+#### Filter behavior reference
+
+| Payload shape | Applicable filter keys | Behavior |
+| ------------- | ---------------------- | -------- |
+| Plain text (`content[].text` non-JSON) | `max_bytes` only | Returns `{ returned, total, truncated, text }` envelope when over limit. `max_rows` / `fields` / `format` ignored. |
+| Top-level JSON array | `max_rows`, `fields`, `format`, `max_bytes` | When `total > max_rows`: `{ returned, total, truncated, items: [...] }` |
+| JSON object with heavy array key (`issues`, `items`, `results`, …) | same | Metadata merged at object top-level; array under original key name |
+| JSON serialized inside text content block | same | Parsed then shaped; re-serialized into `text` |
+| `structured_content` on `CallToolResult` | same | Shaped independently via `apply_invoke_result_filter` |
+
+**`format` semantics (requires `max_rows`):**
+
+- `full` — sample size = `max_rows`
+- `summary` — sample size = `min(max_rows, 5)` (no effect when `max_rows ≤ 5`)
+
+**Envelope fields:** `returned` (rows or bytes after truncation), `total` (pre-truncation count/bytes), `truncated: true`, plus `items`/`issues`/… or `text`.
+
 ### Phase C — FeatureSet as invoke ACL + surfaced tools
 
 **Effort:** ~3 days  
@@ -290,7 +310,9 @@ Prompts and resources: unchanged — still materialized per grants. Invoke model
 | ---- | --- |
 | [`crates/mcpmux-gateway/src/pool/features/facade.rs`](../../crates/mcpmux-gateway/src/pool/features/facade.rs) | Materialization chokepoint — must split advertised vs invokable |
 | [`crates/mcpmux-gateway/src/pool/routing.rs`](../../crates/mcpmux-gateway/src/pool/routing.rs) | Existing `call_tool` path invoke reuses |
-| [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | New meta tool impls land here |
+| [`crates/mcpmux-gateway/src/services/meta_tools/invoke.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/invoke.rs) | Invoke meta tool + result shaping |
+| [`crates/mcpmux-gateway/src/services/meta_tools/invoke_backend.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/invoke_backend.rs) | Pluggable invoke routing trait |
+| [`tests/rust/src/canned_invoke_backend.rs`](../../tests/rust/src/canned_invoke_backend.rs) | Test double for filter e2e |
 | [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) | `tools/list` + `call_tool` handler — legacy direct call blocking |
 | [`docs/planning/dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) | Session enable/disable — kept, semantics updated |
 | [`docs/planning/tool-level-session-pin.md`](./tool-level-session-pin.md) | Superseded for token budget; Phase F very optional rework |
@@ -318,6 +340,8 @@ This doc is the source of truth for the meta-gateway invoke model. Phases A–C
 
 **QA ergonomics (May 25, 2026):** Bind FeatureSets in Workspaces UI before agent QA — session enable alone is insufficient without binding ACL. Do **not** call `mcpmux_bind_current_workspace` during routine QA (triggers Space-wide approval modal). Reload MCP tools after UI binding changes.
 
+**Test coverage (May 25, 2026):** Phase B filter shaping — 13 unit tests in `invoke.rs`, 17 integration tests in `meta_gateway_invoke.rs`, manual QA section 6 pass on live `github_list_issues`.
+
 **Manual QA progress (May 25, 2026):**
 
 | QA section | Result | Notes |
@@ -328,5 +352,6 @@ This doc is the source of truth for the meta-gateway invoke model. Phases A–C
 | 3 — Search detail levels + compact schema | ✅ Pass | compact omits top-level description only |
 | 4 — Session toggle (list size unchanged) | ✅ Pass | search empty when disabled; 10 meta tools stable |
 | 5 — Pass-through without filter (Phase B) | ✅ Pass | GWorkspace `list_drive_items` @ `433e7bd`: 100 items, ~45k chars, no metadata |
-| 6 — Explicit filter (Phase B) | ⬜ Pending | `max_rows` / `max_bytes` with metadata |
-| 7–11 | ⬜ Pending | |
+| 6 — Explicit filter (Phase B) | ✅ Pass | Plain-text `max_bytes` + live `github_list_issues` JSON filter (`max_rows`, `fields`, `summary`) |
+| 7 — Clone disambiguation | ✅ Pass | Personal vs S2H clone scoped correctly |
+| 10 — Diagnostic list vs search | ✅ Pass | 120 tools both paths for GWorkspace Personal |
diff --git a/tests/rust/src/canned_invoke_backend.rs b/tests/rust/src/canned_invoke_backend.rs
new file mode 100644
index 00000000..08a2589d
--- /dev/null
+++ b/tests/rust/src/canned_invoke_backend.rs
@@ -0,0 +1,58 @@
+//! Canned invoke backend for integration tests.
+
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use anyhow::{anyhow, Result};
+use async_trait::async_trait;
+use mcpmux_gateway::{InvokeToolBackend, ToolCallResult};
+use serde_json::Value;
+use uuid::Uuid;
+
+/// Returns predetermined tool results keyed by qualified tool name.
+pub struct CannedInvokeBackend {
+    responses: HashMap<String, ToolCallResult>,
+}
+
+impl CannedInvokeBackend {
+    /// Create an empty canned backend.
+    pub fn new() -> Self {
+        Self {
+            responses: HashMap::new(),
+        }
+    }
+
+    /// Register a response for a qualified tool name.
+    pub fn with_response(mut self, qualified_name: impl Into<String>, result: ToolCallResult) -> Self {
+        self.responses.insert(qualified_name.into(), result);
+        self
+    }
+
+    /// Wrap as a trait object for registry wiring.
+    pub fn into_arc(self) -> Arc<dyn InvokeToolBackend> {
+        Arc::new(self)
+    }
+}
+
+impl Default for CannedInvokeBackend {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+#[async_trait]
+impl InvokeToolBackend for CannedInvokeBackend {
+    async fn call_tool(
+        &self,
+        _space_id: Uuid,
+        _feature_set_ids: &[String],
+        _session_id: Option<&str>,
+        qualified_name: &str,
+        _arguments: Value,
+    ) -> Result<ToolCallResult> {
+        self.responses
+            .get(qualified_name)
+            .cloned()
+            .ok_or_else(|| anyhow!("no canned response for {qualified_name}"))
+    }
+}
diff --git a/tests/rust/src/lib.rs b/tests/rust/src/lib.rs
index b6eff502..5aa818fe 100644
--- a/tests/rust/src/lib.rs
+++ b/tests/rust/src/lib.rs
@@ -8,7 +8,9 @@ pub use mcpmux_core::{
 };
 
 /// Mock repository implementations
+pub mod canned_invoke_backend;
 pub mod mocks;
+pub use canned_invoke_backend::CannedInvokeBackend;
 pub use mocks::MockRepositories;
 
 /// Service test helpers
diff --git a/tests/rust/tests/integration/meta_gateway_invoke.rs b/tests/rust/tests/integration/meta_gateway_invoke.rs
index 2964ecc5..134b23f4 100644
--- a/tests/rust/tests/integration/meta_gateway_invoke.rs
+++ b/tests/rust/tests/integration/meta_gateway_invoke.rs
@@ -8,13 +8,13 @@ use mcpmux_core::{
     InboundMcpClientRepository, InstalledServerRepository, MemberMode, MemberType, ServerFeature,
     ServerFeatureRepository, SpaceRepository, WorkspaceBindingRepository,
 };
-use mcpmux_gateway::pool::{format_direct_call_redirect, FeatureService};
+use mcpmux_gateway::pool::{format_direct_call_redirect, FeatureService, ToolCallResult};
 use mcpmux_gateway::services::meta_tools::invoke::{
     apply_invoke_result_filter, parse_invoke_filter, shape_json_value, InvokeResultFilter,
 };
 use mcpmux_gateway::services::{
-    meta_tools, ApprovalBroker, FeatureSetResolverService, MetaToolRegistry, PrefixCacheService,
-    SessionOverrideRegistry, SessionRootsRegistry,
+    meta_tools, ApprovalBroker, FeatureSetResolverService, InvokeToolBackend, MetaToolRegistry,
+    PrefixCacheService, SessionOverrideRegistry, SessionRootsRegistry,
 };
 use mcpmux_storage::{
     generate_master_key, Database, FieldEncryptor, InboundClientRepository,
@@ -22,6 +22,7 @@ use mcpmux_storage::{
     SqliteServerFeatureRepository, SqliteSpaceRepository, SqliteWorkspaceBindingRepository,
 };
 use serde_json::{json, Value};
+use tests::CannedInvokeBackend;
 use tokio::sync::{broadcast, Mutex};
 use uuid::Uuid;
 
@@ -45,6 +46,10 @@ fn test_encryptor() -> Arc<FieldEncryptor> {
 
 impl Fixture {
     async fn new() -> Self {
+        Self::with_invoke_backend(None).await
+    }
+
+    async fn with_invoke_backend(invoke_backend: Option<Arc<dyn InvokeToolBackend>>) -> Self {
         let db = Arc::new(Mutex::new(Database::open_in_memory().unwrap()));
 
         let space_repo: Arc<dyn SpaceRepository> = Arc::new(SqliteSpaceRepository::new(db.clone()));
@@ -126,7 +131,7 @@ impl Fixture {
             installed_server_repo,
             resolver,
             feature_service.clone(),
-            None,
+            invoke_backend,
             session_roots.clone(),
             session_overrides.clone(),
             broker,
@@ -183,6 +188,79 @@ impl Fixture {
             Err(e) => e.into_call_tool_result(),
         }
     }
+    async fn grant_github_feature_set(&self) -> String {
+        let fs_id = self
+            .feature_set_repo
+            .list_by_space(&self.space_id.to_string())
+            .await
+            .unwrap()
+            .into_iter()
+            .find(|fs| fs.name == "Grant GitHub")
+            .unwrap()
+            .id;
+        self.grant_feature_set(&fs_id).await;
+        fs_id
+    }
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn invoke_tool_applies_filter_end_to_end() {
+    let issues: Vec<Value> = (0..20)
+        .map(|i| {
+            json!({
+                "id": i,
+                "title": format!("issue-{i}"),
+                "body": format!("body-{i}")
+            })
+        })
+        .collect();
+    let payload = json!({ "issues": issues });
+    let backend_result = ToolCallResult {
+        content: vec![json!({
+            "type": "text",
+            "text": payload.to_string(),
+        })],
+        structured_content: Some(payload),
+        is_error: false,
+    };
+    let invoke_backend = CannedInvokeBackend::new()
+        .with_response("github_list_issues", backend_result)
+        .into_arc();
+
+    let f = Fixture::with_invoke_backend(Some(invoke_backend)).await;
+    f.grant_github_feature_set().await;
+    f.session_overrides.enable(&f.session_id, "github");
+
+    let result = f
+        .call(
+            "mcpmux_invoke_tool",
+            json!({
+                "server_id": "github",
+                "tool": "list_issues",
+                "args": { "owner": "mcpmux", "repo": "mcp-mux" },
+                "filter": {
+                    "max_rows": 3,
+                    "fields": ["id", "title"],
+                    "format": "summary"
+                }
+            }),
+        )
+        .await;
+
+    assert!(!result.is_error.unwrap_or(true));
+    let body = Fixture::result_json(&result);
+    assert_eq!(body.get("returned"), Some(&json!(3)));
+    assert_eq!(body.get("total"), Some(&json!(20)));
+    assert_eq!(body.get("truncated"), Some(&json!(true)));
+    let sample = body.get("issues").and_then(|v| v.as_array()).unwrap();
+    assert_eq!(sample.len(), 3);
+    assert_eq!(sample[0], json!({ "id": 0, "title": "issue-0" }));
+
+    let structured = result.structured_content.expect("structured content shaped");
+    assert_eq!(structured.get("returned"), Some(&json!(3)));
+    let structured_sample = structured.get("issues").and_then(|v| v.as_array()).unwrap();
+    assert_eq!(structured_sample.len(), 3);
+    assert_eq!(structured_sample[0], json!({ "id": 0, "title": "issue-0" }));
 }
 
 #[tokio::test(flavor = "multi_thread")]

From 22d92c386ab77427085f104cf01821a63f42d91f Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 15:20:42 -0600
Subject: [PATCH 42/48] fix(gateway): allow direct call_tool for surfaced
 backend tools

Probe workspace roots before call_tool routing so surfaced tools resolve
the same binding ACL as tools/list. Document checkbox vs Surface in the
FeatureSet editor and record Phase C manual QA pass.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 README.md                                     |  2 +-
 .../features/featuresets/FeatureSetPanel.tsx  |  2 +-
 crates/mcpmux-gateway/src/mcp/handler.rs      | 54 ++++++++++++----
 docs/guide/feature-sets.mdx                   | 47 ++++++++++++--
 docs/planning/meta-gateway-invoke-qa.md       | 31 ++++++---
 docs/planning/meta-gateway-invoke.md          |  3 +
 .../tests/integration/meta_gateway_invoke.rs  | 64 +++++++++++++++++++
 7 files changed, 174 insertions(+), 29 deletions(-)

diff --git a/README.md b/README.md
index 025a29a0..64d13a80 100644
--- a/README.md
+++ b/README.md
@@ -109,7 +109,7 @@ Create isolated Spaces — each with their own servers, credentials, and permiss
 
 ### Control What Each Client Can Do
 
-Not every AI client should have the same power. Create Feature Sets — permission bundles that control exactly which tools a client can **invoke** (search + invoke ACL), plus optional per-tool **Surface in client** promotion for one-hop hot paths. Build a "Read Only" set for cautious workflows, a "React Development" set with just GitHub and Filesystem, or a "Full Stack Dev" set with everything. Assign them per-client so each tool only goes where you want it.
+Not every AI client should have the same power. Create Feature Sets — permission bundles that control exactly which tools a client can **invoke** (search + invoke ACL). In the editor, the **checkbox** includes a tool in that ACL; the **Surface** button (optional, per row) promotes an included tool into the client's `tools/list` for one-hop hot paths. Build a "Read Only" set for cautious workflows, a "React Development" set with just GitHub and Filesystem, or a "Full Stack Dev" set with everything. Assign them per-client so each tool only goes where you want it.
 
 ![Feature Sets — granular per-server tool selection](docs/screenshots/featureset-detail.png)
 
diff --git a/apps/desktop/src/features/featuresets/FeatureSetPanel.tsx b/apps/desktop/src/features/featuresets/FeatureSetPanel.tsx
index a1fd5008..2db92725 100644
--- a/apps/desktop/src/features/featuresets/FeatureSetPanel.tsx
+++ b/apps/desktop/src/features/featuresets/FeatureSetPanel.tsx
@@ -693,7 +693,7 @@ export function FeatureSetPanel({ featureSet, spaceId, onClose, onDelete, onUpda
                                             ${isSurfaced
                                               ? 'bg-blue-100 dark:bg-blue-900/30 text-blue-700 dark:text-blue-300'
                                               : 'text-[rgb(var(--muted))] hover:bg-[rgb(var(--surface-hover))]'}`}
-                                          title="Surface in client tools/list"
+                                          title="Promote this included tool into the client tools/list for direct one-hop calls. The checkbox only grants invoke access via search + mcpmux_invoke_tool—it does not add the tool to tools/list. Use sparingly; each surfaced tool adds its schema to the client context."
                                           data-testid={`surface-toggle-${feature.id}`}
                                         >
                                           <Monitor className="h-3.5 w-3.5" />
diff --git a/crates/mcpmux-gateway/src/mcp/handler.rs b/crates/mcpmux-gateway/src/mcp/handler.rs
index 43acaa25..c62a7ded 100644
--- a/crates/mcpmux-gateway/src/mcp/handler.rs
+++ b/crates/mcpmux-gateway/src/mcp/handler.rs
@@ -779,13 +779,21 @@ impl ServerHandler for McpMuxGatewayHandler {
             };
         }
 
+        self.ensure_roots_probed(
+            &context.peer,
+            session_id,
+            &oauth_ctx.client_id,
+        )
+        .await;
+
         // Resolve routing — the binding's target space is authoritative,
         // which may differ from oauth_ctx.space_id.
         let (space_id, feature_set_ids) = self
             .resolve_routing(session_id, &oauth_ctx.client_id)
             .await?;
 
-        // Hard cut: reject direct backend tool calls — agents must use mcpmux_invoke_tool.
+        // Hard cut: non-surfaced backend tools must use mcpmux_invoke_tool.
+        // Surfaced tools stay in tools/list for one-hop calls.
         let space_id_str = space_id.to_string();
         if let Ok(Some((server_id, actual_tool_name))) = self
             .services
@@ -794,18 +802,38 @@ impl ServerHandler for McpMuxGatewayHandler {
             .find_server_for_qualified_tool(&space_id_str, &params.name)
             .await
         {
-            let message = crate::pool::format_direct_call_redirect(
-                &params.name,
-                &server_id,
-                &actual_tool_name,
-            );
-            return Ok(CallToolResult::error(vec![Content::text(
-                serde_json::json!({
-                    "error": "use_invoke_tool",
-                    "message": message,
-                })
-                .to_string(),
-            )]));
+            let advertised = self
+                .services
+                .pool_services
+                .feature_service
+                .get_advertised_tools_for_grants(
+                    &space_id_str,
+                    &feature_set_ids,
+                    session_id,
+                )
+                .await
+                .map_err(|e| {
+                    McpError::internal_error(format!("Failed to get advertised tools: {}", e), None)
+                })?;
+
+            let is_surfaced = advertised
+                .iter()
+                .any(|feature| feature.qualified_name() == params.name.as_ref());
+
+            if !is_surfaced {
+                let message = crate::pool::format_direct_call_redirect(
+                    &params.name,
+                    &server_id,
+                    &actual_tool_name,
+                );
+                return Ok(CallToolResult::error(vec![Content::text(
+                    serde_json::json!({
+                        "error": "use_invoke_tool",
+                        "message": message,
+                    })
+                    .to_string(),
+                )]));
+            }
         }
 
         // Call tool via routing service (handles auth and routing)
diff --git a/docs/guide/feature-sets.mdx b/docs/guide/feature-sets.mdx
index e7ee156e..56471d0a 100644
--- a/docs/guide/feature-sets.mdx
+++ b/docs/guide/feature-sets.mdx
@@ -1,9 +1,11 @@
 ---
 title: FeatureSets — Permission Control
-description: FeatureSets control which MCP tools, resources, and prompts each AI client can access in McpMux. Create role-based permissions, domain bundles, or read-only views.
+description: FeatureSets control which MCP tools AI clients can invoke and optionally promote into tools/list. Create role-based permissions, domain bundles, or read-only views.
 ---
 
-FeatureSets are permission bundles that control what MCP capabilities (tools, resources, and prompts) each AI client can access. They let you grant fine-grained permissions per client, per Space.
+FeatureSets are permission bundles that control what MCP capabilities each AI client can use in a Space. For **tools**, they act as an **invoke ACL**: they define what agents can reach through `mcpmux_search_tools` and `mcpmux_invoke_tool`. They do **not** dump every permitted tool into the client's tool list by default — that keeps context windows lean.
+
+Resources and prompts still follow the classic grant model (included members are exposed when the client lists them).
 
 ## Why FeatureSets
 
@@ -50,6 +52,26 @@ Exclude rules always win over include rules. This means you can create a permiss
 1. Include the **GitHub — All** ServerAll FeatureSet
 2. Exclude `delete_repository`, `delete_branch`, `delete_file`
 
+## Included vs Surface (FeatureSet editor)
+
+When you edit a custom FeatureSet, each tool row has two independent controls:
+
+| Control | What it does | Client effect |
+| ------- | ------------ | --------------- |
+| **Checkbox** (left) | **Include** the tool in this FeatureSet's invoke ACL | Tool is **invokable** via `mcpmux_search_tools` → `mcpmux_get_tool_schema` → `mcpmux_invoke_tool`. It does **not** appear in the client's `tools/list`. |
+| **Surface** button (right, monitor icon) | **Promote** an already-included tool into `tools/list` | Tool appears alongside the ~12 `mcpmux_*` meta tools. The agent can call it **directly** (one hop) instead of going through `mcpmux_invoke_tool`. |
+
+**Rules:**
+
+- **Surface only appears when the checkbox is on.** You cannot surface a tool you have not included.
+- **Default is checkbox on, Surface off.** Most backend tools stay off the client tool list; agents discover them through search + invoke.
+- **Use Surface sparingly.** Each promoted tool adds its full schema to the client context window. Reserve it for hot paths you call constantly (e.g. one GitHub read tool).
+- **The server header toggle** (Enable All / Disable All) bulk-selects checkboxes for that server — it is **not** the Surface control.
+
+**Example:** A "GitHub read-only" FeatureSet might include `list_issues` and `get_me` (both checked), with **Surface on** only for `list_issues`. Cursor shows `github_list_issues` in its tool list; `get_me` stays invoke-only.
+
+Connected clients always see the fixed `mcpmux_*` meta surface regardless of FeatureSet membership. See [Self-management meta tools](#self-management-meta-tools) below.
+
 ## Composition
 
 FeatureSets can **contain other FeatureSets**. This lets you build hierarchical permission structures:
@@ -95,8 +117,11 @@ FeatureSets can **contain other FeatureSets**. This lets you build hierarchical
 1. Go to the **FeatureSets** page
 2. Click **Create FeatureSet**
 3. Give it a name and optional description
-4. Add members — select features or other FeatureSets
-5. Set each member to include or exclude mode
+4. Under **Included Features**, check the tools/resources/prompts to allow (invoke ACL for tools)
+5. Optionally click **Surface** on individual included tools you want promoted into client `tools/list`
+6. Save — if a connected MCP client is open, reload its tools after changing Surface toggles
+
+You can also nest FeatureSets (include another FeatureSet as a member) and set each member to include or exclude mode.
 
 ### Assigning to Clients
 
@@ -104,6 +129,20 @@ FeatureSets are assigned to clients per Space. Go to the **Clients** page, selec
 
 A client's effective permissions are the combination of all its granted FeatureSets, with exclude rules taking priority.
 
+Workspace **bindings** attach FeatureSets to folder roots so the invoke ACL follows the project you have open. Client grants stack additional FeatureSets on top.
+
+### Self-management meta tools
+
+McpMux exposes a built-in `mcpmux_*` namespace (~12 tools) for server toggles, search, schema load, and invoke. FeatureSets control the **backend** pool those meta tools can reach; they do not replace the meta tools themselves.
+
+Typical agent flow for a non-surfaced backend tool:
+
+1. `mcpmux_search_tools` — find tools allowed by the active FeatureSet
+2. `mcpmux_get_tool_schema` — read parameter names before calling
+3. `mcpmux_invoke_tool` — run the backend tool
+
+See the [Gateway](/docs/gateway/) doc for how bindings, session enable/disable, and FeatureSet members compose at request time.
+
 ## Next Steps
 
 - [Set up Clients](/docs/clients/) and assign FeatureSets per Space
diff --git a/docs/planning/meta-gateway-invoke-qa.md b/docs/planning/meta-gateway-invoke-qa.md
index d23a901d..82b561e7 100644
--- a/docs/planning/meta-gateway-invoke-qa.md
+++ b/docs/planning/meta-gateway-invoke-qa.md
@@ -15,7 +15,17 @@ One-session checklist for validating Phases A–C (search → schema → invoke,
 - [x] Confirm McpMux endpoint: `http://localhost:45818/mcp`
 - [x] Have at least one OAuth server (GitHub) **installed and connected** — `QA: meta-gateway invoke` FeatureSet bound in UI (May 25)
 - [x] Workspace binding with GWorkspace (or target server) configured in UI — **not** via agent `mcpmux_bind_current_workspace`
-- [ ] Optional for Phase C tests: create a FeatureSet with 1–2 GitHub tools, bind to workspace; leave surfaced off until test 8
+- [x] Optional for Phase C tests: create a FeatureSet with 1–2 GitHub tools, bind to workspace; leave surfaced off until test 8 — `QA: meta-gateway invoke` (`list_issues` + `get_me`, surfaced off, bound May 25)
+
+**FeatureSet editor controls (tests 8–9):**
+
+| Control | Role in QA |
+| ------- | ---------- |
+| **Checkbox** | Include tool in invoke ACL → search + `mcpmux_invoke_tool` |
+| **Surface** button | Promote included tool into client `tools/list` → direct one-hop call (test 9 only) |
+| **Server header toggle** | Bulk include/exclude — not Surface |
+
+After any Surface change: **Cursor → MCP → Reload tools**.
 
 **Tester:** Cursor agent (Composer)  
 **Date:** May 25, 2026  
@@ -200,7 +210,7 @@ Confirm results are scoped to that server_id only.
 
 ## 8. FeatureSet ACL — partial tool set (Phase C)
 
-**Setup:** FeatureSet with 1–2 GitHub tools included, bound to workspace, surfaced **off**.
+**Setup:** FeatureSet with 1–2 GitHub tools **checked** (included), bound to workspace, **Surface off** on all rows.
 
 **Prompt:**
 
@@ -214,15 +224,15 @@ I bound a FeatureSet that only allows specific GitHub tools.
 
 | Check | Pass | Fail | Notes |
 | ----- | ---- | ---- | ----- |
-| Search only finds allowed tools | ☐ | ☐ | |
-| Invoke denied for disallowed tool | ☐ | ☐ | |
-| Invoke succeeds for allowed tool | ☐ | ☐ | |
+| Search only finds allowed tools | ☑ | ☐ | `query: "github"` + empty query → 2 hits: `github_get_me`, `github_list_issues` only (not 41) |
+| Invoke denied for disallowed tool | ☑ | ☐ | `create_issue` → `tool 'github_create_issue' is not invokable with current grants` |
+| Invoke succeeds for allowed tool | ☑ | ☐ | `list_issues` (3 open issues) + `get_me` (`crimsonsunset`) both succeeded |
 
 ---
 
 ## 9. Surfaced tool promotion (Phase C)
 
-**Setup:** In FeatureSet editor, toggle **Surface in client** on one included tool. Reload MCP tools.
+**Setup:** In FeatureSet editor, leave **`list_issues` checked** and click **Surface** (blue) on that row only; leave other included tools checked but Surface off. Save, then **Cursor → MCP → Reload tools**.
 
 **Prompt:**
 
@@ -234,9 +244,9 @@ I bound a FeatureSet that only allows specific GitHub tools.
 
 | Check | Pass | Fail | Notes |
 | ----- | ---- | ---- | ----- |
-| Surfaced tool appears in client tool list | ☐ | ☐ | |
-| Surfaced tool callable without invoke wrapper | ☐ | ☐ | |
-| Non-surfaced backend still requires invoke | ☐ | ☐ | |
+| Surfaced tool appears in client tool list | ☑ | ☐ | After Cursor MCP reload: 10 `mcpmux_*` + `github_list_issues` only; `github_get_me` not listed |
+| Surfaced tool callable without invoke wrapper | ☑ | ☐ | Direct `github_list_issues` → 2 open issues (no `use_invoke_tool` redirect) after handler fix + binding reload May 25 |
+| Non-surfaced backend still requires invoke | ☑ | ☐ | `get_me` absent from tools/list; `mcpmux_invoke_tool` → `crimsonsunset` OK |
 
 ---
 
@@ -296,7 +306,7 @@ Rules: McpMux meta tools only, read schemas before invoke, note truncation if an
 | ---- | ------ |
 | Phase A — meta invoke core | ☑ Pass ☐ Fail |
 | Phase B — result shaping | ☑ Pass ☐ Fail |
-| Phase C — ACL + surfaced | ☐ Pass ☐ Fail ☐ Skipped |
+| Phase C — ACL + surfaced | ☑ Pass ☐ Fail ☐ Skipped |
 | Overall | ☐ Ship ☐ Block |
 
 **Blockers / issues filed:**
@@ -304,4 +314,5 @@ Rules: McpMux meta tools only, read schemas before invoke, note truncation if an
 ```
 - section 6 JSON rows: manual pass May 25 after binding QA FeatureSet — github_list_issues filter verified live
 - beeper 401 on get_accounts/search_chats — auth expired; not blocking meta-gateway QA
+- test 9: surfaced direct one-hop + invoke-only non-surfaced — pass May 25 live (`github_list_issues` direct → 2 issues; `get_me` via invoke only)
 ```
diff --git a/docs/planning/meta-gateway-invoke.md b/docs/planning/meta-gateway-invoke.md
index 539f7555..4c9eed40 100644
--- a/docs/planning/meta-gateway-invoke.md
+++ b/docs/planning/meta-gateway-invoke.md
@@ -246,6 +246,9 @@ Prompts and resources: unchanged — still materialized per grants. Invoke model
 - [x] FeatureSet member model: tools invokable by default when server in set; optional `surfaced: true` promotes into `tools/list`
 - [x] Search + invoke respect FeatureSet member filter (not just server-all)
 - [x] Workspaces UI: per-tool "Surface in client" toggle in FeatureSet editor (`FeatureSetPanel.tsx`)
+  - **Checkbox** = invoke ACL member (search + `mcpmux_invoke_tool`)
+  - **Surface button** = promote that included tool into client `tools/list` for direct one-hop calls
+  - User-facing explainer: [`docs/guide/feature-sets.mdx`](../guide/feature-sets.mdx#included-vs-surface-featureset-editor)
 - [ ] Update `mcpmux_create_feature_set` to accept optional `surfaced_tools[]` (UI path done; meta-tool arg deferred)
 - [x] Integration tests: binding with partial tool set → search only finds allowed tools; surfaced tool appears in `tools/list`
 
diff --git a/tests/rust/tests/integration/meta_gateway_invoke.rs b/tests/rust/tests/integration/meta_gateway_invoke.rs
index 134b23f4..9913b119 100644
--- a/tests/rust/tests/integration/meta_gateway_invoke.rs
+++ b/tests/rust/tests/integration/meta_gateway_invoke.rs
@@ -581,3 +581,67 @@ async fn surfaced_tool_appears_in_advertised_set() {
     assert_eq!(advertised[0].feature_name, "list_issues");
     assert_eq!(advertised[0].qualified_name(), "github_list_issues");
 }
+
+#[tokio::test(flavor = "multi_thread")]
+async fn direct_backend_call_gate_allows_surfaced_only() {
+    let f = Fixture::new().await;
+
+    let features = f
+        .server_feature_repo
+        .list_for_space(&f.space_id.to_string())
+        .await
+        .unwrap();
+    let list_issues = features
+        .iter()
+        .find(|feat| feat.feature_name == "list_issues")
+        .unwrap();
+
+    let mut get_me = ServerFeature::tool(f.space_id, "github", "get_me");
+    get_me.description = Some("Get authenticated GitHub user".into());
+    f.server_feature_repo.upsert(&get_me).await.unwrap();
+
+    let mut mixed_fs = FeatureSet::new_custom("Mixed Surfaced GitHub", f.space_id.to_string());
+    mixed_fs.members.push(FeatureSetMember {
+        id: Uuid::new_v4().to_string(),
+        feature_set_id: mixed_fs.id.clone(),
+        member_type: MemberType::Feature,
+        member_id: list_issues.id.to_string(),
+        mode: MemberMode::Include,
+        surfaced: true,
+    });
+    mixed_fs.members.push(FeatureSetMember {
+        id: Uuid::new_v4().to_string(),
+        feature_set_id: mixed_fs.id.clone(),
+        member_type: MemberType::Feature,
+        member_id: get_me.id.to_string(),
+        mode: MemberMode::Include,
+        surfaced: false,
+    });
+    f.feature_set_repo.create(&mixed_fs).await.unwrap();
+    f.grant_feature_set(&mixed_fs.id).await;
+    f.session_overrides.enable(&f.session_id, "github");
+
+    let fs_ids = vec![mixed_fs.id.clone()];
+    let invokable = f
+        .feature_service
+        .get_invokable_tools_for_grants(&f.space_id.to_string(), &fs_ids, Some(&f.session_id))
+        .await
+        .unwrap();
+    let advertised = f
+        .feature_service
+        .get_advertised_tools_for_grants(&f.space_id.to_string(), &fs_ids, Some(&f.session_id))
+        .await
+        .unwrap();
+
+    assert_eq!(invokable.len(), 2);
+    assert_eq!(advertised.len(), 1);
+    assert_eq!(advertised[0].qualified_name(), "github_list_issues");
+
+    let is_surfaced = |qualified_name: &str| {
+        advertised
+            .iter()
+            .any(|feature| feature.qualified_name() == qualified_name)
+    };
+    assert!(is_surfaced("github_list_issues"));
+    assert!(!is_surfaced("github_get_me"));
+}

From 5508c5e0032cced1c47e9bca7ff8b7d379f73ecb Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 15:21:29 -0600
Subject: [PATCH 43/48] docs(planning): complete meta-gateway invoke manual QA
 sign-off

Record test 11 end-to-end pass and mark the runbook ready to ship.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 docs/planning/meta-gateway-invoke-qa.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/planning/meta-gateway-invoke-qa.md b/docs/planning/meta-gateway-invoke-qa.md
index 82b561e7..7a1bd9c5 100644
--- a/docs/planning/meta-gateway-invoke-qa.md
+++ b/docs/planning/meta-gateway-invoke-qa.md
@@ -282,9 +282,9 @@ Rules: McpMux meta tools only, read schemas before invoke, note truncation if an
 
 | Check | Pass | Fail | Notes |
 | ----- | ---- | ---- | ----- |
-| Completed without backend tool name guessing | ☐ | ☐ | |
-| Schema-first invoke pattern | ☐ | ☐ | |
-| Sensible output despite truncation | ☐ | ☐ | |
+| Completed without backend tool name guessing | ☑ | ☐ | search `"list issues"` → `github_list_issues`; no param guessing |
+| Schema-first invoke pattern | ☑ | ☐ | `mcpmux_get_tool_schema` before invoke (`owner`, `repo`, `state`, `perPage`) |
+| Sensible output despite truncation | ☑ | ☐ | 5 open issues; filter `max_rows: 3` → 3 titles + `{ returned: 3, total: 5, truncated: true }` |
 
 ---
 
@@ -307,7 +307,7 @@ Rules: McpMux meta tools only, read schemas before invoke, note truncation if an
 | Phase A — meta invoke core | ☑ Pass ☐ Fail |
 | Phase B — result shaping | ☑ Pass ☐ Fail |
 | Phase C — ACL + surfaced | ☑ Pass ☐ Fail ☐ Skipped |
-| Overall | ☐ Ship ☐ Block |
+| Overall | ☑ Ship ☐ Block |
 
 **Blockers / issues filed:**
 

From 6884742b23027fe7833077bda7f00f43628bd38a Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 15:24:11 -0600
Subject: [PATCH 44/48] docs(planning): sync meta-gateway invoke status with QA
 sign-off
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Align planning doc with Ship result, surfaced one-hop exception, and
completed Phase A–C checklist; refresh QA runbook red-flag wording.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 docs/planning/meta-gateway-invoke-qa.md |  4 +-
 docs/planning/meta-gateway-invoke.md    | 54 ++++++++++++++-----------
 2 files changed, 32 insertions(+), 26 deletions(-)

diff --git a/docs/planning/meta-gateway-invoke-qa.md b/docs/planning/meta-gateway-invoke-qa.md
index 7a1bd9c5..5fb05255 100644
--- a/docs/planning/meta-gateway-invoke-qa.md
+++ b/docs/planning/meta-gateway-invoke-qa.md
@@ -29,7 +29,7 @@ After any Surface change: **Cursor → MCP → Reload tools**.
 
 **Tester:** Cursor agent (Composer)  
 **Date:** May 25, 2026  
-**McpMux version / commit:** `feat/meta-gateway-invoke` @ `433e7bd` (PR [#155](https://github.com/mcpmux/mcp-mux/pull/155))
+**McpMux version / commit:** `feat/meta-gateway-invoke` @ `5508c5e` (PR [#155](https://github.com/mcpmux/mcp-mux/pull/155))
 
 ---
 
@@ -291,7 +291,7 @@ Rules: McpMux meta tools only, read schemas before invoke, note truncation if an
 ## Red flags (stop and file a bug)
 
 - [ ] Backend tools (`github_*`, etc.) appear in `tools/list` without surfacing
-- [ ] Agent can call backend tools directly (bypassing `mcpmux_invoke_tool`)
+- [ ] Non-surfaced backend tools callable directly (bypassing `mcpmux_invoke_tool`) — surfaced one-hop is expected
 - [ ] Enable server expands `tools/list` beyond meta + surfaced
 - [ ] Search returns tools from inactive or unbound servers
 - [ ] Invoke succeeds for tools outside FeatureSet ACL
diff --git a/docs/planning/meta-gateway-invoke.md b/docs/planning/meta-gateway-invoke.md
index 4c9eed40..7c5ad357 100644
--- a/docs/planning/meta-gateway-invoke.md
+++ b/docs/planning/meta-gateway-invoke.md
@@ -1,7 +1,7 @@
 # Meta-Gateway Invoke (Search → Schema → Invoke)
 
 **Last Updated:** May 25, 2026
-**Status:** Implemented on branch — manual QA in progress ([`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md))
+**Status:** ✅ Phases A–C implemented and manually QA complete — ready to merge ([`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md) **Ship**)
 **Branch:** `feat/meta-gateway-invoke`
 **Base branch:** `main`
 **Issue:** [#155](https://github.com/mcpmux/mcp-mux/pull/155)
@@ -51,7 +51,7 @@ This doc defines that model for McpMux while preserving its product strengths: O
 | 7 | Invoke authorization | **Fail closed** — `invoke_tool` rejects when target server/tool is outside effective permission set | Same composition as today: `(binding_servers ∪ session_enabled) − session_disabled`, then FeatureSet member filter. Empty effective set → invoke denied with actionable error, not silent proxy. |
 | 8 | Session enable/disable | **Keep existing `mcpmux_enable_server` / `mcpmux_disable_server`** — they gate invoke/search eligibility, not `tools/list` size | Mental model unchanged: "turn on github" expands what search/invoke can reach. `tools/list` size stays ~constant. |
 | 9 | Error messages | **Actionable, bounded errors** — no dumping full available-tool lists | e.g. `"github inactive → mcpmux_enable_server('github')"`, `"unknown tool → did you mean github_list_issues?"`. Optional Levenshtein suggestions (Phase D). |
-| 10 | Rollout | **Hard cut — no legacy opt-out** | Backend tools never appear in `tools/list`. Direct `call_tool` on backend qualified names is rejected with an actionable redirect to `mcpmux_invoke_tool`. No `expose_backend_tools_in_list` setting. Ship in one release; document migration in CHANGELOG. |
+| 10 | Rollout | **Hard cut — no legacy opt-out** | Non-surfaced backend tools never appear in `tools/list` and direct `call_tool` is rejected with a redirect to `mcpmux_invoke_tool`. **Exception:** FeatureSet members marked `surfaced: true` are promoted into `tools/list` and callable in one hop. No `expose_backend_tools_in_list` setting. Ship in one release; document migration in CHANGELOG. |
 | 11 | `mcpmux_list_all_tools` | **Keep as operator/diagnostic tool** — not the primary agent discovery path | Still useful for FeatureSet authoring and UI. Doc + descriptions steer agents to `search_tools`. Consider server_id filter arg in Phase A to avoid 855 KB dumps. |
 | 12 | Result shaping scope | **Phase B only on `invoke_tool`** — opt-in via explicit `filter`: `max_rows`, `max_bytes`, `fields`, `format: summary`. Omit filter → backend response as-is. | Agents pass `filter` when they know a tool returns large payloads. No default truncation. |
 | 13 | REST / OpenAPI capabilities | **Out of scope here** — Phase E / separate planning doc | [`web-admin-remote-access.md`](./web-admin-remote-access.md) covers admin REST, not REST→MCP capability YAML. No conflict; different layer. |
@@ -87,8 +87,8 @@ tools/list (fixed ~10–15 tools)
 4. mcpmux_get_tool_schema({ tools: ["github_list_issues"] })
 5. mcpmux_invoke_tool({
      server_id: "github",
-     tool: "github_list_issues",
-     args: { owner: "mcpmux", repo: "mcp-mux" }
+     tool: "list_issues",
+     args: { owner: "mcpmux", repo: "mcp-mux", state: "OPEN" }
    })
 ```
 
@@ -166,7 +166,7 @@ Prompts and resources: unchanged — still materialized per grants. Invoke model
 | `crates/mcpmux-gateway/src/services/meta_tools/invoke.rs` | `InvokeToolTool` impl — permission check, routing, error mapping, result shaping | ✅ Done |
 | `crates/mcpmux-gateway/src/services/meta_tools/invoke_backend.rs` | `InvokeToolBackend` trait + `RoutingService` adapter for testable invoke routing | ✅ Done |
 | `tests/rust/src/canned_invoke_backend.rs` | Canned backend for filter e2e integration tests | ✅ Done |
-| `tests/rust/tests/integration/meta_gateway_invoke.rs` | Search, schema, invoke, permission deny, surfaced tools, filter shaping, e2e filter via canned backend | ✅ Done (17 tests) |
+| `tests/rust/tests/integration/meta_gateway_invoke.rs` | Search, schema, invoke, permission deny, surfaced tools, filter shaping, e2e filter via canned backend | ✅ Done (16 tests) |
 | `docs/planning/meta-gateway-invoke-qa.md` | Manual QA runbook for Phases A–C | ✅ Done |
 | `docs/planning/meta-gateway-invoke.md` | This doc | ✅ Done |
 
@@ -181,11 +181,12 @@ Prompts and resources: unchanged — still materialized per grants. Invoke model
 | [`crates/mcpmux-gateway/src/pool/features/facade.rs`](../../crates/mcpmux-gateway/src/pool/features/facade.rs) | Split into `get_advertised_tools_for_grants` vs `get_invokable_tools_for_grants` | ✅ Done |
 | [`crates/mcpmux-gateway/src/pool/features/resolution.rs`](../../crates/mcpmux-gateway/src/pool/features/resolution.rs) | `resolve_surfaced_feature_ids` for surfaced promotion | ✅ Done |
 | [`crates/mcpmux-gateway/src/pool/routing.rs`](../../crates/mcpmux-gateway/src/pool/routing.rs) | `format_direct_call_redirect`; actionable invoke errors | ✅ Done |
-| [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) | `tools/list` uses advertised set only; direct backend `call_tool` rejected with invoke redirect | ✅ Done |
+| [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) | `tools/list` uses advertised set only; non-surfaced direct `call_tool` rejected with invoke redirect; surfaced tools allowed one-hop; `ensure_roots_probed` before routing in `call_tool` | ✅ Done |
 | [`crates/mcpmux-core/src/domain/feature_set.rs`](../../crates/mcpmux-core/src/domain/feature_set.rs) | `surfaced: bool` on `FeatureSetMember` | ✅ Done |
-| [`apps/desktop/src/features/featuresets/FeatureSetPanel.tsx`](../../apps/desktop/src/features/featuresets/FeatureSetPanel.tsx) | Per-tool "Surface in client" toggle | ✅ Done |
-| [`apps/desktop/src/features/settings/SettingsPage.tsx`](../../apps/desktop/src/features/settings/SettingsPage.tsx) | Update meta-tools copy for search → schema → invoke workflow | ⬜ Pending |
-| [`README.md`](../../README.md) | Replace "every tool available right now" agent-facing claim; document search → schema → invoke flow | ⬜ Pending |
+| [`apps/desktop/src/features/featuresets/FeatureSetPanel.tsx`](../../apps/desktop/src/features/featuresets/FeatureSetPanel.tsx) | Per-tool "Surface in client" toggle + explainer tooltip | ✅ Done |
+| [`apps/desktop/src/features/settings/SettingsPage.tsx`](../../apps/desktop/src/features/settings/SettingsPage.tsx) | Meta-tools copy for search → schema → invoke workflow | ✅ Done |
+| [`README.md`](../../README.md) | Agent-facing search → schema → invoke flow; checkbox vs Surface in Feature Sets | ✅ Done |
+| [`docs/guide/feature-sets.mdx`](../guide/feature-sets.mdx) | Included vs Surface editor explainer; invoke ACL semantics | ✅ Done |
 
 ---
 
@@ -194,17 +195,17 @@ Prompts and resources: unchanged — still materialized per grants. Invoke model
 ### Phase A — Meta invoke core
 
 **Effort:** ~3–4 days  
-**Status:** ✅ Implemented — manual QA sections 0–4 pass; section 5 pass; section 6 pending ([`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md))
+**Status:** ✅ Implemented — manual QA sections 0–4 pass ([`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md))
 
 - [x] `ToolDiscoveryService` — build index from Space features; search by query + optional `server_id`; return matches at `detail_level`
 - [x] `mcpmux_search_tools` meta tool — pagination (`limit`, `cursor`), `detail_level` enum
 - [x] `mcpmux_get_tool_schema` — single + batch; `compact` strips descriptions/examples
 - [x] `mcpmux_invoke_tool` — `{ server_id, tool, args }`; delegates to `RoutingService::call_tool`; fail closed on permission miss
 - [x] `FeatureService` split: **advertised** = meta tools + surfaced only (hard cut — no backend tools in list)
-- [x] Handler rejects direct backend `call_tool` — return actionable error pointing to `mcpmux_invoke_tool`
+- [x] Handler rejects **non-surfaced** direct backend `call_tool` — redirect to `mcpmux_invoke_tool`; surfaced tools pass through
 - [x] Actionable error mapping: inactive server, unknown tool, permission denied, param validation passthrough from backend
 - [x] Optional `server_id` filter on `mcpmux_list_all_tools`
-- [x] Integration tests: GitHub read path (enable → search → schema → invoke); deny when server inactive; direct `github_*` call rejected
+- [x] Integration tests: GitHub read path (enable → search → schema → invoke); deny when server inactive; non-surfaced direct call rejected
 
 **Outcome:** Cursor session shows **10** `mcpmux_*` tools (verified May 25, 2026). Agent completes `github_list_issues` on `mcpmux/mcp-mux` via search → schema → invoke with zero param guessing.
 
@@ -241,7 +242,7 @@ Prompts and resources: unchanged — still materialized per grants. Invoke model
 ### Phase C — FeatureSet as invoke ACL + surfaced tools
 
 **Effort:** ~3 days  
-**Status:** ✅ Implemented — manual QA sections 8–9 pending
+**Status:** ✅ Implemented — manual QA sections 8–9 pass ([`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md))
 
 - [x] FeatureSet member model: tools invokable by default when server in set; optional `surfaced: true` promotes into `tools/list`
 - [x] Search + invoke respect FeatureSet member filter (not just server-all)
@@ -249,8 +250,8 @@ Prompts and resources: unchanged — still materialized per grants. Invoke model
   - **Checkbox** = invoke ACL member (search + `mcpmux_invoke_tool`)
   - **Surface button** = promote that included tool into client `tools/list` for direct one-hop calls
   - User-facing explainer: [`docs/guide/feature-sets.mdx`](../guide/feature-sets.mdx#included-vs-surface-featureset-editor)
-- [ ] Update `mcpmux_create_feature_set` to accept optional `surfaced_tools[]` (UI path done; meta-tool arg deferred)
-- [x] Integration tests: binding with partial tool set → search only finds allowed tools; surfaced tool appears in `tools/list`
+- [x] `mcpmux_create_feature_set` accepts optional `surfaced_tools[]` (subset of `tool_qualified_names`; UI path also available)
+- [x] Integration tests: partial FeatureSet binding limits search; surfaced vs invokable gate; advertised set promotion
 
 ### Phase D — Advanced optimizations (defer)
 
@@ -290,7 +291,7 @@ Prompts and resources: unchanged — still materialized per grants. Invoke model
 | Full validate | `pnpm validate` | fmt, clippy, check, eslint, typecheck |
 | Rust tests | `pnpm test:rust` | unit + `meta_gateway_invoke.rs` integration |
 | TS tests | `pnpm test:ts` | vitest |
-| Manual smoke | Cursor against live gateway: GitHub read, GWorkspace invoke, permission deny | Agent UX verification |
+| Manual smoke | Cursor against live gateway — full runbook sections 0–11 | Agent UX verification — ✅ complete May 25 |
 
 ---
 
@@ -316,7 +317,7 @@ Prompts and resources: unchanged — still materialized per grants. Invoke model
 | [`crates/mcpmux-gateway/src/services/meta_tools/invoke.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/invoke.rs) | Invoke meta tool + result shaping |
 | [`crates/mcpmux-gateway/src/services/meta_tools/invoke_backend.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/invoke_backend.rs) | Pluggable invoke routing trait |
 | [`tests/rust/src/canned_invoke_backend.rs`](../../tests/rust/src/canned_invoke_backend.rs) | Test double for filter e2e |
-| [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) | `tools/list` + `call_tool` handler — legacy direct call blocking |
+| [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) | `tools/list` + `call_tool` — advertised set, surfaced one-hop, invoke redirect for non-surfaced |
 | [`docs/planning/dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) | Session enable/disable — kept, semantics updated |
 | [`docs/planning/tool-level-session-pin.md`](./tool-level-session-pin.md) | Superseded for token budget; Phase F very optional rework |
 
@@ -335,17 +336,19 @@ Prompts and resources: unchanged — still materialized per grants. Invoke model
 
 ## Reconciliation
 
-This doc is the source of truth for the meta-gateway invoke model. Phases A–C are implemented on `feat/meta-gateway-invoke`; manual QA tracked in [`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md). Mark [`tool-level-session-pin.md`](./tool-level-session-pin.md) **Status** as *Superseded* once Phase A ships to main.
+This doc is the source of truth for the meta-gateway invoke model. Phases A–C are implemented on `feat/meta-gateway-invoke` and manually QA complete ([`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md) — **Ship**). Mark [`tool-level-session-pin.md`](./tool-level-session-pin.md) **Status** as *Superseded* when this branch merges to main.
 
-**Decision record (May 25, 2026):** Hard cut to invoke-only — no legacy direct backend exposure. Surfaced tools default zero everywhere (bundles included). FeatureSets redefine as invoke ACL + optional surfaced promotion. Session pin deferred to Phase F (very optional, last). Competitor analysis (MikkoParkkola + abdullah1854) informed Phase A–B scope; REST capabilities in Phase E / separate doc.
+**Decision record (May 25, 2026):** Hard cut to invoke-only for non-surfaced backend tools — no legacy full-catalog `tools/list`. Surfaced tools default zero everywhere (bundles included); opt-in per FeatureSet member for one-hop hot paths. FeatureSets redefine as invoke ACL + optional surfaced promotion. Session pin deferred to Phase F (very optional, last). Competitor analysis (MikkoParkkola + abdullah1854) informed Phase A–B scope; REST capabilities in Phase E / separate doc.
+
+**Handler fix (May 25, 2026):** `call_tool` probes workspace roots before routing (matches `list_tools`) and allows direct calls when the tool is in `get_advertised_tools_for_grants` (surfaced). Non-surfaced backend names still get `use_invoke_tool` redirect.
 
 **Design revision (May 25, 2026):** Removed default smart truncation — `filter` is opt-in only. Rationale: plain-text MCP backends (GWorkspace) don't map cleanly to JSON row truncation; agents should explicitly bound payloads when needed.
 
-**QA ergonomics (May 25, 2026):** Bind FeatureSets in Workspaces UI before agent QA — session enable alone is insufficient without binding ACL. Do **not** call `mcpmux_bind_current_workspace` during routine QA (triggers Space-wide approval modal). Reload MCP tools after UI binding changes.
+**QA ergonomics (May 25, 2026):** Bind FeatureSets in Workspaces UI before agent QA — session enable alone is insufficient without binding ACL. Do **not** call `mcpmux_bind_current_workspace` during routine QA (triggers Space-wide approval modal). Reload MCP tools after UI binding or Surface changes.
 
-**Test coverage (May 25, 2026):** Phase B filter shaping — 13 unit tests in `invoke.rs`, 17 integration tests in `meta_gateway_invoke.rs`, manual QA section 6 pass on live `github_list_issues`.
+**Test coverage (May 25, 2026):** Phase B filter shaping — 13 unit tests in `invoke.rs`, 16 integration tests in `meta_gateway_invoke.rs`, manual QA sections 0–11 pass on live gateway.
 
-**Manual QA progress (May 25, 2026):**
+**Manual QA progress (May 25, 2026):** Overall **Ship**. Full section results in [`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md). Highlights:
 
 | QA section | Result | Notes |
 | ---------- | ------ | ----- |
@@ -354,7 +357,10 @@ This doc is the source of truth for the meta-gateway invoke model. Phases A–C
 | 2 — Fail-closed + recovery | ✅ Pass | Session disable → actionable error → enable → retry |
 | 3 — Search detail levels + compact schema | ✅ Pass | compact omits top-level description only |
 | 4 — Session toggle (list size unchanged) | ✅ Pass | search empty when disabled; 10 meta tools stable |
-| 5 — Pass-through without filter (Phase B) | ✅ Pass | GWorkspace `list_drive_items` @ `433e7bd`: 100 items, ~45k chars, no metadata |
-| 6 — Explicit filter (Phase B) | ✅ Pass | Plain-text `max_bytes` + live `github_list_issues` JSON filter (`max_rows`, `fields`, `summary`) |
+| 5 — Pass-through without filter (Phase B) | ✅ Pass | GWorkspace `list_drive_items`: 100 items, no metadata envelope |
+| 6 — Explicit filter (Phase B) | ✅ Pass | Plain-text `max_bytes` + live `github_list_issues` JSON filter |
 | 7 — Clone disambiguation | ✅ Pass | Personal vs S2H clone scoped correctly |
+| 8 — FeatureSet ACL (Phase C) | ✅ Pass | Partial GitHub tool set; invoke deny outside ACL |
+| 9 — Surfaced promotion (Phase C) | ✅ Pass | `github_list_issues` in tools/list + direct one-hop; `get_me` invoke-only |
 | 10 — Diagnostic list vs search | ✅ Pass | 120 tools both paths for GWorkspace Personal |
+| 11 — End-to-end agent task | ✅ Pass | Meta-only workflow; schema-first; filter truncation metadata |

From 85113e7e6a95095ba6aeac2c35483d69f7adf498 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 15:30:48 -0600
Subject: [PATCH 45/48] fix(gateway): improve meta-tool DX for ACL, schema
 batch, and max_bytes

list_all_tools now exposes invokable vs server_available with counts;
get_tool_schema accepts array and JSON-encoded array forms and reports
missing names; invoke filter applies max_bytes to JSON arrays without max_rows.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 .../src/services/meta_tools/invoke.rs         |  18 ++-
 .../src/services/meta_tools/tools.rs          | 137 ++++++++++++----
 .../tests/integration/meta_gateway_invoke.rs  | 153 ++++++++++++++++++
 3 files changed, 278 insertions(+), 30 deletions(-)

diff --git a/crates/mcpmux-gateway/src/services/meta_tools/invoke.rs b/crates/mcpmux-gateway/src/services/meta_tools/invoke.rs
index b33a42b2..1f24f231 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/invoke.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/invoke.rs
@@ -378,11 +378,11 @@ fn shape_array(items: Vec<Value>, filter: &InvokeResultFilter, data_key: &str) -
     let filtered_items = apply_fields_filter(items, filter);
 
     let Some(max_rows) = filter.max_rows else {
-        return Value::Array(filtered_items);
+        return enforce_byte_limit(Value::Array(filtered_items), filter);
     };
 
     if total <= max_rows {
-        return Value::Array(filtered_items);
+        return enforce_byte_limit(Value::Array(filtered_items), filter);
     }
 
     let sample_size = if filter.is_summary() {
@@ -662,6 +662,20 @@ mod tests {
         assert_eq!(filter.max_bytes, None);
     }
 
+    #[test]
+    fn max_bytes_only_truncates_top_level_json_array() {
+        let items: Vec<Value> = (0..50)
+            .map(|i| json!({ "id": i, "label": format!("row-{i}-padding") }))
+            .collect();
+        let filter = InvokeResultFilter {
+            max_bytes: Some(512),
+            ..Default::default()
+        };
+        let shaped = shape_json_value(Value::Array(items), &filter);
+        assert_eq!(shaped.get("truncated"), Some(&json!(true)));
+        assert!(shaped.get("total").and_then(|v| v.as_u64()).unwrap_or(0) > 512);
+    }
+
     #[test]
     fn plain_text_byte_trunc_includes_metadata() {
         let text = "x".repeat(100);
diff --git a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
index 13d28435..baffc358 100644
--- a/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
+++ b/crates/mcpmux-gateway/src/services/meta_tools/tools.rs
@@ -111,10 +111,11 @@ impl MetaTool for ListAllToolsTool {
     }
 
     fn description(&self) -> &'static str {
-        "List every tool installed in the caller's resolved Space, without \
-         the current FeatureSet filter applied. Use this to see what the \
-         workspace could expose before composing a custom FeatureSet. \
-         Returns an array of {server_id, qualified_name, description, available}."
+        "Operator/diagnostic: list every tool installed in the caller's resolved \
+         Space (ignores FeatureSet filter on the roster). Each entry includes \
+         server_available (seen on the connected server) and invokable (callable \
+         via mcpmux_invoke_tool with current grants). Agents should prefer \
+         mcpmux_search_tools for discovery — only invokable tools can be invoked."
     }
 
     fn input_schema(&self) -> Value {
@@ -130,8 +131,26 @@ impl MetaTool for ListAllToolsTool {
     }
 
     async fn call(&self, call: MetaToolCall<'_>) -> Result<CallToolResult, MetaToolError> {
+        let resolved = caller_resolution(&call).await?;
         let space_id = caller_space_id(&call).await?;
         let server_filter = call.args.get("server_id").and_then(|v| v.as_str());
+
+        let invokable = call
+            .ctx
+            .feature_service
+            .get_invokable_tools_for_grants(
+                &space_id.to_string(),
+                &resolved.feature_set_ids,
+                call.session_id,
+            )
+            .await
+            .map_err(|e| MetaToolError::Internal(e.to_string()))?;
+        let invokable_names: HashSet<String> = invokable
+            .iter()
+            .filter(|f| f.feature_type == FeatureType::Tool)
+            .map(|f| f.qualified_name())
+            .collect();
+
         let features = call
             .ctx
             .server_feature_repo
@@ -142,15 +161,26 @@ impl MetaTool for ListAllToolsTool {
             .filter(|f| f.feature_type == FeatureType::Tool)
             .filter(|f| server_filter.is_none_or(|sid| f.server_id == sid))
             .map(|f| {
+                let qualified_name = f.qualified_name();
                 json!({
                     "server_id": f.server_id,
-                    "qualified_name": f.qualified_name(),
+                    "qualified_name": qualified_name,
                     "description": f.description,
-                    "available": f.is_available,
+                    "server_available": f.is_available,
+                    "invokable": invokable_names.contains(&qualified_name),
                 })
             })
             .collect();
-        Ok(text_result(json!({ "tools": tools })))
+        let total_invokable = tools
+            .iter()
+            .filter(|t| t.get("invokable") == Some(&json!(true)))
+            .count();
+        Ok(text_result(json!({
+            "tools": tools,
+            "total_installed": tools.len(),
+            "total_invokable": total_invokable,
+            "hint": "Use mcpmux_search_tools for agent discovery. Only invokable tools can be invoked with current FeatureSet grants.",
+        })))
     }
 }
 
@@ -435,6 +465,47 @@ impl MetaTool for SearchToolsTool {
 // mcpmux_get_tool_schema — read
 // ---------------------------------------------------------------------------
 
+/// Parse the `tools` argument from `mcpmux_get_tool_schema` call args.
+///
+/// Accepts a qualified name string, a string array, or a JSON-encoded array
+/// string (common when agents double-serialize through MCP clients).
+fn parse_tool_schema_names(value: Option<&Value>) -> Result<Vec<String>, MetaToolError> {
+    let Some(value) = value else {
+        return Err(MetaToolError::InvalidArgument(
+            "missing or invalid `tools` — expected string or string array".into(),
+        ));
+    };
+
+    match value {
+        Value::String(s) => {
+            if let Ok(Value::Array(arr)) = serde_json::from_str(s) {
+                return names_from_json_array(&arr);
+            }
+            Ok(vec![s.clone()])
+        }
+        Value::Array(arr) => names_from_json_array(arr),
+        _ => Err(MetaToolError::InvalidArgument(
+            "missing or invalid `tools` — expected string or string array".into(),
+        )),
+    }
+}
+
+/// Collect non-empty qualified tool names from a JSON string array.
+fn names_from_json_array(arr: &[Value]) -> Result<Vec<String>, MetaToolError> {
+    let names: Vec<String> = arr
+        .iter()
+        .filter_map(|v| v.as_str().map(str::trim))
+        .filter(|s| !s.is_empty())
+        .map(str::to_string)
+        .collect();
+    if names.is_empty() {
+        return Err(MetaToolError::InvalidArgument(
+            "`tools` must contain at least one qualified name".into(),
+        ));
+    }
+    Ok(names)
+}
+
 pub struct GetToolSchemaTool;
 
 #[async_trait]
@@ -445,8 +516,10 @@ impl MetaTool for GetToolSchemaTool {
 
     fn description(&self) -> &'static str {
         "Load input schemas for one or more qualified tool names before \
-         invoking via mcpmux_invoke_tool. Pass tools as a string or array. \
-         Set compact: true to omit descriptions."
+         invoking via mcpmux_invoke_tool. Pass tools as a single qualified \
+         name string or a string array (e.g. [\"github_list_issues\"]). \
+         Set compact: true to omit descriptions. Tools must be invokable \
+         with current grants — use mcpmux_search_tools to discover names."
     }
 
     fn input_schema(&self) -> Value {
@@ -469,24 +542,7 @@ impl MetaTool for GetToolSchemaTool {
         let resolved = caller_resolution(&call).await?;
         let space_id = caller_space_id(&call).await?;
 
-        let tool_names: Vec<String> = match call.args.get("tools") {
-            Some(Value::String(s)) => vec![s.clone()],
-            Some(Value::Array(arr)) => arr
-                .iter()
-                .filter_map(|v| v.as_str().map(String::from))
-                .collect(),
-            _ => {
-                return Err(MetaToolError::InvalidArgument(
-                    "missing or invalid `tools` — expected string or string array".into(),
-                ));
-            }
-        };
-
-        if tool_names.is_empty() {
-            return Err(MetaToolError::InvalidArgument(
-                "`tools` must contain at least one qualified name".into(),
-            ));
-        }
+        let tool_names = parse_tool_schema_names(call.args.get("tools"))?;
 
         let compact = call
             .args
@@ -518,7 +574,32 @@ impl MetaTool for GetToolSchemaTool {
             compact,
         );
 
-        Ok(text_result(json!({ "schemas": schemas })))
+        let found_names: HashSet<String> = schemas
+            .iter()
+            .filter_map(|s| {
+                s.get("qualified_name")
+                    .and_then(|v| v.as_str())
+                    .map(str::to_string)
+            })
+            .collect();
+        let missing: Vec<&String> = tool_names
+            .iter()
+            .filter(|name| !found_names.contains(*name))
+            .collect();
+
+        if missing.is_empty() {
+            return Ok(text_result(json!({ "schemas": schemas })));
+        }
+
+        let missing_list: Vec<&str> = missing.iter().map(|s| s.as_str()).collect();
+        Ok(text_result(json!({
+            "schemas": schemas,
+            "missing": missing_list,
+            "message": format!(
+                "{} tool(s) not invokable or unknown with current grants → use mcpmux_search_tools to discover allowed names",
+                missing.len()
+            ),
+        })))
     }
 }
 
diff --git a/tests/rust/tests/integration/meta_gateway_invoke.rs b/tests/rust/tests/integration/meta_gateway_invoke.rs
index 9913b119..42db2139 100644
--- a/tests/rust/tests/integration/meta_gateway_invoke.rs
+++ b/tests/rust/tests/integration/meta_gateway_invoke.rs
@@ -645,3 +645,156 @@ async fn direct_backend_call_gate_allows_surfaced_only() {
     assert!(is_surfaced("github_list_issues"));
     assert!(!is_surfaced("github_get_me"));
 }
+
+#[tokio::test(flavor = "multi_thread")]
+async fn list_all_tools_marks_invokable_against_acl() {
+    let f = Fixture::new().await;
+
+    let list_issues = f
+        .server_feature_repo
+        .list_for_space(&f.space_id.to_string())
+        .await
+        .unwrap()
+        .into_iter()
+        .find(|feat| feat.feature_name == "list_issues")
+        .unwrap();
+
+    let mut create_issue = ServerFeature::tool(f.space_id, "github", "create_issue");
+    create_issue.description = Some("Create an issue".into());
+    f.server_feature_repo.upsert(&create_issue).await.unwrap();
+
+    let mut partial_fs = FeatureSet::new_custom("Partial GitHub", f.space_id.to_string());
+    partial_fs.members.push(FeatureSetMember {
+        id: Uuid::new_v4().to_string(),
+        feature_set_id: partial_fs.id.clone(),
+        member_type: MemberType::Feature,
+        member_id: list_issues.id.to_string(),
+        mode: MemberMode::Include,
+        surfaced: false,
+    });
+    f.feature_set_repo.create(&partial_fs).await.unwrap();
+    f.grant_feature_set(&partial_fs.id).await;
+    f.session_overrides.enable(&f.session_id, "github");
+
+    let result = f
+        .call("mcpmux_list_all_tools", json!({ "server_id": "github" }))
+        .await;
+    let body = Fixture::result_json(&result);
+    assert_eq!(body.get("total_installed").and_then(|v| v.as_u64()), Some(2));
+    assert_eq!(body.get("total_invokable").and_then(|v| v.as_u64()), Some(1));
+
+    let tools = body.get("tools").unwrap().as_array().unwrap();
+    let list_row = tools
+        .iter()
+        .find(|t| t.get("qualified_name") == Some(&json!("github_list_issues")))
+        .expect("list_issues in catalog");
+    let create_row = tools
+        .iter()
+        .find(|t| t.get("qualified_name") == Some(&json!("github_create_issue")))
+        .expect("create_issue in catalog");
+    assert_eq!(list_row.get("invokable"), Some(&json!(true)));
+    assert_eq!(create_row.get("invokable"), Some(&json!(false)));
+    assert_eq!(list_row.get("server_available"), Some(&json!(true)));
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn get_tool_schema_accepts_string_array() {
+    let f = Fixture::new().await;
+    f.grant_github_feature_set().await;
+    f.session_overrides.enable(&f.session_id, "github");
+
+    let result = f
+        .call(
+            "mcpmux_get_tool_schema",
+            json!({ "tools": ["github_list_issues"] }),
+        )
+        .await;
+    let body = Fixture::result_json(&result);
+    let schemas = body.get("schemas").unwrap().as_array().unwrap();
+    assert_eq!(schemas.len(), 1);
+    assert_eq!(
+        schemas[0].get("qualified_name"),
+        Some(&json!("github_list_issues"))
+    );
+    assert!(body.get("missing").is_none());
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn get_tool_schema_accepts_json_encoded_array_string() {
+    let f = Fixture::new().await;
+    f.grant_github_feature_set().await;
+    f.session_overrides.enable(&f.session_id, "github");
+
+    let result = f
+        .call(
+            "mcpmux_get_tool_schema",
+            json!({ "tools": "[\"github_list_issues\"]" }),
+        )
+        .await;
+    let body = Fixture::result_json(&result);
+    let schemas = body.get("schemas").unwrap().as_array().unwrap();
+    assert_eq!(schemas.len(), 1);
+    assert_eq!(
+        schemas[0].get("qualified_name"),
+        Some(&json!("github_list_issues"))
+    );
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn get_tool_schema_reports_missing_tools() {
+    let f = Fixture::new().await;
+    f.grant_github_feature_set().await;
+    f.session_overrides.enable(&f.session_id, "github");
+
+    let result = f
+        .call(
+            "mcpmux_get_tool_schema",
+            json!({ "tools": ["github_list_issues", "github_create_issue"] }),
+        )
+        .await;
+    let body = Fixture::result_json(&result);
+    let schemas = body.get("schemas").unwrap().as_array().unwrap();
+    assert_eq!(schemas.len(), 1);
+    let missing = body.get("missing").unwrap().as_array().unwrap();
+    assert_eq!(missing, &[json!("github_create_issue")]);
+    assert!(body.get("message").and_then(|m| m.as_str()).is_some());
+}
+
+#[tokio::test(flavor = "multi_thread")]
+async fn invoke_max_bytes_truncates_json_array_without_max_rows() {
+    let rows: Vec<Value> = (0..40)
+        .map(|i| json!({ "id": i, "label": format!("row-{i}-padding-value") }))
+        .collect();
+    let payload = json!({ "items": rows });
+    let backend_result = ToolCallResult {
+        content: vec![json!({
+            "type": "text",
+            "text": payload.to_string(),
+        })],
+        structured_content: None,
+        is_error: false,
+    };
+    let invoke_backend = CannedInvokeBackend::new()
+        .with_response("github_list_issues", backend_result)
+        .into_arc();
+
+    let f = Fixture::with_invoke_backend(Some(invoke_backend)).await;
+    f.grant_github_feature_set().await;
+    f.session_overrides.enable(&f.session_id, "github");
+
+    let result = f
+        .call(
+            "mcpmux_invoke_tool",
+            json!({
+                "server_id": "github",
+                "tool": "list_issues",
+                "args": { "owner": "mcpmux", "repo": "mcp-mux" },
+                "filter": { "max_bytes": 512 }
+            }),
+        )
+        .await;
+
+    assert!(!result.is_error.unwrap_or(true));
+    let body = Fixture::result_json(&result);
+    assert_eq!(body.get("truncated"), Some(&json!(true)));
+}

From b7626fb3ec41af1c03b2ab0f6bbd4e7316766721 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 15:37:24 -0600
Subject: [PATCH 46/48] docs(planning): sign off meta-gateway invoke targeted
 retest
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Record post-85113e7 QA results for §3, §6, §9, and §10 as Ship.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 docs/planning/meta-gateway-invoke-retest.md | 209 ++++++++++++++++++++
 1 file changed, 209 insertions(+)
 create mode 100644 docs/planning/meta-gateway-invoke-retest.md

diff --git a/docs/planning/meta-gateway-invoke-retest.md b/docs/planning/meta-gateway-invoke-retest.md
new file mode 100644
index 00000000..f7a21785
--- /dev/null
+++ b/docs/planning/meta-gateway-invoke-retest.md
@@ -0,0 +1,209 @@
+# Meta-Gateway Invoke — Targeted Retest (post-DX fixes)
+
+**Last Updated:** May 25, 2026  
+**Branch:** `feat/meta-gateway-invoke`  
+**Commit:** `85113e7` — `fix(gateway): improve meta-tool DX for ACL, schema batch, and max_bytes`  
+**Related:** [`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md) (full runbook), [`meta-gateway-invoke.md`](./meta-gateway-invoke.md) (spec)
+
+Paste the **Agent Prompt** block below into a fresh Cursor agent after gateway restart. Only re-runs **§3, §6, §9, §10** — core invoke QA (§0–§2, §4, §5, §7, §8, §11) already passed.
+
+---
+
+## Prep (required before any tests)
+
+1. Gateway rebuilt/restarted since `85113e7` (`pnpm dev` or restart desktop app)
+2. Cursor → MCP → **Reload tools**
+3. McpMux endpoint: `http://localhost:45818/mcp` (via `user-mcpmux` / CallMcpTool)
+4. Workspace binding active with partial GitHub ACL FeatureSet (e.g. `QA: meta-gateway invoke` — ~3 GitHub tools invokable, not full catalog)
+5. Open the **bound project folder** in Cursor
+6. GitHub OAuth connected; github `enabled_via_binding` or session-enabled
+7. GWorkspace Personal clone available for §6 (bound in FeatureSet)
+
+**FeatureSet editor reminder:**
+
+| Control | Role |
+| ------- | ---- |
+| **Checkbox** | Invoke ACL (search + `mcpmux_invoke_tool`) |
+| **Surface** button | Promote into client `tools/list` for direct one-hop calls |
+| **Server header toggle** | Bulk checkbox only — not Surface |
+
+After any Surface change: **Cursor → MCP → Reload tools**.
+
+---
+
+## Agent Prompt
+
+Copy everything inside the fence:
+
+```markdown
+# McpMux meta-gateway invoke — targeted retest (post-DX fixes)
+
+You are validating **4 sections only** after gateway commit `85113e7` on branch `feat/meta-gateway-invoke`. The core invoke model already passed full QA — do not re-run §0–§2, §4, §5, §7, §8, or §11 unless something blocks you.
+
+## Prep (required before any tests)
+
+1. Gateway rebuilt/restarted since `85113e7` (`pnpm dev` or restart desktop app)
+2. Cursor → MCP → **Reload tools**
+3. McpMux endpoint: `http://localhost:45818/mcp` (via `user-mcpmux` / CallMcpTool)
+4. Workspace binding active with partial GitHub ACL FeatureSet (e.g. `QA: meta-gateway invoke` — ~3 GitHub tools invokable, not full catalog)
+5. Open the **bound project folder** in Cursor
+6. GitHub OAuth connected; github `enabled_via_binding` or session-enabled
+7. GWorkspace Personal clone available for §6 (bound in FeatureSet)
+
+**FeatureSet editor reminder:**
+- **Checkbox** = invoke ACL (search + `mcpmux_invoke_tool`)
+- **Surface button** = promote into client `tools/list` for direct one-hop calls
+- After Surface toggle: **MCP Reload tools**
+
+---
+
+## §3 — Batch schema (was: array returned empty)
+
+Run all three calls on github (enabled):
+
+```
+1. mcpmux_get_tool_schema({ tools: ["github_list_issues"] })
+2. mcpmux_get_tool_schema({ tools: ["github_list_issues", "github_create_issue"] })
+   — create_issue should NOT be in your ACL
+3. mcpmux_get_tool_schema({ tools: "github_list_issues" })  — string form sanity check
+```
+
+**Pass criteria:**
+- (1) `schemas.length === 1`, qualified_name = `github_list_issues`
+- (2) `schemas.length === 1` AND `missing` includes `github_create_issue` AND `message` explains use search
+- (3) string form still works
+- **Fail if:** array form returns `schemas: []` with no `missing` explanation
+
+---
+
+## §6 — Filter max_bytes on plain text (was: partial — payload too small)
+
+Use GWorkspace Personal (`taylorwilsdon.google-workspace-mcp-uvx` or your bound clone):
+
+```
+1. mcpmux_search_tools query "list drive" or "list_drive_items" with server_id set
+2. mcpmux_get_tool_schema for the list tool
+3. mcpmux_invoke_tool with args that return a LARGE list:
+     { page_size: 100 }  (or equivalent from schema — do NOT use page_size: 10)
+4. mcpmux_invoke_tool same call with filter: { "max_bytes": 4096 }
+```
+
+**Pass criteria:**
+- Step 3: full backend response, **no** `{ returned, total, truncated }` envelope
+- Step 4: truncation envelope present — at minimum `{ truncated: true, total, returned, text }` (or byte metadata)
+- **Fail if:** step 4 returns full multi-KB payload with no truncation metadata when clearly >4096 bytes
+
+Also sanity-check JSON filter still works (github):
+
+```
+mcpmux_invoke_tool github list_issues with filter: { "max_rows": 3, "fields": ["title","number"] }
+```
+
+**Pass if:** `{ returned: 3, total: N, truncated: true, issues: [...] }`
+
+---
+
+## §9 — Surfaced promotion (was: SKIP — no surfaced tool configured)
+
+**Setup first (human/UI step — confirm before testing):**
+- In FeatureSet editor: leave `list_issues` **checked**, click **Surface** on that row only
+- Other included tools checked but Surface **off**
+- Save → Cursor → MCP → **Reload tools**
+
+Then run:
+
+```
+1. List every tool you can call — separate mcpmux_* meta tools vs surfaced backend tools
+2. Call github_list_issues DIRECTLY (one hop, no mcpmux_invoke_tool wrapper)
+3. Call github_get_me (or another included but non-surfaced tool) via mcpmux_invoke_tool
+4. Try direct call on a non-surfaced backend tool — expect use_invoke_tool redirect
+```
+
+**Pass criteria:**
+- Exactly ~10 `mcpmux_*` + **1** surfaced backend (`github_list_issues`) in tool surface
+- Direct `github_list_issues` succeeds (no redirect error)
+- Non-surfaced tool absent from direct list but invoke succeeds
+- Direct call on non-surfaced tool → redirect to `mcpmux_invoke_tool`
+- **Fail if:** backend tools leak into list without Surface, or surfaced tool gets redirect
+
+---
+
+## §10 — Diagnostic list_all_tools vs search (was: FAIL — 41 available vs 3 invokable)
+
+```
+1. mcpmux_list_all_tools({ server_id: "github" })
+2. mcpmux_search_tools({ query: "", server_id: "github", detail_level: "name" })
+3. Compare counts and explain which tool agents should use for discovery
+```
+
+**Pass criteria:**
+- `list_all_tools` response includes:
+  - `total_installed` (full github catalog, e.g. ~41)
+  - `total_invokable` (matches ACL, e.g. ~3)
+  - per-row `invokable: true/false` and `server_available` (NOT bare `available: true` for all)
+  - `hint` steering to `mcpmux_search_tools`
+- `search_tools` total === `total_invokable` (not `total_installed`)
+- Agent explicitly recommends **search** for invoke workflows, **list_all_tools** only for operator/diagnostic/FeatureSet authoring
+- **Fail if:** all 41 tools still marked invokable/available with no ACL distinction
+
+---
+
+## FINAL REPORT (required — paste entire block back)
+
+```
+## Retest Summary
+Overall: SHIP | SHIP WITH ISSUES | BLOCK
+Commit tested: 85113e7 (or actual if different)
+Sections run: §3 §6 §9 §10
+
+| Section | Result | Notes |
+|---------|--------|-------|
+| §3 Batch schema | PASS/FAIL | |
+| §6 max_bytes filter | PASS/FAIL/PARTIAL | |
+| §9 Surfaced | PASS/FAIL/SKIP | |
+| §10 Diagnostic | PASS/FAIL | |
+
+## Red flags (check any observed)
+[ ] Array schema still returns empty schemas: []
+[ ] list_all_tools still marks non-ACL tools invokable
+[ ] max_bytes on large plain-text payload no truncation metadata
+[ ] Surfaced tool gets use_invoke_tool redirect
+[ ] Backend tools in tools/list without Surface
+
+## Friction log (verbatim errors / surprises)
+
+## Environment
+- github status:
+- FeatureSet ACL tool count (from search):
+- Surfaced tools in direct list:
+- total_installed / total_invokable from list_all_tools:
+```
+
+Rules: use **McpMux meta tools only** for backend calls unless §9 explicitly tests direct surfaced one-hop. Read schemas before invoke. Show exact JSON snippets for pass/fail evidence on §3, §6 step 4, and §10 counts.
+```
+
+---
+
+## What changed in `85113e7`
+
+| Fix | Expected retest impact |
+| --- | ---------------------- |
+| `list_all_tools` adds `invokable`, `server_available`, counts, hint | §10 should PASS |
+| `get_tool_schema` array + JSON-encoded array + `missing` field | §3 should PASS |
+| `max_bytes` applies to JSON arrays without `max_rows` | §6 step 4 should PASS with large payload |
+
+---
+
+## Sign-off (fill after agent report)
+
+| Section | Result | Notes |
+| ------- | ------ | ----- |
+| §3 Batch schema | ☑ Pass ☐ Fail | Array + string forms; `missing`/`message` on `github_create_issue` |
+| §6 max_bytes filter | ☑ Pass ☐ Fail ☐ Partial | Large github JSON truncates with `{ truncated, total, returned, text }`; JSON filter sanity pass |
+| §9 Surfaced | ☑ Pass ☐ Fail ☐ Skipped | 10 `mcpmux_*` + 1 `github_list_issues`; direct one-hop OK; non-surfaced absent from list |
+| §10 Diagnostic | ☑ Pass ☐ Fail | `total_installed: 41`, `total_invokable: 3`; per-row `invokable`/`server_available`; `hint` present |
+| **Overall** | ☑ Ship ☐ Block | Commit `85113e7` on `feat/meta-gateway-invoke` |
+
+**Tester / date:** Cursor agent / May 25, 2026
+
+**Blockers:** None. §6 used github large payload (GWorkspace not in QA FeatureSet). Dev restart + backend pool spin-up caused transient CONNECTING state before retest completed.

From b9d237020194a9551f95c53e89b95a250d84b368 Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Mon, 25 May 2026 16:02:17 -0600
Subject: [PATCH 47/48] docs(planning): fork integration guide and session
 readiness plans

Document crimsonsunset fork canonical branch (feat/meta-gateway-invoke),
upstream PR policy (#152/#154 keep, #155 megapr closed), and umbrella
warm-pool/session-readiness planning.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 docs/planning/agent-mcp-session-readiness.md | 301 +++++++++++++++++++
 docs/planning/fork-integration.md            |  92 ++++++
 docs/planning/gateway-warm-pool-startup.md   | 264 ++++++++++++++++
 docs/planning/meta-gateway-invoke.md         |   6 +-
 4 files changed, 660 insertions(+), 3 deletions(-)
 create mode 100644 docs/planning/agent-mcp-session-readiness.md
 create mode 100644 docs/planning/fork-integration.md
 create mode 100644 docs/planning/gateway-warm-pool-startup.md

diff --git a/docs/planning/agent-mcp-session-readiness.md b/docs/planning/agent-mcp-session-readiness.md
new file mode 100644
index 00000000..3b6fbb19
--- /dev/null
+++ b/docs/planning/agent-mcp-session-readiness.md
@@ -0,0 +1,301 @@
+# Agent MCP Session Readiness
+
+**Last Updated:** May 25, 2026  
+**Status:** Planned — umbrella initiative; child doc [`gateway-warm-pool-startup.md`](./gateway-warm-pool-startup.md) has Phase 1 decisions locked  
+**Branch:** TBD (multiple tracks; see phasing)  
+**Base branch:** `main`  
+**Issue:** TBD  
+**Depends on:** [`meta-gateway-invoke.md`](./meta-gateway-invoke.md) (meta-tool entrypoint — must be reliable at session start)  
+**Unblocks:** Using McpMux as primary agent MCP endpoint without multi-minute warm-up, empty ACL false alarms, or manual Surface reload guesswork
+
+---
+
+## Problem
+
+Live QA on meta-gateway invoke (May 2026) exposed four friction points for **agent-first** McpMux use. Each has a different **control boundary** — some are fully fixable in-repo, some need client cooperation, one is intentional product design.
+
+| # | Pain | Symptom | Control |
+| - | ---- | ------- | ------- |
+| 1 | **Cold start** | Dozens of backends `CONNECTING`; github unavailable for minutes after dev restart | **High** — gateway startup |
+| 2 | **Binding / roots timing** | `total_invokable: 0` until workspace roots land; fragile across restart + Cursor reload | **Medium-high** — gateway + client timing |
+| 3 | **Surface → reload** | Surfaced tools don't appear until Cursor → MCP → Reload tools | **Medium** — we emit `list_changed`; Cursor may ignore |
+| 4 | **FeatureSet authoring** | QA FS missing GWorkspace; ACL curation is human/agent write work | **Medium** — reduce friction; cannot auto-grant all |
+
+This doc is the **umbrella plan**: what to fix, what to accept, and **exactly where to dig** in the codebase for each controllable part. Implementation detail for cold start lives in [`gateway-warm-pool-startup.md`](./gateway-warm-pool-startup.md).
+
+---
+
+## Decisions (umbrella)
+
+| # | Decision | Choice | Rationale |
+| - | -------- | ------ | --------- |
+| 1 | Initiative structure | **Four tracks**, one umbrella doc; cold start is first ship | Tracks have different owners/risk; don't block warm pool on Cursor |
+| 2 | Cold start | **Tiered hot/warm + parallel×6** — see child doc | Binding-union hot set; no defer of unbound enabled |
+| 3 | Roots timing | **Runtime warm + meta `gateway_warming` signal** | Can't force Cursor to send roots earlier; can probe/warm/react |
+| 4 | Surface reload | **Audit event path first**; doc + Cursor issue if `list_changed` already fires | Don't build workarounds until we confirm gateway gap vs client gap |
+| 5 | FS authoring | **Improve agent + operator DX** — not auto-infer ACL from repo | Security model requires explicit grants |
+| 6 | Lazy invoke connect | **Out of scope** | Pool-based routing requires connected instance ([`ARCHITECTURE.md`](../../crates/mcpmux-gateway/ARCHITECTURE.md)) |
+
+---
+
+## Control matrix
+
+```text
+                    McpMux fixes?    Client/user?        Track
+Cold start              ████████░░        ██ (enable count)   A — warm pool
+Roots timing            ███████░░░        ███ (roots timing)  A + B
+Surface reload          █████░░░░░        █████ (Cursor UX)   C
+FS authoring            ██████░░░░        ████ (ACL by design) D
+```
+
+---
+
+## Track A — Cold start (warm pool)
+
+**Control: ~80%** · **Child doc:** [`gateway-warm-pool-startup.md`](./gateway-warm-pool-startup.md)
+
+### Symptom
+
+Gateway HTTP is up immediately; backend pool takes minutes when many servers are DB-`enabled`. UI shows fleet-wide `CONNECTING`. Agents see `server_available: false` on all tools until sequential connect + feature discovery completes.
+
+### Root cause (confirmed)
+
+| Behavior | Where to dig |
+| -------- | ------------ |
+| Background auto-connect after HTTP bind | [`crates/mcpmux-gateway/src/server/mod.rs`](../../crates/mcpmux-gateway/src/server/mod.rs) — `run_with_shutdown()` ~L445–492 |
+| Mark all features unavailable pre-connect | [`crates/mcpmux-gateway/src/server/startup.rs`](../../crates/mcpmux-gateway/src/server/startup.rs) — `mark_all_features_unavailable()` |
+| **All** DB-enabled servers, **sequential** connect | [`crates/mcpmux-gateway/src/server/startup.rs`](../../crates/mcpmux-gateway/src/server/startup.rs) — `auto_connect_enabled_servers()` ~L128–204 |
+| Batch pre-set CONNECTING for entire fleet | Same file ~L147–159 |
+| Binding does **not** filter startup connect | Compare with [`crates/mcpmux-gateway/src/services/feature_set_resolver.rs`](../../crates/mcpmux-gateway/src/services/feature_set_resolver.rs) (routing only) |
+| Eager pool rationale | [`crates/mcpmux-gateway/ARCHITECTURE.md`](../../crates/mcpmux-gateway/ARCHITECTURE.md) — Pool-Based Connection Management |
+| Dead parallel scaffold (never called) | [`crates/mcpmux-gateway/src/pool/server_manager.rs`](../../crates/mcpmux-gateway/src/pool/server_manager.rs) — `startup_refresh()` |
+| Duplicate manual connect path | [`apps/desktop/src-tauri/src/commands/gateway.rs`](../../apps/desktop/src-tauri/src/commands/gateway.rs) — `connect_all_enabled_servers` |
+| Stale auto-start comment | [`apps/desktop/src-tauri/src/lib.rs`](../../apps/desktop/src-tauri/src/lib.rs) ~L510 (claims frontend auto-connect — wrong) |
+| Tauri auto-start entry | [`apps/desktop/src-tauri/src/lib.rs`](../../apps/desktop/src-tauri/src/lib.rs) — setup spawn ~L357 |
+| UI CONNECTING state | [`apps/desktop/src/hooks/useServerManager.ts`](../../apps/desktop/src/hooks/useServerManager.ts), [`apps/desktop/src/features/servers/ServersPage.tsx`](../../apps/desktop/src/features/servers/ServersPage.tsx) |
+
+### Fix (locked)
+
+Implement [`gateway-warm-pool-startup.md`](./gateway-warm-pool-startup.md) Phases 1–3: `ConnectPlanBuilder` (binding-union hot set), parallel connect (semaphore 6), hot-then-warm tiers, narrow CONNECTING pre-set.
+
+### Outcome when done
+
+Dev restart with QA binding: github `server_available: true` within ~15s even with 8+ other enabled servers. Fleet UI no longer flashes 30× CONNECTING simultaneously.
+
+---
+
+## Track B — Binding / roots timing
+
+**Control: ~70%** · **Overlaps Track A Phase 2**
+
+### Symptom
+
+Agent MCP session calls meta tools before roots arrive → resolver returns `Deny` / empty FS → `total_invokable: 0`. After roots land, binding resolves but backends may still be cold (Track A).
+
+### Root cause (confirmed)
+
+| Behavior | Where to dig |
+| -------- | ------------ |
+| Four-tier resolver (binding / pending roots / grant / deny) | [`crates/mcpmux-gateway/src/services/feature_set_resolver.rs`](../../crates/mcpmux-gateway/src/services/feature_set_resolver.rs) — full file; read module doc ~L1–26 |
+| Tier 1c: roots-capable, roots pending → empty FS | Same file ~L186–199 |
+| Tier 1b: roots but no binding → deny | Same file ~L176–183 |
+| Session roots storage | [`crates/mcpmux-gateway/src/services/session_roots.rs`](../../crates/mcpmux-gateway/src/services/session_roots.rs) — `set_roots_capable`, `get`, probe throttle |
+| On-demand roots probe before list/call | [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) — search `on-demand probe` ~L193–315, ~L660 |
+| `list_tools` vs `call_tool` roots probe parity | Same file — ensure meta-tool path uses same probe as `list_tools` |
+| Integration tests for PendingRoots | [`tests/rust/tests/integration/feature_set_resolver.rs`](../../tests/rust/tests/integration/feature_set_resolver.rs) |
+| Meta tools resolve via `caller_resolution()` | [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) — `caller_resolution()` |
+| Workspace binding entity | [`crates/mcpmux-core/src/domain/workspace_binding.rs`](../../crates/mcpmux-core/src/domain/workspace_binding.rs) |
+| Binding repo longest-prefix match | [`crates/mcpmux-core/src/repository/mod.rs`](../../crates/mcpmux-core/src/repository/mod.rs) — `find_longest_prefix_match` |
+
+### Fix
+
+1. **Track A Phase 2:** `WarmPoolService` on roots stored + `WorkspaceBindingChanged` ([`crates/mcpmux-gateway/src/consumers/mcp_notifier.rs`](../../crates/mcpmux-gateway/src/consumers/mcp_notifier.rs) ~L454 — today only `notify_all_list_changed`, no connect)
+2. **`gateway_warming` in meta tools** — [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) `list_servers` (see child doc)
+3. **Audit:** Confirm every meta-tool `call()` path runs roots probe when `PendingRoots` (handler may already; verify for CallMcpTool session id)
+
+### Not fixable in McpMux alone
+
+- Cursor opening MCP connection before reporting `roots` — we can probe/retry, not force
+- User opening wrong folder (no binding match) — `WorkspaceNeedsBinding` UX, not gateway bug
+
+### Outcome when done
+
+After dev restart + Cursor reload: first `mcpmux_search_tools` either returns tools or explicit `{ gateway_warming: true }` with retry hint — not silent empty ACL.
+
+---
+
+## Track C — Surface changes need MCP reload
+
+**Control: ~50%** · **Audit-first track**
+
+### Symptom
+
+User toggles **Surface** on a FeatureSet member, saves, but Cursor agent still sees only 10 `mcpmux_*` tools until manual **Reload tools**. Direct `github_list_issues` may work via gateway while Cursor descriptor cache is stale.
+
+### What we already do (dig here first)
+
+| Step | Where to dig |
+| ---- | ------------ |
+| Surface toggle UI | [`apps/desktop/src/features/featuresets/FeatureSetPanel.tsx`](../../apps/desktop/src/features/featuresets/FeatureSetPanel.tsx) — `toggleSurfaced`, `handleSave` → `setFeatureSetMembers` with `surfaced:` |
+| Bulk member save + `surfaced` column | [`apps/desktop/src-tauri/src/commands/feature_set.rs`](../../apps/desktop/src-tauri/src/commands/feature_set.rs) — `set_feature_set_members` ~L448–525 |
+| DB migration for `surfaced` | [`crates/mcpmux-storage/src/migrations/019_feature_set_member_surfaced.sql`](../../crates/mcpmux-storage/src/migrations/019_feature_set_member_surfaced.sql) |
+| Event after save | `grant_service.notify_feature_set_modified()` in `set_feature_set_members` ~L516–522 |
+| Grant service → domain event | [`crates/mcpmux-gateway/src/services/grant_service.rs`](../../crates/mcpmux-gateway/src/services/grant_service.rs) — `notify_feature_set_modified` |
+| MCPNotifier → `tools/list_changed` | [`crates/mcpmux-gateway/src/consumers/mcp_notifier.rs`](../../crates/mcpmux-gateway/src/consumers/mcp_notifier.rs) — `FeatureSetMembersChanged` ~L419–429, `force=true` |
+| Advertised vs invokable split | [`crates/mcpmux-gateway/src/pool/features/facade.rs`](../../crates/mcpmux-gateway/src/pool/features/facade.rs) — `get_advertised_tools_for_grants` |
+| Surfaced resolution | [`crates/mcpmux-gateway/src/pool/features/resolution.rs`](../../crates/mcpmux-gateway/src/pool/features/resolution.rs) — `resolve_surfaced_feature_ids` |
+| Direct call gate + redirect | [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) — `call_tool` surfaced check |
+| Meta-tool create FS with surfaced | [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) — `CreateFeatureSetTool` |
+| QA runbook reminder | [`docs/planning/meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md), [`meta-gateway-invoke-retest.md`](./meta-gateway-invoke-retest.md) §9 |
+
+### Investigation tasks (Phase C1)
+
+- [ ] Save Surface in UI → confirm `FeatureSetMembersChanged` in gateway logs
+- [ ] Confirm MCPNotifier sends `notifications/tools/list_changed` to Cursor session (wire log or integration test with mock peer)
+- [ ] If event fires but Cursor ignores: **client limitation** — file Cursor issue; keep runbook "Reload tools after Surface"
+- [ ] If event does **not** fire: fix grant_service / gateway-not-running path in `set_feature_set_members`
+
+### Possible McpMux improvements (Phase C2 — only if audit finds gaps)
+
+- [ ] Per-session `notify_peer_lists_changed` for roots-capable peers on Surface change (today space-wide broadcast — see `ClientGrantChanged` pattern ~L432–446 for narrower fanout)
+- [ ] Desktop toast after save: "Reload MCP tools in your client to pick up surfaced tools"
+- [ ] Meta tool `mcpmux_list_servers` includes `surfaced_tools: ["github_list_issues"]` so agents know what *should* be direct-callable
+
+### Not fixable without client change
+
+Cursor (and some MCP clients) not applying `tools/list_changed` to local tool descriptor cache — manual reload remains fallback.
+
+### Outcome when done
+
+Documented truth table: "gateway emits X → Cursor does Y." Either a confirmed gateway bug fixed, or explicit "reload required" UX with no false "broken gateway" impression.
+
+---
+
+## Track D — FeatureSet authoring friction
+
+**Control: ~60% (reduce friction; ACL stays explicit)**
+
+### Symptom
+
+Agent QA needed GWorkspace in FeatureSet but QA FS only had 3 github tools. Operator must know Workspaces UI, checkbox vs Surface, binding vs session enable.
+
+### Intentional constraint
+
+FeatureSets define **invoke ACL** ([`meta-gateway-invoke.md`](./meta-gateway-invoke.md) decision #5). Auto-granting all installed tools defeats the model.
+
+### Where to dig
+
+| Capability | Where to dig |
+| ---------- | ------------ |
+| FeatureSet editor (checkbox vs Surface) | [`apps/desktop/src/features/featuresets/FeatureSetPanel.tsx`](../../apps/desktop/src/features/featuresets/FeatureSetPanel.tsx) |
+| Workspace binding UI | [`apps/desktop/src/features/workspaces/WorkspacesPage.tsx`](../../apps/desktop/src/features/workspaces/WorkspacesPage.tsx), [`WorkspaceBindingSheet.tsx`](../../apps/desktop/src/features/workspaces/WorkspaceBindingSheet.tsx) |
+| Effective features inspector | Workspaces page — "Effective Features" panel (binding resolve preview) |
+| Meta: list FS | [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) — `ListFeatureSetsTool` |
+| Meta: create FS | Same — `CreateFeatureSetTool` (~L897+) with `tool_qualified_names`, `surfaced_tools` |
+| Meta: bind workspace | Same — `BindCurrentWorkspaceTool` (triggers approval — avoid in routine QA) |
+| Meta: diagnostic full catalog | Same — `ListAllToolsTool` with `invokable` / `total_invokable` (post-85113e7) |
+| Meta: discovery for agents | Same — `SearchToolsTool` |
+| Operator vs agent steering | `list_all_tools` `hint` field in same file |
+| FS member storage | [`crates/mcpmux-core/src/domain/feature_set.rs`](../../crates/mcpmux-core/src/domain/feature_set.rs) |
+| Bundles (starter FS) | FeatureSet bundles in DB; [`docs/planning/meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md) prep |
+
+### Fix options (Phase D — pick 1–2 for v1)
+
+| Option | Effort | Dig/start |
+| ------ | ------ | --------- |
+| **D1: FS authoring helper meta tool** — `mcpmux_suggest_feature_set_from_servers({ server_ids, surfaced? })` returns member list from `list_all_tools` | ~1 day | Extend [`tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) registry in [`mod.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/mod.rs) |
+| **D2: Better empty-search errors** — "server X not in binding FS; add via Workspaces or mcpmux_create_feature_set" | ~0.5 day | [`invoke.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/invoke.rs), [`tool_discovery`](../../crates/mcpmux-gateway/src/services/tool_discovery/) |
+| **D3: UI — clone FS / add server bundle to binding** | ~1–2 days | Workspaces + FeatureSet panels |
+| **D4: QA template FS checked into docs** | ~0.5 day | Extend [`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md) with canonical FS export |
+
+### Out of scope
+
+- Auto-infer FeatureSet from open repo / installed servers without explicit write
+- Removing human approval for `bind_current_workspace` (space-wide effect)
+
+### Outcome when done
+
+Agent or operator can go from "I need github + gworkspace for this repo" to a bound FS in ≤3 meta calls or one UI flow, without hand-editing JSON.
+
+---
+
+## Umbrella phasing
+
+Recommended ship order — each track is independently testable.
+
+### Phase 1 — Warm pool (Track A)
+
+**Effort:** ~2–3 days · **Doc:** [`gateway-warm-pool-startup.md`](./gateway-warm-pool-startup.md) Phases 1–3
+
+Fixes pain **#1** and most of **#2** (backend availability).
+
+### Phase 2 — Roots + warming signal (Track B)
+
+**Effort:** ~1 day · **Doc:** child doc Phase 2 (may merge with Phase 1 if same PR)
+
+Fixes remaining **#2** agent confusion (`gateway_warming`).
+
+### Phase 3 — Surface list_changed audit (Track C)
+
+**Effort:** ~0.5–1 day investigate; ~1 day fix if gateway gap
+
+Fixes or documents **#3** with evidence.
+
+### Phase 4 — FS authoring DX (Track D)
+
+**Effort:** ~1–2 days for D1+D2
+
+Reduces **#4**; does not eliminate ACL curation.
+
+---
+
+## Pre-PR validation (umbrella)
+
+| Track | How to verify |
+| ----- | ------------- |
+| A | Dev restart → github invokable < 15s; logs show hot tier first |
+| B | Reload Cursor → first search returns tools or `gateway_warming: true` |
+| C | Toggle Surface → log `FeatureSetMembersChanged` + optional wire capture; document Cursor behavior |
+| D | Agent creates FS from `list_all_tools` names → search finds new tools after bind |
+
+---
+
+## Out of scope (umbrella)
+
+| Item | Reason |
+| ---- | ------ |
+| Faster uvx/npm installs | Environment / cache, not gateway |
+| Cursor `list_changed` implementation | External client |
+| Full auto-ACL from repo analysis | Conflicts with invoke security model |
+| Disable eager pool / lazy connect on invoke | ARCHITECTURE rejection; large routing change |
+
+---
+
+## Key files referenced
+
+| File | Track |
+| ---- | ----- |
+| [`crates/mcpmux-gateway/src/server/startup.rs`](../../crates/mcpmux-gateway/src/server/startup.rs) | A |
+| [`crates/mcpmux-gateway/src/services/feature_set_resolver.rs`](../../crates/mcpmux-gateway/src/services/feature_set_resolver.rs) | B |
+| [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) | B, C |
+| [`crates/mcpmux-gateway/src/consumers/mcp_notifier.rs`](../../crates/mcpmux-gateway/src/consumers/mcp_notifier.rs) | B, C |
+| [`apps/desktop/src-tauri/src/commands/feature_set.rs`](../../apps/desktop/src-tauri/src/commands/feature_set.rs) | C |
+| [`apps/desktop/src/features/featuresets/FeatureSetPanel.tsx`](../../apps/desktop/src/features/featuresets/FeatureSetPanel.tsx) | C, D |
+| [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | B, D |
+
+---
+
+## Related documentation
+
+- [`docs/planning/gateway-warm-pool-startup.md`](./gateway-warm-pool-startup.md) — Track A/B implementation detail (decisions locked)
+- [`docs/planning/meta-gateway-invoke.md`](./meta-gateway-invoke.md) — meta-tool entrypoint model
+- [`docs/planning/meta-gateway-invoke-retest.md`](./meta-gateway-invoke-retest.md) — live QA evidence
+- [`crates/mcpmux-gateway/ARCHITECTURE.md`](../../crates/mcpmux-gateway/ARCHITECTURE.md) — eager pool rationale
+
+---
+
+## Reconciliation
+
+Update **Status** and track checkboxes as phases ship. When Track A completes, mark [`gateway-warm-pool-startup.md`](./gateway-warm-pool-startup.md) **Status: Complete** and link back here. Run planning-doc reconciliation before closing the umbrella initiative.
+
+**Decision record (May 25, 2026):** Four-track umbrella for agent session readiness; cold start first via warm pool; Surface audit before building client workarounds; FS authoring improved via meta-tool DX not auto-ACL.
diff --git a/docs/planning/fork-integration.md b/docs/planning/fork-integration.md
new file mode 100644
index 00000000..be9d0c17
--- /dev/null
+++ b/docs/planning/fork-integration.md
@@ -0,0 +1,92 @@
+# Personal fork integration (crimsonsunset)
+
+**Last updated:** May 25, 2026  
+**Purpose:** Single source of truth for local/homelab work on [crimsonsunset/mcp-mux](https://github.com/crimsonsunset/mcp-mux). Upstream PR stacking is separate and optional.
+
+---
+
+## Canonical branch
+
+| Branch | Role |
+|--------|------|
+| **`feat/meta-gateway-invoke`** | **Integration tip** — run `pnpm dev`, gateway QA, and all new work here |
+| `feat/dynamic-mcp-toggle-meta-tools` | Pointer kept in sync with tip (session meta-tools, bindings base) |
+| `feat/server-account-clones` | Pointer kept in sync with tip (account clones + meta-gateway invoke) |
+| `main` | Tracks upstream `mcpmux/mcp-mux` — **not** where fork features live |
+
+**Rule:** If it is not on `feat/meta-gateway-invoke`, you are not running your fork.
+
+### What is on the integration tip
+
+Linear stack (newest at top):
+
+1. Meta-gateway invoke (search → schema → invoke, surfaced tools, opt-in invoke filters)
+2. Server account clones
+3. Dynamic MCP toggle meta-tools + workspace/session routing (fork lineage ahead of upstream `main`)
+4. Planning docs and homelab QA sign-offs
+
+See [`meta-gateway-invoke.md`](./meta-gateway-invoke.md), [`agent-mcp-session-readiness.md`](./agent-mcp-session-readiness.md), [`gateway-warm-pool-startup.md`](./gateway-warm-pool-startup.md).
+
+---
+
+## Daily workflow
+
+```bash
+git checkout feat/meta-gateway-invoke
+git pull origin feat/meta-gateway-invoke   # after pushes from other machines
+pnpm dev                                   # gateway on localhost:45818
+```
+
+New feature work:
+
+```bash
+git checkout feat/meta-gateway-invoke
+git pull origin feat/meta-gateway-invoke
+git checkout -b feat/my-topic
+# ... commits ...
+git checkout feat/meta-gateway-invoke
+git merge feat/my-topic                    # or rebase topic onto tip first
+git push origin feat/meta-gateway-invoke
+```
+
+Homelab Cursor config: one `mcpmux` entry → `http://localhost:45818/mcp`. Migration tracker: [mcpmux-server-migration.md](../../../jsg-tech-check/docs/setup/mcpmux-server-migration.md).
+
+---
+
+## Upstream PR policy (mcpmux/mcp-mux)
+
+| PR | Action | Why |
+|----|--------|-----|
+| [#152](https://github.com/mcpmux/mcp-mux/pull/152) `fix/dcr-skip-invalid-redirect-uris` | **Keep open** | Small, standalone OAuth fix (~47 lines) → `main` |
+| [#154](https://github.com/mcpmux/mcp-mux/pull/154) `feat/dynamic-mcp-toggle-meta-tools` | **Keep open (draft)** | Proper stack: base `feat/workspace-root-routing`, not a megapr |
+| [#155](https://github.com/mcpmux/mcp-mux/pull/155) `feat/meta-gateway-invoke` | **Closed** | Wrong base (`main`); entire fork stack (~28k LOC). Work lives on fork integration branch only |
+
+**Not owned by this fork:** [#151](https://github.com/mcpmux/mcp-mux/pull/151) workspace-root-routing (upstream). #154 targets that branch when contributing meta-tools upstream.
+
+Future upstream contributions: branch off fresh `upstream/main` (or merged #151), cherry-pick or restack **one topic per PR** — do not reopen a megapr to `main`.
+
+---
+
+## Branch pointer sync
+
+After the integration tip moves, fast-forward stale names (optional hygiene):
+
+```bash
+git checkout feat/dynamic-mcp-toggle-meta-tools && git merge --ff-only feat/meta-gateway-invoke
+git checkout feat/server-account-clones && git merge --ff-only feat/meta-gateway-invoke
+git push origin feat/meta-gateway-invoke feat/dynamic-mcp-toggle-meta-tools feat/server-account-clones
+```
+
+---
+
+## Next implementation priorities (on integration branch)
+
+1. [`gateway-warm-pool-startup.md`](./gateway-warm-pool-startup.md) — cold start / `gateway_warming`
+2. Homelab `mcp.json` cutover (bindings + `bundle:core`)
+3. Replace stock `McpMux.app` with a build from this branch ([`run-from-source-macos.md`](../run-from-source-macos.md))
+
+---
+
+## Reconciliation
+
+When the integration tip gains a major milestone, update this file's **Last updated** and the **What is on the integration tip** list. Close new upstream megaprs to `main`; keep topic PRs stacked on the appropriate upstream feature branch.
diff --git a/docs/planning/gateway-warm-pool-startup.md b/docs/planning/gateway-warm-pool-startup.md
new file mode 100644
index 00000000..ff209aee
--- /dev/null
+++ b/docs/planning/gateway-warm-pool-startup.md
@@ -0,0 +1,264 @@
+# Gateway Warm Pool Startup
+
+**Last Updated:** May 25, 2026  
+**Status:** Planned — decisions locked, not started  
+**Branch:** TBD (suggest `feat/gateway-warm-pool` off `main`)  
+**Base branch:** `main`  
+**Issue:** TBD — file after planning review  
+**Depends on:** [`meta-gateway-invoke.md`](./meta-gateway-invoke.md) (agent meta-tool entrypoint — warm pool makes invoke/search reliable at session start)  
+**Parent initiative:** [`agent-mcp-session-readiness.md`](./agent-mcp-session-readiness.md) (umbrella — all four agent entrypoint pain points)  
+**Unblocks:** Agent-first McpMux sessions without multi-minute CONNECTING stalls; post-restart binding/roots race where `total_invokable: 0` until backends connect
+
+---
+
+## Problem
+
+Gateway auto-start is fast for HTTP (`Ready to accept connections` immediately), but **backend MCP pool warm-up is slow and binding-blind**. Agents hit empty search/invoke results while servers spin up.
+
+Observed in May 2026 live QA (meta-gateway invoke retest):
+
+| Symptom | Cause |
+| ------- | ----- |
+| All enabled servers show **CONNECTING** at once | Batch `set_connecting` pre-loop in `StartupOrchestrator` |
+| github unavailable for minutes after dev restart | Sequential connect through full enabled fleet |
+| `total_invokable: 0`, `server_available: false` on all tools | `mark_all_features_unavailable` until each server completes handshake + discovery |
+| Binding-resolved FS ready before github connects | Startup connects **all** DB-`enabled` servers, not binding-priority |
+| Agent session roots arrive after first meta-tool calls | No runtime warm on roots/binding change |
+
+Current startup path (`GatewayServer::run_with_shutdown` → `StartupOrchestrator::auto_connect_enabled_servers`):
+
+1. Mark all features unavailable  
+2. Resolve prefixes (all spaces)  
+3. **Sequential** connect every `InstalledServer` where `enabled == true` (all spaces)  
+4. Pre-set **all** enabled servers to CONNECTING before any handshake completes  
+
+`ARCHITECTURE.md` documents pool-based **eager** connect (intentional — routing requires a pool instance). It also claims **parallel** startup connects; implementation is **sequential**. Bindings / FeatureSets affect routing only — not startup selection.
+
+---
+
+## Decisions
+
+| # | Decision | Choice | Rationale |
+| - | -------- | ------ | --------- |
+| 1 | Startup connect scope | **Tiered** — binding-referenced servers first (parallel), then remaining DB-enabled in background | Agent-visible servers ready quickly without abandoning eager pool model for power users |
+| 2 | Hot-set derivation | **Union of server_ids from ALL workspace bindings** (any space) | Matches multi-workspace installs; any bound folder's servers get priority |
+| 3 | Unbound enabled servers | **No deferral** — still connect at boot (background tier after hot) | Preserves current "I enabled it, it should connect" desktop expectation |
+| 4 | Parallelism | **Single semaphore, 6 concurrent** (stdio + HTTP mixed) | Balance wall-clock vs CPU/IO spike on homelab installs |
+| 5 | Runtime warm | **On `WorkspaceBindingChanged` + when MCP session roots first arrive** | Fixes post-restart agent race and binding edits without full gateway restart |
+| 6 | Agent warming signal | **Meta tools** — expose pool warming state (not desktop-only) | Agents can distinguish ACL deny vs still-warming; retry search instead of misdiagnosing |
+| 7 | v1 delivery | **Full scope** — tiered + parallel + runtime warm + meta signal + CONNECTING UX + unify connect paths + setting hook | Single initiative, phased for review |
+| 8 | Lazy invoke-time connect | **Out of scope for v1** | ARCHITECTURE rejects lazy loading; routing requires pool instance today |
+| 9 | Connect path unification | **Single orchestrator** — manual `connect_all_enabled_servers` delegates to `StartupOrchestrator` | Fixes duplicate logic + ServerManager status gap on manual start |
+
+---
+
+## The Model
+
+### Tiered startup
+
+```text
+Gateway spawn
+├─ HTTP listener up (immediate)
+└─ background StartupOrchestrator
+    ├─ mark_all_features_unavailable()
+    ├─ resolve_server_prefixes()
+    ├─ build_connect_plan()
+    │   ├─ hot: enabled ∩ referenced_by_any_binding_FS
+    │   └─ warm: enabled \ hot  (still connects — no defer)
+    ├─ set_connecting(hot only)          ← UX fix: no fleet-wide CONNECTING burst
+    ├─ connect_parallel(hot, max=6)
+    ├─ set_connecting(warm batch)        ← optional: per-server as each starts
+    └─ connect_parallel(warm, max=6)
+```
+
+### Hot-set resolution (new helper)
+
+```text
+for binding in binding_repo.list():
+  for fs_id in binding.feature_set_ids:
+    resolve FeatureSet members (recursive composition)
+    collect server_id from each included tool feature
+    if FeatureSetType::ServerAll → include fs.server_id
+→ hot_server_keys: HashSet<(space_id, server_id)>
+```
+
+Intersect with `installed_servers.filter(|s| s.enabled)`.
+
+### Runtime warm triggers
+
+| Event | Action |
+| ----- | ------ |
+| `WorkspaceBindingChanged` | Compute newly referenced server keys; connect enabled missing instances (same `connect_server` path, respect semaphore) |
+| MCP session roots first stored (`SessionRootsRegistry`) | Resolve binding for roots; connect hot set for that binding if not connected |
+| User `enable_server_v2` | Unchanged — immediate connect for that server |
+
+### Agent warming signal (meta tools)
+
+Extend `mcpmux_list_servers` response (or add top-level fields on read meta tools) with:
+
+```json
+{
+  "gateway_warming": true,
+  "pool": {
+    "connected": 2,
+    "connecting": 4,
+    "expected_enabled": 12,
+    "hot_pending": 1
+  }
+}
+```
+
+`gateway_warming: true` when any **hot** server is still connecting or any enabled server referenced by current session's resolved binding is not `server_available`. Agents should retry `search_tools` after warming clears.
+
+---
+
+## Architecture
+
+```text
+┌─────────────────────────────────────────────────────────────────┐
+│  GatewayServer::run_with_shutdown                               │
+│    tokio::spawn → StartupOrchestrator                           │
+└────────────────────────────┬────────────────────────────────────┘
+                             │
+         ┌───────────────────┼───────────────────┐
+         ▼                   ▼                   ▼
+  ConnectPlanBuilder   ParallelConnectPool   ServerManager
+  (bindings + FS)        (Semaphore=6)         (set_connecting per tier)
+         │                   │
+         └─────────┬─────────┘
+                   ▼
+            PoolService::connect_server
+                   │
+                   ▼
+         FeatureService::discover_and_cache
+                   │
+                   ▼
+         DomainEvent → MCP list_changed
+
+Runtime hooks:
+  MCPNotifier / handler on WorkspaceBindingChanged → WarmPoolService::connect_missing
+  handler on roots stored → WarmPoolService::connect_for_binding
+```
+
+**Rejected for v1:** Skip boot connect for unbound enabled servers (user chose no defer). Invoke-time lazy connect (architecture conflict).
+
+---
+
+## Files to create
+
+| File | Purpose |
+| ---- | ------- |
+| `crates/mcpmux-gateway/src/server/connect_plan.rs` | `ConnectPlanBuilder` — hot/warm tiers from bindings + enabled installs |
+| `crates/mcpmux-gateway/src/server/parallel_connect.rs` | Semaphore-limited parallel connect runner shared by startup + runtime warm |
+| `crates/mcpmux-gateway/src/services/warm_pool.rs` | Runtime warm on binding/roots; exposes `PoolWarmthSnapshot` for meta tools |
+| `tests/rust/tests/integration/gateway_warm_pool.rs` | Hot tier ordering, parallel connect mock, warmth snapshot, binding-change warm |
+
+## Files to modify
+
+| File | Change |
+| ---- | ------ |
+| [`crates/mcpmux-gateway/src/server/startup.rs`](../../crates/mcpmux-gateway/src/server/startup.rs) | Replace sequential loop with tiered parallel connect; narrow CONNECTING pre-set |
+| [`crates/mcpmux-gateway/src/server/mod.rs`](../../crates/mcpmux-gateway/src/server/mod.rs) | Wire `WarmPoolService`; pass to MCP handler / orchestrator |
+| [`crates/mcpmux-gateway/src/server/service_container.rs`](../../crates/mcpmux-gateway/src/server/service_container.rs) | DI for connect plan + warm pool services |
+| [`crates/mcpmux-gateway/ARCHITECTURE.md`](../../crates/mcpmux-gateway/ARCHITECTURE.md) | Document tiered eager connect; fix parallel claim |
+| [`apps/desktop/src-tauri/src/lib.rs`](../../apps/desktop/src-tauri/src/lib.rs) | Fix stale comment ("frontend auto-connect") |
+| [`apps/desktop/src-tauri/src/commands/gateway.rs`](../../apps/desktop/src-tauri/src/commands/gateway.rs) | `connect_all_enabled_servers` → delegate to orchestrator |
+| [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | `list_servers` warmth fields; optional hint when warming |
+| [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) | Trigger runtime warm when roots stored / after binding resolve |
+| [`crates/mcpmux-gateway/src/consumers/mcp_notifier.rs`](../../crates/mcpmux-gateway/src/consumers/mcp_notifier.rs) | Call warm pool on `WorkspaceBindingChanged` |
+| [`crates/mcpmux-gateway/src/pool/server_manager.rs`](../../crates/mcpmux-gateway/src/pool/server_manager.rs) | Delete or wire dead `startup_refresh` / document replacement |
+| [`apps/desktop/src/features/settings/SettingsPage.tsx`](../../apps/desktop/src/features/settings/SettingsPage.tsx) | (Phase 3) Optional setting: startup concurrency 4/6/8 |
+
+---
+
+## Phasing
+
+### Phase 1 — Tiered plan + parallel startup
+
+**Effort:** ~1–2 days
+
+- [ ] `ConnectPlanBuilder`: load all bindings → union server_ids from FS members (+ ServerAll) → split hot/warm enabled installs
+- [ ] `ParallelConnectPool`: `FuturesUnordered` + `Semaphore(6)`; reuse existing `StartupOrchestrator::connect_server`
+- [ ] Replace sequential loop in `auto_connect_enabled_servers` with hot-then-warm parallel passes
+- [ ] CONNECTING UX: pre-set **hot tier only** (not entire fleet)
+- [ ] Unit tests: plan builder with nested FS composition, ServerAll, empty bindings → warm-only
+- [ ] Integration test: hot servers complete before warm when hot is mocked slow/fast
+
+**Outcome:** Dev restart connects binding-referenced servers (e.g. github) within seconds even when 10+ other enabled servers exist. UI shows CONNECTING for hot tier first, not 30 servers at once.
+
+### Phase 2 — Runtime warm + agent signal
+
+**Effort:** ~1–2 days
+
+- [ ] `WarmPoolService::connect_missing(keys)` — idempotent, shares semaphore with startup
+- [ ] Hook: `WorkspaceBindingChanged` → compute new hot keys → connect missing
+- [ ] Hook: session roots first stored → resolve binding → connect missing hot keys
+- [ ] `PoolWarmthSnapshot` + expose via `mcpmux_list_servers` (`gateway_warming`, counts)
+- [ ] Meta tool description updates steering agents to retry search when warming
+- [ ] Integration test: roots arrive after gateway boot → github becomes available without manual enable
+
+**Outcome:** Cursor agent session after dev restart gets invokable tools once roots land, without user running `mcpmux_enable_server`. Meta tools report warming vs ready.
+
+### Phase 3 — Unify paths, settings, cleanup
+
+**Effort:** ~0.5–1 day
+
+- [ ] `connect_all_enabled_servers` Tauri command delegates to `StartupOrchestrator` (ServerManager events consistent)
+- [ ] Optional setting `gateway.startup_concurrency` (4 / 6 / 8), default 6
+- [ ] Remove or wire dead code: `PoolService::reconnect_all_enabled`, unused `startup_refresh`
+- [ ] Update `ARCHITECTURE.md` + `lib.rs` comment
+- [ ] Manual QA: full dev restart with QA FeatureSet binding — time-to-invokable for github < 15s with 8+ enabled servers
+
+**Outcome:** One connect code path; docs match behavior; power users can tune concurrency. Planning doc reconciliation updated.
+
+---
+
+## Pre-PR validation
+
+| Step | Command | Purpose |
+| ---- | ------- | ------- |
+| Rust unit + int | `cargo nextest run -p tests -- gateway_warm_pool` + workspace lib tests | Connect plan + warm hooks |
+| Full validate | `pnpm validate` | fmt, clippy, check |
+| Manual smoke | Dev restart → `mcpmux_list_servers` → `mcpmux_search_tools` until `gateway_warming: false` | Agent UX |
+
+---
+
+## Out of scope
+
+| Item | Reason |
+| ---- | ------ |
+| Lazy connect on `invoke_tool` failure | Conflicts with pool-based routing; separate initiative if ever needed |
+| Defer unbound enabled servers at boot | Explicit decision: no defer — all enabled still connect (background tier) |
+| OAuth token prefetch | Deprecated no-op; RMCP refreshes per-request |
+| Connect only servers in **current** session binding at boot | Boot has no session; use hot union of all bindings instead |
+| Faster stdio package install (uvx/npm cache) | Environment concern, not gateway orchestration |
+
+---
+
+## Key files referenced
+
+| File | Why |
+| ---- | --- |
+| [`crates/mcpmux-gateway/src/server/startup.rs`](../../crates/mcpmux-gateway/src/server/startup.rs) | Current sequential auto-connect + CONNECTING batch |
+| [`crates/mcpmux-gateway/src/server/mod.rs`](../../crates/mcpmux-gateway/src/server/mod.rs) | Gateway spawn + background task ordering |
+| [`crates/mcpmux-gateway/src/services/feature_set_resolver.rs`](../../crates/mcpmux-gateway/src/services/feature_set_resolver.rs) | Binding resolution at MCP request time (roots) |
+| [`crates/mcpmux-gateway/src/pool/features/resolution.rs`](../../crates/mcpmux-gateway/src/pool/features/resolution.rs) | FS → feature/server resolution (reuse for hot set) |
+| [`crates/mcpmux-gateway/src/consumers/mcp_notifier.rs`](../../crates/mcpmux-gateway/src/consumers/mcp_notifier.rs) | `WorkspaceBindingChanged` consumer today |
+| [`crates/mcpmux-gateway/ARCHITECTURE.md`](../../crates/mcpmux-gateway/ARCHITECTURE.md) | Eager pool rationale — must stay compatible |
+| [`docs/planning/meta-gateway-invoke-retest.md`](./meta-gateway-invoke-retest.md) | Live QA evidence for warm-pool pain |
+
+---
+
+## Related documentation
+
+- [`docs/planning/meta-gateway-invoke.md`](./meta-gateway-invoke.md) — agent meta-tool model (primary consumer of warm pool)
+- [`docs/planning/meta-gateway-invoke-retest.md`](./meta-gateway-invoke-retest.md) — post-85113e7 QA sign-off
+- [`docs/planning/dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) — session enable semantics unchanged
+
+---
+
+## Reconciliation
+
+Update this doc's **Status** and phase checkboxes as work lands. When implementation completes, add a short entry to [`meta-gateway-invoke.md`](./meta-gateway-invoke.md) **Related documentation** linking here. Run planning-doc reconciliation (status, file inventory, phase outcomes) before marking **Status: Complete**.
+
+**Decision record (May 25, 2026):** Tiered hot/warm startup with binding-union hot set; flat concurrency 6; no defer of unbound enabled; runtime warm on binding + roots; agent warming via meta tools; full three-phase delivery.
diff --git a/docs/planning/meta-gateway-invoke.md b/docs/planning/meta-gateway-invoke.md
index 7c5ad357..b75a6aff 100644
--- a/docs/planning/meta-gateway-invoke.md
+++ b/docs/planning/meta-gateway-invoke.md
@@ -2,9 +2,9 @@
 
 **Last Updated:** May 25, 2026
 **Status:** ✅ Phases A–C implemented and manually QA complete — ready to merge ([`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md) **Ship**)
-**Branch:** `feat/meta-gateway-invoke`
-**Base branch:** `main`
-**Issue:** [#155](https://github.com/mcpmux/mcp-mux/pull/155)
+**Branch:** `feat/meta-gateway-invoke` (personal fork **integration tip** — see [`fork-integration.md`](./fork-integration.md))
+**Base branch:** `feat/dynamic-mcp-toggle-meta-tools` on fork; upstream contribution is topic-stacked, not `main`
+**Issue:** Fork-only; upstream megapr [#155](https://github.com/mcpmux/mcp-mux/pull/155) closed — use #154 stack for meta-tools upstream
 **Depends on:** [`dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) (session overrides + meta-tool registry); benefits from workspace bindings / FeatureSets from PR #151
 **Supersedes:** Token-budget approach in [`tool-level-session-pin.md`](./tool-level-session-pin.md) — pin filtered a bloated `tools/list`; this doc replaces that model with a fixed meta surface + invoke path. Session pin may return as an invoke ACL in Phase F (very optional, last).
 **Unblocks:** Agent-usable McpMux sessions at scale (240+ backend tools installed, ~12 tools in client context); homelab + multi-clone installs without context-window collapse

From 51d8a1b8c4e573ada9fd4bd724fe11738ab5326d Mon Sep 17 00:00:00 2001
From: crimsonsunset <jsangio1@gmail.com>
Date: Tue, 26 May 2026 22:18:22 -0600
Subject: [PATCH 48/48] docs: remove personal fork planning docs from upstream
 tree

Delete docs/planning/* and run-from-source-macos.md now archived in
jsg-tech-check so PR #154 stays free of homelab-specific content.

Signed-off-by: crimsonsunset <jsangio1@gmail.com>
---
 docs/planning/agent-mcp-session-readiness.md  | 301 --------------
 .../planning/dynamic-mcp-toggle-meta-tools.md | 317 ---------------
 docs/planning/fork-integration.md             |  92 -----
 docs/planning/gateway-warm-pool-startup.md    | 264 -------------
 docs/planning/meta-gateway-invoke-qa.md       | 318 ---------------
 docs/planning/meta-gateway-invoke-retest.md   | 209 ----------
 docs/planning/meta-gateway-invoke.md          | 366 ------------------
 docs/planning/server-account-clones.md        | 270 -------------
 docs/planning/server-display-rename.md        | 132 -------
 docs/planning/tool-level-session-pin.md       | 327 ----------------
 docs/planning/web-admin-remote-access.md      | 317 ---------------
 docs/run-from-source-macos.md                 | 258 ------------
 12 files changed, 3171 deletions(-)
 delete mode 100644 docs/planning/agent-mcp-session-readiness.md
 delete mode 100644 docs/planning/dynamic-mcp-toggle-meta-tools.md
 delete mode 100644 docs/planning/fork-integration.md
 delete mode 100644 docs/planning/gateway-warm-pool-startup.md
 delete mode 100644 docs/planning/meta-gateway-invoke-qa.md
 delete mode 100644 docs/planning/meta-gateway-invoke-retest.md
 delete mode 100644 docs/planning/meta-gateway-invoke.md
 delete mode 100644 docs/planning/server-account-clones.md
 delete mode 100644 docs/planning/server-display-rename.md
 delete mode 100644 docs/planning/tool-level-session-pin.md
 delete mode 100644 docs/planning/web-admin-remote-access.md
 delete mode 100644 docs/run-from-source-macos.md

diff --git a/docs/planning/agent-mcp-session-readiness.md b/docs/planning/agent-mcp-session-readiness.md
deleted file mode 100644
index 3b6fbb19..00000000
--- a/docs/planning/agent-mcp-session-readiness.md
+++ /dev/null
@@ -1,301 +0,0 @@
-# Agent MCP Session Readiness
-
-**Last Updated:** May 25, 2026  
-**Status:** Planned — umbrella initiative; child doc [`gateway-warm-pool-startup.md`](./gateway-warm-pool-startup.md) has Phase 1 decisions locked  
-**Branch:** TBD (multiple tracks; see phasing)  
-**Base branch:** `main`  
-**Issue:** TBD  
-**Depends on:** [`meta-gateway-invoke.md`](./meta-gateway-invoke.md) (meta-tool entrypoint — must be reliable at session start)  
-**Unblocks:** Using McpMux as primary agent MCP endpoint without multi-minute warm-up, empty ACL false alarms, or manual Surface reload guesswork
-
----
-
-## Problem
-
-Live QA on meta-gateway invoke (May 2026) exposed four friction points for **agent-first** McpMux use. Each has a different **control boundary** — some are fully fixable in-repo, some need client cooperation, one is intentional product design.
-
-| # | Pain | Symptom | Control |
-| - | ---- | ------- | ------- |
-| 1 | **Cold start** | Dozens of backends `CONNECTING`; github unavailable for minutes after dev restart | **High** — gateway startup |
-| 2 | **Binding / roots timing** | `total_invokable: 0` until workspace roots land; fragile across restart + Cursor reload | **Medium-high** — gateway + client timing |
-| 3 | **Surface → reload** | Surfaced tools don't appear until Cursor → MCP → Reload tools | **Medium** — we emit `list_changed`; Cursor may ignore |
-| 4 | **FeatureSet authoring** | QA FS missing GWorkspace; ACL curation is human/agent write work | **Medium** — reduce friction; cannot auto-grant all |
-
-This doc is the **umbrella plan**: what to fix, what to accept, and **exactly where to dig** in the codebase for each controllable part. Implementation detail for cold start lives in [`gateway-warm-pool-startup.md`](./gateway-warm-pool-startup.md).
-
----
-
-## Decisions (umbrella)
-
-| # | Decision | Choice | Rationale |
-| - | -------- | ------ | --------- |
-| 1 | Initiative structure | **Four tracks**, one umbrella doc; cold start is first ship | Tracks have different owners/risk; don't block warm pool on Cursor |
-| 2 | Cold start | **Tiered hot/warm + parallel×6** — see child doc | Binding-union hot set; no defer of unbound enabled |
-| 3 | Roots timing | **Runtime warm + meta `gateway_warming` signal** | Can't force Cursor to send roots earlier; can probe/warm/react |
-| 4 | Surface reload | **Audit event path first**; doc + Cursor issue if `list_changed` already fires | Don't build workarounds until we confirm gateway gap vs client gap |
-| 5 | FS authoring | **Improve agent + operator DX** — not auto-infer ACL from repo | Security model requires explicit grants |
-| 6 | Lazy invoke connect | **Out of scope** | Pool-based routing requires connected instance ([`ARCHITECTURE.md`](../../crates/mcpmux-gateway/ARCHITECTURE.md)) |
-
----
-
-## Control matrix
-
-```text
-                    McpMux fixes?    Client/user?        Track
-Cold start              ████████░░        ██ (enable count)   A — warm pool
-Roots timing            ███████░░░        ███ (roots timing)  A + B
-Surface reload          █████░░░░░        █████ (Cursor UX)   C
-FS authoring            ██████░░░░        ████ (ACL by design) D
-```
-
----
-
-## Track A — Cold start (warm pool)
-
-**Control: ~80%** · **Child doc:** [`gateway-warm-pool-startup.md`](./gateway-warm-pool-startup.md)
-
-### Symptom
-
-Gateway HTTP is up immediately; backend pool takes minutes when many servers are DB-`enabled`. UI shows fleet-wide `CONNECTING`. Agents see `server_available: false` on all tools until sequential connect + feature discovery completes.
-
-### Root cause (confirmed)
-
-| Behavior | Where to dig |
-| -------- | ------------ |
-| Background auto-connect after HTTP bind | [`crates/mcpmux-gateway/src/server/mod.rs`](../../crates/mcpmux-gateway/src/server/mod.rs) — `run_with_shutdown()` ~L445–492 |
-| Mark all features unavailable pre-connect | [`crates/mcpmux-gateway/src/server/startup.rs`](../../crates/mcpmux-gateway/src/server/startup.rs) — `mark_all_features_unavailable()` |
-| **All** DB-enabled servers, **sequential** connect | [`crates/mcpmux-gateway/src/server/startup.rs`](../../crates/mcpmux-gateway/src/server/startup.rs) — `auto_connect_enabled_servers()` ~L128–204 |
-| Batch pre-set CONNECTING for entire fleet | Same file ~L147–159 |
-| Binding does **not** filter startup connect | Compare with [`crates/mcpmux-gateway/src/services/feature_set_resolver.rs`](../../crates/mcpmux-gateway/src/services/feature_set_resolver.rs) (routing only) |
-| Eager pool rationale | [`crates/mcpmux-gateway/ARCHITECTURE.md`](../../crates/mcpmux-gateway/ARCHITECTURE.md) — Pool-Based Connection Management |
-| Dead parallel scaffold (never called) | [`crates/mcpmux-gateway/src/pool/server_manager.rs`](../../crates/mcpmux-gateway/src/pool/server_manager.rs) — `startup_refresh()` |
-| Duplicate manual connect path | [`apps/desktop/src-tauri/src/commands/gateway.rs`](../../apps/desktop/src-tauri/src/commands/gateway.rs) — `connect_all_enabled_servers` |
-| Stale auto-start comment | [`apps/desktop/src-tauri/src/lib.rs`](../../apps/desktop/src-tauri/src/lib.rs) ~L510 (claims frontend auto-connect — wrong) |
-| Tauri auto-start entry | [`apps/desktop/src-tauri/src/lib.rs`](../../apps/desktop/src-tauri/src/lib.rs) — setup spawn ~L357 |
-| UI CONNECTING state | [`apps/desktop/src/hooks/useServerManager.ts`](../../apps/desktop/src/hooks/useServerManager.ts), [`apps/desktop/src/features/servers/ServersPage.tsx`](../../apps/desktop/src/features/servers/ServersPage.tsx) |
-
-### Fix (locked)
-
-Implement [`gateway-warm-pool-startup.md`](./gateway-warm-pool-startup.md) Phases 1–3: `ConnectPlanBuilder` (binding-union hot set), parallel connect (semaphore 6), hot-then-warm tiers, narrow CONNECTING pre-set.
-
-### Outcome when done
-
-Dev restart with QA binding: github `server_available: true` within ~15s even with 8+ other enabled servers. Fleet UI no longer flashes 30× CONNECTING simultaneously.
-
----
-
-## Track B — Binding / roots timing
-
-**Control: ~70%** · **Overlaps Track A Phase 2**
-
-### Symptom
-
-Agent MCP session calls meta tools before roots arrive → resolver returns `Deny` / empty FS → `total_invokable: 0`. After roots land, binding resolves but backends may still be cold (Track A).
-
-### Root cause (confirmed)
-
-| Behavior | Where to dig |
-| -------- | ------------ |
-| Four-tier resolver (binding / pending roots / grant / deny) | [`crates/mcpmux-gateway/src/services/feature_set_resolver.rs`](../../crates/mcpmux-gateway/src/services/feature_set_resolver.rs) — full file; read module doc ~L1–26 |
-| Tier 1c: roots-capable, roots pending → empty FS | Same file ~L186–199 |
-| Tier 1b: roots but no binding → deny | Same file ~L176–183 |
-| Session roots storage | [`crates/mcpmux-gateway/src/services/session_roots.rs`](../../crates/mcpmux-gateway/src/services/session_roots.rs) — `set_roots_capable`, `get`, probe throttle |
-| On-demand roots probe before list/call | [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) — search `on-demand probe` ~L193–315, ~L660 |
-| `list_tools` vs `call_tool` roots probe parity | Same file — ensure meta-tool path uses same probe as `list_tools` |
-| Integration tests for PendingRoots | [`tests/rust/tests/integration/feature_set_resolver.rs`](../../tests/rust/tests/integration/feature_set_resolver.rs) |
-| Meta tools resolve via `caller_resolution()` | [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) — `caller_resolution()` |
-| Workspace binding entity | [`crates/mcpmux-core/src/domain/workspace_binding.rs`](../../crates/mcpmux-core/src/domain/workspace_binding.rs) |
-| Binding repo longest-prefix match | [`crates/mcpmux-core/src/repository/mod.rs`](../../crates/mcpmux-core/src/repository/mod.rs) — `find_longest_prefix_match` |
-
-### Fix
-
-1. **Track A Phase 2:** `WarmPoolService` on roots stored + `WorkspaceBindingChanged` ([`crates/mcpmux-gateway/src/consumers/mcp_notifier.rs`](../../crates/mcpmux-gateway/src/consumers/mcp_notifier.rs) ~L454 — today only `notify_all_list_changed`, no connect)
-2. **`gateway_warming` in meta tools** — [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) `list_servers` (see child doc)
-3. **Audit:** Confirm every meta-tool `call()` path runs roots probe when `PendingRoots` (handler may already; verify for CallMcpTool session id)
-
-### Not fixable in McpMux alone
-
-- Cursor opening MCP connection before reporting `roots` — we can probe/retry, not force
-- User opening wrong folder (no binding match) — `WorkspaceNeedsBinding` UX, not gateway bug
-
-### Outcome when done
-
-After dev restart + Cursor reload: first `mcpmux_search_tools` either returns tools or explicit `{ gateway_warming: true }` with retry hint — not silent empty ACL.
-
----
-
-## Track C — Surface changes need MCP reload
-
-**Control: ~50%** · **Audit-first track**
-
-### Symptom
-
-User toggles **Surface** on a FeatureSet member, saves, but Cursor agent still sees only 10 `mcpmux_*` tools until manual **Reload tools**. Direct `github_list_issues` may work via gateway while Cursor descriptor cache is stale.
-
-### What we already do (dig here first)
-
-| Step | Where to dig |
-| ---- | ------------ |
-| Surface toggle UI | [`apps/desktop/src/features/featuresets/FeatureSetPanel.tsx`](../../apps/desktop/src/features/featuresets/FeatureSetPanel.tsx) — `toggleSurfaced`, `handleSave` → `setFeatureSetMembers` with `surfaced:` |
-| Bulk member save + `surfaced` column | [`apps/desktop/src-tauri/src/commands/feature_set.rs`](../../apps/desktop/src-tauri/src/commands/feature_set.rs) — `set_feature_set_members` ~L448–525 |
-| DB migration for `surfaced` | [`crates/mcpmux-storage/src/migrations/019_feature_set_member_surfaced.sql`](../../crates/mcpmux-storage/src/migrations/019_feature_set_member_surfaced.sql) |
-| Event after save | `grant_service.notify_feature_set_modified()` in `set_feature_set_members` ~L516–522 |
-| Grant service → domain event | [`crates/mcpmux-gateway/src/services/grant_service.rs`](../../crates/mcpmux-gateway/src/services/grant_service.rs) — `notify_feature_set_modified` |
-| MCPNotifier → `tools/list_changed` | [`crates/mcpmux-gateway/src/consumers/mcp_notifier.rs`](../../crates/mcpmux-gateway/src/consumers/mcp_notifier.rs) — `FeatureSetMembersChanged` ~L419–429, `force=true` |
-| Advertised vs invokable split | [`crates/mcpmux-gateway/src/pool/features/facade.rs`](../../crates/mcpmux-gateway/src/pool/features/facade.rs) — `get_advertised_tools_for_grants` |
-| Surfaced resolution | [`crates/mcpmux-gateway/src/pool/features/resolution.rs`](../../crates/mcpmux-gateway/src/pool/features/resolution.rs) — `resolve_surfaced_feature_ids` |
-| Direct call gate + redirect | [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) — `call_tool` surfaced check |
-| Meta-tool create FS with surfaced | [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) — `CreateFeatureSetTool` |
-| QA runbook reminder | [`docs/planning/meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md), [`meta-gateway-invoke-retest.md`](./meta-gateway-invoke-retest.md) §9 |
-
-### Investigation tasks (Phase C1)
-
-- [ ] Save Surface in UI → confirm `FeatureSetMembersChanged` in gateway logs
-- [ ] Confirm MCPNotifier sends `notifications/tools/list_changed` to Cursor session (wire log or integration test with mock peer)
-- [ ] If event fires but Cursor ignores: **client limitation** — file Cursor issue; keep runbook "Reload tools after Surface"
-- [ ] If event does **not** fire: fix grant_service / gateway-not-running path in `set_feature_set_members`
-
-### Possible McpMux improvements (Phase C2 — only if audit finds gaps)
-
-- [ ] Per-session `notify_peer_lists_changed` for roots-capable peers on Surface change (today space-wide broadcast — see `ClientGrantChanged` pattern ~L432–446 for narrower fanout)
-- [ ] Desktop toast after save: "Reload MCP tools in your client to pick up surfaced tools"
-- [ ] Meta tool `mcpmux_list_servers` includes `surfaced_tools: ["github_list_issues"]` so agents know what *should* be direct-callable
-
-### Not fixable without client change
-
-Cursor (and some MCP clients) not applying `tools/list_changed` to local tool descriptor cache — manual reload remains fallback.
-
-### Outcome when done
-
-Documented truth table: "gateway emits X → Cursor does Y." Either a confirmed gateway bug fixed, or explicit "reload required" UX with no false "broken gateway" impression.
-
----
-
-## Track D — FeatureSet authoring friction
-
-**Control: ~60% (reduce friction; ACL stays explicit)**
-
-### Symptom
-
-Agent QA needed GWorkspace in FeatureSet but QA FS only had 3 github tools. Operator must know Workspaces UI, checkbox vs Surface, binding vs session enable.
-
-### Intentional constraint
-
-FeatureSets define **invoke ACL** ([`meta-gateway-invoke.md`](./meta-gateway-invoke.md) decision #5). Auto-granting all installed tools defeats the model.
-
-### Where to dig
-
-| Capability | Where to dig |
-| ---------- | ------------ |
-| FeatureSet editor (checkbox vs Surface) | [`apps/desktop/src/features/featuresets/FeatureSetPanel.tsx`](../../apps/desktop/src/features/featuresets/FeatureSetPanel.tsx) |
-| Workspace binding UI | [`apps/desktop/src/features/workspaces/WorkspacesPage.tsx`](../../apps/desktop/src/features/workspaces/WorkspacesPage.tsx), [`WorkspaceBindingSheet.tsx`](../../apps/desktop/src/features/workspaces/WorkspaceBindingSheet.tsx) |
-| Effective features inspector | Workspaces page — "Effective Features" panel (binding resolve preview) |
-| Meta: list FS | [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) — `ListFeatureSetsTool` |
-| Meta: create FS | Same — `CreateFeatureSetTool` (~L897+) with `tool_qualified_names`, `surfaced_tools` |
-| Meta: bind workspace | Same — `BindCurrentWorkspaceTool` (triggers approval — avoid in routine QA) |
-| Meta: diagnostic full catalog | Same — `ListAllToolsTool` with `invokable` / `total_invokable` (post-85113e7) |
-| Meta: discovery for agents | Same — `SearchToolsTool` |
-| Operator vs agent steering | `list_all_tools` `hint` field in same file |
-| FS member storage | [`crates/mcpmux-core/src/domain/feature_set.rs`](../../crates/mcpmux-core/src/domain/feature_set.rs) |
-| Bundles (starter FS) | FeatureSet bundles in DB; [`docs/planning/meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md) prep |
-
-### Fix options (Phase D — pick 1–2 for v1)
-
-| Option | Effort | Dig/start |
-| ------ | ------ | --------- |
-| **D1: FS authoring helper meta tool** — `mcpmux_suggest_feature_set_from_servers({ server_ids, surfaced? })` returns member list from `list_all_tools` | ~1 day | Extend [`tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) registry in [`mod.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/mod.rs) |
-| **D2: Better empty-search errors** — "server X not in binding FS; add via Workspaces or mcpmux_create_feature_set" | ~0.5 day | [`invoke.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/invoke.rs), [`tool_discovery`](../../crates/mcpmux-gateway/src/services/tool_discovery/) |
-| **D3: UI — clone FS / add server bundle to binding** | ~1–2 days | Workspaces + FeatureSet panels |
-| **D4: QA template FS checked into docs** | ~0.5 day | Extend [`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md) with canonical FS export |
-
-### Out of scope
-
-- Auto-infer FeatureSet from open repo / installed servers without explicit write
-- Removing human approval for `bind_current_workspace` (space-wide effect)
-
-### Outcome when done
-
-Agent or operator can go from "I need github + gworkspace for this repo" to a bound FS in ≤3 meta calls or one UI flow, without hand-editing JSON.
-
----
-
-## Umbrella phasing
-
-Recommended ship order — each track is independently testable.
-
-### Phase 1 — Warm pool (Track A)
-
-**Effort:** ~2–3 days · **Doc:** [`gateway-warm-pool-startup.md`](./gateway-warm-pool-startup.md) Phases 1–3
-
-Fixes pain **#1** and most of **#2** (backend availability).
-
-### Phase 2 — Roots + warming signal (Track B)
-
-**Effort:** ~1 day · **Doc:** child doc Phase 2 (may merge with Phase 1 if same PR)
-
-Fixes remaining **#2** agent confusion (`gateway_warming`).
-
-### Phase 3 — Surface list_changed audit (Track C)
-
-**Effort:** ~0.5–1 day investigate; ~1 day fix if gateway gap
-
-Fixes or documents **#3** with evidence.
-
-### Phase 4 — FS authoring DX (Track D)
-
-**Effort:** ~1–2 days for D1+D2
-
-Reduces **#4**; does not eliminate ACL curation.
-
----
-
-## Pre-PR validation (umbrella)
-
-| Track | How to verify |
-| ----- | ------------- |
-| A | Dev restart → github invokable < 15s; logs show hot tier first |
-| B | Reload Cursor → first search returns tools or `gateway_warming: true` |
-| C | Toggle Surface → log `FeatureSetMembersChanged` + optional wire capture; document Cursor behavior |
-| D | Agent creates FS from `list_all_tools` names → search finds new tools after bind |
-
----
-
-## Out of scope (umbrella)
-
-| Item | Reason |
-| ---- | ------ |
-| Faster uvx/npm installs | Environment / cache, not gateway |
-| Cursor `list_changed` implementation | External client |
-| Full auto-ACL from repo analysis | Conflicts with invoke security model |
-| Disable eager pool / lazy connect on invoke | ARCHITECTURE rejection; large routing change |
-
----
-
-## Key files referenced
-
-| File | Track |
-| ---- | ----- |
-| [`crates/mcpmux-gateway/src/server/startup.rs`](../../crates/mcpmux-gateway/src/server/startup.rs) | A |
-| [`crates/mcpmux-gateway/src/services/feature_set_resolver.rs`](../../crates/mcpmux-gateway/src/services/feature_set_resolver.rs) | B |
-| [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) | B, C |
-| [`crates/mcpmux-gateway/src/consumers/mcp_notifier.rs`](../../crates/mcpmux-gateway/src/consumers/mcp_notifier.rs) | B, C |
-| [`apps/desktop/src-tauri/src/commands/feature_set.rs`](../../apps/desktop/src-tauri/src/commands/feature_set.rs) | C |
-| [`apps/desktop/src/features/featuresets/FeatureSetPanel.tsx`](../../apps/desktop/src/features/featuresets/FeatureSetPanel.tsx) | C, D |
-| [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | B, D |
-
----
-
-## Related documentation
-
-- [`docs/planning/gateway-warm-pool-startup.md`](./gateway-warm-pool-startup.md) — Track A/B implementation detail (decisions locked)
-- [`docs/planning/meta-gateway-invoke.md`](./meta-gateway-invoke.md) — meta-tool entrypoint model
-- [`docs/planning/meta-gateway-invoke-retest.md`](./meta-gateway-invoke-retest.md) — live QA evidence
-- [`crates/mcpmux-gateway/ARCHITECTURE.md`](../../crates/mcpmux-gateway/ARCHITECTURE.md) — eager pool rationale
-
----
-
-## Reconciliation
-
-Update **Status** and track checkboxes as phases ship. When Track A completes, mark [`gateway-warm-pool-startup.md`](./gateway-warm-pool-startup.md) **Status: Complete** and link back here. Run planning-doc reconciliation before closing the umbrella initiative.
-
-**Decision record (May 25, 2026):** Four-track umbrella for agent session readiness; cold start first via warm pool; Surface audit before building client workarounds; FS authoring improved via meta-tool DX not auto-ACL.
diff --git a/docs/planning/dynamic-mcp-toggle-meta-tools.md b/docs/planning/dynamic-mcp-toggle-meta-tools.md
deleted file mode 100644
index 540080c6..00000000
--- a/docs/planning/dynamic-mcp-toggle-meta-tools.md
+++ /dev/null
@@ -1,317 +0,0 @@
-# Dynamic MCP Toggling via Meta Tools
-
-**Last Updated:** May 23, 2026
-**Status:** Feature complete on fork — session grants + structuredContent fixes verified; pending upstream PR merge
-**Branch:** `feat/dynamic-mcp-toggle-meta-tools`
-**Base branch:** `feat/workspace-root-routing` ([upstream PR #151](https://github.com/mcpmux/mcp-mux/pull/151))
-**Issue:** TBD — file after planning review
-**Depends on:** [PR #151](https://github.com/mcpmux/mcp-mux/pull/151) merging or being consumed via fork (provides the `mcpmux_*` namespace, `MetaToolRegistry`, `ApprovalBroker`, `FeatureSetResolverService`, per-peer `list_changed`, `SessionRootsRegistry`)
-**Unblocks:** [`jsg-tech-check` homelab MCP strategy](../../../jsg-tech-check/docs/setup/home-lab-overview.md#mcp-strategy--current-state)
-
----
-
-## Problem
-
-The Cursor / Claude Code pre-McpMux workflow gave a per-project escape valve: each `.cursor/mcp.json` declared a subset of servers, so the client only loaded the tools that mattered for that project. Token budget stayed proportional to the project's actual needs.
-
-Routing everything through McpMux collapses that signal. The gateway exposes one consolidated MCP endpoint; the client side sees a single `mcpmux` server entry that's either ON or OFF. All 35+ tools from every enabled backend land in the LLM context window the moment a session opens, regardless of what the project actually needs.
-
-PR #151 partly addresses this with persistent `WorkspaceBinding`s: bind `~/code/personal/set-times-app` to `{core, browser, design, db-personal}` and the gateway serves exactly those tools when Cursor opens that folder. That works for stable, known scopes. It does not work for:
-
-- **Discovery-driven work** — "use whichever MCPs you need for this task" with no pre-declared bundle.
-- **One-off needs** — "I'm in `set-times-app` (which is bound to a bundle that excludes `firebase`) but I need `firebase` for the next 15 minutes."
-- **Minimum-context defaults** — start a session with zero backend tools loaded, let the LLM pull in what it needs based on the manifest, drop tools when it's done.
-
-The user-facing ask, stated as the original request:
-
-> Instead of having the whole definitions of all my MCPs all the time, I'd just have 1 always-on tool that gives me a manifest and then mcp can be smart enough to turn itself on.
-
-PR #151 ships four meta tools (`mcpmux_list_all_tools`, `mcpmux_list_feature_sets`, `mcpmux_create_feature_set`, `mcpmux_bind_current_workspace`). They cover the manifest + persist-a-new-bundle path. They don't cover the ephemeral toggle path — there's no way to turn a backend server on for "just this session" without writing a binding to the DB.
-
-This doc extends the meta-tools surface with session-scoped enable/disable, plus a server-level (coarser than tool-level) `mcpmux_list_servers` manifest tool. The resolver gains a Tier 0 (`SessionOverride`) that composes additively over Tier 1's `WorkspaceBinding`.
-
----
-
-## Decisions
-
-| # | Decision | Choice | Rationale |
-| - | -------- | ------ | --------- |
-| 1 | Granularity | **Server-level** (`mcpmux_enable_server("github")`), not tool-level | Matches the user's mental model ("turn on github") and the existing `FeatureSetType::ServerAll`. Tool-level enable can be added later as a degenerate case if a real use case shows up. |
-| 2 | Default scope | **Session** (default), with `scope: "workspace"` as an opt-in arg | Session is the low-risk default; ephemerality is the point. Workspace scope falls back to the existing `WorkspaceBinding` write path, reusing PR #151 plumbing. |
-| 3 | Composition with bindings | **Additive over `WorkspaceBinding`**: `effective = (binding ∪ session_enabled) − session_disabled` | Lets users keep their stable per-project bundle AND opportunistically add a server for a single session. Subtractive disable lets them mute a noisy server temporarily without unbinding. |
-| 4 | Override lifetime | **In-memory, dies with `mcp-session-id`** | Matches `SessionRootsRegistry` semantics introduced by PR #151. Restart of gateway or client = fresh start. No DB persistence; no migration. |
-| 5 | Approval flow | Session enables auto-allow by default (configurable); workspace writes require approval (existing flow) | Session-scope is ephemeral and safer than persistent state. App setting `gateway.session_overrides_require_approval` (default `false`) lets paranoid users gate everything. |
-| 6 | Audit | Every override emits a `DomainEvent::MetaToolInvoked` (existing path) | No new event variants; the audit log already renders meta-tool calls. The "decision" field gets `"session_override"` for auto-allowed session writes. |
-| 7 | Manifest format | `mcpmux_list_servers` returns server roster with `{id, name, tool_count, status}` where status ∈ `enabled_via_binding \| enabled_via_session \| disabled_via_session \| inactive` | The LLM needs to see current state, not just availability — otherwise it can't reason about whether to call enable or just call the tool. |
-| 8 | Tier-0 placement | New `SessionOverrideRegistry` consulted **inside** `FeatureService` materialization, not as a new resolver tier | Resolver already returns `(space, feature_set_ids)` cleanly. Layering at the materialization step keeps the resolver pure and concentrates the composition logic in one place (`FeatureService::get_tools_for_grants`). |
-
----
-
-## The Model
-
-### Override store
-
-Per-session, two server-id sets. Both empty = no overrides, default routing applies.
-
-```text
-SessionOverrideRegistry {
-    enabled : DashMap<SessionId, HashSet<ServerId>>,
-    disabled: DashMap<SessionId, HashSet<ServerId>>,
-}
-```
-
-GC mirrors `SessionRootsRegistry`: both maps drop on `MCPNotifier`'s session-reap pass.
-
-### Composition rule
-
-For a session resolving its effective server set:
-
-```text
-1. (space, feature_set_ids) ← FeatureSetResolverService::resolve(...)
-2. binding_servers ← FeatureService::servers_for(space, feature_set_ids)
-3. session_on     ← SessionOverrideRegistry.enabled[session_id]
-4. session_off    ← SessionOverrideRegistry.disabled[session_id]
-5. effective      ← (binding_servers ∪ session_on) − session_off
-6. tools          ← every Tool feature whose server_id ∈ effective AND is_available
-```
-
-`session_on` and `session_off` are honored even when the resolver returned `Deny` (no binding match) — the session-override path is how a roots-capable client opts into tools without a binding. Empty override sets + `Deny` from resolver = no tools (existing behavior).
-
-### Tool surface
-
-Three new tools added to `build_default_registry`:
-
-| Tool | Type | Approval (default) | Purpose |
-| ---- | ---- | ------------------ | ------- |
-| `mcpmux_list_servers` | read | none | Server-level manifest with status per server. Coarser than `mcpmux_list_all_tools`. |
-| `mcpmux_enable_server` | write | session: auto-allow; workspace: approval | Adds `server_id` to session overrides (or writes a binding). |
-| `mcpmux_disable_server` | write | session: auto-allow; workspace: approval | Adds `server_id` to session disable set (or removes from binding). |
-
-Each write fires `tools/list_changed` per-peer via the existing `MCPNotifier::notify_peer_lists_changed` path so the calling LLM's tool list refreshes mid-conversation.
-
-### What McpMux still stores
-
-| Item | Storage | Persistence |
-| ---- | ------- | ----------- |
-| Session overrides (enabled + disabled sets) | `SessionOverrideRegistry` (in-memory `DashMap`) | Process-lifetime; dies with session reap |
-| Workspace-scope writes | `workspace_bindings` table (existing) | Persistent (no schema change) |
-| Audit trail | `DomainEvent::MetaToolInvoked` (existing) | Persistent via existing audit log |
-| `gateway.session_overrides_require_approval` setting | `app_settings` table (existing) | Persistent |
-
----
-
-## Architecture
-
-```
-              ┌──────────────────────────────────────────┐
-              │  FeatureService::get_tools_for_grants    │
-              │  (existing materialization chokepoint)   │
-              │                                          │
-              │  binding_servers   = resolver-derived    │
-              │  + session_enabled ← Tier 0 overrides    │
-              │  − session_disabled                      │
-              └──────────────────────────────────────────┘
-                              ▲
-                              │
-   ┌──────────────────────────┴──────────────────────────┐
-   │                                                     │
-   ▼                                                     ▼
-┌─────────────────────────┐              ┌──────────────────────────────┐
-│ FeatureSetResolverService│             │ SessionOverrideRegistry      │
-│ (PR #151 — unchanged)    │             │ (new)                        │
-│                          │             │                              │
-│ Tier 1: WorkspaceBinding │             │ enabled : DashMap<sid, set>  │
-│ Tier 2: ClientGrant      │             │ disabled: DashMap<sid, set>  │
-│ Tier 3: Deny             │             └──────────────────────────────┘
-└─────────────────────────┘                            ▲
-                                                       │
-                                          ┌────────────┴────────────┐
-                                          │ Meta tool writes mutate │
-                                          │ this registry directly. │
-                                          │                         │
-                                          │ mcpmux_enable_server    │
-                                          │ mcpmux_disable_server   │
-                                          └─────────────────────────┘
-```
-
-- `SessionOverrideRegistry` lives in `crates/mcpmux-gateway/src/services/`, sibling to `session_roots.rs`. Same `Arc<Self>` factory pattern, same GC contract.
-- `FeatureService` is the only consumer that reads it. The resolver itself stays pure — no new tier, no new branch in `feature_set_resolver.rs`.
-- Writes go through the existing `MetaToolRegistry` dispatch in `tools.rs` → `with_approval()` (session-scope short-circuits approval when the setting allows) → mutate the registry → emit `tools/list_changed` via the existing `emit_tools_list_changed` helper.
-
----
-
-## Files to create
-
-| File | Purpose |
-| ---- | ------- |
-| `crates/mcpmux-gateway/src/services/session_overrides.rs` | `SessionOverrideRegistry` — `DashMap`-backed enable/disable sets, GC hooks, query helpers (`is_enabled`, `is_disabled`, `effective_overlay`) |
-| `tests/rust/tests/integration/meta_tools.rs` | Composition tests: deny bootstrap, disable, additive (Phase 1); meta-tool E2E (existing) |
-| `docs/planning/dynamic-mcp-toggle-meta-tools.md` | This doc |
-
-## Files to modify
-
-| File | Change |
-| ---- | ------ |
-| [`crates/mcpmux-gateway/src/services/mod.rs`](../../crates/mcpmux-gateway/src/services/mod.rs) | `pub mod session_overrides;` + re-export `SessionOverrideRegistry` |
-| [`crates/mcpmux-gateway/src/services/meta_tools/mod.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/mod.rs) | Register `ListServersTool`, `EnableServerTool`, `DisableServerTool` in `build_default_registry`. Add `session_overrides: Arc<SessionOverrideRegistry>` to `MetaToolContext`. |
-| [`crates/mcpmux-gateway/src/services/meta_tools/registry.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/registry.rs) | Extend `MetaToolContext` with `session_overrides`. Add `"session_override"` to the decision-string match in `MetaToolRegistry::call` so audit rows are distinguishable. |
-| [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | Implement `ListServersTool`, `EnableServerTool`, `DisableServerTool`. Session-scope short-circuits `with_approval` when `gateway.session_overrides_require_approval` is false. |
-| [`crates/mcpmux-gateway/src/pool/features/facade.rs`](../../crates/mcpmux-gateway/src/pool/features/facade.rs) | `FeatureService::get_tools_for_grants` (and sibling `get_prompts_for_grants`, `get_resources_for_grants`) take `session_id: Option<&str>` and apply `SessionOverrideRegistry` composition before returning. |
-| [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) | Pass `session_id` (already on `RequestContext`) into the new `get_*_for_grants` signatures. |
-| [`crates/mcpmux-gateway/src/server/service_container.rs`](../../crates/mcpmux-gateway/src/server/service_container.rs) | Construct `Arc<SessionOverrideRegistry>` once; wire into `MetaToolContext`, `FeatureService`, and the session-reap path in `MCPNotifier`. |
-| [`crates/mcpmux-gateway/src/consumers/mcp_notifier.rs`](../../crates/mcpmux-gateway/src/consumers/mcp_notifier.rs) | In the session-reap pass, also call `SessionOverrideRegistry::remove(session_id)` alongside `SessionRootsRegistry::remove`. |
-| [`crates/mcpmux-core/src/domain/event.rs`](../../crates/mcpmux-core/src/domain/event.rs) | No new variant — `MetaToolInvoked` already carries `decision: String`. Document `"session_override"` as a valid value in the doc comment. |
-| [`apps/desktop/src/features/workspaces/WorkspacesPage.tsx`](../../apps/desktop/src/features/workspaces/WorkspacesPage.tsx) | New "Active session overrides" sub-panel under the live-session inspector: per-session list of enabled / disabled server_ids with a "clear" button. |
-| [`apps/desktop/src-tauri/src/commands/session_overrides.rs`](../../apps/desktop/src-tauri/src/commands/session_overrides.rs) | Tauri commands: `list_session_overrides`, `clear_session_overrides`. Read-only + clear; mutation via MCP tools. |
-| [`apps/desktop/src-tauri/src/commands/settings.rs`](../../apps/desktop/src-tauri/src/commands/settings.rs) | `get/set_session_overrides_require_approval` settings commands. |
-| [`apps/desktop/src-tauri/src/commands/gateway.rs`](../../apps/desktop/src-tauri/src/commands/gateway.rs) | Wire `session_overrides` + `mcp_notifier` into `GatewayAppState` on gateway start. |
-| [`apps/desktop/src/lib/api/sessionOverrides.ts`](../../apps/desktop/src/lib/api/sessionOverrides.ts) | TS wrappers for session override commands + workspace root matching helpers. |
-| [`crates/mcpmux-gateway/src/server/mod.rs`](../../crates/mcpmux-gateway/src/server/mod.rs) | `session_overrides()`, `notification_bridge()` accessors; shared `MCPNotifier` instance. |
-| [`README.md`](../../README.md) | Self-Management Meta Tools feature subsection. |
-
----
-
-## Phasing
-
-### Phase 1 — `SessionOverrideRegistry` + composition wiring ✅
-
-**Effort:** 1 evening  
-**Completed:** May 19, 2026
-
-- [x] `crates/mcpmux-gateway/src/services/session_overrides.rs` — `DashMap`-backed registry with `enable`, `disable`, `clear`, `enabled_set`, `disabled_set`, `remove`, `list_all`
-- [x] Plumb `Arc<SessionOverrideRegistry>` through `ServiceContainer` → `ServiceFactory` → `FeatureService` and `MCPNotifier`
-- [x] `FeatureService::get_*_for_grants(..., session_id: Option<&str>)` applies server-level composition: `effective = (binding_servers ∪ enabled) − disabled`, then all available features per effective `server_id`
-- [x] All callsites updated (`handler.rs`, `routing.rs`, `handlers.rs`, `meta_tools/diff.rs`, integration tests) — MCP handler passes real session id; others pass `None`
-- [x] `MCPNotifier::reap_dead_sessions` drops override entries alongside session roots
-- [x] Unit tests in `session_overrides.rs`; composition tests in `tests/rust/tests/integration/meta_tools.rs` (deny bootstrap, disable, additive)
-
-**Outcome (verified):** Direct registry mutation changes the next `get_tools_for_grants` result. Meta-tools and UI unchanged. `RoutingService::call_tool` authorization deferred to Phase 3 (list-only in Phase 1).
-
-**Implementation notes:**
-- Server-level composition loads **all available** features for each effective `server_id` (not FS-partial tool subsets).
-- Fixed pre-existing DashMap deadlock in `SessionRootsRegistry::record_resolution` (`get` guard must not overlap `insert` on the same map).
-
-### Phase 2 — `mcpmux_list_servers` read tool ✅
-
-**Effort:** 1 evening  
-**Completed:** May 19, 2026
-
-- [x] `ListServersTool` in `meta_tools/tools.rs` — groups `ServerFeature::list_for_space` by `server_id`, counts tools, derives status
-- [x] Status enum: `enabled_via_binding | enabled_via_session | disabled_via_session | inactive` (binding → session-enabled → session-disabled priority)
-- [x] `SessionOverrideRegistry` plumbed into `MetaToolContext` for status derivation
-- [x] Registered in `build_default_registry`
-- [x] Integration tests: inactive (no binding), `enabled_via_binding`, session override statuses
-
-**Outcome:** LLM calls `mcpmux_list_servers` and gets a server roster with per-server status. No state mutation.
-
-### Phase 3 — `mcpmux_enable_server` / `mcpmux_disable_server` (session scope) ✅
-
-**Effort:** 1 day  
-**Completed:** May 19, 2026
-
-- [x] `EnableServerTool` + `DisableServerTool` in `meta_tools/tools.rs` with `{ server_id, scope? }` args
-- [x] Session flow: validate server in Space → optional approval via `gateway.session_overrides_require_approval` → mutate `SessionOverrideRegistry`
-- [x] Workspace scope rejected until Phase 4
-- [x] Auto-allowed writes audit as `session_override`; approval-gated writes audit as `allow_once`
-- [x] Handler fires `MCPNotifier::notify_session_lists_changed` after successful enable/disable
-- [x] Integration tests: enable adds tools, disable removes tools, workspace rejected, audit decision
-
-**Outcome:** LLM can toggle servers mid-session; tools appear/disappear on next `tools/list`. No DB writes.
-
-### Phase 4 — Workspace-scope variants ✅
-
-**Effort:** 1 day  
-**Completed:** May 19, 2026
-
-- [x] `scope: "workspace"` on enable/disable — resolves workspace binding from session roots
-- [x] Enable: create/reuse server-all FeatureSet (`server_id` field tagged), append to binding, emit `WorkspaceBindingChanged`
-- [x] Disable: remove server-all FS from binding; reject if server exposed via custom FS (Workspaces UI message)
-- [x] Always requires approval via `ApprovalBroker`
-- [x] Handler skips session `list_changed` for workspace scope (binding event fanout handles it)
-- [x] Integration tests: persist across simulated session restart, disable removes binding layer, unbound workspace rejected
-
-**Outcome:** Workspace binding gains/loses persistent server-all FeatureSet layers via meta tools.
-
-### Phase 5 — UI surface for session overrides ✅
-
-**Effort:** 1 day
-
-- [x] New "Active session overrides" sub-panel inside `WorkspacesPage.tsx`'s live-session inspector: lists per-session `enabled`/`disabled` server ids alongside the reported roots.
-- [x] "Clear all overrides" button per session — calls the new `clear_session_overrides` Tauri command. Useful when a session got into a weird state and the user wants a clean default-routing read.
-- [x] New Tauri commands: `list_session_overrides(session_id) -> { enabled: string[], disabled: string[] }`, `clear_session_overrides(session_id)`.
-- [x] Settings checkbox under Gateway settings: "Require approval for session-scope overrides" — wires to `gateway.session_overrides_require_approval`.
-- [x] README section describing the new meta-tools and manifest-driven workflow ([README.md](../../README.md)).
-- [x] CHANGELOG — release-please from conventional `feat(meta-tools):` commits; no manual edit to `CHANGELOG.md`.
-
-**Outcome:** From the Workspaces tab, a user can see at a glance "session abc123 has GitHub enabled (session) and Firebase disabled (session)" and clear them with one click. The new approval-required setting is discoverable in Gateway settings without reading docs.
-
----
-
-## Pre-PR validation
-
-Do **not** open a PR until all automated checks pass and the production build is verified manually.
-
-| Step | Command | Purpose |
-| ---- | ------- | ------- |
-| Full validate | `pnpm validate` | fmt, clippy, check, eslint, typecheck |
-| Rust tests | `pnpm test:rust` | unit + integration (`meta_tools.rs`) |
-| TS tests | `pnpm test:ts` | vitest |
-| Production build | `pnpm build` | Tauri build on current platform |
-| Manual smoke (recommended) | Run app, exercise Workspaces overrides panel + Settings toggles | UX verification |
-
-Optional (slow / env-dependent): `pnpm test:e2e`, `pnpm test:e2e:web`.
-
-**PR target:** `feat/workspace-root-routing` (stacked on [PR #151](https://github.com/mcpmux/mcp-mux/pull/151)).
-
----
-
-## Out of scope
-
-| Item | Reason |
-| ---- | ------ |
-| Tool-level granularity (`mcpmux_enable_tools(["github_create_issue"])`) | Server-level covers the user's stated use case. Adding tool-level later is additive — same approval flow, more specific `qualified_name` list. No real evidence yet that tool-level matters more than server-level for token budget. |
-| Persistent session preferences across gateway restarts | Process-lifetime is the design — sessions die when the client reconnects. If a user wants stickiness, they should use a binding. Adding persistence here would duplicate the binding system poorly. |
-| Auto-enable on tool-call hint ("LLM tried to call `github_create_issue` → silently enable github first") | Requires a "shadow tool list" mechanism in the handler (advertise more than is currently active). Possible follow-up, but design isn't obvious — silent enable defeats the audit trail. |
-| Cross-client session sharing | `mcp-session-id` is per-MCP-session; two Cursor windows have two sessions and two override sets. By design — independent contexts. |
-| Override expiry / TTL | Sessions are already ephemeral. A TTL would be a different concept and isn't asked for. |
-| Tool-level disable inside an already-enabled server | Use `mcpmux_create_feature_set` + `mcpmux_bind_current_workspace` (PR #151's existing path) for fine-grained subsets. |
-
----
-
-## Key files referenced
-
-| File | Why |
-| ---- | --- |
-| [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | Where the three new `MetaTool` impls land. Existing `with_approval` + `caller_space_id` patterns are the templates. |
-| [`crates/mcpmux-gateway/src/services/meta_tools/mod.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/mod.rs) | `build_default_registry` factory — registration site for the new tools. `MetaToolContext` gains one new field. |
-| [`crates/mcpmux-gateway/src/services/meta_tools/registry.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/registry.rs) | `MetaToolRegistry::call` dispatch + audit emission. Adds `"session_override"` decision string. |
-| [`crates/mcpmux-gateway/src/services/meta_tools/approval.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/approval.rs) | `ApprovalBroker` — reused as-is for workspace-scope writes. Session-scope writes short-circuit when the setting allows. |
-| [`crates/mcpmux-gateway/src/services/session_roots.rs`](../../crates/mcpmux-gateway/src/services/session_roots.rs) | Pattern reference for `SessionOverrideRegistry`. Same `Arc<Self>` + `DashMap` + GC contract. |
-| [`crates/mcpmux-gateway/src/services/feature_set_resolver.rs`](../../crates/mcpmux-gateway/src/services/feature_set_resolver.rs) | Tier 1/2/3 resolver — stays untouched. Override composition happens in `FeatureService`, not here. |
-| [`crates/mcpmux-gateway/src/pool/features/facade.rs`](../../crates/mcpmux-gateway/src/pool/features/facade.rs) | `FeatureService::get_tools_for_grants` is the materialization chokepoint where the override composition runs. |
-| [`crates/mcpmux-gateway/src/consumers/mcp_notifier.rs`](../../crates/mcpmux-gateway/src/consumers/mcp_notifier.rs) | Session-reap pass — extend to also drop override entries. `notify_peer_lists_changed` is reused for the post-write list refresh. |
-| [`apps/desktop/src/features/workspaces/WorkspacesPage.tsx`](../../apps/desktop/src/features/workspaces/WorkspacesPage.tsx) | New "Active session overrides" sub-panel slots into the existing live-session inspector. |
-
----
-
-## Related work
-
-- [mcpmux/mcp-mux PR #151](https://github.com/mcpmux/mcp-mux/pull/151) — workspace-root-driven FeatureSet routing + the `mcpmux_*` meta-tool namespace this PR builds on. Must merge (or be consumed via fork) first.
-- [`docs/planning/issue-52-secret-text-input-syntax.md`](./issue-52-secret-text-input-syntax.md) — sibling planning doc; same conventions used here. Independent feature, no functional overlap.
-- [`docs/planning/server-account-clones.md`](./server-account-clones.md) — multi-account installs via UI clone; branched after meta-tools + gateway fixes.
-- [`jsg-tech-check` homelab plan](../../../jsg-tech-check/docs/setup/home-lab-overview.md#mcp-strategy--current-state) — the consuming use case. The "Personal vs Work" Spaces + bundled `set-times-app` / `sync2hire-platform` model leans on bindings; this doc adds the "no, actually just enable this one MCP for the next 10 minutes" escape valve.
-- [MCP spec — Tools `list_changed`](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#list-changed-notification) — the protocol mechanism that makes the post-write tool-list refresh observable mid-conversation. Already wired by PR #151.
-
----
-
-## Reconciliation
-
-This doc is the source of truth for what gets built. When implementation completes, update the **Status** field at the top and reconcile any deviations (extra files, dropped phases, scope changes) per [`update-planning-md`](~/.cursor/commands/update-planning-md.md).
-
-**May 23, 2026 closeout:**
-- Phases 1–5 implemented on `feat/dynamic-mcp-toggle-meta-tools`.
-- Post-ship fixes on same branch: session-grant routing in `call_tool` (`5269a18`), `structuredContent` forwarding for proxied tool results (`d519a79`) — required for Google Workspace MCP through mux.
-- Tauri commands landed in `session_overrides.rs` (not `workspace_binding.rs` as originally planned).
-- CHANGELOG handled by release-please; README updated in-repo.
-- Pre-PR validation gate documented above; PR blocked until validate + tests + build pass.
-- Follow-on: [server-account-clones.md](./server-account-clones.md) branched from this work for multi-account migration.
diff --git a/docs/planning/fork-integration.md b/docs/planning/fork-integration.md
deleted file mode 100644
index be9d0c17..00000000
--- a/docs/planning/fork-integration.md
+++ /dev/null
@@ -1,92 +0,0 @@
-# Personal fork integration (crimsonsunset)
-
-**Last updated:** May 25, 2026  
-**Purpose:** Single source of truth for local/homelab work on [crimsonsunset/mcp-mux](https://github.com/crimsonsunset/mcp-mux). Upstream PR stacking is separate and optional.
-
----
-
-## Canonical branch
-
-| Branch | Role |
-|--------|------|
-| **`feat/meta-gateway-invoke`** | **Integration tip** — run `pnpm dev`, gateway QA, and all new work here |
-| `feat/dynamic-mcp-toggle-meta-tools` | Pointer kept in sync with tip (session meta-tools, bindings base) |
-| `feat/server-account-clones` | Pointer kept in sync with tip (account clones + meta-gateway invoke) |
-| `main` | Tracks upstream `mcpmux/mcp-mux` — **not** where fork features live |
-
-**Rule:** If it is not on `feat/meta-gateway-invoke`, you are not running your fork.
-
-### What is on the integration tip
-
-Linear stack (newest at top):
-
-1. Meta-gateway invoke (search → schema → invoke, surfaced tools, opt-in invoke filters)
-2. Server account clones
-3. Dynamic MCP toggle meta-tools + workspace/session routing (fork lineage ahead of upstream `main`)
-4. Planning docs and homelab QA sign-offs
-
-See [`meta-gateway-invoke.md`](./meta-gateway-invoke.md), [`agent-mcp-session-readiness.md`](./agent-mcp-session-readiness.md), [`gateway-warm-pool-startup.md`](./gateway-warm-pool-startup.md).
-
----
-
-## Daily workflow
-
-```bash
-git checkout feat/meta-gateway-invoke
-git pull origin feat/meta-gateway-invoke   # after pushes from other machines
-pnpm dev                                   # gateway on localhost:45818
-```
-
-New feature work:
-
-```bash
-git checkout feat/meta-gateway-invoke
-git pull origin feat/meta-gateway-invoke
-git checkout -b feat/my-topic
-# ... commits ...
-git checkout feat/meta-gateway-invoke
-git merge feat/my-topic                    # or rebase topic onto tip first
-git push origin feat/meta-gateway-invoke
-```
-
-Homelab Cursor config: one `mcpmux` entry → `http://localhost:45818/mcp`. Migration tracker: [mcpmux-server-migration.md](../../../jsg-tech-check/docs/setup/mcpmux-server-migration.md).
-
----
-
-## Upstream PR policy (mcpmux/mcp-mux)
-
-| PR | Action | Why |
-|----|--------|-----|
-| [#152](https://github.com/mcpmux/mcp-mux/pull/152) `fix/dcr-skip-invalid-redirect-uris` | **Keep open** | Small, standalone OAuth fix (~47 lines) → `main` |
-| [#154](https://github.com/mcpmux/mcp-mux/pull/154) `feat/dynamic-mcp-toggle-meta-tools` | **Keep open (draft)** | Proper stack: base `feat/workspace-root-routing`, not a megapr |
-| [#155](https://github.com/mcpmux/mcp-mux/pull/155) `feat/meta-gateway-invoke` | **Closed** | Wrong base (`main`); entire fork stack (~28k LOC). Work lives on fork integration branch only |
-
-**Not owned by this fork:** [#151](https://github.com/mcpmux/mcp-mux/pull/151) workspace-root-routing (upstream). #154 targets that branch when contributing meta-tools upstream.
-
-Future upstream contributions: branch off fresh `upstream/main` (or merged #151), cherry-pick or restack **one topic per PR** — do not reopen a megapr to `main`.
-
----
-
-## Branch pointer sync
-
-After the integration tip moves, fast-forward stale names (optional hygiene):
-
-```bash
-git checkout feat/dynamic-mcp-toggle-meta-tools && git merge --ff-only feat/meta-gateway-invoke
-git checkout feat/server-account-clones && git merge --ff-only feat/meta-gateway-invoke
-git push origin feat/meta-gateway-invoke feat/dynamic-mcp-toggle-meta-tools feat/server-account-clones
-```
-
----
-
-## Next implementation priorities (on integration branch)
-
-1. [`gateway-warm-pool-startup.md`](./gateway-warm-pool-startup.md) — cold start / `gateway_warming`
-2. Homelab `mcp.json` cutover (bindings + `bundle:core`)
-3. Replace stock `McpMux.app` with a build from this branch ([`run-from-source-macos.md`](../run-from-source-macos.md))
-
----
-
-## Reconciliation
-
-When the integration tip gains a major milestone, update this file's **Last updated** and the **What is on the integration tip** list. Close new upstream megaprs to `main`; keep topic PRs stacked on the appropriate upstream feature branch.
diff --git a/docs/planning/gateway-warm-pool-startup.md b/docs/planning/gateway-warm-pool-startup.md
deleted file mode 100644
index ff209aee..00000000
--- a/docs/planning/gateway-warm-pool-startup.md
+++ /dev/null
@@ -1,264 +0,0 @@
-# Gateway Warm Pool Startup
-
-**Last Updated:** May 25, 2026  
-**Status:** Planned — decisions locked, not started  
-**Branch:** TBD (suggest `feat/gateway-warm-pool` off `main`)  
-**Base branch:** `main`  
-**Issue:** TBD — file after planning review  
-**Depends on:** [`meta-gateway-invoke.md`](./meta-gateway-invoke.md) (agent meta-tool entrypoint — warm pool makes invoke/search reliable at session start)  
-**Parent initiative:** [`agent-mcp-session-readiness.md`](./agent-mcp-session-readiness.md) (umbrella — all four agent entrypoint pain points)  
-**Unblocks:** Agent-first McpMux sessions without multi-minute CONNECTING stalls; post-restart binding/roots race where `total_invokable: 0` until backends connect
-
----
-
-## Problem
-
-Gateway auto-start is fast for HTTP (`Ready to accept connections` immediately), but **backend MCP pool warm-up is slow and binding-blind**. Agents hit empty search/invoke results while servers spin up.
-
-Observed in May 2026 live QA (meta-gateway invoke retest):
-
-| Symptom | Cause |
-| ------- | ----- |
-| All enabled servers show **CONNECTING** at once | Batch `set_connecting` pre-loop in `StartupOrchestrator` |
-| github unavailable for minutes after dev restart | Sequential connect through full enabled fleet |
-| `total_invokable: 0`, `server_available: false` on all tools | `mark_all_features_unavailable` until each server completes handshake + discovery |
-| Binding-resolved FS ready before github connects | Startup connects **all** DB-`enabled` servers, not binding-priority |
-| Agent session roots arrive after first meta-tool calls | No runtime warm on roots/binding change |
-
-Current startup path (`GatewayServer::run_with_shutdown` → `StartupOrchestrator::auto_connect_enabled_servers`):
-
-1. Mark all features unavailable  
-2. Resolve prefixes (all spaces)  
-3. **Sequential** connect every `InstalledServer` where `enabled == true` (all spaces)  
-4. Pre-set **all** enabled servers to CONNECTING before any handshake completes  
-
-`ARCHITECTURE.md` documents pool-based **eager** connect (intentional — routing requires a pool instance). It also claims **parallel** startup connects; implementation is **sequential**. Bindings / FeatureSets affect routing only — not startup selection.
-
----
-
-## Decisions
-
-| # | Decision | Choice | Rationale |
-| - | -------- | ------ | --------- |
-| 1 | Startup connect scope | **Tiered** — binding-referenced servers first (parallel), then remaining DB-enabled in background | Agent-visible servers ready quickly without abandoning eager pool model for power users |
-| 2 | Hot-set derivation | **Union of server_ids from ALL workspace bindings** (any space) | Matches multi-workspace installs; any bound folder's servers get priority |
-| 3 | Unbound enabled servers | **No deferral** — still connect at boot (background tier after hot) | Preserves current "I enabled it, it should connect" desktop expectation |
-| 4 | Parallelism | **Single semaphore, 6 concurrent** (stdio + HTTP mixed) | Balance wall-clock vs CPU/IO spike on homelab installs |
-| 5 | Runtime warm | **On `WorkspaceBindingChanged` + when MCP session roots first arrive** | Fixes post-restart agent race and binding edits without full gateway restart |
-| 6 | Agent warming signal | **Meta tools** — expose pool warming state (not desktop-only) | Agents can distinguish ACL deny vs still-warming; retry search instead of misdiagnosing |
-| 7 | v1 delivery | **Full scope** — tiered + parallel + runtime warm + meta signal + CONNECTING UX + unify connect paths + setting hook | Single initiative, phased for review |
-| 8 | Lazy invoke-time connect | **Out of scope for v1** | ARCHITECTURE rejects lazy loading; routing requires pool instance today |
-| 9 | Connect path unification | **Single orchestrator** — manual `connect_all_enabled_servers` delegates to `StartupOrchestrator` | Fixes duplicate logic + ServerManager status gap on manual start |
-
----
-
-## The Model
-
-### Tiered startup
-
-```text
-Gateway spawn
-├─ HTTP listener up (immediate)
-└─ background StartupOrchestrator
-    ├─ mark_all_features_unavailable()
-    ├─ resolve_server_prefixes()
-    ├─ build_connect_plan()
-    │   ├─ hot: enabled ∩ referenced_by_any_binding_FS
-    │   └─ warm: enabled \ hot  (still connects — no defer)
-    ├─ set_connecting(hot only)          ← UX fix: no fleet-wide CONNECTING burst
-    ├─ connect_parallel(hot, max=6)
-    ├─ set_connecting(warm batch)        ← optional: per-server as each starts
-    └─ connect_parallel(warm, max=6)
-```
-
-### Hot-set resolution (new helper)
-
-```text
-for binding in binding_repo.list():
-  for fs_id in binding.feature_set_ids:
-    resolve FeatureSet members (recursive composition)
-    collect server_id from each included tool feature
-    if FeatureSetType::ServerAll → include fs.server_id
-→ hot_server_keys: HashSet<(space_id, server_id)>
-```
-
-Intersect with `installed_servers.filter(|s| s.enabled)`.
-
-### Runtime warm triggers
-
-| Event | Action |
-| ----- | ------ |
-| `WorkspaceBindingChanged` | Compute newly referenced server keys; connect enabled missing instances (same `connect_server` path, respect semaphore) |
-| MCP session roots first stored (`SessionRootsRegistry`) | Resolve binding for roots; connect hot set for that binding if not connected |
-| User `enable_server_v2` | Unchanged — immediate connect for that server |
-
-### Agent warming signal (meta tools)
-
-Extend `mcpmux_list_servers` response (or add top-level fields on read meta tools) with:
-
-```json
-{
-  "gateway_warming": true,
-  "pool": {
-    "connected": 2,
-    "connecting": 4,
-    "expected_enabled": 12,
-    "hot_pending": 1
-  }
-}
-```
-
-`gateway_warming: true` when any **hot** server is still connecting or any enabled server referenced by current session's resolved binding is not `server_available`. Agents should retry `search_tools` after warming clears.
-
----
-
-## Architecture
-
-```text
-┌─────────────────────────────────────────────────────────────────┐
-│  GatewayServer::run_with_shutdown                               │
-│    tokio::spawn → StartupOrchestrator                           │
-└────────────────────────────┬────────────────────────────────────┘
-                             │
-         ┌───────────────────┼───────────────────┐
-         ▼                   ▼                   ▼
-  ConnectPlanBuilder   ParallelConnectPool   ServerManager
-  (bindings + FS)        (Semaphore=6)         (set_connecting per tier)
-         │                   │
-         └─────────┬─────────┘
-                   ▼
-            PoolService::connect_server
-                   │
-                   ▼
-         FeatureService::discover_and_cache
-                   │
-                   ▼
-         DomainEvent → MCP list_changed
-
-Runtime hooks:
-  MCPNotifier / handler on WorkspaceBindingChanged → WarmPoolService::connect_missing
-  handler on roots stored → WarmPoolService::connect_for_binding
-```
-
-**Rejected for v1:** Skip boot connect for unbound enabled servers (user chose no defer). Invoke-time lazy connect (architecture conflict).
-
----
-
-## Files to create
-
-| File | Purpose |
-| ---- | ------- |
-| `crates/mcpmux-gateway/src/server/connect_plan.rs` | `ConnectPlanBuilder` — hot/warm tiers from bindings + enabled installs |
-| `crates/mcpmux-gateway/src/server/parallel_connect.rs` | Semaphore-limited parallel connect runner shared by startup + runtime warm |
-| `crates/mcpmux-gateway/src/services/warm_pool.rs` | Runtime warm on binding/roots; exposes `PoolWarmthSnapshot` for meta tools |
-| `tests/rust/tests/integration/gateway_warm_pool.rs` | Hot tier ordering, parallel connect mock, warmth snapshot, binding-change warm |
-
-## Files to modify
-
-| File | Change |
-| ---- | ------ |
-| [`crates/mcpmux-gateway/src/server/startup.rs`](../../crates/mcpmux-gateway/src/server/startup.rs) | Replace sequential loop with tiered parallel connect; narrow CONNECTING pre-set |
-| [`crates/mcpmux-gateway/src/server/mod.rs`](../../crates/mcpmux-gateway/src/server/mod.rs) | Wire `WarmPoolService`; pass to MCP handler / orchestrator |
-| [`crates/mcpmux-gateway/src/server/service_container.rs`](../../crates/mcpmux-gateway/src/server/service_container.rs) | DI for connect plan + warm pool services |
-| [`crates/mcpmux-gateway/ARCHITECTURE.md`](../../crates/mcpmux-gateway/ARCHITECTURE.md) | Document tiered eager connect; fix parallel claim |
-| [`apps/desktop/src-tauri/src/lib.rs`](../../apps/desktop/src-tauri/src/lib.rs) | Fix stale comment ("frontend auto-connect") |
-| [`apps/desktop/src-tauri/src/commands/gateway.rs`](../../apps/desktop/src-tauri/src/commands/gateway.rs) | `connect_all_enabled_servers` → delegate to orchestrator |
-| [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | `list_servers` warmth fields; optional hint when warming |
-| [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) | Trigger runtime warm when roots stored / after binding resolve |
-| [`crates/mcpmux-gateway/src/consumers/mcp_notifier.rs`](../../crates/mcpmux-gateway/src/consumers/mcp_notifier.rs) | Call warm pool on `WorkspaceBindingChanged` |
-| [`crates/mcpmux-gateway/src/pool/server_manager.rs`](../../crates/mcpmux-gateway/src/pool/server_manager.rs) | Delete or wire dead `startup_refresh` / document replacement |
-| [`apps/desktop/src/features/settings/SettingsPage.tsx`](../../apps/desktop/src/features/settings/SettingsPage.tsx) | (Phase 3) Optional setting: startup concurrency 4/6/8 |
-
----
-
-## Phasing
-
-### Phase 1 — Tiered plan + parallel startup
-
-**Effort:** ~1–2 days
-
-- [ ] `ConnectPlanBuilder`: load all bindings → union server_ids from FS members (+ ServerAll) → split hot/warm enabled installs
-- [ ] `ParallelConnectPool`: `FuturesUnordered` + `Semaphore(6)`; reuse existing `StartupOrchestrator::connect_server`
-- [ ] Replace sequential loop in `auto_connect_enabled_servers` with hot-then-warm parallel passes
-- [ ] CONNECTING UX: pre-set **hot tier only** (not entire fleet)
-- [ ] Unit tests: plan builder with nested FS composition, ServerAll, empty bindings → warm-only
-- [ ] Integration test: hot servers complete before warm when hot is mocked slow/fast
-
-**Outcome:** Dev restart connects binding-referenced servers (e.g. github) within seconds even when 10+ other enabled servers exist. UI shows CONNECTING for hot tier first, not 30 servers at once.
-
-### Phase 2 — Runtime warm + agent signal
-
-**Effort:** ~1–2 days
-
-- [ ] `WarmPoolService::connect_missing(keys)` — idempotent, shares semaphore with startup
-- [ ] Hook: `WorkspaceBindingChanged` → compute new hot keys → connect missing
-- [ ] Hook: session roots first stored → resolve binding → connect missing hot keys
-- [ ] `PoolWarmthSnapshot` + expose via `mcpmux_list_servers` (`gateway_warming`, counts)
-- [ ] Meta tool description updates steering agents to retry search when warming
-- [ ] Integration test: roots arrive after gateway boot → github becomes available without manual enable
-
-**Outcome:** Cursor agent session after dev restart gets invokable tools once roots land, without user running `mcpmux_enable_server`. Meta tools report warming vs ready.
-
-### Phase 3 — Unify paths, settings, cleanup
-
-**Effort:** ~0.5–1 day
-
-- [ ] `connect_all_enabled_servers` Tauri command delegates to `StartupOrchestrator` (ServerManager events consistent)
-- [ ] Optional setting `gateway.startup_concurrency` (4 / 6 / 8), default 6
-- [ ] Remove or wire dead code: `PoolService::reconnect_all_enabled`, unused `startup_refresh`
-- [ ] Update `ARCHITECTURE.md` + `lib.rs` comment
-- [ ] Manual QA: full dev restart with QA FeatureSet binding — time-to-invokable for github < 15s with 8+ enabled servers
-
-**Outcome:** One connect code path; docs match behavior; power users can tune concurrency. Planning doc reconciliation updated.
-
----
-
-## Pre-PR validation
-
-| Step | Command | Purpose |
-| ---- | ------- | ------- |
-| Rust unit + int | `cargo nextest run -p tests -- gateway_warm_pool` + workspace lib tests | Connect plan + warm hooks |
-| Full validate | `pnpm validate` | fmt, clippy, check |
-| Manual smoke | Dev restart → `mcpmux_list_servers` → `mcpmux_search_tools` until `gateway_warming: false` | Agent UX |
-
----
-
-## Out of scope
-
-| Item | Reason |
-| ---- | ------ |
-| Lazy connect on `invoke_tool` failure | Conflicts with pool-based routing; separate initiative if ever needed |
-| Defer unbound enabled servers at boot | Explicit decision: no defer — all enabled still connect (background tier) |
-| OAuth token prefetch | Deprecated no-op; RMCP refreshes per-request |
-| Connect only servers in **current** session binding at boot | Boot has no session; use hot union of all bindings instead |
-| Faster stdio package install (uvx/npm cache) | Environment concern, not gateway orchestration |
-
----
-
-## Key files referenced
-
-| File | Why |
-| ---- | --- |
-| [`crates/mcpmux-gateway/src/server/startup.rs`](../../crates/mcpmux-gateway/src/server/startup.rs) | Current sequential auto-connect + CONNECTING batch |
-| [`crates/mcpmux-gateway/src/server/mod.rs`](../../crates/mcpmux-gateway/src/server/mod.rs) | Gateway spawn + background task ordering |
-| [`crates/mcpmux-gateway/src/services/feature_set_resolver.rs`](../../crates/mcpmux-gateway/src/services/feature_set_resolver.rs) | Binding resolution at MCP request time (roots) |
-| [`crates/mcpmux-gateway/src/pool/features/resolution.rs`](../../crates/mcpmux-gateway/src/pool/features/resolution.rs) | FS → feature/server resolution (reuse for hot set) |
-| [`crates/mcpmux-gateway/src/consumers/mcp_notifier.rs`](../../crates/mcpmux-gateway/src/consumers/mcp_notifier.rs) | `WorkspaceBindingChanged` consumer today |
-| [`crates/mcpmux-gateway/ARCHITECTURE.md`](../../crates/mcpmux-gateway/ARCHITECTURE.md) | Eager pool rationale — must stay compatible |
-| [`docs/planning/meta-gateway-invoke-retest.md`](./meta-gateway-invoke-retest.md) | Live QA evidence for warm-pool pain |
-
----
-
-## Related documentation
-
-- [`docs/planning/meta-gateway-invoke.md`](./meta-gateway-invoke.md) — agent meta-tool model (primary consumer of warm pool)
-- [`docs/planning/meta-gateway-invoke-retest.md`](./meta-gateway-invoke-retest.md) — post-85113e7 QA sign-off
-- [`docs/planning/dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) — session enable semantics unchanged
-
----
-
-## Reconciliation
-
-Update this doc's **Status** and phase checkboxes as work lands. When implementation completes, add a short entry to [`meta-gateway-invoke.md`](./meta-gateway-invoke.md) **Related documentation** linking here. Run planning-doc reconciliation (status, file inventory, phase outcomes) before marking **Status: Complete**.
-
-**Decision record (May 25, 2026):** Tiered hot/warm startup with binding-union hot set; flat concurrency 6; no defer of unbound enabled; runtime warm on binding + roots; agent warming via meta tools; full three-phase delivery.
diff --git a/docs/planning/meta-gateway-invoke-qa.md b/docs/planning/meta-gateway-invoke-qa.md
deleted file mode 100644
index 5fb05255..00000000
--- a/docs/planning/meta-gateway-invoke-qa.md
+++ /dev/null
@@ -1,318 +0,0 @@
-# Meta-Gateway Invoke — Manual QA Runbook
-
-**Last Updated:** May 25, 2026  
-**Branch:** `feat/meta-gateway-invoke`  
-**Related:** [`meta-gateway-invoke.md`](./meta-gateway-invoke.md)
-
-One-session checklist for validating Phases A–C (search → schema → invoke, result shaping, FeatureSet ACL + surfaced tools).
-
----
-
-## Quick prep
-
-- [x] Rebuild/restart gateway if you haven't since the branch (`pnpm dev` or run the built app)
-- [x] Cursor → MCP → **Reload tools**
-- [x] Confirm McpMux endpoint: `http://localhost:45818/mcp`
-- [x] Have at least one OAuth server (GitHub) **installed and connected** — `QA: meta-gateway invoke` FeatureSet bound in UI (May 25)
-- [x] Workspace binding with GWorkspace (or target server) configured in UI — **not** via agent `mcpmux_bind_current_workspace`
-- [x] Optional for Phase C tests: create a FeatureSet with 1–2 GitHub tools, bind to workspace; leave surfaced off until test 8 — `QA: meta-gateway invoke` (`list_issues` + `get_me`, surfaced off, bound May 25)
-
-**FeatureSet editor controls (tests 8–9):**
-
-| Control | Role in QA |
-| ------- | ---------- |
-| **Checkbox** | Include tool in invoke ACL → search + `mcpmux_invoke_tool` |
-| **Surface** button | Promote included tool into client `tools/list` → direct one-hop call (test 9 only) |
-| **Server header toggle** | Bulk include/exclude — not Surface |
-
-After any Surface change: **Cursor → MCP → Reload tools**.
-
-**Tester:** Cursor agent (Composer)  
-**Date:** May 25, 2026  
-**McpMux version / commit:** `feat/meta-gateway-invoke` @ `5508c5e` (PR [#155](https://github.com/mcpmux/mcp-mux/pull/155))
-
----
-
-## 0. Sanity — meta-only surface
-
-**Prompt:**
-
-```
-You have McpMux meta tools only — no direct backend tools like github_*.
-
-1. Call mcpmux_list_servers and show installed servers and active/inactive status.
-2. Tell me how many tools you see in your available tool list total, and list their names.
-```
-
-| Check | Pass | Fail | Notes |
-| ----- | ---- | ---- | ----- |
-| `mcpmux_list_servers` returns installed servers | ☑ | ☐ | 34 servers returned |
-| Only **10** `mcpmux_*` tools exposed (no backend names) | ☑ | ☐ | Verified via MCP descriptor folder |
-| Backend servers show **inactive** until enabled | ☑ | ☐ | All inactive at session start |
-| Tool list count stable (~10 meta + Cursor/plugin tools) | ☑ | ☐ | No backend tools leaked |
-
----
-
-## 1. Happy path — GitHub read (Phase A)
-
-**Prompt** (swap repo if needed):
-
-```
-Use ONLY the McpMux meta workflow — do not guess backend tool names or params.
-
-Goal: list open issues in mcpmux/mcp-mux.
-
-Steps you must follow explicitly:
-1. mcpmux_list_servers — check if github is active
-2. If inactive: mcpmux_enable_server for github
-3. mcpmux_search_tools with query "list issues", server_id "github", detail_level "description"
-4. mcpmux_get_tool_schema for the best match
-5. mcpmux_invoke_tool with exact args from the schema
-
-Show each step briefly, then the first 5 issues.
-```
-
-| Check | Pass | Fail | Notes |
-| ----- | ---- | ---- | ----- |
-| Agent enabled github when inactive | ☐ | ☐ | N/A — github was `enabled_via_binding` |
-| Search before invoke (no param guessing) | ☑ | ☐ | Found `github_list_issues` via search |
-| Schema read before invoke | ☑ | ☐ | Used `owner`/`repo`/`state`/`perPage` from schema |
-| Invoke succeeded with correct param names | ☑ | ☐ | 5 open issues returned for mcpmux/mcp-mux |
-| `tools/list` still ~10 meta tools after enable | ☑ | ☐ | Still exactly 10 `mcpmux_*` tools |
-
----
-
-## 2. Fail-closed + recovery (Phase A errors)
-
-**Prompt:**
-
-```
-Try to invoke a GitHub tool WITHOUT enabling github first (disable it if needed).
-
-1. mcpmux_invoke_tool on github with tool list_issues and dummy args
-2. Show the exact error message
-3. Follow whatever it tells you to do
-4. Retry invoke successfully
-```
-
-| Check | Pass | Fail | Notes |
-| ----- | ---- | ---- | ----- |
-| Invoke denied when server inactive | ☑ | ☐ | After `mcpmux_disable_server` → `disabled_via_session` |
-| Error mentions `mcpmux_enable_server` with server_id | ☑ | ☐ | `server 'github' is disabled for this session → mcpmux_enable_server({ "server_id": "github" })` |
-| Recovery via enable → retry works | ☑ | ☐ | enable + invoke returned 3 issues |
-
----
-
-## 3. Search detail levels + compact schema (Phase A)
-
-**Prompt:**
-
-```
-On github (enabled):
-
-1. mcpmux_search_tools query "list" detail_level "name" limit 5
-2. Same query detail_level "description"
-3. Pick one tool — mcpmux_get_tool_schema compact: true
-4. Same tool — compact: false
-
-What did compact strip?
-```
-
-| Check | Pass | Fail | Notes |
-| ----- | ---- | ---- | ----- |
-| `name` level omits descriptions | ☑ | ☐ | `github_list_issues` — no `description` key |
-| `description` level includes descriptions | ☑ | ☐ | Full tool description present |
-| `compact: true` strips descriptions/examples | ☑ | ☐ | Strips **top-level** tool `description`; property descriptions in `input_schema` kept |
-| Batch schema (array of tools) works if agent tries it | ☑ | ☐ | `tools: ["github_list_issues"]` returned schemas array |
-
----
-
-## 4. Session toggle — list size unchanged (Phase A)
-
-**Prompt:**
-
-```
-1. Enable github — confirm search finds github tools
-2. Disable github via mcpmux_disable_server
-3. Search again for github tools
-4. Report tools/list count before and after — must stay the same
-```
-
-| Check | Pass | Fail | Notes |
-| ----- | ---- | ---- | ----- |
-| Search empty / no github matches when disabled | ☑ | ☐ | `total: 0`, `tools: []` after session disable |
-| Meta tool count unchanged across enable/disable | ☑ | ☐ | 10 `mcpmux_*` before and after |
-
----
-
-## 5. Pass-through without filter (Phase B)
-
-**Setup:** GWorkspace Personal bound (`taylorwilsdon.google-workspace-mcp-uvx`) or any heavy server in FeatureSet ACL.
-
-**Prompt:**
-
-```
-Find a list tool via search (e.g. GWorkspace list_drive_items), read schema, invoke WITHOUT filter.
-
-Confirm the full backend response is returned with no { returned, total, truncated } metadata.
-Paste rough char count.
-```
-
-| Check | Pass | Fail | Notes |
-| ----- | ---- | ---- | ----- |
-| Full backend response returned | ☑ | ☐ | GWorkspace `list_drive_items` `page_size: 100` → 100 items + `nextPageToken` |
-| No truncation metadata without filter | ☑ | ☐ | Plain text only; no `{ returned, total, truncated }` (opt-in filter @ `433e7bd`) |
-
----
-
-## 6. Explicit filter (Phase B)
-
-**Setup:** Same tool as test 5, or GitHub `list_issues` for JSON row truncation.
-
-**Prompt:**
-
-```
-Invoke with filter: { "max_rows": 3, "format": "summary" }
-
-For plain-text tools (GWorkspace), also try filter: { "max_bytes": 4096 }.
-
-Then fields projection if the tool returns JSON objects with id/name/title fields.
-```
-
-| Check | Pass | Fail | Notes |
-| ----- | ---- | ---- | ----- |
-| `max_rows: 3` honored (JSON tools) | ☑ | ☐ | Live `github_list_issues` → `{ returned: 3, total: 5, truncated: true, issues: [3 items] }` (5 open issues in repo) |
-| `max_bytes` honored with metadata (plain text) | ☑ | ☐ | GWorkspace `list_drive_items` `max_bytes: 4096` → `{ returned: 4110, total: 7660, truncated: true, text: "…[truncated]" }` |
-| `format: summary` applied | ☑ | ☐ | JSON: metadata envelope present; with 5 total issues and `max_rows: 3` → 3 returned (summary no-op when max_rows ≤ 5) |
-| `fields` projection limits keys per row (if tested) | ☑ | ☐ | `fields: ["id","title","number"]` → rows kept `title` + `number` only (`id` absent in GitHub payload) |
-
----
-
-## 7. Clone disambiguation (server_id filter)
-
-**Setup:** You have GWorkspace ×2 clones — enable **only one**.
-
-**Prompt:**
-
-```
-Enable ONLY taylorwilsdon.google-workspace-mcp-uvx (not the s2h clone).
-
-mcpmux_search_tools query "drive" or "list files" with server_id set explicitly.
-Confirm results are scoped to that server_id only.
-```
-
-| Check | Pass | Fail | Notes |
-| ----- | ---- | ---- | ----- |
-| `server_id` filter scopes search | ☑ | ☐ | `server_id: taylorwilsdon.google-workspace-mcp-uvx` + query `"drive"` → 24 hits, all Personal prefix |
-| Other clone's tools not in results | ☑ | ☐ | S2H clone inactive; search with `server_id: …-s2h` → `total: 0` |
-
----
-
-## 8. FeatureSet ACL — partial tool set (Phase C)
-
-**Setup:** FeatureSet with 1–2 GitHub tools **checked** (included), bound to workspace, **Surface off** on all rows.
-
-**Prompt:**
-
-```
-I bound a FeatureSet that only allows specific GitHub tools.
-
-1. mcpmux_search_tools query "github" detail_level "name"
-2. Try mcpmux_invoke_tool on a tool NOT in the FeatureSet
-3. Invoke one tool that IS included
-```
-
-| Check | Pass | Fail | Notes |
-| ----- | ---- | ---- | ----- |
-| Search only finds allowed tools | ☑ | ☐ | `query: "github"` + empty query → 2 hits: `github_get_me`, `github_list_issues` only (not 41) |
-| Invoke denied for disallowed tool | ☑ | ☐ | `create_issue` → `tool 'github_create_issue' is not invokable with current grants` |
-| Invoke succeeds for allowed tool | ☑ | ☐ | `list_issues` (3 open issues) + `get_me` (`crimsonsunset`) both succeeded |
-
----
-
-## 9. Surfaced tool promotion (Phase C)
-
-**Setup:** In FeatureSet editor, leave **`list_issues` checked** and click **Surface** (blue) on that row only; leave other included tools checked but Surface off. Save, then **Cursor → MCP → Reload tools**.
-
-**Prompt:**
-
-```
-1. List all tools available — identify mcpmux_* vs surfaced backend
-2. Call the surfaced tool directly (one hop)
-3. Call a different tool on same server via mcpmux_invoke_tool
-```
-
-| Check | Pass | Fail | Notes |
-| ----- | ---- | ---- | ----- |
-| Surfaced tool appears in client tool list | ☑ | ☐ | After Cursor MCP reload: 10 `mcpmux_*` + `github_list_issues` only; `github_get_me` not listed |
-| Surfaced tool callable without invoke wrapper | ☑ | ☐ | Direct `github_list_issues` → 2 open issues (no `use_invoke_tool` redirect) after handler fix + binding reload May 25 |
-| Non-surfaced backend still requires invoke | ☑ | ☐ | `get_me` absent from tools/list; `mcpmux_invoke_tool` → `crimsonsunset` OK |
-
----
-
-## 10. Diagnostic — list_all_tools vs search
-
-**Prompt:**
-
-```
-mcpmux_list_all_tools with server_id "github" (or one enabled server).
-Compare count to mcpmux_search_tools with query "" and same server_id.
-Explain why agents should prefer search.
-```
-
-| Check | Pass | Fail | Notes |
-| ----- | ---- | ---- | ----- |
-| `server_id` filter on list_all_tools works | ☑ | ☐ | GWorkspace Personal: 120 tools; all `server_id` matches filter |
-| Agent recommends search over full dump | ☑ | ☐ | Same count (120); search supports query/detail_level/pagination — list_all_tools dumps ~42 KB with full descriptions |
-
----
-
-## 11. End-to-end agent task (realism)
-
-**Prompt:**
-
-```
-Brief status report on mcpmux/mcp-mux repo:
-- open issue count
-- 3 most recent issue titles
-- one paragraph summary
-
-Rules: McpMux meta tools only, read schemas before invoke, note truncation if any.
-```
-
-| Check | Pass | Fail | Notes |
-| ----- | ---- | ---- | ----- |
-| Completed without backend tool name guessing | ☑ | ☐ | search `"list issues"` → `github_list_issues`; no param guessing |
-| Schema-first invoke pattern | ☑ | ☐ | `mcpmux_get_tool_schema` before invoke (`owner`, `repo`, `state`, `perPage`) |
-| Sensible output despite truncation | ☑ | ☐ | 5 open issues; filter `max_rows: 3` → 3 titles + `{ returned: 3, total: 5, truncated: true }` |
-
----
-
-## Red flags (stop and file a bug)
-
-- [ ] Backend tools (`github_*`, etc.) appear in `tools/list` without surfacing
-- [ ] Non-surfaced backend tools callable directly (bypassing `mcpmux_invoke_tool`) — surfaced one-hop is expected
-- [ ] Enable server expands `tools/list` beyond meta + surfaced
-- [ ] Search returns tools from inactive or unbound servers
-- [ ] Invoke succeeds for tools outside FeatureSet ACL
-- [ ] Invoke with explicit filter fails to truncate or return metadata
-- [ ] Opaque errors (no enable/invoke redirect hints)
-
----
-
-## Sign-off
-
-| Area | Result |
-| ---- | ------ |
-| Phase A — meta invoke core | ☑ Pass ☐ Fail |
-| Phase B — result shaping | ☑ Pass ☐ Fail |
-| Phase C — ACL + surfaced | ☑ Pass ☐ Fail ☐ Skipped |
-| Overall | ☑ Ship ☐ Block |
-
-**Blockers / issues filed:**
-
-```
-- section 6 JSON rows: manual pass May 25 after binding QA FeatureSet — github_list_issues filter verified live
-- beeper 401 on get_accounts/search_chats — auth expired; not blocking meta-gateway QA
-- test 9: surfaced direct one-hop + invoke-only non-surfaced — pass May 25 live (`github_list_issues` direct → 2 issues; `get_me` via invoke only)
-```
diff --git a/docs/planning/meta-gateway-invoke-retest.md b/docs/planning/meta-gateway-invoke-retest.md
deleted file mode 100644
index f7a21785..00000000
--- a/docs/planning/meta-gateway-invoke-retest.md
+++ /dev/null
@@ -1,209 +0,0 @@
-# Meta-Gateway Invoke — Targeted Retest (post-DX fixes)
-
-**Last Updated:** May 25, 2026  
-**Branch:** `feat/meta-gateway-invoke`  
-**Commit:** `85113e7` — `fix(gateway): improve meta-tool DX for ACL, schema batch, and max_bytes`  
-**Related:** [`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md) (full runbook), [`meta-gateway-invoke.md`](./meta-gateway-invoke.md) (spec)
-
-Paste the **Agent Prompt** block below into a fresh Cursor agent after gateway restart. Only re-runs **§3, §6, §9, §10** — core invoke QA (§0–§2, §4, §5, §7, §8, §11) already passed.
-
----
-
-## Prep (required before any tests)
-
-1. Gateway rebuilt/restarted since `85113e7` (`pnpm dev` or restart desktop app)
-2. Cursor → MCP → **Reload tools**
-3. McpMux endpoint: `http://localhost:45818/mcp` (via `user-mcpmux` / CallMcpTool)
-4. Workspace binding active with partial GitHub ACL FeatureSet (e.g. `QA: meta-gateway invoke` — ~3 GitHub tools invokable, not full catalog)
-5. Open the **bound project folder** in Cursor
-6. GitHub OAuth connected; github `enabled_via_binding` or session-enabled
-7. GWorkspace Personal clone available for §6 (bound in FeatureSet)
-
-**FeatureSet editor reminder:**
-
-| Control | Role |
-| ------- | ---- |
-| **Checkbox** | Invoke ACL (search + `mcpmux_invoke_tool`) |
-| **Surface** button | Promote into client `tools/list` for direct one-hop calls |
-| **Server header toggle** | Bulk checkbox only — not Surface |
-
-After any Surface change: **Cursor → MCP → Reload tools**.
-
----
-
-## Agent Prompt
-
-Copy everything inside the fence:
-
-```markdown
-# McpMux meta-gateway invoke — targeted retest (post-DX fixes)
-
-You are validating **4 sections only** after gateway commit `85113e7` on branch `feat/meta-gateway-invoke`. The core invoke model already passed full QA — do not re-run §0–§2, §4, §5, §7, §8, or §11 unless something blocks you.
-
-## Prep (required before any tests)
-
-1. Gateway rebuilt/restarted since `85113e7` (`pnpm dev` or restart desktop app)
-2. Cursor → MCP → **Reload tools**
-3. McpMux endpoint: `http://localhost:45818/mcp` (via `user-mcpmux` / CallMcpTool)
-4. Workspace binding active with partial GitHub ACL FeatureSet (e.g. `QA: meta-gateway invoke` — ~3 GitHub tools invokable, not full catalog)
-5. Open the **bound project folder** in Cursor
-6. GitHub OAuth connected; github `enabled_via_binding` or session-enabled
-7. GWorkspace Personal clone available for §6 (bound in FeatureSet)
-
-**FeatureSet editor reminder:**
-- **Checkbox** = invoke ACL (search + `mcpmux_invoke_tool`)
-- **Surface button** = promote into client `tools/list` for direct one-hop calls
-- After Surface toggle: **MCP Reload tools**
-
----
-
-## §3 — Batch schema (was: array returned empty)
-
-Run all three calls on github (enabled):
-
-```
-1. mcpmux_get_tool_schema({ tools: ["github_list_issues"] })
-2. mcpmux_get_tool_schema({ tools: ["github_list_issues", "github_create_issue"] })
-   — create_issue should NOT be in your ACL
-3. mcpmux_get_tool_schema({ tools: "github_list_issues" })  — string form sanity check
-```
-
-**Pass criteria:**
-- (1) `schemas.length === 1`, qualified_name = `github_list_issues`
-- (2) `schemas.length === 1` AND `missing` includes `github_create_issue` AND `message` explains use search
-- (3) string form still works
-- **Fail if:** array form returns `schemas: []` with no `missing` explanation
-
----
-
-## §6 — Filter max_bytes on plain text (was: partial — payload too small)
-
-Use GWorkspace Personal (`taylorwilsdon.google-workspace-mcp-uvx` or your bound clone):
-
-```
-1. mcpmux_search_tools query "list drive" or "list_drive_items" with server_id set
-2. mcpmux_get_tool_schema for the list tool
-3. mcpmux_invoke_tool with args that return a LARGE list:
-     { page_size: 100 }  (or equivalent from schema — do NOT use page_size: 10)
-4. mcpmux_invoke_tool same call with filter: { "max_bytes": 4096 }
-```
-
-**Pass criteria:**
-- Step 3: full backend response, **no** `{ returned, total, truncated }` envelope
-- Step 4: truncation envelope present — at minimum `{ truncated: true, total, returned, text }` (or byte metadata)
-- **Fail if:** step 4 returns full multi-KB payload with no truncation metadata when clearly >4096 bytes
-
-Also sanity-check JSON filter still works (github):
-
-```
-mcpmux_invoke_tool github list_issues with filter: { "max_rows": 3, "fields": ["title","number"] }
-```
-
-**Pass if:** `{ returned: 3, total: N, truncated: true, issues: [...] }`
-
----
-
-## §9 — Surfaced promotion (was: SKIP — no surfaced tool configured)
-
-**Setup first (human/UI step — confirm before testing):**
-- In FeatureSet editor: leave `list_issues` **checked**, click **Surface** on that row only
-- Other included tools checked but Surface **off**
-- Save → Cursor → MCP → **Reload tools**
-
-Then run:
-
-```
-1. List every tool you can call — separate mcpmux_* meta tools vs surfaced backend tools
-2. Call github_list_issues DIRECTLY (one hop, no mcpmux_invoke_tool wrapper)
-3. Call github_get_me (or another included but non-surfaced tool) via mcpmux_invoke_tool
-4. Try direct call on a non-surfaced backend tool — expect use_invoke_tool redirect
-```
-
-**Pass criteria:**
-- Exactly ~10 `mcpmux_*` + **1** surfaced backend (`github_list_issues`) in tool surface
-- Direct `github_list_issues` succeeds (no redirect error)
-- Non-surfaced tool absent from direct list but invoke succeeds
-- Direct call on non-surfaced tool → redirect to `mcpmux_invoke_tool`
-- **Fail if:** backend tools leak into list without Surface, or surfaced tool gets redirect
-
----
-
-## §10 — Diagnostic list_all_tools vs search (was: FAIL — 41 available vs 3 invokable)
-
-```
-1. mcpmux_list_all_tools({ server_id: "github" })
-2. mcpmux_search_tools({ query: "", server_id: "github", detail_level: "name" })
-3. Compare counts and explain which tool agents should use for discovery
-```
-
-**Pass criteria:**
-- `list_all_tools` response includes:
-  - `total_installed` (full github catalog, e.g. ~41)
-  - `total_invokable` (matches ACL, e.g. ~3)
-  - per-row `invokable: true/false` and `server_available` (NOT bare `available: true` for all)
-  - `hint` steering to `mcpmux_search_tools`
-- `search_tools` total === `total_invokable` (not `total_installed`)
-- Agent explicitly recommends **search** for invoke workflows, **list_all_tools** only for operator/diagnostic/FeatureSet authoring
-- **Fail if:** all 41 tools still marked invokable/available with no ACL distinction
-
----
-
-## FINAL REPORT (required — paste entire block back)
-
-```
-## Retest Summary
-Overall: SHIP | SHIP WITH ISSUES | BLOCK
-Commit tested: 85113e7 (or actual if different)
-Sections run: §3 §6 §9 §10
-
-| Section | Result | Notes |
-|---------|--------|-------|
-| §3 Batch schema | PASS/FAIL | |
-| §6 max_bytes filter | PASS/FAIL/PARTIAL | |
-| §9 Surfaced | PASS/FAIL/SKIP | |
-| §10 Diagnostic | PASS/FAIL | |
-
-## Red flags (check any observed)
-[ ] Array schema still returns empty schemas: []
-[ ] list_all_tools still marks non-ACL tools invokable
-[ ] max_bytes on large plain-text payload no truncation metadata
-[ ] Surfaced tool gets use_invoke_tool redirect
-[ ] Backend tools in tools/list without Surface
-
-## Friction log (verbatim errors / surprises)
-
-## Environment
-- github status:
-- FeatureSet ACL tool count (from search):
-- Surfaced tools in direct list:
-- total_installed / total_invokable from list_all_tools:
-```
-
-Rules: use **McpMux meta tools only** for backend calls unless §9 explicitly tests direct surfaced one-hop. Read schemas before invoke. Show exact JSON snippets for pass/fail evidence on §3, §6 step 4, and §10 counts.
-```
-
----
-
-## What changed in `85113e7`
-
-| Fix | Expected retest impact |
-| --- | ---------------------- |
-| `list_all_tools` adds `invokable`, `server_available`, counts, hint | §10 should PASS |
-| `get_tool_schema` array + JSON-encoded array + `missing` field | §3 should PASS |
-| `max_bytes` applies to JSON arrays without `max_rows` | §6 step 4 should PASS with large payload |
-
----
-
-## Sign-off (fill after agent report)
-
-| Section | Result | Notes |
-| ------- | ------ | ----- |
-| §3 Batch schema | ☑ Pass ☐ Fail | Array + string forms; `missing`/`message` on `github_create_issue` |
-| §6 max_bytes filter | ☑ Pass ☐ Fail ☐ Partial | Large github JSON truncates with `{ truncated, total, returned, text }`; JSON filter sanity pass |
-| §9 Surfaced | ☑ Pass ☐ Fail ☐ Skipped | 10 `mcpmux_*` + 1 `github_list_issues`; direct one-hop OK; non-surfaced absent from list |
-| §10 Diagnostic | ☑ Pass ☐ Fail | `total_installed: 41`, `total_invokable: 3`; per-row `invokable`/`server_available`; `hint` present |
-| **Overall** | ☑ Ship ☐ Block | Commit `85113e7` on `feat/meta-gateway-invoke` |
-
-**Tester / date:** Cursor agent / May 25, 2026
-
-**Blockers:** None. §6 used github large payload (GWorkspace not in QA FeatureSet). Dev restart + backend pool spin-up caused transient CONNECTING state before retest completed.
diff --git a/docs/planning/meta-gateway-invoke.md b/docs/planning/meta-gateway-invoke.md
deleted file mode 100644
index b75a6aff..00000000
--- a/docs/planning/meta-gateway-invoke.md
+++ /dev/null
@@ -1,366 +0,0 @@
-# Meta-Gateway Invoke (Search → Schema → Invoke)
-
-**Last Updated:** May 25, 2026
-**Status:** ✅ Phases A–C implemented and manually QA complete — ready to merge ([`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md) **Ship**)
-**Branch:** `feat/meta-gateway-invoke` (personal fork **integration tip** — see [`fork-integration.md`](./fork-integration.md))
-**Base branch:** `feat/dynamic-mcp-toggle-meta-tools` on fork; upstream contribution is topic-stacked, not `main`
-**Issue:** Fork-only; upstream megapr [#155](https://github.com/mcpmux/mcp-mux/pull/155) closed — use #154 stack for meta-tools upstream
-**Depends on:** [`dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) (session overrides + meta-tool registry); benefits from workspace bindings / FeatureSets from PR #151
-**Supersedes:** Token-budget approach in [`tool-level-session-pin.md`](./tool-level-session-pin.md) — pin filtered a bloated `tools/list`; this doc replaces that model with a fixed meta surface + invoke path. Session pin may return as an invoke ACL in Phase F (very optional, last).
-**Unblocks:** Agent-usable McpMux sessions at scale (240+ backend tools installed, ~12 tools in client context); homelab + multi-clone installs without context-window collapse
-
----
-
-## Problem
-
-Routing every AI client through one McpMux gateway endpoint solved config duplication and credential sprawl. It introduced a different bottleneck: **tool definition bloat in the client context window**.
-
-Concrete symptoms from a May 2026 Cursor session against a real install:
-
-| Symptom | Number |
-| ------- | ------ |
-| Installed servers in Space | 34 |
-| Tools in `mcpmux_list_all_tools` dump | 1,581 (~855 KB JSON) |
-| Tools exposed in Cursor session (GWorkspace × 2 clones) | 240 |
-| GitHub tools available but usable only after `mcpmux_enable_server` | 41 |
-| GitHub tool schemas in Cursor MCP descriptor folder | 0 |
-| Approximate tokens consumed by 240 tool definitions | ~30–50k |
-
-Session meta-tools ([`dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md)) let the LLM enable/disable servers mid-conversation, but **`tools/list` still advertises every backend tool** once a server is in the effective set. The LLM must guess parameter names (`issueNumber` vs `issue_number`) because schemas are not exposed through discovery APIs — only through client-side descriptor files that lag behind dynamic enablement.
-
-Competing gateways ([MikkoParkkola/mcp-gateway](https://github.com/MikkoParkkola/mcp-gateway), [abdullah1854/MCPGateway](https://github.com/abdullah1854/MCPGateway)) solve this with a **fixed meta surface** (~14–19 tools) and **progressive disclosure**: search → load schema → invoke. McpMux already has half the plumbing (`mcpmux_list_servers`, `mcpmux_enable_server`, `mcpmux_list_all_tools`) but lacks search-with-schema and a single invoke entry point.
-
-The user-facing ask (May 2026 session):
-
-> I'd rather 1–2 more calls that actually work well than hundreds of tool defs I can't call correctly.
-
-This doc defines that model for McpMux while preserving its product strengths: OS keychain credentials, Spaces, FeatureSets, per-client auth, and the server registry.
-
----
-
-## Decisions
-
-| # | Decision | Choice | Rationale |
-| - | -------- | ------ | --------- |
-| 1 | Client `tools/list` shape | **Meta tools + optional surfaced backend tools only** — never the full backend catalog | Fixes context bloat. Backend tools are invoked through `mcpmux_invoke_tool`, not registered in the client tool list (except surfaced exceptions). |
-| 2 | Discovery API | **`mcpmux_search_tools` with `detail_level`**: `name` \| `description` \| `schema`** | Replaces dumping `mcpmux_list_all_tools` for agent workflows. Supports server_id filter, pagination, and query string. Start with substring + server_id filter; TF-IDF semantic rank is Phase D optional. |
-| 3 | Schema API | **`mcpmux_get_tool_schema`** — single or batch, optional `compact: true`** | Agents must read schemas before invoke without relying on Cursor descriptor JSON files. Batch load for multi-tool workflows (e.g. issue read + comment write). |
-| 4 | Invoke API | **`mcpmux_invoke_tool({ server_id, tool, args, filter? })`** — one entry point for all backend calls | Mirrors `gateway_invoke`. Routes through existing `RoutingService::call_tool` after permission checks. Optional `filter` arg activates result shaping (Phase B). |
-| 5 | FeatureSet semantics | **FeatureSets define what is *invokable*, not what appears in `tools/list`** | Binding / grant / session-enable controls the candidate pool for search + invoke. Security boundary stays meaningful without polluting client context. |
-| 6 | Surfaced tools escape hatch | **FeatureSet members may mark tools `surfaced: true` (0–N per set)** — promoted into `tools/list` for one-hop hot paths | Default: **zero surfaced everywhere**, including built-in bundles. No bundle auto-promotes backend tools. Opt-in only via FeatureSet editor (Phase C). |
-| 7 | Invoke authorization | **Fail closed** — `invoke_tool` rejects when target server/tool is outside effective permission set | Same composition as today: `(binding_servers ∪ session_enabled) − session_disabled`, then FeatureSet member filter. Empty effective set → invoke denied with actionable error, not silent proxy. |
-| 8 | Session enable/disable | **Keep existing `mcpmux_enable_server` / `mcpmux_disable_server`** — they gate invoke/search eligibility, not `tools/list` size | Mental model unchanged: "turn on github" expands what search/invoke can reach. `tools/list` size stays ~constant. |
-| 9 | Error messages | **Actionable, bounded errors** — no dumping full available-tool lists | e.g. `"github inactive → mcpmux_enable_server('github')"`, `"unknown tool → did you mean github_list_issues?"`. Optional Levenshtein suggestions (Phase D). |
-| 10 | Rollout | **Hard cut — no legacy opt-out** | Non-surfaced backend tools never appear in `tools/list` and direct `call_tool` is rejected with a redirect to `mcpmux_invoke_tool`. **Exception:** FeatureSet members marked `surfaced: true` are promoted into `tools/list` and callable in one hop. No `expose_backend_tools_in_list` setting. Ship in one release; document migration in CHANGELOG. |
-| 11 | `mcpmux_list_all_tools` | **Keep as operator/diagnostic tool** — not the primary agent discovery path | Still useful for FeatureSet authoring and UI. Doc + descriptions steer agents to `search_tools`. Consider server_id filter arg in Phase A to avoid 855 KB dumps. |
-| 12 | Result shaping scope | **Phase B only on `invoke_tool`** — opt-in via explicit `filter`: `max_rows`, `max_bytes`, `fields`, `format: summary`. Omit filter → backend response as-is. | Agents pass `filter` when they know a tool returns large payloads. No default truncation. |
-| 13 | REST / OpenAPI capabilities | **Out of scope here** — Phase E / separate planning doc | [`web-admin-remote-access.md`](./web-admin-remote-access.md) covers admin REST, not REST→MCP capability YAML. No conflict; different layer. |
-
----
-
-## The Model
-
-### What the agent sees
-
-```text
-tools/list (fixed ~10–15 tools)
-├── mcpmux_list_servers
-├── mcpmux_enable_server / mcpmux_disable_server
-├── mcpmux_search_tools
-├── mcpmux_get_tool_schema
-├── mcpmux_invoke_tool
-├── mcpmux_list_feature_sets / mcpmux_create_feature_set / mcpmux_bind_current_workspace
-├── mcpmux_list_all_tools          (diagnostic — not primary discovery)
-└── [0–N surfaced backend tools]   (optional, from FeatureSet)
-```
-
-### Agent workflow (GitHub read example)
-
-```text
-1. mcpmux_list_servers                          → github: inactive
-2. mcpmux_enable_server({ server_id: "github" })
-3. mcpmux_search_tools({
-     query: "list issues",
-     server_id: "github",
-     detail_level: "description"
-   })
-4. mcpmux_get_tool_schema({ tools: ["github_list_issues"] })
-5. mcpmux_invoke_tool({
-     server_id: "github",
-     tool: "list_issues",
-     args: { owner: "mcpmux", repo: "mcp-mux", state: "OPEN" }
-   })
-```
-
-Three to four meta calls before the backend call — predictable schemas, bounded context.
-
-### Permission composition (unchanged server layer, new tool-list layer)
-
-```text
-1. (space, feature_set_ids) ← FeatureSetResolverService
-2. binding_servers          ← servers_for(space, feature_set_ids)
-3. session_on/off           ← SessionOverrideRegistry
-4. effective_servers        ← (binding ∪ session_on) − session_off
-5. invokable_tools          ← Tool features for effective_servers ∩ FeatureSet members
-6. tools/list               ← meta_tools ∪ surfaced(invokable_tools)
-7. search_tools / invoke    ← scoped to invokable_tools only
-```
-
-Prompts and resources: unchanged — still materialized per grants. Invoke model is tool-specific.
-
-### What this is NOT
-
-- Not replacing the desktop app, registry, or Spaces model
-- Not removing FeatureSets — they become invoke ACLs
-- Not implementing abdullah's full 15-layer optimization stack in v1
-- Not REST capability YAML / OpenAPI import (separate future doc)
-
----
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│  Cursor / Claude / VS Code                                      │
-│  tools/list → ~12 meta tools (+ optional surfaced)              │
-└────────────────────────────┬────────────────────────────────────┘
-                             │
-                             ▼
-┌─────────────────────────────────────────────────────────────────┐
-│  McpMux Gateway (:45818)                                        │
-│  ┌───────────────────────────────────────────────────────────┐  │
-│  │ MetaToolRegistry                                          │  │
-│  │  search_tools → ToolDiscoveryService (index from Space)   │  │
-│  │  get_tool_schema → ServerFeature.input_schema             │  │
-│  │  invoke_tool → RoutingService::call_tool (existing path)  │  │
-│  └───────────────────────────────────────────────────────────┘  │
-│  ┌───────────────────────────────────────────────────────────┐  │
-│  │ FeatureService::get_tools_for_grants                      │  │
-│  │  → meta tools + surfaced only (hard cut — no backend list)  │  │
-│  └───────────────────────────────────────────────────────────┘  │
-└────────────────────────────┬────────────────────────────────────┘
-                             │
-         ┌───────────────────┼───────────────────┐
-         ▼                   ▼                   ▼
-    github (stdio)    google-workspace     posthog-personal
-```
-
-**New components:**
-
-- `ToolDiscoveryService` — in-memory index built from `server_feature_repo::list_for_space`, rebuilt on feature change events. Powers search + schema lookup.
-- `InvokeToolTool` — validates invokable set, forwards to `RoutingService::call_tool`, maps errors to actionable messages.
-
-**Chokepoints (existing):**
-
-- `FeatureService::get_tools_for_grants` — change what gets advertised in `tools/list`
-- `RoutingService::call_tool` — reuse for invoke; add invokable-set check if not already covered by grant lookup
-- `MetaToolRegistry` — register three new tools
-
----
-
-## Files to create
-
-| File | Purpose | Status |
-| ---- | ------- | ------ |
-| `crates/mcpmux-gateway/src/services/tool_discovery.rs` | Index + search + schema lookup over Space tool features | ✅ Done |
-| `crates/mcpmux-gateway/src/services/meta_tools/invoke.rs` | `InvokeToolTool` impl — permission check, routing, error mapping, result shaping | ✅ Done |
-| `crates/mcpmux-gateway/src/services/meta_tools/invoke_backend.rs` | `InvokeToolBackend` trait + `RoutingService` adapter for testable invoke routing | ✅ Done |
-| `tests/rust/src/canned_invoke_backend.rs` | Canned backend for filter e2e integration tests | ✅ Done |
-| `tests/rust/tests/integration/meta_gateway_invoke.rs` | Search, schema, invoke, permission deny, surfaced tools, filter shaping, e2e filter via canned backend | ✅ Done (16 tests) |
-| `docs/planning/meta-gateway-invoke-qa.md` | Manual QA runbook for Phases A–C | ✅ Done |
-| `docs/planning/meta-gateway-invoke.md` | This doc | ✅ Done |
-
-## Files to modify
-
-| File | Change | Status |
-| ---- | ------ | ------ |
-| [`crates/mcpmux-gateway/src/services/mod.rs`](../../crates/mcpmux-gateway/src/services/mod.rs) | `pub mod tool_discovery;` | ✅ Done |
-| [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | `SearchToolsTool`, `GetToolSchemaTool`; extend `ListAllToolsTool` with optional `server_id` filter | ✅ Done |
-| [`crates/mcpmux-gateway/src/services/meta_tools/mod.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/mod.rs) | Register new tools; wire `ToolDiscoveryService` + `InvokeToolBackend` into `MetaToolContext` | ✅ Done |
-| [`crates/mcpmux-gateway/src/services/meta_tools/registry.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/registry.rs) | Extend `MetaToolContext` with discovery + invoke backend handles | ✅ Done |
-| [`crates/mcpmux-gateway/src/pool/features/facade.rs`](../../crates/mcpmux-gateway/src/pool/features/facade.rs) | Split into `get_advertised_tools_for_grants` vs `get_invokable_tools_for_grants` | ✅ Done |
-| [`crates/mcpmux-gateway/src/pool/features/resolution.rs`](../../crates/mcpmux-gateway/src/pool/features/resolution.rs) | `resolve_surfaced_feature_ids` for surfaced promotion | ✅ Done |
-| [`crates/mcpmux-gateway/src/pool/routing.rs`](../../crates/mcpmux-gateway/src/pool/routing.rs) | `format_direct_call_redirect`; actionable invoke errors | ✅ Done |
-| [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) | `tools/list` uses advertised set only; non-surfaced direct `call_tool` rejected with invoke redirect; surfaced tools allowed one-hop; `ensure_roots_probed` before routing in `call_tool` | ✅ Done |
-| [`crates/mcpmux-core/src/domain/feature_set.rs`](../../crates/mcpmux-core/src/domain/feature_set.rs) | `surfaced: bool` on `FeatureSetMember` | ✅ Done |
-| [`apps/desktop/src/features/featuresets/FeatureSetPanel.tsx`](../../apps/desktop/src/features/featuresets/FeatureSetPanel.tsx) | Per-tool "Surface in client" toggle + explainer tooltip | ✅ Done |
-| [`apps/desktop/src/features/settings/SettingsPage.tsx`](../../apps/desktop/src/features/settings/SettingsPage.tsx) | Meta-tools copy for search → schema → invoke workflow | ✅ Done |
-| [`README.md`](../../README.md) | Agent-facing search → schema → invoke flow; checkbox vs Surface in Feature Sets | ✅ Done |
-| [`docs/guide/feature-sets.mdx`](../guide/feature-sets.mdx) | Included vs Surface editor explainer; invoke ACL semantics | ✅ Done |
-
----
-
-## Phasing
-
-### Phase A — Meta invoke core
-
-**Effort:** ~3–4 days  
-**Status:** ✅ Implemented — manual QA sections 0–4 pass ([`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md))
-
-- [x] `ToolDiscoveryService` — build index from Space features; search by query + optional `server_id`; return matches at `detail_level`
-- [x] `mcpmux_search_tools` meta tool — pagination (`limit`, `cursor`), `detail_level` enum
-- [x] `mcpmux_get_tool_schema` — single + batch; `compact` strips descriptions/examples
-- [x] `mcpmux_invoke_tool` — `{ server_id, tool, args }`; delegates to `RoutingService::call_tool`; fail closed on permission miss
-- [x] `FeatureService` split: **advertised** = meta tools + surfaced only (hard cut — no backend tools in list)
-- [x] Handler rejects **non-surfaced** direct backend `call_tool` — redirect to `mcpmux_invoke_tool`; surfaced tools pass through
-- [x] Actionable error mapping: inactive server, unknown tool, permission denied, param validation passthrough from backend
-- [x] Optional `server_id` filter on `mcpmux_list_all_tools`
-- [x] Integration tests: GitHub read path (enable → search → schema → invoke); deny when server inactive; non-surfaced direct call rejected
-
-**Outcome:** Cursor session shows **10** `mcpmux_*` tools (verified May 25, 2026). Agent completes `github_list_issues` on `mcpmux/mcp-mux` via search → schema → invoke with zero param guessing.
-
-### Phase B — Result shaping on invoke
-
-**Effort:** ~2 days  
-**Status:** ✅ Implemented — manual QA section 6 pass (May 25)
-
-- [x] Extend `mcpmux_invoke_tool` args with optional `filter: { max_rows?, max_bytes?, fields?, format? }`
-- [x] Post-process JSON/text results in gateway when `filter` is provided
-- [x] Opt-in truncation only — omit `filter` to return backend response unchanged (May 25 design revision)
-- [x] Unit tests (13): top-level arrays, nested `issues`/`items` keys, JSON-in-text blocks, `structured_content`, `fields`, `format: summary` vs `full`, `parse_invoke_filter` edge cases
-- [x] Integration tests: pure-fn filter shaping + `invoke_tool_applies_filter_end_to_end` via `CannedInvokeBackend`
-
-**Outcome:** Agents pass `filter` on known-heavy tools (GWorkspace drive lists, GitHub issues, PostHog events). Plain-text and JSON backends both supported when filter is explicit.
-
-#### Filter behavior reference
-
-| Payload shape | Applicable filter keys | Behavior |
-| ------------- | ---------------------- | -------- |
-| Plain text (`content[].text` non-JSON) | `max_bytes` only | Returns `{ returned, total, truncated, text }` envelope when over limit. `max_rows` / `fields` / `format` ignored. |
-| Top-level JSON array | `max_rows`, `fields`, `format`, `max_bytes` | When `total > max_rows`: `{ returned, total, truncated, items: [...] }` |
-| JSON object with heavy array key (`issues`, `items`, `results`, …) | same | Metadata merged at object top-level; array under original key name |
-| JSON serialized inside text content block | same | Parsed then shaped; re-serialized into `text` |
-| `structured_content` on `CallToolResult` | same | Shaped independently via `apply_invoke_result_filter` |
-
-**`format` semantics (requires `max_rows`):**
-
-- `full` — sample size = `max_rows`
-- `summary` — sample size = `min(max_rows, 5)` (no effect when `max_rows ≤ 5`)
-
-**Envelope fields:** `returned` (rows or bytes after truncation), `total` (pre-truncation count/bytes), `truncated: true`, plus `items`/`issues`/… or `text`.
-
-### Phase C — FeatureSet as invoke ACL + surfaced tools
-
-**Effort:** ~3 days  
-**Status:** ✅ Implemented — manual QA sections 8–9 pass ([`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md))
-
-- [x] FeatureSet member model: tools invokable by default when server in set; optional `surfaced: true` promotes into `tools/list`
-- [x] Search + invoke respect FeatureSet member filter (not just server-all)
-- [x] Workspaces UI: per-tool "Surface in client" toggle in FeatureSet editor (`FeatureSetPanel.tsx`)
-  - **Checkbox** = invoke ACL member (search + `mcpmux_invoke_tool`)
-  - **Surface button** = promote that included tool into client `tools/list` for direct one-hop calls
-  - User-facing explainer: [`docs/guide/feature-sets.mdx`](../guide/feature-sets.mdx#included-vs-surface-featureset-editor)
-- [x] `mcpmux_create_feature_set` accepts optional `surfaced_tools[]` (subset of `tool_qualified_names`; UI path also available)
-- [x] Integration tests: partial FeatureSet binding limits search; surfaced vs invokable gate; advertised set promotion
-
-### Phase D — Advanced optimizations (defer)
-
-**Effort:** TBD
-
-- [ ] Levenshtein "did you mean?" on invoke errors
-- [ ] TF-IDF / semantic rank in search
-- [ ] Delta responses, auto-summarize, parallel invoke batching
-- [ ] Sandboxed code execution (abdullah-style `gateway_execute_code`)
-
-**Outcome:** Incremental token/latency wins for power users. Each item is independently shippable.
-
-### Phase E — REST capabilities (separate initiative)
-
-**Effort:** TBD — requires its own planning doc
-
-- [ ] OpenAPI → capability definition in registry or gateway-local YAML
-- [ ] Invoke through same `mcpmux_invoke_tool` path
-
-**Outcome:** Non-MCP HTTP APIs join the gateway without a separate MCP server process. Not blocked by Phases A–D.
-
-### Phase F — Session pin as invoke ACL (very optional)
-
-**Effort:** ~1 day — **only if** a concrete use case remains after Phases A–C
-
-- [ ] Re-scope [`tool-level-session-pin.md`](./tool-level-session-pin.md): `mcpmux_pin_this_session` restricts **invokable set** for the session, not `tools/list` membership
-- [ ] Ship only on evidence that search + invoke + FeatureSet ACL is insufficient (e.g. agent repeatedly invokes disallowed tools and needs a tighter session knob)
-
-**Outcome:** Temporary invoke ACL ("only these 12 tools invokable for this session") without re-expanding `tools/list`. Skip entirely if Phase A–C covers the GWorkspace clone case.
-
----
-
-## Pre-PR validation
-
-| Step | Command | Purpose |
-| ---- | ------- | ------- |
-| Full validate | `pnpm validate` | fmt, clippy, check, eslint, typecheck |
-| Rust tests | `pnpm test:rust` | unit + `meta_gateway_invoke.rs` integration |
-| TS tests | `pnpm test:ts` | vitest |
-| Manual smoke | Cursor against live gateway — full runbook sections 0–11 | Agent UX verification — ✅ complete May 25 |
-
----
-
-## Out of scope
-
-| Item | Reason |
-| ---- | ------ |
-| [`web-admin-remote-access.md`](./web-admin-remote-access.md) | Remote admin UI — parallel track, no overlap |
-| Full abdullah 15-layer stack | Phase D picks winners after A+B prove value |
-| Removing `mcpmux_enable_server` | Still gates invoke eligibility; still needed when server not in binding |
-| Auto-enable server on failed invoke | Silent enable defeats audit trail — rejected in dynamic-toggle doc |
-| Tool-poisoning validator / SHA-256 pinning | MikkoParkkola feature; valuable follow-up for registry trust, not invoke core |
-| Cursor descriptor JSON sync | Client-side concern; schema-on-demand makes it non-blocking |
-
----
-
-## Key files referenced
-
-| File | Why |
-| ---- | --- |
-| [`crates/mcpmux-gateway/src/pool/features/facade.rs`](../../crates/mcpmux-gateway/src/pool/features/facade.rs) | Materialization chokepoint — must split advertised vs invokable |
-| [`crates/mcpmux-gateway/src/pool/routing.rs`](../../crates/mcpmux-gateway/src/pool/routing.rs) | Existing `call_tool` path invoke reuses |
-| [`crates/mcpmux-gateway/src/services/meta_tools/invoke.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/invoke.rs) | Invoke meta tool + result shaping |
-| [`crates/mcpmux-gateway/src/services/meta_tools/invoke_backend.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/invoke_backend.rs) | Pluggable invoke routing trait |
-| [`tests/rust/src/canned_invoke_backend.rs`](../../tests/rust/src/canned_invoke_backend.rs) | Test double for filter e2e |
-| [`crates/mcpmux-gateway/src/mcp/handler.rs`](../../crates/mcpmux-gateway/src/mcp/handler.rs) | `tools/list` + `call_tool` — advertised set, surfaced one-hop, invoke redirect for non-surfaced |
-| [`docs/planning/dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) | Session enable/disable — kept, semantics updated |
-| [`docs/planning/tool-level-session-pin.md`](./tool-level-session-pin.md) | Superseded for token budget; Phase F very optional rework |
-
----
-
-## Related documentation
-
-- [`docs/planning/dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) — session overrides (complete)
-- [`docs/planning/tool-level-session-pin.md`](./tool-level-session-pin.md) — superseded; Phase F may revive as invoke ACL only if needed
-- [`docs/planning/server-account-clones.md`](./server-account-clones.md) — origin of 240-tool bloat evidence
-- [`docs/planning/web-admin-remote-access.md`](./web-admin-remote-access.md) — remote operator UI (orthogonal)
-- [MikkoParkkola/mcp-gateway](https://github.com/MikkoParkkola/mcp-gateway) — `gateway_search_tools` / `gateway_invoke` reference
-- [abdullah1854/MCPGateway](https://github.com/abdullah1854/MCPGateway) — `gateway_get_tool_schema` / result filtering reference
-
----
-
-## Reconciliation
-
-This doc is the source of truth for the meta-gateway invoke model. Phases A–C are implemented on `feat/meta-gateway-invoke` and manually QA complete ([`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md) — **Ship**). Mark [`tool-level-session-pin.md`](./tool-level-session-pin.md) **Status** as *Superseded* when this branch merges to main.
-
-**Decision record (May 25, 2026):** Hard cut to invoke-only for non-surfaced backend tools — no legacy full-catalog `tools/list`. Surfaced tools default zero everywhere (bundles included); opt-in per FeatureSet member for one-hop hot paths. FeatureSets redefine as invoke ACL + optional surfaced promotion. Session pin deferred to Phase F (very optional, last). Competitor analysis (MikkoParkkola + abdullah1854) informed Phase A–B scope; REST capabilities in Phase E / separate doc.
-
-**Handler fix (May 25, 2026):** `call_tool` probes workspace roots before routing (matches `list_tools`) and allows direct calls when the tool is in `get_advertised_tools_for_grants` (surfaced). Non-surfaced backend names still get `use_invoke_tool` redirect.
-
-**Design revision (May 25, 2026):** Removed default smart truncation — `filter` is opt-in only. Rationale: plain-text MCP backends (GWorkspace) don't map cleanly to JSON row truncation; agents should explicitly bound payloads when needed.
-
-**QA ergonomics (May 25, 2026):** Bind FeatureSets in Workspaces UI before agent QA — session enable alone is insufficient without binding ACL. Do **not** call `mcpmux_bind_current_workspace` during routine QA (triggers Space-wide approval modal). Reload MCP tools after UI binding or Surface changes.
-
-**Test coverage (May 25, 2026):** Phase B filter shaping — 13 unit tests in `invoke.rs`, 16 integration tests in `meta_gateway_invoke.rs`, manual QA sections 0–11 pass on live gateway.
-
-**Manual QA progress (May 25, 2026):** Overall **Ship**. Full section results in [`meta-gateway-invoke-qa.md`](./meta-gateway-invoke-qa.md). Highlights:
-
-| QA section | Result | Notes |
-| ---------- | ------ | ----- |
-| 0 — Sanity (meta-only surface) | ✅ Pass | 10 `mcpmux_*` tools; 34 servers listed; all inactive until enabled |
-| 1 — Happy path (GitHub read) | ✅ Pass | search → schema → invoke returned 5 open issues; enable step N/A (`enabled_via_binding`) |
-| 2 — Fail-closed + recovery | ✅ Pass | Session disable → actionable error → enable → retry |
-| 3 — Search detail levels + compact schema | ✅ Pass | compact omits top-level description only |
-| 4 — Session toggle (list size unchanged) | ✅ Pass | search empty when disabled; 10 meta tools stable |
-| 5 — Pass-through without filter (Phase B) | ✅ Pass | GWorkspace `list_drive_items`: 100 items, no metadata envelope |
-| 6 — Explicit filter (Phase B) | ✅ Pass | Plain-text `max_bytes` + live `github_list_issues` JSON filter |
-| 7 — Clone disambiguation | ✅ Pass | Personal vs S2H clone scoped correctly |
-| 8 — FeatureSet ACL (Phase C) | ✅ Pass | Partial GitHub tool set; invoke deny outside ACL |
-| 9 — Surfaced promotion (Phase C) | ✅ Pass | `github_list_issues` in tools/list + direct one-hop; `get_me` invoke-only |
-| 10 — Diagnostic list vs search | ✅ Pass | 120 tools both paths for GWorkspace Personal |
-| 11 — End-to-end agent task | ✅ Pass | Meta-only workflow; schema-first; filter truncation metadata |
diff --git a/docs/planning/server-account-clones.md b/docs/planning/server-account-clones.md
deleted file mode 100644
index 603fab2b..00000000
--- a/docs/planning/server-account-clones.md
+++ /dev/null
@@ -1,270 +0,0 @@
-# Server Account Clones (UI-Assisted Multi-Account)
-
-**Last Updated:** May 23, 2026
-**Status:** Complete — Phases 1–4 shipped; Phase 5 (first-class instances) optional/deferred
-**Branch:** `feat/server-account-clones` (merged or ready to merge)
-**Base branch:** `main`
-**Issue:** TBD — file after planning review
-**Depends on:** None (orthogonal to session meta-tools; benefits from but does not require PR #154)
-**Unblocks:** Personal MCP migration (`jsg-tech-check/docs/setup/mcpmux-server-migration.md`) — Gmail, Sheets, PostHog ×2, Firebase ×4, and other single-account stdio servers
-
----
-
-## Problem
-
-McpMux installs servers once per `(space_id, server_id)` — enforced by `UNIQUE(space_id, server_id)` on `installed_servers`, `credentials`, and `outbound_oauth_clients`. That model works when one Space maps to one account (Personal vs S2H vs GAIT), but breaks down when a user needs **two accounts for the same MCP in the same Space**:
-
-| Server type | Example need | Current workaround |
-| ----------- | ------------ | ------------------ |
-| Native multi-account | Google Workspace (`user_google_email` per call) | One install — works today |
-| Single-account stdio | PostHog personal + work in Personal Space | Hand-edit user space JSON with suffixed IDs (`posthog-personal`, `posthog-work`) |
-| Single-account OAuth HTTP | Two Notion workspaces in one Space | Same JSON hack or split Spaces |
-| Env-at-startup servers | Firebase ×4 projects | Four manual JSON entries with different env paths |
-
-The workaround **works** — custom entries with unique IDs get separate processes, credential rows, and tool prefixes — but it is undiscoverable, error-prone, and regresses the "click Install" UX. Users migrating from a 40-entry `~/.cursor/mcp.json` hit this immediately.
-
-Spaces remain the canonical answer for **context-level** separation (work vs personal repos). This feature targets **account-level** duplication inside a Space when context splitting is wrong or insufficient.
-
----
-
-## Decisions
-
-| # | Decision | Choice | Rationale |
-| - | -------- | ------ | --------- |
-| 1 | Primary approach | **Option 2: UI-assisted clone** — new `server_id` + `manual_entry`, no schema migration | Highest value-to-effort. Removes JSON-editing pain without touching OAuth/credential layer mid-migration. |
-| 2 | Schema change | **Defer Option 3** (`instance_label` column) to optional Phase 5 | Architecturally cleaner long-term, but 2–3 weeks of migration risk across 5+ tables. Ship clones first; revisit when migration volume justifies it. |
-| 3 | Clone identity | **`{base_server_id}-{suffix}`** where suffix is user-chosen (default suggestions: `work`, `personal`, `prod`) | Satisfies unique constraint. Hyphen suffix only — underscores are stripped by `normalize_server_id` and reserved as the tool-name delimiter. |
-| 4 | Definition source | **Copy `cached_definition` from source install** into clone at creation time | Clone is self-contained for offline/gateway startup. Registry updates do not auto-propagate — acceptable tradeoff for v1; document in UI. |
-| 5 | Prefix / alias | **Auto-set alias = suffix** (e.g. `posthog-work` → tools prefixed `posthog-work_*`) | Reuses `PrefixCacheService` first-come assignment. User can override alias in configure step. |
-| 6 | Credentials | **Never copy secrets** — clone starts with empty `input_values` / no OAuth; user configures fresh | Prevents accidental credential sharing. Clone wizard opens configure flow immediately after create. |
-| 7 | Source tracking | **`InstallationSource::ManualEntry`** + optional `cloned_from: Option<String>` metadata on `InstalledServer` | Distinguishes registry installs from clones in UI (`SourceBadge`). `cloned_from` is display-only in v1 — not a FK. |
-| 8 | Registry dedup UX | **"Add another account" disabled when source is already a clone-of-clone** (max depth 1) or when suffix collision detected | Prevents unbounded ID sprawl (`posthog-work-work-work`). Clones clone from registry/original only. |
-| 9 | Spaces unchanged | **No change to Space model** — clone is per-Space like any install | Work/personal split via Spaces stays documented as primary pattern; clones are the escape hatch. |
-
----
-
-## The Model
-
-### What a clone is
-
-A clone is a **new `InstalledServer` row** in the same Space as the source, with:
-
-```text
-InstalledServer {
-  server_id:     "{base_id}-{suffix}",     // e.g. "posthog-work"
-  server_name:   "{display} ({suffix})",   // e.g. "PostHog (work)"
-  cached_definition: <copy from source>,
-  input_values:  {},                       // empty — user fills in configure step
-  source:        ManualEntry,
-  cloned_from:   Some("{base_id}"),        // new optional field, v1 display-only
-  enabled:       false,                    // same default as registry install
-}
-```
-
-Prefix resolution treats the clone as an independent server. Tool names become `{alias}_{tool}` (e.g. `posthog-work_capture_event`).
-
-### What a clone is NOT
-
-- Not a second OAuth session on the same `server_id` row
-- Not a runtime credential swap (stdio env is fixed at process spawn)
-- Not a registry duplicate — the registry still has one definition for `posthog`; clones are local installs
-
-### Composition with existing patterns
-
-```text
-Multi-account need?
-├─ MCP has per-call account param (Google Workspace)
-│   └─ ONE install — no clone needed
-├─ Accounts map to repo context (Personal / S2H / GAIT)
-│   └─ Spaces — no clone needed
-└─ Two+ accounts in SAME Space, single-account MCP
-    └─ Clone via "Add another account" (this feature)
-```
-
----
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│  My Servers UI                                                  │
-│                                                                 │
-│  [PostHog ▼]  Connected                                       │
-│    ├─ Configure / Logs / …                                      │
-│    └─ "Add another account…"  ─────────────────────┐            │
-└────────────────────────────────────────────────────│────────────┘
-                                                     │
-                                                     ▼
-                              ┌──────────────────────────────────┐
-                              │  CloneAccountModal                 │
-                              │  • suffix input (work/personal/…)  │
-                              │  • alias preview (posthog-work)    │
-                              │  • collision check                 │
-                              └──────────────────────────────────┘
-                                                     │
-                                                     ▼
-                              ┌──────────────────────────────────┐
-                              │  ServerAppService::clone_server  │
-                              │  1. validate unique server_id    │
-                              │  2. copy cached_definition       │
-                              │  3. set alias in definition JSON │
-                              │  4. install as ManualEntry       │
-                              │  5. emit ServerInstalled         │
-                              └──────────────────────────────────┘
-                                                     │
-                    ┌────────────────────────────────┴───────────────┐
-                    ▼                                                ▼
-         installed_servers row                          credentials row(s)
-         (new server_id)                                (empty until configure)
-                    │
-                    ▼
-         PrefixCache assigns alias on first enable/connect
-                    │
-                    ▼
-         Separate stdio process / OAuth flow with clone's creds
-```
-
-- **No gateway routing changes** — clone is a distinct `server_id`; existing prefix cache + routing already handle multiple servers in one Space.
-- **FeatureSets** see clones as separate servers — user adds `posthog-work` to a FeatureSet independently. Future Option 3 could add "all instances of server X" grouping.
-- **Meta tools** (`mcpmux_enable_server`) already accept any `server_id` string — clones work with session enable once the user knows the suffixed ID. Phase 3 adds optional `cloned_from` hint in `mcpmux_list_servers` response.
-
----
-
-## Files to create
-
-| File | Purpose |
-| ---- | ------- |
-| `apps/desktop/src/features/servers/CloneAccountModal.tsx` | Suffix input, alias preview, collision feedback, submit → Tauri command |
-| `apps/desktop/src/lib/api/serverClone.ts` | TS wrappers: `cloneServer`, `suggestCloneSuffix`, `isCloneIdAvailable` |
-| `apps/desktop/src-tauri/src/commands/server_clone.rs` | Tauri commands delegating to `ServerAppService::clone_server` |
-| `tests/rust/tests/integration/server_clone.rs` | Clone creates distinct install, empty creds, unique prefix, collision rejection |
-| `docs/planning/server-account-clones.md` | This doc |
-
-## Files to modify
-
-| File | Change |
-| ---- | ------ |
-| [`crates/mcpmux-core/src/domain/installed_server.rs`](../../crates/mcpmux-core/src/domain/installed_server.rs) | Add optional `cloned_from: Option<String>`. Builder `with_cloned_from`. |
-| [`crates/mcpmux-core/src/application/server.rs`](../../crates/mcpmux-core/src/application/server.rs) | `clone_server(space_id, source_server_id, suffix, alias_override?)` — copy definition, derive new ID, install as `ManualEntry`. |
-| [`crates/mcpmux-storage/src/repositories/installed_server_repository.rs`](../../crates/mcpmux-storage/src/repositories/installed_server_repository.rs) | Serialize/deserialize `cloned_from` (new nullable column or JSON in existing row — see Phase 1). |
-| [`crates/mcpmux-storage/src/migrations/`](../../crates/mcpmux-storage/src/migrations/) | New migration: `cloned_from TEXT` nullable on `installed_servers`. |
-| [`apps/desktop/src/features/servers/ServerActionMenu.tsx`](../../apps/desktop/src/features/servers/ServerActionMenu.tsx) | Add "Add another account…" action; hidden for clones-of-clones. |
-| [`apps/desktop/src/features/servers/ServersPage.tsx`](../../apps/desktop/src/features/servers/ServersPage.tsx) | Wire modal, group clones visually under source (optional Phase 2 polish). |
-| [`apps/desktop/src/components/SourceBadge.tsx`](../../apps/desktop/src/components/SourceBadge.tsx) | Badge variant for cloned servers ("Clone of posthog"). |
-| [`apps/desktop/src-tauri/src/lib.rs`](../../apps/desktop/src-tauri/src/lib.rs) | Register `clone_server`, `suggest_clone_suffix`, `is_clone_id_available` commands. |
-| [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | (Phase 3) Optional `cloned_from` field in `mcpmux_list_servers` payload. |
-| [`docs/guide/servers.mdx`](../../docs/guide/servers.mdx) | Document multi-account patterns: Spaces vs native params vs clones. |
-
----
-
-## Phasing
-
-### Phase 1 — Core clone API + storage
-
-**Effort:** ~1 day
-
-- [x] Migration: `cloned_from TEXT NULL` on `installed_servers`
-- [x] `InstalledServer.cloned_from` field + repo round-trip
-- [x] `ServerAppService::clone_server`:
-  - Load source install + definition from `cached_definition`
-  - Derive `new_id = "{base}-{suffix}"` using same normalization as `UserServerEntry::normalize_server_id`
-  - Reject if `(space_id, new_id)` exists or source is missing
-  - Patch definition `alias` to suffix (or user override)
-  - Install via existing `install()` path with `ManualEntry` + `with_cloned_from(source_id)`
-- [x] Unit tests: happy path, collision, missing source, suffix normalization (no underscores)
-- [x] Tauri command `clone_server(space_id, source_server_id, suffix, alias?)`
-
-**Outcome:** `clone_server` from Tauri creates a disabled `posthog-work` install with copied definition, empty creds, and `cloned_from = "posthog"`. Verifiable via `list_installed_servers` and SQLite inspection. No UI yet.
-
-### Phase 2 — Clone wizard UI
-
-**Effort:** ~1 day
-
-- [x] `CloneAccountModal` — suffix field with suggestions (`work`, `personal`, `prod`, `staging`), live alias preview, inline collision error
-- [x] `ServerActionMenu` → "Add another account…" on registry and manual installs (not on clones)
-- [x] Post-clone flow: open existing `ConfigEditorModal` for credential entry before enable
-- [x] `SourceBadge` shows clone lineage
-- [ ] Optional: collapsed "Accounts" group on `ServersPage` when `cloned_from` matches same base (visual only, no schema)
-
-**Outcome:** User clicks "Add another account" on PostHog, enters suffix `work`, gets `posthog-work` card in My Servers, configures API key, enables — tools appear as `posthog-work_*` in gateway. No JSON editing.
-
-### Phase 3 — Meta-tool + docs surfacing
-
-**Effort:** ~0.5 day
-
-- [x] `mcpmux_list_servers` returns optional `cloned_from` for clone rows
-- [x] `docs/guide/servers.mdx` section: "Multiple accounts" — decision tree (Spaces / native param / clone)
-- [ ] Migration doc update in `jsg-tech-check` with concrete clone targets (PostHog, Gmail, Sheets, Firebase) — out of repo; deferred
-
-**Outcome:** LLM manifest shows clone lineage. Docs explain when to clone vs use a Space. Migration checklist has explicit suffix naming convention.
-
-### Phase 4 — Validation + edge cases
-
-**Effort:** ~0.5 day
-
-- [x] Integration test: two clones in one Space, distinct prefixes, both connect with different env
-- [x] Uninstall clone does not affect source
-- [x] Uninstall source warns if clones exist (list dependents, offer bulk uninstall)
-- [x] Prefix collision: two different registry servers cannot claim same alias (existing behavior — verify clones don't break it)
-- [x] `pnpm validate` + targeted Rust/TS tests
-
-**Outcome:** Clone lifecycle is safe through install → configure → enable → uninstall. Source/uninstall warnings prevent orphaned expectations.
-
-### Phase 5 — (Optional) First-class instances (Option 3)
-
-**Effort:** ~2–3 weeks — **defer until clone UX proves demand**
-
-- [ ] Schema: replace `UNIQUE(space_id, server_id)` with `UNIQUE(space_id, server_id, instance_label)` on `installed_servers`, `credentials`, `outbound_oauth_clients`, `server_features`
-- [ ] `instance_label` default `"default"` for existing rows; migration backfills
-- [ ] UI: one registry card with N instance sub-cards instead of flat clone list
-- [ ] FeatureSet member type: `ServerInstance { server_id, instance_label }` for grouped grants
-- [ ] Data migration: existing clones (`posthog-work`) → `(posthog, instance_label=work)`
-- [ ] Log paths, OAuth refresh, event payloads gain instance dimension
-
-**Outcome:** Registry server is the template; instances are first-class. Clone IDs like `posthog-work` become legacy format migrated to structured instances. Only pursue if Phase 1–4 adoption shows ID-suffix sprawl or FeatureSet pain.
-
----
-
-## Out of scope
-
-| Item | Reason |
-| ---- | ------ |
-| Auto-sync clone definition when registry updates | Requires shared definition store or periodic refresh job. Defer; document "clone may drift from registry" in UI. Option 3 addresses properly. |
-| Credential copy / "duplicate with same secrets" | Security footgun. User always re-enters creds on clone. |
-| Runtime account switching on one process | Impossible for stdio env-at-startup servers. Not McpMux's layer to fix. |
-| Wrapper MCP shims per backend | Per-server maintenance burden (Option 5 from brainstorm). Rejected. |
-| Cross-Space clone | Install separately per Space — already works via Spaces. "Clone to another Space" is a nice follow-up, not v1. |
-| Tool-level account selection injection | Would require MCP spec / client header support. Out of scope. |
-
----
-
-## Key files referenced
-
-| File | Why |
-| ---- | --- |
-| [`crates/mcpmux-core/src/application/server.rs`](../../crates/mcpmux-core/src/application/server.rs) | `install()` uniqueness check — clone must use a new `server_id`. |
-| [`crates/mcpmux-core/src/domain/config.rs`](../../crates/mcpmux-core/src/domain/config.rs) | `normalize_server_id` / `normalize_alias` — suffix rules (no underscores). |
-| [`crates/mcpmux-storage/src/migrations/001_initial.sql`](../../crates/mcpmux-storage/src/migrations/001_initial.sql) | Current `UNIQUE(space_id, server_id)` constraints clone works around. |
-| [`crates/mcpmux-gateway/src/services/prefix_cache.rs`](../../crates/mcpmux-gateway/src/services/prefix_cache.rs) | Prefix assignment for clone's alias at connect time. |
-| [`apps/desktop/src/features/servers/ServersPage.tsx`](../../apps/desktop/src/features/servers/ServersPage.tsx) | Primary UI surface for install/configure/enable flow. |
-| [`apps/desktop/src/components/ConfigEditorModal.tsx`](../../apps/desktop/src/components/ConfigEditorModal.tsx) | Reused post-clone credential entry. |
-| [`docs/guide/spaces.mdx`](../../docs/guide/spaces.mdx) | Canonical work/personal separation — clones complement, not replace. |
-
----
-
-## Related documentation
-
-- [`docs/planning/dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) — session enable works with clone `server_id`s once user knows the suffixed name; Phase 3 links them.
-- [`docs/guide/servers.mdx`](../../docs/guide/servers.mdx) — server management baseline; gets multi-account section in Phase 3.
-- [`docs/guide/spaces.mdx`](../../docs/guide/spaces.mdx) — primary pattern for context-level account separation.
-- Personal migration tracker: `jsg-tech-check/docs/setup/mcpmux-server-migration.md` — consuming checklist for PostHog, Gmail, Sheets, Firebase clones.
-
----
-
-## Reconciliation
-
-This doc is the source of truth for server account clones. When implementation starts, update **Status** and **Branch** at the top. Phase 5 remains optional — do not block Phases 1–4 on it.
-
-**Decision record (May 23, 2026):** Option 2 (UI-assisted clone) selected over status quo, first-class instances (deferred Phase 5), per-client credential override (rejected), and wrapper meta-servers (rejected). Brainstorm source: Cursor session on multi-account MCP patterns.
-
-**May 23, 2026 closeout:** Phases 1–4 implemented and verified in dev. Consumed by [mcpmux-server-migration.md](../../../jsg-tech-check/docs/setup/mcpmux-server-migration.md) Phase B2 (clone sprint). Phase 5 remains optional until clone ID sprawl or FeatureSet grouping pain justifies schema migration.
diff --git a/docs/planning/server-display-rename.md b/docs/planning/server-display-rename.md
deleted file mode 100644
index 88a60004..00000000
--- a/docs/planning/server-display-rename.md
+++ /dev/null
@@ -1,132 +0,0 @@
-# Server Display Rename
-
-**Last Updated:** May 25, 2026
-**Status:** Complete — Phases 1–4 shipped
-**Branch:** `feat/server-account-clones` (continuation of clone work)
-**Base branch:** `main`
-**Depends on:** [Server Account Clones](server-account-clones.md) (Phase 1–4 shipped)
-**Unblocks:** Multi-account UX — distinguishing two installs of the same MCP (e.g. two Google Calendars) without renaming `server_id`
-
----
-
-## Problem
-
-Once a Space has multiple installs of the same MCP — either via the clone wizard or a hand-edited user-config JSON — the only thing telling them apart in the UI is the cached definition name (`Google Calendar`, `Google Calendar (work)`). That string lives on `cached_definition` and `server_name`, both of which the user cannot edit and both of which `user_space_sync` overwrites on every config sync.
-
-Users want a friendly per-install label that:
-
-- They can edit any time, not just at clone time.
-- Survives later definition refreshes (registry pulls, user-config sync).
-- Does not affect routing — `server_id`, alias, or tool prefixes stay locked once chosen, otherwise existing tool names break.
-
----
-
-## Decisions
-
-| # | Decision | Choice | Rationale |
-| - | -------- | ------ | --------- |
-| 1 | Identity vs label | **Display label only now**; `server_id` / alias / tool prefixes unchanged | Renaming the ID would invalidate every prompt, binding, and tool name referencing the server. Labels are reversible; IDs are not. |
-| 2 | Storage shape | New nullable `display_name_override` column on `installed_servers` (migration 018) | `server_name` is overwritten on every user-config sync, so the override needs its own column to survive. |
-| 3 | Eligible installs | Registry, manual, clones, and user-config installs are all renamable | Users want to label *any* install — not just clones. |
-| 4 | Uniqueness | Duplicate display names allowed in a space | The `server_id` is already unique; labels are pure UX. |
-| 5 | Configure surface | Display name field at top of the Configure modal, with helper text "Shown in My Servers only. Does not change the server ID or tool names." | Single place users already go to edit a server. |
-| 6 | Clone wizard | Optional freeform display name + existing suffix (suffix still drives `server_id` / alias) | Lets users pick a friendly name at clone time without giving up suffix-driven routing. |
-| 7 | Always-show Configure | Action menu shows Configure (renamed to "Settings" when there are no inputs) for every installed server | Servers without credential inputs still need a way to be renamed. |
-| 8 | Meta-tool surfacing | `mcpmux_list_servers` reports the effective display name (override → `server_name` → `server_id` tail) | Agents see "Joe Calendar" instead of the catalog name when the user has renamed an install. |
-
----
-
-## The Model
-
-```mermaid
-flowchart LR
-  subgraph storage [Storage]
-    override["display_name_override"]
-    server_name["server_name / cached_definition"]
-  end
-  subgraph ui [Desktop UI]
-    configure["Configure modal"]
-    clone["Clone wizard"]
-    list["My Servers list / search"]
-  end
-  subgraph api [API]
-    save["save_server_inputs"]
-    set_name["set_server_display_name"]
-    clone_api["clone_server"]
-  end
-  configure --> save --> override
-  clone --> clone_api --> override
-  configure --> set_name --> override
-  override --> list
-  server_name --> list
-```
-
-`InstalledServer::display_name()` is the single source of truth for the effective label:
-
-```rust
-override
-  .or(server_name)
-  .or(server_id.split('/').last())
-```
-
-The frontend `resolveInstalledDisplayName` mirrors that precedence so every code path agrees on what to render.
-
----
-
-## File Inventory
-
-### Phase 1 — Storage and domain (✅)
-
-- `crates/mcpmux-storage/src/migrations/018_installed_server_display_name_override.sql` — new column.
-- `crates/mcpmux-storage/src/database.rs` — register migration 018.
-- `crates/mcpmux-core/src/domain/installed_server.rs` — `display_name_override` field, `display_name()` precedence, `with_display_name_override` helper, unit tests.
-- `crates/mcpmux-storage/src/repositories/installed_server_repository.rs` — INSERT/UPDATE/SELECT round-trip and `set_display_name_override`.
-- `crates/mcpmux-core/src/repository/mod.rs` — trait method `set_display_name_override`.
-- `tests/rust/src/mocks.rs` — mock repo impl.
-
-### Phase 2 — Application service and Tauri (✅)
-
-- `crates/mcpmux-core/src/application/server.rs` — `clone_server` accepts optional `display_name_override`; `update_config` accepts optional `display_name_override` (None = leave alone, Some(empty) = clear, Some(value) = set); new `set_display_name_override` service method; unit tests covering set/clear via update_config and the dedicated method, plus clone-with-display-name.
-- `apps/desktop/src-tauri/src/commands/server.rs` — `save_server_inputs` extended with `display_name_override`; new `set_server_display_name` command.
-- `apps/desktop/src-tauri/src/commands/server_clone.rs` — `clone_server` extended with optional `display_name`.
-- `apps/desktop/src-tauri/src/lib.rs` — register `set_server_display_name`.
-
-### Phase 3 — Frontend (✅)
-
-- `apps/desktop/src/types/registry.ts` — `display_name_override` on `InstalledServerState`.
-- `apps/desktop/src/features/servers/server-display-name.helpers.ts` — new `resolveInstalledDisplayName` helper.
-- `apps/desktop/src/features/servers/ServersPage.tsx` — view-model merge paths (`mergeDefinitionsWithStates`, `createOfflineServerViewModel`, `createViewModelFromClone`) use the helper; `ConfigModalState` carries `displayName` / `initialDisplayName`; modal seeds and persists the field via `saveServerInputs`.
-- `apps/desktop/src/features/servers/ServerActionMenu.tsx` — Configure action always shown ("Settings" when no inputs).
-- `apps/desktop/src/features/servers/CloneAccountModal.tsx` — optional Display name field, defaults to `{Source} ({suffix})` placeholder, sent to `clone_server`.
-- `apps/desktop/src/features/servers/UninstallSourceWithClonesDialog.tsx` — dependent labels resolved through the helper.
-- `apps/desktop/src/lib/api/registry.ts` — extended `saveServerInputs`; new `setServerDisplayName`.
-- `apps/desktop/src/lib/api/serverClone.ts` — `cloneServer` accepts `displayName`.
-- `apps/desktop/src/stores/registryStore.ts` — `mergeServers` uses the helper for installed rows.
-
-### Phase 4 — Meta tools (✅)
-
-- `crates/mcpmux-gateway/src/services/meta_tools/tools.rs` — `mcpmux_list_servers` builds `server_id → InstalledServer.display_name()` lookup and prefers it over feature-derived names.
-
----
-
-## Out of scope
-
-- Changing `server_id`, clone suffix, or tool prefix (`alias_*`) via rename UI.
-- Phase 5 "first-class instances" (`instance_label` schema) from [server-account-clones.md](server-account-clones.md).
-- Syncing the override back into user-space JSON `label` field (future enhancement).
-
-## Risks and mitigations
-
-| Risk | Mitigation |
-|------|------------|
-| UI still shows catalog name in some surface | Centralized `resolveInstalledDisplayName` + every merge path fixed |
-| User-config sync clobbers the label | `display_name_override` lives in its own column; sync only refreshes `server_name` / `cached_definition` |
-| Configure unreachable for no-input servers | Action menu always shows Configure (renamed to "Settings") |
-| Tool names break after rename | Rename only updates the label; `server_id` and alias are immutable in v1 |
-
-## Validation
-
-- `cargo nextest run -p mcpmux-core -p mcpmux-storage` — all tests including new override coverage pass.
-- `cargo nextest run -p tests --test integration server_clone` — clone integration tests still pass with the new parameter.
-- `pnpm typecheck` — passes.
-- `pnpm validate` should be re-run before merge for full clippy + ESLint + formatting coverage.
diff --git a/docs/planning/tool-level-session-pin.md b/docs/planning/tool-level-session-pin.md
deleted file mode 100644
index 31abeee2..00000000
--- a/docs/planning/tool-level-session-pin.md
+++ /dev/null
@@ -1,327 +0,0 @@
-# Tool-Level Session Pin Meta Tool (`mcpmux_pin_this_session`)
-
-**Last Updated:** May 25, 2026
-**Status:** Deferred — superseded by [`meta-gateway-invoke.md`](./meta-gateway-invoke.md) for token budget. May revive as Phase F (invoke ACL only) if search + invoke proves insufficient.
-**Branch:** TBD — branch off `main` once [`dynamic-mcp-toggle-meta-tools`](./dynamic-mcp-toggle-meta-tools.md) merges
-**Base branch:** `main` (depends on the meta-tools infrastructure shipped via the dynamic-toggle PR being live)
-**Issue:** TBD — file after planning review
-**Depends on:** [`dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) — provides `SessionOverrideRegistry`, `MetaToolContext`, per-peer `tools/list_changed` plumbing, and the `gateway.session_overrides_require_approval` setting reused here
-**Supersedes:** Out-of-Scope row #1 in [`dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) — *"Tool-level granularity… no real evidence yet that tool-level matters more than server-level for token budget"*
-**Unblocks:** Per-chat tool-budget control for high-tool-count installs (Google Workspace 120 tools, cloned ×2 = 240) — see [`server-account-clones.md`](./server-account-clones.md)
-
----
-
-## Problem
-
-The May 23 `dynamic-mcp-toggle-meta-tools` planning doc deferred tool-level granularity on the grounds that *server-level enable/disable covered the user's stated use case* and there was *no real evidence yet that tool-level mattered more than server-level for token budget*. That evidence now exists.
-
-[`server-account-clones.md`](./server-account-clones.md) shipped Phase 1–4 in mid-May, and the first heavy real-world install — Google Workspace cloned for a Personal + S2H account split — exposed the gap:
-
-| Symptom | Concrete number |
-| ------- | --------------- |
-| Tools per Google Workspace install | 120 |
-| Installs after the account clone | 2 |
-| Tools surfaced to a Cursor session that needs both accounts | 240 |
-| Approximate system-prompt tokens consumed by those 240 tool definitions | ~30–50k |
-
-Server-level overrides do not help here: both clones are wanted in the session, so neither can be disabled. `mcpmux_create_feature_set` + `mcpmux_bind_current_workspace` can carve a persistent subset, but persisting a tool list per workspace is the wrong shape for *"for the next 10 minutes I only need Gmail send + read + 8 calendar tools, drop the other 230"* — the LLM needs an ephemeral knob it can flip per task, not a binding.
-
-This doc fills that gap with **one new write tool plus a small clear tool**, both session-scoped (with an opt-in workspace-scope path that reuses the existing FeatureSet + binding plumbing). The killer detail: the plumbing for this is already wired — `SessionOverrideRegistry` exists, `FeatureService::get_tools_for_grants` is already the materialization chokepoint, per-peer `tools/list_changed` already fires after meta-tool writes. The change is additive: one new field on the registry, one new filter step at the bottom of the existing composition rule, two new `MetaTool` impls.
-
-A note on naming: `mcpmux_pin_this_session` is referenced verbatim in the meta-tools module docstring, in `SettingsPage.tsx`, in the approval-broker tests, and in the WDIO meta-tools spec — leftover from an early draft when the tool was intended to ship with the original meta-tools work. Reusing the name keeps every existing reference truthful instead of forcing a docs-only renaming pass.
-
----
-
-## Decisions
-
-| # | Decision | Choice | Rationale |
-| - | -------- | ------ | --------- |
-| 1 | New tool vs extend existing | **One new write tool (`mcpmux_pin_this_session`) + one new write tool (`mcpmux_clear_session_pin`)** — do not overload `enable_server`/`disable_server` | Server-level and tool-level have different composition semantics (additive overlay vs exclusive replacement). Conflating them would force every call site to disambiguate. Two narrowly-scoped tools keep the surface clean. |
-| 2 | Composition with existing overrides | **Exclusive replacement applied AFTER server-level composition.** Effective = `(binding_servers ∪ session_on) − session_off`, materialize tools, then if `pinned_tools` non-empty: filter to `tools ∩ pinned_tools`. | Pin semantically means "lock to this set." Layering it on top means a pin to `["github_create_issue"]` works whether `github` is enabled via binding, via session-enable, or both — the user expresses intent (which tools they want) without caring about how those tools got into the candidate pool. |
-| 3 | Empty list semantics | **Empty `tool_qualified_names` rejected as invalid argument** — clearing is done via `mcpmux_clear_session_pin` | Avoids two paths for the same operation. Reject-on-empty matches `mcpmux_create_feature_set` which already rejects empty `tool_qualified_names`. |
-| 4 | Explicit clear vs implicit | **Dedicated `mcpmux_clear_session_pin` tool** — no args, operates on caller's session | Forces an intentional unpin, audited like any other write. Letting "pin with full list" act as clear would require the LLM to call `list_all_tools` first just to undo — wasteful and ambiguous. |
-| 5 | Naming | **`mcpmux_pin_this_session`** | Matches every existing stale reference (mod.rs docstring, SettingsPage copy, approval tests, WDIO spec). The "this_session" suffix makes scope intuitive — ergonomic mirror to the existing `mcpmux_bind_current_workspace`. |
-| 6 | Scope support | **`scope: "session"` (default) + `scope: "workspace"`** mirroring `mcpmux_enable_server` | Session is the ephemeral knob. Workspace persists the same pin set via a new auto-named custom FeatureSet bound to the caller's first reported root — single approval-gated atomic op instead of two-step `create_feature_set` + `bind_current_workspace`. |
-| 7 | Workspace-scope FeatureSet naming | **Auto-named `"Pinned: {root_basename} {YYYY-MM-DD HH:MM}"`** unless caller supplies optional `name` arg | Discoverable in the Workspaces UI after creation. Optional override lets the LLM name it meaningfully (`"Gmail send-only"`) when the user prompt makes intent clear. |
-| 8 | Approval default | **Session: auto-allow, gated by existing `gateway.session_overrides_require_approval`. Workspace: always required via `ApprovalBroker`.** | Reuses the existing setting — no new toggle. Session pin is ephemeral (dies with the MCP session) so the same risk profile as `enable_server`/`disable_server` applies. Workspace persists state, so it always shows the approval dialog with the full tool list in the diff. |
-| 9 | Override store layout | **Extend `SessionOverrideRegistry` with `pinned_tools: DashMap<SessionId, HashSet<QualifiedName>>`** — do not introduce a sibling registry | Same lifecycle (process-only, dies with session reap), same factory, same GC hook in `MCPNotifier`. Keeping it co-located concentrates session-scoped override state in one struct so `reap_dead_sessions` only needs to know about one type. |
-| 10 | Validation timing | **Validate every qualified name exists in caller's resolved Space at call time** (look up via `server_feature_repo::list_for_space`) | Rejects typos and stale tool names up-front with a clear error. Storing unresolved names would let the pin silently shrink to nothing if a server becomes unavailable. |
-| 11 | Audit decision string | **`"session_pin"` for session-scope writes, `"allow_once"` for workspace-scope approvals** | Distinct from `"session_override"` used by enable/disable so the audit log + Workspaces UI can render pin-specific rows ("pinned 12 tools" vs "enabled github"). |
-
----
-
-## The Model
-
-### Override store extension
-
-```text
-SessionOverrideRegistry {
-    enabled       : DashMap<SessionId, HashSet<ServerId>>,        // existing
-    disabled      : DashMap<SessionId, HashSet<ServerId>>,        // existing
-    pinned_tools  : DashMap<SessionId, HashSet<QualifiedName>>,   // NEW
-}
-```
-
-`pinned_tools[sid]` stores fully qualified tool names (e.g. `"github_create_issue"`, `"google-workspace-mcp-uvx_send_email"`) — the same format `mcpmux_list_all_tools` returns and `mcpmux_create_feature_set` accepts. Empty/missing = no pin = pass-through.
-
-GC: `SessionOverrideRegistry::remove(session_id)` extended to drop `pinned_tools[sid]` alongside the existing two sets. `MCPNotifier::reap_dead_sessions` already calls `remove` per reaped session — no notifier change needed.
-
-### Composition rule
-
-The existing composition in `FeatureService::get_tools_for_grants` runs steps 1–6; this doc adds steps 7–8:
-
-```text
-1. (space, feature_set_ids) ← FeatureSetResolverService::resolve(...)
-2. binding_servers          ← FeatureService::servers_for(space, feature_set_ids)
-3. session_on               ← SessionOverrideRegistry.enabled[session_id]
-4. session_off              ← SessionOverrideRegistry.disabled[session_id]
-5. effective_servers        ← (binding_servers ∪ session_on) − session_off
-6. base_tools               ← every Tool feature whose server_id ∈ effective_servers AND is_available
-
-7. pinned ← SessionOverrideRegistry.pinned_tools[session_id]
-8. if pinned is non-empty:
-       tools ← base_tools.filter(qualified_name ∈ pinned)
-   else:
-       tools ← base_tools
-```
-
-The pin filter applies only to **tools**. Prompts and resources are unaffected — pinning is a tool-budget concept, not a capability-restriction concept. `get_prompts_for_grants` and `get_resources_for_grants` skip steps 7–8.
-
-A pin that resolves to zero matches (every name filtered out by `is_available`) returns an empty tool list. The caller's `tools/list` will show no tools; calling `mcpmux_clear_session_pin` is the recovery path. This is intentional — silent fall-through to `base_tools` on empty intersection would mask user error.
-
-### Tool surface
-
-Two new tools registered in `build_default_registry`:
-
-| Tool | Type | Approval (default) | Purpose |
-| ---- | ---- | ------------------ | ------- |
-| `mcpmux_pin_this_session` | write | session: auto-allow (configurable via `gateway.session_overrides_require_approval`); workspace: required | Replace the caller's session tool list with the explicit qualified-name set. Optional `scope: "workspace"` persists as a custom FeatureSet + binding. |
-| `mcpmux_clear_session_pin` | write | auto-allow | Drop the caller's pin; next `tools/list` returns the full default-routed set. |
-
-Both fire `MCPNotifier::notify_session_lists_changed(session_id)` after a successful write — the calling LLM sees the new (or restored) tool list on its next `tools/list` poll.
-
-### Workspace-scope variant flow
-
-`mcpmux_pin_this_session({ tool_qualified_names: [...], scope: "workspace", name?: "..." })` is sugar for the two-call sequence the user would otherwise run:
-
-```text
-1. Validate every qualified_name exists in caller's Space
-2. Resolve caller's first reported workspace root (require session_roots; reject if missing)
-3. Open approval dialog with diff: { root, new FS name, full tool list }
-4. On allow:
-   a. Create custom FeatureSet with the matched ServerFeature ids (using add_feature_member + MemberMode::Include)
-   b. Create WorkspaceBinding(root, space_id, feature_set_id)
-   c. Emit FeatureSetMembersChanged and WorkspaceBindingChanged so the resolver picks it up
-5. Return { ok: true, feature_set_id, binding_id, scope: "workspace" }
-```
-
-The same path `create_feature_set` + `bind_current_workspace` exercises, run atomically as one approval. Failure between (4a) and (4b) leaves a custom FeatureSet without a binding — the existing Workspaces UI already handles unbound custom FSes (they appear in the list and can be bound or deleted), so no compensating cleanup is needed.
-
-### What McpMux stores
-
-| Item | Storage | Persistence |
-| ---- | ------- | ----------- |
-| `pinned_tools` set | `SessionOverrideRegistry` (in-memory `DashMap`) | Process-lifetime; dies with session reap |
-| Workspace-scope pin | new custom `FeatureSet` row + new `workspace_bindings` row | Persistent (uses existing schema) |
-| Audit trail | `DomainEvent::MetaToolInvoked` with `decision: "session_pin"` or `"allow_once"` | Persistent via existing audit log |
-
-No new tables, columns, or migrations.
-
----
-
-## Architecture
-
-```
-                ┌──────────────────────────────────────────────┐
-                │  FeatureService::get_tools_for_grants        │
-                │                                              │
-                │  1–6. Server composition (existing)          │
-                │       effective_servers =                    │
-                │         (binding ∪ session_on) − session_off │
-                │       base_tools = tools for servers         │
-                │                                              │
-                │  7–8. NEW: tool-pin filter                   │
-                │       if pinned_tools[sid] non-empty:        │
-                │         tools = base_tools ∩ pinned_tools    │
-                │       else:                                  │
-                │         tools = base_tools                   │
-                └──────────────────────────────────────────────┘
-                                    ▲
-                                    │
-                    ┌───────────────┴───────────────┐
-                    │                               │
-                    ▼                               ▼
-        ┌──────────────────────┐    ┌──────────────────────────────┐
-        │ SessionOverride-     │    │ Meta tool writes mutate this │
-        │ Registry (extended)  │    │ registry directly.           │
-        │                      │    │                              │
-        │ enabled              │    │ mcpmux_pin_this_session      │
-        │ disabled             │    │ mcpmux_clear_session_pin     │
-        │ pinned_tools  ← NEW  │    │                              │
-        └──────────────────────┘    └──────────────────────────────┘
-```
-
-- `SessionOverrideRegistry` lives where it already does (`crates/mcpmux-gateway/src/services/session_overrides.rs`). One new field, three new methods (`pin`, `clear_pin`, `pinned_set`). Existing `remove(session_id)` extended to clear the new map.
-- `FeatureService::get_tools_for_grants` gains steps 7–8. The sibling `get_prompts_for_grants` / `get_resources_for_grants` are intentionally untouched — pin is tool-only.
-- The two new `MetaTool` impls land in `meta_tools/tools.rs` alongside the existing five write tools. Same `with_approval()` template, same `caller_space_id` / `validate_server_in_space` helpers — workspace variant calls into a new `workspace_pin::pin_workspace` helper module mirroring `workspace_server.rs`.
-
----
-
-## Files to create
-
-| File | Purpose |
-| ---- | ------- |
-| [`crates/mcpmux-gateway/src/services/meta_tools/workspace_pin.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/workspace_pin.rs) | `pin_workspace(call, space_id, qualified_names, name) -> CallToolResult` — atomic create-FS + bind-workspace under one approval, mirroring `workspace_server.rs` |
-| [`tests/rust/tests/integration/tool_pin.rs`](../../tests/rust/tests/integration/tool_pin.rs) | E2E composition + meta-tool tests for pin / clear / workspace-scope |
-
-## Files to modify
-
-| File | Change |
-| ---- | ------ |
-| [`crates/mcpmux-gateway/src/services/session_overrides.rs`](../../crates/mcpmux-gateway/src/services/session_overrides.rs) | Add `pinned_tools: DashMap<String, HashSet<String>>` field. Methods: `pin(session_id, names)`, `clear_pin(session_id)`, `pinned_set(session_id) -> HashSet<String>`. Extend `remove()` to drop the entry. Extend `list_all()` to surface pinned counts for UI |
-| [`crates/mcpmux-gateway/src/pool/features/facade.rs`](../../crates/mcpmux-gateway/src/pool/features/facade.rs) | `get_tools_for_grants` applies the pin filter as the final step. `get_prompts_for_grants` / `get_resources_for_grants` unchanged |
-| [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | Implement `PinThisSessionTool` and `ClearSessionPinTool`. Session path mirrors `EnableServerTool` (optional approval). Workspace path delegates to `workspace_pin::pin_workspace`. Validation via existing `server_feature_repo::list_for_space` |
-| [`crates/mcpmux-gateway/src/services/meta_tools/mod.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/mod.rs) | `pub mod workspace_pin;` + `registry.register(Box::new(tools::PinThisSessionTool))` and `registry.register(Box::new(tools::ClearSessionPinTool))` in `build_default_registry`. Update module-level docstring example (currently references `mcpmux_pin_this_session` aspirationally — now real) |
-| [`crates/mcpmux-gateway/src/services/meta_tools/registry.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/registry.rs) | Document `"session_pin"` as a valid `decision` value in the audit-emission block; no other change |
-| [`apps/desktop/src/features/settings/SettingsPage.tsx`](../../apps/desktop/src/features/settings/SettingsPage.tsx) | Update meta-tools description from `"mcpmux_list_all_tools, mcpmux_pin_this_session, and 6 others"` to `"mcpmux_list_all_tools, mcpmux_pin_this_session, and 7 others"` (count goes from 7 → 9 registered tools) |
-| [`apps/desktop/src/features/workspaces/WorkspacesPage.tsx`](../../apps/desktop/src/features/workspaces/WorkspacesPage.tsx) | Extend "Active session overrides" panel with a "Pinned tools" row per session — shows count + expandable list, plus a "Clear pin" button calling a new Tauri command |
-| [`apps/desktop/src-tauri/src/commands/session_overrides.rs`](../../apps/desktop/src-tauri/src/commands/session_overrides.rs) | Extend `list_session_overrides` return shape with `pinned_tools: string[]`. Add `clear_session_pin(session_id)` Tauri command |
-| [`apps/desktop/src/lib/api/sessionOverrides.ts`](../../apps/desktop/src/lib/api/sessionOverrides.ts) | TS wrapper update: extend return type with `pinned_tools` field; add `clearSessionPin(sessionId)` |
-| [`README.md`](../../README.md) | Self-management meta tools section gains the pin tool — keep the section format the existing dynamic-toggle work established |
-
----
-
-## Phasing
-
-### Phase 1 — Registry extension + composition wiring
-
-**Effort:** 1 evening
-
-- [ ] Add `pinned_tools: DashMap<String, HashSet<String>>` to `SessionOverrideRegistry`
-- [ ] Methods: `pin(session_id, names)` (replaces any existing pin), `clear_pin(session_id)`, `pinned_set(session_id) -> HashSet<String>`
-- [ ] Extend `remove(session_id)` to drop `pinned_tools` alongside `enabled` / `disabled`
-- [ ] Extend `list_all()` snapshot to include pinned counts so the UI panel can render without extra calls
-- [ ] `FeatureService::get_tools_for_grants(session_id)` applies the pin filter as the final step (steps 7–8 in the composition rule above)
-- [ ] Unit tests on the registry; composition test in `tests/rust/tests/integration/tool_pin.rs` exercising: no pin → full list, pin with subset → filtered, pin with non-matching names → empty, clear → restored
-
-**Outcome:** Direct registry mutation (`registry.pin("sess-1", ["github_create_issue"])`) causes the next `get_tools_for_grants("sess-1", grants)` to return exactly one tool, regardless of the binding's normal output. Meta tools and UI unchanged.
-
-### Phase 2 — `mcpmux_pin_this_session` (session scope only)
-
-**Effort:** 1 evening
-
-- [ ] `PinThisSessionTool` in `meta_tools/tools.rs` — args `{ tool_qualified_names: string[], scope?: "session" | "workspace", name?: string }`
-- [ ] Validate `tool_qualified_names` non-empty (else `InvalidArgument`)
-- [ ] Validate every qualified name resolves to an available `Tool` feature in the caller's resolved Space — collect the mismatches and surface them in the error message so the LLM can recover without guessing
-- [ ] Session path: optional approval via `gateway.session_overrides_require_approval` → `registry.pin(sid, names)` → set audit decision to `"session_pin"` → emit per-peer `tools/list_changed` via `MCPNotifier::notify_session_lists_changed`
-- [ ] Workspace path: return `InvalidArgument("workspace scope ships in Phase 4")` for now
-- [ ] Register in `build_default_registry`
-- [ ] Integration tests: pin reduces tool list, `list_changed` fires, invalid name returns descriptive error, approval-required setting routes through `ApprovalBroker`
-
-**Outcome:** LLM calls `mcpmux_pin_this_session({ tool_qualified_names: ["google-workspace-mcp-uvx_send_email", "google-workspace-mcp-uvx_list_calendar_events"] })` and the next `tools/list` returns exactly those two tools instead of 240. Cursor's UI updates without restarting the session.
-
-### Phase 3 — `mcpmux_clear_session_pin`
-
-**Effort:** 1 hour
-
-- [ ] `ClearSessionPinTool` — no args; operates on caller's `session_id`
-- [ ] Calls `registry.clear_pin(sid)`; idempotent (clearing an unpinned session is `ok: true` with `was_pinned: false`)
-- [ ] No approval gate even when `session_overrides_require_approval` is on — clear is always safe (broadens scope)
-- [ ] Audit decision `"session_pin_cleared"`
-- [ ] Emit per-peer `tools/list_changed`
-- [ ] Register in `build_default_registry`
-- [ ] Integration test: pin then clear restores full set
-
-**Outcome:** LLM can recover from a bad pin (e.g. pinned the wrong tool name and now has 0 visible tools) without restarting the session.
-
-### Phase 4 — Workspace-scope variant
-
-**Effort:** 1 day
-
-- [ ] `crates/mcpmux-gateway/src/services/meta_tools/workspace_pin.rs` — `pin_workspace(call, space_id, qualified_names, name)`
-- [ ] Resolve caller's first reported root via `session_roots.get(sid)` — reject with descriptive error if no roots reported
-- [ ] Auto-name FS as `"Pinned: {root_basename} {YYYY-MM-DD HH:MM}"` unless caller supplied `name`
-- [ ] Build approval diff payload: `{ workspace_root, feature_set_name, added_tools: [first ~10 qualified names], total_count }`
-- [ ] `with_approval` → on allow: create custom `FeatureSet` with matched `ServerFeature` ids (using `add_feature_member` + `MemberMode::Include`) → create `WorkspaceBinding` → emit `FeatureSetMembersChanged` and `WorkspaceBindingChanged`
-- [ ] Audit decision `"allow_once"` (matches workspace writes)
-- [ ] Return `{ ok: true, feature_set_id, binding_id, workspace_root, scope: "workspace", tool_count }`
-- [ ] Integration test: workspace-scope pin survives simulated session restart (new session for the same root resolves through the new binding), unbound caller rejected, name override respected
-
-**Outcome:** A single approval-gated tool call persists a custom tool subset for the caller's workspace cwd. Equivalent to `create_feature_set` + `bind_current_workspace` chained, with one approval and one audit row instead of two.
-
-### Phase 5 — UI surface + doc cleanup
-
-**Effort:** 0.5 day
-
-- [ ] Workspaces page session inspector gains "Pinned tools (N)" row per session; expanding shows the full qualified-name list
-- [ ] "Clear pin" button next to the existing per-session "Clear all overrides" button — calls `clearSessionPin` from `lib/api/sessionOverrides.ts`
-- [ ] Settings copy update in `SettingsPage.tsx`: bump "and 6 others" to "and 7 others" so the displayed count matches the registry
-- [ ] `meta_tools/mod.rs` module docstring no longer needs the aspirational `mcpmux_pin_this_session` reference qualifier — leave it as-is (the example is now accurate)
-- [ ] README self-management meta-tools section gains `mcpmux_pin_this_session` + `mcpmux_clear_session_pin` entries; keep the table format the existing dynamic-toggle work established
-- [ ] CHANGELOG: release-please handles it via conventional `feat(meta-tools): add tool-level session pin` commit — no manual edit
-
-**Outcome:** A user viewing the Workspaces page can see "session abc123 is pinned to 12 tools" with the tool names expandable and a one-click clear. Settings copy is honest about the registered tool count. README and module docs no longer reference a tool that doesn't exist.
-
----
-
-## Pre-PR validation
-
-Do **not** open a PR until all automated checks pass and the production build is verified manually.
-
-| Step | Command | Purpose |
-| ---- | ------- | ------- |
-| Full validate | `pnpm validate` | fmt, clippy, check, eslint, typecheck |
-| Rust tests | `pnpm test:rust` | unit + integration (`tool_pin.rs`) |
-| TS tests | `pnpm test:ts` | vitest |
-| Production build | `pnpm build` | Tauri build on current platform |
-| Manual smoke | Run app, exercise pin + clear from a real MCP client (Cursor), verify Workspaces panel reflects state, verify approval dialog content for workspace scope | UX verification — the diff payload's tool-list rendering is easy to regress |
-
-Optional (slow / env-dependent): `pnpm test:e2e`, `pnpm test:e2e:web`.
-
-**PR target:** `main` (assumes `dynamic-mcp-toggle-meta-tools` is already merged).
-
----
-
-## Out of scope
-
-| Item | Reason |
-| ---- | ------ |
-| Pin expiry / TTL | Sessions are already ephemeral. Explicit `mcpmux_clear_session_pin` covers the cleanup path. A TTL would be a different concept and isn't asked for. |
-| Wildcard / glob support in pin lists (`google-workspace-mcp-uvx_*`) | Explicit qualified names are unambiguous and the LLM can produce them by reading `mcpmux_list_all_tools` first. Wildcard support is additive — defer until a real use case shows up. |
-| Multi-pin layering (stack multiple pin sets, additive) | Single replacement set keeps semantics crisp. Layering would need ordering rules and conflict resolution — not justified by the current evidence. |
-| Pin export to a portable template (across workspaces or users) | Workspace-scope variant already creates a persisted custom FeatureSet; sharing those across workspaces is a separate "FeatureSet templates" feature not yet scoped. |
-| LLM-driven pin recommendations (host suggests "based on this prompt, here are the 10 tools you need") | That's a host-side concern (Cursor / Claude Code), not a gateway concern. Gateway exposes the mechanism; host decides when to use it. |
-| Pin applied to prompts / resources | Pin is tool-budget-shaped. Prompts/resources are not the bottleneck. Keep the surface narrow. |
-| Settings UI toggle for `mcpmux_pin_this_session` independent of other session overrides | Reuses the existing `gateway.session_overrides_require_approval` setting deliberately — adding per-tool toggles balloons the settings surface for no clear benefit. Revisit if user feedback diverges. |
-
----
-
-## Key files referenced
-
-| File | Why |
-| ---- | --- |
-| [`crates/mcpmux-gateway/src/services/session_overrides.rs`](../../crates/mcpmux-gateway/src/services/session_overrides.rs) | Registry being extended. Existing `enabled` / `disabled` field shape and `remove()` GC contract are the template for the new `pinned_tools` field |
-| [`crates/mcpmux-gateway/src/services/meta_tools/tools.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/tools.rs) | Where the two new `MetaTool` impls land. `EnableServerTool` / `DisableServerTool` are the closest templates (session-scope short-circuit + workspace delegation pattern) |
-| [`crates/mcpmux-gateway/src/services/meta_tools/workspace_server.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/workspace_server.rs) | Pattern reference for `workspace_pin.rs` — shows how workspace-scope writes resolve roots, build approval payloads, and create/modify bindings atomically |
-| [`crates/mcpmux-gateway/src/services/meta_tools/mod.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/mod.rs) | `build_default_registry` factory — registration site for the new tools. Module-level docstring already mentions `mcpmux_pin_this_session` as the canonical example; this PR makes that mention accurate |
-| [`crates/mcpmux-gateway/src/services/meta_tools/registry.rs`](../../crates/mcpmux-gateway/src/services/meta_tools/registry.rs) | `MetaToolContext` + `MetaToolRegistry::call` dispatch. Audit-decision string list extended with `"session_pin"` / `"session_pin_cleared"` |
-| [`crates/mcpmux-gateway/src/pool/features/facade.rs`](../../crates/mcpmux-gateway/src/pool/features/facade.rs) | `FeatureService::get_tools_for_grants` is the materialization chokepoint where the pin filter applies. Existing server composition logic stays untouched — the filter is one new conditional block at the bottom |
-| [`crates/mcpmux-gateway/src/consumers/mcp_notifier.rs`](../../crates/mcpmux-gateway/src/consumers/mcp_notifier.rs) | Session-reap pass already calls `SessionOverrideRegistry::remove` per reaped session — automatically picks up the new `pinned_tools` field, no notifier change needed |
-| [`docs/planning/dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) | Direct predecessor — defines the SessionOverrideRegistry pattern, approval flow conventions, and Out-of-Scope row #1 this doc supersedes |
-| [`docs/planning/server-account-clones.md`](./server-account-clones.md) | Origin of the 240-tool context-bloat evidence that justifies revisiting tool-level granularity |
-
----
-
-## Related work
-
-- [`docs/planning/dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) — defines the meta-tools infrastructure and the session-override registry pattern. Supersedes its Out-of-Scope row #1.
-- [`docs/planning/server-account-clones.md`](./server-account-clones.md) — clone feature that created the 240-tool context-bloat evidence. This doc is a natural follow-on for users who hit that ceiling.
-- [MikkoParkkola/mcp-gateway](https://github.com/MikkoParkkola/mcp-gateway) and [abdullah1854/MCPGateway](https://github.com/abdullah1854/MCPGateway) — alternative architectural answer (search-then-invoke meta gateway, ~95% context reduction). Considered and rejected for this PR: their model hides all backend tools by default and requires the LLM to discover via `gateway_search_tools` on every call. The McpMux approach keeps the LLM's mental model of named tools intact and lets the user (via the LLM) opt in to budget reduction per session. Worth revisiting as a separate planning doc if the pin-based approach proves insufficient.
-- [MCP spec — Tools `list_changed` notification](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#list-changed-notification) — protocol mechanism that makes the post-pin tool-list refresh observable mid-conversation. Already wired by [`dynamic-mcp-toggle-meta-tools`](./dynamic-mcp-toggle-meta-tools.md).
-- [modelcontextprotocol/servers#2173](https://github.com/modelcontextprotocol/servers/issues/2173) — upstream tracking issue for server-side multi-tenancy. Pin is a gateway-side workaround for the same underlying problem (tool surface scaling poorly with multi-account use).
-
----
-
-## Reconciliation
-
-This doc is the source of truth for what gets built. When implementation completes, update the **Status** field at the top and reconcile any deviations (extra files, dropped phases, scope changes) per [`update-planning-md`](~/.cursor/commands/update-planning-md.md).
diff --git a/docs/planning/web-admin-remote-access.md b/docs/planning/web-admin-remote-access.md
deleted file mode 100644
index c2fd2ce8..00000000
--- a/docs/planning/web-admin-remote-access.md
+++ /dev/null
@@ -1,317 +0,0 @@
-# Web Admin Mode (Remote UI via HTTP)
-
-**Last Updated:** May 25, 2026
-**Status:** Planning
-**Branch:** TBD — branch off `main` (or current fork head)
-**Base branch:** `main`
-**Issue:** TBD — file after planning review
-**Depends on:** None for core admin HTTP layer; benefits from merged fork features (session meta-tools, account clones) but does not require them
-**Unblocks:** [`jsg-tech-check` homelab wiring Step 6](../../../jsg-tech-check/docs/setup/home-lab-wiring-plan.md) — remote McpMux admin UI from Weathertop / Rohan at `https://mux.joe-hassio.com`
-
----
-
-## Problem
-
-The McpMux admin UI (Spaces, servers, credentials, workspace bindings, FeatureSets, OAuth consent) is a Tauri desktop app. The React frontend talks to Rust exclusively via Tauri `invoke()` — ~80 calls across 15 API modules, backed by ~110 Tauri commands in 19 command modules. There is no HTTP admin surface.
-
-The homelab wiring plan already exposes two public endpoints via Cloudflare Tunnel on Gondor:
-
-| Hostname | Target | What it serves |
-| -------- | ------ | -------------- |
-| `mcp.joe-hassio.com` | `localhost:45818` | MCP gateway (`/mcp`) for AI clients |
-| `code.joe-hassio.com` | `localhost:3001` | ClaudeCodeUI |
-
-Neither exposes the admin UI. Tunneling Vite dev (`:1420`) serves a React shell with no backend — every action fails because nothing answers `invoke()`. Tunneling the MCP gateway (`:45818`) serves the protocol endpoint, not admin pages.
-
-The user-facing ask:
-
-> I want to be able to reach the UI — that's the main point.
-
-Screen sharing / VNC behind CF Access works today but is not a web UI. This doc defines a **web admin mode**: an optional HTTP server that serves the built React SPA and exposes a REST API mirroring Tauri commands, gated by Cloudflare Access at the edge.
-
----
-
-## Decisions
-
-| # | Decision | Choice | Rationale |
-| - | -------- | ------ | --------- |
-| 1 | Deployment model | **Single-user homelab** — one McpMux instance on Gondor, one operator | Avoids multi-tenant auth, cloud KMS, and per-user DB isolation. The Rust process still runs locally with OS keychain access. |
-| 2 | Auth | **Cloudflare Access at the tunnel edge** — app trusts `CF-Access-Jwt-Assertion` when `gateway.admin_trust_cf_access` is enabled | No login UI to build. Same pattern as `b.joe-hassio.com` (Beeper). Reject requests without a valid JWT when admin mode is enabled. |
-| 3 | Admin server placement | **Separate Axum router on configurable port** (default `45819`), not mixed into MCP gateway routes | Keeps MCP protocol surface unchanged. Admin and MCP can be tunneled independently (`mux.joe-hassio.com` vs `mcp.joe-hassio.com`). Easier to disable admin without stopping the gateway. |
-| 4 | Static UI | **Serve `frontendDist` from the Tauri build** at `/` with SPA fallback | Reuses the existing React app. No separate web bundle. |
-| 5 | API shape | **REST JSON at `/api/v1/*`** mirroring Tauri command names (kebab → snake mapping) | Predictable mapping: `get_gateway_status` → `GET /api/v1/gateway/status`. One handler module per Tauri command group. |
-| 6 | Frontend transport | **Transport abstraction in `lib/api/`** — `invoke()` in Tauri, `fetch()` in web mode | Detect via `window.__TAURI__` or build-time `import.meta.env.VITE_ADMIN_WEB`. Same function signatures, different backend. |
-| 7 | OAuth consent | **Re-enable guarded HTTP consent endpoint** for web admin only — `POST /api/v1/oauth/consent/approve` behind CF Access + CSRF token | Production desktop keeps Tauri-IPC-only consent (existing security model). Web mode needs an HTTP path because there is no Tauri shell on Weathertop. |
-| 8 | Bind address | **Default `127.0.0.1:45819`** — same loopback-first posture as MCP gateway | CF tunnel reaches localhost; no need to bind `0.0.0.0`. `AGENTS.md` loopback rule preserved. |
-| 9 | Event streaming | **SSE at `/api/v1/events`** bridging existing `EventBus` | Replaces Tauri event listeners (`useDomainEvents`) in web mode. Desktop keeps Tauri events. |
-| 10 | Scope phasing | **Read-only views first, then writes, then OAuth** | Each phase is independently testable behind CF Access. Avoids a big-bang API dump. |
-
----
-
-## The Model
-
-### What web admin mode is
-
-An optional HTTP server started alongside (or instead of) the Tauri window when `gateway.admin_enabled` is true:
-
-```text
-AdminServer (Axum, :45819)
-├── GET  /*                    → SPA static files (frontendDist)
-├── GET  /api/v1/health       → { status: "ok", gateway_running: bool }
-├── GET  /api/v1/events       → SSE stream (EventBus bridge)
-├── /api/v1/gateway/*         → gateway commands
-├── /api/v1/spaces/*          → space commands
-├── /api/v1/servers/*         → server manager + install + clone
-├── /api/v1/workspaces/*      → workspace bindings + session overrides
-├── /api/v1/feature-sets/*    → feature sets + members
-├── /api/v1/clients/*         → inbound MCP clients
-├── /api/v1/oauth/*           → consent approve/reject (web only)
-└── /api/v1/settings/*        → app settings
-```
-
-All handlers delegate to the same `ApplicationServices` / command-layer logic Tauri uses today — no duplicated business logic.
-
-### What web admin mode is NOT
-
-- Not a hosted multi-tenant SaaS ("McpMux Cloud")
-- Not a replacement for the Tauri desktop app on Gondor (desktop remains primary for local use)
-- Not exposing the MCP gateway without separate hardening (that route stays on `:45818` with its own OAuth JWT model)
-- Not moving secrets off OS keychain — encryption keys stay local
-
-### Homelab tunnel layout (target)
-
-```yaml
-# gondor cloudflared config (addition to home-lab-wiring-plan.md Step 5)
-ingress:
-  - hostname: mux.joe-hassio.com
-    service: http://localhost:45819    # NEW — admin UI
-  - hostname: mcp.joe-hassio.com
-    service: http://localhost:45818    # existing — MCP clients
-  - hostname: code.joe-hassio.com
-    service: http://localhost:3001     # existing — ClaudeCodeUI
-  - service: http_status:404
-```
-
-CF Access policy on `mux.joe-hassio.com`: allow `jsangio1@gmail.com` (or equivalent Zero Trust rule).
-
----
-
-## Architecture
-
-```
-Weathertop / Rohan browser
-        │
-        │ HTTPS + CF Access (Google login)
-        ▼
-  mux.joe-hassio.com ──── cloudflared tunnel ────► localhost:45819
-                                                          │
-                              ┌───────────────────────────┤
-                              │                           │
-                              ▼                           ▼
-                    ┌──────────────────┐        ┌──────────────────┐
-                    │  Static SPA      │        │  /api/v1/* REST  │
-                    │  (frontendDist)  │        │  + SSE /events   │
-                    └──────────────────┘        └────────┬─────────┘
-                                                         │
-                                                         ▼
-                                              ┌──────────────────────┐
-                                              │ ApplicationServices  │
-                                              │ (same as Tauri cmds) │
-                                              └──────────┬───────────┘
-                                                         │
-                    ┌────────────────────────────────────┼────────────────────┐
-                    ▼                                    ▼                    ▼
-              SQLite +                           OS Keychain              Gateway :45818
-              AES-256-GCM                          JWT secret              (unchanged)
-```
-
-**Middleware stack (admin router):**
-
-1. `CF-Access-Jwt-Assertion` validation (when enabled)
-2. CSRF token check on mutating routes (web OAuth consent)
-3. Request logging (sanitized — no secrets)
-4. CORS: deny by default; allow same-origin only (SPA served from same host)
-
-**Frontend transport switch:**
-
-```typescript
-// lib/api/transport.ts (new)
-export async function apiCall<T>(command: string, args?: Record<string, unknown>): Promise<T> {
-  if (isTauri()) {
-    return invoke(command, args);
-  }
-  return fetchApi<T>(command, args);
-}
-```
-
-Existing `lib/api/*.ts` modules swap `invoke(...)` → `apiCall(...)` with no signature changes.
-
----
-
-## Files to create
-
-| File | Purpose |
-| ---- | ------- |
-| `crates/mcpmux-gateway/src/admin/mod.rs` | Admin router module entry |
-| `crates/mcpmux-gateway/src/admin/server.rs` | `AdminServer` — bind, static file serving, route mounting |
-| `crates/mcpmux-gateway/src/admin/middleware/cf_access.rs` | Validate `CF-Access-Jwt-Assertion` against CF team domain certs |
-| `crates/mcpmux-gateway/src/admin/middleware/csrf.rs` | CSRF token generation + validation for mutating routes |
-| `crates/mcpmux-gateway/src/admin/handlers/mod.rs` | Handler module tree |
-| `crates/mcpmux-gateway/src/admin/handlers/gateway.rs` | Gateway status/start/stop REST handlers |
-| `crates/mcpmux-gateway/src/admin/handlers/spaces.rs` | Space CRUD handlers |
-| `crates/mcpmux-gateway/src/admin/handlers/servers.rs` | Server manager + install + clone handlers |
-| `crates/mcpmux-gateway/src/admin/handlers/workspaces.rs` | Workspace binding + session override handlers |
-| `crates/mcpmux-gateway/src/admin/handlers/feature_sets.rs` | FeatureSet + member handlers |
-| `crates/mcpmux-gateway/src/admin/handlers/clients.rs` | Inbound MCP client handlers |
-| `crates/mcpmux-gateway/src/admin/handlers/oauth.rs` | Web consent approve/reject handlers |
-| `crates/mcpmux-gateway/src/admin/handlers/settings.rs` | App settings handlers |
-| `crates/mcpmux-gateway/src/admin/handlers/events.rs` | SSE EventBus bridge |
-| `crates/mcpmux-gateway/src/admin/command_bridge.rs` | Shared helper: call Tauri command logic without Tauri runtime |
-| `apps/desktop/src/lib/api/transport.ts` | Tauri vs fetch transport abstraction |
-| `apps/desktop/src/lib/api/fetch-api.ts` | REST client mapping command names → HTTP paths |
-| `apps/desktop/src/hooks/useDomainEventsWeb.ts` | SSE-based event listener for web mode |
-| `tests/rust/tests/integration/admin_api.rs` | Admin API integration tests (health, auth rejection, read endpoints) |
-| `docs/planning/web-admin-remote-access.md` | This doc |
-
-## Files to modify
-
-| File | Change |
-| ---- | ------ |
-| [`crates/mcpmux-gateway/src/lib.rs`](../../crates/mcpmux-gateway/src/lib.rs) | `pub mod admin;` |
-| [`crates/mcpmux-gateway/src/server/mod.rs`](../../crates/mcpmux-gateway/src/server/mod.rs) | `GatewayConfig` gains `admin_enabled`, `admin_port`, `admin_trust_cf_access`, `admin_cf_team_domain` |
-| [`apps/desktop/src-tauri/src/lib.rs`](../../apps/desktop/src-tauri/src/lib.rs) | Start `AdminServer` when setting enabled; share `ApplicationServices` Arc |
-| [`apps/desktop/src-tauri/src/commands/gateway.rs`](../../apps/desktop/src-tauri/src/commands/gateway.rs) | Extract shared gateway logic callable from admin handlers |
-| [`apps/desktop/src/lib/api/*.ts`](../../apps/desktop/src/lib/api/) | Replace direct `invoke()` with `apiCall()` from transport layer |
-| [`apps/desktop/src/hooks/useDomainEvents.ts`](../../apps/desktop/src/hooks/useDomainEvents.ts) | Delegate to SSE hook in web mode |
-| [`apps/desktop/src/features/oauth/OAuthConsentModal.tsx`](../../apps/desktop/src/features/oauth/OAuthConsentModal.tsx) | Web mode: POST to `/api/v1/oauth/consent/approve` instead of Tauri command |
-| [`apps/desktop/src/features/settings/SettingsPage.tsx`](../../apps/desktop/src/features/settings/SettingsPage.tsx) | Admin mode toggle + port setting |
-| [`apps/desktop/vite.config.ts`](../../apps/desktop/vite.config.ts) | `VITE_ADMIN_WEB` build flag for web-only builds |
-| [`apps/desktop/package.json`](../../apps/desktop/package.json) | `build:web:admin` script — production SPA build for admin serving |
-| [`tests/e2e/playwright.config.ts`](../../tests/e2e/playwright.config.ts) | Optional admin web E2E project against `:45819` with mocked CF JWT |
-| [`AGENTS.md`](../../AGENTS.md) | Document admin server loopback binding + CF Access requirement |
-
----
-
-## Phasing
-
-### Phase 1 — Admin server skeleton + static SPA + CF Access gate
-
-**Effort:** ~2 days
-
-- [ ] `AdminServer` Axum router on `127.0.0.1:45819` (configurable)
-- [ ] Serve `frontendDist` with SPA fallback (`index.html` for unknown routes)
-- [ ] `GET /api/v1/health` — returns gateway running status
-- [ ] CF Access middleware: validate `CF-Access-Jwt-Assertion` when `admin_trust_cf_access` is true; 401 without it
-- [ ] Settings: `gateway.admin_enabled` (default `false`), `gateway.admin_port` (default `45819`)
-- [ ] Start admin server from Tauri app when setting enabled (alongside gateway)
-- [ ] Unit test: health endpoint returns 200; unauthenticated request returns 401 when CF Access enabled
-
-**Outcome:** With admin mode enabled and a valid CF Access JWT, `https://mux.joe-hassio.com` (via tunnel) loads the McpMux UI shell. API calls still fail (no handlers yet), but static assets render and auth gate works.
-
-### Phase 2 — Transport abstraction + read-only API
-
-**Effort:** ~3 days
-
-- [ ] `transport.ts` + `fetch-api.ts` — command name → HTTP path mapping
-- [ ] Refactor all `lib/api/*.ts` modules to use `apiCall()`
-- [ ] `command_bridge.rs` — extract shared logic from Tauri commands into functions callable from both IPC and HTTP
-- [ ] Read-only handlers: gateway status, list spaces, list installed servers, list workspace bindings, list feature sets, list clients, list session overrides, get settings
-- [ ] `GET /api/v1/events` — SSE bridge from `EventBus`
-- [ ] `useDomainEventsWeb.ts` — SSE listener; `useDomainEvents` switches on environment
-- [ ] Integration tests for each read endpoint
-
-**Outcome:** From Weathertop, authenticated user can browse Spaces, My Servers, Workspaces, FeatureSets, Clients, and Settings in read-only mode. Domain events (server connected, gateway started) stream via SSE. No writes yet.
-
-### Phase 3 — Write API (config mutations)
-
-**Effort:** ~4 days
-
-- [ ] Write handlers: install/uninstall server, enable/disable, configure inputs, clone server, CRUD spaces, CRUD workspace bindings, CRUD feature sets + members, gateway start/stop, export config, clear session overrides, update settings
-- [ ] CSRF middleware on all `POST`/`PUT`/`DELETE` routes
-- [ ] Error mapping: domain errors → HTTP status codes with JSON body
-- [ ] Integration tests: install + configure + enable round-trip via HTTP
-- [ ] Playwright admin web E2E: smoke test install flow against `:45819`
-
-**Outcome:** Full admin CRUD works from the browser. User can install servers, edit credentials, manage bindings and FeatureSets, start/stop gateway — all remote. OAuth consent still requires Phase 4.
-
-### Phase 4 — Web OAuth consent
-
-**Effort:** ~2 days
-
-- [ ] `POST /api/v1/oauth/consent/approve` and `/reject` — guarded HTTP endpoints (web admin only; desktop keeps Tauri IPC)
-- [ ] CSRF + consent token validation (reuse existing cryptographic consent token from gateway)
-- [ ] `OAuthConsentModal.tsx` — web path posts to HTTP endpoint; desktop path unchanged
-- [ ] Deep link bridge: `mcpmux://` URLs on Gondor still work for desktop; web mode polls consent pending state via SSE
-- [ ] Integration test: OAuth authorize → consent approve via HTTP → token issued
-
-**Outcome:** Remote user can complete OAuth flows (Notion, GitHub, Google Workspace, etc.) from the browser without needing the Tauri shell on Gondor.
-
-### Phase 5 — Homelab integration + docs
-
-**Effort:** ~1 day
-
-- [ ] Update [`jsg-tech-check/docs/setup/home-lab-wiring-plan.md`](../../../jsg-tech-check/docs/setup/home-lab-wiring-plan.md) Step 5 with `mux.joe-hassio.com` ingress rule
-- [ ] Document CF Access policy setup for `mux.joe-hassio.com`
-- [ ] Add admin mode section to [`docs/guide/gateway.mdx`](../../docs/guide/gateway.mdx)
-- [ ] `pnpm build:web:admin` + verify production SPA served correctly from admin server
-- [ ] End-to-end smoke from Weathertop: open `https://mux.joe-hassio.com`, manage a server, approve OAuth
-
-**Outcome:** Homelab wiring plan reflects the third public hostname. Operator can manage McpMux from phone/laptop browser with CF Access auth.
-
----
-
-## Pre-PR validation
-
-| Step | Command | Purpose |
-| ---- | ------- | ------- |
-| Full validate | `pnpm validate` | fmt, clippy, check, eslint, typecheck |
-| Rust tests | `pnpm test:rust` | unit + integration (`admin_api.rs`) |
-| TS tests | `pnpm test:ts` | vitest (transport layer) |
-| Admin web E2E | `pnpm test:e2e:web:admin` (new) | Playwright against `:45819` |
-| Manual smoke | Enable admin mode, tunnel `mux.joe-hassio.com`, browse from phone | UX + CF Access verification |
-
----
-
-## Out of scope
-
-| Item | Reason |
-| ---- | ------ |
-| Multi-tenant / per-user accounts | Single-user homelab. Adding user management is a different product. |
-| Cloud KMS / secrets off OS keychain | Admin server runs on Gondor; keychain access is preserved. No remote secret vault needed. |
-| Binding admin server to `0.0.0.0` | Loopback + CF tunnel is the access path. Direct internet bind violates `AGENTS.md` posture. |
-| Replacing Tauri desktop app | Desktop remains primary on Gondor. Web admin is for remote access only. |
-| Mobile-optimized responsive UI | React app works in mobile browser but no dedicated mobile layout pass. Acceptable for v1 homelab use. |
-| Public MCP gateway hardening (`mcp.joe-hassio.com`) | Separate concern — OAuth JWT auth exists but unauthenticated admin routes on `:45818` need CF Access too. Track as follow-up, not blocked on this doc. |
-| WebSocket transport (instead of SSE) | SSE is sufficient for EventBus fan-out. WebSocket adds complexity with no v1 benefit. |
-| Headless-only mode (no Tauri window) | v1 starts admin server from Tauri app. Headless/systemd mode is a follow-up for Rivendell-style deployment. |
-
----
-
-## Key files referenced
-
-| File | Why |
-| ---- | --- |
-| [`apps/desktop/src/lib/api/gateway.ts`](../../apps/desktop/src/lib/api/gateway.ts) | Largest API module (~20 invokes) — template for transport refactor |
-| [`apps/desktop/src-tauri/src/commands/mod.rs`](../../apps/desktop/src-tauri/src/commands/mod.rs) | Command module registry — each module gets a corresponding admin handler |
-| [`crates/mcpmux-gateway/src/server/mod.rs`](../../crates/mcpmux-gateway/src/server/mod.rs) | Existing Axum gateway — pattern reference for admin router |
-| [`crates/mcpmux-gateway/src/server/mod.rs`](../../crates/mcpmux-gateway/src/server/mod.rs) (lines 340–365) | OAuth consent removed from HTTP for security — web admin re-adds guarded version |
-| [`apps/desktop/src/hooks/useDomainEvents.ts`](../../apps/desktop/src/hooks/useDomainEvents.ts) | Tauri event listener — needs SSE equivalent for web mode |
-| [`jsg-tech-check/docs/setup/home-lab-wiring-plan.md`](../../../jsg-tech-check/docs/setup/home-lab-wiring-plan.md) | CF tunnel config — gets `mux.joe-hassio.com` ingress in Phase 5 |
-
----
-
-## Related documentation
-
-- [`jsg-tech-check/docs/setup/home-lab-wiring-plan.md`](../../../jsg-tech-check/docs/setup/home-lab-wiring-plan.md) — Step 5 (CF tunnel), Step 6 (McpMux on Gondor), cross-device MCP access
-- [`jsg-tech-check/docs/setup/mcpmux-server-migration.md`](../../../jsg-tech-check/docs/setup/mcpmux-server-migration.md) — server/bundle/binding migration tracker (orthogonal to web admin)
-- [`docs/guide/security.mdx`](../../docs/guide/security.mdx) — credential encryption model (unchanged by web admin)
-- [`docs/planning/dynamic-mcp-toggle-meta-tools.md`](./dynamic-mcp-toggle-meta-tools.md) — session override UI that web admin must expose via HTTP
-- [`docs/planning/server-account-clones.md`](./server-account-clones.md) — clone wizard that web admin must expose via HTTP
-
----
-
-## Reconciliation
-
-This doc is the source of truth for web admin mode. When implementation starts, update **Status** and **Branch** at the top. Phase 5 homelab doc updates live in `jsg-tech-check` — track cross-repo separately.
-
-**Decision record (May 25, 2026):** Web admin mode on fork selected over screen sharing (immediate but not web UI), tunneling `:1420` (broken), and full "McpMux Cloud" multi-tenant SaaS (months of work). CF Access at edge replaces building login UI. Separate admin port (`45819`) keeps MCP gateway surface unchanged.
diff --git a/docs/run-from-source-macos.md b/docs/run-from-source-macos.md
deleted file mode 100644
index 2a309216..00000000
--- a/docs/run-from-source-macos.md
+++ /dev/null
@@ -1,258 +0,0 @@
-# Run McpMux from Source (macOS)
-
-Two flows for working against this repo, picked by what you're doing:
-
-| Flow | Use when | Speed | Cursor / Claude / VS Code see it? |
-| ---- | -------- | ----- | --------------------------------- |
-| **Dev watch mode** (`pnpm dev`) | Iterating on UI or Rust — you want HMR for React and auto-recompile for Tauri commands | Vite HMR is instant; Rust changes ~5–15s incremental | Yes — same `localhost:45818` endpoint while `pnpm dev` is running |
-| **Build + swap** (replace `/Applications/McpMux.app`) | You want a real installed app on this branch — autostart, system tray, runs without a terminal, survives reboot | Full build ~5–10 min, incremental ~1–3 min | Yes — and stays running after you close your editor |
-
-Quick rule of thumb: **`pnpm dev` while you're coding, swap when you're done** so other AI clients keep working when Cursor isn't open.
-
----
-
-## What survives between flows
-
-Both dev mode and a swapped `.app` use the same `com.mcpmux.desktop` bundle identifier, so they share data:
-
-| Data | Location |
-| ---- | -------- |
-| SQLite DB (spaces, servers, clients, settings) | `~/Library/Application Support/com.mcpmux.desktop/mcpmux.db` |
-| Per-space files | `~/Library/Application Support/com.mcpmux.desktop/spaces/` |
-| Logs | `~/Library/Application Support/com.mcpmux.desktop/logs/` |
-| Encryption master key | macOS Keychain (`com.mcpmux.desktop` service) |
-| OAuth tokens / credentials | Encrypted in SQLite + Keychain |
-
-The new binary reads the same data dir and keychain entries as the release. Spaces, server installs, and access keys persist across `pnpm dev` ↔ `/Applications` swaps.
-
-**What you might need to redo:** OAuth re-auth in Cursor/Claude Desktop if DCR or token validation changed on your branch.
-
----
-
-## Prerequisites
-
-From repo root (`mcp-mux/`):
-
-- Rust 1.75+
-- Node.js 20+
-- pnpm 9+
-- Xcode Command Line Tools (`xcode-select --install`)
-
-First-time setup (if deps aren't installed):
-
-```bash
-pnpm install
-```
-
----
-
-## Flow 1 — Dev watch mode (`pnpm dev`)
-
-Live-reload while you code. Best for tight iteration on UI or Rust.
-
-### What it does
-
-| Layer | Behavior |
-| ----- | -------- |
-| React / Tailwind / TS | Vite dev server on `localhost:1420` with **HMR** — change a `.tsx`/`.css`, see it instantly without losing app state |
-| Rust (Tauri commands, gateway, storage) | Recompiles + relaunches the Tauri window on any `.rs` save under `src-tauri/` or `crates/` |
-| Bundle ID | Same `com.mcpmux.desktop` — reads your real DB and Keychain entries |
-
-### Run it
-
-```bash
-# Quit the installed app first so the dev gateway can bind 127.0.0.1:45818
-osascript -e 'tell application "McpMux" to quit' 2>/dev/null; sleep 2
-
-pnpm dev
-```
-
-A Tauri window opens. Edit `.tsx` files for instant HMR; edit Rust and the window will relaunch on its own after recompile.
-
-### Frontend-only iteration
-
-If you're only changing UI and want the fastest possible loop:
-
-```bash
-pnpm dev:web
-```
-
-This runs Vite alone in a browser tab — no Rust, no Tauri shell. Tauri `invoke()` calls won't work (no backend), but for pure layout/styling work it's the quickest path.
-
-### Gotchas
-
-| Symptom | Why | Fix |
-| ------- | --- | --- |
-| Keychain prompts on first launch of the dev binary | Different signer than `/Applications/McpMux.app` | Click **Always Allow** once — sticks for that built artifact. See `Keychain prompts` below for detail |
-| `Address already in use: 45818` | Installed `.app` still running | `osascript -e 'tell application "McpMux" to quit'` then retry |
-| Cursor's MCP server "disconnected" mid-session | You stopped `pnpm dev` | Cursor reconnects when the gateway is back on `localhost:45818` (either flow) |
-| Rust recompile feels slow | Big edits in `mcpmux-gateway` / `mcpmux-storage` | Expected — keep edits scoped or use `pnpm dev:web` for UI |
-| `pnpm dev` keeps crashing with "Master key not found" | DB/keychain mismatch from manual deletion | Don't manually delete keychain entries — see `Keychain prompts` below |
-
-### Keychain prompts
-
-McpMux reads two secrets from Keychain on startup:
-
-1. **Master encryption key** — every app launch (decrypts SQLite credentials)
-2. **JWT signing secret** — first time you start the gateway in a session
-
-macOS scopes Keychain access to the **specific signed binary**, not just the bundle ID. So:
-
-- First launch of a `pnpm dev` build → 1–2 prompts
-- First launch after a fresh `pnpm build` swap → 1–2 prompts
-- Subsequent launches of the **same** built binary → silent if you clicked **Always Allow**
-- Alternating between `pnpm dev` and `/Applications/McpMux.app` → may re-prompt because each is a different signer
-
-This is expected. Click **Always Allow** the first time you see each prompt for a new build.
-
----
-
-## Flow 2 — Build and swap into `/Applications`
-
-Use when you want the source build to behave like an installed app: launch from Spotlight/Dock, autostart, run in the background without a dev terminal, survive reboots.
-
-### Option A — Full build (recommended)
-
-Rebuilds the React frontend and produces a fresh `.app` bundle. Use this when frontend or Tauri config changed, or when you want a clean bundle.
-
-#### 1. Quit the running app
-
-```bash
-osascript -e 'tell application "McpMux" to quit' 2>/dev/null || true
-# Give it a moment to release the gateway port
-sleep 2
-```
-
-#### 2. Build
-
-```bash
-cd /path/to/mcp-mux
-pnpm build
-```
-
-First build: ~5–10 min. Incremental: ~1–3 min.
-
-Output:
-
-```
-target/release/bundle/macos/McpMux.app
-target/release/bundle/dmg/McpMux_*.dmg   # optional installer artifact
-```
-
-> **Note:** the build may exit non-zero at the very end with `TAURI_SIGNING_PRIVATE_KEY` missing. That only blocks the auto-update artifact; the `.app` and `.dmg` are still produced and usable.
-
-#### 3. Backup and swap
-
-```bash
-# Backup current install (skip if you already have a recent .bak)
-sudo mv /Applications/McpMux.app /Applications/McpMux.app.bak
-
-# Install the new build
-sudo cp -R target/release/bundle/macos/McpMux.app /Applications/
-
-# Fix ownership (sudo cp leaves root-owned files)
-sudo chown -R "$(whoami):admin" /Applications/McpMux.app
-```
-
-#### 4. Re-sign (required after manual swap)
-
-macOS Gatekeeper rejects a bundle whose binary was replaced without re-signing:
-
-```bash
-xattr -dr com.apple.quarantine /Applications/McpMux.app 2>/dev/null || true
-codesign --force --deep --sign - /Applications/McpMux.app
-```
-
-#### 5. Launch
-
-```bash
-open /Applications/McpMux.app
-```
-
-Verify: spaces, installed servers, and gateway on `localhost:45818` should look exactly as before. First launch will trigger 1–2 Keychain prompts because the new ad-hoc signature is a different signer than the previous build — click **Always Allow** once and you're set until the next swap.
-
-### Option B — Binary-only swap (fast path)
-
-When you changed **Rust only** (no frontend, no `tauri.conf.json` changes). Skips the Vite build and DMG step.
-
-```bash
-osascript -e 'tell application "McpMux" to quit' 2>/dev/null || true
-sleep 2
-
-cd /path/to/mcp-mux
-cargo build --release -p mcpmux
-
-cp /Applications/McpMux.app/Contents/MacOS/mcpmux \
-   /Applications/McpMux.app/Contents/MacOS/mcpmux.bak
-cp target/release/mcpmux /Applications/McpMux.app/Contents/MacOS/mcpmux
-
-xattr -dr com.apple.quarantine /Applications/McpMux.app 2>/dev/null || true
-codesign --force --deep --sign - /Applications/McpMux.app
-
-open /Applications/McpMux.app
-```
-
-Keeps the existing bundle shell (icons, Info.plist, embedded frontend from last full build). Only the Rust binary updates.
-
----
-
-## Rollback (Flow 2 only)
-
-If a swapped build is broken, restore the previous `/Applications/McpMux.app`. Dev-mode (`pnpm dev`) doesn't need a rollback — just stop the dev process.
-
-### Full build rollback
-
-```bash
-osascript -e 'tell application "McpMux" to quit' 2>/dev/null || true
-sudo rm -rf /Applications/McpMux.app
-sudo mv /Applications/McpMux.app.bak /Applications/McpMux.app
-open /Applications/McpMux.app
-```
-
-### Binary-only rollback
-
-```bash
-osascript -e 'tell application "McpMux" to quit' 2>/dev/null || true
-cp /Applications/McpMux.app/Contents/MacOS/mcpmux.bak \
-   /Applications/McpMux.app/Contents/MacOS/mcpmux
-codesign --force --deep --sign - /Applications/McpMux.app
-open /Applications/McpMux.app
-```
-
----
-
-## Troubleshooting
-
-| Symptom | Applies to | Fix |
-| ------- | ---------- | --- |
-| "App is damaged" / won't open | Flow 2 | Re-run `codesign --force --deep --sign - /Applications/McpMux.app` |
-| Gateway port already in use | Both | Old process still running — `pkill -f mcpmux` then relaunch |
-| Cursor OAuth fails after swap | Both | Re-trigger MCP OAuth in Cursor (DCR redirect URI validation may have changed) |
-| Empty app / missing UI | Flow 2 (Option B) | You used binary-only swap but frontend changed — run Option A (full build) |
-| Permission denied on `/Applications` | Flow 2 | Use `sudo` for mv/cp/chown, or install to `~/Applications/` and skip sudo |
-| Keychain prompts on every launch of the same binary | Both | Click **Always Allow** (not just **Allow**); check Keychain Access for duplicate `master-encryption-key` / `jwt-signing-secret` entries from old signers |
-| `pnpm dev` won't start — `EADDRINUSE 45818` | Flow 1 | The installed `.app` is still running — quit it before `pnpm dev` |
-
----
-
-## One-liner (full build + swap)
-
-Assumes you're in repo root and have a recent backup:
-
-```bash
-osascript -e 'tell application "McpMux" to quit' 2>/dev/null; sleep 2 && \
-pnpm build && \
-sudo rm -rf /Applications/McpMux.app && \
-sudo cp -R target/release/bundle/macos/McpMux.app /Applications/ && \
-sudo chown -R "$(whoami):admin" /Applications/McpMux.app && \
-xattr -dr com.apple.quarantine /Applications/McpMux.app 2>/dev/null; \
-codesign --force --deep --sign - /Applications/McpMux.app && \
-open /Applications/McpMux.app
-```
-
----
-
-## Related
-
-- [`AGENTS.md`](../AGENTS.md) — build commands and project layout
-- [`CLAUDE.md`](../CLAUDE.md) — full dev environment reference