---
name: whiteline-phone-agent
description: Control a personal Android device over Open-Core BYO-Gateway Dual MCP (Streamable HTTP https://mcp.phonectl.dev/mcp or local stdio whq-phone-mcp) with compact @e1..@eN refs and expected_screen_hash locking.
---

# Whiteline Phone Agent MCP Skill

Use this portable skill to connect Claude Code, Codex, Cursor, or Antigravity to your own paired Android phone running Whiteline Phone Agent (`v0.4.0` APK + `v0.5.0` Cloud Gateway).

## Option A: Remote Streamable HTTP MCP (Zero Local Binary)

Point any MCP client supporting Streamable HTTP (`2025-03-26`) to your personal Cloud Gateway `/mcp` endpoint (for example `https://mcp.phonectl.dev/mcp`):

```json
{
  "mcpServers": {
    "whiteline-phone": {
      "type": "streamable-http",
      "url": "https://mcp.phonectl.dev/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_GATEWAY_BEARER_TOKEN>"
      }
    }
  }
}
```

## Option B: Local Stdio MCP Bridge (`whq-phone-mcp`)

1. Store your personal gateway URL and bearer token in `~/.config/whiteline/android-gateway.json` (`chmod 600`):

```json
{
  "gateway_url": "https://mcp.phonectl.dev",
  "token": "<YOUR_GATEWAY_BEARER_TOKEN>"
}
```

2. Register the stdio server in your client MCP configuration (assuming `whq-phone-mcp` is on `PATH` or installed at `$HOME/bin/whq-phone-mcp`):

```json
{
  "mcpServers": {
    "whiteline-phone": {
      "command": "whq-phone-mcp",
      "args": []
    }
  }
}
```

## Standard Observe-Then-Act Loop

1. Always verify connectivity first with `phone_status`.
2. Call `phone_observe` with `{"mode": "live"}` to receive `screen_hash` and compact clickable refs `@e1..@eN`.
3. Call `phone_act` using `"target_ref"` and `"expected_screen_hash"` so accidental clicks on shifted UI fail safely with `STALE_SCREEN_HASH`.
4. Use `phone_run` with natural-language `prompt` only when a multi-step Gemini vision plan is needed (`wait: false` returns `mission_id` right away).
5. Use `phone_cancel` immediately to halt any running mission.

## Available Tools & Resources

- Tools: `phone_status`, `phone_observe`, `phone_act`, `phone_run`, `phone_apps`, `phone_cancel`
- Resources: `phone://status`, `phone://screen/compact`, `phone://apps`, `phone://openapi`
- Machine Specs: `https://phonectl.dev/openapi.json`, `https://phonectl.dev/.well-known/mcp.json`, `https://phonectl.dev/llms-full.txt`