feat: MCP_GATEWAY_TOOL_TIMEOUT env var + minimum 10s bound for toolTimeout (no upper limit) (#4967)

Slow MCP backends (e.g. Repo Mind full-text search) fail with the
hardcoded 60s tool timeout and had no way to override it per-workflow.
The `toolTimeout` field already existed in the stdin JSON schema but
lacked an env var fallback.

## Changes

**Env var fallback (`MCP_GATEWAY_TOOL_TIMEOUT`)**
- Priority chain: stdin `gateway.toolTimeout` →
`MCP_GATEWAY_TOOL_TIMEOUT` env var → built-in default (60s)
- Applied in `convertStdinConfig` for both "gateway section present" and
"no gateway section" paths
- Public `GetGatewayToolTimeoutFromEnv()` + private
`toolTimeoutEnvOrDefault()` in `config_env.go`
- Env var is only evaluated when stdin omits `gateway.toolTimeout`,
avoiding spurious log noise

**Bounds enforcement (minimum 10s, no upper limit)**
- New `rules.TimeoutMinimum(timeout, min, ...)` function for
minimum-only validation
- `validateGatewayConfig` uses `TimeoutMinimum(10)` for `toolTimeout` —
any value ≥ 10 seconds is accepted
- JSON schema updated: `minimum: 10` (no `maximum`)
- Constant `ToolTimeoutMin = 10` exported from `config_env.go`

**Example usage**

```json
{
  "gateway": {
    "toolTimeout": 3600
  },
  "mcpServers": { "repo-mind": { "type": "http", "url": "..." } }
}
```
Or without touching the config:
```bash
MCP_GATEWAY_TOOL_TIMEOUT=3600 ./awmg --config-stdin ...
```

**Test updates**
- New table-driven tests for `GetGatewayToolTimeoutFromEnv`,
`toolTimeoutEnvOrDefault`, and the three-level priority in
`convertStdinConfig`
- Tests cover large values (3600 = 1 hour, 86400 = 24 hours) to confirm
no upper bound
- Existing tests updated to reflect the minimum-only constraint

Author: lpcox

AGENTS.md

@@ -386,6 +386,7 @@ DEBUG_COLORS=0 DEBUG=* ./awmg --config config.toml
 - `MCP_GATEWAY_PAYLOAD_PATH_PREFIX` - Path prefix for remapping payloadPath returned to clients (sets default for `--payload-path-prefix` flag, default: empty)
 - `MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD` - Size threshold in bytes for payload storage; payloads larger than this are stored to disk (sets default for `--payload-size-threshold` flag, default: `524288`)
 - `MCP_GATEWAY_SESSION_TIMEOUT` - Session timeout for stateful sessions in both unified mode (`/mcp`) and routed mode (`/mcp/<server>`). Accepts Go duration strings (e.g., `30m`, `1h`, `2h30m`). (default: `6h`)
+- `MCP_GATEWAY_TOOL_TIMEOUT` - Tool invocation timeout in seconds. Fallback when `gateway.toolTimeout` is not set in stdin JSON config. Accepts any integer ≥ 10 (no upper bound). Priority: stdin config > env var > built-in default. (default: `60`)
 - `DOCKER_HOST` - Docker daemon socket path (default: `/var/run/docker.sock`)
 - `MCP_GATEWAY_GUARDS_SINK_SERVER_IDS` - Comma-separated server IDs whose RPC JSONL logs should include agent secrecy/integrity tag snapshots (sets default for `--guards-sink-server-ids`)
 - `MCP_GATEWAY_GUARDS_MODE` - Guards enforcement mode: `strict` (deny violations), `filter` (remove denied tools), `propagate` (auto-adjust agent labels) (sets default for `--guards-mode`, default: `strict`)

docs/ENVIRONMENT_VARIABLES.md

@@ -26,6 +26,7 @@ When running locally (`run.sh`), these variables are optional (warnings shown if
 | `MCP_GATEWAY_PAYLOAD_PATH_PREFIX` | Path prefix for remapping payloadPath returned to clients (sets default for `--payload-path-prefix` flag) | (empty - use actual filesystem path) |
 | `MCP_GATEWAY_PAYLOAD_SIZE_THRESHOLD` | Size threshold in bytes for payload storage (sets default for `--payload-size-threshold` flag) | `524288` |
 | `MCP_GATEWAY_SESSION_TIMEOUT` | Session timeout for stateful sessions in both unified (`/mcp`) and routed (`/mcp/<server>`) modes. Accepts Go duration strings (e.g., `30m`, `1h`). Default is 6 hours to match the GitHub Actions default timeout. | `6h` |
+| `MCP_GATEWAY_TOOL_TIMEOUT` | Tool invocation timeout in seconds. Used as fallback when `gateway.toolTimeout` is not set in the stdin JSON config. Accepts any integer ≥ 10 (no upper bound). Priority: stdin `gateway.toolTimeout` > this env var > built-in default. | `60` |
 | `MCP_GATEWAY_WASM_GUARDS_DIR` | Root directory for per-server WASM guards (`<root>/<serverID>/*.wasm`, first match is loaded) | (disabled) |
 | `MCP_GATEWAY_GUARDS_MODE` | Guards enforcement mode: `strict` (deny violations), `filter` (remove denied tools), `propagate` (auto-adjust agent labels) (sets default for `--guards-mode`) | `strict` |
 | `MCP_GATEWAY_GUARDS_SINK_SERVER_IDS` | Comma-separated sink server IDs for JSONL guards tag enrichment (sets default for `--guards-sink-server-ids`) | (disabled) |

internal/config/config_env.go

@@ -8,6 +8,9 @@ import (
 	"github.com/github/gh-aw-mcpg/internal/envutil"
 )
 
+// ToolTimeoutMin is the minimum allowed value for toolTimeout (seconds).
+const ToolTimeoutMin = 10
+
 // GetGatewayPortFromEnv returns the MCP_GATEWAY_PORT value, parsed as int
 func GetGatewayPortFromEnv() (int, error) {
 	portStr := envutil.GetEnvString("MCP_GATEWAY_PORT", "")
@@ -50,3 +53,42 @@ func GetGatewayAPIKeyFromEnv() string {
 	}
 	return key
 }
+
+// GetGatewayToolTimeoutFromEnv returns the MCP_GATEWAY_TOOL_TIMEOUT value, parsed as int.
+// Returns (0, false) when the environment variable is not set or empty.
+// Returns an error when the variable is set but invalid (non-integer or below minimum of 10).
+func GetGatewayToolTimeoutFromEnv() (int, bool, error) {
+	timeoutStr := envutil.GetEnvString("MCP_GATEWAY_TOOL_TIMEOUT", "")
+	if timeoutStr == "" {
+		logConfig.Print("MCP_GATEWAY_TOOL_TIMEOUT not set in environment")
+		return 0, false, nil
+	}
+
+	timeout, err := strconv.Atoi(timeoutStr)
+	if err != nil {
+		logConfig.Printf("MCP_GATEWAY_TOOL_TIMEOUT=%q is not a valid integer: %v", timeoutStr, err)
+		return 0, false, fmt.Errorf("invalid MCP_GATEWAY_TOOL_TIMEOUT value: %s", timeoutStr)
+	}
+
+	if validationErr := rules.TimeoutMinimum(timeout, ToolTimeoutMin, "MCP_GATEWAY_TOOL_TIMEOUT", "MCP_GATEWAY_TOOL_TIMEOUT"); validationErr != nil {
+		logConfig.Printf("MCP_GATEWAY_TOOL_TIMEOUT=%d is below minimum %d: %s", timeout, ToolTimeoutMin, validationErr.Message)
+		return 0, false, fmt.Errorf("%s", validationErr.Message)
+	}
+
+	logConfig.Printf("MCP_GATEWAY_TOOL_TIMEOUT resolved to %d", timeout)
+	return timeout, true, nil
+}
+
+// toolTimeoutEnvOrDefault returns the value of MCP_GATEWAY_TOOL_TIMEOUT when set and valid,
+// otherwise DefaultToolTimeout. Invalid env var values are logged and ignored (fallback to default).
+func toolTimeoutEnvOrDefault() int {
+	timeout, ok, err := GetGatewayToolTimeoutFromEnv()
+	if err != nil {
+		logConfig.Printf("MCP_GATEWAY_TOOL_TIMEOUT is invalid, falling back to default %d: %v", DefaultToolTimeout, err)
+		return DefaultToolTimeout
+	}
+	if !ok {
+		return DefaultToolTimeout
+	}
+	return timeout
+}

internal/config/config_stdin.go

@@ -309,9 +309,13 @@ func convertStdinConfig(stdinCfg *StdinConfig) (*Config, error) {
 			APIKey:            stdinCfg.Gateway.APIKey,
 			Domain:            stdinCfg.Gateway.Domain,
 			StartupTimeout:    intPtrOrDefault(stdinCfg.Gateway.StartupTimeout, DefaultStartupTimeout),
-			ToolTimeout:       intPtrOrDefault(stdinCfg.Gateway.ToolTimeout, DefaultToolTimeout),
 			KeepaliveInterval: intPtrOrDefault(stdinCfg.Gateway.KeepaliveInterval, DefaultKeepaliveInterval),
 		}
+		if stdinCfg.Gateway.ToolTimeout != nil {
+			cfg.Gateway.ToolTimeout = *stdinCfg.Gateway.ToolTimeout
+		} else {
+			cfg.Gateway.ToolTimeout = toolTimeoutEnvOrDefault()
+		}
 		if stdinCfg.Gateway.PayloadDir != "" {
 			cfg.Gateway.PayloadDir = stdinCfg.Gateway.PayloadDir
 		}
@@ -328,6 +332,10 @@ func convertStdinConfig(stdinCfg *StdinConfig) (*Config, error) {
 		logStdin.Print("No gateway config in stdin, applying defaults")
 		cfg.Gateway = &GatewayConfig{}
 		applyGatewayDefaults(cfg.Gateway)
+		// Apply MCP_GATEWAY_TOOL_TIMEOUT env var if set. toolTimeoutEnvOrDefault() returns
+		// the env var value when valid and present, otherwise DefaultToolTimeout (which
+		// applyGatewayDefaults already wrote). This is a no-op when the env var is absent.
+		cfg.Gateway.ToolTimeout = toolTimeoutEnvOrDefault()
 	}
 
 	// Apply feature-specific defaults

internal/config/docker_helpers_and_env_test.go

@@ -108,3 +108,234 @@ func TestGetGatewayPortFromEnv_Comprehensive(t *testing.T) {
 		})
 	}
 }
