fix: retire idle bundled MCP runtimes

docs/.generated/config-baseline.sha256

@@ -1,4 +1,4 @@
-3b8ff208a31b04ea61391182444bd744357577872eac279136bbc284c3dc064a  config-baseline.json
-4dfeadeb814fb205f5a17d797cbbe3c07685009821fe8dbf8771ea428ed5b4dd  config-baseline.core.json
+13b68287fec00108ca66032120909a0eac797ed541e026357e175e3fce5bacdd  config-baseline.json
+77ee66fb3b2cde94b393712bc03a132b096cf601c193bde1fe42902eecb0b66b  config-baseline.core.json
 d72032762ab46b99480b57deb81130a0ab5b1401189cfbaf4f7fef4a063a7f6c  config-baseline.channel.json
 0d5ba81f0030bd39b7ae285096276cc18b150836c2252fd2217329fc6154e80e  config-baseline.plugin.json

docs/cli/mcp.md

@@ -376,6 +376,9 @@ Important behavior:
 - embedded Pi exposes configured MCP tools in normal `coding` and `messaging`
   tool profiles; `minimal` still hides them, and `tools.deny: ["bundle-mcp"]`
   disables them explicitly
+- session-scoped bundled MCP runtimes are reaped after `mcp.sessionIdleTtlMs`
+  milliseconds of idle time (default 10 minutes; set `0` to disable) and
+  one-shot embedded runs clean them up at run end
 
 ## Saved MCP server definitions
 

docs/gateway/cli-backends.md

@@ -349,6 +349,12 @@ When bundle MCP is enabled, OpenClaw:
 If no MCP servers are enabled, OpenClaw still injects a strict config when a
 backend opts into bundle MCP so background runs stay isolated.
 
+Session-scoped bundled MCP runtimes are cached for reuse within a session, then
+reaped after `mcp.sessionIdleTtlMs` milliseconds of idle time (default 10
+minutes; set `0` to disable). One-shot embedded runs such as auth probes,
+slug generation, and active-memory recall request cleanup at run end so stdio
+children and Streamable HTTP/SSE streams do not outlive the run.
+
 ## Limitations
 
 - **No direct OpenClaw tool calls.** OpenClaw does not inject tool calls into

docs/gateway/configuration-reference.md

@@ -51,6 +51,44 @@ Tool policy, experimental toggles, provider-backed tool config, and custom
 provider / base-URL setup moved to a dedicated page — see
 [Configuration — tools and custom providers](/gateway/config-tools).
 
+## MCP
+
+OpenClaw-managed MCP server definitions live under `mcp.servers` and are
+consumed by embedded Pi and other runtime adapters. The `openclaw mcp list`,
+`show`, `set`, and `unset` commands manage this block without connecting to the
+target server during config edits.
+
+```json5
+{
+  mcp: {
+    // Optional. Default: 600000 ms (10 minutes). Set 0 to disable idle eviction.
+    sessionIdleTtlMs: 600000,
+    servers: {
+      docs: {
+        command: "npx",
+        args: ["-y", "@modelcontextprotocol/server-fetch"],
+      },
+      remote: {
+        url: "https://example.com/mcp",
+        transport: "streamable-http", // streamable-http | sse
+        headers: {
+          Authorization: "Bearer ${MCP_REMOTE_TOKEN}",
+        },
+      },
+    },
+  },
+}
+```
+
+- `mcp.servers`: named stdio or remote MCP server definitions for runtimes that
+  expose configured MCP tools.
+- `mcp.sessionIdleTtlMs`: idle TTL for session-scoped bundled MCP runtimes.
+  One-shot embedded runs request run-end cleanup; this TTL is the backstop for
+  long-lived sessions and future callers.
+
+See [MCP](/cli/mcp#openclaw-as-an-mcp-client-registry) and
+[CLI backends](/gateway/cli-backends#bundle-mcp-overlays) for runtime behavior.
+
 ## Skills
 
 ```json5