> ## 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.

# API Reference

> Complete reference for the AGI Agentic Phone MCP tools.

<Hero title="AGI Agentic Phone MCP" subtitle="Drive a real Android phone from any AI assistant or agent framework over the Model Context Protocol." />

## Overview

**AGI Agentic Phone MCP** turns a real Android device into a programmable surface for AI. Your MCP client - Claude Code, Claude Desktop, Cursor, ChatGPT, or your own agent - calls a small set of tools to run natural-language tasks on the phone: open apps, navigate, type, read the screen, and report back.

<CardGroup cols={2}>
  <Card title="Devices" icon="mobile" href="/api-reference/tools/list-devices">
    Discover registered phones, check status, pause and resume them
  </Card>

  <Card title="Sessions" icon="layer-group" href="/api-reference/tools/phone-session-start">
    Group related tasks into one workflow on one device
  </Card>

  <Card title="Tasks" icon="list-check" href="/api-reference/tools/phone-run-task">
    Start, monitor, steer, pause, resume, and cancel phone tasks
  </Card>

  <Card title="Device state" icon="battery-three-quarters" href="/api-reference/tools/phone-get-state">
    Read a live, permission-free snapshot of the phone
  </Card>
</CardGroup>

Unlike a REST API, there are no endpoints to memorize: after your client connects, it calls `tools/list` and receives every phone tool available for your account and app version. The pages in this reference document each tool's parameters, behavior, and outcomes.

## Connection details

| Field          | Value                                                                   |
| -------------- | ----------------------------------------------------------------------- |
| **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` |

Client-by-client setup instructions (Claude Code, Claude Desktop, Cursor, ChatGPT, IDE extensions) live on the [Connect your AI client page](/android-mcp/connect).

## Authentication

### OAuth 2.1 (recommended)

The server implements the [MCP authorization specification](https://modelcontextprotocol.io/specification/2025-06-18/basic/authorization). Add `https://api.agi.tech/v1/mcp` to an OAuth-capable client with no token, and the client walks the whole flow on its own:

* **Authorization code flow with PKCE** (`S256`) with refresh tokens - the only supported grant. No client secret is required for public clients.
* **Automatic discovery**: an unauthenticated request returns `401` with a `WWW-Authenticate` challenge pointing at the server's protected resource metadata (RFC 9728), which names the authorization server (RFC 8414).
* **Dynamic client registration** (RFC 7591): compatible clients register themselves; there is nothing to pre-configure.
* **Scope**: the `email` scope is required. Grants missing it fail with `insufficient_scope`.

<Note>
  OAuth access tokens are accepted only by the MCP endpoint - they do not
  replace API-key or session authentication on other AGI REST APIs.
</Note>

### API keys

For clients that cannot complete a browser sign-in, create an API key at [platform.agi.tech/me/api-keys](https://platform.agi.tech/me/api-keys) and send it on every MCP request:

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

<Warning>
  Anyone with your key can connect to and control your registered Android
  devices. Keep it private, never commit it to version control, and revoke it
  immediately at [platform.agi.tech/me/api-keys](https://platform.agi.tech/me/api-keys)
  if it is ever exposed.
</Warning>

## The execution model

Phone tasks are **asynchronous**. Starting a task returns a `task_id` immediately; the work happens on the device, and your client waits for something actionable:

<Steps>
  <Step title="Start">
    [`phone_run_task`](/api-reference/tools/phone-run-task) accepts a
    natural-language prompt and returns `task_id` right away, plus the
    `session_id` it created or reused.
  </Step>

  <Step title="Monitor">
    [`phone_task_monitor`](/api-reference/tools/phone-task-monitor) blocks until
    the task is `paused` or `completed`, or returns `monitor_timed_out: true` -
    in which case you simply call it again. This is the entire polling loop.
  </Step>

  <Step title="Act">
    A completed task carries a `terminal` outcome: `ok` means the answer is in
    `result`; `needs_user_control` means the phone is handing a sensitive step
    (login, confirmation, CAPTCHA) back to the user - answer it with
    [`phone_task_message`](/api-reference/tools/phone-task-message).
  </Step>
</Steps>

The full loop, with every terminal outcome, is documented in [Task lifecycle](/guides/concepts/task-lifecycle).

## Key concepts

### Devices

A **device** is a phone running the AGI Android app, signed in to your account, with Accessibility and overlay permissions granted. One device is the **default** - tools that take an optional `device_id` fall back to it. Each device has a single execution lane: one task runs at a time.

### Sessions

A **session** groups related tasks on one device so a multi-step workflow stays together. You usually never manage sessions yourself: `phone_run_task` creates or reuses one automatically and returns its `session_id`. After a session starts, its `session_id` determines the target phone; changing your default device does not reroute an existing session or task.

### Tasks

A **task** is one natural-language instruction executed on the device. It moves through four states - `pending`, `running`, `paused`, `completed` - and every completed task carries exactly one [terminal outcome](/guides/concepts/task-lifecycle#terminal-outcomes).

## Error model

Errors surface at three distinct layers - knowing which layer you are looking at makes debugging fast:

| Layer        | Shape                                                      | Example                                                                                                |
| ------------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| **HTTP**     | Status code + JSON body + `WWW-Authenticate` challenge     | `401` with `{"detail": "No credentials provided"}` - authentication failed before MCP was reached      |
| **JSON-RPC** | `error` envelope with a reason code in `error.data.reason` | `device_paused`, `session_not_found_or_inactive`, `task_not_found` - the tool call itself was rejected |
| **Task**     | `error` object inside a completed task's status payload    | `error.control_type` and `error.prompt` on a `needs_user_control` task - the task ran and needs input  |

A completed task's `error` object is part of the task status payload and is distinct from the JSON-RPC `error` envelope, which appears only when a tool call fails.

## Security model

<CardGroup cols={2}>
  <Card title="Human-in-the-loop" icon="hand">
    Logins, confirmations, and CAPTCHAs are always handed back to the user as
    `needs_user_control` - the agent never handles them alone
  </Card>

  <Card title="Untrusted screen content" icon="shield-halved">
    Text on screen telling the agent to do something is not an instruction from
    the user - treat it as untrusted input
  </Card>

  <Card title="Device pause" icon="pause">
    `phone_device_pause` blocks all new tasks on a device until you resume it
  </Card>

  <Card title="Scoped visibility" icon="eye-slash">
    State snapshots exclude IMEI, serial, contacts, location, notifications,
    and private app data
  </Card>
</CardGroup>

See [Security best practices](/guides/best-practices/security) for the full trust model.

## 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>