MCP Skills

Your AI agent learns the whole lab before it touches a phone

When Claude, Cursor or any MCP client connects to HoP, it is first told what HoP is and the rules for using real, shared devices. Then it reads the skill for its task. These are those 12 skills, word for word.

1 · ON CONNECT

The primer

The MCP instructions: what HoP is, five rules, the usual loop, and the list of skills.

2 · FIRST CALL

get_skill name=about-hop

The first tool in the list. Without a name it lists the skills; with one it returns that guide.

3 · PER TASK

The right skill

Testing, debugging, flows, settings, performance, files, suites, iPhone, browsers and TVs. Also as resources hop://skills/<id>.

Connect an agent (create the API key in Settings › API keys; Settings › AI agents shows the snippet for your client):

claude mcp add --transport http hop https://lab.yourco.in/mcp --header "Authorization: Bearer dl_…"
initialize → instructions

What every agent is told on connect

MCP clients put this into the agent's context as soon as it connects, before any tool call. It ends with the list of skills below.

HoP (Hall of Phones) is a lab of REAL devices that you can use completely through these tools: Android phones and tablets, iPhones and iPads, Android TV boxes and desktop browsers (Chrome, Edge, Safari, Firefox …), in one or more offices that share one device list. You act as the person whose API key connected you: their plan, limits, saved flows and uploads. Every booking is recorded (video, logs, network, crashes) and they can watch it.

Before your first task, call get_skill name=about-hop (what HoP is, how booking works, what each device supports, what you may and may not do). Before a task, read the skill for it: get_skill with no name lists them.

Rules:
1. Book a device (book_device) before using it; it is yours alone until release_device. Always release every device when you are done; idle bookings end after 15 min (idle_minutes) but use the person's minutes until then.
2. The devices are shared and some have real SIMs and accounts. Stay inside the task: no sign-outs, security or lock-screen changes, calls, SMS, purchases or deleting files you didn't create, unless the person asked for exactly that.
3. Never put real passwords or card numbers in flows; use ${placeholders} and pass params at run time.
4. Read the screen with get_screen (elements you can tap by text or id); every action returns the new screen. Use screenshot only for visual checks.
5. Report what you saw with evidence (screen text, log lines, crash, request, recording links). Don't claim something works without checking.

Typical loop: list_devices → book_device → install_app / launch_app / open_url → get_screen → tap / type_text / swipe / press_key → get_logs / get_crashes / get_network → save_flow → release_device → get_session_files.

