POC tool discovery proposal (dont merge)

Makefile

@@ -314,7 +314,9 @@ build-test-servers: ## Build test server Docker images locally
 	cd tests/servers/custom-path-server && $(CONTAINER_ENGINE) build $(CONTAINER_ENGINE_EXTRA_FLAGS) -t ghcr.io/kuadrant/mcp-gateway/test-custom-path-server:latest .
 	cd tests/servers/oidc-server && $(CONTAINER_ENGINE) build $(CONTAINER_ENGINE_EXTRA_FLAGS) -t ghcr.io/kuadrant/mcp-gateway/test-oidc-server:latest .
 	cd tests/servers/everything-server && $(CONTAINER_ENGINE) build $(CONTAINER_ENGINE_EXTRA_FLAGS) -t ghcr.io/kuadrant/mcp-gateway/test-everything-server:latest .
-	cd tests/servers/custom-response-server && $(CONTAINER_ENGINE) build $(CONTAINER_ENGINE_EXTRA_FLAGS) -t ghcr.io/kuadrant/mcp-gateway/test-custom-response-server:latest .	
+	cd tests/servers/custom-response-server && $(CONTAINER_ENGINE) build $(CONTAINER_ENGINE_EXTRA_FLAGS) -t ghcr.io/kuadrant/mcp-gateway/test-custom-response-server:latest .
+	cd tests/servers/restaurant-server && $(CONTAINER_ENGINE) build $(CONTAINER_ENGINE_EXTRA_FLAGS) -t ghcr.io/kuadrant/mcp-gateway/test-restaurant-server:latest .
+	cd tests/servers/messaging-server && $(CONTAINER_ENGINE) build $(CONTAINER_ENGINE_EXTRA_FLAGS) -t ghcr.io/kuadrant/mcp-gateway/test-messaging-server:latest .
 
 # Build conformance server Docker image
 .PHONY: build-conformance-server
@@ -334,6 +336,8 @@ kind-load-test-servers: kind build-test-servers ## Load test server images into
 	$(call load-image,ghcr.io/kuadrant/mcp-gateway/test-oidc-server:latest)
 	$(call load-image,ghcr.io/kuadrant/mcp-gateway/test-everything-server:latest)
 	$(call load-image,ghcr.io/kuadrant/mcp-gateway/test-custom-response-server:latest)
+	$(call load-image,ghcr.io/kuadrant/mcp-gateway/test-restaurant-server:latest)
+	$(call load-image,ghcr.io/kuadrant/mcp-gateway/test-messaging-server:latest)
 
 # Load everything server image into Kind cluster
 kind-load-everything-server: kind build-everything-server ## Load everything server image into Kind cluster

api/v1alpha1/types.go

@@ -62,6 +62,18 @@ type MCPServerRegistrationSpec struct {
 	// The controller will aggregate these credentials and make them available to the broker via environment variables following the pattern: KAGENTI_{MCP_NAME}_CRED
 	// +optional
 	CredentialRef *SecretReference `json:"credentialRef,omitempty"`
+
+	// category is a free-text classification of the server's domain.
+	// Used by the discover_tools meta-tool to present a high-level overview of available servers.
+	// Defaults to "uncategorised" if not set.
+	// +optional
+	Category string `json:"category,omitempty"`
+
+	// hint is a short natural-language description of what the server's tools do.
+	// Used by the discover_tools meta-tool to help agents decide which tools are relevant
+	// without loading full tool schemas.
+	// +optional
+	Hint string `json:"hint,omitempty"`
 }
 
 // TargetReference identifies an HTTPRoute that points to MCP servers.

bundle/manifests/mcp-gateway.clusterserviceversion.yaml

@@ -6,7 +6,7 @@ metadata:
     capabilities: Basic Install
     categories: Integration & Delivery
     containerImage: ghcr.io/kuadrant/mcp-controller:latest
-    createdAt: "2026-04-10T09:45:58Z"
+    createdAt: "2026-04-13T07:59:55Z"
     description: An Envoy-based gateway for Model Context Protocol (MCP) servers
     operators.operatorframework.io/builder: operator-sdk-v1.38.0
     operators.operatorframework.io/project_layout: go.kubebuilder.io/v4

