iOS MCP routing (Argent vs XcodeBuildMCP)

Decide the primary tool by task class. Prefer one owner per phase. Combine only at clean handoff points (usually: XcodeBuildMCP builds → Argent verifies).

0. Availability check (once per session)

1. XcodeBuildMCP — MCP tools present (XcodeBuildMCP__*) and/or command -v xcodebuildmcp.
2. Argent — MCP tools present (argent__*) and/or command -v argent.
3. If only one is available, use it within its strengths; do not invent the missing one.
4. If neither is available, fall back to shell (xcodebuild, xcrun simctl, adb) and say so.

Load this skill before defaulting to either stack for Apple platform work.

1. One-line rule

2. Decision tree

What is the bottleneck / goal?
│
├─ Does it need a successful Xcode/SwiftPM build or XCTest run?
│  └─ YES → XcodeBuildMCP (session defaults → build / test / build_run_sim)
│
├─ Is the app already installed and the task is "use / verify the product"?
│  └─ YES → Argent (list-devices → launch-app → describe → interact)
│
├─ Compile/link/signing failure?
│  └─ XcodeBuildMCP only (fix build; do not start Argent UI loops)
│
├─ Runtime crash / wrong UI / flow / visual regression?
│  └─ Prefer Argent for interaction + evidence
│     (optional: XcodeBuildMCP log capture / LLDB if you need native stack)
│
├─ Android, Chromium/Electron, Fire TV / Apple TV remote, RN Metro inspect?
│  └─ Argent only (XcodeBuildMCP does not own these)
│
└─ Physical iOS device install/run/test, or macOS app?
   └─ XcodeBuildMCP (Argent iOS path is simulator-first)

3. Capability map (what each owns)

XcodeBuildMCP — build system + Apple toolchain

Owns:

• Project discovery: discover_projs, list_schemes, show_build_settings
• Session defaults: session_show_defaults / session_set_defaults (required before first build/run/test)
• Simulator: build, build_run_sim, test_sim, install_app_sim, launch_app_sim, stop_app_sim, boot_sim, open_sim, list_sims
• Clean / app path / bundle id extraction
• Physical device and macOS build/run/test
• SwiftPM build/test/run
• LLDB: attach, breakpoints, stack, variables, continue/detach
• Code coverage from xcresult
• Sim management extras: erase, location, appearance, status bar, video record
• Built-in UI automation via elementRef (snapshot_ui → tap / type_text / swipe / wait_for_ui / batch)

Does not own (or is weak for):

• Android / Chromium / Vega
• Permission grant/deny/reset without Settings UI
• Screenshot pixel-diff workflows, record/replay flows
• React Native Metro component tree / JS eval
• Native Instruments/Perfetto-style profiling pipelines Argent provides
• Cross-app system AX for arbitrary foreground content as rich as Argent describe (Argent is preferred for agent QA loops)

Mandatory session habit: before first build/run/test call, session_show_defaults. If project/scheme/simulator missing, set them. Prefer build_run_sim over separate build+install+launch unless you need a compile-only check.

Argent — device runtime, interaction, QA

Owns:

• Multi-platform device inventory: list-devices (iOS sim, Android emu/device, Chromium CDP, Vega)
• Boot/launch/restart/reinstall: boot-device, launch-app, restart-app, reinstall-app
• Discovery: describe (AX/DOM), native-describe-screen (iOS UIKit), RN debugger-component-tree
• Interaction: gestures, keyboard (incl. secret placeholders), hardware buttons, deep links (open-url)
• Waiting: await-ui-element, await-screen-idle
• Evidence: screenshot, screenshot-diff
• Setup: settings-permissions
• Automation reuse: flow record/execute (.argent/flows/)
• Profiling: native profiler (+ RN profiler when RN)
• TV: tv-remote + focus-oriented describe

Does not own:

• Xcode scheme builds, clean, XCTest orchestration, coverage reports
• LLDB source-level debugging of native binaries
• Guaranteed physical-iOS parity (treat Argent iOS as simulator-first)
• Replacing pnpm ios:prepare / XcodeGen / Fastlane release pipelines

Mandatory interaction habit: never guess tap coordinates from a screenshot alone — always discover (describe / native / RN tree) first. Prefer launch-app over home-screen icon taps.

Overlap zone (pick one primary)

Both can: boot a sim, launch an installed app, screenshot, basic tap/type.

