Pular para conteúdo

Referência de ferramentas

Esta página é construída a partir dos schemas MCP reais. Execute python scripts/generate-tools-reference.py após alterar a superfície pública de tools para atualizar a referência English.

A maioria das ferramentas retorna um ToolResult estruturado com ok, message e data. workspace_open retorna o estado visível ao modelo usado para renderizar a MCP App. A maioria das ferramentas de execução e arquivos aceita machine opcional: omita para o workspace do controller e informe para um worker conectado. Operações Git usam deliberadamente run_shell ou outra ferramenta shell, em vez de wrappers Git dedicados.

Guia de seleção

Necessidade Tools preferidas
Monitorar ou colaborar com a execução no ChatGPT workspace_open
Inspecionar um ambiente environment_get, file_tree, file_read
Executar command curto ou operação Git run_shell
Executar tarefa interativa ou longa shell_start or job_start
Fazer mudanças exatas em arquivos file_edit or file_patch
Transferir arquivo ou diretório remote_transfer
Descobrir capability MCP externa mcp_tool_search, then mcp_tool_inspect
Interagir com uma página browser_session, browser_snapshot, then browser_act
Executar lógica browser personalizada browser_run_script
Controlar um aplicativo desktop nativo gui_list, gui_state e depois gui_action
Trabalhar em máquina remota use a mesma tool com machine; use remote_* apenas para administração de workers

Workspace interativo

workspace_open

Abre ou reutiliza um Live Workspace que exibe a Logical Session informada explicitamente. Passe o session_id ativo retornado por session_manage. O Workspace nunca infere a identidade da tarefa a partir do transporte MCP; passe null explicitamente quando não houver Logical Session ativa.

Parâmetro Tipo Obrigatório/default Descrição
session_id string \| null required
machine string \| null null
cwd string "."

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

Ambiente, Skills e estado de tarefas

environment_get

Retorna versão, workspace, auth, policy e informações de ambiente localmente ou em máquina remota.

Parâmetro Tipo Obrigatório/default Descrição
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

skill_list

Lista Agent Skills instaladas sem carregar suas instructions. A superfície MCP de tools permanece fixa; adicionar ou remover diretórios Skill aparece na próxima chamada.

Parâmetro Tipo Obrigatório/default Descrição
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

skill_load

Carrega uma Skill instalada pelo nome exato retornado por skill_list. Retorna instructions completas de SKILL.md e paths de arquivos relacionados.

Parâmetro Tipo Obrigatório/default Descrição
name string required
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

skill_read

Lê um arquivo de texto relacionado de uma Skill instalada.

Parâmetro Tipo Obrigatório/default Descrição
name string required
path string required
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

secret_scan

Escaneia arquivos de texto do workspace local em busca de secrets comuns antes de commit ou push.

Parâmetro Tipo Obrigatório/default Descrição
cwd string "."
glob string \| null null
max_results integer 200
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

session_manage

Gerencia uma única Logical Session durável. start cria uma nova tarefa e retorna seu session_id. resume continua somente o session_id explícito fornecido pelo usuário ou já presente nesta conversa. Todas as ações, exceto start, exigem session_id. Ações: start, resume, get, report, finish, cancel, delete. report aceita summary/findings/next/blockers/objective/label; delete exige uma Session terminal. Após 24 horas de inatividade, Sessions ativas tornam-se stale ao acessar, listar ou iniciar, exceto quando há uma chamada de ferramenta em andamento. Sessions stale podem ser retomadas ou removidas do histórico a partir das mais antigas.

Parâmetro Tipo Obrigatório/default Descrição
action string required
session_id string \| null null
label string \| null null
objective string \| null null
summary string \| null null
findings array[string] \| null null
next string \| null null
blockers array[string] \| null null

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

plan_manage

Gerencia o Goal mode opcional da Logical Session explícita. Um plan ativo habilita continuação automática após 15 minutos sem atividade do agent, limitada a 10 tentativas. session_id deve ser o mesmo id durável retornado por session_manage. Ações: start, get, update, block, resume, finish, cancel. start exige objective e steps; finish exige todos os steps completed ou skipped.

Parâmetro Tipo Obrigatório/default Descrição
action string required
session_id string required
objective string \| null null
steps array[object] \| null null
step_id string \| null null
status string \| null null
text string \| null null
note string \| null null

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

audit_tail

Lê entradas recentes do audit log local.

Parâmetro Tipo Obrigatório/default Descrição
lines integer 100
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Shells e jobs

run_shell

