From 9fbc3b223a563db061689e854438d1d7b05875d1 Mon Sep 17 00:00:00 2001 From: Cameron Cooke Date: Wed, 6 May 2026 22:37:22 +0100 Subject: [PATCH 1/2] docs: Document MCP idle timeout configuration Add website documentation for XCODEBUILDMCP_MCP_IDLE_TIMEOUT_MS in the environment variable reference and MCP server mode guide. Refs getsentry/XcodeBuildMCP#394 Co-Authored-By: Codex --- app/docs/_content/env-vars.mdx | 7 +++++++ app/docs/_content/mcp-mode.mdx | 16 ++++++++++++++++ 2 files changed, 23 insertions(+) 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..fbee886 100644 --- a/app/docs/_content/mcp-mode.mdx +++ b/app/docs/_content/mcp-mode.mdx @@ -118,4 +118,20 @@ 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. + +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. From 70e649cb02aa2588a654ec0eb5d95316f6028bf4 Mon Sep 17 00:00:00 2001 From: Cameron Cooke Date: Thu, 7 May 2026 08:35:40 +0100 Subject: [PATCH 2/2] docs: Note MCP idle timeout client reconnect caveat Warn that idle shutdown depends on the MCP client recovering from a server-side stdio disconnect, and call out clients known to respawn gracefully. Refs getsentry/XcodeBuildMCP#394 Co-Authored-By: Codex --- app/docs/_content/mcp-mode.mdx | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/app/docs/_content/mcp-mode.mdx b/app/docs/_content/mcp-mode.mdx index fbee886..1ef9351 100644 --- a/app/docs/_content/mcp-mode.mdx +++ b/app/docs/_content/mcp-mode.mdx @@ -132,6 +132,10 @@ MCP server mode does not shut down for idleness by default. To opt in, set `XCOD 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. + + 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. + + 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.