Change dynamic-tools feature to opt-in and streamline tools

The dynamic-tools feature now defaults to disabled instead of enabled, making it an opt-in capability. This provides better control over when automatic server management tools are available.

Key changes:
- Default dynamic-tools to disabled in feature flags and gateway logic
- Auto-disable dynamic-tools when --servers flag is used (explicit mode)
- Streamline available dynamic tools (remove mcp-registry-import, mcp-session-name, mcp-discover prompt)
- Adjust mcp-add to only send tool JSON for Claude clients
- Add cagent example configuration
- Update documentation to reflect new behavior

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: slimslenderslacks

cmd/docker-mcp/commands/feature.go

@@ -210,7 +210,6 @@ func isFeatureEnabledFromConfig(configFile *configfile.ConfigFile, feature strin
 	// Features that are enabled by default
 	defaultEnabledFeatures := map[string]bool{
 		"mcp-oauth-dcr": true,
-		"dynamic-tools": true,
 	}
 
 	if configFile.Features == nil {

cmd/docker-mcp/commands/feature_test.go

@@ -63,15 +63,15 @@ func TestIsFeatureEnabledDynamicTools(t *testing.T) {
 			Features: make(map[string]string),
 		}
 		enabled := isFeatureEnabledFromConfig(configFile, "dynamic-tools")
-		assert.True(t, enabled, "dynamic-tools should default to enabled when missing")
+		assert.False(t, enabled, "dynamic-tools should default to disabled when missing")
 	})
 
 	t.Run("nil features map", func(t *testing.T) {
 		configFile := &configfile.ConfigFile{
 			Features: nil,
 		}
 		enabled := isFeatureEnabledFromConfig(configFile, "dynamic-tools")
-		assert.True(t, enabled, "dynamic-tools should default to enabled when Features is nil")
+		assert.False(t, enabled, "dynamic-tools should default to disabled when Features is nil")
 	})
 }
 

cmd/docker-mcp/commands/gateway.go

@@ -152,6 +152,18 @@ func gatewayCommand(docker docker.Client, dockerCli command.Cli) *cobra.Command
 				options.ServerNames = allServerNames
 			}
 
+			// Disable dynamic-tools if the user explicitly configured a set of servers via the --servers flag.
+			// When users specify servers explicitly, they're operating in a more manual mode
+			// and may not want the automatic server management tools (mcp-find, mcp-add, mcp-remove).
+			if len(options.ServerNames) > 0 && !enableAllServers {
+				if options.DynamicTools {
+					options.DynamicTools = false
+					if options.Verbose {
+						fmt.Fprintln(dockerCli.Err(), "Note: dynamic-tools disabled when using --servers flag")
+					}
+				}
+			}
+
 			return gateway.NewGateway(options, docker).Run(cmd.Context())
 		},
 	}
@@ -308,12 +320,12 @@ func isMcpOAuthDcrFeatureEnabled(dockerCli command.Cli) bool {
 func isDynamicToolsFeatureEnabled(dockerCli command.Cli) bool {
 	configFile := dockerCli.ConfigFile()
 	if configFile == nil || configFile.Features == nil {
-		return true // Default enabled when no config exists
+		return false // Default disabled when no config exists
 	}
 
 	value, exists := configFile.Features["dynamic-tools"]
 	if !exists {
-		return true // Default enabled when not in config
+		return false // Default disabled when not in config
 	}
 
 	return value == "enabled"

cmd/docker-mcp/commands/gateway_test.go

@@ -88,31 +88,31 @@ func TestIsDynamicToolsFeatureEnabled(t *testing.T) {
 			Features: map[string]string{},
 		}
 		enabled := isDynamicToolsFeatureEnabledFromConfig(configFile)
-		assert.True(t, enabled, "should return true when dynamic-tools is not set")
+		assert.False(t, enabled, "should return false when dynamic-tools is not set")
 	})
 
 	t.Run("nil config", func(t *testing.T) {
 		enabled := isDynamicToolsFeatureEnabledFromConfig(nil)
-		assert.True(t, enabled, "should return true when config is nil")
+		assert.False(t, enabled, "should return false when config is nil")
 	})
 
 	t.Run("nil features", func(t *testing.T) {
 		configFile := &configfile.ConfigFile{
 			Features: nil,
 		}
 		enabled := isDynamicToolsFeatureEnabledFromConfig(configFile)
-		assert.True(t, enabled, "should return true when features is nil")
+		assert.False(t, enabled, "should return false when features is nil")
 	})
 }
 
 // Helper function for testing (extract logic from isDynamicToolsFeatureEnabled)
 func isDynamicToolsFeatureEnabledFromConfig(configFile *configfile.ConfigFile) bool {
 	if configFile == nil || configFile.Features == nil {
-		return true // Default enabled when no config exists
+		return false // Default disabled when no config exists
 	}
 	value, exists := configFile.Features["dynamic-tools"]
 	if !exists {
-		return true // Default enabled when not in config
+		return false // Default disabled when not in config
 	}
 	return value == "enabled"
 }