Executa um command shell não interativo localmente ou em máquina remota. Use para build, test, package-manager, Git e inspeção que devam terminar rapidamente. Para processos longos, interativos ou streaming, use shell_start ou job_start. Campos opcionais purpose/explanation permitem indicar por que o command está sendo executado.

Com persist_on_timeout=true (padrão false), a mesma tarefa continua após o tempo limite e retorna job_id. Consulte job_tail; stdout e stderr são combinados.

Parâmetro Tipo Obrigatório/default Descrição
command string required
cwd string "."
timeout_s integer \| null null
max_output_bytes integer \| null null
purpose string \| null null
explanation string \| null null
machine string \| null null
persist_on_timeout boolean false
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

run_python

Escreve e executa um script Python curto localmente ou em máquina remota.

Com persist_on_timeout=true (padrão false), a mesma tarefa continua após o tempo limite e retorna job_id. Consulte job_tail; stdout e stderr são combinados.

Parâmetro Tipo Obrigatório/default Descrição
code string required
cwd string "."
timeout_s integer 60
purpose string \| null null
explanation string \| null null
machine string \| null null
persist_on_timeout boolean false
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

shell_start

Inicia shell interativo persistente localmente ou em máquina remota.

Parâmetro Tipo Obrigatório/default Descrição
cwd string "."
name string \| null null
command string \| null null
purpose string \| null null
explanation string \| null null
machine string \| null null
idempotency_key string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

shell_send

Envia input para sessão shell persistente local ou remota.

Parâmetro Tipo Obrigatório/default Descrição
session_id string required
input_text string required
enter boolean true
machine string \| null null
idempotency_key string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

shell_read

Lê output recente de sessão shell persistente local ou remota.

Parâmetro Tipo Obrigatório/default Descrição
session_id string required
lines integer 200
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

shell_stop

Encerra sessão shell persistente local ou remota.

Parâmetro Tipo Obrigatório/default Descrição
session_id string required
machine string \| null null
idempotency_key string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

shell_list

Lista sessões shell persistentes localmente ou em máquina remota.

Parâmetro Tipo Obrigatório/default Descrição
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

job_start

Inicia job longo e trackeado localmente ou em máquina remota.

Parâmetro Tipo Obrigatório/default Descrição
command string required
cwd string "."
name string \| null null
purpose string \| null null
explanation string \| null null
machine string \| null null
idempotency_key string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

job_list

Lista resumida de tarefas, com as ativas primeiro. Paginação por next_offset; dados limitados a 32 KiB.

Parâmetro Tipo Obrigatório/default Descrição
include_finished boolean true
limit integer 25
offset integer 0
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

job_get

Obtém os detalhes completos da tarefa, incluindo comando, progresso e resultado.

Parâmetro Tipo Obrigatório/default Descrição
job_id string required
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

job_tail

Lê output recente de job local ou remoto trackeado.

Parâmetro Tipo Obrigatório/default Descrição
job_id string required
lines integer 200
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

job_stop

Para job local ou remoto trackeado.

Parâmetro Tipo Obrigatório/default Descrição
job_id string required
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

job_retry

Reinicia job local ou remoto trackeado que foi parado ou saiu.

Parâmetro Tipo Obrigatório/default Descrição
job_id string required
purpose string \| null null
explanation string \| null null
machine string \| null null
idempotency_key string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

Arquivos e transferências

file_list

Lista arquivos e diretórios localmente ou em máquina remota.

Parâmetro Tipo Obrigatório/default Descrição
path string "."
recursive boolean false
max_entries integer 500
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

file_tree

Retorna árvore compacta de diretórios localmente ou em máquina remota.

Parâmetro Tipo Obrigatório/default Descrição
cwd string "."
depth integer 3
max_entries integer 500
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

file_glob

Encontra paths por glob localmente ou em máquina remota.

Parâmetro Tipo Obrigatório/default Descrição
pattern string required
cwd string "."
max_results integer 500
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

file_grep

Pesquisa conteúdo de arquivos localmente ou em máquina remota.

Parâmetro Tipo Obrigatório/default Descrição
query string required
cwd string "."
glob string \| null null
regex boolean true
case_sensitive boolean true
max_results integer \| null null
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

file_read

Lê um arquivo ou lista de arquivos localmente ou em máquina remota.

Parâmetro Tipo Obrigatório/default Descrição
path string \| array[string] required
start_line integer \| null null
end_line integer \| null null
binary_preview string \| null null
binary_preview_bytes integer 256
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

image_view

