feat: make HTTP keepalive interval configurable

Add keepalive_interval field to GatewayConfig (seconds). Default 1500
(25 min) preserves current behavior. Set to -1 to disable keepalive
pings entirely when higher-level timeouts manage session lifecycle.

Thread the configurable duration through NewHTTPConnection → trySDKTransport
→ newMCPClient instead of hardcoding DefaultHTTPKeepaliveInterval.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: lpcox

internal/config/config_core.go

@@ -29,16 +29,18 @@ import (
 	"io"
 	"log"
 	"os"
+	"time"
 
 	"github.com/BurntSushi/toml"
 	"github.com/github/gh-aw-mcpg/internal/logger"
 )
 
 // Core constants for configuration defaults
 const (
-	DefaultPort           = 3000
-	DefaultStartupTimeout = 60  // seconds
-	DefaultToolTimeout    = 120 // seconds
+	DefaultPort              = 3000
+	DefaultStartupTimeout    = 60   // seconds
+	DefaultToolTimeout       = 120  // seconds
+	DefaultKeepaliveInterval = 1500 // seconds (25 minutes) — keeps HTTP backend sessions alive
 )
 
 // Config represents the internal gateway configuration.
@@ -87,6 +89,13 @@ type GatewayConfig struct {
 	// ToolTimeout is the maximum time (seconds) to wait for tool execution
 	ToolTimeout int `toml:"tool_timeout" json:"tool_timeout,omitempty"`
 
+	// KeepaliveInterval is the interval (seconds) for sending keepalive pings to HTTP
+	// backends. This prevents long-running sessions from being expired by the remote
+	// server's idle timeout (typically 30 minutes). Set to -1 to disable keepalive
+	// pings entirely (useful when higher-level timeouts manage session lifecycle).
+	// Default: 1500 (25 minutes)
+	KeepaliveInterval int `toml:"keepalive_interval" json:"keepalive_interval,omitempty"`
+
 	// PayloadDir is the directory for storing large payloads
 	PayloadDir string `toml:"payload_dir" json:"payload_dir,omitempty"`
 
@@ -110,6 +119,15 @@ type GatewayConfig struct {
 	TrustedBots []string `toml:"trusted_bots" json:"trusted_bots,omitempty"`
 }
 
+// HTTPKeepaliveInterval returns the keepalive interval as a time.Duration.
+// A negative KeepaliveInterval disables keepalive (returns 0).
+func (g *GatewayConfig) HTTPKeepaliveInterval() time.Duration {
+	if g.KeepaliveInterval < 0 {
+		return 0
+	}
+	return time.Duration(g.KeepaliveInterval) * time.Second
+}
+
 // GetAPIKey returns the gateway API key, handling a nil Gateway safely.
 func (c *Config) GetAPIKey() string {
 	if c.Gateway == nil {
@@ -196,6 +214,9 @@ func applyGatewayDefaults(cfg *GatewayConfig) {
 	if cfg.ToolTimeout == 0 {
 		cfg.ToolTimeout = DefaultToolTimeout
 	}
+	if cfg.KeepaliveInterval == 0 {
+		cfg.KeepaliveInterval = DefaultKeepaliveInterval
+	}
 }
 
 // EnsureGatewayDefaults guarantees that cfg.Gateway is non-nil and that all

internal/launcher/launcher.go

@@ -139,7 +139,7 @@ func GetOrLaunch(l *Launcher, serverID string) (*mcp.Connection, error) {
 			}
 
 			// Create an HTTP connection
-			conn, err := mcp.NewHTTPConnection(l.ctx, serverID, serverCfg.URL, serverCfg.Headers, oidcProvider, oidcAudience)
+			conn, err := mcp.NewHTTPConnection(l.ctx, serverID, serverCfg.URL, serverCfg.Headers, oidcProvider, oidcAudience, l.config.Gateway.HTTPKeepaliveInterval())
 			if err != nil {
 				logger.LogErrorWithServer(serverID, "backend", "Failed to create HTTP connection: %s, error=%v", serverID, err)
 				log.Printf("[LAUNCHER] ❌ FAILED to create HTTP connection for '%s'", serverID)

internal/mcp/connection.go

@@ -197,7 +197,7 @@ func NewConnection(ctx context.Context, serverID, command string, args []string,
 // Authorization header from the headers map.
 //
 // This ensures compatibility with all types of HTTP MCP servers.
-func NewHTTPConnection(ctx context.Context, serverID, url string, headers map[string]string, oidcProvider *oidc.Provider, oidcAudience string) (*Connection, error) {
+func NewHTTPConnection(ctx context.Context, serverID, url string, headers map[string]string, oidcProvider *oidc.Provider, oidcAudience string, keepAlive time.Duration) (*Connection, error) {
 	logger.LogInfo("backend", "Creating HTTP MCP connection with transport fallback, url=%s", url)
 	ctx, cancel := context.WithCancel(ctx)
 
@@ -235,7 +235,7 @@ func NewHTTPConnection(ctx context.Context, serverID, url string, headers map[st
 
 	// Try 1: Streamable HTTP (2025-03-26 spec)
 	logConn.Printf("Attempting streamable HTTP transport for %s", url)
-	conn, err := tryStreamableHTTPTransport(ctx, cancel, serverID, url, headers, headerClient)
+	conn, err := tryStreamableHTTPTransport(ctx, cancel, serverID, url, headers, headerClient, keepAlive)
 	if err == nil {
 		logger.LogInfo("backend", "Successfully connected using streamable HTTP transport, url=%s", url)
 		log.Printf("Configured HTTP MCP server with streamable transport: %s", url)
@@ -245,7 +245,7 @@ func NewHTTPConnection(ctx context.Context, serverID, url string, headers map[st
 
 	// Try 2: SSE (2024-11-05 spec)
 	logConn.Printf("Attempting SSE transport for %s", url)
-	conn, err = trySSETransport(ctx, cancel, serverID, url, headers, headerClient)
+	conn, err = trySSETransport(ctx, cancel, serverID, url, headers, headerClient, keepAlive)
 	if err == nil {
 		logger.LogWarn("backend", "⚠️  MCP over SSE has been deprecated. Connected using SSE transport for url=%s. Please migrate to streamable HTTP transport (2025-03-26 spec).", url)
 		log.Printf("⚠️  WARNING: MCP over SSE (2024-11-05 spec) has been DEPRECATED")

internal/mcp/connection_arguments_test.go

@@ -159,7 +159,7 @@ func TestCallTool_ArgumentsPassed(t *testing.T) {
 			// Create connection
 			conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, map[string]string{
 				"Authorization": "test-token",
-			}, nil, "")
+			}, nil, "", 0)
 			require.NoError(t, err, "Failed to create HTTP connection")
 			defer conn.Close()
 
@@ -224,7 +224,7 @@ func TestCallTool_MissingArguments(t *testing.T) {
 
 	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, map[string]string{
 		"Authorization": "test-token",
-	}, nil, "")
+	}, nil, "", 0)
 	require.NoError(t, err)
 	defer conn.Close()
 

internal/mcp/connection_stderr_test.go

@@ -37,7 +37,7 @@ func TestConnection_SendRequest(t *testing.T) {
 
 	conn, err := NewHTTPConnection(context.Background(), "test-server", srv.URL, map[string]string{
 		"Authorization": "test-token",
-	}, nil, "")
+	}, nil, "", 0)
 	require.NoError(t, err)
 	defer conn.Close()
 

internal/mcp/connection_test.go

@@ -42,7 +42,7 @@ func TestHTTPRequest_SessionIDHeader(t *testing.T) {
 	// Create an HTTP connection
 	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, map[string]string{
 		"Authorization": "test-auth-token",
-	}, nil, "")
+	}, nil, "", 0)
 	require.NoError(t, err, "Failed to create HTTP connection")
 
 	// Create a context with session ID
@@ -79,7 +79,7 @@ func TestHTTPRequest_NoSessionID(t *testing.T) {
 	// Create an HTTP connection
 	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, map[string]string{
 		"Authorization": "test-auth-token",
-	}, nil, "")
+	}, nil, "", 0)
 	require.NoError(t, err, "Failed to create HTTP connection")
 
 	// Send a request without session ID in context
@@ -117,7 +117,7 @@ func TestHTTPRequest_ConfiguredHeaders(t *testing.T) {
 	authToken := "configured-auth-token"
 	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, map[string]string{
 		"Authorization": authToken,
-	}, nil, "")
+	}, nil, "", 0)
 	require.NoError(t, err, "Failed to create HTTP connection")
 
 	// Create a context with session ID
@@ -376,7 +376,7 @@ func TestHTTPRequest_ErrorResponses(t *testing.T) {
 			// Create connection with custom headers to use plain JSON transport
 			conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, map[string]string{
 				"Authorization": "test-token",
-			}, nil, "")
+			}, nil, "", 0)
 			if err != nil && tt.expectError {
 				// Error during initialization is expected for some error conditions
 				if tt.errorSubstring != "" && !containsSubstring(err.Error(), tt.errorSubstring) {
@@ -428,7 +428,7 @@ func TestConnection_IsHTTP(t *testing.T) {
 		"X-Custom":      "custom-value",
 	}
 
-	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, headers, nil, "")
+	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, headers, nil, "", 0)
 	require.NoError(t, err, "Failed to create HTTP connection")
 	defer conn.Close()
 
