​

Desarrollar remotamente una app de Base44 sobre MCP

Inicio más fácil: en el editor de app de Base44, haz clic en Send to Coding Agent. Para un agente local te da un prompt listo para pegar (que obtiene un README y controla el sandbox sobre MCP o la CLI base44 sandbox — Sección 10); para la web te da un prompt para pegar en un chat de claude.ai (con el conector MCP de Base44) más un botón Open Claude. El botón es la superficie de descubrimiento — el resto de esta habilidad es la referencia.

Dos transportes: los agentes web usan claude.ai con el conector MCP de Base44 (Secciones 1-9) — ten en cuenta que este es el chat regular de claude.ai, no Claude Code en la web (claude.ai/code), que se ejecuta en su propio sandbox respaldado por repositorio. Un agente local puede conectar ese mismo servidor MCP, o controlar el sandbox con la CLI base44 sandbox (un token CLI de Base44, Sección 10) — mismas herramientas, mismo comportamiento, mismos códigos de error; la CLI simplemente las expone bajo nombres de comando más cortos (sandbox read, sandbox ls, …).

​

1. Conectar el servidor MCP

https://app.base44.com/mcp

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

​

2. Autenticar

claude

/mcp

​

Ámbitos

​

3. Elegir la app y orientarse

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.

Arranque en frío: si la app no tiene un sandbox en ejecución, la primera llamada de herramienta lo inicia de forma transparente desde tu último commit — solo tarda un poco más. Las llamadas posteriores son rápidas.

Nombres de CLI: sobre la CLI base44 sandbox (Sección 10) estas herramientas de lectura son list_directory → sandbox ls, read_file → sandbox read, y grep → sandbox grep.

​

4. Hacer cambios

