docs: update auto-approval documentation for fine-grained control

ravitemer · ravitemer · commit 33bd4d3f6df5 · 2025-05-28T05:44:50.000Z
- Add autoApprove field documentation to servers.json config
- Update CodeCompanion and Avante extension docs with new auto-approval options
- Add UI interaction instructions for 'a' keymap
- Document auto-approval priority order and configuration examples
diff --git a/doc/configuration.md b/doc/configuration.md
@@ -141,10 +141,12 @@ By default when the LLM calls a tool or resource on a MCP server, we show a conf
 
 ![Image](https://github.com/user-attachments/assets/201a5804-99b6-4284-9351-348899e62467)
 
-Set it to to `true` to automatically approve MCP tool calls without user confirmation. This also sets `vim.g.mcphub_auto_approve` variable to `true`. You can toggle this option in the MCP Hub UI with `ga` keymap. You can see the current auto approval status in the Hub UI.
+Set it to `true` to automatically approve all MCP tool calls without user confirmation. This also sets `vim.g.mcphub_auto_approve` variable to `true`. You can toggle this option in the MCP Hub UI with `ga` keymap. You can see the current auto approval status in the Hub UI.
 
 ![Image](https://github.com/user-attachments/assets/64708065-3428-4eb3-82a5-e32d2d1f98c6)
 
+**Fine-Grained Auto-Approval**: For more granular control, configure auto-approval per server or per tool using the `autoApprove` field in your `servers.json`. You can also toggle auto-approval from the Hub UI using the `a` keymap on individual servers or tools. See [servers.json configuration](/mcp/servers_json#auto-approval-configuration) for detailed examples and configuration options.
+
 ### auto_toggle_mcp_servers
 
 Default: `true`
@@ -256,3 +258,4 @@ Logging configuration options:
 
 
 
+
diff --git a/doc/extensions/avante.md b/doc/extensions/avante.md
@@ -75,17 +75,54 @@ By default, whenever avante calls `use_mcp_tool` or `access_mcp_resource` tool,
 
 ![Image](https://github.com/user-attachments/assets/201a5804-99b6-4284-9351-348899e62467)
 
-You can set `auto_approve` to `true` to automatically approve MCP tool calls without user confirmation.
+### Global Auto-Approval
+
+You can set `auto_approve` to `true` to automatically approve all MCP tool calls without user confirmation:
+
 ```lua
 require("mcphub").setup({
     -- This sets vim.g.mcphub_auto_approve to true by default (can also be toggled from the HUB UI with `ga`)
     auto_approve = true, 
 })
 ```
+
 This also sets `vim.g.mcphub_auto_approve` variable to `true`. You can also toggle this option in the MCP Hub UI with `ga` keymap. You can see the current auto approval status in the Hub UI.
 
 ![Image](https://github.com/user-attachments/assets/64708065-3428-4eb3-82a5-e32d2d1f98c6)
 
+### Fine-Grained Auto-Approval
+
+For more control, configure auto-approval per server or per tool in your `servers.json`:
+
+```json
+{
+    "mcpServers": {
+        "trusted-server": {
+            "command": "npx",
+            "args": ["trusted-mcp-server"],
+            "autoApprove": true  // Auto-approve all tools on this server
+        },
+        "partially-trusted": {
+            "command": "npx", 
+            "args": ["some-mcp-server"],
+            "autoApprove": ["read_file", "list_files"]  // Only auto-approve specific tools
+        }
+    }
+}
+```
+
+You can also toggle auto-approval from the Hub UI:
+- Press `a` on a server line to toggle auto-approval for all tools on that server
+- Press `a` on an individual tool to toggle auto-approval for just that tool
+- Resources are always auto-approved (no configuration needed)
+
+### Auto-Approval Priority
+
+The system checks auto-approval in this order:
+1. **Global**: `vim.g.mcphub_auto_approve = true` (approves everything)
+2. **Server-specific**: `autoApprove` field in server config
+3. **Default**: Show confirmation dialog
+
 
 ## Usage
 
@@ -94,3 +131,4 @@ This also sets `vim.g.mcphub_auto_approve` variable to `true`. You can also togg
 3. Avante will call `use_mcp_tool` and `access_mcp_resource` tools when necessary
 
 
+
diff --git a/doc/extensions/codecompanion.md b/doc/extensions/codecompanion.md
@@ -59,7 +59,9 @@ By default, whenever codecompanion calls `use_mcp_tool` or `access_mcp_resource`
 
 ![Image](https://github.com/user-attachments/assets/201a5804-99b6-4284-9351-348899e62467)
 
-1. You can set `auto_approve` to `true` to automatically approve MCP tool calls without user confirmation.
+### Global Auto-Approval
+
+You can set `auto_approve` to `true` to automatically approve all MCP tool calls without user confirmation:
 
 ```lua
 require("mcphub").setup({
@@ -72,5 +74,38 @@ This also sets `vim.g.mcphub_auto_approve` variable to `true`. You can also togg
 
 ![Image](https://github.com/user-attachments/assets/64708065-3428-4eb3-82a5-e32d2d1f98c6)
 
-2. MCP Hub also respects CodeCompanion auto tool mode: `vim.g.codecompanion_auto_tool_mode = true` (toggled via `gta` in the chat buffer)
+### Fine-Grained Auto-Approval
+
+For more control, configure auto-approval per server or per tool in your `servers.json`:
+
+```json
+{
+    "mcpServers": {
+        "trusted-server": {
+            "command": "npx",
+            "args": ["trusted-mcp-server"],
+            "autoApprove": true  // Auto-approve all tools on this server
+        },
+        "partially-trusted": {
+            "command": "npx", 
+            "args": ["some-mcp-server"],
+            "autoApprove": ["read_file", "list_files"]  // Only auto-approve specific tools
+        }
+    }
+}
+```
+
+You can also toggle auto-approval from the Hub UI:
+- Press `a` on a server line to toggle auto-approval for all tools on that server
+- Press `a` on an individual tool to toggle auto-approval for just that tool
+- Resources are always auto-approved (no configuration needed)
+
+### Auto-Approval Priority
+
+The system checks auto-approval in this order:
+1. **Global**: `vim.g.mcphub_auto_approve = true` (approves everything)
+2. **CodeCompanion**: `vim.g.codecompanion_auto_tool_mode = true` (toggled via `gta` in chat buffer)
+3. **Server-specific**: `autoApprove` field in server config
+4. **Default**: Show confirmation dialog
+
 
diff --git a/doc/mcp/servers_json.md b/doc/mcp/servers_json.md
@@ -169,6 +169,7 @@ MCPHub adds several extra keys for each server automatically from the UI:
             "disabled_tools": ["expensive-tool"],
             "disabled_resources": ["resource://large-data"],
             "disabled_resourceTemplates": ["resource://{type}/{id}"],
+            "autoApprove": ["safe-tool", "read-only-tool"],
             "custom_instructions": {
                 "disabled": false,
                 "text": "Custom instructions for this server"
@@ -178,5 +179,21 @@ MCPHub adds several extra keys for each server automatically from the UI:
 }
 ```
 
+### Auto-Approval Configuration
+
+The `autoApprove` field allows fine-grained control over which tools are automatically approved without user confirmation:
+
+| Value | Behavior | Example |
+|-------|----------|---------|
+| `true` | Auto-approve all tools on this server | `"autoApprove": true` |
+| `["tool1", "tool2"]` | Auto-approve only specific tools | `"autoApprove": ["read_file", "list_files"]` |
+| `[]` or omitted | No auto-approval (show confirmation dialog) | `"autoApprove": []` |
+
+**Notes:**
+- Resources are always auto-approved by default (no explicit configuration needed)
+- Auto-approval only applies to enabled servers and enabled tools
+- You can toggle auto-approval from the UI using the `a` keymap on servers or individual tools
+
+
 
 
