feat(crd): add default timeout field to MCPServerSpec (#121)

### Summary

Adds a `Timeout` field to `MCPServerSpec` with a kubebuilder default of
`30s`.

This addresses
[kagent-dev/kagent#1272](kagent-dev/kagent#1272):
MCP servers deployed via the MCPServer CRD use a sidecar gateway that
spawns a new stdio process (e.g. via `uvx`/`npx`) for each session.
Process startup can take 2–8 seconds depending on package cache state,
which exceeds the default 5-second timeout used by some ADK clients
(e.g. Python ADK `StreamableHTTPConnectionParams`), causing intermittent
`"Failed to create MCP session"` errors.

### Context

An initial fix was proposed in
[kagent-dev/kagent#1275](kagent-dev/kagent#1275)
by making the timeout configurable via the Helm chart (env var →
controller flag → handler threading). A maintainer [correctly pointed
out](kagent-dev/kagent#1275 (comment)) that
the proper fix is to add this field to the MCPServer CRD itself, which:

- Follows existing CRD patterns (`Port` has `+kubebuilder:default=3000`,
`Replicas` has `+kubebuilder:default=1`)
- Provides **per-resource granularity** (each MCPServer can specify its
own timeout)
- Eliminates complex threading through Helm/env/flags/handlers
- Is the Kubernetes-idiomatic approach

### Changes

| File | Description |
|------|-------------|
| `api/v1alpha1/mcpserver_types.go` | Add `Timeout *metav1.Duration`
field with `+kubebuilder:default="30s"` |
| `api/v1alpha1/zz_generated.deepcopy.go` | Regenerated via `make
generate` |
| `config/crd/bases/kagent.dev_mcpservers.yaml` | CRD manifest
regenerated via `make manifests` |
| `helm/kmcp-crds/templates/mcpserver-crd.yaml` | Helm CRD template
updated to match |

### Backward Compatibility

- The default value is `30s` — existing MCPServer resources without an
explicit timeout will automatically get this default applied by the API
server.
- No breaking changes to existing CRs.

### Companion PR

Once this is merged and released, I will create a new PR and the kagent
controller will be updated to propagate this field:
`ConvertMCPServerToRemoteMCPServer` propagates `MCPServer.Spec.Timeout`
→ `RemoteMCPServer.Spec.Timeout`

Ref:
[kagent-dev/kagent#1272](kagent-dev/kagent#1272)

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

Author: skhedim

api/v1alpha1/mcpserver_types.go

@@ -148,6 +148,17 @@ type MCPServerSpec struct {
 
 	// HTTPTransport defines the configuration for a Streamable HTTP transport.
 	HTTPTransport *HTTPTransport `json:"httpTransport,omitempty"`
+
+	// Timeout defines the default connection timeout for clients connecting
+	// to this MCP server. MCP servers deployed via the MCPServer CRD use a
+	// sidecar gateway that spawns a new stdio process (e.g. via uvx/npx)
+	// for each session. Process startup can take 2-8 seconds depending on
+	// package cache state, which may exceed the default timeout used by some
+	// clients. This value is propagated to the generated RemoteMCPServer
+	// resources when they do not specify an explicit timeout.
+	// +optional
+	// +kubebuilder:default="30s"
+	Timeout *metav1.Duration `json:"timeout,omitempty"`
 }
 
 // StdioTransport defines the configuration for a standard input/output transport.

api/v1alpha1/zz_generated.deepcopy.go

@@ -5282,6 +5282,17 @@ spec:
                 description: StdioTransport defines the configuration for a standard
                   input/output transport.
                 type: object
+              timeout:
+                default: 30s
+                description: |-
+                  Timeout defines the default connection timeout for clients connecting
+                  to this MCP server. MCP servers deployed via the MCPServer CRD use a
+                  sidecar gateway that spawns a new stdio process (e.g. via uvx/npx)
+                  for each session. Process startup can take 2-8 seconds depending on
+                  package cache state, which may exceed the default timeout used by some
+                  clients. This value is propagated to the generated RemoteMCPServer
+                  resources when they do not specify an explicit timeout.
+                type: string
               transportType:
                 description: TransportType defines the type of mcp server being run
                 enum:

config/crd/bases/kagent.dev_mcpservers.yaml

@@ -2014,6 +2014,17 @@ spec:
                 description: StdioTransport defines the configuration for a standard
                   input/output transport.
                 type: object
+              timeout:
+                default: 30s
+                description: |-
+                  Timeout defines the default connection timeout for clients connecting
+                  to this MCP server. MCP servers deployed via the MCPServer CRD use a
+                  sidecar gateway that spawns a new stdio process (e.g. via uvx/npx)
+                  for each session. Process startup can take 2-8 seconds depending on
+                  package cache state, which may exceed the default timeout used by some
+                  clients. This value is propagated to the generated RemoteMCPServer
+                  resources when they do not specify an explicit timeout.
+                type: string
               transportType:
                 description: TransportType defines the type of mcp server being run
                 enum: