config.yaml is unreliable with MCP clients — env vars should be the primary configuration surface

[ichoosetoaccept]

Problem

XcodeBuildMCP's primary configuration mechanism is a project-local file at .xcodebuildmcp/config.yaml. This file is discovered relative to process.cwd(). However, MCP clients do not guarantee that process.cwd() points to the user's project directory when spawning stdio-based MCP servers.

Empirically verified with Windsurf (Codeium):

process.cwd(): /
process.argv: ["node", ".../build/cli.js", "mcp"]

The server starts with cwd=/, so loadProjectConfig never finds <project>/.xcodebuildmcp/config.yaml. This means:

• enabledWorkflows is empty, so only defaultEnabled workflows are registered (simulator + session-management). macOS, device, coverage, debugging, logging, ui-automation, xcode-ide, and other workflows are invisible.
• sessionDefaults from the config file are not applied.
• incrementalBuildsEnabled, debug, and other flags are not set.

The user has no way to fix this without either:

1. Hardcoding a --cwd path in the MCP config (breaks multi-project setups)
2. Using XCODEBUILDMCP_CWD env var (same problem)

Why cwd is unreliable for MCP servers

The MCP specification does not prescribe the working directory of spawned server processes. While all three official MCP SDKs support cwd as a parameter, MCP clients vary widely in whether they actually set it:

MCP Client	cwd behavior
VS Code	Supports ${workspaceFolder} interpolation in mcp.json
Cursor	Supports ${workspaceFolder} interpolation (added after community requests)
Windsurf	Always sets cwd=/ — reported here
OpenAI Codex	Does not set workspace cwd — openai/codex#4222
Claude Desktop	No cwd field in config; relies on absolute paths

Relying on process.cwd() + a config file is fragile because:

• MCP clients don't guarantee cwd. Windsurf sets it to /. Codex has the same bug. Claude Desktop doesn't expose it at all.
• ${workspaceFolder} interpolation is not standard. Only VS Code and Cursor support it. Windsurf and Claude Desktop do not.
• roots capability could theoretically solve this, but client adoption is sparse (very few clients support it today).
• tools/listChanged notifications could allow lazy tool registration after config is discovered, but not all clients honor these notifications in practice.

Env vars are the ecosystem standard, not "legacy"

The current CONFIGURATION.md labels environment variables as "legacy." This is at odds with the broader MCP ecosystem, where env vars are the de facto standard for server configuration.

Evidence:

1. The MCP config schema itself is designed around env vars. Every MCP client implements the env field:

   {
     "mcpServers": {
       "my-server": {
         "command": "my-server",
         "args": [],
         "env": {
           "MY_SERVER_API_KEY": "...",
           "MY_SERVER_OPTION": "true"
         }
       }
     }
   }

2. MCP best practices (modelcontextprotocol.info) explicitly recommends: "Externalize all configuration with environment-specific overrides" — using Pydantic BaseSettings with env_prefix as the reference pattern.

3. Reference MCP server implementations (filesystem, GitHub, Sentry, Playwright, etc.) all use environment variables for configuration, not config files.

4. Every MCP client supports env (Claude Desktop, VS Code, Cursor, Windsurf, Claude Code, Codex). It works regardless of cwd, doesn't require filesystem discovery, and is explicit.

5. 12-factor app principles — widely adopted in the server ecosystem — prescribe that config should live in the environment, not in files tied to deployment.

Config files have their place (CLI usage, complex multi-profile setups), but env vars should be the recommended path for MCP client integration since they work reliably across all clients.

Current env var support

XcodeBuildMCP already supports env vars for most config options via readEnvConfig() in config-store.ts:

Config key	Env var	Status
enabledWorkflows	XCODEBUILDMCP_ENABLED_WORKFLOWS	Supported
debug	XCODEBUILDMCP_DEBUG	Supported
sentryDisabled	XCODEBUILDMCP_SENTRY_DISABLED	Supported
incrementalBuildsEnabled	INCREMENTAL_BUILDS_ENABLED	Supported
experimentalWorkflowDiscovery	XCODEBUILDMCP_EXPERIMENTAL_WORKFLOW_DISCOVERY	Supported
disableSessionDefaults	XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS	Supported
disableXcodeAutoSync	XCODEBUILDMCP_DISABLE_XCODE_AUTO_SYNC	Supported
debuggerBackend	XCODEBUILDMCP_DEBUGGER_BACKEND	Supported
sessionDefaults.*	—	Not supported

