How the build-ios-apps Plugin Integrates with XcodeBuildMCP for Simulator Debugging

The build-ios-apps plugin integrates XcodeBuildMCP for simulator debugging by declaring an MCP server in .mcp.json that launches the xcodebuildmcp npm package, enabling skills like ios-debugger-agent to execute debugging workflows through the Codex MCP client library.

The openai/plugins repository hosts the build-ios-apps plugin, which embeds XcodeBuildMCP (Multi-Client Protocol) directly into the Codex platform. This integration allows AI agents to build iOS apps, launch simulators, and attach debuggers programmatically without manual Xcode interaction.

MCP Server Configuration in .mcp.json

The integration anchor is plugins/build-ios-apps/.mcp.json, which registers the xcodebuildmcp server with the Codex runtime. When the plugin activates, the runtime reads this configuration and spawns the server process.

The file defines the server startup command and environment:

{
  "mcpServers": {
    "xcodebuildmcp": {
      "command": "npx",
      "args": ["-y", "xcodebuildmcp@latest", "mcp"],
      "env": {
        "XCODEBUILDMCP_ENABLED_WORKFLOWS": "simulator,ui-automation,debugging,logging"
      }
    }
  }
}

This configuration instructs the Codex runtime to execute npx -y xcodebuildmcp@latest mcp, ensuring the latest MCP server version starts in MCP mode. The XCODEBUILDMCP_ENABLED_WORKFLOWS environment variable acts as a capability gate, exposing specific workflows to client skills.

XcodeBuildMCP Workflow Configuration

The XCODEBUILDMCP_ENABLED_WORKFLOWS environment variable controls which operations the server exposes. The build-ios-apps plugin enables four distinct workflows:

Simulator Workflow

Handles compiling Xcode schemes and launching the iOS Simulator on specified device types (e.g., iPhone 15).

UI Automation Workflow

Drives UI tests by injecting automation commands into the running simulator instance.

Debugging Workflow

Attaches LLDB to the running app process, enabling breakpoint management and variable inspection during simulator execution.

Logging Workflow

Streams console logs and system output from the simulator back to the requesting skill in real time.

Skill-Level MCP Client Integration

Individual skills consume the MCP server through the Codex MCP client library. The ios-debugger-agent skill, located in plugins/build-ios-apps/skills/ios-debugger-agent/, constructs structured requests to trigger debugging sessions.

A skill initiates debugging by sending a payload to the xcodebuildmcp server:

# inside plugins/build-ios-apps/skills/ios-debugger-agent/scripts/debug.py

from codex.mcp import MCPClient

client = MCPClient(server="xcodebuildmcp")
response = client.run(
    workflow="debugging",
    payload={"scheme": "MyApp", "device": "iPhone 15"}
)

print("Debugger attached – logs:")
print(response["logs"])

The MCPClient abstracts the transport layer, sending JSON-RPC requests to the local xcodebuildmcp process. The server then executes the appropriate xcodebuild commands, launches the specified simulator, attaches LLDB, and returns aggregated logs and debug metadata.

Plugin Manifest and Runtime Activation

The top-level plugin declaration resides in plugins/build-ios-apps/.codex-plugin/plugin.json. This manifest registers the plugin with the Codex platform and references the MCP configuration.

When a user loads the build-ios-apps plugin, the Codex runtime:

1. Parses .codex-plugin/plugin.json to validate the plugin structure
2. Detects .mcp.json and starts the xcodebuildmcp subprocess with the specified environment variables
3. Binds the MCP server endpoints to the skill implementations, making the xcodebuildmcp target available to MCPClient instances

The plugin's documentation in plugins/build-ios-apps/README.md (lines 25-26) explicitly documents this capability, noting that the MCP server provides the underlying infrastructure for simulator builds and live debugging.

Summary

• .mcp.json declares the server: Located at plugins/build-ios-apps/.mcp.json, this file configures the xcodebuildmcp server to start via npx -y xcodebuildmcp@latest mcp.
• Workflow environment variable: XCODEBUILDMCP_ENABLED_WORKFLOWS gates access to simulator builds, UI automation, debugging, and logging workflows.
• Skill implementation: Skills like ios-debugger-agent use the Codex MCPClient class to send requests to the xcodebuildmcp server, triggering xcodebuild operations and LLDB attachment.
• Automatic startup: The .codex-plugin/plugin.json manifest triggers the Codex runtime to launch the MCP server automatically when the plugin loads.

Frequently Asked Questions

What is XcodeBuildMCP and how does it relate to the build-ios-apps plugin?

XcodeBuildMCP is a Multi-Client Protocol server distributed as the xcodebuildmcp@latest npm package. The build-ios-apps plugin embeds this server via its .mcp.json configuration, allowing Codex skills to invoke xcodebuild, manage simulators, and control debuggers through standardized MCP requests rather than direct shell commands.

How do I enable simulator debugging workflows in the build-ios-apps plugin?

Ensure the XCODEBUILDMCP_ENABLED_WORKFLOWS environment variable in plugins/build-ios-apps/.mcp.json includes debugging and simulator in its comma-separated value list. When present, the xcodebuildmcp server exposes endpoints that skills can call to launch simulators and attach LLDB debuggers to running apps.

Which files control the XcodeBuildMCP integration?

The primary files are:

• plugins/build-ios-apps/.mcp.json: Declares the MCP server command and enabled workflows.
• plugins/build-ios-apps/.codex-plugin/plugin.json: Registers the plugin and triggers MCP server startup.
• plugins/build-ios-apps/skills/ios-debugger-agent/: Implements the client-side logic that communicates with the MCP server.

What specific MCP request does a skill send to debug an app on a simulator?

A skill sends a JSON request specifying "server": "xcodebuildmcp", "workflow": "debugging", and a payload object containing the Xcode scheme name and target device identifier, such as {"scheme": "MyApp", "device": "iPhone 15"}. The xcodebuildmcp server processes this request by building the scheme, launching the specified simulator, attaching the debugger, and streaming logs back to the skill.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}