# Control a Capgo simulator

> Instructions for AI agents. Human page: https://capgo.app/simulator/

A Capgo simulator session is one cloud device. iOS sessions expose an MCP server on that device, so you can look at the screen and tap it.

## 1. Start a session

Ask the user for a Capgo API key, or use one already saved by `bunx @capgo/cli@latest login`.

```bash
bunx @capgo/cli@latest simulator start com.example.app --platform ios --json
```

- `data.id` is the Capgo session id. `simulator get` and `simulator stop` need it.
- `data.url` is the viewer URL, shaped `https://ios-emulator.capgo.app/s/<session-id>/`.
- `data.remoteConfig.agentDeviceRemoteSessionToken` is the token for that device. Do not print it in chat logs.

Android sessions do not boot an iOS screen. Use `--platform ios` when you need to tap and screenshot.

A running session uses one native builder slot and build minutes. Stop it when you are done.

## 2. Connect MCP to that session

The MCP URL is the viewer URL with `mcp` added:

`https://ios-emulator.capgo.app/s/<session-id>/mcp`

Streamable HTTP. Send `Authorization: Bearer <agentDeviceRemoteSessionToken>`.

```json
{
  "mcpServers": {
    "capgo-simulator": {
      "type": "http",
      "url": "https://ios-emulator.capgo.app/s/<session-id>/mcp",
      "headers": { "Authorization": "Bearer <session-token>" }
    }
  }
}
```

One session, one MCP server. Start another session when you need another device.

## 3. Tools

- `screenshot`: JPEG of the current screen, plus the artifact path under `/s/<session-id>/`.
- `tap`: `x` and `y` from 0 to 1, or points on a 402 by 874 screen.
- `home`: press Home.
- `lock`: press Lock.
- `open_app`: `bundleId` of an installed app.
- `snapshot`: screen size and one screen node. There is no accessibility tree.

Call `screenshot` after each action before you decide the next tap.

## 4. Stop

```bash
bunx @capgo/cli@latest simulator stop <session-id> com.example.app
```

Stopping ends the device, releases the builder slot, and records build minutes.

## Reference

- Human page: https://capgo.app/simulator/
- Device API: https://ios-emulator.capgo.app/docs/
- Site index: https://capgo.app/llms.txt