docs/feature-specs/dynamic_servers.md

@@ -18,6 +18,8 @@ docker config view | grep dynamic-tools
 
 When enabled, the gateway adds five internal management tools to the available tool set.
 
+**Note**: Dynamic tools are automatically disabled when using the `--servers` flag to explicitly specify which servers to run. This is because explicit server configuration indicates a manual mode where automatic server management tools are not needed.
+
 ## Available Tools
 
 ### 1. mcp-find

examples/cagent/agent.yaml

@@ -0,0 +1,37 @@
+version: v2
+
+agents:
+  root:
+    model: claude
+    description: Root orchestrator agent that coordinates tasks and delegates to specialized sub-agents
+    instruction: |
+      You are a specialized agent with access to MCP (Model Context Protocol) server tools
+      running through the Docker MCP Gateway.
+
+      Your capabilities include:
+      - Searching for MCP servers that might help with my task
+      - Managing and discovering available MCP tools
+      - Providing detailed results from tool executions
+
+      When executing MCP tools:
+      1. List available tools if unsure what's available
+      2. Use the appropriate tool with correct parameters
+      3. Return clear, structured results to the parent agent
+      4. Handle errors gracefully and suggest alternatives
+    toolsets:
+      - type: filesystem # Grants the agent filesystem access
+      - type: todo # Enable the todo list tool
+      - type: mcp
+        command: docker
+        args:
+          - mcp
+          - gateway
+          - run
+          - --log=/Users/slim/gateway.log
+
+models:
+  claude:
+    provider: anthropic
+    model: claude-sonnet-4-0
+    max_tokens: 64000
+    thinking_budget: medium

pkg/gateway/dynamic_mcps.go

@@ -688,9 +688,17 @@ func (g *Gateway) createMcpAddTool(clientConfig *clientConfig) *ToolRegistration
 		// Build the response text
 		responseText := fmt.Sprintf("Successfully added %d tools in server '%s'. Assume that it is fully configured and ready to use.", len(addedTools), serverName)
 
