feat(config): ping liveness + configurable discovery/health-check intervals

Replaces the heavyweight tools/list liveness probe with the MCP-standard
lightweight `ping`, and makes both background cadences configurable globally
and per-server.

Ping liveness (US1, FR-001/002):
- Add Client.Ping wrapper to internal/upstream/core/client.go (mcp-go Ping).
- Rewrite managed performHealthCheck to probe via a narrow livenessProber
  interface (the coreClient in prod; a fake in tests) instead of ListTools,
  preserving the existing connection-error classification and flap resistance.
  An idle proxy no longer emits recurring tools/list to upstreams (#608).

Configurable intervals (US2/US3, FR-004..009):
- *Duration tri-state (nil=inherit, "0s"=disabled, positive=interval) on both
  Config (global) and ServerConfig (per-server): health_check_interval (30s
  default) and tool_discovery_interval (5m default). Defaults live only in the
  resolvers so unset keys behave exactly as before (SC-005).
- ResolveHealthCheckInterval / ResolveToolDiscoveryInterval: per-server ->
  global -> default; resolved <=0 disables the loop.
- Validate() enforces health-check {0} U [5s,1h] and tool-discovery {0} U
  [30s,24h] for every global and per-server pointer, with clear messages.
- backgroundHealthCheck and backgroundToolIndexing now use resettable timers
  that re-resolve each cycle (hot-reload aware) and skip when disabled.
- Per-server overrides round-trip through UpstreamRecord (storage canary).

UI + docs:
- Web settings "Tool discovery & health checks" accordion (fields.ts) and the
  mirrored macOS ConfigSection (SettingsCatalog.swift), duration controls with
  0s=disabled help text.
- docs/configuration.md documents both keys, defaults, ranges, 0s semantics,
  and the per-server override; swagger regenerated.

Related #608

Co-Authored-By: Paperclip <noreply@paperclip.ing>

Author: Dumbris

docs/configuration.md

@@ -96,6 +96,54 @@ MCPProxy looks for configuration in these locations (in order):
 | `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 |
 
+### Discovery & Health Checks
+
+mcpproxy keeps each upstream connection alive and its tool index fresh with two
+background loops. Both intervals are tunable globally and per server, so you can
+quiet a chatty upstream that returns a large tool catalog.
+
+```json
+{
+  "health_check_interval": "30s",
+  "tool_discovery_interval": "5m"
+}
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `health_check_interval` | duration | `"30s"` | How often to probe each connected server for liveness with a lightweight MCP `ping`. `"0s"` disables the periodic probe. Range: `5s`–`1h`. |
+| `tool_discovery_interval` | duration | `"5m"` | How often to re-list every server's tools to rebuild the search index. `"0s"` disables the periodic sweep. Range: `30s`–`24h`. |
+
+**Liveness uses `ping`, not `tools/list`.** The health-check loop issues the
+MCP-standard `ping` request rather than re-listing every tool, so an idle proxy
+no longer generates large recurring `tools/list` traffic to upstream servers
+(GitHub [#608](https://github.com/smart-mcp-proxy/mcpproxy-go/issues/608)). Tool
+changes are still picked up reactively whenever a server pushes
+`notifications/tools/list_changed`.
+
+**Disabling a loop (`"0s"`).** Set either key to `"0s"` to turn the
+corresponding loop off:
+
+- `health_check_interval: "0s"` — no periodic liveness probe. A dead transport
+  is then detected lazily, on the next real tool call or discovery sweep, rather
+  than proactively.
+- `tool_discovery_interval: "0s"` — no periodic index rebuild. Tools are still
+  discovered at connect time and whenever a server pushes
+  `notifications/tools/list_changed`. **Trade-off:** a server that does *not*
+  support `list_changed` will not have new/removed tools reflected until it
+  reconnects or you trigger a manual refresh.
+
+An unset key behaves exactly as before this feature (the built-in default), and
+a change to either interval takes effect on the next cycle without restarting
+the proxy.
+
+> **Per-server override.** Both keys can also be set on an individual server
+> entry under `mcpServers[]` (see [Server Fields](#server-fields)) to override
+> the global value for just that server; the per-server value wins, and `"0s"`
+> disables the loop for that server only. A dedicated per-server form control in
+> the Web UI / macOS app is planned; for now set per-server overrides via the
+> Raw JSON editor or the REST API.
+
 ### Debug & Development
 
 ```json
@@ -150,6 +198,8 @@ MCPProxy looks for configuration in these locations (in order):
 | `working_dir` | string | No | Working directory for stdio servers, or for the locally-launched child of an HTTP/SSE server (default: current directory) |
 | `env` | object | No | Environment variables for stdio servers, or for the locally-launched child of an HTTP/SSE server |
 | `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). Accepted and persisted for forward-compatibility; the periodic index rebuild currently runs on the global cadence. Range: `30s`–`24h`. Omit to inherit the global value. |
 | `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`) |

frontend/src/views/settings/fields.ts

@@ -331,6 +331,15 @@ export const ADVANCED_ACCORDIONS: SettingsAccordion[] = [
       { key: 'activity_cleanup_interval_min', label: 'Cleanup runs every (minutes)', control: 'number', min: 1 },
     ],
   },
+  {
+    id: 'discovery',
+    title: 'Tool discovery & health checks',
+    description: 'How often mcpproxy probes upstream servers for liveness and re-discovers their tools. Lower these to reduce background traffic to chatty servers.',
+    fields: [
+      { key: 'health_check_interval', label: 'Health-check interval', help: 'How often to send a lightweight liveness ping to each connected server. "0s" disables the periodic probe (a dead server is then detected lazily on the next tool call). Range: 5s–1h. Default 30s.', control: 'duration', placeholder: '30s', optional: true },
+      { key: 'tool_discovery_interval', label: 'Tool-discovery interval', help: 'How often to re-list every server’s tools to rebuild the search index. "0s" disables the periodic sweep — tool changes are then picked up only at connect time and via tools/list_changed push notifications. Range: 30s–24h. Default 5m.', control: 'duration', placeholder: '5m', optional: true },
+    ],
+  },
   {
     id: 'logging',
     title: 'Logging',

internal/config/config.go

@@ -52,6 +52,51 @@ func (d Duration) Duration() time.Duration {
 	return time.Duration(d)
 }
 
+// Built-in defaults for the discovery/health-check loops (spec 074). They live
+// here (not in DefaultConfig) so an unset key resolves to the historical
+// behaviour and existing configs are unchanged (SC-005).
+const (
+	defaultHealthCheckInterval   = 30 * time.Second
+	defaultToolDiscoveryInterval = 5 * time.Minute
+)
+
+// resolveInterval applies the per-server → global → default precedence for an
+// optional *Duration. A non-nil pointer wins at each level, including a pointer
+// to 0 ("disabled"). Returns the resolved duration; a value <= 0 means the
+// caller should disable the corresponding loop.
+func resolveInterval(server, global *Duration, def time.Duration) time.Duration {
+	if server != nil {
+		return server.Duration()
+	}
+	if global != nil {
+		return global.Duration()
+	}
+	return def
+}
+
+// ResolveHealthCheckInterval resolves the effective health-check probe interval
+// for a server: per-server override → global → 30s default. A resolved value
+// <= 0 disables the periodic probe for that server (spec 074, FR-006).
+func (c *Config) ResolveHealthCheckInterval(sc *ServerConfig) time.Duration {
+	var server *Duration
+	if sc != nil {
+		server = sc.HealthCheckInterval
+	}
+	return resolveInterval(server, c.HealthCheckInterval, defaultHealthCheckInterval)
+}
+
+// ResolveToolDiscoveryInterval resolves the effective tool-discovery sweep
+// interval: per-server override → global → 5m default. A resolved value <= 0
+// disables the periodic sweep (connect-time + reactive list_changed discovery
+// still run). The periodic index rebuild is global; pass nil for the sweep.
+func (c *Config) ResolveToolDiscoveryInterval(sc *ServerConfig) time.Duration {
+	var server *Duration
+	if sc != nil {
+		server = sc.ToolDiscoveryInterval
+	}
+	return resolveInterval(server, c.ToolDiscoveryInterval, defaultToolDiscoveryInterval)
+}
+
 // Config represents the main configuration structure
 type Config struct {
 	Listen       string `json:"listen" mapstructure:"listen"`
@@ -69,6 +114,15 @@ type Config struct {
 	CallToolTimeout    Duration `json:"call_tool_timeout" mapstructure:"call-tool-timeout" swaggertype:"string"`
 	MaxResultSizeChars int      `json:"max_result_size_chars,omitempty" mapstructure:"max-result-size-chars"` // Advertised on every tool as `_meta.anthropic/maxResultSizeChars`; raises Claude Code's inline-response ceiling from 50k to up to 500k chars. Set to 0 to disable.
 
+	// Discovery & health-check cadence (spec 074, #608). Both are *Duration
+	// tri-state pointers: nil = inherit the built-in default; a pointer to 0s =
+	// the loop is disabled; a positive value = that interval. Defaults live only
+	// in the resolvers (ResolveHealthCheckInterval / ResolveToolDiscoveryInterval)
+	// so an unset key behaves exactly as before this feature (SC-005). Validated
+	// in Validate(): health-check ∈ {0} ∪ [5s,1h]; tool-discovery ∈ {0} ∪ [30s,24h].
+	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"`
+
 	// Environment configuration for secure variable filtering
 	Environment *secureenv.EnvConfig `json:"environment,omitempty" mapstructure:"environment"`
 
@@ -257,8 +311,19 @@ type ServerConfig struct {
 	// mcpproxy starts the process AND connects via network. Stdio servers ignore
 	// this field. Zero or unset → 30s default.
 	LauncherWaitTimeout Duration `json:"launcher_wait_timeout,omitempty" mapstructure:"launcher_wait_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
+
+	// Per-server discovery & health-check overrides (spec 074). Same *Duration
+	// tri-state as the global keys: nil = inherit the global value (or default),
+	// pointer to 0s = disabled for this server, positive = that interval.
+	// HealthCheckInterval is fully wired into the per-server health loop;
+	// ToolDiscoveryInterval is accepted/validated and round-trips for
+	// forward-compat, but the periodic index sweep is governed by the global
+	// cadence in this iteration (see spec 074 plan §C).
+	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"`
+
+	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
 
 	// SourceRegistryID records which registry this server was added from (empty
 	// for manually-configured servers). MCP-866: surfaced in the approval /
@@ -1257,6 +1322,14 @@ func (c *Config) ValidateDetailed() []ValidationError {
 		})
 	}
 
+	// Validate global discovery/health-check intervals (spec 074, FR-008).
+	if e := validateIntervalBound("health_check_interval", c.HealthCheckInterval, 5*time.Second, time.Hour); e != nil {
+		errors = append(errors, *e)
+	}
+	if e := validateIntervalBound("tool_discovery_interval", c.ToolDiscoveryInterval, 30*time.Second, 24*time.Hour); e != nil {
+		errors = append(errors, *e)
+	}
+
 	// Validate code execution configuration (0 means use default)
 	if c.CodeExecutionTimeoutMs != 0 && (c.CodeExecutionTimeoutMs < 1 || c.CodeExecutionTimeoutMs > 600000) {
 		errors = append(errors, ValidationError{
@@ -1365,6 +1438,14 @@ func (c *Config) ValidateDetailed() []ValidationError {
 		// Spec 074: per-upstream auth_broker validation + default application.
 		// No-op in the personal edition (stub); enforced in the server edition.
 		errors = append(errors, validateServerAuthBroker(server, fieldPrefix)...)
+
+		// Spec 074: per-server discovery/health-check interval overrides.
+		if e := validateIntervalBound(fieldPrefix+".health_check_interval", server.HealthCheckInterval, 5*time.Second, time.Hour); e != nil {
+			errors = append(errors, *e)
+		}
+		if e := validateIntervalBound(fieldPrefix+".tool_discovery_interval", server.ToolDiscoveryInterval, 30*time.Second, 24*time.Hour); e != nil {
+			errors = append(errors, *e)
+		}
 	}
 
 	// Validate DataDir exists (if specified and not empty).
@@ -1405,6 +1486,27 @@ func (c *Config) ValidateDetailed() []ValidationError {
 	return errors
 }
 
+// validateIntervalBound enforces the tri-state interval contract (spec 074,
+// FR-008): nil is fine (inherit), 0s is fine (disabled), and any other value
+// must fall within [min, max]. Returns nil when valid, or a ValidationError
+// with a human-readable, actionable message.
+func validateIntervalBound(field string, d *Duration, minVal, maxVal time.Duration) *ValidationError {
+	if d == nil {
+		return nil
+	}
+	v := d.Duration()
+	if v == 0 {
+		return nil // explicit "disabled"
+	}
+	if v < minVal || v > maxVal {
+		return &ValidationError{
+			Field:   field,
+			Message: fmt.Sprintf("must be 0s (disabled) or between %s and %s, got %s", minVal, maxVal, v),
+		}
+	}
+	return nil
+}
+
 // isValidListenAddr checks if the listen address format is valid
 func isValidListenAddr(addr string) bool {
 	// Allow :port format

internal/config/discovery_intervals_test.go

@@ -0,0 +1,135 @@
+package config
+
+import (
+	"testing"
+	"time"
+)
+
+func durPtr(d time.Duration) *Duration {
+	v := Duration(d)
+	return &v
+}
+
+// TestResolveHealthCheckInterval covers the per-server → global → default
+// precedence and the pointer-to-zero "disabled" semantics (spec 074, FR-006/FR-007).
+func TestResolveHealthCheckInterval(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(45 * time.Second), nil, 45 * time.Second},
+		{"server override wins", durPtr(45 * time.Second), durPtr(10 * time.Second), 10 * time.Second},
+		{"server override wins over default when global unset", nil, durPtr(15 * time.Second), 15 * time.Second},
+		{"global disabled (0s)", durPtr(0), nil, 0},
+		{"server disabled (0s) wins over global interval", durPtr(45 * time.Second), durPtr(0), 0},
+		{"server interval wins over global disabled", durPtr(0), durPtr(20 * time.Second), 20 * time.Second},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			c := &Config{HealthCheckInterval: tc.global}
+			sc := &ServerConfig{HealthCheckInterval: tc.server}
+			got := c.ResolveHealthCheckInterval(sc)
+			if got != tc.want {
+				t.Errorf("ResolveHealthCheckInterval = %v, want %v", got, tc.want)
+			}
+		})
+	}
+
+	// A nil server config must still resolve via global → default.
+	c := &Config{HealthCheckInterval: durPtr(45 * time.Second)}
+	if got := c.ResolveHealthCheckInterval(nil); got != 45*time.Second {
+		t.Errorf("nil server: got %v, want 45s", got)
+	}
+}
+
+// TestResolveToolDiscoveryInterval mirrors the health-check resolver with the
+// 5m default.
+func TestResolveToolDiscoveryInterval(t *testing.T) {
+	cases := []struct {
+		name   string
+		global *Duration
+		server *Duration
+		want   time.Duration
+	}{
+		{"both unset → default", nil, nil, 5 * time.Minute},
+		{"global set", durPtr(10 * time.Minute), nil, 10 * time.Minute},
+		{"server override wins", durPtr(10 * time.Minute), durPtr(2 * time.Minute), 2 * time.Minute},
+		{"global disabled", durPtr(0), nil, 0},
+		{"server disabled wins", durPtr(10 * time.Minute), durPtr(0), 0},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			c := &Config{ToolDiscoveryInterval: tc.global}
+			sc := &ServerConfig{ToolDiscoveryInterval: tc.server}
+			got := c.ResolveToolDiscoveryInterval(sc)
+			if got != tc.want {
+				t.Errorf("ResolveToolDiscoveryInterval = %v, want %v", got, tc.want)
+			}
+		})
+	}
+}
+
+// TestValidateDiscoveryIntervalBounds covers FR-008: 0s accepted (disabled),
+// in-range accepted, out-of-range rejected — for both the global and per-server
+// pointers, across both keys.
+func TestValidateDiscoveryIntervalBounds(t *testing.T) {
+	cases := []struct {
+		name      string
+		mutate    func(*Config)
+		wantError bool
+	}{
+		// Health-check: 0s or [5s, 1h]
+		{"health 0s accepted (disabled)", func(c *Config) { c.HealthCheckInterval = durPtr(0) }, false},
+		{"health 5s accepted (min)", func(c *Config) { c.HealthCheckInterval = durPtr(5 * time.Second) }, false},
+		{"health 1h accepted (max)", func(c *Config) { c.HealthCheckInterval = durPtr(time.Hour) }, false},
+		{"health 2s rejected (below min)", func(c *Config) { c.HealthCheckInterval = durPtr(2 * time.Second) }, true},
+		{"health 2h rejected (above max)", func(c *Config) { c.HealthCheckInterval = durPtr(2 * time.Hour) }, true},
+		{"health negative rejected", func(c *Config) { c.HealthCheckInterval = durPtr(-1 * time.Second) }, true},
+		// Tool-discovery: 0s or [30s, 24h]
+		{"discovery 0s accepted (disabled)", func(c *Config) { c.ToolDiscoveryInterval = durPtr(0) }, false},
+		{"discovery 30s accepted (min)", func(c *Config) { c.ToolDiscoveryInterval = durPtr(30 * time.Second) }, false},
+		{"discovery 24h accepted (max)", func(c *Config) { c.ToolDiscoveryInterval = durPtr(24 * time.Hour) }, false},
+		{"discovery 10s rejected (below min)", func(c *Config) { c.ToolDiscoveryInterval = durPtr(10 * time.Second) }, true},
+		{"discovery 48h rejected (above max)", func(c *Config) { c.ToolDiscoveryInterval = durPtr(48 * time.Hour) }, true},
+		// Per-server pointers validated too.
+		{"per-server health 2s rejected", func(c *Config) {
+			c.Servers = []*ServerConfig{{Name: "s", HealthCheckInterval: durPtr(2 * time.Second)}}
+		}, true},
+		{"per-server discovery 30s accepted", func(c *Config) {
+			c.Servers = []*ServerConfig{{Name: "s", ToolDiscoveryInterval: durPtr(30 * time.Second)}}
+		}, false},
+		{"per-server discovery 5s rejected", func(c *Config) {
+			c.Servers = []*ServerConfig{{Name: "s", ToolDiscoveryInterval: durPtr(5 * time.Second)}}
+		}, true},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			c := DefaultConfig()
+			tc.mutate(c)
+			errs := c.ValidateDetailed()
+			hasIntervalErr := false
+			for _, e := range errs {
+				if containsAny(e.Field, "health_check_interval", "tool_discovery_interval") {
+					hasIntervalErr = true
+				}
+			}
+			if hasIntervalErr != tc.wantError {
+				t.Errorf("validation interval error = %v, want %v (errors: %+v)", hasIntervalErr, tc.wantError, errs)
+			}
+		})
+	}
+}
+
+func containsAny(s string, subs ...string) bool {
+	for _, sub := range subs {
+		for i := 0; i+len(sub) <= len(s); i++ {
+			if s[i:i+len(sub)] == sub {
+				return true
+			}
+		}
+	}
+	return false
+}