MCP: a run_on_device tool runs simctl, adb or devicectl against the session's lease #951

Request: #949

Problem

The MCP server has four tools: list_devices, lease_simulator, release_simulator, lease_status. None of them touches the device. After lease_simulator, an agent on MCP still drops into its shell, runs simlock simctl install <UDID> …, and copies the UDID out of the tool result into every command. The docs say so: "The MCP tools lease and release devices. They do not run commands on the device" (getting-started/connect-your-agent.mdx).

The same copying hits every device.exec caller (HTTP, gateway, client): for simctl and an emulator's adb, the arguments must name the device. Nothing stops an agent that copies the wrong id, or uses booted, from driving another agent's simulator.

Who it is for

A coding agent that reaches Simlock only through MCP (agent-device first, then any MCP client), on one machine or through simlock --gateway mcp. Second: any agent calling POST /v1/leases/{id}/exec over HTTP, the client's exec, or simlock --gateway simctl|adb.

Outcome

• An agent on MCP alone installs, launches and inspects an app on its leased device without a shell and without ever passing a device id.
• Every device.exec caller may leave the device out of simctl, adb and devicectl commands; Simlock fills in the lease's device.
• A command that names a different device than the lease's is refused before it runs, with a message naming both.

How it works for the user

sequenceDiagram
  participant A as Agent
  participant M as simlock mcp
  participant W as Worker (or gateway → worker)
  A->>M: lease_simulator {platform: ios}
  M-->>A: grant
  A->>M: run_on_device {tool: simctl, args: [install, /builds/App.app]}
  M->>W: device.exec on the session's lease
  alt refused (names another device, refused verb)
    W-->>M: PASSTHROUGH_REFUSED
    M-->>A: isError {code, message}
  else no lease held
    M-->>A: isError {code: NO_LEASE, message}
  else runs
    W-->>M: output chunks, exit code
    M-->>A: {exitCode, stdout, stderr, truncated}
  end

Before, over MCP:

lease_simulator {"platform":"ios"}            → {"device":{"driverDeviceId":"6F1D…3C90",…},…}
(shell) simlock simctl install 6F1D…3C90 /builds/App.app

After:

run_on_device {"tool":"simctl","args":["install","/builds/App.app"]}
→ {"exitCode":0,"stdout":"","stderr":"","truncated":false}

run_on_device {"tool":"simctl","args":["install","booted","/builds/App.app"]}
→ isError {"code":"PASSTHROUGH_REFUSED","message":"Refusing `simctl install booted /builds/App.app`: it names device booted, and this lease holds 6F1D…3C90. Leave the device out; Simlock fills it in."}

run_on_device {"tool":"adb","args":["shell","getprop","ro.build.version.sdk"]}   (before any lease)
→ isError {"code":"NO_LEASE","message":"This MCP session holds no lease. Call lease_simulator first."}

Examples

device.exec arguments on an iOS simulator lease (UDID 6F1D…3C90) and an emulator lease (serial emulator-5554):

What could go wrong

• A simctl verb Simlock does not know (a new Xcode) gets no device filled in, so simctl fails asking for one. The agent can still name its own UDID. Likely only after an Xcode release.
• A long command's output is cut to its last part, so an agent misses an early line. Visible as truncated: true.
• Through a gateway whose workers run mixed versions, a command that leaves the device out fails on workers older than this change.
• An HTTP caller that sends booted today, against the docs' advice, is now refused. So is one that names its own device by a simctl name, a devicectl ECID or name, or adb -t: only the UDID or serial passes.
• A command that prints nothing for a long time (a big simctl install) can outrun an MCP client's tool timeout. Simlock sends a progress notice every 10 s while it runs, which helps only clients that reset their timer on progress.

Words used

• lease's device: the one device a lease holds; on iOS its UDID (6F1D2A8C-3B4E-4F7A-9C2D-8E5B1A7F3C90), on an emulator its adb serial (emulator-5554), on an Android phone its USB serial.
• fill in: Simlock inserts the lease's device into the command where the tool expects it, e.g. install App.app → install <udid> App.app.
• device verb (simctl): a subcommand whose first operand is a device, e.g. install, launch, io; list and runtime are not.
• refused: answered PASSTHROUGH_REFUSED before any process starts.
• truncated: the tool result kept only the last 32 768 characters of a stream.

Non-goals