• edit_file (sandbox edit en la CLI) — preferido para cambiar archivos existentes. Proporciona ediciones old_text→new_text exactas. Cada old_text debe ser único en el archivo a menos que establezcas replace_all. Todas las ediciones en una llamada se aplican atómicamente (todo o nada) y obtienes un diff unificado de vuelta. Pasa dry_run: true para previsualizar el diff sin escribir.
• write_file (sandbox write en la CLI) — para crear nuevos archivos. Para sobrescribir un archivo existente debes pasar overwrite: true (nunca sobrescribe silenciosamente).
• run_command (sandbox run en la CLI) — ejecuta cualquier comando bash en el sandbox (build, install, scaffolding, codemods). El directorio de trabajo por defecto es la raíz de la app; cd no persiste entre llamadas, así que usa el parámetro cwd o encadena comandos (cd sub && cmd). El tiempo de espera es 120s por defecto (máx. 600s); la salida está limitada a ~1 MB.
• create_checkpoint (sandbox checkpoint en la CLI) — guarda un punto de restauración con nombre al que el usuario puede volver más tarde. Toma un name opcional (mensaje/título; autogenerado si se omite). Cualquier cambio pendiente se descarga y confirma primero, para que el checkpoint se ancle a tu código más reciente; luego devuelve el id del checkpoint, nombre y hash de commit de git. Úsalo para marcar un estado conocido como bueno antes o después de un bloque de ediciones. (Si un auto-commit reciente no puede confirmarse como duradero aún, rechaza con el reintentable COMMIT_FLUSH_PENDING en lugar de hacer checkpoint del estado obsoleto — reintenta en 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. Previsualizar y verificar (el bucle editar → comprobar)

• Verlo en vivo: get_app_preview_url inicia el servidor de desarrollo y devuelve la URL de vista previa. Vite HMR refleja tus ediciones a medida que las haces.
• Estado de compilación: get_app_status devuelve ready / processing / error.
• Muestra errores de build/tipo/lint bajo demanda con run_command:
  npm run build       # errores de bundler/compilación
  npx tsc --noEmit    # errores de tipo
  npm run lint        # errores de lint
  
• Lee los registros del servidor de desarrollo (Vite) — el servidor de desarrollo gestionado escribe en /tmp/vite.log. Sigúelo mediante run_command para ver errores de HMR/compilación:
  tail -c 32000 /tmp/vite.log
  
  (Esto está fuera del árbol de la app, por lo que solo es accesible a través de run_command, no de las herramientas de archivo — y por tanto necesita sandbox:write.)

Los errores de runtime del navegador (un componente que compila pero lanza al renderizar, una llamada de API cliente fallida) aparecen en la consola del navegador, no en /tmp/vite.log. Abre la URL de vista previa para detectar esos.

​

6. Cómo persisten tus cambios

• sobreviva a la muerte del sandbox (el sandbox se recrea desde el último commit),
• aparezca en las pestañas Library/Data del builder,
• mantenga consistentes los despliegues de funciones de backend, y
• se incluya cuando publiques la app.

• Hay una pequeña ventana de pérdida (~5s) — no mates la sesión inmediatamente después de la última edición; dale un momento para confirmar.
• Las ediciones a entidades, agentes, workflows, funciones de backend y enrutamiento de página se sincronizan a Base44 automáticamente después del commit. Las ediciones simples de página/componente/CSS viven en git y no necesitan nada extra.

​

7. Concurrencia: tú vs. el builder de Base44

• Mientras estás usando activamente las herramientas del sandbox, el chat del builder de Base44 está bloqueado (“An external agent is currently working on this app”). Tu sesión es implícita — las llamadas de herramienta recientes son la sesión; termina después de un breve período de inactividad (~10 min).
• Si el builder de Base44 está a mitad de compilación, tus herramientas mutantes devuelven BUILDER_BUSY. Sondea get_app_status y reintenta una vez que esté ready. Las herramientas de solo lectura aún funcionan durante una compilación.

​

8. Salvaguardas y límites

• Las rutas están confinadas a la app. Las herramientas de archivo operan solo dentro del directorio de la app; las rutas de recorrido/absolutas se rechazan (PATH_OUTSIDE_SANDBOX).
• .agents/ está fuera de los límites de las herramientas de archivo (PROTECTED_PATH) — contiene configuración y secretos gestionados por el agente (.agents/.env). No intentes leerlo o editarlo a través de las herramientas de archivo.
• Los límites de tasa se aplican por app: lecturas ~120/min, mutaciones ~60/min, comandos ~30/min. Si golpeas RATE_LIMITED, ralentiza.
• delete_file no es una herramienta dedicada — elimina mediante run_command rm.

​

Códigos de error que puedes ver

​

9. Consejos y trucos

• Lee antes de escribir. Un rápido list_directory + read_file (o grep) cuesta poco y mejora dramáticamente la precisión de la edición.
• Usa dry_run en edit_file para confirmar el diff antes de comprometerte a un cambio, especialmente para llamadas de múltiples ediciones.
• Prefiere edit_file sobre write_file para archivos existentes — las ediciones quirúrgicas evitan sobrescribir y producen un diff revisable.
• Lee rangos de líneas con offset/limit de read_file en archivos grandes en lugar de traer todo al contexto.
• Cuando algo “parece roto”, sigue /tmp/vite.log antes de adivinar — suele nombrar el archivo y línea exactos.
• Deja que se comprometa. Pausa unos segundos después de tu edición final para que el auto-commit llegue antes de desconectarte o publicar.
• Marca estados conocidos como buenos. Usa create_checkpoint (sandbox checkpoint) para marcar un punto de restauración antes o después de un bloque arriesgado de ediciones — descarga los cambios pendientes primero, para que el usuario pueda revertir siempre a ese punto.
• Un agente a la vez. La función está diseñada para un único agente externo por app; no ejecutes sesiones paralelas contra la misma app.

​

10. Agentes locales mediante la 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 (integraciones OAuth)

• Alcances declarativos (reemplazar, no fusionar). initiate_connector_connection establece el conector a exactamente los scopes que pases. Los alcances omitidos se eliminan y se pide al usuario que vuelva a consentir. Siempre llama primero a list_connectors, luego pasa el conjunto completo deseado (alcances existentes que quieres mantener más cualquier nuevo).
• OAuth necesita un humano. La herramienta devuelve already_authorized: true (nada que hacer) o una redirect_url que el usuario debe abrir en un navegador para iniciar sesión y consentir — no puedes completarlo tú mismo. Después de que terminen, llama a list_connectors de nuevo para verificar y leer los alcances concedidos (un proveedor puede conceder menos de los solicitados).