feat(gateway): Phase C — FeatureSet invoke ACL + surfaced tools

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>

Author: crimsonsunset

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.

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

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>

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>

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

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