The gap is sessionDefaults — there are no env vars for workspacePath, scheme, platform, derivedDataPath, suppressWarnings, etc.

Proposal

1. Remove the "legacy" label from environment variables in the documentation. Env vars are the ecosystem standard for MCP server configuration, not a deprecated mechanism.

2. Add env vars for session defaults (the main gap):

   • XCODEBUILDMCP_WORKSPACE_PATH
   • XCODEBUILDMCP_PROJECT_PATH
   • XCODEBUILDMCP_SCHEME
   • XCODEBUILDMCP_PLATFORM
   • XCODEBUILDMCP_DERIVED_DATA_PATH
   • XCODEBUILDMCP_SUPPRESS_WARNINGS
   • XCODEBUILDMCP_SIMULATOR_NAME
   • XCODEBUILDMCP_SIMULATOR_ID
   • XCODEBUILDMCP_CONFIGURATION
   • XCODEBUILDMCP_USE_LATEST_OS
   • XCODEBUILDMCP_PREFER_XCODEBUILD
   • XCODEBUILDMCP_ARCH
   • XCODEBUILDMCP_BUNDLE_ID
   • XCODEBUILDMCP_DEVICE_ID
   • XCODEBUILDMCP_SIMULATOR_PLATFORM

3. Document env vars as the recommended configuration method for MCP client integration. Provide copy-pastable MCP config snippets for common setups (iOS, macOS, multi-platform) so users can get started without guessing which workflows and session defaults they need.

4. Have xcodebuildmcp setup output a ready-to-paste MCP config JSON block (e.g. --format mcp-json). The interactive flow is genuinely useful for guiding users through configuration — the output format just needs to match how MCP clients consume it.

