Docs/Usage/Workflows

Workflows

Tools are grouped into workflow packages. Enable only what your agent needs, each dropped workflow saves context.

By default only the simulator workflow is enabled. Enable more via .xcodebuildmcp/config.yaml:

yaml

schemaVersion: 1
enabledWorkflows:
  - simulator
  - debugging
  - ui-automation

Or via env var (comma-separated):

shell

export XCODEBUILDMCP_ENABLED_WORKFLOWS="simulator,debugging,ui-automation"

Available workflows#

This list is generated live from the latest getsentry/XcodeBuildMCP release.

Workflow	Tools	Description
coverage	2	View code coverage data from xcresult bundles produced by test runs.
debugging	8	Attach LLDB debugger to simulator apps, set breakpoints, inspect variables and call stacks.
device	17	Complete iOS development workflow for physical devices (iPhone, iPad, Apple Watch, Apple TV, Apple Vision Pro).
doctor	1	Diagnostic tool providing comprehensive information about the MCP server environment, dependencies, and configuration.
logging	4	Capture and retrieve logs from simulator and device apps.
macos	13	Complete macOS development workflow for both .xcodeproj and .xcworkspace files. Build, test, deploy, and manage macOS applications.
project-discovery	5	Discover and examine Xcode projects, workspaces, and Swift packages. Analyze project structure, schemes, build settings, and bundle information.
project-scaffolding	2	Scaffold new iOS and macOS projects from templates.
session-managementdefault	5	Manage session defaults for project/workspace paths, scheme, configuration, simulator/device settings.
simulatordefault	23	Complete iOS development workflow for both .xcodeproj and .xcworkspace files targeting simulators.
simulator-management	8	Tools for managing simulators from booting, opening simulators, listing simulators, stopping simulators, erasing simulator content and settings, and setting simulator environment options like location, network, statusbar and appearance.
swift-package	8	Build, test, run and manage Swift Package Manager projects.
ui-automation	11	UI automation and accessibility testing tools for iOS simulators. Perform gestures, interactions, screenshots, and UI analysis for automated testing workflows.
utilities	1	Utility tools for cleaning build products and managing build artifacts.
workflow-discovery	1	Manage enabled workflows at runtime.
xcode-ide	5	Bridge tools for connecting to Xcode's built-in MCP server (mcpbridge) to access IDE-specific functionality.

Custom workflows#

Define your own workflow in config.yaml with an explicit tool list:

yaml

schemaVersion: 1
enabledWorkflows: ["my-workflow"]
customWorkflows:
  my-workflow:
    - build_run_sim
    - record_sim_video
    - screenshot

Notes:

Session-management tools are always auto-included.
The doctor workflow is auto-included when debug: true.
Custom workflow names are normalized to lowercase.
Unknown tool names are ignored and logged as warnings.

Experimental: workflow discovery#

Expose a manage-workflows tool so agents can add/remove workflows at runtime:

yaml

experimentalWorkflowDiscovery: true

Requires client support

This depends on MCP tools/list_changed notifications. Cursor, Claude Code, and Codex do not support this at the time of writing; a session restart is required for changes to take effect.

Context savings

Cutting from the full catalog to simulator,debugging drops advertised tool count from 82 to 23 + 8 (minus overlaps), saving roughly 70% of tool-list tokens on agent boot.