Server MCP Macaly Cloud - Macaly Documentation

Macaly Cloud è un server MCP 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.

Apri la scheda di Macaly Cloud nella directory dei connettori di Claude. Funziona su claude.ai, nell’app desktop e su mobile.
Fai clic su Connect.
Accedi a Macaly e approva l’accesso nella finestra che si apre.

Esegui nel terminale:

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.

Apri il plugin Macaly Cloud nel Cursor Marketplace e aggiungilo. Puoi anche eseguire /add-plugin macaly-code nella chat di Cursor.
Quando Cursor apre il browser, accedi a Macaly e approva l’accesso.

Esegui nel terminale:

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 invece che con OAuth: utile per agenti headless e automazioni. Passa la chiave come bearer token:

{
  "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

Crea l'app

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.

Scrivi il codice

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.

Aggiungi capacità della piattaforma

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.

Controlla i tipi

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.

Anteprima

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.

Pubblica

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.

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

La finestra di accesso non compare

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.

Una scrittura restituisce CHAT_CLAIMED_BY_AGENT o CHAT_CLAIMED_BY_EDITOR

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à.

La build dell'anteprima fallisce con un timeout di caricamento

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.

L'URL dell'anteprima non mostra ancora nulla

Le anteprime vengono servite da una build completata. Controlla previewBuildStatus con get_project e, se è fallita, leggi get_logs con log_type: "build".

Un'azione viene rifiutata perché ho esaurito le Cloud actions

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.

Uno strumento restituisce FORBIDDEN

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.

​Cosa ti serve

​Collega il tuo client

​Usare una chiave API

​Costruisci un’app dall’inizio alla fine

​Strumenti disponibili

​Workspace e app

​Codice

​Media

​Capacità e diagnostica

​Pubblicazione

​Cloud actions

​Lavorare insieme all’editor di Macaly

​Esempi di prompt

​Risoluzione dei problemi

Cosa ti serve

Collega il tuo client

Usare una chiave API

Costruisci un’app dall’inizio alla fine

Strumenti disponibili

Workspace e app

Codice

Media

Capacità e diagnostica

Pubblicazione

Cloud actions

Lavorare insieme all’editor di Macaly

Esempi di prompt

Risoluzione dei problemi