Update to be consistent with: https://docs.google.com/document/d/1tOOBJ4y9xY61QVrO18ymuVt4SO9nV-z2B4ckaL2f9IU/edit?tab=t.0#heading=h.ffto4e5dwzlf

specifically
- allow for --tools and dynamic toolset mode together
- allow for --tools and --toolsets together

Author: tommaso-moro

README.md

@@ -345,7 +345,7 @@ The environment variable `GITHUB_TOOLSETS` takes precedence over the command lin
 
 #### Specifying Individual Tools
 
-You can also configure specific tools instead of entire toolsets using the `--tools` flag. When tools are specified, they take priority over toolsets configuration, read-only mode, and dynamic toolsets.
+You can also configure specific tools using the `--tools` flag. Tools can be used independently or combined with toolsets and dynamic toolsets discovery for fine-grained control.
 
 1. **Using Command Line Argument**:
 
@@ -358,12 +358,24 @@ You can also configure specific tools instead of entire toolsets using the `--to
    GITHUB_TOOLS="get_file_contents,issue_read,create_pull_request" ./github-mcp-server
    ```
 
+3. **Combining with Toolsets** (additive):
+   ```bash
+   github-mcp-server --toolsets repos,issues --tools get_file_contents,search_code
+   ```
+   This registers all tools from `repos` and `issues` toolsets, plus `get_file_contents` and `search_code`.
+
+4. **Combining with Dynamic Toolsets** (additive):
+   ```bash
+   github-mcp-server --tools get_file_contents --dynamic-toolsets
+   ```
+   This registers `get_file_contents` plus the dynamic toolset tools (`enable_toolset`, `list_available_toolsets`, `get_toolset_tools`).
+
 **Important Notes:**
-- When `--tools` is specified, only the listed tools are registered, bypassing toolset enablement
-- Read-only mode is still respected: write tools are skipped if `--read-only` is set, even if explicitly requested
-- Dynamic toolsets are disabled when specific tools are configured
-- Resources and prompts from all toolsets are still registered to maintain functionality
+- Tools, toolsets, and dynamic toolsets can all be used together - they are additive
+- Read-only mode takes priority: write tools are skipped if `--read-only` is set, even if explicitly requested via `--tools`
+- When write tools are skipped due to read-only mode, a warning is logged to stderr
 - Tool names must match exactly (e.g., `get_file_contents`, not `getFileContents`)
+- Invalid tool names will cause the server to fail at startup with an error message
 
 ### Using Toolsets With Docker
 
@@ -378,13 +390,21 @@ docker run -i --rm \
 
 ### Using Tools With Docker
 
-When using Docker, you can pass specific tools as environment variables:
+When using Docker, you can pass specific tools as environment variables. You can also combine tools with toolsets:
 
 ```bash
+# Tools only
 docker run -i --rm \
   -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
   -e GITHUB_TOOLS="get_file_contents,issue_read,create_pull_request" \
   ghcr.io/github/github-mcp-server
+
+# Tools combined with toolsets (additive)
+docker run -i --rm \
+  -e GITHUB_PERSONAL_ACCESS_TOKEN=<your-token> \
+  -e GITHUB_TOOLSETS="repos,issues" \
+  -e GITHUB_TOOLS="search_code,search_repositories" \
+  ghcr.io/github/github-mcp-server
 ```
 
 ### Special toolsets

cmd/github-mcp-server/main.go

@@ -45,17 +45,17 @@ var (
 				return fmt.Errorf("failed to unmarshal toolsets: %w", err)
 			}
 
-			// No passed toolsets configuration means we enable the default toolset
-			if len(enabledToolsets) == 0 {
-				enabledToolsets = []string{github.ToolsetMetadataDefault.ID}
-			}
-
 			// Parse tools (similar to toolsets)
 			var enabledTools []string
 			if err := viper.UnmarshalKey("tools", &enabledTools); err != nil {
 				return fmt.Errorf("failed to unmarshal tools: %w", err)
 			}
 
