Add tool filtering to MCPServer CRD. (#1176)

This change adds support for `tools` to `MCPServer` CRD.

By default, the list is `nil` which defaults to no `--tools` option being passed as argument to the container. When a non-empty list is passed, it is interpolated ensuring the items are sorted first, so that changing the sequence of tools being enabled does not trigger a reconciliation.

A simple unit test was added to verify the various cases of reconciliation, but I also tested it locally using `kind` and a debugger.

Fixes #1005

Author: blkt

cmd/thv-operator/.task/checksum/crdref-gen

@@ -0,0 +1 @@
+4ce3c9a46c7a123dc6af67746ae657c1

cmd/thv-operator/README.md

@@ -161,7 +161,7 @@ kubectl describe mcpserver <name>
 
 ### MCPServer Spec
 
-| Field               | Description                                     | Required | Default |
+| Field               | Description                                      | Required | Default |
 |---------------------|--------------------------------------------------|----------|---------|
 | `image`             | Container image for the MCP server               | Yes      | -       |
 | `transport`         | Transport method (stdio, streamable-http or sse) | No       | stdio   |
@@ -173,6 +173,7 @@ kubectl describe mcpserver <name>
 | `resources`         | Resource requirements for the container          | No       | -       |
 | `secrets`           | References to secrets to mount in the container  | No       | -       |
 | `permissionProfile` | Permission profile configuration                 | No       | -       |
+| `tools`             | Allow-list filter on the list of tools           | No       | -       |
 
 ### Permission Profiles
 
@@ -255,4 +256,4 @@ The Kubebuilder project structure is as follows:
 - `config/`: Contains the Kubernetes manifests for deploying the operator
 - `PROJECT`: Kubebuilder project configuration file
 
-For more information on Kubebuilder, see the [Kubebuilder Book](https://book.kubebuilder.io/).
+For more information on Kubebuilder, see the [Kubebuilder Book](https://book.kubebuilder.io/).

cmd/thv-operator/api/v1alpha1/mcpserver_types.go

@@ -70,6 +70,10 @@ type MCPServerSpec struct {
 	// AuthzConfig defines authorization policy configuration for the MCP server
 	// +optional
 	AuthzConfig *AuthzConfigRef `json:"authzConfig,omitempty"`
+
+	// ToolsFilter is the filter on tools applied to the MCP server
+	// +optional
+	ToolsFilter []string `json:"tools,omitempty"`
 }
 
 // ResourceOverrides defines overrides for annotations and labels on created resources

cmd/thv-operator/api/v1alpha1/zz_generated.deepcopy.go

@@ -9,6 +9,7 @@ import (
 	"maps"
 	"os"
 	"reflect"
+	"slices"
 	"strings"
 	"time"
 
@@ -440,6 +441,12 @@ func (r *MCPServerReconciler) deploymentForMCPServer(m *mcpv1alpha1.MCPServer) *
 		args = append(args, fmt.Sprintf("--env=%s=%s", e.Name, e.Value))
 	}
 
+	// Add tools filter args
+	if len(m.Spec.ToolsFilter) > 0 {
+		slices.Sort(m.Spec.ToolsFilter)
+		args = append(args, fmt.Sprintf("--tools=%s", strings.Join(m.Spec.ToolsFilter, ",")))
+	}
+
 	// Add the image
 	args = append(args, m.Spec.Image)
 
@@ -805,6 +812,22 @@ func deploymentNeedsUpdate(deployment *appsv1.Deployment, mcpServer *mcpv1alpha1
 			return true
 		}
 
+		// Check if the tools filter has changed
+		if mcpServer.Spec.ToolsFilter == nil {
+			for _, arg := range container.Args {
+				if strings.HasPrefix(arg, "--tools=") {
+					return true
+				}
+			}
+		} else {
+			slices.Sort(mcpServer.Spec.ToolsFilter)
+			toolsFilterArg := fmt.Sprintf("--tools=%s", strings.Join(mcpServer.Spec.ToolsFilter, ","))
+			found = slices.Contains(container.Args, toolsFilterArg)
+			if !found {
+				return true
+			}
+		}
+
 		// Check if the pod template spec has changed
 
 		// TODO: Add more comprehensive checks for PodTemplateSpec changes beyond just the args

cmd/thv-operator/controllers/mcpserver_controller.go

@@ -577,3 +577,74 @@ func TestDeploymentNeedsUpdateProxyEnv(t *testing.T) {
 		})
 	}
 }