@@ -475,7 +475,7 @@ func TestHTTPConnection_InvalidURL(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			_, err := NewHTTPConnection(context.Background(), "test-server", tt.url, tt.headers, nil, "")
+			_, err := NewHTTPConnection(context.Background(), "test-server", tt.url, tt.headers, nil, "", 0)
 
 			if tt.expectError {
 				if err == nil {

internal/mcp/http_connection_test.go

@@ -54,7 +54,7 @@ func TestNewHTTPConnection_WithCustomHeaders(t *testing.T) {
 		"X-Custom-Header": "custom-value",
 	}
 
-	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, customHeaders, nil, "")
+	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, customHeaders, nil, "", 0)
 	require.NoError(err, "Failed to create HTTP connection with custom headers")
 	require.NotNil(conn, "Connection should not be nil")
 	defer conn.Close()
@@ -112,7 +112,7 @@ func TestNewHTTPConnection_WithoutHeaders_FallbackSequence(t *testing.T) {
 	defer testServer.Close()
 
 	// Create connection without custom headers - streamable transport should succeed first
-	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, nil, nil, "")
+	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, nil, nil, "", 0)
 	require.NoError(err, "Connection should succeed")
 	require.NotNil(conn)
 	defer conn.Close()
@@ -134,7 +134,7 @@ func TestNewHTTPConnection_AllTransportsFail(t *testing.T) {
 	defer testServer.Close()
 
 	// Try to create connection without custom headers (will try all transports)
-	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, nil, nil, "")
+	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, nil, nil, "", 0)
 
 	// Should fail after trying all transports
 	require.Error(err, "Should fail when all transports fail")
