Ferramentas do MCP

As 19 ferramentas que o agente recebe quando conecta o MCP, hospedado ou local. A lista sai direto do servidor, então está sempre igual ao que o agente vê

Limites

Ler e gravar arquivos direto: até 1 MB. Maior que isso, o agente usa get_upload_url e get_download_url.
exec espera até 600 s. Para mais tempo, start_job e job_wait (até 600 s por espera).
Cada ferramenta pede um escopo na chave. Os escopos estão em Chaves e segurança.

Lista

Abra os parâmetros de cada ferramenta para ver o que ela recebe.

list_boxes

Listar boxessó lê

Lista as boxes do workspace (mais novas primeiro), com estado, tamanho, custo e metadados. Filtre por estado ou por metadados (ex.: {"kind": "render"}).

Escopo:boxes:read

5 parâmetros

statearray: Só boxes nestes estados.
metadataobject: Só boxes com estes pares de metadados.
includeDeletedboolean: Incluir as apagadas.
limitinteger: Itens por página (1–100, padrão 20).
cursorstring: nextCursor da página anterior.

get_box

Ver boxsó lê

Mostra uma box: estado e motivo, tamanho, políticas de ociosidade, operação em andamento, custo e comando SSH.

Escopo:boxes:read

1 parâmetro

boxIdstringobrigatório: Id (bx_…) ou nome da box.

Cria uma box (computador Linux na nuvem). Por padrão espera ela ficar running (até 120 s). Ociosa, ela dorme sozinha; apague com delete_box quando terminar. Use metadata.kind para o tipo de tarefa (ex.: render, testes).

Escopo:boxes:write

16 parâmetros

namestring: Nome (minúsculas, números e hífen; até 40). Sem nome, o servidor escolhe.
templatestring: Template (padrão: o do workspace).
templateVersionstring
snapshotIdstring
vcpus: Núcleos: 2, 4, 8, 16 ou 32 (o plano limita).
memMiB: Memória em MiB: 4096, 8192, 16384, 32768 ou 65536 (até 2048 × vcpus).
dataGiBinteger: Disco em GiB (20–500).
autoSuspendSecondsinteger: Dorme depois de tantos segundos ociosa: 0 (nunca, só pago) ou 300–1800 em minutos inteiros.
maxRunMinutesinteger: Pausa depois de tantos minutos rodando (-1 ilimitado, só pago).
deleteAfterSecondsinteger: Apaga sozinha depois de tantos segundos (60–86400).
metadataobject: Até 32 pares texto→texto. metadata.kind = tipo de tarefa (aparece no uso por tipo).
secretsarray: Nomes dos Secrets do workspace que a box pode usar.
taskobject
setupobject
idempotencyKeystring: Chave de idempotência: repetir a chamada com a mesma chave e os mesmos argumentos não cria outra.
waitboolean: Esperar a box ficar running (padrão true). false devolve na hora.

delete_box

Apagar boxmuda ou apaga

Apaga a box e todos os arquivos dela, em qualquer estado. Não tem volta: exige confirm: true. Salve antes o que precisa (read_file, get_download_url ou save_snapshot).

Escopo:boxes:delete

3 parâmetros

boxIdstringobrigatório: Id (bx_…) ou nome da box.
confirmboolean: Precisa ser true: a box e os arquivos dela somem.
waitboolean: Esperar a box ser apagada (padrão true). false devolve na hora.

suspend_box

Pausar boxcria ou muda

Pausa a box guardando memória e processos (para de cobrar CPU e memória). Pausada por você, ela só volta com resume_box.

Escopo:boxes:write

2 parâmetros

boxIdstringobrigatório: Id (bx_…) ou nome da box.
waitboolean: Esperar a operação terminar (padrão true). false devolve na hora.

resume_box

Retomar boxcria ou muda

Retoma uma box pausada ou desligada. Volta com os processos quando foi pausada; desligada, liga do zero.

Escopo:boxes:write

2 parâmetros

boxIdstringobrigatório: Id (bx_…) ou nome da box.
waitboolean: Esperar a operação terminar (padrão true). false devolve na hora.

fork_box

Copiar boxcria ou muda

Cria de 1 a 5 cópias da box (disco igual, sem a memória), no mesmo nó. Por padrão espera as cópias ficarem prontas.

Escopo:boxes:write

6 parâmetros

countinteger: Quantas cópias (1–5, padrão 1).
namesarray: Nomes das cópias (opcional).
metadataobject
boxIdstringobrigatório: Id (bx_…) ou nome da box.
idempotencyKeystring: Chave de idempotência: repetir a chamada com a mesma chave e os mesmos argumentos não cria outra.
waitboolean: Esperar as cópias ficarem prontas (padrão true). false devolve na hora.

exec

Executar comandomuda ou apaga

Roda um comando na box e devolve o ExecResult (stdout, stderr, exitCode, durationMs). Passe cmd (texto para o bash) ou argv. Até 600 s e 1 MB por stream; para mais tempo, use start_job. Acorda a box se ela dormiu por ociosidade.

Escopo:boxes:exec

8 parâmetros

cmdstring: Comando em texto, rodado com bash -lc.
argvarray: Comando como lista de argumentos (sem shell).
cwdstring: Pasta de trabalho (padrão /data/home).
envobject: Variáveis de ambiente extras.
timeoutSecondsinteger: Prazo em segundos (1–600, padrão 60).
stdinstring: Entrada padrão.
stdinEncodingutf8 | base64: utf8 (padrão) ou base64.
boxIdstringobrigatório: Id (bx_…) ou nome da box.