+
+func TestDeploymentNeedsUpdateToolsFilter(t *testing.T) {
+	t.Parallel()
+
+	scheme := runtime.NewScheme()
+	require.NoError(t, mcpv1alpha1.AddToScheme(scheme))
+
+	client := fake.NewClientBuilder().WithScheme(scheme).Build()
+	r := &MCPServerReconciler{
+		Client: client,
+		Scheme: scheme,
+	}
+
+	tests := []struct {
+		name               string
+		initialToolsFilter []string
+		newToolsFilter     []string
+		expectEnvChange    bool
+	}{
+		{
+			name:               "empty tools filter",
+			initialToolsFilter: nil,
+			newToolsFilter:     nil,
+			expectEnvChange:    false,
+		},
+		{
+			name:               "tools filter not changed",
+			initialToolsFilter: []string{"tool1", "tool2"},
+			newToolsFilter:     []string{"tool1", "tool2"},
+			expectEnvChange:    false,
+		},
+		{
+			name:               "tools filter changed",
+			initialToolsFilter: []string{"tool1", "tool2"},
+			newToolsFilter:     []string{"tool2", "tool3"},
+			expectEnvChange:    true,
+		},
+		{
+			name:               "tools filter change order",
+			initialToolsFilter: []string{"tool1", "tool2"},
+			newToolsFilter:     []string{"tool2", "tool1"},
+			expectEnvChange:    false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			t.Parallel()
+
+			mcpServer := &mcpv1alpha1.MCPServer{
+				ObjectMeta: metav1.ObjectMeta{
+					Name:      "test-server",
+					Namespace: "default",
+				},
+				Spec: mcpv1alpha1.MCPServerSpec{
+					Image:       "test-image",
+					Port:        8080,
+					ToolsFilter: tt.initialToolsFilter,
+				},
+			}
+
+			deployment := r.deploymentForMCPServer(mcpServer)
+			require.NotNil(t, deployment)
+
+			mcpServer.Spec.ToolsFilter = tt.newToolsFilter
+
+			needsUpdate := deploymentNeedsUpdate(deployment, mcpServer)
+			assert.Equal(t, tt.expectEnvChange, needsUpdate)
+		})
+	}
+}

cmd/thv-operator/controllers/mcpserver_resource_overrides_test.go

@@ -74,6 +74,9 @@ var (
 
 	// Network isolation flag
 	runIsolateNetwork bool
+
+	// Tools filter
+	runToolsFilter []string
 )
 
 func init() {
@@ -176,7 +179,12 @@ func init() {
 		"Enable Prometheus-style /metrics endpoint on the main transport port")
 	runCmd.Flags().BoolVar(&runIsolateNetwork, "isolate-network", false,
 		"Isolate the container network from the host (default: false)")
-
+	runCmd.Flags().StringArrayVar(
+		&runToolsFilter,
+		"tools",
+		nil,
+		"Filter MCP server tools (comma-separated list of tool names)",
+	)
 }
 
 func runCmdFunc(cmd *cobra.Command, args []string) error {
@@ -243,6 +251,7 @@ func runCmdFunc(cmd *cobra.Command, args []string) error {
 			runThvCABundle, runJWKSAuthTokenFile, runJWKSAllowPrivateIP).
 		WithTelemetryConfig(finalOtelEndpoint, runOtelEnablePrometheusMetricsPath, runOtelServiceName,
 			finalOtelSamplingRate, runOtelHeaders, runOtelInsecure, finalOtelEnvironmentVariables).
+		WithToolsFilter(runToolsFilter).
 		Build(ctx, imageMetadata, runEnv, envVarValidator)
 	if err != nil {
 		return fmt.Errorf("failed to create RunConfig: %v", err)

cmd/thv-proxyrunner/app/run.go

@@ -2,5 +2,5 @@ apiVersion: v2
 name: toolhive-operator-crds
 description: A Helm chart for installing the ToolHive Operator CRDs into Kubernetes.
 type: application
-version: 0.0.11
+version: 0.0.12
 appVersion: "0.0.1"

deploy/charts/operator-crds/Chart.yaml

@@ -1,7 +1,7 @@
 
 # ToolHive Operator CRDs Helm Chart
 
-![Version: 0.0.11](https://img.shields.io/badge/Version-0.0.11-informational?style=flat-square)
+![Version: 0.0.12](https://img.shields.io/badge/Version-0.0.12-informational?style=flat-square)
 ![Type: application](https://img.shields.io/badge/Type-application-informational?style=flat-square)
 
 A Helm chart for installing the ToolHive Operator CRDs into Kubernetes.

deploy/charts/operator-crds/README.md

@@ -8405,6 +8405,12 @@ spec:
                 maximum: 65535
                 minimum: 1
                 type: integer
+              tools:
+                description: ToolsFilter is the filter on tools applied to the MCP
+                  server
+                items:
+                  type: string
+                type: array
               transport:
                 default: stdio
                 description: Transport is the transport method for the MCP server