> ## 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. # Sviluppa un'app Base44 da remoto tramite MCP > Vendored from base44-dev/apper PR #11608 Questa pagina fa parte di una skill per agenti di codifica IA ed è scritta per gli agenti, non per gli esseri umani. Per la documentazione Base44 leggibile dagli umani, consulta la [documentazione per sviluppatori](/developers). # Sviluppa un'app Base44 da remoto tramite MCP Collega il tuo agente di codifica alla sandbox di un'app Base44 e sviluppa direttamente al suo interno — esegui comandi, leggi e modifica file, usa grep, elenca le directory — mentre Base44 fornisce la sandbox e tu fornisci l'agente e l'LLM. Funziona con qualsiasi client MCP-compatibile. Gli esempi usano Claude Code. > **Inizio più semplice:** nell'editor dell'app Base44, clicca su **Send to Coding Agent**. Per un agente locale ti fornisce un prompt pronto da incollare (che recupera un README e guida la sandbox tramite MCP o la CLI `base44 sandbox` — Sezione 10); > per il web ti fornisce un prompt da incollare in una chat **claude.ai** (con il connettore MCP di Base44) > più un pulsante **Open Claude**. Il pulsante è la superficie di scoperta — il resto di questa skill è > il riferimento. > **Due trasporti:** gli agenti web usano **claude.ai** con il **connettore MCP** di Base44 (Sezioni > 1–9) — nota che questa è la normale chat di claude.ai, *non* Claude Code sul web (`claude.ai/code`), > che gira nella sua sandbox basata su repo. Un agente locale può collegarsi allo stesso server MCP, oppure > guidare la sandbox con la **CLI `base44 sandbox`** (un token CLI di Base44, Sezione 10) — stessi strumenti, > stesso comportamento, stessi codici di errore; la CLI li espone semplicemente sotto nomi di comando più brevi > (`sandbox read`, `sandbox ls`, …). *** ## 1. Collega il server MCP L'endpoint MCP di Base44 è: ``` https://app.base44.com/mcp ``` Registralo con Claude Code (esegui da qualsiasi cartella): ```bash theme={null} claude mcp add --transport http base44 https://app.base44.com/mcp ``` Aggiungi `--scope user` se lo vuoi disponibile in ogni progetto invece che solo nella cartella corrente. `claude mcp add` scrive solo la configurazione — non autentica ancora. ## 2. Autenticati Avvia Claude Code e apri il menu MCP: ```bash theme={null} claude ``` poi, all'interno di Claude Code: ``` /mcp ``` Seleziona **base44** → **Authenticate**. Si apre un browser per il flusso OAuth di Base44 (PKCE) — accedi e approva. Quando ha successo, `/mcp` mostra **base44** come connesso ed elenca i suoi strumenti. **Client puri da CLI / headless** che non possono aprire un browser usano invece il flusso device OAuth (`/oauth/device/code`) — richiedono un codice, lo approvano in un browser su un altro dispositivo e il client riceve il token. ### Scopes | Strumenti | Scope richiesto | | ------------------------------------------------------------------------------------------------ | --------------------------------- | | `read_file`, `grep`, `list_directory`, `get_app_preview_url`, `get_app_status`, `list_user_apps` | `apps:read` (concesso di default) | | `write_file`, `edit_file`, `run_command`, `create_checkpoint` | `sandbox:write` | `sandbox:write` **non** è concesso di default — le mutazioni di shell e file lo richiedono esplicitamente. Se gli strumenti di lettura funzionano ma quelli di mutazione restituiscono `NOT_AUTHORIZED`, al tuo token manca `sandbox:write`; riconnettiti e concedi l'accesso alla sandbox (il flusso device può richiederlo esplicitamente). *** ## 3. Scegli l'app e orientati Ogni strumento richiede un `appId` obbligatorio. Trova le tue app con `list_user_apps`, poi fissa l'id nelle tue richieste così che l'agente lo passi a ogni chiamata. Inizia in **sola lettura** per costruire un modello mentale prima di cambiare qualcosa: ``` 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. ``` > **Avvio a freddo:** se l'app non ha una sandbox in esecuzione, la prima chiamata dello strumento ne avvia una in modo trasparente dall'ultimo commit — richiede solo un po' più di tempo. Le chiamate successive sono veloci. > **Nomi CLI:** tramite la CLI `base44 sandbox` (Sezione 10) questi strumenti di lettura sono > `list_directory` → `sandbox ls`, `read_file` → `sandbox read`, e > `grep` → `sandbox grep`. *** ## 4. Apporta modifiche * **`edit_file`** (`sandbox edit` nella CLI) — preferito per modificare file esistenti. Fornisci modifiche esatte `old_text`→`new_text`. Ogni `old_text` deve essere unico nel file a meno che non imposti `replace_all`. Tutte le modifiche in una chiamata vengono applicate atomicamente (tutto o niente) e ricevi un diff unificato. Passa `dry_run: true` per visualizzare il diff senza scrivere. * **`write_file`** (`sandbox write` nella CLI) — per creare nuovi file. Per sovrascrivere un file esistente devi passare `overwrite: true` (non lo sovrascrive mai silenziosamente). * **`run_command`** (`sandbox run` nella CLI) — esegue qualsiasi comando bash nella sandbox (build, install, scaffolding, codemods). La directory di lavoro predefinita è la radice dell'app; `cd` non persiste tra le chiamate, quindi usa il parametro `cwd` o concatena i comandi (`cd sub && cmd`). Il timeout predefinito è 120s (max 600s); l'output è limitato a \~1 MB. * **`create_checkpoint`** (`sandbox checkpoint` nella CLI) — salva un punto di ripristino nominato a cui l'utente può tornare in seguito. Accetta un `name` opzionale (messaggio/titolo; generato automaticamente se omesso). Eventuali modifiche in sospeso vengono **scaricate e committate prima** così che il checkpoint si ancori al tuo codice più recente; restituisce quindi l'id del checkpoint, il nome e l'hash del commit git. Usalo per contrassegnare uno stato noto e funzionante prima o dopo un blocco di modifiche. (Se un auto-commit recente non può ancora essere confermato durevole, rifiuta con il codice ritentabile `COMMIT_FLUSH_PENDING` invece di fare il checkpoint di uno stato obsoleto — riprova a breve.) Esempio: ``` 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. Anteprima e verifica (il ciclo modifica → controllo) Non esiste uno strumento di streaming dei log in tempo reale, ma puoi chiudere il ciclo di feedback: * **Vedilo in diretta:** `get_app_preview_url` avvia il server di sviluppo e restituisce l'URL di anteprima. Vite HMR riflette le tue modifiche mentre le apporti. * **Stato della build:** `get_app_status` restituisce `ready` / `processing` / `error`. * **Mostra errori di build/tipo/lint su richiesta** con `run_command`: ```bash theme={null} npm run build # bundler/compile errors npx tsc --noEmit # type errors npm run lint # lint errors ``` * **Leggi i log del server di sviluppo (Vite)** — il server di sviluppo gestito scrive su `/tmp/vite.log`. Fai il tail tramite `run_command` per vedere gli errori HMR/compile: ```bash theme={null} tail -c 32000 /tmp/vite.log ``` (Questo è fuori dall'albero dell'app, quindi è raggiungibile solo tramite `run_command`, non tramite gli strumenti sui file — e quindi richiede `sandbox:write`.) Un ciclo solido: `edit_file` → `npm run build` (o tail `/tmp/vite.log`) → correggi eventuali errori → `get_app_preview_url` per verificare visivamente. > **Gli errori runtime del browser** (un componente che compila ma genera errori al render, > una chiamata API client fallita) appaiono nella console del browser, non in > `/tmp/vite.log`. Apri l'URL di anteprima per rilevarli. *** ## 6. Come persistono le tue modifiche Non devi "salvare". Ogni chiamata di mutazione pianifica un **auto-commit con debounce** (\~5 secondi): la modifica viene committata e inviata allo storage del codice di Base44, così: * sopravvive alla morte della sandbox (la sandbox viene ricreata dall'ultimo commit), * appare nelle schede Library/Data del builder, * mantiene coerenti i deploy delle funzioni backend, e * è inclusa quando pubblichi l'app. Implicazioni pratiche: * C'è una piccola finestra di perdita (\~5s) — non chiudere la sessione subito dopo l'ultima modifica; dagli un momento per committare. * Le modifiche a entità, agenti, workflow, funzioni backend e routing delle pagine vengono sincronizzate automaticamente in Base44 dopo il commit. Le semplici modifiche a pagine/componenti/CSS vivono in git e non richiedono nulla di extra. *** ## 7. Concorrenza: tu contro il builder di Base44 Tu e il builder Base44 in-app non potete mutare la stessa app contemporaneamente: * **Mentre stai usando attivamente gli strumenti della sandbox**, la chat del builder Base44 è bloccata ("An external agent is currently working on this app"). La tua sessione è implicita — le chiamate recenti agli strumenti *sono* la sessione; termina dopo un breve periodo di inattività (\~10 min). * **Se il builder Base44 è in fase di build**, i tuoi strumenti di mutazione restituiscono `BUILDER_BUSY`. Fai polling di `get_app_status` e riprova quando è `ready`. Gli strumenti di sola lettura funzionano ancora durante una build. *** ## 8. Guardrail e limiti * **I percorsi sono confinati all'app.** Gli strumenti sui file operano solo all'interno della directory dell'app; i percorsi traversal/assoluti vengono rifiutati (`PATH_OUTSIDE_SANDBOX`). * **`.agents/` è off-limits agli strumenti sui file** (`PROTECTED_PATH`) — contiene configurazioni e segreti gestiti dagli agenti (`.agents/.env`). Non tentare di leggerlo o modificarlo tramite gli strumenti sui file. * **I limiti di frequenza** si applicano per app: letture \~120/min, mutazioni \~60/min, comandi \~30/min. Se raggiungi `RATE_LIMITED`, rallenta. * **`delete_file` non è uno strumento dedicato** — elimina tramite `run_command rm`. ### Codici di errore che puoi vedere `NOT_AUTHORIZED` (scope/flag mancante) · `APP_NOT_FOUND` (id errato o nessun accesso) · `PATH_OUTSIDE_SANDBOX` · `PROTECTED_PATH` · `NOT_FOUND` · `BINARY_FILE` · `EDIT_TEXT_NOT_FOUND` · `EDIT_TEXT_NOT_UNIQUE` (rendi `old_text` unico o usa `replace_all`) · `OVERWRITE_NOT_ALLOWED` (passa `overwrite: true`) · `TIMEOUT` · `OUTPUT_TRUNCATED` · `BUILDER_BUSY` · `COMMIT_FLUSH_PENDING` (un auto-commit in sospeso non è ancora durevole; riprova a breve — per esempio su `create_checkpoint`) · `RATE_LIMITED` · `BACKEND_ERROR`. I messaggi sono scritti in modo che l'agente possa auto-correggersi — leggili e adattati. *** ## 9. Suggerimenti e trucchi * **Leggi prima di scrivere.** Un rapido `list_directory` + `read_file` (o `grep`) costa poco e migliora notevolmente la precisione delle modifiche. * **Usa `dry_run` su `edit_file`** per confermare il diff prima di impegnarti in una modifica, specialmente per chiamate multi-edit. * **Preferisci `edit_file` a `write_file`** per i file esistenti — modifiche chirurgiche evitano sovrascritture e producono un diff revisionabile. * **Leggi intervalli di righe** con `offset`/`limit` di `read_file` su file grandi invece di caricare tutto nel contesto. * **Quando qualcosa "sembra rotto", fai tail di `/tmp/vite.log`** prima di indovinare — di solito nomina il file e la riga esatti. * **Lascialo committare.** Fai una pausa di qualche secondo dopo la modifica finale così che l'auto-commit atterri prima che ti disconnetti o pubblichi. * **Checkpoint di stati noti e funzionanti.** Usa `create_checkpoint` (`sandbox checkpoint`) per contrassegnare un punto di ripristino prima o dopo un blocco di modifiche rischiose — scarica prima le modifiche in sospeso, così l'utente può sempre tornare a quel punto. * **Un agente alla volta.** La funzionalità è progettata per un singolo agente esterno per app; non eseguire sessioni parallele sulla stessa app. *** ## 10. Agenti locali tramite la CLI `base44 sandbox` Se il tuo agente gira sulla tua macchina, può guidare la stessa sandbox tramite la CLI di Base44 invece che MCP, autenticandosi con la CLI di Base44 invece che con OAuth. Stessi strumenti, stesso comportamento, stessi codici di errore (Sezione 8) — differiscono solo la superficie e l'autenticazione. **Autenticazione.** Accedi con la CLI di Base44 (`base44 login`) — la stessa credenziale usata per `base44 functions deploy`. Come i comandi `base44 connectors` senza progetto, i sottocomandi sandbox risolvono l'id dell'app da `--app-id`, poi `BASE44_APP_ID`, poi un `.app.jsonc` locale; non è richiesto alcun `config.jsonc`. **Nomi dei comandi.** La CLI espone ogni strumento sandbox sotto un nome più breve: | Strumento 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` accetta un `--name` opzionale (messaggio/titolo) e salva un punto di ripristino: ```bash theme={null} npx base44 sandbox checkpoint --app-id --name "before refactor" ``` **Passa a un agente il riferimento completo** per un'app specifica (istruzioni, pubblico, non richiede autenticazione per il recupero): ``` https://app.base44.com/api/sandbox//local-agent/readme.md ``` (L'equivalente cloud/MCP è `.../api/sandbox//claude-web/readme.md`.) Tutto il resto in questa skill — il ciclo modifica→anteprima→verifica (Sezione 5), la persistenza (Sezione 6), la concorrenza (Sezione 7) e i guardrail (Sezione 8) — si applica identicamente; differiscono solo la superficie e l'autenticazione. *** ## 11. Connettori (integrazioni OAuth) Oltre agli strumenti sandbox su file/shell, il server MCP di Base44 espone due strumenti per gestire un connettore OAuth di terze parti (Google Calendar, Gmail, Slack, …) su un'app. Non toccano il filesystem della sandbox — operano direttamente sullo stato del connettore dell'app. Entrambi accettano `appId`. | Strumento | Scope | Scopo | | ------------------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `list_connectors` | `apps:read` | Elenca i connettori dell'app. Senza `integrationTypes`, restituisce il catalogo completo (nome, descrizione, connesso?, e — se connesso — stato e scope concessi). Passa `integrationTypes` per il dettaglio su specifici. | | `initiate_connector_connection` | `apps:write` | Connetti (o ri-definisci gli scope di) un connettore. Input: `appId`, `integrationType`, `scopes`, `connectionConfig` opzionale. | Due semantiche da capire bene: * **Scope dichiarativi (sostituzione, non fusione).** `initiate_connector_connection` imposta il connettore **esattamente** sugli `scopes` che passi. Gli scope omessi vengono rimossi e all'utente viene richiesto nuovamente il consenso. **Chiama sempre prima `list_connectors`**, poi passa l'insieme desiderato completo (gli scope esistenti che vuoi mantenere **più** quelli nuovi). * **OAuth richiede un umano.** Lo strumento restituisce o `already_authorized: true` (niente da fare) o un `redirect_url` che **l'utente** deve aprire in un browser per accedere e dare il consenso — non puoi completarlo tu stesso. Dopo che ha finito, chiama di nuovo `list_connectors` per verificare e leggere gli scope **concessi** (un provider potrebbe concederne meno di quelli richiesti). Questi richiedono solo `apps:read` / `apps:write` — **non** `sandbox:write`. Sulla superficie CLI (Sezione 10), l'equivalente sono i comandi `base44 connectors` senza progetto (`list-available`, `initiate --integration-type --scopes --app-id `, `pull`), che stampano lo stesso URL di autorizzazione. Questa pagina è stata tradotta utilizzando l'IA. Per informazioni più accurate e aggiornate, consulta la [versione inglese](/).