Session Defaults

Set shared values once per session (workspace, scheme, simulator, etc.) and every tool reuses them automatically.

Session defaults are the single biggest token saver when working with an agent. Instead of your agent re-asking for project path, scheme, and simulator on every tool call, it sets them once and all subsequent calls reuse the values.

Session defaults are on by default.

How it works#

1. At the start of a session, the agent stores your defaults (workspace, scheme, simulator, etc.) via session_set_defaults, or picks them up from .xcodebuildmcp/config.yaml.
2. Every subsequent tool call uses those stored values when a matching parameter is missing.
3. Ask your agent to show the current defaults at any time. It reads them via session_show_defaults.
4. When you switch projects or context, ask the agent to clear or replace the defaults. It uses session_clear_defaults or another session_set_defaults call.

Setting defaults#

From the agent (runtime)#

Tell your agent which workspace (or project), scheme, and simulator to use; it will store those values via session_set_defaults. By default these live in memory only. Ask your agent to persist them and they will be saved to .xcodebuildmcp/config.yaml, patch-only, so only the keys you set are updated.

From config (startup)#

Seed defaults when the server boots by adding a sessionDefaults block to .xcodebuildmcp/config.yaml:

schemaVersion: 1
sessionDefaults:
  projectPath: "./MyApp.xcodeproj"
  scheme: "MyApp"
  simulatorName: "iPhone 17 Pro"
  configuration: "Debug"

From environment variables (MCP client bootstrap)#

When your MCP client can't supply workspace context directly, use env vars:

{
  "env": {
    "XCODEBUILDMCP_WORKSPACE_PATH": "/repo/MyApp.xcworkspace",
    "XCODEBUILDMCP_SCHEME": "MyApp",
    "XCODEBUILDMCP_SIMULATOR_NAME": "iPhone 17 Pro"
  }
}

See Environment Variables for the full list.

Reference#

Mutual exclusivity#

• projectPath vs workspacePath → workspacePath wins if both are set.
• simulatorId vs simulatorName → simulatorId wins if both are set.

Named profiles#

For monorepos, keep separate defaults per sub-project. Each profile is strictly isolated, values are not inherited from the global profile.

schemaVersion: 1
sessionDefaultsProfiles:
  ios:
    workspacePath: ./MyApp.xcworkspace
    scheme: MyApp-iOS
    simulatorName: iPhone 17 Pro
  watch:
    workspacePath: ./MyApp.xcworkspace
    scheme: MyApp-watchOS
    simulatorName: Apple Watch Series 10 (45mm)
activeSessionDefaultsProfile: ios

Tell your agent to switch profiles ("use the watch profile") and it will load that profile via session_use_defaults_profile. Ask it to persist the switch if you want the profile selection to survive restarts. To return to the unnamed global profile, ask the agent to switch back to global. To create a new profile on the fly, ask the agent to set defaults under a new profile name.

Opting out#

If you prefer explicit parameters on every tool call, set this at the top level of your config:

disableSessionDefaults: true

Or via env:

export XCODEBUILDMCP_DISABLE_SESSION_DEFAULTS=true

This restores the legacy behavior where every parameter must be passed on every call.

CLI behavior#

The CLI auto-fills matching flags from session defaults. If your config sets scheme, projectPath, and simulatorName, xcodebuildmcp simulator build just works, no need to repeat those flags. Override for a single call with --profile <name> or by passing the flag explicitly.

See CLI for more.

Related#

• Configuration, everything else XcodeBuildMCP reads on startup
• Environment Variables, env-based bootstrap
• Workflows, pick which tool groups are loaded