> For the complete documentation index, see [llms.txt](https://docs.incogniton.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.incogniton.com/documentation/pt-br-documentation/telefones-na-nuvem/control-cloud-phones-from-scripts.md).

# Controlar telefones na nuvem a partir de scripts e clientes de IA

Liste, inicie, pare e conecte-se a telefones na nuvem a partir de seus próprios scripts com a API REST local ou o Incogniton CLI, ou de um cliente de IA através do MCP.

Ative a API REST local em **Configurações > Automação** (ative **Habilitar API de automação** e clique em **Salvar**). Seus scripts e o Incogniton CLI podem então listar seus telefones na nuvem, iniciá-los e pará-los, e obter um endereço ADB para eles. Clientes de IA conectados com um **token MCP** podem listar, iniciar, parar e criar telefones na nuvem.

Esta página é sobre controlar telefones de fora do aplicativo. Para as tarefas prontas que você executa em telefones dentro do Incogniton, veja **Automação de telefone** em [Gerenciar telefones na nuvem](https://docs.incogniton.com/documentation/pt-br-documentation/telefones-na-nuvem/manage-cloud-phones.md#automation).

### O que você precisa

* A API REST local ativada em **Configurações > Automação**. Veja [Usar a API REST local](https://docs.incogniton.com/documentation/pt-br-documentation/api-de-automacao-e-sdks/local-rest-api.md). A API de automação é um recurso pago.
* Incogniton aberto e logado no mesmo computador que seu script. A API escuta em `127.0.0.1`, porta 35000 por padrão.
* Em uma equipe, a permissão correta para telefone na nuvem: **Usar telefones na nuvem (ligar, reiniciar, conectar)** para listar, iniciar e parar telefones, e **Gerenciar telefones na nuvem (editar, proxy, resetar, versão Android, ADB, root, apps, automação, mover)** para ativar o ADB.

### O que você pode fazer com a API REST local

| Ação                                                                                                     | Endpoint                         | Comando CLI                |
| -------------------------------------------------------------------------------------------------------- | -------------------------------- | -------------------------- |
| Liste os telefones na nuvem da sua equipe com seu ID, nome, grupo, status, versão Android e endereço ADB | `GET /cloudphone/list`           | `cloudphone-list`          |
| Inicie telefones sem abrir suas telas (para ADB, apps e automação)                                       | `POST /cloudphone/start`         | `cloudphone-start`         |
| Inicie telefones e abra a tela de cada um em uma janela no Incogniton                                    | `POST /cloudphone/start-display` | `cloudphone-start-display` |
| Desligue os telefones                                                                                    | `POST /cloudphone/stop`          | `cloudphone-stop`          |
| Habilite o ADB em um telefone em execução e obtenha seu endereço local                                   | `POST /cloudphone/adb`           | `cloudphone-adb`           |

Iniciar e parar requer uma lista de 1 a 100 IDs de telefone da lista de telefones. Cada telefone é verificado individualmente (minutos restantes, assinatura ativa, proxy configurado, não reiniciando), então alguns telefones podem iniciar enquanto outros são recusados; a resposta fornece o motivo por telefone.

Um telefone iniciado dessa forma continua em execução, e usando minutos, até que você o pare. Parar um telefone também fecha sua janela e sua conexão ADB local no Incogniton.

A ação ADB retorna um endereço local como `127.0.0.1:6555`. Conecte-se a ele com `adb connect`, exatamente como o endereço do **Comando de cópia ADB** no aplicativo. O telefone deve estar em execução. Veja [Conectar a um telefone na nuvem com ADB](https://docs.incogniton.com/documentation/pt-br-documentation/telefones-na-nuvem/connect-to-a-cloud-phone-with-adb.md).

Você não pode editar, reiniciar ou resetar um telefone na nuvem através da API REST local. Faça isso no aplicativo: veja [Editar, reiniciar ou resetar um telefone na nuvem](https://docs.incogniton.com/documentation/pt-br-documentation/telefones-na-nuvem/edit-restart-and-reset-cloud-phones.md).

### Use o Incogniton CLI

Cada ação acima tem um comando CLI correspondente. Clique em **Baixar CLI** na aba **Automação** para instalá-lo; enquanto estiver instalado, ele se atualiza quando o aplicativo inicia. Execute `incogniton-cli cloudphone-list` para ver seus telefones e seus IDs. Veja a [documentação CLI](https://api-docs.incogniton.com/cli) para saber como funcionam os comandos, flags e saída.

### Controle telefones na nuvem a partir de um cliente de IA (MCP)

Quando você conecta um cliente de IA como Claude ou Cursor com um token MCP (**Configurações > Automação > Gerar Token MCP**, veja [Conectar clientes de IA com MCP](https://docs.incogniton.com/documentation/pt-br-documentation/api-de-automacao-e-sdks/connect-ai-clients-mcp.md)), o cliente de IA pode:

* **Listar** seus telefones na nuvem com seu status e se o ADB está ativado.
* **Iniciar** telefones sem tela, para ADB, aplicativos instalados e automação.
* **Parar** telefones.
* **Criar** um novo telefone na nuvem com um proxy da sua Biblioteca de Proxies.

As ferramentas MCP rodam nos servidores do Incogniton, então também funcionam quando o aplicativo Incogniton está fechado. Elas não podem abrir a tela de um telefone: para ver um telefone, abra-o no aplicativo (**Telefones na Nuvem**, depois **Ligar** ou **Conectar**). Um telefone iniciado através do MCP continua em execução até ser parado, ou até que seu aplicativo Incogniton feche enquanto **Parar meus telefones na nuvem quando o Incogniton fechar** estiver ativado (telefones executando uma tarefa de automação continuam em execução).

{% hint style="info" %}
A documentação para desenvolvedores em [api-docs.incogniton.com](https://api-docs.incogniton.com/apis) cobre os endpoints de perfil, cookie e automação. Se você tiver dúvidas sobre automação de telefones na nuvem, entre em contato com nosso [departamento de suporte](https://incogniton.com/contact/).
{% endhint %}
