Agentic Phone MCP - Documentation

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.

Server URL: https://api.agi.tech/v1/mcpProtocol: MCP 2024-11-05 (JSON-RPC 2.0) | Transport: Streamable HTTP (JSON responses) or SSEAuth: OAuth 2.1 sign-in (recommended) or Authorization: Bearer YOUR_API_KEY

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:

┌──────────────────┐    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.

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.

Quickstart

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.

Connect your AI client

The fastest path is Claude Code:

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.

Run your first task

Ask your assistant:

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.

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.

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.

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

The loop

Every workflow is the same three beats:

Start - phone_run_task with a prompt. You get task_id (and a session_id to reuse for follow-ups).
Monitor - phone_task_monitor until it returns with monitor_timed_out: false. If true, the task is still working: call it again.
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 has the recovery move.

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.

Example prompts

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

Send a message for me

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.

Morning catch-up

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.

App testing and QA

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.

Cross-app workflow in one session

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.

Go deeper

Phone setup

Install the app, grant permissions, manage devices

Connect your AI client

Claude Code, Claude Desktop, Cursor, ChatGPT, IDEs - plus auth in depth

Task lifecycle

States, terminal outcomes, handoffs, pause/resume

Tool reference

Every parameter, default, and cap

Best practices

Task design, sessions, errors, performance, security, monitoring

Troubleshooting

Symptom-based fixes for devices, tasks, auth, and clients

Support

Email Support

support@theagi.company

API Keys

Create and manage your API keys

​How it works

​Quickstart

​The tools at a glance

​The loop

​Example prompts

​Go deeper

Phone setup

Connect your AI client

Task lifecycle

Tool reference

Best practices

Troubleshooting

​Support

Email Support

API Keys

How it works

Quickstart

The tools at a glance

The loop

Example prompts

Go deeper

Support