> ## Documentation Index
> Fetch the complete documentation index at: https://www.macaly.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Server MCP Macaly Cloud
> Lascia che Claude, ChatGPT, Cursor, Grok Bot o Codex scrivano il codice: Macaly lo esegue, lo compila e lo ospita
Macaly Cloud è un server [MCP](https://modelcontextprotocol.io) che trasforma Macaly nell'infrastruttura del tuo agente di sviluppo AI. Il tuo agente scrive ogni riga di codice; Macaly fornisce il repository git, la sandbox cloud, il database e le capacità della piattaforma, la build, l'anteprima condivisibile e l'hosting in produzione su `macaly.app`.
Sul tuo computer non viene generato nulla e l'agente di Macaly non entra mai in azione. L'app vive nel tuo workspace Macaly fin dal primo file, così puoi aprirla nell'editor di Macaly quando vuoi e continuare a lavorarci lì.
## Cosa ti serve
Ti serve un client MCP che supporti i server remoti via Streamable HTTP: Claude (claude.ai, Desktop, Cowork), Claude Code, ChatGPT, Cursor, Grok Bot o Codex.
## Collega il tuo client
Claude, ChatGPT, Cursor e Grok Bot installano Macaly Cloud dalle loro directory ufficiali. In Macaly, **Impostazioni → Connessioni** ha una scheda per ciascuno di loro con gli stessi passaggi e un link alla voce nella directory. Gli altri client aggiungono il server all'indirizzo:
```
https://www.macaly.com/api/cloud/mcp
```
In entrambi i casi il client apre una finestra del browser in cui accedi a Macaly e approvi l'accesso (OAuth). Non c'è nessuna chiave da copiare.
1. Apri la [scheda di Macaly Cloud](https://claude.ai/directory/macaly-cloud) nella directory dei connettori di Claude. Funziona su claude.ai, nell'app desktop e su mobile.
2. Fai clic su **Connect**.
3. Accedi a Macaly e approva l'accesso nella finestra che si apre.
Esegui nel terminale:
```bash theme={null}
claude mcp add macaly-cloud --transport http https://www.macaly.com/api/cloud/mcp
```
Poi avvia Claude Code ed esegui `/mcp` per accedere a Macaly.
1. Apri il [plugin Macaly Cloud](https://chatgpt.com/plugins/plugin_asdk_app_6a732e22122c8191ac404137c0514300) nella directory dei plugin di ChatGPT. Lo stesso plugin funziona nel browser e nell'app desktop.
2. Fai clic su **Install**.
3. Quando ChatGPT chiede di collegare il tuo account, accedi a Macaly e approva l'accesso nella finestra che si apre.
1. Apri il [plugin Macaly Cloud](https://cursor.com/marketplace/macaly) nel Cursor Marketplace e aggiungilo. Puoi anche eseguire `/add-plugin macaly-code` nella chat di Cursor.
2. Quando Cursor apre il browser, accedi a Macaly e approva l'accesso.
1. In Grok Bot, seleziona **Plugins** nella barra laterale. Nell'app mobile, tocca il tuo avatar e seleziona **Plugins**.
2. Cerca **Macaly Cloud** e aggiungilo.
3. Quando Grok Bot ti chiede **Authorize**, accedi a Macaly e approva l'accesso nel browser.
4. Verifica che il plugin compaia in **Installed**. Da quel momento è disponibile per ogni Bot che esegui.
Esegui nel terminale:
```bash theme={null}
codex mcp add macaly-cloud --url https://www.macaly.com/api/cloud/mcp
codex mcp login macaly-cloud
```
### Usare una chiave API
Puoi autenticarti con una [chiave API di Macaly](/docs/it/api/authentication) invece che con OAuth: utile per agenti headless e automazioni. Passa la chiave come bearer token:
```json theme={null}
{
"mcpServers": {
"macaly-cloud": {
"url": "https://www.macaly.com/api/cloud/mcp",
"headers": {
"Authorization": "Bearer macaly_your_api_key_here"
}
}
}
}
```
Le chiavi API valgono per un solo workspace, quindi gli strumenti che accettano un `teamId` lo ricavano da sole.
## Costruisci un'app dall'inizio alla fine
Il tuo agente chiama `create_app` con un nome. Riceve un `chatId` e il briefing del progetto. L'app nasce vuota: nessun prompt iniziale, nessuna build AI.
`write_file` scrive un file intero, mentre `edit_file` sostituisce un testo esatto in un file esistente, così una piccola modifica a un file grande non richiede di inviare di nuovo l'intero file. Ogni chiamata a `write_file`, `edit_file` e `delete_file` è un commit git atomico con una voce dedicata nella cronologia dell'app. La prima scrittura su un workspace freddo richiede 20-30 secondi in più, il tempo che la sandbox si avvii.
Per database, pagamenti, AI, media o ricerca, l'agente legge la guida con `skill_info` ed esegue i suoi comandi con `bash`: la sandbox contiene già le credenziali richieste dalle guide.
Dopo l'ultima scrittura l'agente esegue `bash ".sandbox/check-errors --strict"`: individua errori di tipi, di stili e del server in un colpo solo, termina con un riepilogo del risultato ed esce con un errore quando TypeScript o CSS non superano il controllo. In caso di errore, `get_logs` restituisce l'output reale.
L'anteprima viene ricompilata automaticamente pochi secondi dopo l'ultima scrittura. Quando la build riesce, `preview_app` restituisce l'URL live da aprire o condividere. Con `path`, il link apre direttamente una sottopagina, per esempio `/pricing`. L'agente chiama `preview_app` alla fine di ogni turno in cui ha modificato l'app, anche quando un link precedente è ancora valido: questa chiamata comunica a Macaly che il turno è terminato.
Quando chiedi esplicitamente di andare online, l'agente chiama `publish_app` e interroga `get_deployment` con il `deploymentId` restituito finché lo stato non è `READY`. Poi ti fornisce `liveUrl`, l'indirizzo della versione online. `connect_domain` collega un dominio personalizzato o rinomina il sottodominio Macaly.
## Strumenti disponibili
Macaly Cloud espone 20 strumenti.
### Workspace e app
| Strumento | Cosa fa |
| - | - |
| `list_teams` | Elenca i workspace in cui puoi costruire |
| `create_app` | Crea una nuova app vuota sullo stack predefinito e ne restituisce il briefing |
| `list_projects` | Elenca le app di un workspace, dalle più recenti, con ricerca e paginazione. Le app fissate compaiono nella prima pagina |
| `get_project` | Stato del progetto: build dell'anteprima, URL di anteprima, stato dell'ultima pubblicazione e `liveUrl`, briefing e chi sta lavorando sull'app |
| `get_messages` | Legge la cronologia della chat dell'app - cosa è stato chiesto e cosa è già stato costruito - prima di fare modifiche |
| `duplicate_app` | Duplica un'app con la sua cronologia in una nuova |
### Codice
| Strumento | Cosa fa |
| - | - |
| `list_files` | Elenca i file sorgente dell'app |
| `read_file` | Legge un file dal suo percorso, oppure solo un intervallo di righe con `startLine` ed `endLine` |
| `write_file` | Scrive un file per intero e lo committa subito |
| `edit_file` | Sostituisce un testo esatto in un file esistente e lo committa subito: fino a 20 sostituzioni per chiamata, applicate tutte o nessuna |
| `delete_file` | Elimina un file e committa subito la cancellazione |
| `bash` | Esegue un comando shell nella sandbox dell'app: installazioni, CLI, script delle skill e il controllo `.sandbox/check-errors --strict`. Un comando può avere fino a 32.000 caratteri ed essere eseguito per un massimo di 240 secondi |
### Media
| Strumento | Cosa fa |
| - | - |
| `upload_file` | Aggiunge un file alla libreria media dell'app e restituisce il suo URL pubblico permanente (fino a 1 GB). Il file arriva da un URL pubblicamente raggiungibile, oppure dal tuo computer o dalla sandbox dell'app tramite un comando `curl` pronto all'uso |
| `list_media` | Elenca i file della libreria media dell'app con i loro URL pubblici e fornisce un link in cui trascinare un file locale |
Nessuno strumento accetta i byte grezzi di un file. Per un file sul tuo computer, `upload_file` restituisce un comando `curl` che il tuo agente esegue nella tua shell. Per un file che l'agente ha creato nella sandbox, esegue il comando nella sandbox. Se il tuo agente non ha una shell, trascina il file nella libreria media tramite il link di `list_media`.
Non mettere immagini, audio e video generati o scaricati nella cartella `public/` dell'app. Ogni build dell'anteprima carica di nuovo `public/`, quindi file numerosi o pesanti rallentano la build e possono farla fallire. Carica i media con `upload_file` e usa l'URL restituito.
### Capacità e diagnostica
| Strumento | Cosa fa |
| - | - |
| `skill_info` | Legge la guida di una capacità della piattaforma, con comandi pronti all'uso e i pattern di codice da applicare |
| `get_logs` | Recupera i log di build, dev server o deployment |
| `preview_app` | Restituisce un link di anteprima valido tre ore da condividere, anche per una sottopagina |
### Pubblicazione
| Strumento | Cosa fa |
| - | - |
| `publish_app` | Pubblica l'app in produzione sul suo URL `macaly.app` |
| `get_deployment` | Verifica l'ultimo tentativo di pubblicazione (o quello indicato da `deploymentId`), `liveUrl` e i domini collegati |
| `connect_domain` | Collega un dominio personalizzato o rinomina il sottodominio Macaly |
## Cloud actions
Le Cloud actions sono le operazioni che il tuo agente esterno esegue tramite Macaly Cloud. Il piano Gratuito include **100 Cloud actions al mese**. I piani a pagamento non hanno un limite mensile di Cloud actions.
Vengono conteggiate queste azioni:
* Creare o duplicare un'app (`create_app`, `duplicate_app`)
* Scrivere, modificare o eliminare file (`write_file`, `edit_file`, `delete_file`)
* Eseguire comandi (`bash`)
* Caricare file (`upload_file`)
* Pubblicare (`publish_app`)
* Collegare un dominio (`connect_domain`)
Leggere file (`read_file`), elencarli e le anteprime (`preview_app`) sono gratuiti. Chattare con l'agente di Macaly dentro l'app non usa Cloud actions.
La soglia del piano Gratuito è condivisa dall'intero workspace, si azzera il 1° di ogni mese (UTC) e non si accumula. Quando è esaurita, le ulteriori azioni conteggiate vengono rifiutate con la data di azzeramento e un link a Fatturazione. Le letture, le app già online e la chat con Macaly dentro l'app continuano a funzionare. Fatturazione e **Impostazioni → Utilizzo e limiti** mostrano quante Cloud actions hai usato. Vedi [Utilizzo e limiti](/docs/it/account/workspaces/usage).
## Lavorare insieme all'editor di Macaly
Un'app costruita con Macaly Cloud è un'app Macaly come le altre. Puoi aprirla nell'editor, consultare la cronologia delle versioni, tornare indietro o proseguire con l'agente di Macaly.
* **Ogni modifica viene registrata.** Ogni scrittura porta una breve spiegazione del tuo agente, che compare nella cronologia della chat come una scheda con il nome del client che l'ha eseguita: così l'agente di Macaly ha il contesto se poi continui lì. Quando termina una sessione con più modifiche, la sua scheda riassume cosa è cambiato.
* **Puoi tornare indietro.** Clicca su **Ripristina la versione precedente** su una scheda per riportare l'app com'era dopo quella sessione. Tutto ciò che viene dopo sparisce dalla chat. **Duplica** copia quella versione in un nuovo progetto.
* **Una scheda per ogni turno.** Macaly non vede i messaggi che invii al tuo agente, solo le sue chiamate agli strumenti. Una sessione termina quando il tuo agente ti restituisce l'app con `preview_app` o `publish_app`. Se salta questa chiamata, più richieste tue possono finire in un'unica scheda.
* **Un solo agente alla volta.** Mentre lavora il tuo agente esterno la chat è bloccata: l'agente di Macaly non avvia un turno e il campo di scrittura indica chi ha l'app in mano. Il blocco si libera da solo qualche minuto dopo l'ultima scrittura, o non appena il tuo agente ti mostra l'anteprima.
* **L'anteprima aspetta l'app finita.** Le build intermedie vengono trattenute, così il pannello continua a mostrare l'app che avevi già finché la sessione non termina.
## Esempi di prompt
```
Costruiscimi un'app su Macaly: una landing page per un abbonamento
al caffè con hero, prezzi e modulo di iscrizione via e-mail.
```
```
Aggiungi un interruttore per la modalità scura alla mia app del caffè
su Macaly, controlla i tipi e dammi il link dell'anteprima.
```
```
Configura un database per la mia app del caffè e salvaci le iscrizioni
via e-mail.
```
```
Pubblica l'app del caffè e collega il dominio coffee.example.com.
```
## Risoluzione dei problemi
Verifica che il tuo client supporti i server MCP remoti con OAuth e di aver inserito l'URL completo, incluso il percorso `/api/cloud/mcp`.
L'app è in mano a qualcun altro: l'agente di Macaly è a metà di un turno, oppure un altro editor esterno ha scritto di recente. Attendi e riprova: il blocco si libera da solo qualche minuto dopo l'ultima attività.
L'output della build è troppo grande o contiene troppi file, di solito media in `public/`. `get_logs` con `log_type: "build"` mostra il numero e la dimensione dei file. Sposta i media fuori da `public/` con `upload_file`, usa gli URL restituiti e lascia che l'anteprima venga ricompilata.
Le anteprime vengono servite da una build completata. Controlla `previewBuildStatus` con `get_project` e, se è fallita, leggi `get_logs` con `log_type: "build"`.
Il piano Gratuito include 100 Cloud actions al mese. Il messaggio di rifiuto mostra la data in cui si azzerano (il 1° del mese, UTC) e un link a Fatturazione. Letture e anteprime continuano a funzionare. Passa a Starter o Pro per eliminare il limite mensile.
O il workspace su cui stai operando ha Macaly Cloud disattivato, oppure l'azione richiede una funzionalità di piano che non hai, per esempio la pubblicazione su un dominio personalizzato.
Ancora bloccato? Scrivici dalla chat in Macaly o consulta le [FAQ](/docs/it/welcome/faq).
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.