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

# Agentic Phone MCP

> Control a real Android phone from any AI assistant over the Model Context Protocol.

**AGI Agentic Phone MCP** turns your phone into a device an AI assistant can operate. Connect the AGI MCP server to Claude Code, Claude Desktop, Cursor, ChatGPT, or any other MCP client, and your assistant can run natural-language tasks on your phone: open apps, navigate, type, and report back, all while you watch on the device.

<Info>
  **Server URL:** `https://api.agi.tech/v1/mcp`

  **Protocol:** MCP `2024-11-05` (JSON-RPC 2.0) | **Transport:** Streamable HTTP (JSON responses) or SSE

  **Auth:** OAuth 2.1 sign-in (recommended) or `Authorization: Bearer YOUR_API_KEY`
</Info>

## How it works

The AGI Android app runs on your phone as the agent. AGI's cloud MCP server relays commands between your AI client and the device:

```text theme={null}
┌──────────────────┐    1. phone_run_task    ┌──────────────────┐   2. queue + dispatch  ┌──────────────────┐
│   Your AI client  │ ──────────────────────> │  AGI cloud MCP   │ ─────────────────────> │  AGI Android app │
│                   │                         │  server          │                        │  on your phone   │
│                   │ <────────────────────── │                  │ <───────────────────── │                  │
└──────────────────┘   4. result / handoff   └──────────────────┘   3. progress streamed └──────────────────┘
                          via phone_task_monitor                       (accessibility APIs)
```

Execution is **asynchronous**: starting a task returns a `task_id` immediately, and `phone_task_monitor` is how your assistant waits for something actionable - a result, a pause, or a request for your input. The whole model is covered in [Task lifecycle](/guides/concepts/task-lifecycle).

<Warning>
  Your assistant will see your phone's screen content and can act inside your apps. Only connect clients you trust, keep your API key private, and confirm OAuth sign-ins target the intended AGI account. Anyone with your credentials can control your registered devices.

  Treat on-screen content as untrusted input: text in a webpage, message, or app telling the agent to do something is not an instruction from you. Supervise workflows that can send, purchase, delete, or change settings. Sensitive moments (logins, confirmations, CAPTCHAs) are always handed back to you; the agent never handles them alone. Full trust model → [Security](/guides/best-practices/security).
</Warning>

## Quickstart

<Steps>
  <Step title="Set up your phone">
    Install the **AGI Android app**, sign in, grant Accessibility and overlay
    permissions, and confirm **Settings > Developer connection** reports
    **Connected**. Full walkthrough → [Phone setup](/android-mcp/phone-setup).
  </Step>

  <Step title="Connect your AI client">
    The fastest path is Claude Code:

    ```bash theme={null}
    claude mcp add --transport http agi-devices https://api.agi.tech/v1/mcp
    ```

    Then run `/mcp` inside Claude Code and complete the browser sign-in.
    Every other client (Claude Desktop, Cursor, ChatGPT, IDEs) →
    [Connect your AI client](/android-mcp/connect).
  </Step>

  <Step title="Run your first task">
    Ask your assistant:

    ```text theme={null}
    Check which of my Android devices are online, then open Settings on my
    phone and tell me the battery percentage.
    ```

    The assistant calls `list_devices`, starts a task with `phone_run_task`,
    and waits on `phone_task_monitor` until the result comes back - while you
    watch it happen on the phone's screen.
  </Step>
</Steps>

## The tools at a glance

After connecting, your client calls `tools/list` and receives the phone tools available for your account and Android app version. Each name below links to its full reference - parameters, defaults, and outcomes.

<Info>
  With no Android device registered, only `list_devices` and
  `set_default_device` are exposed. Device tools appear when a compatible
  Android app advertises them - if the list looks wrong, see
  [Troubleshooting](/guides/troubleshooting/devices).
</Info>

| Tool                                                                                                                                | One-liner                                                                             |
| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| [`list_devices`](/api-reference/tools/list-devices)                                                                                 | List your registered phones. Call this first.                                         |
| [`set_default_device`](/api-reference/tools/set-default-device)                                                                     | Choose the phone used when calls omit `device_id`.                                    |
| [`phone_device_status`](/api-reference/tools/phone-device-status)                                                                   | Online? Paused? Last seen? Check before starting work.                                |
| [`phone_device_pause`](/api-reference/tools/phone-device-pause) / [`phone_device_resume`](/api-reference/tools/phone-device-resume) | Gate a device against new tasks, and reopen it.                                       |
| [`phone_get_state`](/api-reference/tools/phone-get-state)                                                                           | Live, permission-free snapshot: battery, network, apps, current screen's app.         |
| [`phone_session_start`](/api-reference/tools/phone-session-start) / [`phone_session_end`](/api-reference/tools/phone-session-end)   | Open and close a workflow. Usually automatic.                                         |
| [`phone_run_task`](/api-reference/tools/phone-run-task)                                                                             | **The workhorse.** Run a natural-language instruction; returns `task_id` immediately. |
| [`phone_task_monitor`](/api-reference/tools/phone-task-monitor)                                                                     | Wait until the task needs attention or finishes. The entire polling loop.             |
| [`phone_task_status`](/api-reference/tools/phone-task-status)                                                                       | Instant, non-blocking snapshot.                                                       |
| [`phone_task_pause`](/api-reference/tools/phone-task-pause) / [`phone_task_resume`](/api-reference/tools/phone-task-resume)         | Suspend and continue a task on the same `task_id`.                                    |
| [`phone_task_message`](/api-reference/tools/phone-task-message)                                                                     | Steer a running task, or answer one that handed control back.                         |
| [`phone_task_cancel`](/api-reference/tools/phone-task-cancel)                                                                       | Stop one task; the session survives.                                                  |