Skills (get_skill name=<id>, or resource hop://skills/<id>):
- about-hop: Read this first, before any other tool. What HoP is, the devices, how booking works, what you are allowed to do, and which skill to read next.
- book-and-drive: Picking a device, booking it, reading the screen and acting on it (tap, type, swipe, keys, waiting).
- test-an-app: You are asked to test an app, a build or a feature on a real phone and report what works and what breaks.
- debug-an-issue: Something is broken (crash, wrong data, blank screen, failed request, slow screen) and you need the cause with evidence.
- flows: The work should be repeatable: save a journey, record one, run it on one or many phones, fix broken selectors, export a script. Also the full flow step reference.
- phone-conditions: The test needs a condition: battery, dark mode, font size, language, time zone, permissions, network speed, location, camera image, fingerprint answer, accessibility check.
- performance-and-media: Questions about speed: CPU, memory, frame rate, jank, launch time, data used, battery; comparing two builds; frozen video, black frames or sound drop-outs.
- files: Reading, downloading, creating, uploading, moving or deleting files on the phone's storage or inside an app's private data.
- test-suites-and-ci: Running Espresso / instrumentation or XCUITest suites on many phones, pointing Appium at the lab, PDF reports, pass rates and flaky tests.
- iphone: The device is an iPhone or iPad: what works, what doesn't, and how to install your app.
- browsers-and-tvs: The device is a desktop browser (Chrome, Edge, Brave, Chromium, Safari, Firefox) or an Android TV / Google TV box.
- results-and-sharing: Handing results to a person: recording links, PDF reports, a live phone link, usage and plan limits, the audit log (admins).
get_skill name=about-hophop://skills/about-hop

About HoP

Read it when: Read this first, before any other tool. What HoP is, the devices, how booking works, what you are allowed to do, and which skill to read next.

HoP is a lab of real devices that people and AI agents use remotely: Android phones and tablets, iPhones and iPads, Android TV / Google TV boxes, and desktop browsers (Chrome, Edge, Brave, Chromium, Safari, Firefox) running on the lab's machines. The devices sit in one or more offices ("hubs"). Every hub shows every hub's devices, so you see one list. Nothing here is an emulator unless list_devices says so.

You reach the whole lab through this MCP server. You act as the person whose API key connected you: their plan, their limits, their saved flows and uploads. Everything you do is recorded and shown to them.

The devices are real and shared

  • A device you book is yours alone. Nobody else can use it until you release it.
  • Other people use the same phones. Some phones have a real SIM card and real accounts on them.
  • When you release a phone, the apps you installed are removed and the phone is reset for the next person.
  • Each booking is recorded: screen video, device log, actions, network traffic and crashes. get_session_files gives the links afterwards.

Rules for agents

  1. Release every device when you are done (release_device). A booking you forget ends by itself after idle_minutes without tool calls (default 15, up to 120), but it uses the person's device minutes until then.
  2. Book only as many devices as the task needs. get_account shows the plan's limits (device minutes per month, devices at the same time, AI goals).
  3. Stay inside the task. Don't sign out of accounts on a phone, change its lock screen or security settings, make calls, send SMS, buy anything or delete files you didn't create, unless the person asked for exactly that.
  4. Never put real passwords or card numbers into a flow. Use ${placeholders} and pass values at run time.
  5. Prefer reading the screen as elements (get_screen) to screenshots. It is cheaper and lets you tap by text or id.
  6. When something fails, say what you saw and give evidence (screen text, log lines, crash, screenshot file). Don't guess that it worked.

How a session goes

list_devices → book_device → (install_app / launch_app / open_url)
  → get_screen → tap / type_text / swipe / press_key → (each returns the new screen)
  → check: get_logs, get_crashes, get_network, get_performance …
  → save what worked: save_flow (reusable on any phone)
  → release_device → get_session_files (video, logs) for the person

Ids you will see

  • session_id: one booking, from book_device. Optional in most tools when you hold exactly one device.
  • serial / UDID: a device, from list_devices. A device on another hub looks like hub~serial; use it the same way.
  • upload_id: an app or test file stored in the account (upload_app, list_uploads).
  • flow / run_id: a saved flow and one run of it (list_flows, run_flow).

What each kind of device supports

AndroidiPhone / iPadDesktop browserAndroid TV
Screen as elements, tap, type, swipe, keysyesyesyes (DOM elements)yes (D-pad keys)
Install appsAPKsigned .ipa—APK
Device log, crashesyesyesconsole logyes
Network capture, 2G/3G/offlineyesbuilt, not yet confirmedin the recording (Chrome)yes
Chrome / WebView traffic and HTMLyes—in the recording (Chrome)yes
App databases, adb shellyes——yes
Filesstorage + debuggable appsyour team's apps—yes
Performance timelineyesyes (Instruments)—yes
Camera image, fingerprint answersyes (SDK)camera (SDK)——
Flows, quick commandsyesyesflowsyes

Skills (read with get_skill)

SkillRead it when
book-and-driveyou need to pick, book and control a device
test-an-appyou are asked to test an app or a feature end to end
debug-an-issuesomething is broken and you need the cause
flowsthe work should be repeatable: record, save, run on many phones, self-heal
phone-conditionsthe test needs a setting: battery, dark mode, network, location, permissions, camera, fingerprint, accessibility
performance-and-mediaspeed, memory, frame rate, launch time, video or sound quality
filesyou need files on the phone or inside an app's data
test-suites-and-ciEspresso / XCUITest suites, Appium, PDF reports, CI
iphonethe device is an iPhone or iPad
browsers-and-tvsthe device is a desktop browser or an Android TV
results-and-sharingyou need to hand results, recordings or a live phone to a person

If the lab owner turned it on, run_goal lets HoP's own AI agent do a task on a phone you hold. You can always do the same yourself with the tools above.

get_skill name=book-and-drivehop://skills/book-and-drive

Book and drive a device

Read it when: Picking a device, booking it, reading the screen and acting on it (tap, type, swipe, keys, waiting).

1. Pick a device

list_devices lists every device on every hub: platform, model, OS version, free or held by whom, where it is (city, country), and for phones the SIM: carrier, Wi-Fi or mobile data, 2G–5G and signal. Filters: platform (android, ios, desktop), available_only, country, city, carrier (none = no SIM).

2. Book it

book_device gives you a session_id. Choose one way:

  • a specific device: serial (from list_devices);
  • or let the lab choose: platform, model (part of the name, e.g. pixel, iPhone 14), os_version (prefix, e.g. 13, 17.4), country, city, carrier, form_factor (tv or phone), browser (a desktop browser).

wait_seconds (default 60, max 1800) waits for one to become free. idle_minutes (default 15, max 120) is how long the booking survives without tool calls. You can hold several devices at once (up to the plan's limit); pass session_id to every tool when you do. my_sessions lists what you hold.

3. Read the screen

get_screen returns the screen size, the app in front, then the elements, one per line:

screen 1080x2400 android app=com.example.shop
[3] Button "Log in" id=login_button (clickable) @0.500,0.820
[7] EditText desc="Email" id=email (clickable,editable,focused) @0.500,0.410

[3] is the index, then the type, text, desc (label, when it differs from the text), id, flags (clickable, editable, scrollable, checked, selected, focused, disabled) and the centre as fractions of the screen (0..1). Use all=true to include layout-only elements and screenshot=true to also get the picture. screenshot alone returns a JPEG (max_side 256–2048). Use screenshots for visual checks (layout, colours, images); use elements to act.

4. Act

Every action returns the new screen (turn off with return_screen=false; settle_ms waits before reading it back, default 700). Targets, in order of preference:

  1. text (exact, case-insensitive) or contains (part of the text);
  2. id (Android resource-id, iOS accessibility identifier) or desc (content-desc / accessibility label);
  3. index from the last get_screen;
  4. x, y as fractions 0..1 (or pixels if > 1), only when the element has no text or id.
ToolDoes
taptaps an element or point; waits up to 8 s for the element; heal=true taps the closest match if none is exact
long_presspress and hold (ms, default 900)
type_texttypes text into the focused field, or first taps the field given by into_text / into_id / into_index …; clear=true empties it first, submit=true presses Enter after
swipedirection up / down / left / right (up = finger moves up = content scrolls down), or x1,y1 → x2,y2; ms
scroll_toswipes until an element with that text / contains / id / desc appears (12 swipes at most)
press_keyBACK, HOME, RECENTS, ENTER, DEL, TAB, ESCAPE, POWER, VOLUME_UP / DOWN, MENU, DPAD_* (iPhone: HOME, VOLUME_UP, VOLUME_DOWN, ENTER)
wait_forwaits until an element appears, or disappears with gone=true (timeout_seconds, default 15)

5. Apps and links

  • install_app from an upload_id, a url or base64: APK on Android, signed .ipa on iPhone. It returns the package / bundle id. upload_app stores a file in the account first, so it can be reused (list_uploads).
  • launch_app, stop_app, uninstall_app, clear_app_data (Android), list_apps (also shows the app in front).
  • open_url opens a web page or a deep link (myapp://…).

6. Finish

release_device ends the booking, removes the apps you installed and resets the phone. The recording stays: get_session_files session_id=….

Tips

  • Read the screen after each step and check that it changed the way you expected before going on.
  • If an element isn't found, call get_screen all=true, try contains, or scroll with scroll_to.
  • System dialogs (permissions, keyboards) are on the screen like any element: tap them by text.
  • When you hold one device you can leave out session_id; with several, always pass it.
get_skill name=test-an-apphop://skills/test-an-app

Test an app end to end

Read it when: You are asked to test an app, a build or a feature on a real phone and report what works and what breaks.

The prompt test_app (arguments app, goal, platform) starts the same routine.

1. Get the build on a phone

  1. book_device with the platform the person asked for (or any free phone).
  2. Is the app already there? list_apps. If not: install_app upload_id=…; or install_app url=… directly.
    • upload_app with a url (or base64) and a name that keeps the extension (app-debug.apk, MyApp.ipa), then
    • iPhone: the .ipa must be signed for that iPhone (development or ad-hoc profile with its UDID, or enterprise).
  3. launch_app app=<package or bundle id> (the id is in the install_app reply).

Start from a clean state when the test needs it: clear_app_data (Android), or uninstall and install again (iPhone).

2. Do the journey

Work in small steps: get_screen, act with tap / type_text / swipe by text or id, read the new screen, check it. For each check, write down what you expected and what the screen shows.

Use test data only: test accounts the person gave you, or values from their test fixtures. Never use a real password or card. If a login needs a code sent to a real person, stop and ask.

3. Check what the user can't see

At the end, and whenever something looks wrong:

  • get_crashes: crashes, ANRs and native crashes (iPhone: crash reports, watchdog and out-of-memory kills).
  • get_logs grep=<package or tag>: errors and warnings. Keep next_offset and pass it as offset next time to read only new lines.
  • get_network contains=<api host>: failed requests (status 4xx / 5xx, slow ones).
  • get_web_requests for screens that are web pages inside the app (Chrome tabs and debuggable WebViews, Android).
  • accessibility_scan on key screens (missing labels, small targets, low contrast).
  • get_performance if the app felt slow (launch time, frame rate, memory).

4. Try the edges

phone-conditions covers them: slow or no network (set_network EDGE / OFFLINE), another location (set_location), dark mode, a big font, low battery, a different language or time zone (run_quick_command), a QR code or document in front of the camera (inject_camera_image), a fingerprint prompt (biometric), another screen size (book a second phone).

5. Make it repeatable

Save the journey that worked with save_flow (see flows), run it once with run_flow on the same phone to prove it replays, and say which other phones it could run on.

6. Report

For each problem: what you did (steps), what you expected, what happened, and the evidence: screen text, the log lines, the crash title, the request that failed, a screenshot. Mention the phone, OS version and app version. Add the recording links from get_session_files and, for a written report, get_report_pdf session_id=….

Then release_device.

get_skill name=debug-an-issuehop://skills/debug-an-issue

Debug an issue

Read it when: Something is broken (crash, wrong data, blank screen, failed request, slow screen) and you need the cause with evidence.

1. Reproduce it

Book the kind of phone where it happens (book_device by model, os_version, carrier, city), install the same build and repeat the steps. Note the time you start, so the log lines are easy to find.

2. Read the evidence

QuestionTool
Did it crash or freeze?get_crashes: Java crashes, ANRs, native crashes; iPhone crash reports, watchdog and out-of-memory kills, with stack traces
What did the app log?get_logs (logcat on Android, syslog on iPhone). grep is a case-insensitive regex, max_lines up to 2000; pass the returned next_offset as offset to read only new lines
Did a request fail?get_network (requests through the lab proxy: method, status, URL, size, time; HTTPS shows host and bytes)
What did a web page or WebView load?get_web_requests (Chrome and debuggable WebViews, HTTPS included) → get_response_body request_id=…; get_page_html for the rendered HTML (refresh=true snapshots open pages now)
What is stored in the app?inspect_app_data: without app it lists debuggable apps; with app its SQLite databases and SharedPreferences; db + sql runs a query on a copy; prefs reads a prefs file
What files did it write?list_files app=<package> / read_file (see files)
Is it slow?get_performance (CPU, memory, threads, fps, janky frames, launch time, network, battery)
Is the phone in an odd state?run_quick_command checks (memory, frame stats, crash logs, settings) or shell on Android

Web traffic, app data and shell are Android only. On an iPhone, use the log, crash reports, files of your team's apps and the performance timeline.

3. Narrow it down

Change one thing at a time and repeat: another network (set_network), another phone or OS version, a clean install (clear_app_data), another account. A flow (run_flow on several phones with count) shows quickly on which phones it fails.

4. Report the cause

Give: the steps, the phone and OS, the first error in the log or the crash title with the top of its stack, the request and its status if the network is involved, and what you think the cause is (say how sure you are). Attach get_session_files links so a developer can watch the video next to the log.

Keep shell read-only unless the person asked for a change: no rm, no settings changes, no pm uninstall of apps you didn't install.

get_skill name=flowshop://skills/flows

Flows (save, replay, self-heal)

Read it when: The work should be repeatable: save a journey, record one, run it on one or many phones, fix broken selectors, export a script. Also the full flow step reference.

A flow is a saved list of steps in the person's account (shared with their team). Steps find elements by text or id, not pixels, so one flow runs on any Android phone or iPhone with the app. Flows are versioned.

Make one

  • Write it after you got a journey working by hand: save_flow with name, steps (JSON array), optional description, platform (any, android, ios), app, params (default values), tags. Same name or flow_id updates it (new version).
  • Record it: start_recording, then drive the phone (you, or a person on the live screen), then stop_recording save_as=<name>. Taps are saved as element selectors.
  • Try one step before saving it: run_step step={…} on the phone you hold.
  • Put credentials and test data in ${placeholders}: "text": "${email}", and pass params at run time.

Run it

run_flow flow=<id or name> and one of:

  • session_id: on the phone you hold (it stays booked);
  • devices: a list of serials / UDIDs;
  • count: on N free phones in parallel (0 = all free phones), optionally only platform android or ios.

Other options: params, screenshots (each, failure = default, none), heal (default true), wait_seconds (default 600; 0 returns at once with a run_id for get_flow_run). The reply has a result per step and per phone; failing steps name a screenshot file.

list_flows, get_flow (format=python exports a script), list_flow_runs, delete_flow.

Self-healing

When a selector no longer matches (a button was renamed or moved), the run taps the closest element and marks the step HEALED. If the healed steps are right, heal_flow run_id=… saves them into the flow as a new version.

The prompt regression_on_all_phones (argument flow) runs a flow everywhere and summarises failures per phone.

Step reference

A flow is a list of steps. Targets (target) find an element; every field set must match (text is case-insensitive): {"text": "Log in"} · {"contains": "Log"} · {"id": "login_button"} · {"desc": "Search"} · {"cls": "EditText", "nth": 1}. Add "x" / "y" (fractions 0..1) as a fallback point. Strings may use ${param} placeholders, filled from run params.

actionfields
launch / stop_app / clear_appapp (package or bundle id)
installapp = upload id
open_urlurl (web or deep link)
tap / long_presstarget or x, y; long_press: ms
typetext, optional target (tapped first)
clear_textoptional target
swipedirection up / down / left / right, or x, y, x2, y2; ms
scroll_totarget, direction (default up)
key / back / homekey: BACK, HOME, ENTER, DEL, TAB, …
waitms
wait_for / wait_gonetarget, timeoutMs
assert_visible / assert_not_visibletarget, timeoutMs
assert_texttarget, text (must contain)
screenshotname
shellcommand (Android)
set_locationlat, lng
set_networkprofile NONE / WIFI / LTE / HSPA / EDGE / OFFLINE

Every step may set "optional": true (a failure doesn't fail the run) and "note".

[{"action":"launch","app":"lab.hop.sample"},
 {"action":"tap","target":{"text":"Database"}},
 {"action":"assert_visible","target":{"contains":"note"}},
 {"action":"type","target":{"id":"email"},"text":"${email}"},
 {"action":"key","key":"ENTER"},
 {"action":"screenshot","name":"done"}]

Good flows

  • Start with launch (and clear_app when the journey needs a fresh state).
  • After each important step, assert something the user would see (assert_visible, assert_text).
  • Use wait_for instead of fixed wait where you can.
  • Keep platform-specific steps (shell, clear_app) out of flows meant for both Android and iPhone, or mark them optional.
get_skill name=phone-conditionshop://skills/phone-conditions

Phone settings and test conditions

Read it when: The test needs a condition: battery, dark mode, font size, language, time zone, permissions, network speed, location, camera image, fingerprint answer, accessibility check.

Quick commands first

list_quick_commands lists ready-made settings and checks for the booked phone (filter by category or query, e.g. query="battery level"). run_quick_command id=… values={…} runs one; values are checked and quoted for you, and a missing app value means the app on screen. Values are strings; on / off switches take "true" or "false" (anything other than "false" counts as on). Examples:

  • id=bat.level values={"level":"15"}: fake battery level (also charging, battery saver, temperature, Doze);
  • id=disp.dark values={"on":"true"}: dark mode (Android); id=ios.appearance values={"mode":"true"} (iPhone); "false" turns it off;
  • also font size, animations off, TalkBack, colour inversion, Wi-Fi / data / airplane, app language, time zone, permissions, developer overlays, cold-start time, frame stats, memory, crash logs.

Use them instead of shell: they work the same on every phone and are read back to confirm. Settings you change on a phone stay until the booking ends; put them back if the person will keep using the phone.

Network and place

  • set_network profile=…: NONE (normal), WIFI, LTE, HSPA (3G), EDGE (2G), OFFLINE. Goes through the lab proxy.
  • set_location lat=… lng=…: mock GPS.
  • Real networks: phones with SIMs show carrier, network type and signal in list_devices. Book by carrier, city or country to test on a real network in that place.

Camera: make the app see an image

inject_camera_image makes the app's camera see sample (built-in qr, cheque, id_card mock-ups), a QR code made from qr_text, an image from image_base64 / url, a file already on the phone (phone_path) or from the recording (session_file). clear=true gives the real camera back. Needs the HoP Camera SDK in the app's debug build (Android sdk-camera; iPhone the HopCamera Swift Package, development-signed builds). iPhone's built-in QR detection (AVCaptureMetadataOutput) doesn't see injected images.

Fingerprint prompts (Android)

Tap the app's fingerprint button, then biometric result=success (or fail = not recognised, prompt stays open; cancel; lockout). It waits up to wait_seconds for the prompt. queue=true answers the app's next prompt. get_biometric_prompts shows which apps use the HoP Biometrics SDK and what is waiting. Needs sdk-biometrics (LabBiometricPrompt) in a debuggable build. The phone's own fingerprints and security settings are never used.

Accessibility

accessibility_scan checks the current screen, WCAG 2.1 AA-style (Android and iPhone): unlabeled controls and images, touch targets under 48 dp / 44 pt, contrast under 4.5:1, meaningless or duplicate labels, unlabeled fields, controls the screen reader can't reach. Each issue has a rule, WCAG reference, severity, the element (index as in get_screen) and the fix for Android and iOS. app= limits it to one app; screenshot=true returns numbered boxes on the issues. Each scan is saved in the recording. Automated checks find only part of the problems: say so, and suggest a TalkBack / VoiceOver pass for anything important.

get_skill name=performance-and-mediahop://skills/performance-and-media

Performance, video and sound quality

Read it when: Questions about speed: CPU, memory, frame rate, jank, launch time, data used, battery; comparing two builds; frozen video, black frames or sound drop-outs.

The performance timeline

Every booking records the phone once a second: app and phone CPU, memory, threads, frames per second, janky frames, app launch times, network throughput, battery and temperature. iPhone uses Xcode Instruments in chunks of about 10 s (steadiest over USB) and has no janky frames or launch times.

get_performance returns a summary, key events (launches, crashes, network changes) and hot spots. It works on a live booking or a finished one (session_id from the recordings). app= picks the package to summarise (default: the most-used app); samples=N adds the last N raw one-second samples (max 600).

To measure something specific:

  1. For a cold launch: run_quick_command id=perf.coldStart (stops the app, starts it and measures until it shows), or stop_app, launch_app, then get_performance (launch times; Android).
  2. For scrolling or animation: swipe through the screen several times, then read fps and janky frames.
  3. For memory: repeat the journey a few times and see whether memory keeps growing.

Compare two builds

Run the same flow on the same phone model with the old build and with the new build (two bookings), then compare_performance session_a=<old> session_b=<new>. Each measure is marked better, worse or the same. Use the same phone and the same flow, or the comparison means little.

Video and sound quality

get_media_quality session_id=… measures a finished recording with ffmpeg: frozen picture while it was playing, black frames, frame-rate drops, sound drop-outs, clipping and loudness. Each moment comes with the video file and the second in it. The video is final a few seconds after release_device. reference_session= scores this recording against another one with VMAF (useful only when both show the same picture: same flow, same phone).

Sound needs Android 11 or later. iPhones and older Android phones get the picture checks only.

Reporting

Give numbers with the phone and build: "Cold launch 1.9 s on Moto one action (Android 11), was 1.2 s in build 41". For a written report, get_report_pdf session_id=… includes the performance charts.

get_skill name=fileshop://skills/files

Files on the phone

Read it when: Reading, downloading, creating, uploading, moving or deleting files on the phone's storage or inside an app's private data.

Where you can look

list_files with no path and no app shows where to start: the phone's storage folders and the apps whose private data you can open.

  • Android: shared storage (/sdcard, the default), /data/local/tmp and any folder adb can read; with app=<package>, the private data of a debuggable build (paths like files/config.json, shared_prefs/x.xml, databases/app.db; "" = its top folder).
  • iPhone: with app=<bundle id>, the data of apps built by the person's team (development-signed). There is no general phone storage on iPhone, and files can only be listed, found, read, downloaded and uploaded (written over): Apple's device tools can't create folders, move, copy or delete.

Tools

ToolDoes
list_fileslists a folder
find_filesfinds files whose name contains name, 8 folder levels deep, up to 300 matches
read_filetext files come back as text (offset, max_bytes up to 2 MB); images come back as images you can see
download_filea link valid for 15 minutes that needs no key (curl -L -o name '<link>'), plus the file itself up to 5 MB; a folder downloads as .zip
write_filecreates or replaces a file from text or base64; append=true adds to the end
get_upload_linka 15-minute link to upload a file of any size: curl -T local.file '<link>'
make_folder, move_file, copy_fileas named; move and copy fail if the target exists
delete_filedeletes a file or a folder with everything in it, for good (no trash)

For an app's databases, inspect_app_data can run SQL on a copy, which is easier than downloading the .db file.

Care

  • Delete only files you created, or files the person asked you to delete. Top-level folders are refused.
  • Don't write into apps you didn't install for the test.
  • Download links work without a key for 15 minutes: share them only with the person who asked.
get_skill name=test-suites-and-cihop://skills/test-suites-and-ci

Test suites, Appium and CI

Read it when: Running Espresso / instrumentation or XCUITest suites on many phones, pointing Appium at the lab, PDF reports, pass rates and flaky tests.

Espresso / instrumentation (Android)

  1. upload_app the app APK and the androidTest APK (keep the .apk names).
  2. run_tests test_upload_id=<test apk> app_upload_id=<app apk> with count (phones; 0 = all free) or devices, shard=true to split the tests across phones, args for instrumentation arguments (e.g. {"class":"com.app.LoginTest"}).
  3. It waits up to wait_seconds (default 900; 0 returns at once with a run_id). get_test_run run_id=… gives the status and failures.

XCUITest (iPhone)

run_tests platform=ios with test_upload_id = a zip of xcodebuild build-for-testing output (with the .xctestrun file), or the UI-test runner .ipa plus app_upload_id = the app .ipa. only_testing / skip_testing take test ids like MyAppUITests/LoginTests/testOk. Results come from the .xcresult: pass, fail, skipped, screen video, JUnit XML.

Reports

get_report_pdf run_id=… gives a PDF of a test run (summary, pass / fail matrix by phone, failures with screenshots); session_id=… gives one of a recording (phone, duration, performance charts, key events, crashes). It comes back as an embedded PDF and a URL.

Appium and WebDriver

appium_info tells you how to point an Appium client or Appium Inspector at the lab: a hub that books a matching phone per WebDriver session, or the endpoint of a phone you already booked. Auth is the same API key.

Quality over time

get_insights days=…: sessions, minutes, test and flow runs, pass rate, flaky tests, crashes and phone use. Use it to answer "which tests are flaky?" or "are crashes going up?".

In CI

Outside MCP, the same lab has a Python SDK and CLI (hop flow "Checkout" --count 0), a GitHub Actions example and webhooks (Slack, signed generic). Point the person there when they want this on every build. Saved flows (flows) are often the quickest regression suite: no test code, and they run on Android and iPhone.

get_skill name=iphonehop://skills/iphone

iPhone and iPad

Read it when: The device is an iPhone or iPad: what works, what doesn't, and how to install your app.

iPhones are in the same list and use the same tools as Android phones. The lab drives them through Apple's own tools (WebDriverAgent / XCUITest and devicectl), with no root or jailbreak. Lab iPhones have no passcode.

Install your app

iPhones only run apps signed for them. The .ipa must be signed for that iPhone: a development or ad-hoc profile that includes its UDID (in list_devices), or an enterprise profile. App Store and TestFlight builds can't be installed this way. upload_app with a name ending in .ipa, then install_app; the reply has the bundle id. If the profile doesn't include the iPhone, the install fails with Apple's message: tell the person to add the UDID to their Apple Developer account and export the build again.

What works

  • get_screen, tap, long_press, type_text, swipe, scroll_to, wait_for, screenshot.
  • press_key: HOME, VOLUME_UP, VOLUME_DOWN, ENTER only. There is no Back key: tap the app's back button.
  • launch_app, stop_app, uninstall_app, list_apps, open_url (Safari pages and deep links), set_location.
  • Quick commands made for iPhone: list_quick_commands platform=ios (appearance, alerts, crash logs, …).
  • get_logs (the device log), get_crashes (crash reports, watchdog and out-of-memory kills).
  • get_performance (from Xcode Instruments, about every 10 s; no janky frames or launch times).
  • Files of your team's apps: list, find, read, download, upload (see files).
  • inject_camera_image with the HopCamera Swift Package in a development-signed debug build.
  • accessibility_scan, flows, run_tests platform=ios (XCUITest), Appium.

What doesn't (yet)

  • shell, clear_app_data (uninstall and install again for a fresh state), inspect_app_data.
  • get_web_requests, get_response_body, get_page_html (Android only).
  • biometric (Android only).
  • get_network and set_network go through the lab proxy, which the iPhone must be set to use; this path is built but not yet confirmed on a lab iPhone. Don't rely on it without checking that requests show up.
  • Sound: recordings have no sound track, so get_media_quality checks the picture only.

Tips

  • System alerts (permissions, "Allow notifications") are on the screen as elements: tap "Allow" or "Don't Allow".
  • Elements often have an accessibility identifier: target it with id.
  • Flows written with text / id targets run on Android and iPhone alike, if both apps use the same labels.
get_skill name=browsers-and-tvshop://skills/browsers-and-tvs

Desktop browsers and Android TVs

Read it when: The device is a desktop browser (Chrome, Edge, Brave, Chromium, Safari, Firefox) or an Android TV / Google TV box.

Desktop browsers

Browsers on the lab's machines are devices with platform desktop (ids like chrome-1). Book one with book_device platform=desktop, or a given browser with browser= chrome, edge, brave, chromium, safari or firefox. Every booking starts with a fresh profile, which is deleted on release, so nobody sees anyone else's cookies or history.

The usual tools work on the page:

  • get_screen returns DOM elements (positions in CSS pixels); tap, type_text, swipe (scrolls), scroll_to, wait_for, screenshot;
  • press_key: ENTER, TAB, ESCAPE, arrows, PageDown, F5, BACK / FORWARD (history), RELOAD, any DOM key or a chord like Ctrl+A;
  • open_url, set_location, set_network, run_flow;
  • get_logs gives the browser console (Chrome-family browsers only).

browser handles what a phone doesn't have: action=state (URL, title, tabs, viewport, open dialog), navigate, back, forward, reload, new_tab, tab / close_tab with a tab_id, viewport (width, height) to test responsive layouts, dialog (accept true / false, text for a prompt) and eval (runs a JavaScript expression and returns its value).

Chrome, Edge, Brave and Chromium record the console and every web request with its body into the recording (get_session_files: web.har). Safari and Firefox are driven over WebDriver and don't capture the console or network.

Selenium users can point a WebDriver client at the lab instead: it books a browser per session. See test-suites-and-ci (appium_info also explains the endpoints).

Android TV and Google TV

TV boxes are Android devices marked [tv] in list_devices. Book one with book_device form_factor=tv. There is no touch: move with press_key DPAD_UP / DPAD_DOWN / DPAD_LEFT / DPAD_RIGHT (or UP, DOWN, LEFT, RIGHT) and select with OK (= DPAD_CENTER). Also BACK, HOME, MENU, PLAY_PAUSE, STOP, NEXT, PREVIOUS, REWIND, FAST_FORWARD, MUTE, CHANNEL_UP / CHANNEL_DOWN, GUIDE, INFO, SETTINGS, SEARCH.

get_screen shows which element is focused: press keys, read the screen again and check that the focus moved where you wanted. launch_app also finds TV launcher apps, and list_apps includes TV-only apps. Logs, crashes, network, performance and flows work as on a phone.

get_skill name=results-and-sharinghop://skills/results-and-sharing

Results, recordings and sharing

Read it when: Handing results to a person: recording links, PDF reports, a live phone link, usage and plan limits, the audit log (admins).

Recordings

Every booking is recorded. get_session_files session_id=… (current or past) gives download links for the screen video, device log, network HAR, crashes, flow screenshots, accessibility reports and the whole recording as a zip. Put these links in your report: a developer can watch the video next to the log.

PDF reports

get_report_pdf with run_id (a test run: pass / fail by phone, failures with screenshots) or session_id (a recording: phone, duration, performance charts, key events, crashes).

Let a person see or use the phone

share_device makes a link and QR code that opens the booked phone's live screen in any phone browser, with no app or sign-in. mode=view (default) or control (touch, Home / Back / app switcher, rotate, clipboard). It stops after minutes (default 15; 0 = when the booking ends), when you revoke it, or when the booking ends. list=true shows your links and who is watching; revoke=<share id> stops one. A control link lets anyone who has it use the phone: give it only to the person who asked.

Plan and usage

get_account: the plan, its limits (device minutes per month, devices at the same time, AI goals, seats) and use this month. Check it before starting a big parallel run. get_insights: sessions, minutes, runs, pass rate, flaky tests, crashes and phone use over the last N days.

Audit log (admins only)

get_audit_log shows who did what and when: sign-ins and failed sign-ins, bookings, downloads, share links, API keys, admin changes, recordings deleted by data retention, each with IP. Filters: since, until, user, action (e.g. login.failed, booking., share_link.), query, failed_only, limit. It also says whether the log's hash chain is intact (an edited or removed record breaks it).

Ending well

Before you finish: release_device for every booking (my_sessions shows what you still hold), revoke share links you no longer need, and tell the person what you did, what you found and where the evidence is.