getsentry · cameroncooke · Mar 9, 2026 · Mar 11, 2026 · Mar 11, 2026 · Mar 11, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,17 @@
 # Changelog
 
+## [Unreleased]
+
+### Added
+
+- Added environment variable support for flat session default bootstrap values (for example `XCODEBUILDMCP_WORKSPACE_PATH`, `XCODEBUILDMCP_SCHEME`, and `XCODEBUILDMCP_PLATFORM`) so constrained MCP clients can supply startup defaults without changing project config files ([#268](https://github.com/getsentry/XcodeBuildMCP/pull/268) by [@detailobsessed](https://github.com/detailobsessed)).
+- Added `--format mcp-json` flag to `xcodebuildmcp setup` that exports an env-based MCP bootstrap config block instead of writing `config.yaml` ([#268](https://github.com/getsentry/XcodeBuildMCP/pull/268) by [@detailobsessed](https://github.com/detailobsessed)).
+- Added MCP bootstrap config examples to [docs/CONFIGURATION.md](docs/CONFIGURATION.md) for clients that need env-based startup defaults ([#268](https://github.com/getsentry/XcodeBuildMCP/pull/268) by [@detailobsessed](https://github.com/detailobsessed)).
+
+### Changed
+
+- Clarified configuration layering: `session_set_defaults` overrides `config.yaml`, which overrides env-based bootstrap values. See [docs/CONFIGURATION.md](docs/CONFIGURATION.md) ([#268](https://github.com/getsentry/XcodeBuildMCP/pull/268) by [@detailobsessed](https://github.com/detailobsessed)).
+
 ## [2.2.1]
 
 - Fix AXe bundling issue.
@@ -395,4 +407,3 @@ Please note that the UI automation features are an early preview and currently i
 - Initial release of XcodeBuildMCP
 - Basic support for building iOS and macOS applications
 
-
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
@@ -1,10 +1,12 @@
 # Configuration
 
-XcodeBuildMCP reads configuration from a project config file. The config file is optional but provides deterministic, repo-scoped behavior for every session.
+XcodeBuildMCP reads configuration from environment variables and/or a project config file. Both are optional but provide deterministic behavior for every session.
 
 ## Contents
 
 - [Config file](#config-file)
+- [Configuration layering](#configuration-layering)
+- [Environment variables](#environment-variables)
 - [Session defaults](#session-defaults)
 - [Workflow selection](#workflow-selection)
 - [Build settings](#build-settings)
@@ -13,13 +15,12 @@ XcodeBuildMCP reads configuration from a project config file. The config file is
 - [Templates](#templates)
 - [Telemetry](#telemetry)
 - [Quick reference](#quick-reference)
-- [Environment variables (legacy)](#environment-variables-legacy)
 
 ---
 
 ## Config file
 
-Create a config file at your workspace root:
+The config file provides repo-scoped, version-controllable configuration. Create it at your workspace root:
 
 ```
 <workspace-root>/.xcodebuildmcp/config.yaml
@@ -337,15 +338,36 @@ Notes:
 
 ---
 
-## Environment variables (legacy)
+## Configuration layering
 
-Environment variables are supported for backwards compatibility but the config file is preferred.
+When multiple configuration sources are present, they are merged with clear precedence:
+
+1. **`session_set_defaults` tool** (highest) — agent runtime overrides, set during a session
+2. **Config file** — project-local config (`config.yaml`), committed to repo
+3. **Environment variables** (lowest) — MCP client integration, set in `mcp_config.json`
+
+This follows the same pattern as tools like `git config` (`--flag` > `--local` > `--global`). Each layer serves a different context:
+
+- **Config file** is the canonical home for structured, repo-scoped, version-controlled settings.
+- **Env vars** are best used to bootstrap flat startup defaults for MCP clients with limited workspace support.
+- **Tool calls** are for agent-driven runtime adjustments.
+
+---
+
+## Environment variables
+
+Environment variables are supported for MCP client integration when a client cannot reliably provide workspace context to the server. Set them in the `env` field of your MCP client config (for example `mcp_config.json` for Windsurf, `.vscode/mcp.json` for VS Code, or `claude_desktop_config.json` for Claude Desktop).
+
+Use env vars for flat bootstrap values such as startup workflow selection, project path, scheme, simulator selector, or other scalar defaults. Keep structured project-owned configuration in `config.yaml`.
+
+### General settings
 
 | Config option | Environment variable |
 |---------------|---------------------|
 | `enabledWorkflows` | `XCODEBUILDMCP_ENABLED_WORKFLOWS` (comma-separated) |
 | `experimentalWorkflowDiscovery` | `XCODEBUILDMCP_EXPERIMENTAL_WORKFLOW_DISCOVERY` |
 | `disableSessionDefaults` | `XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS` |
+| `disableXcodeAutoSync` | `XCODEBUILDMCP_DISABLE_XCODE_AUTO_SYNC` |
 | `incrementalBuildsEnabled` | `INCREMENTAL_BUILDS_ENABLED` |
 | `debug` | `XCODEBUILDMCP_DEBUG` |
 | `sentryDisabled` | `XCODEBUILDMCP_SENTRY_DISABLED` |
@@ -360,7 +382,55 @@ Environment variables are supported for backwards compatibility but the config f
 | `macosTemplatePath` | `XCODEBUILDMCP_MACOS_TEMPLATE_PATH` |
 | `macosTemplateVersion` | `XCODEBUILD_MCP_MACOS_TEMPLATE_VERSION` |
 
-Config file takes precedence over environment variables when both are set.
+### Session default bootstrap values
+
+| Session default | Environment variable |
+|----------------|---------------------|
+| `workspacePath` | `XCODEBUILDMCP_WORKSPACE_PATH` |
+| `projectPath` | `XCODEBUILDMCP_PROJECT_PATH` |
+| `scheme` | `XCODEBUILDMCP_SCHEME` |
+| `configuration` | `XCODEBUILDMCP_CONFIGURATION` |
+| `simulatorName` | `XCODEBUILDMCP_SIMULATOR_NAME` |
+| `simulatorId` | `XCODEBUILDMCP_SIMULATOR_ID` |
+| `simulatorPlatform` | `XCODEBUILDMCP_SIMULATOR_PLATFORM` |
+| `deviceId` | `XCODEBUILDMCP_DEVICE_ID` |
+| `platform` | `XCODEBUILDMCP_PLATFORM` |
+| `useLatestOS` | `XCODEBUILDMCP_USE_LATEST_OS` |
+| `arch` | `XCODEBUILDMCP_ARCH` |
+| `suppressWarnings` | `XCODEBUILDMCP_SUPPRESS_WARNINGS` |
+| `derivedDataPath` | `XCODEBUILDMCP_DERIVED_DATA_PATH` |
+| `preferXcodebuild` | `XCODEBUILDMCP_PREFER_XCODEBUILD` |
+| `bundleId` | `XCODEBUILDMCP_BUNDLE_ID` |
+
+### Example MCP config
+
+Use this when your MCP client needs env-based bootstrap defaults:
+
+```json
+{
+  "mcpServers": {
+    "XcodeBuildMCP": {
+      "command": "npx",
+      "args": ["-y", "xcodebuildmcp@latest", "mcp"],
+      "env": {
+        "XCODEBUILDMCP_ENABLED_WORKFLOWS": "simulator,debugging,logging",
+        "XCODEBUILDMCP_WORKSPACE_PATH": "/Users/me/MyApp/MyApp.xcworkspace",
+        "XCODEBUILDMCP_SCHEME": "MyApp",
+        "XCODEBUILDMCP_PLATFORM": "iOS Simulator",
+        "XCODEBUILDMCP_SIMULATOR_NAME": "iPhone 16 Pro"
+      }
+    }
+  }
+}
+```
+
+You can also export a bootstrap block interactively:
+
+```bash
+xcodebuildmcp setup --format mcp-json
+```
+
+That export is intended for MCP client bootstrap. It does not replace `config.yaml` as the canonical project configuration.
 
 ---