+			// If neither toolset config nor tools config is passed we enable the default toolset
+			if len(enabledToolsets) == 0 && len(enabledTools) == 0 {
+				enabledToolsets = []string{github.ToolsetMetadataDefault.ID}
+			}
+
 			stdioServerConfig := ghmcp.StdioServerConfig{
 				Version:              version,
 				Host:                 viper.GetString("host"),

internal/ghmcp/server.go

@@ -39,8 +39,8 @@ type MCPServerConfig struct {
 	// See: https://github.com/github/github-mcp-server?tab=readme-ov-file#tool-configuration
 	EnabledToolsets []string
 
-	// EnabledTools is a list of specific tools to enable (takes priority over toolsets)
-	// When specified, only these tools will be registered, bypassing toolset enablement
+	// EnabledTools is a list of specific tools to enable (additive to toolsets)
+	// When specified, these tools are registered in addition to any specified toolset tools
 	EnabledTools []string
 
 	// Whether to enable dynamic toolsets
@@ -171,43 +171,36 @@ func NewMCPServer(cfg MCPServerConfig) (*server.MCPServer, error) {
 		github.FeatureFlags{LockdownMode: cfg.LockdownMode},
 	)
 
-	// PRIORITY: If specific tools are configured, use tool-level registration
-	if len(cfg.EnabledTools) > 0 {
-		// Clean and validate tool names
-		enabledTools, invalidTools := github.CleanTools(cfg.EnabledTools)
-
-		if len(invalidTools) > 0 {
-			fmt.Fprintf(os.Stderr, "Invalid tools ignored: %s\n", strings.Join(invalidTools, ", "))
-		}
-
-		// Register only the specified tools (bypasses toolset enablement)
-		err = tsg.RegisterSpecificTools(ghServer, enabledTools, cfg.ReadOnly)
-		if err != nil {
-			return nil, fmt.Errorf("failed to register tools: %w", err)
-		}
-
-		// Still register resources and prompts from all toolsets to maintain functionality
-		for _, toolset := range tsg.Toolsets {
-			toolset.RegisterResourcesTemplates(ghServer)
-			toolset.RegisterPrompts(ghServer)
-		}
-	} else {
-		// EXISTING FLOW: Use toolset-based registration
+	// Enable and register toolsets if configured
+	// This always happens if toolsets are specified, regardless of whether tools are also specified
+	if len(enabledToolsets) > 0 {
 		err = tsg.EnableToolsets(enabledToolsets, nil)
 		if err != nil {
 			return nil, fmt.Errorf("failed to enable toolsets: %w", err)
 		}
 
-		// Register all mcp functionality with the server
+		// Register all mcp functionality with the server (tools, resources, prompts)
 		tsg.RegisterAll(ghServer)
+	}
+
+	// Register specific tools if configured (additive to toolsets)
+	if len(cfg.EnabledTools) > 0 {
+		// Clean and validate tool names
+		enabledTools := github.CleanTools(cfg.EnabledTools)
 
-		// Dynamic toolsets only work if no specific tools configured
-		if cfg.DynamicToolsets {
-			dynamic := github.InitDynamicToolset(ghServer, tsg, cfg.Translator)
-			dynamic.RegisterTools(ghServer)
+		// Register the specified tools (additive to any toolsets already enabled)
+		err = tsg.RegisterSpecificTools(ghServer, enabledTools, cfg.ReadOnly)
+		if err != nil {
+			return nil, fmt.Errorf("failed to register tools: %w", err)
 		}
 	}
 
+	// Register dynamic toolsets if configured (additive to toolsets and tools)
+	if cfg.DynamicToolsets {
+		dynamic := github.InitDynamicToolset(ghServer, tsg, cfg.Translator)
+		dynamic.RegisterTools(ghServer)
+	}
+
 	return ghServer, nil
 }
 
@@ -225,8 +218,8 @@ type StdioServerConfig struct {
 	// See: https://github.com/github/github-mcp-server?tab=readme-ov-file#tool-configuration
 	EnabledToolsets []string
 
-	// EnabledTools is a list of specific tools to enable (takes priority over toolsets)
-	// When specified, only these tools will be registered, bypassing toolset enablement
+	// EnabledTools is a list of specific tools to enable (additive to toolsets)
+	// When specified, these tools are registered in addition to any specifiedtoolset tools
 	EnabledTools []string
 
 	// Whether to enable dynamic toolsets

pkg/github/tools.go

@@ -524,16 +524,11 @@ func ContainsToolset(tools []string, toCheck string) bool {
 	return false
 }
 
-// CleanTools validates and cleans tool names:
-// - Duplicates are removed from the result
-// - Removes whitespaces
-// - Validation of tool existence is done during registration
-// Returns: (cleaned tools, invalid tools)
-// Note: Invalid tools are identified during registration, so this function only cleans and deduplicates.
-func CleanTools(toolNames []string) ([]string, []string) {
+// CleanTools cleans tool names by removing duplicates and trimming whitespace.
+// Validation of tool existence is done during registration.
+func CleanTools(toolNames []string) []string {
 	seen := make(map[string]bool)
 	result := make([]string, 0, len(toolNames))
-	invalid := make([]string, 0)
 
 	// Remove duplicates and trim whitespace
 	for _, tool := range toolNames {
@@ -547,6 +542,5 @@ func CleanTools(toolNames []string) ([]string, []string) {
 		}
 	}
 
-	// Validation will happen during registration, so we return empty invalid list here
-	return result, invalid
+	return result
 }

pkg/toolsets/toolsets.go

@@ -2,6 +2,8 @@ package toolsets
 
 import (
 	"fmt"
+	"os"
+	"strings"
 
 	"github.com/mark3labs/mcp-go/mcp"
 	"github.com/mark3labs/mcp-go/server"
@@ -300,6 +302,7 @@ func (tg *ToolsetGroup) FindToolByName(toolName string) (*server.ServerTool, str
 // Respects read-only mode (skips write tools if readOnly=true).
 // Returns error if any tool is not found.
 func (tg *ToolsetGroup) RegisterSpecificTools(s *server.MCPServer, toolNames []string, readOnly bool) error {
+	var skippedTools []string
 	for _, toolName := range toolNames {
 		tool, toolsetName, err := tg.FindToolByName(toolName)
 		if err != nil {
@@ -312,6 +315,7 @@ func (tg *ToolsetGroup) RegisterSpecificTools(s *server.MCPServer, toolNames []s
 			isWriteTool := !*tool.Tool.Annotations.ReadOnlyHint
 			if isWriteTool && readOnly {
 				// Skip write tools in read-only mode
+				skippedTools = append(skippedTools, toolName)
 				continue
 			}
 		}
@@ -320,5 +324,11 @@ func (tg *ToolsetGroup) RegisterSpecificTools(s *server.MCPServer, toolNames []s
 		s.AddTool(tool.Tool, tool.Handler)
 		_ = toolsetName // toolsetName is available for potential future use (logging, etc.)
 	}
+
+	// Log skipped write tools if any
+	if len(skippedTools) > 0 {
+		fmt.Fprintf(os.Stderr, "Write tools skipped due to read-only mode: %s\n", strings.Join(skippedTools, ", "))
+	}
+
 	return nil
 }