diff --git a/app/docs/_content/env-vars.mdx b/app/docs/_content/env-vars.mdx
index 3022910..4faded8 100644
--- a/app/docs/_content/env-vars.mdx
+++ b/app/docs/_content/env-vars.mdx
@@ -32,6 +32,7 @@ Set env vars in the `env` field of your MCP client config (for example `mcp_conf
 | `dapRequestTimeoutMs` | `XCODEBUILDMCP_DAP_REQUEST_TIMEOUT_MS` |
 | `dapLogEvents` | `XCODEBUILDMCP_DAP_LOG_EVENTS` |
 | `launchJsonWaitMs` | `XBMCP_LAUNCH_JSON_WAIT_MS` |
+| MCP idle timeout | `XCODEBUILDMCP_MCP_IDLE_TIMEOUT_MS` |
 | `uiDebuggerGuardMode` | `XCODEBUILDMCP_UI_DEBUGGER_GUARD_MODE` |
 | `axePath` | `XCODEBUILDMCP_AXE_PATH` |
 | `iosTemplatePath` | `XCODEBUILDMCP_IOS_TEMPLATE_PATH` |
@@ -59,6 +60,12 @@ Set env vars in the `env` field of your MCP client config (for example `mcp_conf
 | `preferXcodebuild` | `XCODEBUILDMCP_PREFER_XCODEBUILD` |
 | `bundleId` | `XCODEBUILDMCP_BUNDLE_ID` |
 
+## MCP idle shutdown
+
+`XCODEBUILDMCP_MCP_IDLE_TIMEOUT_MS` is disabled by default (`0`). Set it to a positive number of milliseconds when you want an unused MCP server process to shut down gracefully after that idle period.
+
+The server only exits when the timeout has elapsed, no MCP request is in flight, and no registered runtime operation is active.
+
 ## Example
 
 ```json
diff --git a/app/docs/_content/mcp-mode.mdx b/app/docs/_content/mcp-mode.mdx
index bc8074f..1ef9351 100644
--- a/app/docs/_content/mcp-mode.mdx
+++ b/app/docs/_content/mcp-mode.mdx
@@ -118,4 +118,24 @@ Enable `xcode-ide` to expose Xcode 26+'s `xcrun mcpbridge` tools through XcodeBu
 
 Every tool declares read-only, destructive, and open-world hints so MCP clients that respect annotations can skip unnecessary confirmation prompts for lower-risk calls and keep prompts for risky ones.
 
+## Idle shutdown
+
+MCP server mode does not shut down for idleness by default. To opt in, set `XCODEBUILDMCP_MCP_IDLE_TIMEOUT_MS` to a positive number of milliseconds in your MCP client env config.
+
+```json
+{
+  "env": {
+    "XCODEBUILDMCP_MCP_IDLE_TIMEOUT_MS": "600000"
+  }
+}
+```
+
+When enabled, the server exits through the normal graceful shutdown path only after the idle timeout has elapsed, no MCP request is in flight, and no registered runtime operation is active. Use `0` or omit the variable to keep idle shutdown disabled.
+
+<Callout variant="warn" title="Client reconnect behavior varies">
+  Idle shutdown closes the MCP stdio connection from the server side. Claude Code and Codex CLI are expected to respawn MCP servers after disconnects, but other MCP clients may not handle this gracefully. Keep this disabled unless your client can recover from the server exiting, and choose a timeout long enough for normal pauses between agent requests.
+</Callout>
+
+See [Environment Variables](/docs/env-vars#mcp-idle-shutdown) for the full reference.
+
 See [MCP Protocol Support](/docs/mcp-protocol-support) for the full list of MCP features XcodeBuildMCP implements.