feat(upstream): configurable per-server MCP initialize timeout

Add init_timeout (global default + per-server override) controlling the
deadline for an upstream's MCP initialize handshake. Un-isolated stdio
servers previously inherited the caller's ~30s context and were killed
mid-startup during legitimate first-run warmup (cache/index build); with
docker run --rm the partial work was discarded and retries looped forever
(GH #760).

- config: InitTimeout *Duration on Config and ServerConfig; ResolveInitTimeout
  (per-server > global > 30s default; <=0 maps to default, never disabled);
  bounds {0} u [1s,30m] in Validate().
- upstream/manager: resolveConnectTimeout applied at AddServer, ConnectAll
  (wrap ALL connects, not just Docker), and the post-OAuth retry; Docker
  isolation keeps a 3m floor, a larger override still wins.
- Plumb init_timeout through the upstream_servers MCP tool (add/patch),
  REST AddServerRequest allowlist + GET serialization, config merge/copy,
  storage UpstreamRecord, contracts.Server, and mcpproxy upstream patch
  --init-timeout.
- Docs (configuration.md) + regenerated oas/swagger.yaml.

Related #760

Author: Dumbris

cmd/mcpproxy/upstream_cmd.go

@@ -286,6 +286,7 @@ Examples:
 	upstreamPatchHeaderRemove []string
 	upstreamPatchEnvs         []string
 	upstreamPatchEnvRemove    []string
+	upstreamPatchInitTimeout  string
 
 	// Import command flags
 	upstreamImportServer       string
@@ -361,6 +362,7 @@ func init() {
 	upstreamPatchCmd.Flags().StringArrayVar(&upstreamPatchHeaderRemove, "header-remove", nil, "HTTP header name to delete (repeatable)")
 	upstreamPatchCmd.Flags().StringArrayVar(&upstreamPatchEnvs, "env", nil, "Environment variable to upsert in KEY=value format (repeatable)")
 	upstreamPatchCmd.Flags().StringArrayVar(&upstreamPatchEnvRemove, "env-remove", nil, "Environment variable name to delete (repeatable)")
+	upstreamPatchCmd.Flags().StringVar(&upstreamPatchInitTimeout, "init-timeout", "", "MCP initialize handshake deadline as a duration (e.g. '120s', '3m'); raise for upstreams that warm up before responding to initialize")
 
 	// Inspect command flags
 	upstreamInspectCmd.Flags().StringVar(&upstreamInspectTool, "tool", "", "Show details for a specific tool")
@@ -2075,9 +2077,18 @@ func runUpstreamPatch(_ *cobra.Command, args []string) error {
 		return fmt.Errorf("server name is required")
 	}
 
+	initTimeout := strings.TrimSpace(upstreamPatchInitTimeout)
 	if len(upstreamPatchHeaders) == 0 && len(upstreamPatchHeaderRemove) == 0 &&
-		len(upstreamPatchEnvs) == 0 && len(upstreamPatchEnvRemove) == 0 {
-		return fmt.Errorf("at least one of --header / --header-remove / --env / --env-remove must be specified")
+		len(upstreamPatchEnvs) == 0 && len(upstreamPatchEnvRemove) == 0 && initTimeout == "" {
+		return fmt.Errorf("at least one of --header / --header-remove / --env / --env-remove / --init-timeout must be specified")
+	}
+
+	// Validate --init-timeout locally so we fail fast with a clear message
+	// before hitting the daemon (the backend re-validates the bounds).
+	if initTimeout != "" {
+		if _, perr := time.ParseDuration(initTimeout); perr != nil {
+			return fmt.Errorf("invalid --init-timeout %q: %v (expected a duration like '120s' or '3m')", initTimeout, perr)
+		}
 	}
 
 	headers := map[string]*string{}
@@ -2135,6 +2146,9 @@ func runUpstreamPatch(_ *cobra.Command, args []string) error {
 	if len(envs) > 0 {
 		body["env"] = envs
 	}
+	if initTimeout != "" {
+		body["init_timeout"] = initTimeout
+	}
 
 	bodyBytes, err := json.Marshal(body)
 	if err != nil {
@@ -2176,6 +2190,9 @@ func runUpstreamPatch(_ *cobra.Command, args []string) error {
 	if n := len(upstreamPatchEnvRemove); n > 0 {
 		parts = append(parts, fmt.Sprintf("%d env var(s) removed", n))
 	}
+	if initTimeout != "" {
+		parts = append(parts, fmt.Sprintf("init_timeout=%s", initTimeout))
+	}
 	if len(parts) > 0 {
 		fmt.Printf(": %s", strings.Join(parts, ", "))
 	}

docs/configuration.md

@@ -86,7 +86,8 @@ MCPProxy looks for configuration in these locations (in order):
 {
   "tools_limit": 15,
   "tool_response_limit": 20000,
-  "call_tool_timeout": "2m"
+  "call_tool_timeout": "2m",
+  "init_timeout": "30s"
 }
 ```
 
@@ -95,6 +96,7 @@ MCPProxy looks for configuration in these locations (in order):
 | `tools_limit` | integer | `15` | Maximum number of tools to return per request (1-1000) |
 | `tool_response_limit` | integer | `20000` | Maximum characters in tool responses (0 = unlimited) |
 | `call_tool_timeout` | string | `"2m"` | Timeout for tool calls (e.g., `"30s"`, `"2m"`, `"5m"`). **Note**: When using agents like Codex or Claude as MCP servers, you may need to increase this timeout significantly, even up to 10 minutes (`"10m"`), as these agents may require longer processing times for complex operations |
+| `init_timeout` | duration | `"30s"` | Deadline for an upstream's MCP `initialize` handshake (e.g. `"30s"`, `"120s"`, `"3m"`). Raise this for servers that do legitimate first-run warmup — building a cache/index or prefetching — before they answer `initialize`, so they are not killed mid-startup. Global default; can be overridden per server (see [Server Fields](#server-fields)). Range: `1s`–`30m`; `"0s"`/unset uses the 30s default. |
 
 ### Discovery & Health Checks
 
@@ -208,6 +210,7 @@ the proxy.
 | `launcher_wait_timeout` | duration | No | When `command` is set together with an HTTP/SSE `url`, how long mcpproxy waits for that URL to become reachable after spawning the child (e.g. `"15s"`, default `"30s"`) |
 | `health_check_interval` | duration | No | Per-server override for the global [`health_check_interval`](#discovery--health-checks). `"0s"` disables the liveness probe for this server only. Range: `5s`–`1h`. Omit to inherit the global value. |
 | `tool_discovery_interval` | duration | No | Per-server override for the global [`tool_discovery_interval`](#discovery--health-checks). Overrides the global/default cadence for this server only; `"0s"` disables the periodic tool-discovery sweep for this server (connect-time and reactive `list_changed` discovery still run). Range: `30s`–`24h`. Omit to inherit the global value. |
+| `init_timeout` | duration | No | Per-server override for the global [`init_timeout`](#search--tool-limits) — the MCP `initialize` handshake deadline. Raise it for an upstream that warms up (caches/indexes data) before responding to `initialize` (e.g. `"120s"`, `"3m"`); without it such a server is killed mid-startup and, with `docker run --rm`, retries forever. Range: `1s`–`30m`. Omit to inherit the global value (30s default). Settable via the `upstream_servers` tool and `mcpproxy upstream patch --init-timeout`. |
 | `oauth` | object | No | OAuth configuration (see [OAuth Configuration](#oauth-configuration)) |
 | `isolation` | object | No | Per-server Docker isolation settings (see [Docker Isolation](#docker-isolation)) |
 | `enabled` | boolean | No | Enable/disable server (default: `true`) |

internal/config/config.go

@@ -58,6 +58,10 @@ func (d Duration) Duration() time.Duration {
 const (
 	defaultHealthCheckInterval   = 30 * time.Second
 	defaultToolDiscoveryInterval = 5 * time.Minute
+	// defaultInitTimeout is the deadline applied to a stdio/HTTP upstream's MCP
+	// `initialize` handshake when no per-server or global override is set
+	// (MCP-3322 / GH #760). It preserves the historical ~30s behaviour.
+	defaultInitTimeout = 30 * time.Second
 )
 
 // resolveInterval applies the per-server → global → default precedence for an
@@ -97,6 +101,23 @@ func (c *Config) ResolveToolDiscoveryInterval(sc *ServerConfig) time.Duration {
 	return resolveInterval(server, c.ToolDiscoveryInterval, defaultToolDiscoveryInterval)
 }
 
+// ResolveInitTimeout resolves the effective MCP `initialize` handshake deadline
+// for a server: per-server override → global → 30s default (MCP-3322 / GH #760).
+// Unlike the discovery intervals, a resolved value <= 0 maps to the default
+// rather than "disabled" — a zero/negative connect deadline would let a stuck
+// upstream hang the connect path forever, so we always keep a real ceiling.
+func (c *Config) ResolveInitTimeout(sc *ServerConfig) time.Duration {
+	var server *Duration
+	if sc != nil {
+		server = sc.InitTimeout
+	}
+	resolved := resolveInterval(server, c.InitTimeout, defaultInitTimeout)
+	if resolved <= 0 {
+		return defaultInitTimeout
+	}
+	return resolved
+}
+
 // Config represents the main configuration structure
 type Config struct {
 	Listen       string `json:"listen" mapstructure:"listen"`
@@ -127,6 +148,15 @@ type Config struct {
 	HealthCheckInterval   *Duration `json:"health_check_interval,omitempty" mapstructure:"health-check-interval" swaggertype:"string"`
 	ToolDiscoveryInterval *Duration `json:"tool_discovery_interval,omitempty" mapstructure:"tool-discovery-interval" swaggertype:"string"`
 
+	// InitTimeout is the global default deadline for an upstream's MCP
+	// `initialize` handshake (MCP-3322 / GH #760). *Duration tri-state: nil =
+	// inherit the built-in 30s default; a positive value = that deadline. A
+	// per-server InitTimeout overrides this. Resolved by ResolveInitTimeout;
+	// validated to {0} ∪ [1s, 30m] in Validate(). Servers doing legitimate
+	// first-run warmup (cache/index build) before answering `initialize` can
+	// raise this so they are not killed mid-startup.
+	InitTimeout *Duration `json:"init_timeout,omitempty" mapstructure:"init-timeout" swaggertype:"string"`
+
 	// Environment configuration for secure variable filtering
 	Environment *secureenv.EnvConfig `json:"environment,omitempty" mapstructure:"environment"`
 
@@ -367,6 +397,14 @@ type ServerConfig struct {
 	HealthCheckInterval   *Duration `json:"health_check_interval,omitempty" mapstructure:"health_check_interval" swaggertype:"string"`
 	ToolDiscoveryInterval *Duration `json:"tool_discovery_interval,omitempty" mapstructure:"tool_discovery_interval" swaggertype:"string"`
 
+	// InitTimeout overrides the global init_timeout for this server's MCP
+	// `initialize` handshake deadline (MCP-3322 / GH #760). *Duration tri-state:
+	// nil = inherit the global value (or 30s default), positive = that deadline.
+	// Resolved by Config.ResolveInitTimeout; validated to {0} ∪ [1s, 30m]. Raise
+	// this for upstreams that do legitimate first-run warmup (e.g. caching many
+	// channels/users) before responding to `initialize`.
+	InitTimeout *Duration `json:"init_timeout,omitempty" mapstructure:"init_timeout" swaggertype:"string"`
+
 	EnabledTools  []string `json:"enabled_tools,omitempty" mapstructure:"enabled_tools"`   // Allowlist: only these tools are exposed; mutually exclusive with disabled_tools
 	DisabledTools []string `json:"disabled_tools,omitempty" mapstructure:"disabled_tools"` // Denylist: these tools are hidden; mutually exclusive with enabled_tools
 
@@ -1455,6 +1493,9 @@ func (c *Config) ValidateDetailed() []ValidationError {
 	}
 
 	// Validate global discovery/health-check intervals (spec 074, FR-008).
+	if e := validateIntervalBound("init_timeout", c.InitTimeout, time.Second, 30*time.Minute); e != nil {
+		errors = append(errors, *e)
+	}
 	if e := validateIntervalBound("health_check_interval", c.HealthCheckInterval, 5*time.Second, time.Hour); e != nil {
 		errors = append(errors, *e)
 	}
@@ -1578,6 +1619,10 @@ func (c *Config) ValidateDetailed() []ValidationError {
 		if e := validateIntervalBound(fieldPrefix+".tool_discovery_interval", server.ToolDiscoveryInterval, 30*time.Second, 24*time.Hour); e != nil {
 			errors = append(errors, *e)
 		}
+		// MCP-3322: per-server MCP `initialize` handshake deadline override.
+		if e := validateIntervalBound(fieldPrefix+".init_timeout", server.InitTimeout, time.Second, 30*time.Minute); e != nil {
+			errors = append(errors, *e)
+		}
 	}
 
 	// Validate DataDir exists (if specified and not empty).

internal/config/init_timeout_test.go

@@ -0,0 +1,83 @@
+package config
+
+import (
+	"testing"
+	"time"
+)
+
+// TestResolveInitTimeout covers the per-server → global → default precedence
+// (MCP-3322 / GH #760). Unlike the discovery intervals, a resolved value <= 0
+// (including a pointer-to-zero override) maps to the 30s default rather than
+// "disabled" — we never want a hang-forever connect deadline.
+func TestResolveInitTimeout(t *testing.T) {
+	cases := []struct {
+		name   string
+		global *Duration
+		server *Duration
+		want   time.Duration
+	}{
+		{"both unset → default", nil, nil, 30 * time.Second},
+		{"global set, server unset → global", durPtr(120 * time.Second), nil, 120 * time.Second},
+		{"server override wins", durPtr(120 * time.Second), durPtr(90 * time.Second), 90 * time.Second},
+		{"server override wins over default when global unset", nil, durPtr(45 * time.Second), 45 * time.Second},
+		{"global zero → default (never disabled)", durPtr(0), nil, 30 * time.Second},
+		{"server zero → default (never disabled)", durPtr(120 * time.Second), durPtr(0), 30 * time.Second},
+		{"server negative → default", nil, durPtr(-5 * time.Second), 30 * time.Second},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			c := &Config{InitTimeout: tc.global}
+			sc := &ServerConfig{InitTimeout: tc.server}
+			got := c.ResolveInitTimeout(sc)
+			if got != tc.want {
+				t.Errorf("ResolveInitTimeout = %v, want %v", got, tc.want)
+			}
+		})
+	}
+
+	// A nil server config must still resolve via global → default.
+	c := &Config{InitTimeout: durPtr(120 * time.Second)}
+	if got := c.ResolveInitTimeout(nil); got != 120*time.Second {
+		t.Errorf("nil server: got %v, want 120s", got)
+	}
+}
+
+// TestValidateInitTimeoutBounds covers the bounds contract: 0s accepted (means
+// "use default"), in-range [1s, 30m] accepted, out-of-range rejected — for both
+// the global and per-server pointers.
+func TestValidateInitTimeoutBounds(t *testing.T) {
+	cases := []struct {
+		name      string
+		mutate    func(*Config)
+		wantError bool
+	}{
+		{"0s accepted (default)", func(c *Config) { c.InitTimeout = durPtr(0) }, false},
+		{"1s accepted (min)", func(c *Config) { c.InitTimeout = durPtr(time.Second) }, false},
+		{"30m accepted (max)", func(c *Config) { c.InitTimeout = durPtr(30 * time.Minute) }, false},
+		{"500ms rejected (below min)", func(c *Config) { c.InitTimeout = durPtr(500 * time.Millisecond) }, true},
+		{"31m rejected (above max)", func(c *Config) { c.InitTimeout = durPtr(31 * time.Minute) }, true},
+		{"negative rejected", func(c *Config) { c.InitTimeout = durPtr(-1 * time.Second) }, true},
+		{"per-server 500ms rejected", func(c *Config) {
+			c.Servers = []*ServerConfig{{Name: "s", InitTimeout: durPtr(500 * time.Millisecond)}}
+		}, true},
+		{"per-server 120s accepted", func(c *Config) {
+			c.Servers = []*ServerConfig{{Name: "s", InitTimeout: durPtr(120 * time.Second)}}
+		}, false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			c := DefaultConfig()
+			tc.mutate(c)
+			errs := c.ValidateDetailed()
+			hasErr := false
+			for _, e := range errs {
+				if containsAny(e.Field, "init_timeout") {
+					hasErr = true
+				}
+			}
+			if hasErr != tc.wantError {
+				t.Errorf("validation init_timeout error = %v, want %v (errors: %+v)", hasErr, tc.wantError, errs)
+			}
+		})
+	}
+}

internal/config/merge.go

@@ -319,6 +319,17 @@ func MergeServerConfig(base, patch *ServerConfig, opts MergeOptions) (*ServerCon
 		merged.OAuth = newOAuth
 	}
 
+	// InitTimeout (MCP-3322): *Duration tri-state. A non-nil pointer in the
+	// patch sets/replaces the per-server override; nil leaves the base value
+	// (already carried by CopyServerConfig) untouched.
+	if patch.InitTimeout != nil {
+		it := *patch.InitTimeout
+		if diff != nil && (base.InitTimeout == nil || *base.InitTimeout != it) {
+			diff.Modified["init_timeout"] = FieldChange{Path: "init_timeout", From: base.InitTimeout, To: patch.InitTimeout}
+		}
+		merged.InitTimeout = &it
+	}
+
 	// Always update the Updated timestamp
 	merged.Updated = time.Now()
 
@@ -588,6 +599,10 @@ func CopyServerConfig(src *ServerConfig) *ServerConfig {
 		td := *src.ToolDiscoveryInterval
 		dst.ToolDiscoveryInterval = &td
 	}
+	if src.InitTimeout != nil {
+		it := *src.InitTimeout
+		dst.InitTimeout = &it
+	}
 
 	// Copy the per-upstream auth-broker block by value (spec 074, server edition).
 	// In the personal edition AuthBrokerConfig is an empty stub struct, so this is

internal/config/merge_test.go

@@ -1006,19 +1006,25 @@ func TestCopyServerConfig_AllFields(t *testing.T) {
 func TestCopyServerConfig_PreservesAllowlistAndOverrides(t *testing.T) {
 	hc := Duration(30 * time.Second)
 	td := Duration(5 * time.Minute)
+	it := Duration(120 * time.Second)
 	src := &ServerConfig{
 		Name:                     "srv",
 		ReconnectOnUse:           true,
 		EnabledTools:             []string{"a", "b"},
 		DisabledTools:            []string{"c"},
 		HealthCheckInterval:      &hc,
 		ToolDiscoveryInterval:    &td,
+		InitTimeout:              &it,
 		SourceRegistryID:         "reg-1",
 		SourceRegistryProvenance: "official",
 	}
 
 	dst := CopyServerConfig(src)
 
+	if dst.InitTimeout == nil || *dst.InitTimeout != it {
+		t.Errorf("InitTimeout: got %v, want %v", dst.InitTimeout, it)
+	}
+
 	if !dst.ReconnectOnUse {
 		t.Error("ReconnectOnUse was dropped")
 	}
@@ -1052,6 +1058,57 @@ func TestCopyServerConfig_PreservesAllowlistAndOverrides(t *testing.T) {
 	}
 }
 
+// TestMergeServerConfig_InitTimeout covers MCP-3322: a patch carrying
+// init_timeout sets/replaces the per-server override (and records a diff), while
+// a patch that omits it preserves the existing value.
+func TestMergeServerConfig_InitTimeout(t *testing.T) {
+	t.Run("patch sets init_timeout from unset", func(t *testing.T) {
+		base := &ServerConfig{Name: "srv", Enabled: true}
+		it := Duration(120 * time.Second)
+		patch := &ServerConfig{InitTimeout: &it}
+
+		merged, diff, err := MergeServerConfig(base, patch, DefaultMergeOptions())
+		if err != nil {
+			t.Fatalf("merge: %v", err)
+		}
+		if merged.InitTimeout == nil || *merged.InitTimeout != it {
+			t.Errorf("InitTimeout: got %v, want %v", merged.InitTimeout, it)
+		}
+		if diff == nil || diff.Modified["init_timeout"].Path != "init_timeout" {
+			t.Errorf("expected init_timeout in diff, got %+v", diff)
+		}
+	})
+
+	t.Run("unrelated patch preserves init_timeout", func(t *testing.T) {
+		it := Duration(120 * time.Second)
+		base := &ServerConfig{Name: "srv", Enabled: true, InitTimeout: &it}
+		patch := &ServerConfig{Enabled: true, URL: "http://example.com/mcp"}
+
+		merged, _, err := MergeServerConfig(base, patch, DefaultMergeOptions())
+		if err != nil {
+			t.Fatalf("merge: %v", err)
+		}
+		if merged.InitTimeout == nil || *merged.InitTimeout != it {
+			t.Errorf("InitTimeout was wiped on unrelated patch: got %v, want %v", merged.InitTimeout, it)
+		}
+	})
+
+	t.Run("patch replaces existing init_timeout", func(t *testing.T) {
+		old := Duration(120 * time.Second)
+		base := &ServerConfig{Name: "srv", Enabled: true, InitTimeout: &old}
+		newVal := Duration(45 * time.Second)
+		patch := &ServerConfig{InitTimeout: &newVal}
+
+		merged, _, err := MergeServerConfig(base, patch, DefaultMergeOptions())
+		if err != nil {
+			t.Fatalf("merge: %v", err)
+		}
+		if merged.InitTimeout == nil || *merged.InitTimeout != newVal {
+			t.Errorf("InitTimeout: got %v, want %v", merged.InitTimeout, newVal)
+		}
+	})
+}
+
 // TestMergeServerConfig_PreservesDisabledToolsOnUnrelatedPatch is the
 // end-to-end regression: patching an unrelated field on a server that has a
 // disabled_tools denylist must not wipe the denylist (it previously did,

internal/contracts/converters.go

@@ -36,6 +36,9 @@ func ConvertServerConfig(cfg *config.ServerConfig, status string, connected bool
 		// MCP-2940: surface the per-server auto-approve intent (tri-state *bool)
 		// so the Web UI toggle reflects the persisted value.
 		AutoApproveToolChanges: cfg.AutoApproveToolChanges,
+		// MCP-3322: surface the per-server init_timeout override so callers can
+		// read back a configured handshake deadline.
+		InitTimeout: cfg.InitTimeout,
 	}
 
 	// Convert OAuth config if present
@@ -187,6 +190,14 @@ func ConvertGenericServersToTyped(genericServers []map[string]interface{}) []Ser
 			v := autoApprove
 			server.AutoApproveToolChanges = &v
 		}
+		// MCP-3322: init_timeout serializes as a duration string (e.g. "120s").
+		// Parse it back into a *config.Duration so the GET payload round-trips.
+		if initTimeout, ok := generic["init_timeout"].(string); ok && initTimeout != "" {
+			if d, err := time.ParseDuration(initTimeout); err == nil {
+				v := config.Duration(d)
+				server.InitTimeout = &v
+			}
+		}
 		if connected, ok := generic["connected"].(bool); ok {
 			server.Connected = connected
 		}