Exibe PNG, JPEG, GIF ou WebP como conteúdo de imagem MCP nativo localmente ou em máquina remota. Use em vez de file_read quando inspeção visual for necessária. Imagens remotas reutilizam o protocolo de transferência existente, então o worker não precisa de RPC específico de imagem.

Parâmetro Tipo Obrigatório/default Descrição
path string required
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

file_write

Escreve arquivo de texto UTF-8 localmente ou em máquina remota.

Parâmetro Tipo Obrigatório/default Descrição
path string required
content string required
overwrite boolean true
encoding string "utf-8"
purpose string \| null null
explanation string \| null null
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

file_edit

Aplica um ou mais edits de texto exatos a um arquivo local ou remoto. Cada edit contém old, new e replace_all opcional; old deve corresponder exatamente, incluindo whitespace e indentation.

Parâmetro Tipo Obrigatório/default Descrição
path string required
edits array[TextEdit] required
purpose string \| null null
explanation string \| null null
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

file_delete

Exclui arquivo ou diretório local ou remoto. recursive=false exclui arquivos ou diretórios vazios; diretórios não vazios exigem recursive=true, que deve ser usado com cuidado.

Parâmetro Tipo Obrigatório/default Descrição
path string required
recursive boolean false
purpose string \| null null
explanation string \| null null
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

file_patch

Verifica e aplica unified diff ou envelope file_patch local ou remotamente.

Parâmetro Tipo Obrigatório/default Descrição
patch string required
cwd string "."
purpose string \| null null
explanation string \| null null
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

remote_transfer

Inicia um job rastreado que copia um arquivo ou diretório entre o controller e máquinas remotas. Uploads remotos usam chunks raw-binary retomáveis; gerencie a transferência com job_list, job_tail, job_stop e job_retry.

Parâmetro Tipo Obrigatório/default Descrição
source_path string required
destination_path string required
source_machine string \| null null
destination_machine string \| null null
overwrite boolean false
chunk_size integer \| null null
purpose string \| null null
explanation string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Pelo menos um de source_machine e destination_machine deve ser informado. Endpoints omitidos referem-se ao workspace do controller; a origem pode ser arquivo ou diretório.

Cria URL temporária acessível por browser para arquivo local. Por default a resposta baixa como attachment; defina inline=true para render direto em browser ou imagem Markdown. Links são bearer URLs públicas protegidas por token de alta entropia, TTL, limite opcional de downloads e revogação explícita.

Parâmetro Tipo Obrigatório/default Descrição
path string required
ttl_s integer \| null null
filename string \| null null
max_downloads integer \| null null
inline boolean false
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Lista URLs de download de arquivos locais geradas.

Parâmetro Tipo Obrigatório/default Descrição
include_expired boolean false
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Revoga URL de download de arquivo local gerada.

Parâmetro Tipo Obrigatório/default Descrição
token string required
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Gateway MCP dinâmico

mcp_manage

Registra, lista, obtém, habilita, desabilita, refresh, remove ou atualiza environment/headers isolados de servidores MCP dinâmicos. Use transport stdio com command/args/cwd ou streamable_http com url. Valores secret env/header são persistidos privadamente e nunca retornados.

Parâmetro Tipo Obrigatório/default Descrição
action string required
name string \| null null
transport string \| null null
command string \| null null
args array[string] \| null null
cwd string \| null null
url string \| null null
env object \| null null
headers object \| null null
enabled boolean true
overwrite boolean false
refresh boolean true
key string \| null null
value string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Pesquisa summaries leves cacheados de tools de servidores MCP dinâmicos habilitados. Tools dinâmicas ficam fora de tools/list deste server; use o nome <server>:<tool> retornado com mcp_tool_inspect antes de chamar.

Parâmetro Tipo Obrigatório/default Descrição
query string ""
server string \| null null
limit integer 20
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

mcp_tool_inspect

Retorna schema completo cacheado de uma tool MCP dinâmica chamada <server>:<tool>. Faça refresh do server com mcp_manage se o cache estiver stale.

Parâmetro Tipo Obrigatório/default Descrição
name string required
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

mcp_tool_call

Chama uma tool MCP dinâmica cacheada chamada <server>:<tool>. Descubra com mcp_tool_search e inspecione schema com mcp_tool_inspect primeiro. Conexões MCP externas são abertas apenas durante esta chamada.

Parâmetro Tipo Obrigatório/default Descrição
name string required
arguments object \| null null
timeout_s integer \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Browser automation

browser_session

Inicia, lista, fecha ou limpa sessões browser persistentes de alto nível local ou remotamente. start pode abrir URL, reutilizar profile_id persistente ou carregar storage_state_path; close pode salvar storage state.

