> ## Documentation Index
> Fetch the complete documentation index at: https://phone-harness.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Connect Claude, Cursor, Codex or any MCP client to a Cloud Android or Cloud iPhone with one URL and a sign-in.

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.

```text theme={null}
https://mcp.phone-harness.com/mcp
```

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](https://phone-harness.com/cloud), and new accounts start with \$5 of credit.

## Connect your client

> [tab] Claude
>
> 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.

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http phone-harness https://mcp.phone-harness.com/mcp
> ```
>
> Then run `/mcp`, choose `phone-harness`, and sign in. The server is added to the current project; add `--scope user` to have it in every project.

> [tab] Cursor
>
> Add the server to `~/.cursor/mcp.json` for every project, or to `.cursor/mcp.json` for one, then restart Cursor. Cursor asks you to sign in.
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "phone-harness": {
>       "url": "https://mcp.phone-harness.com/mcp"
>     }
>   }
> }
> ```

> [tab] VS Code
>
> Run **MCP: Add Server** from the Command Palette, choose **HTTP**, and paste the URL. Or add the server to `mcp.json`:
>
> ```json theme={null}
> {
>   "servers": {
>     "phone-harness": {
>       "type": "http",
>       "url": "https://mcp.phone-harness.com/mcp"
>     }
>   }
> }
> ```
>
> Sign in when VS Code asks.

> [tab] Codex
>
> ```bash theme={null}
> codex mcp add phone-harness --url https://mcp.phone-harness.com/mcp
> codex mcp login phone-harness
> ```
>
> `codex mcp login` opens the sign-in in your browser.

> [tab] ChatGPT
>
> Custom MCP servers in ChatGPT need a Business, Enterprise or Edu workspace, and an admin adds them. On ChatGPT web, open **Plugins → + → Add custom MCP server**, paste the URL, choose sign-in, and select **Create as a plugin**. Install the plugin, then mention it in a chat.

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](https://github.com/phone-harness/mcp#setup) has steps for more clients.

Then ask your agent:

```text theme={null}
Start a phone, open Settings, and tell me what's on the screen.
Then stop the phone.
```

> [!NOTE]
>
> That starts a temporary Cloud Android, which bills by the minute until the agent stops it. See [Start and stop](#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](https://phone-harness.com/dashboard).

## Use an API key instead

For a client without OAuth sign-in, or a job that runs unattended, send an [API key](https://phone-harness.com/docs/authentication) 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](https://phone-harness.com/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:

```json Claude Code: .mcp.json theme={null}
{
  "mcpServers": {
    "phone-harness": {
      "type": "http",
      "url": "https://mcp.phone-harness.com/mcp",
      "headers": {
        "Authorization": "Bearer ${PHONE_HARNESS_API_KEY}"
      }
    }
  }
}
```

```toml Codex: ~/.codex/config.toml theme={null}
[mcp_servers.phone-harness]
url = "https://mcp.phone-harness.com/mcp"
bearer_token_env_var = "PHONE_HARNESS_API_KEY"
```

To replace or revoke a key, see [Rotate and revoke keys](https://phone-harness.com/docs/authentication#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.

```bash theme={null}
claude mcp add phone-harness -- uvx phone-harness-mcp
```

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](https://github.com/phone-harness/mcp/blob/main/docs/self-hosting.md).

## 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](#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](https://phone-harness.com/docs/guides/iphone.md), or your [saved Android](https://phone-harness.com/docs/guides/android.md) 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](https://phone-harness.com/docs/guides/limits-and-credits.md).

> [!NOTE]
>
> 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.

| | Watch | Control |
| - | - | - |
| What you can do | Watch only: nothing you do reaches the phone | Tap, type and press buttons on the phone |
| Open it with | The session's `watch_url`, or `phone-harness cloud watch` | The [dashboard](https://phone-harness.com/dashboard), or `phone-harness cloud open` |
| Sign-in | None: the link carries a view grant | Your Phone Harness account |
| Works until | Six hours after the session was created, and never past the session | The session ends |
| Embedded by | Only the Phone Harness watch page | Only the Phone Harness dashboard |
| API | [Get the live view](https://phone-harness.com/docs/api-reference/phone/get-viewer.md) | [Get the owner viewer](https://phone-harness.com/docs/api-reference/phone/get-owner-viewer.md) |

* **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](https://github.com/ShawnPana/phone-harness) CLI signed in to the same account (`phone-harness cloud login`):

```bash theme={null}
# Open the watch link in your browser, or print it with --print
phone-harness cloud watch SESSION_ID
phone-harness cloud watch SESSION_ID --print

# Open the dashboard, to take the controls
phone-harness cloud open
```

`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](https://phone-harness.com/docs/guides/viewer-and-screenshots.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.