start_job

Iniciar jobmuda ou apaga

Inicia um comando longo em segundo plano (sem prazo) e devolve o job. Acompanhe com job_logs e job_wait. Enquanto roda, a box não dorme por ociosidade.

Escopo:boxes:exec

7 parâmetros

namestring: Nome do job (opcional).
cmdstring: Comando em texto, rodado com bash -lc.
argvarray: Comando como lista de argumentos (sem shell).
cwdstring: Pasta de trabalho (padrão /data/home).
envobject: Variáveis de ambiente extras.
boxIdstringobrigatório: Id (bx_…) ou nome da box.
idempotencyKeystring: Chave de idempotência: repetir a chamada com a mesma chave e os mesmos argumentos não cria outra.

job_logs

Saída do jobsó lê

Lê a saída de um job (stdout e stderr juntos). Use offset para continuar de onde parou, ou tail para as últimas linhas.

Escopo:boxes:read

4 parâmetros

boxIdstringobrigatório: Id (bx_…) ou nome da box.
jobIdstringobrigatório: Id do job (job_…).
offsetinteger: Byte de onde começar (o nextOffset da leitura anterior).
tailinteger: Só as últimas N linhas.

job_wait

Esperar jobsó lê

Espera o job terminar (até timeoutSeconds, no máximo 600 s) e devolve o job com status e exitCode. Ainda rodando no fim do prazo: status running.

Escopo:boxes:read

3 parâmetros

boxIdstringobrigatório: Id (bx_…) ou nome da box.
jobIdstringobrigatório: Id do job (job_…).
timeoutSecondsinteger: Quanto esperar (1–600 s, padrão 300).

read_file

Ler arquivosó lê

Lê um arquivo de até 1 MB da box. Texto UTF-8 volta em encoding utf8; o resto, em base64. Para arquivos maiores ou pastas, use get_download_url.

Escopo:boxes:read

2 parâmetros

boxIdstringobrigatório: Id (bx_…) ou nome da box.
pathstringobrigatório: Caminho na box (absoluto, ou relativo a /data/home).

write_file

Gravar arquivomuda ou apaga

Grava um arquivo de até 1 MB na box (troca atômica; cria as pastas que faltam). Texto em UTF-8, ou encoding: base64 para binário. Para arquivos maiores, use get_upload_url.

Escopo:boxes:write

6 parâmetros

boxIdstringobrigatório: Id (bx_…) ou nome da box.
pathstringobrigatório: Caminho na box (absoluto, ou relativo a /data/home).
contentstringobrigatório: Conteúdo (UTF-8, ou base64 com encoding: base64).
encodingutf8 | base64: utf8 (padrão) ou base64.
modestring: Permissões em octal (padrão 0644).
parentsboolean: Criar as pastas que faltam (padrão true).

get_upload_url

URL de enviocria ou muda

Gera uma URL assinada (1 h) para enviar um arquivo grande (até 5 GB) direto para a box com um PUT. Ex.: curl -X PUT -H 'Content-Type: application/octet-stream' --data-binary @arquivo '<url>'.

Escopo:boxes:write

3 parâmetros

boxIdstringobrigatório: Id (bx_…) ou nome da box.
pathstringobrigatório: Caminho na box (absoluto, ou relativo a /data/home).
modestring: Permissões em octal (padrão 0644).

get_download_url

URL de downloadsó lê

Gera uma URL assinada (1 h) para baixar um arquivo de qualquer tamanho da box com um GET. Para uma pasta, mande archive: true (vem como tar.zst, até 2 GB).

Escopo:boxes:read

3 parâmetros

boxIdstringobrigatório: Id (bx_…) ou nome da box.
pathstringobrigatório: Caminho na box (absoluto, ou relativo a /data/home).
archiveboolean: true para baixar uma pasta como tar.zst.

publish_port

Publicar portacria ou muda

Publica uma porta da box numa URL HTTPS. Privada (padrão) exige o accessToken devolvido (só aparece agora); pública abre para qualquer um.

Escopo:boxes:write

4 parâmetros

portintegerobrigatório: Porta na box (1–65535).
protocolhttp | tcp: http (padrão) ou tcp.
visibilityprivate | public: private (padrão) ou public.
boxIdstringobrigatório: Id (bx_…) ou nome da box.

save_snapshot

Salvar snapshotcria ou muda

Salva o disco da box num snapshot (para criar boxes iguais depois com create_box snapshotId). Por padrão espera até 60 s.

Escopo:images:write

4 parâmetros

namestring: Nome do snapshot (opcional).
metadataobject
boxIdstringobrigatório: Id (bx_…) ou nome da box.
waitboolean: Esperar o snapshot ficar pronto (padrão true). false devolve na hora.

list_snapshots

Listar snapshotssó lê

Lista os snapshots do workspace (mais novos primeiro), opcionalmente só os de uma box.

Escopo:images:read

3 parâmetros

boxIdstring: Só os snapshots desta box (id ou nome).
limitinteger: Itens por página (1–100, padrão 20).
cursorstring: nextCursor da página anterior.

get_usage

Uso do mêssó lê

Resumo do gasto do workspace no mês (fuso de São Paulo): total, previsão, franquia do plano e o gasto por tipo de tarefa, box, agente e pessoa, em reais e em centavos.

Escopo:nenhum

1 parâmetro

periodstring: Mês AAAA-MM (padrão: o corrente).