bundle/manifests/mcp.kuadrant.io_mcpserverregistrations.yaml

@@ -71,6 +71,12 @@ spec:
           spec:
             description: spec defines the desired state of MCPServerRegistration.
             properties:
+              category:
+                description: |-
+                  category is a free-text classification of the server's domain.
+                  Used by the discover_tools meta-tool to present a high-level overview of available servers.
+                  Defaults to "uncategorised" if not set.
+                type: string
               credentialRef:
                 description: |-
                   credentialRef references a Secret containing authentication credentials for the MCP server.
@@ -90,6 +96,12 @@ spec:
                 required:
                 - name
                 type: object
+              hint:
+                description: |-
+                  hint is a short natural-language description of what the server's tools do.
+                  Used by the discover_tools meta-tool to help agents decide which tools are relevant
+                  without loading full tool schemas.
+                type: string
               path:
                 default: /mcp
                 description: |-

charts/mcp-gateway/crds/mcp.kuadrant.io_mcpserverregistrations.yaml

@@ -71,6 +71,12 @@ spec:
           spec:
             description: spec defines the desired state of MCPServerRegistration.
             properties:
+              category:
+                description: |-
+                  category is a free-text classification of the server's domain.
+                  Used by the discover_tools meta-tool to present a high-level overview of available servers.
+                  Defaults to "uncategorised" if not set.
+                type: string
               credentialRef:
                 description: |-
                   credentialRef references a Secret containing authentication credentials for the MCP server.
@@ -90,6 +96,12 @@ spec:
                 required:
                 - name
                 type: object
+              hint:
+                description: |-
+                  hint is a short natural-language description of what the server's tools do.
+                  Used by the discover_tools meta-tool to help agents decide which tools are relevant
+                  without loading full tool schemas.
+                type: string
               path:
                 default: /mcp
                 description: |-

cmd/mcp-broker-router/main.go

@@ -67,8 +67,9 @@ var (
 	managerTickerIntervalSecs int64
 	loglevel                  int
 	logFormat                 string
-	enforceToolFilteringFlag  bool
-	invalidToolPolicyFlag     string
+	enforceToolFilteringFlag   bool
+	invalidToolPolicyFlag      string
+	discoveryToolThresholdFlag int
 )
 
 func main() {
@@ -135,6 +136,7 @@ func main() {
 	flag.Int64Var(&managerTickerIntervalSecs, "mcp-check-interval", 60, "interval in seconds for MCP manager backend health checks. Default 60 seconds.")
 	flag.BoolVar(&enforceToolFilteringFlag, "enforce-tool-filtering", false, "when enabled an x-authorized-tools header will be needed to return any tools")
 	flag.StringVar(&invalidToolPolicyFlag, "invalid-tool-policy", "FilterOut", "policy for upstream tools with invalid schemas: FilterOut (default) or RejectServer")
+	flag.IntVar(&discoveryToolThresholdFlag, "discovery-tool-threshold", 10, "when total registered tools exceeds this threshold, new sessions only see discovery meta-tools until select_tools is called. Set 0 to always require discovery.")
 	flag.Parse()
 
 	loggerOpts := &slog.HandlerOptions{}
@@ -216,6 +218,7 @@ func main() {
 		broker.WithTrustedHeadersPublicKey(os.Getenv("TRUSTED_HEADER_PUBLIC_KEY")),
 		broker.WithManagerTickerInterval(managerTickerInterval),
 		broker.WithInvalidToolPolicy(invalidToolPolicy),
+		broker.WithDiscoveryToolThreshold(discoveryToolThresholdFlag),
 	)
 	brokerServer, mcpServer := setUpHTTPServer(mcpBrokerAddrFlag, mcpBroker, jwtSessionMgr, brokerWriteTimeoutSecs)
 	routerGRPCServer, router := setUpRouter(mcpBroker, logger, jwtSessionMgr, sessionCache, elicitationMap)
@@ -396,6 +399,10 @@ func LoadConfig(path string) {
 			s.URL,
 			"routable host",
 			s.Hostname,
+			"category",
+			s.Category,
+			"hint",
+			s.Hint,
 		)
 	}
 }

