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>

Author: crimsonsunset

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.

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",

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;
         }
 

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))?;
 

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.

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");
         }

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(),

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
     }
 

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,20 +232,39 @@ 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
 
 - [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.
+- [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.

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"));
 }