docs: document discovery & health-check intervals (#608)

docs/configuration/config-file.md

@@ -27,6 +27,8 @@ MCPProxy uses a JSON configuration file located at `~/.mcpproxy/mcp_config.json`
   "data_dir": "~/.mcpproxy",
   "api_key": "your-secret-api-key",
   "enable_socket": true,
+  "health_check_interval": "30s",
+  "tool_discovery_interval": "5m",
   "tools_limit": 15,
   "tool_response_limit": 20000,
   "enable_code_execution": false,
@@ -64,6 +66,43 @@ MCPProxy uses a JSON configuration file located at `~/.mcpproxy/mcp_config.json`
 | `tools_limit` | integer | `15` | Maximum tools to return in a single request |
 | `tool_response_limit` | integer | `20000` | Maximum characters in tool response |
 
+### Tool Discovery & Health Check Intervals
+
+MCPProxy keeps upstream connections fresh with two independent background loops:
+
+- a lightweight **liveness probe** that sends a standard MCP `ping` to confirm the connection is alive, and
+- a periodic **tool-discovery sweep** that re-lists tools to rebuild the search index. (Tool changes are also picked up reactively via `notifications/tools/list_changed`; the sweep is a fallback for servers that don't advertise `listChanged`.)
+
+Both cadences are configurable globally, and can be overridden per server (see [Upstream Servers](/configuration/upstream-servers)). Values are [duration strings](https://pkg.go.dev/time#ParseDuration) such as `30s`, `5m`, or `1h`.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `health_check_interval` | duration | `30s` | Cadence of the lightweight liveness `ping`. Accepts `0s` or `5s`–`1h`. `0s` disables the probe. |
+| `tool_discovery_interval` | duration | `5m` | Cadence of the periodic `tools/list` re-index sweep. Accepts `0s` or `30s`–`24h`. `0s` disables the sweep. |
+
+**Resolution order**: per-server value → global value → built-in default. Leaving a key unset preserves the previous behaviour, so existing configs are unaffected by an upgrade.
+
+```json
+{
+  "health_check_interval": "30s",
+  "tool_discovery_interval": "5m",
+  "mcpServers": [
+    {
+      "name": "chatty-server",
+      "health_check_interval": "2m",
+      "tool_discovery_interval": "0s"
+    }
+  ]
+}
+```
+
+**Notes:**
+
+- **`0s` = disabled.** Disabling the discovery sweep for a server that does **not** support `listChanged` means tool changes are only picked up on (re)connect — fine for static servers, worth knowing for dynamic ones. With the liveness probe disabled, a dead transport is detected lazily (on the next real tool call or discovery sweep) rather than proactively.
+- **Docker-isolated servers**: `health_check_interval` is a **no-op** — their liveness is monitored at the container level, not via MCP `ping`. `tool_discovery_interval` still applies. Remote (HTTP/SSE) servers benefit most from the `ping`-based probe.
+- **Hot reload**: interval changes take effect on the next cycle without a full restart.
+- These intervals are also editable in the Web UI and macOS app under **Settings → Advanced → Tool discovery & health checks**.
+
 ### Code Execution Settings
 
 | Option | Type | Default | Description |

docs/configuration/upstream-servers.md

@@ -72,6 +72,10 @@ Servers requiring OAuth 2.1 authentication:
 | `working_dir` | string | No | Working directory for stdio servers |
 | `env` | object | No | Environment variables to pass |
 | `oauth` | object | No | OAuth configuration |
+| `health_check_interval` | duration | No | Per-server override for the liveness `ping` cadence (`0s` disables; falls back to the global value, then the `30s` default). No-op for Docker-isolated servers. |
+| `tool_discovery_interval` | duration | No | Per-server override for the `tools/list` re-index sweep (`0s` disables; falls back to the global value, then the `5m` default). |
+
+See [Tool Discovery & Health Check Intervals](/configuration/config-file#tool-discovery--health-check-intervals) for the global defaults, accepted ranges, and trade-offs.
 
 ## Headers, Environment Variables, and Secrets