​

Desenvolva um aplicativo Base44 remotamente por MCP

Início mais fácil: no editor do aplicativo Base44, clique em Send to Coding Agent. Para um agente local, isso fornece um prompt pronto para colar (que busca um README e opera o sandbox via MCP ou a CLI base44 sandbox — Seção 10); para a web, isso fornece um prompt para colar em um chat da claude.ai (com o conector MCP da Base44) mais um botão Open Claude. O botão é a superfície de descoberta — o resto desta habilidade é a referência.

Dois transportes: agentes web usam claude.ai com o conector MCP da Base44 (Seções 1–9) — observe que este é o chat regular da claude.ai, não Claude Code na web (claude.ai/code), que roda em seu próprio sandbox apoiado por repo. Um agente local pode conectar esse mesmo servidor MCP, ou operar o sandbox com a CLI base44 sandbox (um token da CLI Base44, Seção 10) — mesmas ferramentas, mesmo comportamento, mesmos códigos de erro; a CLI apenas os expõe sob nomes de comando mais curtos (sandbox read, sandbox ls, …).

​

1. Conectar o servidor MCP

https://app.base44.com/mcp

claude mcp add --transport http base44 https://app.base44.com/mcp

​

2. Autenticar

claude

/mcp

​

Escopos

​

3. Escolha o aplicativo e oriente-se

Using the base44 tools on appId <APP_ID>:
1. list_directory on the app root (recursive, depth 2)
2. read_file src/App.jsx and src/pages.config.js
3. grep for the component I want to change
Summarize the structure before editing.

Inicialização a frio: se o aplicativo não tem um sandbox em execução, a primeira chamada de ferramenta o traz de volta de forma transparente do seu último commit — apenas leva um pouco mais de tempo. Chamadas subsequentes são rápidas.

Nomes na CLI: na CLI base44 sandbox (Seção 10), essas ferramentas de leitura são list_directory → sandbox ls, read_file → sandbox read e grep → sandbox grep.

​

4. Fazer alterações

• edit_file (sandbox edit na CLI) — preferido para alterar arquivos existentes. Forneça edições exatas old_text→new_text. Cada old_text deve ser único no arquivo, a menos que você defina replace_all. Todas as edições em uma chamada são aplicadas atomicamente (tudo ou nada) e você recebe um diff unificado de volta. Passe dry_run: true para pré-visualizar o diff sem gravar.
• write_file (sandbox write na CLI) — para criar novos arquivos. Para sobrescrever um arquivo existente, você deve passar overwrite: true (nunca sobrescreve silenciosamente).
• run_command (sandbox run na CLI) — executa qualquer comando bash no sandbox (build, install, scaffolding, codemods). O diretório de trabalho padrão é a raiz do aplicativo; cd não persiste entre chamadas, então use o parâmetro cwd ou encadeie comandos (cd sub && cmd). O tempo limite padrão é 120s (máx 600s); a saída é limitada a ~1 MB.
• create_checkpoint (sandbox checkpoint na CLI) — salva um ponto de restauração nomeado ao qual o usuário pode reverter mais tarde. Recebe um name opcional (mensagem/título; gerado automaticamente se omitido). Quaisquer alterações pendentes são flushadas e commitadas primeiro para que o checkpoint ancore ao seu código mais recente; depois retorna o ID do checkpoint, nome e hash do commit git. Use-o para marcar um estado conhecido bom antes ou depois de um bloco de edições. (Se um auto-commit recente não puder ser confirmado durável ainda, ele recusa com o retryable COMMIT_FLUSH_PENDING em vez de fazer checkpoint do estado obsoleto — tente novamente em breve.)

On appId <APP_ID>, use edit_file to change the homepage heading in
src/pages/Home.jsx from "Welcome" to "Welcome back". Show me the diff first
with dry_run, then apply it.

​

5. Pré-visualizar e verificar (o loop edit → check)

• Veja ao vivo: get_app_preview_url inicia o servidor de dev e retorna a URL de pré-visualização. O Vite HMR reflete suas edições enquanto você as faz.
• Status do build: get_app_status retorna ready / processing / error.
• Faça surgir erros de build/type/lint sob demanda com run_command:
  npm run build       # bundler/compile errors
  npx tsc --noEmit    # type errors
  npm run lint        # lint errors
  
• Leia os logs do dev-server (Vite) — o dev server gerenciado grava em /tmp/vite.log. Faça tail via run_command para ver erros de HMR/compile:
  tail -c 32000 /tmp/vite.log
  
  (Isto está fora da árvore do aplicativo, então só é alcançável por run_command, não pelas ferramentas de arquivo — e, portanto, precisa de sandbox:write.)