@@ -161,7 +161,7 @@ func TestNewHTTPConnection_ContextCancellation(t *testing.T) {
 	cancel()
 
 	// Try to create connection with cancelled context
-	conn, err := NewHTTPConnection(ctx, "test-server", testServer.URL, map[string]string{"Auth": "token"}, nil, "")
+	conn, err := NewHTTPConnection(ctx, "test-server", testServer.URL, map[string]string{"Auth": "token"}, nil, "", 0)
 
 	// Should fail due to context cancellation
 	require.Error(err, "Should fail with cancelled context")
@@ -198,7 +198,7 @@ func TestNewHTTPConnection_InvalidURL(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
-			conn, err := NewHTTPConnection(context.Background(), "test-server", tt.url, tt.headers, nil, "")
+			conn, err := NewHTTPConnection(context.Background(), "test-server", tt.url, tt.headers, nil, "", 0)
 
 			if tt.expectError {
 				assert.Error(t, err, "Expected error for invalid URL")
@@ -273,7 +273,7 @@ func TestTryPlainJSONTransport_InitializeFailure(t *testing.T) {
 			// Try to create connection
 			conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, map[string]string{
 				"Authorization": "test-token",
-			}, nil, "")
+			}, nil, "", 0)
 
 			// Should fail with appropriate error
 			require.Error(t, err, "Should fail on initialization error")
@@ -306,7 +306,7 @@ data: {"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","serverIn
 	// Create connection
 	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, map[string]string{
 		"Authorization": "test-token",
-	}, nil, "")
+	}, nil, "", 0)
 
 	require.NoError(err, "Should successfully parse SSE-formatted initialize response")
 	require.NotNil(conn)