config/crd/mcp.kuadrant.io_mcpserverregistrations.yaml

@@ -71,6 +71,12 @@ spec:
           spec:
             description: spec defines the desired state of MCPServerRegistration.
             properties:
+              category:
+                description: |-
+                  category is a free-text classification of the server's domain.
+                  Used by the discover_tools meta-tool to present a high-level overview of available servers.
+                  Defaults to "uncategorised" if not set.
+                type: string
               credentialRef:
                 description: |-
                   credentialRef references a Secret containing authentication credentials for the MCP server.
@@ -90,6 +96,12 @@ spec:
                 required:
                 - name
                 type: object
+              hint:
+                description: |-
+                  hint is a short natural-language description of what the server's tools do.
+                  Used by the discover_tools meta-tool to help agents decide which tools are relevant
+                  without loading full tool schemas.
+                type: string
               path:
                 default: /mcp
                 description: |-

config/samples/mcpserverregistration-discovery.yaml

@@ -0,0 +1,84 @@
+---
+# sample MCPServerRegistrations with category and hint fields for tool discovery
+apiVersion: mcp.kuadrant.io/v1alpha1
+kind: MCPServerRegistration
+metadata:
+  name: test-server1
+  namespace: mcp-test
+  labels:
+    mcp.kuadrant.io/managed: 'true'
+spec:
+  toolPrefix: test1_
+  category: "greetings utilities"
+  hint: "greeting tools, time utilities, request header inspection, and slow response simulation"
+  targetRef:
+    # Server 1 - Go SDK based (greet, time, slow, headers tools)
+    group: gateway.networking.k8s.io
+    kind: HTTPRoute
+    name: mcp-server1-route
+---
+apiVersion: mcp.kuadrant.io/v1alpha1
+kind: MCPServerRegistration
+metadata:
+  name: test-server2
+  namespace: mcp-test
+  labels:
+    mcp.kuadrant.io/managed: 'true'
+spec:
+  toolPrefix: test2_
+  category: "greetings authentication"
+  hint: "hello world greeting, time, header inspection, auth token validation, and slow response tools"
+  targetRef:
+    # Server 2 - Go SDK based (hello_world, time, headers, auth1234, slow tools)
+    group: gateway.networking.k8s.io
+    kind: HTTPRoute
+    name: mcp-server2-route
+---
+apiVersion: mcp.kuadrant.io/v1alpha1
+kind: MCPServerRegistration
+metadata:
+  name: test-server3
+  namespace: mcp-test
+  labels:
+    mcp.kuadrant.io/managed: 'true'
+spec:
+  toolPrefix: test3_
+  category: "math weather"
+  hint: "mathematical operations (add, dozen, pi), weather forecasts, and time utilities"
+  targetRef:
+    # Server 3 - Python FastMCP based (time, add, dozen, pi, get_weather, slow)
+    group: gateway.networking.k8s.io
+    kind: HTTPRoute
+    name: mcp-server3-route
+---
+apiVersion: mcp.kuadrant.io/v1alpha1
+kind: MCPServerRegistration
+metadata:
+  name: restaurant-server
+  namespace: mcp-test
+  labels:
+    mcp.kuadrant.io/managed: 'true'
+spec:
+  toolPrefix: restaurant_
+  category: "dining reservations"
+  hint: "search restaurants by cuisine and location, check table availability, make and cancel reservations"
+  targetRef:
+    group: gateway.networking.k8s.io
+    kind: HTTPRoute
+    name: mcp-restaurant-server-route
+---
+apiVersion: mcp.kuadrant.io/v1alpha1
+kind: MCPServerRegistration
+metadata:
+  name: messaging-server
+  namespace: mcp-test
+  labels:
+    mcp.kuadrant.io/managed: 'true'
+spec:
+  toolPrefix: messaging_
+  category: "communication contacts"
+  hint: "find contacts, send messages via email/sms/slack, view message history, create messaging groups"
+  targetRef:
+    group: gateway.networking.k8s.io
+    kind: HTTPRoute
+    name: mcp-messaging-server-route

