> ## 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. # Desarrollar remotamente una app de Base44 sobre MCP > Vendored de base44-dev/apper PR #11608 Esta página es parte de una habilidad de agente de codificación con IA y está escrita para agentes, no para humanos. Para la documentación de Base44 legible por humanos, consulta la [documentación para desarrolladores](/developers). # Desarrollar remotamente una app de Base44 sobre MCP Conecta tu propio agente de codificación al sandbox de una app de Base44 y desarrolla en él directamente — ejecuta comandos, lee y edita archivos, haz grep, lista directorios — mientras Base44 proporciona el sandbox y tú proporcionas el agente y el LLM. Esto funciona con cualquier cliente compatible con MCP. Los ejemplos usan Claude Code. > **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 El endpoint MCP de Base44 es: ``` https://app.base44.com/mcp ``` Regístralo con Claude Code (ejecuta desde cualquier carpeta): ```bash theme={null} claude mcp add --transport http base44 https://app.base44.com/mcp ``` Añade `--scope user` si quieres que esté disponible en cada proyecto en lugar de solo en la carpeta actual. `claude mcp add` solo escribe la configuración — aún no autentica. ## 2. Autenticar Inicia Claude Code y abre el menú MCP: ```bash theme={null} claude ``` luego, dentro de Claude Code: ``` /mcp ``` Selecciona **base44** → **Authenticate**. Se abre un navegador para el flujo OAuth de Base44 (PKCE) — inicia sesión y aprueba. Cuando tenga éxito, `/mcp` muestra **base44** como conectado y lista sus herramientas. **Clientes puros de CLI / sin cabezal** que no pueden abrir un navegador usan el flujo OAuth de dispositivo (`/oauth/device/code`) — solicita un código, apruébalo en un navegador en otro dispositivo y el cliente recibe el token. ### Ámbitos | Herramientas | Ámbito requerido | | ------------------------------------------------------------------------------------------------ | ----------------------------------- | | `read_file`, `grep`, `list_directory`, `get_app_preview_url`, `get_app_status`, `list_user_apps` | `apps:read` (concedido por defecto) | | `write_file`, `edit_file`, `run_command`, `create_checkpoint` | `sandbox:write` | `sandbox:write` **no** se concede por defecto — shell y mutación de archivos lo requieren explícitamente. Si las herramientas de lectura funcionan pero las mutantes devuelven `NOT_AUTHORIZED`, a tu token le falta `sandbox:write`; reconecta y concede acceso al sandbox (el flujo de dispositivo puede solicitarlo explícitamente). *** ## 3. Elegir la app y orientarse Cada herramienta toma un `appId` requerido. Encuentra tus apps con `list_user_apps`, luego fija el id en tus solicitudes para que el agente lo pase en cada llamada. Empieza en **solo lectura** para construir un modelo mental antes de cambiar cualquier cosa: ``` 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. ``` > **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.) Ejemplo: ``` 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. Previsualizar y verificar (el bucle editar → comprobar) No hay una herramienta de transmisión de registros en vivo, pero puedes cerrar el bucle de retroalimentación: * **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`: ```bash theme={null} 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: ```bash theme={null} 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`.) Un bucle sólido: `edit_file` → `npm run build` (o `tail /tmp/vite.log`) → arregla cualquier error → `get_app_preview_url` para verlo. > **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 No necesitas "guardar". Cada llamada mutante programa un **auto-commit con debounce** (\~5 segundos): el cambio se confirma y se envía al almacenamiento de código de Base44, para que: * 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. Implicaciones prácticas: * 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 Tú y el builder de Base44 dentro de la app no podéis mutar la misma app a la vez: * **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 `NOT_AUTHORIZED` (ámbito/bandera faltante) · `APP_NOT_FOUND` (id incorrecto o sin acceso) · `PATH_OUTSIDE_SANDBOX` · `PROTECTED_PATH` · `NOT_FOUND` · `BINARY_FILE` · `EDIT_TEXT_NOT_FOUND` · `EDIT_TEXT_NOT_UNIQUE` (haz que `old_text` sea único o usa `replace_all`) · `OVERWRITE_NOT_ALLOWED` (pasa `overwrite: true`) · `TIMEOUT` · `OUTPUT_TRUNCATED` · `BUILDER_BUSY` · `COMMIT_FLUSH_PENDING` (un auto-commit pendiente aún no es duradero; reintenta en breve — por ejemplo, en `create_checkpoint`) · `RATE_LIMITED` · `BACKEND_ERROR`. Los mensajes se escriben para que el agente pueda autocorregirse — léelos y ajusta. *** ## 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` Si tu agente se ejecuta en tu máquina, puede controlar el mismo sandbox a través de la CLI de Base44 en lugar de MCP, autenticándose con la CLI de Base44 en lugar de OAuth. Mismas herramientas, mismo comportamiento, mismos códigos de error (Sección 8) — solo la superficie y auth difieren. **Auth.** Inicia sesión con la CLI de Base44 (`base44 login`) — la misma credencial usada para `base44 functions deploy`. Como los comandos `base44 connectors` sin proyecto, los subcomandos de sandbox resuelven el id de app desde `--app-id`, luego `BASE44_APP_ID`, luego un `.app.jsonc` local; no se requiere `config.jsonc`. **Nombres de comando.** La CLI expone cada herramienta de sandbox bajo un nombre más corto: | Herramienta 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` toma un `--name` opcional (mensaje/título) y guarda un punto de restauración: ```bash theme={null} npx base44 sandbox checkpoint --app-id --name "before refactor" ``` **Entrega a un agente la referencia completa** para una app específica (instrucciones, público, no se necesita auth para obtener): ``` https://app.base44.com/api/sandbox//local-agent/readme.md ``` (El equivalente cloud/MCP es `.../api/sandbox//claude-web/readme.md`.) Todo lo demás en esta habilidad — el bucle editar→previsualizar→verificar (Sección 5), persistencia (Sección 6), concurrencia (Sección 7) y salvaguardas (Sección 8) — se aplica idénticamente; solo la superficie y auth difieren. *** ## 11. Conectores (integraciones OAuth) Más allá de las herramientas de archivo/shell del sandbox, el servidor MCP de Base44 expone dos herramientas para gestionar un conector OAuth de terceros (Google Calendar, Gmail, Slack, …) en una app. No tocan el sistema de archivos del sandbox — operan directamente sobre el estado del conector de la app. Ambas toman `appId`. | Herramienta | Ámbito | Propósito | | ------------------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_connectors` | `apps:read` | Lista los conectores de la app. Sin `integrationTypes`, devuelve el catálogo completo (nombre, descripción, ¿conectado?, y — si está conectado — estado y alcances concedidos). Pasa `integrationTypes` para detalle sobre específicos. | | `initiate_connector_connection` | `apps:write` | Conecta (o re-alcanza) un conector. Entradas: `appId`, `integrationType`, `scopes`, `connectionConfig` opcional. | Dos semánticas que hay que entender bien: * **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). Estos solo necesitan `apps:read` / `apps:write` — **no** `sandbox:write`. Sobre la superficie de CLI (Sección 10), el equivalente son los comandos `base44 connectors` sin proyecto (`list-available`, `initiate --integration-type --scopes --app-id `, `pull`), que imprimen la misma URL de autorización. Esta página fue traducida usando IA. Para obtener la información más precisa y actualizada, consulta la [versión en inglés](/).