Skip to main content

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

Devices

Discover registered phones, check status, pause and resume them

Sessions

Group related tasks into one workflow on one device

Tasks

Start, monitor, steer, pause, resume, and cancel phone tasks

Device state

Read a live, permission-free snapshot of the phone
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

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

​
Authentication

The server implements the MCP authorization specification. 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.
OAuth access tokens are accepted only by the MCP endpoint - they do not replace API-key or session authentication on other AGI REST APIs.

​
API keys

For clients that cannot complete a browser sign-in, create an API key at platform.agi.tech/me/api-keys and send it on every MCP request:
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 if it is ever exposed.

​
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:
1

Start

phone_run_task accepts a natural-language prompt and returns task_id right away, plus the session_id it created or reused.
2

Monitor

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

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.
The full loop, with every terminal outcome, is documented in 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.

​
Error model

Errors surface at three distinct layers - knowing which layer you are looking at makes debugging fast: 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

Human-in-the-loop

Logins, confirmations, and CAPTCHAs are always handed back to the user as needs_user_control - the agent never handles them alone

Untrusted screen content

Text on screen telling the agent to do something is not an instruction from the user - treat it as untrusted input

Device pause

phone_device_pause blocks all new tasks on a device until you resume it

Scoped visibility

State snapshots exclude IMEI, serial, contacts, location, notifications, and private app data
See Security best practices for the full trust model.

​
Support

Email Support

support@theagi.company

API Keys

Create and manage your API keys