一、前提条件
1. 已开通 云手机服务，并且有购买云手机实例。
2. 已在 API 密钥管理 获取 SecretId 和 SecretKey。
3. 你的 Agent 框架支持 MCP 远程服务（Streamable HTTP 传输）并能自定义请求头，例如 WorkBuddy、CodeBuddy、Cursor，或基于 MCP SDK 自研的 Agent。
二、适用场景
| 场景 | 说明 |
| Agent 自动化操作 Android App | Agent 根据自然语言任务，读取 App 界面并执行点击、滑动、输入、按键等操作。 |
| App 功能验证与巡检 | 先观察当前界面，再执行操作并检查结果；适用于重复性的 UI 流程。 |
| 人工接管 | 必要时获取短时体验链接，由授权人员查看并操作同一台云手机。 |
三、整体架构
架构可参考下图：
四、基本概念
| 概念 | 说明 |
| MCP | Model Context Protocol，AI Agent 调用外部工具的开放协议。Agent 作为 MCP Client，发现并调用云手机工具。 |
| 云手机 MCP Server | 已由服务提供方部署的远程 MCP 服务。Agent 通过统一地址连接，获得可用的云手机操作工具。 |
| 云手机实例 | 运行 Android 系统及目标 App 的云端手机；调用具体工具时通常需指定实例 ID。 |
| 通用交互工具 | 读取 UI 控件、截图、点击、长按、滑动、按键、文本输入等工具；无需为每个 Android App 单独开发 MCP。 |
| MCP Token | 访问云手机 MCP 服务的凭证。由服务提供方签发并交付，用于限制可访问的云手机实例及有效期。 |
注意：Agent 只持有 MCP Token，绝不持有腾讯云 API 密钥（SecretId / SecretKey）。并发申请、会话创建、Token 签发都应在业务后台完成。
六、步骤1：调用 CreateAndroidInstanceMCPToken 创建访问凭证
云手机 MCP Server 采用 Bearer Token 鉴权。调用方需要先获取由腾讯云签发的 MCP Token，之后才能与服务建立连接、发现并调用云手机工具。本步骤在业务后台完成：后台使用自身的 SecretId / SecretKey 调用云 API CreateAndroidInstanceMCPToken 签发 Token，再按需下发给 Agent。
注意：Token 仅在创建成功时返回一次，服务端不留存副本，也不提供再次查看 Token 明文的接口。请务必在收到响应后妥善保管；一旦丢失，只能重新签发。
七、步骤2：Agent 接入云手机 MCP Server
在支持 Streamable HTTP 的 Agent 客户端中，添加远程 MCP 服务。
{ "mcpServers": { "tencent-cvp": { "type": "streamableHttp", "url": "https://mcp-server.crtrcloud.com/mcp", "headers": { "Authorization": "Bearer <CreateMCPToken 返回的 Token>" } } }}
注意：说明：
注意：该方式适合调试。生产环境中 Token 有有效期且与会话绑定，建议由业务后台动态下发，而非写死在配置文件中。
连接后，Agent 可自动发现当前服务开放的云手机 MCP 工具。先给出目标实例 ID，再提出要执行的任务，例如：请在指定云手机上打开待办 App，查看有哪些任务，点击进入并确认页面已打开。
八、可用工具
连接成功后，Agent 可自动发现并调用以下工具。工具名称统一以 android_instance_ 开头；除 android_instance_list 外，调用时均需指定目标实例 ID。
九、实例与设备状态
| 工具名称 | 说明 |
| android_instance_list | 列出当前凭证可访问的云手机实例，含实例 ID、名称、状态、分辨率与地域。 |
| android_instance_get_resolution | 获取实例当前屏幕分辨率与像素密度。 |
| android_instance_get_orientation | 获取屏幕方向（竖屏或横屏）及旋转角度。 |
| android_instance_get_foreground_app | 获取当前前台应用的包名与 Activity。 |
| android_instance_get_logcat | 读取实例已有的 logcat 日志，用于排障。 |
| android_instance_get_task | 查询安装、重启等异步任务的执行状态。 |
| android_instance_get_experience_url | 获取实例的短时体验链接，供人工接管查看和操作。 |
| android_instance_get_clipboard | 读取实例剪贴板中的文本内容。 |
| android_instance_reboot | 重启云手机实例。 |
| android_instance_open_url | 在实例中打开公网 HTTP 或 HTTPS 链接。 |
十、界面感知
| 工具名称 | 说明 |
| android_instance_screenshot | 截取当前屏幕画面，并返回该图的宽高作为坐标基准。 |
| android_instance_dump_ui | 导出当前屏幕的 UI 控件层级，用于按文本或控件定位元素。 |
十一、交互操作
| 工具名称 | 说明 |
| android_instance_click | 单击屏幕上的指定位置。 |
| android_instance_long_press | 长按屏幕上的指定位置。 |
| android_instance_swipe | 在屏幕上按指定方向滑动。 |
| android_instance_key | 模拟按下系统按键，如 Home、Back、Enter。 |
| android_instance_input_raw | 按顺序执行一组原始输入事件，用于多指等复杂操作。 |
| android_instance_input_text | 在当前焦点输入框中输入 ASCII 文本。 |
| android_instance_paste_text | 向当前焦点输入框粘贴文本，支持中文等非 ASCII 字符。 |
十二、应用管理
| 工具名称 | 说明 |
| android_instance_list_apps | 查询实例上已安装的应用列表。 |
| android_instance_install_app | 从公网下载地址为实例安装 APK。 |
| android_instance_start_app | 启动实例上的指定应用。 |
| android_instance_stop_app | 强制停止指定应用。 |
| android_instance_clear_app_data | 清除指定应用的数据，使其恢复到刚安装的状态。 |
| android_instance_uninstall_app | 卸载实例上的指定应用。 |
十三、安全建议
1. 优先使用 USER Key，并只授权必要实例。
2. 优先设置有限有效期。
3. 体验链接等同于临时实例控制权，避免公开传播。
4. 卸载应用和清理应用数据前确认影响范围。
5. Key 疑似泄露时，先创建并切换新 Key，再立即吊销旧 Key。
6. 体验链接可控制实例，勿向无关人员转发。
十五、调用工具返回鉴权失败
检查请求头格式是否为 Authorization: Bearer <MCP Token>，并确认使用本云手机 MCP 服务签发的有效 Token；过期时通过接口重新创建。若提示实例无权访问，请核对实例是否在该 Token 的授权范围内。
十六、User Key 无法操作实例
请检查实例白名单是否包含目标实例、实例 ID 是否正确，以及实例是否处于可操作状态。
十七、体验链接无法打开
请检查链接是否超过1小时有效期、实例是否可操作，以及网络和实时音视频通道是否可达。
十八、安装或重启长时间未完成
安装和重启为异步任务，耗时较长，请使用 android_instance_get_task 查询状态；安装 APK 应使用云端可直接访问的公网 HTTP 或 HTTPS 地址。
十九、点击位置不准确
优先通过 android_instance_dump_ui 获取实时元素位置；使用截图坐标时，应确保坐标基准与截图尺寸一致。
20、Agent 使用 MCP 是否额外计费？
腾讯云手机资源和带宽按 云手机计费说明 计费；涉及对象存储等能力时，可能产生相关产品费用。本服务的 MCP 工具是否另行收费，以服务提供方与客户的实际协议为准，不能套用应用云渲染的计费规则。