fix: propagate MCPServer CRD timeout to RemoteMCPServer (#1277)

Closes #1272
Supersedes #1275

### Summary

Propagates the new `Timeout` field from the MCPServer CRD (added in
[kagent-dev/kmcp#121](kagent-dev/kmcp#121)) to
the generated `RemoteMCPServer` resources, fixing intermittent `"Failed
to create MCP session"` errors for sidecar gateway deployments.

### Context

[#1272](#1272) reported that
the default 5s MCP connection timeout is too low for MCPServer CRD
deployments where the sidecar gateway spawns stdio processes (via
`uvx`/`npx`) with 2–8s cold starts.

An initial approach
([#1275](#1275)) made the
timeout configurable via Helm chart values, threading it through 6+
layers (Helm → ConfigMap → env → flag → handlers → translator). Per
[maintainer
feedback](#1275 (comment)),
the proper fix is to add the timeout directly to the MCPServer CRD.

### Approach

Instead of global controller-level configuration, the timeout is now a
**per-resource field** on the MCPServer CRD with a kubebuilder default
of `30s` (see
[kagent-dev/kmcp#121](kagent-dev/kmcp#121)).

`ConvertMCPServerToRemoteMCPServer` now propagates:
- **`Timeout`** from `MCPServerSpec` → `RemoteMCPServerSpec` (defaults
to 30s via CRD)
- **`TerminateOnClose: true`** (matches ADK expected behavior for
managed servers)

### Changes

| File | Description |
|------|-------------|
| `go/go.mod` | Bump kmcp dependency to version with `Timeout` field
(kmcp version 0.2.6) |
| `go/internal/controller/translator/agent/adk_api_translator.go` |
`ConvertMCPServerToRemoteMCPServer` propagates `Timeout` and sets
`TerminateOnClose: true` |
|
`go/internal/controller/translator/agent/testdata/outputs/agent_with_proxy_mcpserver.json`
| Golden test updated |

### Backward Compatibility

- Default timeout is `30s`, matching the previous hardcoded behavior
from #1275.
- When `MCPServer.Spec.Timeout` is explicitly set, that value takes
precedence.
- `RemoteMCPServer` resources created directly (not via MCPServer CRD)
are unaffected — they continue using their own `Spec.Timeout` field.

### Depends on

- [x] [kagent-dev/kmcp#121](kagent-dev/kmcp#121)
must be merged and released first
- [x] Update `go.mod` to replace the `replace` directive with the actual
released version

### Testing

- All existing unit tests pass
- Golden test outputs regenerated
- `go build ./...` and `go test ./internal/controller/...` pass cleanly

Signed-off-by: skhedim <sebastien.khedim@gmail.com>

Author: skhedim

go/go.mod

@@ -14,7 +14,7 @@ require (
 	github.com/gorilla/mux v1.8.1
 	github.com/hashicorp/go-multierror v1.1.1
 	github.com/jedib0t/go-pretty/v6 v6.7.8
-	github.com/kagent-dev/kmcp v0.2.5
+	github.com/kagent-dev/kmcp v0.2.6
 	github.com/kagent-dev/mockllm v0.0.3
 	github.com/modelcontextprotocol/go-sdk v1.2.0
 	github.com/muesli/reflow v0.3.0

go/go.sum

@@ -165,10 +165,8 @@ github.com/josharian/intern v1.0.0 h1:vlS4z54oSdjm0bgjRigI+G1HpF+tI+9rE5LLzOg8Hm
 github.com/josharian/intern v1.0.0/go.mod h1:5DoeVV0s6jJacbCEi61lwdGj/aVlrQvzHFFd8Hwg//Y=
 github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
 github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
-github.com/kagent-dev/kmcp v0.2.2 h1:uvbKmo9IT6OT9RBNXYwGX0PWyxBLfAW1F9yWd5/wxaI=
-github.com/kagent-dev/kmcp v0.2.2/go.mod h1:g7wS/3m2wonRo/1DMwVoHxnilr/urPgV2hwV1DwkwrQ=
-github.com/kagent-dev/kmcp v0.2.5 h1:Em5A2vROJuR5JpMe5luSMe2vQJTwxX93AMXJm6Lg/E0=
-github.com/kagent-dev/kmcp v0.2.5/go.mod h1:g7wS/3m2wonRo/1DMwVoHxnilr/urPgV2hwV1DwkwrQ=
+github.com/kagent-dev/kmcp v0.2.6 h1:9h4JEbEK7/Joonucoide4GqGA0zJfoDxBTK+AXCkmNQ=
+github.com/kagent-dev/kmcp v0.2.6/go.mod h1:g7wS/3m2wonRo/1DMwVoHxnilr/urPgV2hwV1DwkwrQ=
 github.com/kagent-dev/mockllm v0.0.3 h1:hk6Oa/vxHoBrGqRig4GCzox8EqRQYXM4c3oFPP/k9Tg=
 github.com/kagent-dev/mockllm v0.0.3/go.mod h1:tDLemRsTZa1NdHaDbg3sgFk9cT1QWvMPlBtLVD6I2mA=
 github.com/klauspost/compress v1.18.0 h1:c/Cqfb0r+Yi+JtIEq73FWXVkRonBlf0CRNYc8Zttxdo=

go/internal/controller/translator/agent/adk_api_translator.go

@@ -14,6 +14,7 @@ import (
 	"slices"
 	"strconv"
 	"strings"
+	"time"
 
 	"github.com/kagent-dev/kagent/go/api/v1alpha2"
 	"github.com/kagent-dev/kagent/go/internal/adk"
@@ -45,6 +46,12 @@ const (
 	MCPServiceProtocolDefault = v1alpha2.RemoteMCPServerProtocolStreamableHttp
 
 	ProxyHostHeader = "x-kagent-host"
+
+	// DefaultMCPServerTimeout is the fallback connection timeout applied when
+	// an MCPServer CRD resource does not have an explicit Timeout set (e.g.
+	// objects created before the field was introduced). This value mirrors
+	// the kubebuilder default on MCPServerSpec.Timeout in the kmcp CRD.
+	DefaultMCPServerTimeout = 30 * time.Second
 )
 
 // ValidationError indicates a configuration error that requires user action to fix.
@@ -1259,7 +1266,7 @@ func ConvertMCPServerToRemoteMCPServer(mcpServer *v1alpha1.MCPServer) (*v1alpha2
 		return nil, NewValidationError("cannot determine port for MCP server %s", mcpServer.Name)
 	}
 
-	return &v1alpha2.RemoteMCPServer{
+	remoteMCP := &v1alpha2.RemoteMCPServer{
 		ObjectMeta: metav1.ObjectMeta{
 			Name:      mcpServer.Name,
 			Namespace: mcpServer.Namespace,
@@ -1268,7 +1275,20 @@ func ConvertMCPServerToRemoteMCPServer(mcpServer *v1alpha1.MCPServer) (*v1alpha2
 			URL:      fmt.Sprintf("http://%s.%s:%d/mcp", mcpServer.Name, mcpServer.Namespace, mcpServer.Spec.Deployment.Port),
 			Protocol: v1alpha2.RemoteMCPServerProtocolStreamableHttp,
 		},
-	}, nil
+	}
+
+	// Propagate the timeout from the MCPServer CRD to the generated
+	// RemoteMCPServer spec. Fall back to DefaultMCPServerTimeout for
+	// MCPServer objects created before the CRD default was introduced,
+	// so the ADK never uses its own 5s built-in which is too short for
+	// sidecar gateway cold starts.
+	if mcpServer.Spec.Timeout != nil {
+		remoteMCP.Spec.Timeout = mcpServer.Spec.Timeout
+	} else {
+		remoteMCP.Spec.Timeout = &metav1.Duration{Duration: DefaultMCPServerTimeout}
+	}
+
+	return remoteMCP, nil
 }
 
 func (a *adkApiTranslator) translateRemoteMCPServerTarget(ctx context.Context, agent *adk.AgentConfig, remoteMcpServer *v1alpha2.RemoteMCPServer, mcpServerTool *v1alpha2.McpServerTool, agentHeaders map[string]string, proxyURL string) error {

go/internal/controller/translator/agent/testdata/inputs/agent_with_proxy_mcpserver_custom_timeout.yaml

@@ -0,0 +1,49 @@
+operation: translateAgent
+targetObject: agent-with-proxy-mcpserver-timeout
+namespace: test
+proxyURL: http://proxy.kagent.svc.cluster.local:8080
+objects:
+  - apiVersion: v1
+    kind: Secret
+    metadata:
+      name: openai-secret
+      namespace: test
+    data:
+      api-key: c2stdGVzdC1hcGkta2V5  # base64 encoded "sk-test-api-key"
+  - apiVersion: kagent.dev/v1alpha2
+    kind: ModelConfig
+    metadata:
+      name: default-model
+      namespace: test
+    spec:
+      provider: OpenAI
+      model: gpt-4o
+      apiKeySecret: openai-secret
+      apiKeySecretKey: api-key
+  - apiVersion: kagent.dev/v1alpha1
+    kind: MCPServer
+    metadata:
+      name: test-mcp-server
+      namespace: test
+    spec:
+      deployment:
+        port: 8084
+      timeout: 60s
+  - apiVersion: kagent.dev/v1alpha2
+    kind: Agent
+    metadata:
+      name: agent-with-proxy-mcpserver-timeout
+      namespace: test
+    spec:
+      type: Declarative
+      declarative:
+        description: An agent with proxy configuration and MCPServer with custom timeout
+        systemMessage: You are an agent that uses proxies.
+        modelConfig: default-model
+        tools:
+          - type: MCPServer
+            mcpServer:
+              name: test-mcp-server
+              kind: MCPServer
+              toolNames:
+                - test-tool

go/internal/controller/translator/agent/testdata/outputs/agent_with_proxy_mcpserver.json

@@ -25,6 +25,7 @@
           "headers": {
             "x-kagent-host": "test-mcp-server.test"
           },
+          "timeout": 30,
           "url": "http://proxy.kagent.svc.cluster.local:8080/mcp"
         },
         "tools": [
@@ -69,7 +70,7 @@
       },
       "stringData": {
         "agent-card.json": "{\"name\":\"agent_with_proxy_mcpserver\",\"description\":\"\",\"url\":\"http://agent-with-proxy-mcpserver.test:8080\",\"version\":\"\",\"capabilities\":{\"streaming\":true,\"pushNotifications\":false,\"stateTransitionHistory\":true},\"defaultInputModes\":[\"text\"],\"defaultOutputModes\":[\"text\"],\"skills\":[]}",
-        "config.json": "{\"model\":{\"type\":\"openai\",\"model\":\"gpt-4o\",\"base_url\":\"\"},\"description\":\"\",\"instruction\":\"You are an agent that uses proxies.\",\"http_tools\":[{\"params\":{\"url\":\"http://proxy.kagent.svc.cluster.local:8080/mcp\",\"headers\":{\"x-kagent-host\":\"test-mcp-server.test\"}},\"tools\":[\"test-tool\"]}],\"sse_tools\":null,\"remote_agents\":null,\"stream\":false}"
+        "config.json": "{\"model\":{\"type\":\"openai\",\"model\":\"gpt-4o\",\"base_url\":\"\"},\"description\":\"\",\"instruction\":\"You are an agent that uses proxies.\",\"http_tools\":[{\"params\":{\"url\":\"http://proxy.kagent.svc.cluster.local:8080/mcp\",\"headers\":{\"x-kagent-host\":\"test-mcp-server.test\"},\"timeout\":30},\"tools\":[\"test-tool\"]}],\"sse_tools\":null,\"remote_agents\":null,\"stream\":false}"
       }
     },
     {
@@ -138,7 +139,7 @@
         "template": {
           "metadata": {
             "annotations": {
-              "kagent.dev/config-hash": "4693175952507523169"
+              "kagent.dev/config-hash": "14322610689340983156"
             },
             "labels": {
               "app": "kagent",