feat: add per-server tool_timeout to override global gateway timeout (#5206)

Reusable shared workflows wrapping long-running HTTP MCP servers (e.g.
Repo Mind Light) have no way to set the gateway's tool invocation
timeout — consumers must know to configure `MCP_GATEWAY_TOOL_TIMEOUT` in
`sandbox.mcp.env`, breaking the reusable component contract.

## Changes

- **`ServerConfig.ToolTimeout`** — new per-server field (TOML:
`tool_timeout`, JSON stdin: `tool_timeout`); minimum 10s; zero/omitted
means fall back to `gateway.toolTimeout`
- **`callBackendTool`** — per-server `ToolTimeout` takes precedence over
`gateway.ToolTimeout` when set
- **JSON schema** — `tool_timeout` added to `stdioServerConfig` and
`httpServerConfig` definitions so stdin validation accepts the field
- **Validation** — `validateStandardServerConfig` enforces minimum of 10
for per-server `tool_timeout`
- **Docs** — `CONFIGURATION.md` documents the field and its relationship
to the global timeout

## Example

A reusable shared workflow can now declare its own timeout directly on
the server:

```json
{
  "mcpServers": {
    "repo-mind": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp",
      "tool_timeout": 600
    }
  },
  "gateway": { "port": 3000, "domain": "localhost", "apiKey": "${API_KEY}" }
}
```

Consumers get a sane 600s timeout without needing to know about
`MCP_GATEWAY_TOOL_TIMEOUT`. They can still override at the consumer
level if needed.

> [!WARNING]
>
> <details>
> <summary>Firewall rules blocked me from connecting to one or more
addresses (expand for details)</summary>
>
> #### I tried to connect to the following addresses, but was blocked by
firewall rules:
>
> - `example.com`
> - Triggering command: `/tmp/go-build2847888803/b509/launcher.test
/tmp/go-build2847888803/b509/launcher.test
-test.testlogfile=/tmp/go-build2847888803/b509/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true 997891/b463/_pkg_.a
-trimpath ache/go/1.25.9/x64/pkg/tool/linux_amd64/vet -p ny/timefmt-go
-lang=go1.25 ache/go/1.25.9/x-buildtags` (dns block)
> - Triggering command: `/tmp/go-build1669811436/b513/launcher.test
/tmp/go-build1669811436/b513/launcher.test
-test.testlogfile=/tmp/go-build1669811436/b513/testlog.txt
-test.paniconexit0 -test.timeout=10m0s dock�� -stringintconv -tests
64/pkg/tool/linux_amd64/link _.a 997891/b150/ x_amd64/vet
64/pkg/tool/linux_amd64/link --no�� test.test x_amd64/vet x_amd64/vet
1.80.0/channelz/docker 997891/b150/ 64/pkg/tool/linu-nilfunc
x_amd64/vet` (dns block)
> - `invalid-host-that-does-not-exist-12345.com`
> - Triggering command: `/tmp/go-build871958364/b001/config.test
/tmp/go-build871958364/b001/config.test -test.paniconexit0
-test.timeout=2m0s -test.count=1 rtcf��
1024825-9d38bb4040a9/status/status.pb.go
64/src/internal/google.golang.org/grpc/internal/channelz x86_64/as` (dns
block)
> - Triggering command: `/tmp/go-build2847888803/b491/config.test
/tmp/go-build2847888803/b491/config.test
-test.testlogfile=/tmp/go-build2847888803/b491/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true msSmPlS8N cfg
x_amd64/vet . -imultiarch x86_64-linux-gnu--noprofile x_amd64/vet 9978��
om/spf13/[email protected]/active_he-errorsas cfg x_amd64/vet --gdwarf-5
b/gh-aw-mcpg/intphp8.3 -o x_amd64/vet` (dns block)
> - Triggering command: `/tmp/go-build1669811436/b495/config.test
/tmp/go-build1669811436/b495/config.test
-test.testlogfile=/tmp/go-build1669811436/b495/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -ato�� -bool -buildtags
x_amd64/vet -errorsas -ifaceassert -nilfunc x_amd64/vet run test -tests
ache/go/1.25.9/x64/pkg/tool/linux_amd64/compile _.a
aw-mcpg/internal/tmp/go-build1282575160/b425/vet.cfg x_amd64/vet
ache/go/1.25.9/x64/pkg/tool/linux_amd64/compile` (dns block)
> - `nonexistent.local`
> - Triggering command: `/tmp/go-build2847888803/b509/launcher.test
/tmp/go-build2847888803/b509/launcher.test
-test.testlogfile=/tmp/go-build2847888803/b509/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true 997891/b463/_pkg_.a
-trimpath ache/go/1.25.9/x64/pkg/tool/linux_amd64/vet -p ny/timefmt-go
-lang=go1.25 ache/go/1.25.9/x-buildtags` (dns block)
> - Triggering command: `/tmp/go-build1669811436/b513/launcher.test
/tmp/go-build1669811436/b513/launcher.test
-test.testlogfile=/tmp/go-build1669811436/b513/testlog.txt
-test.paniconexit0 -test.timeout=10m0s dock�� -stringintconv -tests
64/pkg/tool/linux_amd64/link _.a 997891/b150/ x_amd64/vet
64/pkg/tool/linux_amd64/link --no�� test.test x_amd64/vet x_amd64/vet
1.80.0/channelz/docker 997891/b150/ 64/pkg/tool/linu-nilfunc
x_amd64/vet` (dns block)
> - `slow.example.com`
> - Triggering command: `/tmp/go-build2847888803/b509/launcher.test
/tmp/go-build2847888803/b509/launcher.test
-test.testlogfile=/tmp/go-build2847888803/b509/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true 997891/b463/_pkg_.a
-trimpath ache/go/1.25.9/x64/pkg/tool/linux_amd64/vet -p ny/timefmt-go
-lang=go1.25 ache/go/1.25.9/x-buildtags` (dns block)
> - Triggering command: `/tmp/go-build1669811436/b513/launcher.test
/tmp/go-build1669811436/b513/launcher.test
-test.testlogfile=/tmp/go-build1669811436/b513/testlog.txt
-test.paniconexit0 -test.timeout=10m0s dock�� -stringintconv -tests
64/pkg/tool/linux_amd64/link _.a 997891/b150/ x_amd64/vet
64/pkg/tool/linux_amd64/link --no�� test.test x_amd64/vet x_amd64/vet
1.80.0/channelz/docker 997891/b150/ 64/pkg/tool/linu-nilfunc
x_amd64/vet` (dns block)
> - `this-host-does-not-exist-12345.com`
> - Triggering command: `/tmp/go-build2847888803/b518/mcp.test
/tmp/go-build2847888803/b518/mcp.test
-test.testlogfile=/tmp/go-build2847888803/b518/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true se
958364/b060/vet.cfg ache/go/1.25.9/x64/pkg/tool/linux_amd64/vet .
--gdwarf2 --64 ache/go/1.25.9/x-trimpath` (dns block)
> - Triggering command: `/tmp/go-build3024656909/b518/mcp.test
/tmp/go-build3024656909/b518/mcp.test
-test.testlogfile=/tmp/go-build3024656909/b518/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true
/tmp/go-build689997891/b448/_pkg_.a -trimpath docker-buildx -p
go.opentelemetryinspect -lang=go1.24 docker-buildx -uns��
-unreachable=false /tmp/go-build871958364/b091/vet.-ifaceassert .cfg
-c=4 -nolocalimports -importcfg
ache/go/1.25.9/x64/pkg/tool/linu{{.Config.OpenStdin}}` (dns block)
> - Triggering command: `/tmp/go-build3319390857/b518/mcp.test
/tmp/go-build3319390857/b518/mcp.test
-test.testlogfile=/tmp/go-build3319390857/b518/testlog.txt
-test.paniconexit0 -test.timeout=10m0s -test.v=true g_.a
/tmp/go-build871958364/b023/vet.journal-or-kmsg x_amd64/vet -c=4
-nolocalimports -importcfg x_amd64/vet -uns�� hI9joKUGJ
/tmp/go-build871958364/b152/vet.cfg
ache/go/1.25.9/x64/pkg/tool/linux_amd64/vet en.go en.go
ache/go/1.25.9/x-o ctHi6v3/br4fXcgGpaHZ4LUv69Ml` (dns block)
>
> If you need me to access, download, or install something from one of
these locations, you can either:
>
> - Configure [Actions setup
steps](https://gh.io/copilot/actions-setup-steps) to set up my
environment, which run before the firewall is enabled
> - Add the appropriate URLs or hosts to the custom allowlist in this
repository's [Copilot coding agent
settings](https://github.com/github/gh-aw-mcpg/settings/copilot/coding_agent)
(admins only)
>
> </details>

Author: lpcox

docs/CONFIGURATION.md

@@ -176,6 +176,11 @@ Run `./awmg --help` for full CLI options. Key flags:
 
 - **`connect_timeout`** (optional, HTTP servers only): Per-transport connection timeout in seconds for connecting to HTTP backends. The gateway tries streamable HTTP, then SSE, then plain JSON-RPC over HTTP POST in sequence; this timeout applies to each attempt. It does **not** set the end-to-end `tools/call` execution timeout. Default: `30`.
 
+- **`tool_timeout`** (optional): Per-server tool invocation timeout in seconds. When set to a positive value, overrides the global tool timeout for `tools/call` requests to this specific server. This allows reusable shared workflow components wrapping long-running HTTP MCP servers to set an appropriate timeout once, without requiring every consumer to configure `MCP_GATEWAY_TOOL_TIMEOUT`. Minimum: `10`. Omit the field (or set to `0`) to fall back to the global timeout.
+  - Global timeout field name: **`toolTimeout`** in stdin JSON (`gateway.toolTimeout`), **`tool_timeout`** in TOML (`[gateway]` → `tool_timeout`)
+  - Example (stdin JSON): `"tool_timeout": 600` on an HTTP MCP server that may take up to 10 minutes
+  - Example (TOML): `tool_timeout = 600` under a `[servers.my-server]` section
+
 - **`rate_limit_threshold`** (optional, TOML/JSON file configs only): Number of consecutive rate-limit errors from this backend that will trip the circuit breaker (transition CLOSED → OPEN). When OPEN, requests are immediately rejected until the breaker is eligible to transition to HALF-OPEN again; this is normally controlled by `rate_limit_cooldown`, but if the gateway knows an upstream rate-limit reset time (for example from response headers or parsed tool error text), that reset time takes precedence. **Not available in JSON stdin format.** Default: `3`.
 
 - **`rate_limit_cooldown`** (optional, TOML/JSON file configs only): Default number of seconds before the circuit breaker allows a single probe request (transition OPEN → HALF-OPEN). If the gateway knows an upstream rate-limit reset time, it uses that reset time instead of this cooldown to decide when to probe again. If the probe succeeds the circuit closes; if rate-limited again it re-opens. **Not available in JSON stdin format.** Default: `60`.

internal/config/config_core.go

@@ -217,6 +217,11 @@ type ServerConfig struct {
 	// slow to initialize. Only applies to HTTP server types. Default: 30 seconds.
 	ConnectTimeout int `toml:"connect_timeout" json:"connect_timeout,omitempty"`
 
+	// ToolTimeout is the per-server maximum time (seconds) to wait for a single tool invocation.
+	// When set, this overrides the global gateway.tool_timeout for calls to this server only.
+	// Minimum: 10. When 0 (unset), the global gateway.tool_timeout is used.
+	ToolTimeout int `toml:"tool_timeout" json:"tool_timeout,omitempty"`
+
 	// RateLimitThreshold is the number of consecutive rate-limit errors from this backend
 	// that will trip the circuit breaker (transition CLOSED → OPEN). When OPEN, requests
 	// are immediately rejected until the cooldown period elapses. Default: 3.

internal/config/config_stdin.go

@@ -127,6 +127,12 @@ type StdinServerConfig struct {
 	// Only applies to HTTP server types. Default: 30 seconds.
 	ConnectTimeout *int `json:"connect_timeout,omitempty"`
 
+	// ToolTimeout is the per-server maximum time (seconds) to wait for a single tool invocation.
+	// When set to a positive value, this overrides the global gateway.toolTimeout for calls to
+	// this server only. Minimum: 10. Omit the field (or set to 0) to fall back to the global
+	// gateway.toolTimeout (or MCP_GATEWAY_TOOL_TIMEOUT env fallback).
+	ToolTimeout *int `json:"tool_timeout,omitempty"`
+
 	// AdditionalProperties stores any extra fields for custom server types
 	// This allows custom schemas to define their own fields beyond the standard ones
 	AdditionalProperties map[string]interface{} `json:"-"`
@@ -170,6 +176,7 @@ func (s *StdinServerConfig) UnmarshalJSON(data []byte) error {
 		"guard":           true,
 		"auth":            true,
 		"connect_timeout": true,
+		"tool_timeout":    true,
 	}
 
 	// Store additional properties (fields not in the struct)
@@ -429,6 +436,9 @@ func convertStdinServerConfig(name string, server *StdinServerConfig, customSche
 		if server.ConnectTimeout != nil {
 			serverCfg.ConnectTimeout = *server.ConnectTimeout
 		}
+		if server.ToolTimeout != nil {
+			serverCfg.ToolTimeout = *server.ToolTimeout
+		}
 		if server.Auth != nil {
 			serverCfg.Auth = &AuthConfig{
 				Type:     server.Auth.Type,

internal/config/config_test.go

@@ -1725,3 +1725,122 @@ func TestLoadFromStdin_WithEmptyTrustedBots(t *testing.T) {
 	require.Error(t, err)
 	assert.ErrorContains(t, err, "trustedBots")
 }
+
+// TestLoadFromStdin_HTTPServerWithToolTimeout verifies that tool_timeout is parsed and
+// converted correctly from a stdin JSON HTTP server configuration.
+func TestLoadFromStdin_HTTPServerWithToolTimeout(t *testing.T) {
+	jsonConfig := `{
+"mcpServers": {
+"repo-mind": {
+"type": "http",
+"url": "http://127.0.0.1:8000/mcp",
+"tool_timeout": 600
+}
+},
+"gateway": {
+"port": 3000,
+"domain": "localhost",
+"apiKey": "test-key"
+}
+}`
+
+	oldStdin := os.Stdin
+	defer func() { os.Stdin = oldStdin }()
+	r, w, err := os.Pipe()
+	require.NoError(t, err)
+	os.Stdin = r
+	go func() {
+		defer w.Close()
+		_, _ = w.Write([]byte(jsonConfig))
+	}()
+
+	cfg, err := LoadFromStdin()
+	require.NoError(t, err, "LoadFromStdin() should succeed with tool_timeout")
+
+	server, ok := cfg.Servers["repo-mind"]
+	require.True(t, ok, "Server 'repo-mind' should be present")
+	assert.Equal(t, 600, server.ToolTimeout, "Per-server tool_timeout should be 600")
+}
+
+// TestLoadFromStdin_HTTPServerToolTimeoutOverridesGlobal verifies that the per-server
+// tool_timeout in a server config takes precedence over gateway.toolTimeout.
+func TestLoadFromStdin_HTTPServerToolTimeoutOverridesGlobal(t *testing.T) {
+	jsonConfig := `{
+"mcpServers": {
+"fast-server": {
+"type": "http",
+"url": "http://127.0.0.1:8001/mcp"
+},
+"slow-server": {
+"type": "http",
+"url": "http://127.0.0.1:8002/mcp",
+"tool_timeout": 300
+}
+},
+"gateway": {
+"port": 3000,
+"domain": "localhost",
+"apiKey": "test-key",
+"toolTimeout": 60
+}
+}`
+
+	oldStdin := os.Stdin
+	defer func() { os.Stdin = oldStdin }()
+	r, w, err := os.Pipe()
+	require.NoError(t, err)
+	os.Stdin = r
+	go func() {
+		defer w.Close()
+		_, _ = w.Write([]byte(jsonConfig))
+	}()
+
+	cfg, err := LoadFromStdin()
+	require.NoError(t, err, "LoadFromStdin() should succeed")
+
+	// Global timeout
+	assert.Equal(t, 60, cfg.Gateway.ToolTimeout, "Global toolTimeout should be 60")
+
+	// fast-server: no per-server timeout, inherits global via callBackendTool
+	fastServer, ok := cfg.Servers["fast-server"]
+	require.True(t, ok)
+	assert.Equal(t, 0, fastServer.ToolTimeout, "fast-server should have no per-server tool_timeout")
+
+	// slow-server: per-server timeout 300 overrides global 60
+	slowServer, ok := cfg.Servers["slow-server"]
+	require.True(t, ok)
+	assert.Equal(t, 300, slowServer.ToolTimeout, "slow-server should have per-server tool_timeout 300")
+}
+
+// TestLoadFromStdin_HTTPServerToolTimeoutBelowMinimum verifies that a per-server
+// tool_timeout below the minimum (10) is rejected.
+func TestLoadFromStdin_HTTPServerToolTimeoutBelowMinimum(t *testing.T) {
+	jsonConfig := `{
+"mcpServers": {
+"repo-mind": {
+"type": "http",
+"url": "http://127.0.0.1:8000/mcp",
+"tool_timeout": 5
+}
+},
+"gateway": {
+"port": 3000,
+"domain": "localhost",
+"apiKey": "test-key"
+}
+}`
+
+	oldStdin := os.Stdin
+	defer func() { os.Stdin = oldStdin }()
+	r, w, err := os.Pipe()
+	require.NoError(t, err)
+	os.Stdin = r
+	go func() {
+		defer w.Close()
+		_, _ = w.Write([]byte(jsonConfig))
+	}()
+
+	_, err = LoadFromStdin()
+	require.Error(t, err, "LoadFromStdin() should fail with tool_timeout below minimum")
+	assert.ErrorContains(t, err, "tool_timeout")
+}

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

@@ -125,6 +125,21 @@
           "default": [
             "*"
           ]
+        },
+        "tool_timeout": {
+          "description": "Per-server tool invocation timeout in seconds. When set to a positive value (minimum 10), overrides the global gateway.toolTimeout for tool calls to this server only. Set to 0 or omit the field to fall back to the global gateway.toolTimeout.",
+          "oneOf": [
+            {
+              "type": "integer",
+              "const": 0,
+              "description": "0 means unset: fall back to gateway.toolTimeout."
+            },
+            {
+              "type": "integer",
+              "minimum": 10,
+              "description": "Positive timeout value in seconds (minimum 10)."
+            }
+          ]
         }
       },
       "required": [
@@ -180,6 +195,21 @@
           "type": "object",
           "description": "Guard policies for access control at the MCP gateway level. The structure of guard policies is server-specific. For GitHub MCP server, see the GitHub guard policy schema. For other servers (Jira, WorkIQ), different policy schemas will apply.",
           "additionalProperties": true
+        },
+        "tool_timeout": {
+          "description": "Per-server tool invocation timeout in seconds. When set to a positive value (minimum 10), overrides the global gateway.toolTimeout for tool calls to this server only. Set to 0 or omit the field to fall back to the global gateway.toolTimeout.",
+          "oneOf": [
+            {
+              "type": "integer",
+              "const": 0,
+              "description": "0 means unset: fall back to gateway.toolTimeout."
+            },
+            {
+              "type": "integer",
+              "minimum": 10,
+              "description": "Positive timeout value in seconds (minimum 10)."
+            }
+          ]
         }
       },
       "required": [

internal/config/validation.go

@@ -118,6 +118,15 @@ func validateStandardServerConfig(name string, server *StdinServerConfig, jsonPa
 		}
 	}
 
+	// Validate per-server tool_timeout if provided and non-zero.
+	// A value of 0 means "unset – fall back to the global gateway timeout".
+	if server.ToolTimeout != nil && *server.ToolTimeout != 0 {
+		if err := rules.TimeoutMinimum(*server.ToolTimeout, ToolTimeoutMin, "tool_timeout", jsonPath+".tool_timeout"); err != nil {
+			logValidateServerFailed(name, fmt.Sprintf("tool_timeout %d is below minimum %d", *server.ToolTimeout, ToolTimeoutMin))
+			return err
+		}
+	}
+
 	logValidateServerPassed(name)
 	return nil
 }

internal/config/validation_test.go

@@ -1082,3 +1082,101 @@ func TestValidateAuthConfig(t *testing.T) {
 		})
 	}
 }