Erros de runtime do navegador (um componente que compila mas lança na renderização, uma chamada de API de cliente com falha) aparecem no console do navegador, não em /tmp/vite.log. Abra a URL de pré-visualização para capturá-los.

​

6. Como suas alterações persistem

• sobrevive à morte do sandbox (o sandbox é recriado do último commit),
• aparece nas abas Library/Data do construtor,
• mantém implantações de função de backend consistentes, e
• é incluída quando você publica o aplicativo.

• Há uma pequena janela de perda (~5s) — não mate a sessão imediatamente após a última edição; dê um momento para commitar.
• Edições a entidades, agentes, workflows, funções de backend e roteamento de página são sincronizadas na Base44 automaticamente após o commit. Edições simples de página/componente/CSS ficam no git e não precisam de nada mais.

​

7. Concorrência: você vs. o construtor Base44

• Enquanto você está usando ativamente as ferramentas do sandbox, o chat do construtor Base44 é bloqueado (“An external agent is currently working on this app”). Sua sessão é implícita — chamadas de ferramenta recentes são a sessão; ela termina após um curto período de inatividade (~10 min).
• Se o construtor Base44 está no meio de um build, suas ferramentas de mutação retornam BUILDER_BUSY. Faça polling em get_app_status e tente novamente quando estiver ready. Ferramentas somente leitura ainda funcionam durante um build.

​

8. Guardrails e limites

• Caminhos são confinados ao aplicativo. As ferramentas de arquivo operam apenas dentro do diretório do aplicativo; caminhos de travessia/absolutos são rejeitados (PATH_OUTSIDE_SANDBOX).
• .agents/ é fora dos limites para ferramentas de arquivo (PROTECTED_PATH) — ele contém configuração e segredos gerenciados por agente (.agents/.env). Não tente ler ou editar por meio das ferramentas de arquivo.
• Limites de taxa se aplicam por aplicativo: leituras ~120/min, mutações ~60/min, comandos ~30/min. Se você atingir RATE_LIMITED, diminua a velocidade.
• delete_file não é uma ferramenta dedicada — exclua via run_command rm.

​

Códigos de erro que você pode ver

​

9. Dicas e truques

• Leia antes de escrever. Uma passagem rápida de list_directory + read_file (ou grep) custa pouco e melhora dramaticamente a precisão da edição.
• Use dry_run no edit_file para confirmar o diff antes de se comprometer com uma alteração, especialmente para chamadas de várias edições.
• Prefira edit_file em vez de write_file para arquivos existentes — edições cirúrgicas evitam sobrescrever e produzem um diff revisável.
• Leia intervalos de linhas com offset/limit de read_file em arquivos grandes em vez de puxar tudo para o contexto.
• Quando algo “parece quebrado”, faça tail em /tmp/vite.log antes de adivinhar — geralmente nomeia o arquivo e a linha exatos.
• Deixe commitar. Pause alguns segundos após sua edição final para que o auto-commit chegue antes de desconectar ou publicar.
• Checkpoint em estados conhecidos bons. Use create_checkpoint (sandbox checkpoint) para marcar um ponto de restauração antes ou depois de um bloco arriscado de edições — ele flusha as alterações pendentes primeiro, para que o usuário possa sempre reverter a esse ponto.
• Um agente por vez. O recurso é projetado para um único agente externo por aplicativo; não execute sessões paralelas contra o mesmo aplicativo.

​

10. Agentes locais via a CLI base44 sandbox

npx base44 sandbox read --app-id <APP_ID> src/App.jsx

npx base44 sandbox checkpoint --app-id <APP_ID> --name "before refactor"

https://app.base44.com/api/sandbox/<APP_ID>/local-agent/readme.md

​

11. Conectores (integrações OAuth)

• Escopos declarativos (substituir, não mesclar). initiate_connector_connection define o conector para exatamente os scopes que você passa. Escopos omitidos são removidos e o usuário é reprocurado para consentir. Sempre chame list_connectors primeiro, depois passe o conjunto desejado completo (escopos existentes que você quer manter mais quaisquer novos).
• OAuth precisa de um humano. A ferramenta retorna already_authorized: true (nada a fazer) ou uma redirect_url que o usuário deve abrir em um navegador para fazer login e consentir — você não pode concluí-la sozinho. Depois que ele terminar, chame list_connectors novamente para verificar e ler os escopos concedidos (um provedor pode conceder menos do que solicitado).