5. Be explicit about the configuration layering. Env vars and config.yaml are not competing sources of truth — they serve different contexts with clear precedence:

   • Env vars → MCP client integration (set in mcp_config.json's env field)
   • Config file → project-local config (committed to repo, used by CLI / xcodebuildmcp setup)
   • session_set_defaults tool → agent runtime overrides (set during a session)

   Precedence: tool > file > env. This is the standard pattern (like git config --global < --local < --flag). Document it clearly so users understand which layer wins.

Accompanying PR

A PR implementing all of the above is ready:

• readEnvSessionDefaults() in config-store.ts — parses all 15 session default env vars
• resolveSessionDefaults() updated — merges env → file → tool overrides
• selectionToMcpConfigJson() in setup.ts — xcodebuildmcp setup --format mcp-json
• CONFIGURATION.md rewritten — env vars first, "legacy" label removed, layering documented
• Tests for env var parsing and file-over-env precedence
• Test for --format mcp-json output

Example: full env-var-based MCP config

This replaces a config.yaml entirely:

{
  "mcpServers": {
    "XcodeBuildMCP": {
      "command": "xcodebuildmcp",
      "args": ["mcp"],
      "env": {
        "XCODEBUILDMCP_ENABLED_WORKFLOWS": "coverage,debugging,doctor,logging,macos,project-discovery,project-scaffolding,swift-package,ui-automation,utilities,xcode-ide",
        "XCODEBUILDMCP_DEBUG": "true",
        "INCREMENTAL_BUILDS_ENABLED": "true",
        "XCODEBUILDMCP_WORKSPACE_PATH": "/Users/me/myproject/myproject.xcworkspace",
        "XCODEBUILDMCP_SCHEME": "myproject",
        "XCODEBUILDMCP_PLATFORM": "macOS",
        "XCODEBUILDMCP_DERIVED_DATA_PATH": "/Users/me/myproject/.derivedData",
        "XCODEBUILDMCP_SUPPRESS_WARNINGS": "true"
      }
    }
  }
}

[ichoosetoaccept]

After the initial submission, added platform-specific copy-pastable MCP config examples to docs/CONFIGURATION.md — one each for macOS, iOS, iOS+macOS (multi-platform / Catalyst), and tvOS/watchOS. Each includes a callout explaining which workflows are relevant and why (e.g., no simulator workflow for macOS, both simulator and macos for multi-platform projects without pinning XCODEBUILDMCP_PLATFORM).

These were promised in the proposal under point 3 ("Provide copy-pastable MCP config snippets for common setups") but weren't in the initial diff.

[cameroncooke]

Thanks for the investigation and the implementation. The compatibility problem you've identified is real, and I don't want to dismiss it.

I agree that:

• some MCP clients don't provide a reliable project cwd
• this makes repo-local config discovery less portable than it should be
• env vars are a useful fallback for those clients

Where I disagree is treating env vars as the primary configuration surface rather than a compatibility layer.

On the scope of the compatibility problem

It's worth noting that the most widely used clients handle this well. Cursor, VS Code, Codex CLI, and Claude Code CLI all set cwd to the workspace root by default, or support explicit override via ${workspaceFolder} interpolation. This is also the first issue we've seen reporting config discovery problems, which suggests the majority of users are on clients where things work as expected today.

The MCP spec not prescribing working directory behaviour is true, but it cuts both ways: the spec also doesn't prescribe client config file formats, yet we've ended up with config.toml, mcp.json, claude.json, and others. Lack of prescription doesn't make something a design target. The real-world situation for mainstream clients is better than the framing here suggests, and I'd rather not reshape the config model around a minority of edge cases.

Why config.yaml exists, and why that matters

The decision to use a project-local config file wasn't just about structure - it was a deliberate design choice to make configuration something that agents can write to and teams can share via source control. That's a first-class feature, not a side effect.

This means config.yaml can be:

• committed to the repo and shared across the whole team
• reviewed in pull requests like any other project decision
• written and updated by agents during a session, not just read
• evolved alongside the project with full version history

Env vars have none of these properties. They typically live in local or client-specific config, aren't committed, aren't reviewable in context, and are awkward for agents to update safely. Elevating them to the primary config surface would directly undermine the collaborative, agent-writable design that makes the file-based approach worthwhile.

Why env vars don't scale as the canonical config model

XcodeBuildMCP's config model already includes workflow selection, session defaults, profiles, custom workflows, runtime overrides, and path resolution. That's structured state, and env vars are a poor fit for it.

When you try to represent something like this in env vars:

schemaVersion: 1
sessionDefaults:
  workspacePath: ./App.xcworkspace
  scheme: App
  platform: iOS Simulator
sessionDefaultsProfiles:
  ios:
    workspacePath: ./App.xcworkspace
    scheme: App
    platform: iOS Simulator
    simulatorName: iPhone 16 Pro
  macos:
    workspacePath: ./App.xcworkspace
    scheme: App
    platform: macOS
customWorkflows:
  local-debug:
    - simulator
    - debugging
    - logging

...the options are all bad:

Option 1 - explode into bespoke vars:

{
  "env": {
    "XCODEBUILDMCP_PROFILE_IOS_SCHEME": "App",
    "XCODEBUILDMCP_PROFILE_IOS_PLATFORM": "iOS Simulator",
    "XCODEBUILDMCP_PROFILE_MACOS_SCHEME": "App",
    "XCODEBUILDMCP_CUSTOM_WORKFLOW_LOCAL_DEBUG": "simulator,debugging,logging"
  }
}

Option 2 - encode structured data into a single string:

{
  "env": {
    "XCODEBUILDMCP_SESSION_DEFAULTS_PROFILES": "{\"ios\":{\"scheme\":\"App\"},\"macos\":{\"scheme\":\"App\"}}"
  }
}

Option 3 - only support a subset of features in env vars.

Option 1 doesn't scale. Option 2 is just a worse config file inside a string. Option 3 creates a split-brain system where some features are "real" and others are second-class. Each also introduces parsing, validation, naming, and documentation overhead that compounds as the config surface grows.

There's also a subtler design risk: if env vars become first-class, future config work starts with "can we represent this in env vars?" instead of "what's the right model?" That's a design trap worth avoiding.

The right layering

The better answer to the portability problem is a clear precedence model:

1. session_set_defaults - runtime overrides for the current agent session
2. config.yaml - canonical project-local structured config
3. env vars - compatibility/bootstrap layer for constrained MCP clients

What I'd support from this work (#268)

• Env var support for flat sessionDefaults fields (the missing ones identified here)
• Clearer precedence documentation
• Improved setup/export flows for clients that need env-based bootstrap

What I wouldn't want is describing env vars as the recommended primary method, or letting env-var ergonomics constrain future structured config work.

The portability concern is valid. I just think the right fix preserves config.yaml as the source of truth rather than moving the centre of gravity into client env blocks.