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

> Learn how the build-ios-apps plugin integrates XcodeBuildMCP for simulator debugging. Explore the .mcp.json file and enable iOS debugger workflows via the Codex MCP client library.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-20

---

**The build-ios-apps plugin integrates XcodeBuildMCP for simulator debugging by declaring an MCP server in [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.mcp.json)

The integration anchor is [`plugins/build-ios-apps/.mcp.json`](https://github.com/openai/plugins/blob/main/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:

```json
{
  "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:

```python

# 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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.codex-plugin/plugin.json) to validate the plugin structure
2. Detects [`.mcp.json`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.mcp.json) declares the server**: Located at [`plugins/build-ios-apps/.mcp.json`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/.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`](https://github.com/openai/plugins/blob/main/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`](https://github.com/openai/plugins/blob/main/plugins/build-ios-apps/.mcp.json): Declares the MCP server command and enabled workflows.
- [`plugins/build-ios-apps/.codex-plugin/plugin.json`](https://github.com/openai/plugins/blob/main/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.