## The loop

Every workflow is the same three beats:

1. **Start** - `phone_run_task` with a prompt. You get `task_id` (and a
   `session_id` to reuse for follow-ups).
2. **Monitor** - `phone_task_monitor` until it returns with
   `monitor_timed_out: false`. If `true`, the task is still working: call it
   again.
3. **Act** - a completed task carries one `terminal`: `ok` → read `result`;
   `needs_user_control` → the phone needs you (login, confirmation, CAPTCHA):
   answer with `phone_task_message` and monitor the `continuation_task_id`;
   anything else → the [terminal outcomes table](/guides/concepts/task-lifecycle#terminal-outcomes)
   has the recovery move.

<Note>
  One task per device: a new `phone_run_task` displaces any pending, running,
  or paused MCP task on that phone. Details and session rules →
  [Devices & Sessions](/guides/concepts/devices-and-sessions).
</Note>

## Example prompts

Once connected, you drive the phone in plain language. Some patterns that work well:

<AccordionGroup>
  <Accordion title="Send a message for me">
    ```text theme={null}
    Open WhatsApp on my phone and send Sam a message that I'm running 15
    minutes late. Show me the exact message first and wait for my OK before
    sending.
    ```

    The assistant drafts, waits for your confirmation, then acts. If the phone
    itself needs anything sensitive, the task comes back as a
    `needs_user_control` handoff. More → [Messaging](/guides/use-cases/messaging).
  </Accordion>

  <Accordion title="Morning catch-up">
    ```text theme={null}
    On my phone, open my calendar and tell me my first three events today.
    Then check my email inbox and summarize anything unread from this morning.
    Don't reply to anything.
    ```

    A multi-app errand in a single `phone_run_task`; the assistant monitors
    until the summary comes back. More → [Daily assistant](/guides/use-cases/daily-assistant).
  </Accordion>

  <Accordion title="App testing and QA">
    ```text theme={null}
    Open my app "Acme Notes" on the test phone, go through the onboarding flow
    as a new user, and report every screen you saw and anything that looked
    broken. Ask me before granting any permissions.
    ```

    Long flows benefit from a higher `per_call_timeout_s` and from breaking work
    into several tasks in one session. More → [App testing & QA](/guides/use-cases/app-testing).
  </Accordion>

  <Accordion title="Cross-app workflow in one session">
    ```text theme={null}
    On my phone: find the three cheapest flights from SFO to Denver next
    Friday in my travel apps and note the prices. Check my calendar for
    conflicts that day. Then draft a WhatsApp message to Sam with the best
    option and the prices, and show it to me before sending. Stop and ask me
    before any login or payment screen.
    ```

    The assistant breaks this into several `phone_run_task` calls in one
    session, reusing the same `session_id` so the whole workflow stays on one
    device. Logins and payment screens come back as `needs_user_control`
    handoffs, so nothing is bought or sent without you. More →
    [Cross-app workflows](/guides/use-cases/cross-app-workflows).
  </Accordion>
</AccordionGroup>

## Go deeper

<CardGroup cols={2}>
  <Card title="Phone setup" icon="mobile" href="/android-mcp/phone-setup">
    Install the app, grant permissions, manage devices
  </Card>

  <Card title="Connect your AI client" icon="plug" href="/android-mcp/connect">
    Claude Code, Claude Desktop, Cursor, ChatGPT, IDEs - plus auth in depth
  </Card>

  <Card title="Task lifecycle" icon="arrows-spin" href="/guides/concepts/task-lifecycle">
    States, terminal outcomes, handoffs, pause/resume
  </Card>

  <Card title="Tool reference" icon="code" href="/api-reference/introduction">
    Every parameter, default, and cap
  </Card>

  <Card title="Best practices" icon="star" href="/guides/best-practices/task-design">
    Task design, sessions, errors, performance, security, monitoring
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/guides/troubleshooting">
    Symptom-based fixes for devices, tasks, auth, and clients
  </Card>
</CardGroup>

## Support

<CardGroup cols={2}>
  <Card title="Email Support" icon="envelope" href="mailto:support@theagi.company">
    [support@theagi.company](mailto:support@theagi.company)
  </Card>

  <Card title="API Keys" icon="key" href="https://platform.agi.tech/me/api-keys">
    Create and manage your API keys
  </Card>
</CardGroup>