Parâmetro Tipo Obrigatório/default Descrição
action string required
session_id string \| null null
browser string "chromium"
headless boolean true
width integer 1440
height integer 1000
url string \| null null
wait_until string "domcontentloaded"
profile_id string \| null null
storage_state_path string \| null null
save_storage_state_path string \| null null
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

browser_snapshot

Captura página browser persistente: title, URL, texto visível limitado, elementos interativos com refs curtas estáveis como e1, erros recentes page/network e path opcional de screenshot. Use as refs diretamente como targets de browser_act até ocorrer navegação ou novo snapshot.

Parâmetro Tipo Obrigatório/default Descrição
session_id string required
page_id string \| null null
include_text boolean true
screenshot boolean true
full_page boolean false
max_text_chars integer 100000
max_elements integer 100
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

browser_act

Executa ações estruturadas em sessão browser persistente. Suporta navigate, new_page, close_page, click, fill, type, select, press, check, uncheck, hover, wait, wait_for_text e wait_for_url. target pode ser ref browser_snapshot como e1 ou selector CSS. Use browser_run_script somente quando as ações de alto nível não bastarem.

Parâmetro Tipo Obrigatório/default Descrição
session_id string required
actions array[object] required
page_id string \| null null
timeout_ms integer 30000
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

browser_run_script

Executa script Python Playwright completo localmente ou em máquina remota.

Parâmetro Tipo Obrigatório/default Descrição
script string required
cwd string "."
timeout_s integer 60
machine string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.

Automação de GUI de desktop

gui_list

Lista local ou remotamente janelas visíveis de aplicativos desktop e as capacidades do backend GUI.

Parâmetro Tipo Obrigatório/padrão Descrição
machine string \| null null
logical_session_id string \| null obrigatório Logical Session desta chamada. Durante a tarefa, passe o session_id retornado por session_manage. Use null somente quando nenhuma Logical Session estiver ativa.

Escopos OAuth: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é informado, a chamada também exige remote:use e é executada pelo protocolo do worker remoto.

gui_state

Observa uma janela desktop antes de agir. Retorna elementos de acessibilidade, uma captura MCP nativa opcional e um state_id de curta duração. Prefira ações por element_id; coordenadas são relativas à janela observada e são rejeitadas se ela foi movida ou redimensionada.

Parâmetro Tipo Obrigatório/padrão Descrição
window_id string obrigatório
screenshot boolean true
include_elements boolean true
max_elements integer 300
max_depth integer 12
machine string \| null null
logical_session_id string \| null obrigatório Logical Session desta chamada. Durante a tarefa, passe o session_id retornado por session_manage. Use null somente quando nenhuma Logical Session estiver ativa.

Escopos OAuth: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é informado, a chamada também exige remote:use e é executada pelo protocolo do worker remoto.

gui_action

Executa ações GUI local ou remotamente sobre uma observação gui_state recente. O state_id é de uso único. Prefira element_id semântico; coordenadas x/y brutas são relativas à janela. Suporta click, double_click, right_click, move, scroll, drag, type, key, set_value, focus e wait.

Parâmetro Tipo Obrigatório/padrão Descrição
window_id string obrigatório
state_id string obrigatório
actions array[GuiAction] obrigatório
machine string \| null null
logical_session_id string \| null obrigatório Logical Session desta chamada. Durante a tarefa, passe o session_id retornado por session_manage. Use null somente quando nenhuma Logical Session estiver ativa.

Escopos OAuth: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é informado, a chamada também exige remote:use e é executada pelo protocolo do worker remoto.

Administração de remote workers

remote_manage

Gerencia remote workers com action=invite, list, reset, revoke ou rename. invite aceita name/workdir/ttl_s/max_uses; revoke exige machine; rename exige machine e new_name. max_uses tem valor padrão 1. reset exige machine e limpa solicitações de controle na fila ou ativas que podem ser canceladas com segurança, sem desconectar o worker; operações protegidas já iniciadas são preservadas.

Parâmetro Tipo Obrigatório/default Descrição
action string required
name string \| null null
workdir string \| null null
ttl_s integer \| null null
max_uses integer 1
machine string \| null null
new_name string \| null null
logical_session_id string \| null required Logical Session desta chamada de tool. Enquanto trabalha na tarefa, passe o session_id retornado por session_manage. Use null somente quando não houver Logical Session ativa.

OAuth scopes: shell:read, shell:write, shell:execute, browser:use, file:share, remote:use.

Quando machine é fornecido, a chamada também exige remote:use e é executada pelo protocolo de remote worker.