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>

Author: crimsonsunset

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)
 

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

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)

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,15 +117,32 @@ 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
 
 FeatureSets are assigned to clients per Space. Go to the **Clients** page, select a client, and manage its FeatureSet grants for each Space.
 
 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

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,12 +306,13 @@ 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:**
 
 ```
 - 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)
 ```

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`
 

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