@@ -347,7 +347,7 @@ func TestHTTPConnection_NoSessionIDInResponse(t *testing.T) {
 	// Create connection
 	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, map[string]string{
 		"Authorization": "test-token",
-	}, nil, "")
+	}, nil, "", 0)
 
 	require.NoError(err, "Should succeed even without session ID from server")
 	require.NotNil(conn)
@@ -393,7 +393,7 @@ func TestNewHTTPConnection_HeadersPropagation(t *testing.T) {
 		"X-Custom-2":    "value2",
 	}
 
-	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, customHeaders, nil, "")
+	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, customHeaders, nil, "", 0)
 	require.NoError(err)
 	require.NotNil(conn)
 	defer conn.Close()
@@ -440,7 +440,7 @@ func TestNewHTTPConnection_EmptyHeaders(t *testing.T) {
 	defer testServer.Close()
 
 	// Create connection with empty headers - should try SDK transports first
-	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, map[string]string{}, nil, "")
+	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, map[string]string{}, nil, "", 0)
 	require.NoError(err, "Should succeed with empty headers")
 	require.NotNil(conn)
 	defer conn.Close()
@@ -473,7 +473,7 @@ func TestNewHTTPConnection_NilHeaders(t *testing.T) {
 	defer testServer.Close()
 
 	// Create connection with nil headers (should try SDK transports first)
-	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, nil, nil, "")
+	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, nil, nil, "", 0)
 	require.NoError(err, "Should succeed with nil headers")
 	require.NotNil(conn)
 	defer conn.Close()
@@ -509,7 +509,7 @@ func TestNewHTTPConnection_HTTPClientTimeout(t *testing.T) {
 	// Create connection
 	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, map[string]string{
 		"Authorization": "test",
-	}, nil, "")
+	}, nil, "", 0)
 
 	// Should succeed (delay is within timeout)
 	require.NoError(err, "Should succeed within timeout")
@@ -530,7 +530,7 @@ func TestNewHTTPConnection_ConnectionRefused(t *testing.T) {
 	// Try to create connection
 	conn, err := NewHTTPConnection(context.Background(), "test-server", unreachableURL, map[string]string{
 		"Authorization": "test",
-	}, nil, "")
+	}, nil, "", 0)
 
 	// Should fail with connection error
 	require.Error(err, "Should fail with connection refused")
@@ -563,7 +563,7 @@ func TestNewHTTPConnection_GettersAfterCreation(t *testing.T) {
 		"X-Custom":      "custom-value",
 	}
 
-	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, customHeaders, nil, "")
+	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, customHeaders, nil, "", 0)
 	require.NoError(err)
 	require.NotNil(conn)
 	defer conn.Close()

internal/mcp/http_error_propagation_test.go

@@ -119,7 +119,7 @@ func TestHTTPErrorPropagation_Non200Status(t *testing.T) {
 			// Create connection with custom headers to use plain JSON transport
 			conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, map[string]string{
 				"Authorization": "test-token",
-			}, nil, "")
+			}, nil, "", 0)
 			require.NoError(t, err, "Failed to create connection")
 			defer conn.Close()
 
@@ -192,7 +192,7 @@ func TestHTTPErrorPropagation_JSONRPCError(t *testing.T) {
 
 	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, map[string]string{
 		"Authorization": "test-token",
-	}, nil, "")
+	}, nil, "", 0)
 	require.NoError(t, err, "Failed to create connection")
 	defer conn.Close()
 
