> ## Documentation Index > Fetch the complete documentation index at: https://docs.base44.com/llms.txt > Use this file to discover all available pages before exploring further. # Desenvolva um aplicativo Base44 remotamente por MCP > Vendored from base44-dev/apper PR #11608 Esta página faz parte de uma habilidade de agente de código IA e é escrita para agentes, não para humanos. Para a documentação legível por humanos da Base44, veja a [documentação para desenvolvedores](/developers). # Desenvolva um aplicativo Base44 remotamente por MCP Conecte seu próprio agente de codificação ao sandbox de um aplicativo Base44 e desenvolva nele diretamente — execute comandos, leia e edite arquivos, faça grep, liste diretórios — enquanto a Base44 fornece o sandbox e você fornece o agente e o LLM. Isto funciona com qualquer cliente compatível com MCP. Os exemplos usam o Claude Code. > **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 O endpoint MCP da Base44 é: ``` https://app.base44.com/mcp ``` Registre-o no Claude Code (execute de qualquer pasta): ```bash theme={null} claude mcp add --transport http base44 https://app.base44.com/mcp ``` Adicione `--scope user` se você quer disponibilizá-lo em cada projeto em vez de apenas na pasta atual. `claude mcp add` apenas grava a configuração — ainda não autentica. ## 2. Autenticar Inicie o Claude Code e abra o menu MCP: ```bash theme={null} claude ``` depois, dentro do Claude Code: ``` /mcp ``` Selecione **base44** → **Authenticate**. Um navegador abre para o fluxo OAuth da Base44 (PKCE) — faça login e aprove. Quando bem-sucedido, `/mcp` mostra **base44** como conectado e lista suas ferramentas. **Clientes puramente CLI/headless** que não podem abrir um navegador usam o fluxo OAuth device (`/oauth/device/code`) — solicite um código, aprove-o em um navegador em outro dispositivo, e o cliente recebe o token. ### Escopos | Ferramentas | Escopo obrigatório | | ------------------------------------------------------------------------------------------------ | ---------------------------------- | | `read_file`, `grep`, `list_directory`, `get_app_preview_url`, `get_app_status`, `list_user_apps` | `apps:read` (concedido por padrão) | | `write_file`, `edit_file`, `run_command`, `create_checkpoint` | `sandbox:write` | `sandbox:write` **não** é concedido por padrão — shell e mutação de arquivo requerem explicitamente. Se as ferramentas de leitura funcionam, mas as de mutação retornam `NOT_AUTHORIZED`, seu token está sem `sandbox:write`; reconecte e conceda acesso ao sandbox (o fluxo device pode solicitá-lo explicitamente). *** ## 3. Escolha o aplicativo e oriente-se Cada ferramenta recebe um `appId` obrigatório. Encontre seus aplicativos com `list_user_apps`, depois fixe o id nas suas solicitações para que o agente o passe em cada chamada. Comece **somente leitura** para construir um modelo mental antes de alterar qualquer coisa: ``` Using the base44 tools on appId : 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.) Exemplo: ``` On appId , 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) Não há ferramenta de streaming de log ao vivo, mas você pode fechar o loop de feedback: * **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`: ```bash theme={null} 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: ```bash theme={null} 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`.) Um loop sólido: `edit_file` → `npm run build` (ou tail `/tmp/vite.log`) → corrija quaisquer erros → `get_app_preview_url` para dar uma olhada. > **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 Você não precisa "salvar". Cada chamada de mutação agenda um **auto-commit debounced** (\~5 segundos): a alteração é commitada e enviada ao armazenamento de código da Base44, então: * 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. Implicações práticas: * 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 Você e o construtor Base44 no aplicativo não podem mutar o mesmo aplicativo ao mesmo tempo: * **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 `NOT_AUTHORIZED` (escopo/flag ausente) · `APP_NOT_FOUND` (ID errado ou sem acesso) · `PATH_OUTSIDE_SANDBOX` · `PROTECTED_PATH` · `NOT_FOUND` · `BINARY_FILE` · `EDIT_TEXT_NOT_FOUND` · `EDIT_TEXT_NOT_UNIQUE` (torne `old_text` único ou use `replace_all`) · `OVERWRITE_NOT_ALLOWED` (passe `overwrite: true`) · `TIMEOUT` · `OUTPUT_TRUNCATED` · `BUILDER_BUSY` · `COMMIT_FLUSH_PENDING` (um auto-commit pendente ainda não é durável; tente novamente em breve — por exemplo, em `create_checkpoint`) · `RATE_LIMITED` · `BACKEND_ERROR`. As mensagens são escritas para que o agente possa se autocorrigir — leia-as e ajuste. *** ## 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` Se seu agente rodar na sua máquina, ele pode operar o mesmo sandbox pela CLI Base44 em vez de MCP, autenticando com a CLI Base44 em vez de OAuth. Mesmas ferramentas, mesmo comportamento, mesmos códigos de erro (Seção 8) — apenas a superfície e a autenticação diferem. **Autenticação.** Faça login com a CLI Base44 (`base44 login`) — a mesma credencial usada para `base44 functions deploy`. Como os comandos `base44 connectors` sem projeto, os subcomandos sandbox resolvem o ID do aplicativo de `--app-id`, depois `BASE44_APP_ID`, depois um `.app.jsonc` local; nenhum `config.jsonc` é necessário. **Nomes de comando.** A CLI expõe cada ferramenta sandbox sob um nome mais curto: | Ferramenta MCP | Comando CLI | | ------------------- | --------------------------- | | `list_directory` | `base44 sandbox ls` | | `read_file` | `base44 sandbox read` | | `write_file` | `base44 sandbox write` | | `edit_file` | `base44 sandbox edit` | | `run_command` | `base44 sandbox run` | | `grep` | `base44 sandbox grep` | | `create_checkpoint` | `base44 sandbox checkpoint` | ```bash theme={null} npx base44 sandbox read --app-id src/App.jsx ``` `base44 sandbox checkpoint` recebe um `--name` opcional (mensagem/título) e salva um ponto de restauração: ```bash theme={null} npx base44 sandbox checkpoint --app-id --name "before refactor" ``` **Entregue a um agente a referência completa** para um aplicativo específico (instruções, público, nenhuma autenticação necessária para buscar): ``` https://app.base44.com/api/sandbox//local-agent/readme.md ``` (O equivalente para nuvem/MCP é `.../api/sandbox//claude-web/readme.md`.) Todo o resto nesta habilidade — o loop edit→preview→verify (Seção 5), persistência (Seção 6), concorrência (Seção 7) e guardrails (Seção 8) — se aplica de forma idêntica; apenas a superfície e a autenticação diferem. *** ## 11. Conectores (integrações OAuth) Além das ferramentas de arquivo/shell do sandbox, o servidor MCP da Base44 expõe duas ferramentas para gerenciar um conector OAuth de terceiros (Google Calendar, Gmail, Slack, …) em um aplicativo. Elas não tocam no sistema de arquivos do sandbox — operam diretamente no estado do conector do aplicativo. Ambas recebem `appId`. | Ferramenta | Escopo | Propósito | | ------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_connectors` | `apps:read` | Lista os conectores do aplicativo. Sem `integrationTypes`, retorna o catálogo completo (nome, descrição, conectado?, e — se conectado — status e escopos concedidos). Passe `integrationTypes` para detalhes sobre os específicos. | | `initiate_connector_connection` | `apps:write` | Conecta (ou reescopa) um conector. Entradas: `appId`, `integrationType`, `scopes`, opcional `connectionConfig`. | Duas semânticas para acertar: * **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). Estas precisam apenas de `apps:read` / `apps:write` — **não** `sandbox:write`. Na superfície da CLI (Seção 10), o equivalente são os comandos `base44 connectors` sem projeto (`list-available`, `initiate --integration-type --scopes --app-id `, `pull`), que imprimem a mesma URL de autorização. Esta página foi traduzida usando IA. Para informações mais precisas e atualizadas, consulte a [versão em inglês](/).