Connect your client
- Claude
- Claude Code
- Cursor
- VS Code
- Codex
- ChatGPT
Open Customize → Connectors and add a custom connector. Name it Phone Harness, paste the URL above, choose sign-in rather than No sign in, and add it. Then connect it and sign in.On Team and Enterprise plans, an Owner adds the connector under Organization settings → Connectors, and each member connects it.
That starts a temporary Cloud Android, which bills by the minute until the agent stops it. See Start and stop.
What signing in allows
Signing in opens a Phone Harness page in your browser, where you approve the client for thephone:drive scope. No key is copied anywhere. The MCP server stores no credential of its own: each call carries your client’s token to the Phone Harness API.
That sign-in can start, use and stop your phones, and read your account. It cannot manage the account: creating or revoking API keys, adding credit, billing, and resetting your saved Android or a Cloud iPhone answer 403 with code: scope_limited. Do those in the dashboard.
Use an API key instead
For a client without OAuth sign-in, or a job that runs unattended, send an API key as a bearer token on every request. A key has no scope limit: it acts as your whole account. Create one in Dashboard → API keys and keep it in an environment variable or your secret store. Never put it in a chat with the agent, in a URL, or in a file you commit. These configs read the key fromPHONE_HARNESS_API_KEY when the client starts, so the file itself holds no secret:
Run the server locally
The same server runs on your machine over stdio, as thephone-harness-mcp package. It drives the same cloud phones and signs in as that machine. Run uvx phone-harness cloud login once and nothing is pasted, or start the server with PHONE_HARNESS_API_KEY in its environment.
uvx with the argument phone-harness-mcp. Locally the server adds one tool, phone_save_screenshot, which writes a PNG or JPEG to a path on that machine. To run the HTTP server yourself, see self-hosting.
Tools
Every tool except the first two takesdevice: the id of a running phone, from phone_list_available_devices or phone_start_device. That id is the phone’s session id. The server keeps no state between calls, so the client names the phone every time.
Phones
phone_list_available_deviceslists the running phones with their ids, the phones your account can start, and your balance.phone_start_devicestarts a phone and waits until it is ready. See Start and stop.phone_stop_deviceends the session.
phone_get_screen_sizereturns the screen size, in the coordinates taps and swipes use.phone_take_screenshotreturns a JPEG of the screen, its long side at mostmax_size(default 1024), or scaled byscale. A line before the image converts a point in it to screen coordinates.phone_list_elements_on_screenlists the visible text with tap-ready centers, astextorjson. Positions come from the accessibility tree on Android and from reading the pixels on an iPhone.
phone_click_on_screen_at_coordinatestapsx,y.phone_long_press_on_screen_at_coordinatespresses and holdsx,yfordurationmilliseconds (default 800, at most 10000).phone_swipe_on_screenswipesup,down,leftorright: the way the finger moves, soupshows what is below. It starts atx,yor the center and travelsdistancepixels, or 40% of the screen.phone_type_keystypestextinto the focused field.submitpresses Enter after it.phone_press_buttonpressesHOME,BACK(Android only),APP_SWITCHERorENTER.
phone_list_appslists the installed apps: package ids on Android, bundle ids on an iPhone.phone_launch_appopens an app by the name on its icon, or by package id on Android.phone_get_foreground_appnames the app in front, when the phone reports it.
Start and stop
phone_start_device with nothing named starts a temporary Android emulator, which keeps nothing once it stops. To start a particular phone, pass its device_id from phone_list_available_devices: one of your Cloud iPhones, or your saved Android with its apps and logins. platform and kind go together: android with emulator, or ios with device.
The tool waits up to four minutes for the phone to be ready. If it is still not ready, the tool asks the service to end that session and says so. minutes (default 30) is how long the session lasts, boot included. The session ends then, unless phone_stop_device ends it first.
phone_stop_device ends the session. A temporary Android is deleted with its data, your saved Android is saved for next time, and a Cloud iPhone keeps its apps and data.
A Cloud Android costs 5¢ per minute, from ready until the session ends. A Cloud iPhone is a flat subscription and is not billed by the minute. See Limits and credits.
The agent decides when to start and stop phones. To approve each start yourself, turn on your client’s confirmation for tool calls.
Watch the phone
The MCP tools return no viewer link. The agent sees the phone through screenshots and the text on screen. To see it yourself, open it in Phone Harness. A phone your client started is a session on your account like any other, so the dashboard lists it, and itsdevice id is the session id that the API and the CLI take.
There are two live views. Both show the same live video, and both work for Cloud Android and Cloud iPhone.
- A watch link is a capability. Anyone who holds it can watch, and can read the session’s details and snapshots. It never reveals the ADB unlock code or an iPhone’s control URL, and it cannot open the control view. Share it only with people who should see the phone.
- The control view is yours alone. It opens behind your sign-in. Use it when the phone needs you, to type a password or a code, say, and ask the agent to wait while you do.
- Neither view goes on your own site. Each viewer URL is minted for Phone Harness’s own pages and refuses to load inside any other page. To show someone the phone, send the watch link.
- Viewer URLs are secrets too. Both endpoints return
{url, expires_at}for a ready session, expiring at the session’s deadline.GET /sessions/{sid}/viewertakes your credential or the watch link’s grant astoken.GET /sessions/{sid}/owner-viewertakes only yours. Do not log or share either URL. Fetch a new one to reconnect; that does not extend the session.
From a terminal
With the phone-harness CLI signed in to the same account (phone-harness cloud login):
SESSION_ID is the device id from the MCP tools, or a unique prefix of it. Without one, cloud watch uses the phone the CLI itself started or attached last. cloud open opens your dashboard, not one phone’s page; given a SESSION_ID, it first checks that the session is running. More on both views is in Viewer and screenshots.