+
+// TestValidatePerServerToolTimeout tests per-server tool_timeout validation.
+func TestValidatePerServerToolTimeout(t *testing.T) {
+	tests := []struct {
+		name      string
+		server    *StdinServerConfig
+		shouldErr bool
+		errMsg    string
+	}{
+		{
+			name: "valid tool_timeout on http server",
+			server: &StdinServerConfig{
+				Type:        "http",
+				URL:         "https://example.com/mcp",
+				ToolTimeout: intPtr(600),
+			},
+			shouldErr: false,
+		},
+		{
+			name: "valid tool_timeout at minimum (10) on http server",
+			server: &StdinServerConfig{
+				Type:        "http",
+				URL:         "https://example.com/mcp",
+				ToolTimeout: intPtr(10),
+			},
+			shouldErr: false,
+		},
+		{
+			name: "tool_timeout large value (3600 = 1 hour) on http server",
+			server: &StdinServerConfig{
+				Type:        "http",
+				URL:         "https://example.com/mcp",
+				ToolTimeout: intPtr(3600),
+			},
+			shouldErr: false,
+		},
+		{
+			name: "tool_timeout below minimum (9) on http server",
+			server: &StdinServerConfig{
+				Type:        "http",
+				URL:         "https://example.com/mcp",
+				ToolTimeout: intPtr(9),
+			},
+			shouldErr: true,
+			errMsg:    "tool_timeout",
+		},
+		{
+			name: "tool_timeout of 0 on http server (treated as unset, falls back to global)",
+			server: &StdinServerConfig{
+				Type:        "http",
+				URL:         "https://example.com/mcp",
+				ToolTimeout: intPtr(0),
+			},
+			shouldErr: false,
+		},
+		{
+			name: "valid tool_timeout on stdio server",
+			server: &StdinServerConfig{
+				Type:        "stdio",
+				Container:   "ghcr.io/owner/image:latest",
+				ToolTimeout: intPtr(120),
+			},
+			shouldErr: false,
+		},
+		{
+			name: "tool_timeout below minimum on stdio server",
+			server: &StdinServerConfig{
+				Type:        "stdio",
+				Container:   "ghcr.io/owner/image:latest",
+				ToolTimeout: intPtr(5),
+			},
+			shouldErr: true,
+			errMsg:    "tool_timeout",
+		},
+		{
+			name: "no tool_timeout set (omitted)",
+			server: &StdinServerConfig{
+				Type: "http",
+				URL:  "https://example.com/mcp",
+			},
+			shouldErr: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			err := validateStandardServerConfig("test-server", tt.server, "mcpServers.test-server")
+			if tt.shouldErr {
+				require.Error(t, err)
+				if tt.errMsg != "" {
+					assert.ErrorContains(t, err, tt.errMsg)
+				}
+			} else {
+				assert.NoError(t, err)
+			}
+		})
+	}
+}