@@ -275,7 +275,7 @@ func TestHTTPErrorPropagation_MixedContent(t *testing.T) {
 
 			conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, map[string]string{
 				"Authorization": "test-token",
-			}, nil, "")
+			}, nil, "", 0)
 			require.NoError(t, err, "Failed to create connection")
 			defer conn.Close()
 
@@ -344,7 +344,7 @@ func TestHTTPErrorPropagation_PreservesDetails(t *testing.T) {
 
 	conn, err := NewHTTPConnection(context.Background(), "test-server", testServer.URL, map[string]string{
 		"Authorization": "test-token",
-	}, nil, "")
+	}, nil, "", 0)
 	require.NoError(t, err, "Failed to create connection")
 	defer conn.Close()
 

internal/mcp/http_transport.go

@@ -403,11 +403,12 @@ func trySDKTransport(
 	transportType HTTPTransportType,
 	transportName string,
 	createTransport transportConnector,
+	keepAlive time.Duration,
 ) (*Connection, error) {
-	// Create MCP client with logger and keepalive enabled.
-	// DefaultHTTPKeepaliveInterval sends periodic pings to prevent session expiry
-	// on backends (e.g. safeoutputs) that have a 30-minute idle timeout.
-	client := newMCPClient(logConn, DefaultHTTPKeepaliveInterval)
+	// Create MCP client with logger and optional keepalive.
+	// When keepAlive > 0, periodic pings prevent session expiry on backends
+	// (e.g. safeoutputs) that have an idle timeout.
+	client := newMCPClient(logConn, keepAlive)
 
 	// Create transport using the provided connector
 	transport := createTransport(url, httpClient)
@@ -422,15 +423,15 @@ func trySDKTransport(
 		return nil, fmt.Errorf("%s transport connect failed: %w", transportName, err)
 	}
 
-	conn := newHTTPConnection(ctx, cancel, client, session, url, headers, httpClient, transportType, serverID, DefaultHTTPKeepaliveInterval)
+	conn := newHTTPConnection(ctx, cancel, client, session, url, headers, httpClient, transportType, serverID, keepAlive)
 
 	logger.LogInfo("backend", "%s transport connected successfully", transportName)
 	logConn.Printf("Connected with %s transport", transportName)
 	return conn, nil
 }
 
 // tryStreamableHTTPTransport attempts to connect using the streamable HTTP transport (2025-03-26 spec)
-func tryStreamableHTTPTransport(ctx context.Context, cancel context.CancelFunc, serverID, url string, headers map[string]string, httpClient *http.Client) (*Connection, error) {
+func tryStreamableHTTPTransport(ctx context.Context, cancel context.CancelFunc, serverID, url string, headers map[string]string, httpClient *http.Client, keepAlive time.Duration) (*Connection, error) {
 	return trySDKTransport(
 		ctx, cancel, serverID, url, headers, httpClient,
 		HTTPTransportStreamable,
@@ -442,11 +443,12 @@ func tryStreamableHTTPTransport(ctx context.Context, cancel context.CancelFunc,
 				MaxRetries: 0, // Don't retry on failure - we'll try other transports
 			}
 		},
+		keepAlive,
 	)
 }
 
 // trySSETransport attempts to connect using the SSE transport (2024-11-05 spec)
-func trySSETransport(ctx context.Context, cancel context.CancelFunc, serverID, url string, headers map[string]string, httpClient *http.Client) (*Connection, error) {
+func trySSETransport(ctx context.Context, cancel context.CancelFunc, serverID, url string, headers map[string]string, httpClient *http.Client, keepAlive time.Duration) (*Connection, error) {
 	return trySDKTransport(
 		ctx, cancel, serverID, url, headers, httpClient,
 		HTTPTransportSSE,
@@ -457,6 +459,7 @@ func trySSETransport(ctx context.Context, cancel context.CancelFunc, serverID, u
 				HTTPClient: httpClient,
 			}
 		},
+		keepAlive,
 	)
 }