Skip to main content
The Phone Harness MCP server gives an AI client the tools to use a phone: start it, read the screen, tap, type, swipe, open apps, and stop it. The phone is a Cloud Android emulator or a Cloud iPhone on your account. Add one URL to your client and sign in; there is nothing to install.
The server speaks streamable HTTP and signs you in with OAuth. You need a Phone Harness account: sign-up is open at phone-harness.com/cloud, and new accounts start with $5 of credit.

Connect your client

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.
Any other client that can add a remote MCP server over streamable HTTP works the same way: add the URL and sign in. The server’s README has steps for more clients. Then ask your agent:
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 the phone: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 from PHONE_HARNESS_API_KEY when the client starts, so the file itself holds no secret:
To replace or revoke a key, see Rotate and revoke keys.

Run the server locally

The same server runs on your machine over stdio, as the phone-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.
In other clients, the command is 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 takes device: 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_devices lists the running phones with their ids, the phones your account can start, and your balance.
  • phone_start_device starts a phone and waits until it is ready. See Start and stop.
  • phone_stop_device ends the session.
The screen
  • phone_get_screen_size returns the screen size, in the coordinates taps and swipes use.
  • phone_take_screenshot returns a JPEG of the screen, its long side at most max_size (default 1024), or scaled by scale. A line before the image converts a point in it to screen coordinates.
  • phone_list_elements_on_screen lists the visible text with tap-ready centers, as text or json. Positions come from the accessibility tree on Android and from reading the pixels on an iPhone.
Touch and keys
  • phone_click_on_screen_at_coordinates taps x, y.
  • phone_long_press_on_screen_at_coordinates presses and holds x, y for duration milliseconds (default 800, at most 10000).
  • phone_swipe_on_screen swipes up, down, left or right: the way the finger moves, so up shows what is below. It starts at x, y or the center and travels distance pixels, or 40% of the screen.
  • phone_type_keys types text into the focused field. submit presses Enter after it.
  • phone_press_button presses HOME, BACK (Android only), APP_SWITCHER or ENTER.
Apps
  • phone_list_apps lists the installed apps: package ids on Android, bundle ids on an iPhone.
  • phone_launch_app opens an app by the name on its icon, or by package id on Android.
  • phone_get_foreground_app names the app in front, when the phone reports it.
No tool opens a URL, installs an app, reads the clipboard, records the screen, or returns a link to watch the phone.

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 its device 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}/viewer takes your credential or the watch link’s grant as token. GET /sessions/{sid}/owner-viewer takes 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.