-		// Include the JSON representation of the newly added tools
-		// This is useful when the client session does not support tool change notifications
-		if len(addedTools) > 0 {
+		// Get client name
+		clientName := ""
+		if req.Session.InitializeParams().ClientInfo != nil {
+			clientName = req.Session.InitializeParams().ClientInfo.Name
+		}
+
+		// Include the JSON representation of the newly added tools if client name contains "cagent" or "claude"
+		clientNameLower := strings.ToLower(clientName)
+		shouldSendTools := len(addedTools) > 0 && strings.Contains(clientNameLower, "claude")
+
+		if shouldSendTools {
 			// Create a tools list response matching the format from tools/list
 			toolsList := make([]map[string]any, 0, len(addedTools))
 			for _, tool := range addedTools {
@@ -808,6 +816,7 @@ func (g *Gateway) createMcpRemoveTool() *ToolRegistration {
 	}
 }
 
+//nolint:unused
 func (g *Gateway) createMcpRegistryImportTool(configuration Configuration, _ *clientConfig) *ToolRegistration {
 	tool := &mcp.Tool{
 		Name:        "mcp-registry-import",
@@ -943,6 +952,8 @@ func (g *Gateway) createMcpRegistryImportTool(configuration Configuration, _ *cl
 }
 
 // readServersFromURL fetches and parses server definitions from a URL
+//
+//nolint:unused
 func (g *Gateway) readServersFromURL(ctx context.Context, url string) (map[string]catalog.Server, error) {
 	servers := make(map[string]catalog.Server)
 
@@ -1098,6 +1109,8 @@ func (g *Gateway) createMcpConfigSetTool(clientConfig *clientConfig) *ToolRegist
 }
 
 // createMcpSessionNameTool implements a tool for setting the session name
+//
+//nolint:unused
 func (g *Gateway) createMcpSessionNameTool() *ToolRegistration {
 	tool := &mcp.Tool{
 		Name:        "mcp-session-name",
@@ -1170,6 +1183,8 @@ func (g *Gateway) createMcpSessionNameTool() *ToolRegistration {
 }
 
 // isValidSessionName checks if a session name contains only alphanumeric characters and hyphens
+//
+//nolint:unused
 func isValidSessionName(name string) bool {
 	for _, ch := range name {
 		if (ch < 'a' || ch > 'z') && (ch < 'A' || ch > 'Z') && (ch < '0' || ch > '9') && ch != '-' && ch != '_' {

pkg/gateway/reload.go

@@ -9,7 +9,7 @@ import (
 	"github.com/modelcontextprotocol/go-sdk/mcp"
 
 	"github.com/docker/mcp-gateway/pkg/log"
-	"github.com/docker/mcp-gateway/pkg/prompts"
+	// "github.com/docker/mcp-gateway/pkg/prompts"
 )
 
 func (g *Gateway) reloadConfiguration(ctx context.Context, configuration Configuration, serverNames []string, clientConfig *clientConfig) error {
@@ -95,42 +95,43 @@ func (g *Gateway) reloadConfiguration(ctx context.Context, configuration Configu
 		g.mcpServer.AddTool(mcpRemoveTool.Tool, mcpRemoveTool.Handler)
 		g.toolRegistrations[mcpRemoveTool.Tool.Name] = *mcpRemoveTool
 
-		// Add mcp-registry-import tool
-		mcpRegistryImportTool := g.createMcpRegistryImportTool(configuration, clientConfig)
-		g.mcpServer.AddTool(mcpRegistryImportTool.Tool, mcpRegistryImportTool.Handler)
-		g.toolRegistrations[mcpRegistryImportTool.Tool.Name] = *mcpRegistryImportTool
-
-		// Add mcp-config-set tool
-		mcpConfigSetTool := g.createMcpConfigSetTool(clientConfig)
-		g.mcpServer.AddTool(mcpConfigSetTool.Tool, mcpConfigSetTool.Handler)
-		g.toolRegistrations[mcpConfigSetTool.Tool.Name] = *mcpConfigSetTool
-
-		// Add mcp-session-name tool
-		mcpSessionNameTool := g.createMcpSessionNameTool()
-		g.mcpServer.AddTool(mcpSessionNameTool.Tool, mcpSessionNameTool.Handler)
-		g.toolRegistrations[mcpSessionNameTool.Tool.Name] = *mcpSessionNameTool
-
 		// Add codemode
 		codeModeTool := g.createCodeModeTool(clientConfig)
 		g.mcpServer.AddTool(codeModeTool.Tool, codeModeTool.Handler)
 		g.toolRegistrations[codeModeTool.Tool.Name] = *codeModeTool
 
-		// Add mcp-exec tool
+		// Add mcp-exec tool only if client name contains "claude"
 		mcpExecTool := g.createMcpExecTool()
 		g.mcpServer.AddTool(mcpExecTool.Tool, mcpExecTool.Handler)
 		g.toolRegistrations[mcpExecTool.Tool.Name] = *mcpExecTool
 
-		prompts.AddDiscoverPrompt(g.mcpServer)
+		// Add mcp-config-set tool
+		mcpConfigSetTool := g.createMcpConfigSetTool(clientConfig)
+		g.mcpServer.AddTool(mcpConfigSetTool.Tool, mcpConfigSetTool.Handler)
+		g.toolRegistrations[mcpConfigSetTool.Tool.Name] = *mcpConfigSetTool
 
-		log.Log("  > mcp-discover: prompt for learning about dynamic server management")
 		log.Log("  > mcp-find: tool for finding MCP servers in the catalog")
 		log.Log("  > mcp-add: tool for adding MCP servers to the registry")
 		log.Log("  > mcp-remove: tool for removing MCP servers from the registry")
-		log.Log("  > mcp-registry-import: tool for importing servers from MCP registry URLs")
 		log.Log("  > mcp-config-set: tool for setting configuration values for MCP servers")
-		log.Log("  > mcp-session-name: tool for setting session name to persist configuration")
 		log.Log("  > code-mode: write code that calls other MCPs directly")
 		log.Log("  > mcp-exec: execute tools that exist in the current session")
+
+		// Add mcp-registry-import tool
+		// mcpRegistryImportTool := g.createMcpRegistryImportTool(configuration, clientConfig)
+		// g.mcpServer.AddTool(mcpRegistryImportTool.Tool, mcpRegistryImportTool.Handler)
+		// g.toolRegistrations[mcpRegistryImportTool.Tool.Name] = *mcpRegistryImportTool
+
+		// Add mcp-session-name tool
+		// mcpSessionNameTool := g.createMcpSessionNameTool()
+		// g.mcpServer.AddTool(mcpSessionNameTool.Tool, mcpSessionNameTool.Handler)
+		// g.toolRegistrations[mcpSessionNameTool.Tool.Name] = *mcpSessionNameTool
+		// log.Log("  > mcp-registry-import: tool for importing servers from MCP registry URLs")
+		// log.Log("  > mcp-session-name: tool for setting session name to persist configuration")
+
+		// Add prompt
+		// prompts.AddDiscoverPrompt(g.mcpServer)
+		// log.Log("  > mcp-discover: prompt for learning about dynamic server management")
 	}
 
 	for _, prompt := range capabilities.Prompts {