# Connect an agent

Remote MCP connects a compatible computer-based agent to your device. The agent can inspect screens, create and edit scripts, run them, and read their results. You approve access on the phone; no ApplesauceOS account or SSH setup is needed.

## Pair once

1. Open **ApplesauceOS → Settings → Remote MCP** and enable remote access.
2. Add `https://mcp.applesauceos.com/mcp` as a **remote HTTP MCP server** in your client. It must support Streamable HTTP and OAuth.
3. Start authorization from that client. On its authorization page, enter a **New pairing code** generated in the phone app. Codes expire in five minutes and work once.
4. Return to the phone and approve the waiting client. Verify its name and return address.
5. Give the agent the [automation playbook](/doc/ai.md), then describe your task.

Opening `/mcp` in a browser alone does not connect an agent. The public server being online is different from a client being authorized for a particular phone. The client discovers tool names, descriptions and argument schemas using the MCP protocol and keeps its own credentials. Do not paste tokens into prompts.

## A first request

> Read https://mcp.applesauceos.com/doc/ai.md. Use the paired ApplesauceOS device to create a script that opens Settings. Save it in Scripts, run it, and verify that Settings is foreground. Read any JavaScript function pages you need before coding.

The playbook teaches how to work; [the function reference](/doc/api) supplies exact JavaScript signatures. People and agents read the same reference. `get_documentation` returns the complete playbook as one Markdown text, with no document selector or pagination.

## Available tools

| Task | MCP tools |
| --- | --- |
| Connection and state | `list_devices`, `device_status`, `release_control` |
| Apps | `list_apps`, `app_info`, `open_app` |
| Screen and elements | `observe_screen`, `capture_screen`, `find_elements`, `inspect_element` |
| UI actions and waits | `element_action`, `wait_for_element`, `touch_gesture`, `press_button`, `set_inspector` |
| Script files and folders | `list_scripts`, `read_file`, `write_file`, `create_directory`, `move_path`, `delete_file` |
| Normal saved scripts/projects | `start_script`, `get_script_run`, `stop_script` |
| Async JavaScript function bodies | `run_javascript`, `run_script`, `get_run`, `list_runs`, `stop_run`, `delete_run` |
| Diagnostics | `read_logs`, `list_crash_reports`, `read_crash_report` |
| Working instructions | `get_documentation` |

`write_file` creates a script. `create_directory` creates a project folder. For shell commands, the agent can run JavaScript containing `return execResult("id -u", false, 5);` and inspect its result. There is no separate execute-command tool.

Use the live schemas for parameter names. MCP tool names are not JavaScript functions: `open_app` is a tool, while `openApp()` runs inside a script.

## Access and privacy

Approval grants full device automation, including native calls and shell commands. Approve only clients you trust. Each authorization controls one phone. Screens, scripts and results pass through the relay over encrypted connections; they are not end-to-end encrypted against the relay.

The relay stores device identity, authorization/pairing state and bounded run ownership metadata. It does not persist screenshots, script source or execution output. Saved scripts and journals remain on the phone.

Select a paired client in the app to revoke access, or disable remote access to disconnect. Already running scripts continue: stop them from Runs or with the matching tool. The screen is shared with the person holding the device; avoid simultaneous manual and agent actions.

## If connection fails

Check that remote access is enabled, the device has internet access, the client supports remote HTTP/OAuth, and pairing was approved on the intended device. Unlock the phone for visual automation. If access was revoked, pair again. After a connection interruption, inspect an existing run ID rather than blindly submitting its actions again.