• Returning files or binary output to the agent (a screenshot as an image). Follow-up.
• Uploading an app from the agent's machine to the worker.
• simlock simctl / simlock adb on a worker scoped to the lease (simlock simctl and simlock adb on a worker run only against the caller's lease, and fill the device in #948 reuses this feature's driver rule).
• Writing the instructions text (Add simlock instructions: the rules an agent must follow, printable and served over MCP #147); MCP: run_on_device runs a command on the session's lease #959 only updates its MCP section to name the new tool.
• Cancelling a running command from MCP.

Completion conditions

• Over MCP, an agent with a lease runs simctl install, simctl launch and adb shell through run_on_device without passing a device id, and gets stdout, stderr and the exit code.
• POST /v1/leases/{id}/exec with {"tool":"simctl","args":["install","/builds/App.app"]} installs on the lease's device; with booted it answers 422 PASSTHROUGH_REFUSED.
• run_on_device without a lease answers NO_LEASE.
• The website's MCP and remote-agents pages describe both.

Open questions

Decisions

• ADR 0047 — device.exec fills in the lease's device, and refuses another (PR docs(adr): 0047 device.exec fills in the lease's device, and refuses another (#951) #955): the drivers own where the device goes per tool and verb; every device.exec caller gets it; no contract change.
• ADR 0047 §6: run_on_device runs outside the session's tool-call queue (narrows ADR 0003 §11).
• Interview 2026-10-23: one tool result with stdout, stderr, exitCode and a cap, not output streamed in progress messages; a refusal is isError with {code, message} like the other four tools; a non-zero exit code is a normal result; file-returning output is a follow-up.

Shared values

Behaviours

Tasks

flowchart LR
  ADR[ADR 0047, PR #955] --> T1[#958: drivers fill in the device on device.exec]
  T1 --> T2[#959: MCP run_on_device]

• device.exec fills in the lease's device and refuses another #958 device.exec fills in the lease's device and refuses another — a device.exec caller leaves the device out. Risk: a command lands on the wrong spot in the arguments and simctl or adb fails.
• MCP: run_on_device runs a command on the session's lease #959 MCP run_on_device — an agent on MCP runs device commands without a shell. Risk: output cut too short, or a call that waits behind another.

Completion conditions: the first and third → #959; the second → #958; the fourth → #958 (remote-agents page) and #959 (MCP pages).

Open work in the same area:

• simlock simctl and simlock adb on a worker run only against the caller's lease, and fill the device in #948 (simlock simctl/adb on a worker scoped to the lease): reuses ADR 0047's driver rule by passing a device to driver.passthrough. Should depend on device.exec fills in the lease's device and refuses another #958; not edited here (another feature's body).
• Add simlock instructions: the rules an agent must follow, printable and served over MCP #147 (instructions text, re-specified in a parallel session): its body changes createMcpServer in src/mcp/server.ts, as MCP: run_on_device runs a command on the session's lease #959 does, so MCP: run_on_device runs a command on the session's lease #959 Depends on Add simlock instructions: the rules an agent must follow, printable and served over MCP #147. MCP: run_on_device runs a command on the session's lease #959 updates the MCP section of Add simlock instructions: the rules an agent must follow, printable and served over MCP #147's text to name run_on_device.
• simlock run holds a lease around one command, and a detached lease follows the agent process #944 (simlock run): separate; no shared code.
• PR docs(adr): 0045 a device's screen streams to operators, not a lease's (#906) #908 (ADR 0045) and PR docs(adr): 0046 a standalone worker serves agent-device by default with a private profile #954 (ADR 0046, agent-device on the same Mac works with no operator step #952): ADR numbering only; this feature takes 0047.
• Add simlock instructions: the rules an agent must follow, printable and served over MCP #147 also changes the driver refusal code device.exec fills in the lease's device and refuses another #958 changes (src/drivers/ios/index.ts:134-138, #assertProxyable; src/drivers/android/index.ts:289), so device.exec fills in the lease's device and refuses another #958 Depends on Add simlock instructions: the rules an agent must follow, printable and served over MCP #147 too.
• PR fix(http): an Android lease over HTTP names its adb serial as address #953 (Android lease over HTTP names its adb serial as address, ready): rewrites the serial-lookup bullet of remote-agents.mdx that device.exec fills in the lease's device and refuses another #958 removes. device.exec fills in the lease's device and refuses another #958 Depends on fix(http): an Android lease over HTTP names its adb serial as address #953.
• PR fix(daemon): exec children get a minimal environment; docs say what an agent token can do #891 (exec children get a minimal environment, draft): edits #deviceExec and the same remote-agents.mdx section. device.exec fills in the lease's device and refuses another #958 changes only a comment in #deviceExec; no Depends on: whichever merges second takes the other's text when it rebases, and fix(daemon): exec children get a minimal environment; docs say what an agent token can do #891 is a draft with no ready task.

Written by an agent.