Do not interleave Argent gestures and XcodeBuildMCP snapshot_ui/tap on the same screen without a deliberate refresh — elementRefs and coordinate spaces are stack-specific. Finish one automation style, then switch only at a stable boundary (e.g. after navigation settle).

4. When to combine in one session

Pattern A — implement → build → UI verify (most common)

1. Edit code.
2. XcodeBuildMCP: session_show_defaults → fix defaults → build_run_sim (or build if install not needed).
3. On build failure: stay on XcodeBuildMCP until green. Do not open Argent yet.
4. On success: note simulator UDID/name and bundle id from defaults / get_app_bundle_id.
5. Argent: list-devices → same UDID → describe / interact / screenshot / optional screenshot-diff.
6. If UI wrong → fix code → return to step 2 (rebuild). If only JS/web content in a hybrid shell and no native rebuild needed, relaunch/reload as the project requires, then Argent again.

Pattern B — compile-only gate, then manual QA later

1. XcodeBuildMCP build (simulator, no launch).
2. Later Argent session for QA against an already-installed build (or reinstall via Argent reinstall-app using get_sim_app_path / known .app path).

Pattern C — crash / native bug

1. Reproduce with Argent (or XcodeBuildMCP UI) to get to the crash.
2. Attach XcodeBuildMCP LLDB (debug_attach_sim, breakpoints, stack, variables).
3. After fix: XcodeBuildMCP rebuild; Argent re-verify the flow.

Pattern D — test suite + exploratory QA

1. XcodeBuildMCP test_sim for automated tests / coverage.
2. Argent for scenarios tests do not cover (permissions matrix, visual diff, multi-step product flows).

Pattern E — hybrid monorepo (native host + web/miniapps)

1. Native host changes → XcodeBuildMCP build/run.
2. In-app UX / miniapp surface → Argent describe + screenshots (WKWebView content may be sparse in AX; use screenshot + careful discovery).
3. Pure web package work → not these tools (web browser tooling / project web scripts).

5. Shared identifiers (handoff contract)

When combining tools, pass these explicitly between phases:

Prefer one booted simulator for the whole session. If XcodeBuildMCP boots sim A and Argent boots sim B, launches and UI state diverge.

6. Anti-patterns

1. Argent for compile errors — it will not fix or surface xcodebuild diagnostics; use XcodeBuildMCP.
2. XcodeBuildMCP as the only tool for multi-step product QA when Argent is available — weaker flows, no screenshot-diff/permissions/Android.
3. Building with raw xcodebuild/simctl when XcodeBuildMCP is connected — prefer MCP session defaults (skill: xcodebuildmcp-cli).
4. Tapping from screenshots with either stack when a discovery API exists.
5. Starting Argent UI work before the new binary is installed after native code changes — rebuild first.
6. Assuming the repo is React Native because Argent has RN skills — detect project type; native-only hosts skip Metro/debugger-component-tree.
7. Mixing elementRef taps and Argent coordinate taps mid-flow without re-discovering.
8. Physical device QA defaulting to Argent — use XcodeBuildMCP device workflow unless Argent explicitly supports the target in this environment.

7. Suggested skill handoff

After choosing the primary tool, load the specialized skill (do not re-encode their full procedures here):

8. Quick recipes

"Build the iOS app"

XcodeBuildMCP only → defaults → build or build_run_sim.

"Is the new button on screen / does the menu work?"

If binary current: Argent only. If you just changed native UI code: XcodeBuildMCP build_run_sim, then Argent QA.

"XCTest failed"

XcodeBuildMCP test_sim (and logs/coverage). Use Argent only if you need to reproduce a manual path the test does not cover.

"Need Android or webview Electron too"

Argent. XcodeBuildMCP is out of scope.

"LLDB breakpoint in Swift"

XcodeBuildMCP debugging workflow. Argent does not replace LLDB.

9. Exit criteria

Before acting, state (internally or briefly to the user when ambiguous):

1. Primary tool for this step: Argent | XcodeBuildMCP | both (ordered).
2. Why (one sentence from the decision tree).
3. Handoff tokens if both: UDID, bundle id, scheme.
4. Specialized skill loaded next.

If the user already named a tool, honor that unless it is impossible (e.g. "Argent build my scheme" → explain and use XcodeBuildMCP for build).

References

• Capability detail and edge cases: references/capability-matrix.md