+
+// TestGetGatewayToolTimeoutFromEnv tests the env-based tool timeout parsing.
+func TestGetGatewayToolTimeoutFromEnv(t *testing.T) {
+	tests := []struct {
+		name        string
+		envValue    string
+		envSet      bool
+		wantTimeout int
+		wantOK      bool
+		wantErr     bool
+		errMsg      string
+	}{
+		{
+			name:    "env var not set",
+			envSet:  false,
+			wantOK:  false,
+			wantErr: false,
+		},
+		{
+			name:     "env var set to empty string",
+			envValue: "",
+			envSet:   true,
+			wantOK:   false,
+			wantErr:  false,
+		},
+		{
+			name:     "invalid integer value",
+			envValue: "not-a-number",
+			envSet:   true,
+			wantOK:   false,
+			wantErr:  true,
+			errMsg:   "invalid MCP_GATEWAY_TOOL_TIMEOUT value",
+		},
+		{
+			name:     "below minimum (9)",
+			envValue: "9",
+			envSet:   true,
+			wantOK:   false,
+			wantErr:  true,
+			errMsg:   "must be at least 10",
+		},
+		{
+			name:     "zero (out of range)",
+			envValue: "0",
+			envSet:   true,
+			wantOK:   false,
+			wantErr:  true,
+			errMsg:   "must be at least 10",
+		},
+		{
+			name:     "negative value",
+			envValue: "-1",
+			envSet:   true,
+			wantOK:   false,
+			wantErr:  true,
+			errMsg:   "must be at least 10",
+		},
+		{
+			name:        "valid minimum boundary (10)",
+			envValue:    "10",
+			envSet:      true,
+			wantTimeout: 10,
+			wantOK:      true,
+			wantErr:     false,
+		},
+		{
+			name:        "valid default value (60)",
+			envValue:    "60",
+			envSet:      true,
+			wantTimeout: 60,
+			wantOK:      true,
+			wantErr:     false,
+		},
+		{
+			name:        "valid high value (120)",
+			envValue:    "120",
+			envSet:      true,
+			wantTimeout: 120,
+			wantOK:      true,
+			wantErr:     false,
+		},
+		{
+			name:        "valid large value (3600 = 1 hour)",
+			envValue:    "3600",
+			envSet:      true,
+			wantTimeout: 3600,
+			wantOK:      true,
+			wantErr:     false,
+		},
+		{
+			name:        "valid very large value (86400 = 24 hours)",
+			envValue:    "86400",
+			envSet:      true,
+			wantTimeout: 86400,
+			wantOK:      true,
+			wantErr:     false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if tt.envSet {
+				t.Setenv("MCP_GATEWAY_TOOL_TIMEOUT", tt.envValue)
+			} else {
+				os.Unsetenv("MCP_GATEWAY_TOOL_TIMEOUT")
+			}
+
+			timeout, ok, err := GetGatewayToolTimeoutFromEnv()
+			if tt.wantErr {
+				require.Error(t, err)
+				assert.False(t, ok)
+				if tt.errMsg != "" {
+					assert.Contains(t, err.Error(), tt.errMsg)
+				}
+				assert.Equal(t, 0, timeout)
+			} else {
+				require.NoError(t, err)
+				assert.Equal(t, tt.wantOK, ok)
+				if tt.wantOK {
+					assert.Equal(t, tt.wantTimeout, timeout)
+				} else {
+					assert.Equal(t, 0, timeout)
+				}
+			}
+		})
+	}
+}
+
+// TestToolTimeoutEnvOrDefault tests that toolTimeoutEnvOrDefault uses the env var when set.
+func TestToolTimeoutEnvOrDefault(t *testing.T) {
+	t.Run("returns DefaultToolTimeout when env var is not set", func(t *testing.T) {
+		t.Setenv("MCP_GATEWAY_TOOL_TIMEOUT", "")
+		got := toolTimeoutEnvOrDefault()
+		assert.Equal(t, DefaultToolTimeout, got, "should return DefaultToolTimeout when env var is empty")
+	})
+
+	t.Run("returns env var value when set to valid value", func(t *testing.T) {
+		t.Setenv("MCP_GATEWAY_TOOL_TIMEOUT", "120")
+		got := toolTimeoutEnvOrDefault()
+		assert.Equal(t, 120, got, "should return 120 from env var")
+	})
+
+	t.Run("returns DefaultToolTimeout when env var has invalid value", func(t *testing.T) {
+		t.Setenv("MCP_GATEWAY_TOOL_TIMEOUT", "not-a-number")
+		got := toolTimeoutEnvOrDefault()
+		assert.Equal(t, DefaultToolTimeout, got, "should fall back to default on invalid env var")
+	})
+
+	t.Run("returns env var value at minimum boundary (10)", func(t *testing.T) {
+		t.Setenv("MCP_GATEWAY_TOOL_TIMEOUT", "10")
+		got := toolTimeoutEnvOrDefault()
+		assert.Equal(t, 10, got, "should return 10 at minimum boundary")
+	})
+
+	t.Run("returns env var large value (3600 = 1 hour)", func(t *testing.T) {
+		t.Setenv("MCP_GATEWAY_TOOL_TIMEOUT", "3600")
+		got := toolTimeoutEnvOrDefault()
+		assert.Equal(t, 3600, got, "should return 3600 (1 hour)")
+	})
+}
+
+// TestConvertStdinConfig_ToolTimeoutEnvFallback verifies the stdin config priority:
+// stdin config value > MCP_GATEWAY_TOOL_TIMEOUT env var > built-in default.
+func TestConvertStdinConfig_ToolTimeoutEnvFallback(t *testing.T) {
+	t.Run("stdin value takes priority over env var", func(t *testing.T) {
+		t.Setenv("MCP_GATEWAY_TOOL_TIMEOUT", "120")
+		stdinCfg := &StdinConfig{
+			MCPServers: map[string]*StdinServerConfig{
+				"test": {Type: "stdio", Container: "test/server:latest"},
+			},
+			Gateway: &StdinGatewayConfig{
+				ToolTimeout: intPtr(300),
+			},
+		}
+		cfg, err := convertStdinConfig(stdinCfg)
+		require.NoError(t, err)
+		assert.Equal(t, 300, cfg.Gateway.ToolTimeout, "stdin value (300) should override env var (120)")
+	})
+
+	t.Run("env var used as fallback when stdin omits toolTimeout", func(t *testing.T) {
+		t.Setenv("MCP_GATEWAY_TOOL_TIMEOUT", "120")
+		stdinCfg := &StdinConfig{
+			MCPServers: map[string]*StdinServerConfig{
+				"test": {Type: "stdio", Container: "test/server:latest"},
+			},
+			Gateway: &StdinGatewayConfig{}, // toolTimeout not set
+		}
+		cfg, err := convertStdinConfig(stdinCfg)
+		require.NoError(t, err)
+		assert.Equal(t, 120, cfg.Gateway.ToolTimeout, "env var (120) should be used when stdin omits toolTimeout")
+	})
+
+	t.Run("built-in default used when both stdin and env var are absent", func(t *testing.T) {
+		t.Setenv("MCP_GATEWAY_TOOL_TIMEOUT", "")
+		stdinCfg := &StdinConfig{
+			MCPServers: map[string]*StdinServerConfig{
+				"test": {Type: "stdio", Container: "test/server:latest"},
+			},
+			Gateway: &StdinGatewayConfig{}, // toolTimeout not set
+		}
+		cfg, err := convertStdinConfig(stdinCfg)
+		require.NoError(t, err)
+		assert.Equal(t, DefaultToolTimeout, cfg.Gateway.ToolTimeout, "built-in default should be used when both stdin and env var are absent")
+	})
+
+	t.Run("env var used when no gateway section in stdin", func(t *testing.T) {
+		t.Setenv("MCP_GATEWAY_TOOL_TIMEOUT", "180")
+		stdinCfg := &StdinConfig{
+			MCPServers: map[string]*StdinServerConfig{
+				"test": {Type: "stdio", Container: "test/server:latest"},
+			},
+			// no Gateway section
+		}
+		cfg, err := convertStdinConfig(stdinCfg)
+		require.NoError(t, err)
+		assert.Equal(t, 180, cfg.Gateway.ToolTimeout, "env var (180) should be used when no gateway section present")
+	})
+
+	t.Run("built-in default used when no gateway section and no env var", func(t *testing.T) {
+		t.Setenv("MCP_GATEWAY_TOOL_TIMEOUT", "")
+		stdinCfg := &StdinConfig{
+			MCPServers: map[string]*StdinServerConfig{
+				"test": {Type: "stdio", Container: "test/server:latest"},
+			},
+			// no Gateway section
+		}
+		cfg, err := convertStdinConfig(stdinCfg)
+		require.NoError(t, err)
+		assert.Equal(t, DefaultToolTimeout, cfg.Gateway.ToolTimeout, "built-in default should be used when no gateway section and no env var")
+	})
+}