config/test-servers/kustomization.yaml

@@ -39,3 +39,9 @@ resources:
   - broken-server-service.yaml
   - broken-server-httproute.yaml
   - broken-server-deployment.yaml
+  - restaurant-server-deployment.yaml
+  - restaurant-server-service.yaml
+  - restaurant-server-httproute.yaml
+  - messaging-server-deployment.yaml
+  - messaging-server-service.yaml
+  - messaging-server-httproute.yaml

config/test-servers/messaging-server-deployment.yaml

@@ -0,0 +1,35 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: mcp-messaging-server
+  labels:
+    app: mcp-messaging-server
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: mcp-messaging-server
+  template:
+    metadata:
+      labels:
+        app: mcp-messaging-server
+    spec:
+      containers:
+      - name: mcp-messaging-server
+        image: ghcr.io/kuadrant/mcp-gateway/test-messaging-server:latest
+        imagePullPolicy: Never
+        command: ["/mcp-test-server"]
+        args: ["--http", "0.0.0.0:9090"]
+        ports:
+        - containerPort: 9090
+          name: http
+        env:
+        - name: LOG_LEVEL
+          value: "info"
+        resources:
+          limits:
+            memory: "128Mi"
+            cpu: "100m"
+          requests:
+            memory: "64Mi"
+            cpu: "50m"

config/test-servers/messaging-server-httproute.yaml

@@ -0,0 +1,20 @@
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: mcp-messaging-server-route
+  labels:
+    mcp-server: 'true'
+spec:
+  parentRefs:
+    - name: mcp-gateway
+      namespace: gateway-system
+  hostnames:
+    - 'messaging-server.mcp.local'
+  rules:
+    - matches:
+        - path:
+            type: PathPrefix
+            value: /
+      backendRefs:
+        - name: mcp-messaging-server
+          port: 9090

config/test-servers/messaging-server-service.yaml

@@ -0,0 +1,14 @@
+apiVersion: v1
+kind: Service
+metadata:
+  name: mcp-messaging-server
+  labels:
+    app: mcp-messaging-server
+spec:
+  ports:
+  - name: http
+    port: 9090
+    targetPort: 9090
+  selector:
+    app: mcp-messaging-server
+  type: ClusterIP

config/test-servers/restaurant-server-deployment.yaml

@@ -0,0 +1,35 @@
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: mcp-restaurant-server
+  labels:
+    app: mcp-restaurant-server
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      app: mcp-restaurant-server
+  template:
+    metadata:
+      labels:
+        app: mcp-restaurant-server
+    spec:
+      containers:
+      - name: mcp-restaurant-server
+        image: ghcr.io/kuadrant/mcp-gateway/test-restaurant-server:latest
+        imagePullPolicy: Never
+        command: ["/mcp-test-server"]
+        args: ["--http", "0.0.0.0:9090"]
+        ports:
+        - containerPort: 9090
+          name: http
+        env:
+        - name: LOG_LEVEL
+          value: "info"
+        resources:
+          limits:
+            memory: "128Mi"
+            cpu: "100m"
+          requests:
+            memory: "64Mi"
+            cpu: "50m"

config/test-servers/restaurant-server-httproute.yaml

@@ -0,0 +1,20 @@
+apiVersion: gateway.networking.k8s.io/v1
+kind: HTTPRoute
+metadata:
+  name: mcp-restaurant-server-route
+  labels:
+    mcp-server: 'true'
+spec:
+  parentRefs:
+    - name: mcp-gateway
+      namespace: gateway-system
+  hostnames:
+    - 'restaurant-server.mcp.local'
+  rules:
+    - matches:
+        - path:
+            type: PathPrefix
+            value: /
+      backendRefs:
+        - name: mcp-restaurant-server
+          port: 9090