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
- Open ApplesauceOS → Settings → Remote MCP and enable remote access.
- Add
https://mcp.applesauceos.com/mcpas a remote HTTP MCP server in your client. It must support Streamable HTTP and OAuth. - 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.
- Return to the phone and approve the waiting client. Verify its name and return address.
- Give the agent the automation playbook, 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 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.