internal/config/rules/rules.go

@@ -120,6 +120,39 @@ func TimeoutPositive(timeout int, fieldName, jsonPath string) *ValidationError {
 	return nil
 }
 
+// TimeoutMinimum validates that a timeout value is at least min.
+// Returns nil if valid, *ValidationError if below the minimum.
+func TimeoutMinimum(timeout, min int, fieldName, jsonPath string) *ValidationError {
+	log.Printf("Validating timeout minimum: field=%s, value=%d, min=%d, jsonPath=%s", fieldName, timeout, min, jsonPath)
+	if timeout < min {
+		log.Printf("Timeout minimum validation failed: %s=%d is below minimum %d", fieldName, timeout, min)
+		return &ValidationError{
+			Field:      fieldName,
+			Message:    fmt.Sprintf("%s must be at least %d, got %d", fieldName, min, timeout),
+			JSONPath:   jsonPath,
+			Suggestion: fmt.Sprintf("Use a value of at least %d seconds", min),
+		}
+	}
+	return nil
+}
+
+// TimeoutRange validates that a timeout value is within [min, max] (inclusive).
+// Returns nil if valid, *ValidationError if outside the range.
+func TimeoutRange(timeout, min, max int, fieldName, jsonPath string) *ValidationError {
+	log.Printf("Validating timeout range: field=%s, value=%d, min=%d, max=%d, jsonPath=%s", fieldName, timeout, min, max, jsonPath)
+	if timeout < min || timeout > max {
+		log.Printf("Timeout range validation failed: %s=%d is outside [%d, %d]", fieldName, timeout, min, max)
+		suggestedTimeout := min + (max-min)/2
+		return &ValidationError{
+			Field:      fieldName,
+			Message:    fmt.Sprintf("%s must be between %d and %d, got %d", fieldName, min, max, timeout),
+			JSONPath:   jsonPath,
+			Suggestion: fmt.Sprintf("Use a value between %d and %d seconds (e.g., %d)", min, max, suggestedTimeout),
+		}
+	}
+	return nil
+}
+
 // MountFormat validates a mount specification in the format "source:dest:mode"
 // Returns nil if valid, *ValidationError if invalid
 // Per MCP Gateway specification v1.8.0 section 4.1.5:

internal/config/schema/mcp-gateway-config.schema.json

@@ -251,7 +251,7 @@
         "toolTimeout": {
           "type": "integer",
           "description": "Tool invocation timeout in seconds. The gateway enforces this timeout for individual tool/method calls to MCP servers.",
-          "minimum": 1,
+          "minimum": 10,
           "default": 60
         },
         "payloadDir": {

internal/config/validation.go

@@ -359,7 +359,7 @@ func validateGatewayConfig(gateway *StdinGatewayConfig) error {
 
 	if gateway.ToolTimeout != nil {
 		logValidation.Printf("Validating tool timeout: %d", *gateway.ToolTimeout)
-		if err := rules.TimeoutPositive(*gateway.ToolTimeout, "toolTimeout", "gateway.toolTimeout"); err != nil {
+		if err := rules.TimeoutMinimum(*gateway.ToolTimeout, ToolTimeoutMin, "toolTimeout", "gateway.toolTimeout"); err != nil {
 			return err
 		}
 	}