Configurare MCP e gli agenti

La CLI di Cloud Noce include un server MCP su stdio che espone progetti, ambienti, servizi, domini, variabili, log, build e release come strumenti strutturati per assistenti AI: Claude Code, Cursor, Codex, GitHub Copilot, OpenCode, Grok, Devin, Pi, Gemini Antigravity e qualsiasi client compatibile con MCP. Dal tuo editor o terminale puoi chiedere all’assistente di creare un servizio o eseguirne il deploy, leggere i log o configurare variabili di ambiente. L’assistente non deve ottenere un accesso indipendente al token: viene usato quello della CLI salvato con gerdoo login.

Configurazione con un solo comando

Dopo aver installato la CLI, esegui gerdoo setup agent nella radice del progetto. Il comando scrive la configurazione MCP per tutti gli assistenti riconosciuti e installa la skill use-gerdoo, che spiega all’assistente come usare gli strumenti di Cloud Noce.

Procedura di configurazione

Installa la CLI e accedi

Se non hai ancora installato gerdoo, esegui curl -fsSL https://get.gerdoo.cloud/install.sh | sh, poi accedi con gerdoo login. Il comando apre Cloud Noce nel browser, dove confermi l’accesso; la password non viene mai inserita nel terminale. Il server MCP usa lo stesso token salvato, senza un’autenticazione separata.

Collega l’assistente a Cloud Noce

Nella radice del progetto su cui lavora l’assistente esegui:


gerdoo setup agent

Per impostazione predefinita, il comando configura MCP per tutti gli strumenti supportati e installa use-gerdoo. Se ne usi solo uno, specificalo con --agent.

Verifica la connessione

Riapri l’editor o il terminale, oppure ricarica i server MCP, e chiedi all’assistente di mostrare i tuoi servizi o progetti. Se nell’elenco degli strumenti compaiono quelli con prefisso gerdoo_*, la connessione è attiva.

Flag di `gerdoo setup agent`


gerdoo setup agent [--agent claude-code|cursor|codex|copilot|opencode|devin|pi|grok|antigravity|print]
                   [--skill-only] [--no-skill] [--global]

Flag	Descrizione
`--agent <name>`	Configura solo lo strumento indicato; senza questo flag vengono configurati tutti. `print` stampa la configurazione nei quattro formati comuni invece di scrivere file, per usarla in qualsiasi strumento compatibile con MCP.
`--skill-only`	Installa solo la skill `use-gerdoo`, senza modificare MCP.
`--no-skill`	Scrive solo la configurazione MCP, senza installare la skill.
`--global`	Installa la skill nel percorso utente globale (`~/.claude/skills/use-gerdoo`) anziché nella cartella del progetto (`.claude/skills/use-gerdoo`).

Puoi eseguire di nuovo il comando senza problemi: i file esistenti non vengono sovrascritti integralmente, ma vengono aggiornate soltanto le voci di configurazione di Cloud Noce.

Dove viene configurato ogni strumento?

Strumento	File di configurazione
Claude Code	`.mcp.json` nella radice del progetto; le altre voci restano invariate.
Grok	Legge gli stessi `.mcp.json` e `.cursor/mcp.json`; non richiede una configurazione separata.
Cursor	`.cursor/mcp.json` nella radice del progetto, con la stessa struttura.
Codex CLI	Tabella `[mcp_servers.gerdoo]` in `.codex/config.toml`, senza modificare il resto del file.
GitHub Copilot	`.vscode/mcp.json`, nel formato VS Code con chiave `servers` e `type: stdio`.
OpenCode	`opencode.json` nella radice del progetto, con chiave `mcp` e `type: local`.
Devin	`.devin/mcp_config.json` nella radice del progetto.
Pi	`.pi/mcp.json` nella radice del progetto.
Gemini Antigravity	`.agents/mcp_config.json` nella radice del progetto, formato condiviso da IDE e CLI Antigravity.

Se usi un altro strumento MCP, oppure uno configurato da un pannello web senza file locali, esegui gerdoo setup agent --agent print per stampare i quattro formati comuni. gerdoo mcp è un server stdio standard e funziona con qualsiasi client MCP.

Il comando `gerdoo mcp`

Se preferisci scrivere la configurazione manualmente, avvia il server MCP su ingresso e uscita standard, stdio, con:


gerdoo mcp

Normalmente non viene eseguito direttamente: l’assistente lo avvia come sottoprocesso. Il comando gerdoo deve essere presente nel PATH dell’ambiente in cui gira l’assistente. Su macchine senza browser, come CI e server remoti, puoi impostare GERDOO_TOKEN invece di usare gerdoo login.

Strumenti disponibili per l’assistente

Il server MCP di Cloud Noce fornisce più di 40 strumenti che coprono l’intera API:

Account: gerdoo_whoami restituisce l’email dell’account e un riepilogo dei servizi con totale, suddivisione per stato ed elenco breve; è una buona prima chiamata per conoscere la situazione dell’account.
Costi: gerdoo_get_pricing restituisce il listino a consumo in toman (IRT): CPU e RAM orarie, disco mensile, traffico in uscita e minuti di build. Indicando le dimensioni del servizio, calcola anche una stima mensile. gerdoo_get_spending mostra saldo del portafoglio, spesa del mese corrente e servizi più costosi.
Progetti e ambienti: elenco, dettagli e creazione di nuovi progetti e ambienti.
Servizi: elenco, dettagli, creazione da immagini Docker, deploy da cartelle locali (gerdoo_deploy_service_source), aggiornamento della configurazione, avvio, arresto e riavvio.
Variabili: sia la mappa env semplice sia l’archivio tipizzato build-time/secret. Tutti i nomi sono visibili, ma i valori segreti e quelli sensibili in env vengono nascosti con [redacted].
Domini: aggiunta, verifica e rimozione di domini personalizzati con i relativi record DNS.
Database e Add-on gestiti: gerdoo_add_database crea con una sola chiamata un Add-on PostgreSQL, Redis, MinIO, RabbitMQ, MariaDB o MongoDB e lo collega al servizio, inserendo automaticamente variabili come DATABASE_URL e REDIS_URL; sono disponibili anche creazione, elenco, collegamento e scollegamento degli Add-on.
Template del Marketplace: elenco e dettagli dei template e deploy in un solo passaggio tramite gerdoo_deploy_template. Immagini e credenziali provengono sempre dal catalogo della piattaforma e le password generate non vengono restituite all’assistente.
Rete interna: gerdoo_get_service restituisce l’indirizzo interno (internal_address) e l’elenco dei servizi dello stesso progetto; gerdoo_list_services restituisce internal_host per ogni servizio. Per collegare i servizi tra loro usa il nome interno, non l’indirizzo pubblico.
Osservazione e diagnosi: gerdoo_diagnose_service restituisce con una chiamata stato del servizio, log del container, ultima build e relativo log, oltre alla spiegazione dell’errore di build. gerdoo_get_logs accetta level, grep, since e invert e indica quante righe corrispondono. gerdoo_exec esegue un singolo comando nel container di un servizio attivo. Sono disponibili anche elenchi di build e release e metriche del traffico tramite gerdoo_get_metrics.
Ticket di assistenza: creazione, lettura, risposta e chiusura tramite gerdoo_create_ticket e altri strumenti per problemi di competenza della piattaforma.
Deploy da cartelle locali: se la build fallisce, gerdoo_deploy_service_source include la diagnosi nel campo diagnosis, evitando chiamate aggiuntive per comprendere la causa.
Operazioni sensibili: eliminazione di servizi o progetti, rollback e sospensione richiedono tutti confirm: true e sono contrassegnati in MCP come distruttivi, così che il client chieda conferma all’utente prima dell’esecuzione.

Privacy e ambito di accesso

gerdoo_whoami restituisce soltanto l’email dell’account corrente; MCP non invia all’assistente telefono, indirizzo o informazioni identificative. Tuttavia, gli strumenti usano il token completo dell’account CLI: l’assistente può gestire tutti i progetti e servizi dell’account, non soltanto quello corrente. Prima di confermare eliminazioni, rollback o sospensioni, verifica sempre che progetto e servizio siano quelli corretti.

Risorse di riferimento

Oltre agli strumenti, il server MCP pubblica risorse consultabili dall’assistente per leggere i valori corretti invece di indovinarli:

Risorsa	Contenuto
`gerdoo://catalog/templates`	Elenco aggiornato dei template disponibili per il deploy per questo account
`gerdoo://catalog/addon-kinds`	Tipi di Add-on e variabili di connessione inserite da ciascuno
`gerdoo://catalog/frameworks`	Valori ammessi per `framework`, predefinito `auto`
`gerdoo://reference/variable-precedence`	Precedenza degli archivi di variabili e sintassi `${{ }}`
`gerdoo://reference/service-statuses`	Significato di ogni stato del servizio e azione appropriata

La skill `use-gerdoo`

use-gerdoo è una guida operativa installata con la CLI. Indica all’assistente quali strumenti usare per creare servizi, eseguire il deploy della cartella corrente, diagnosticare problemi tramite log e build e gestire variabili e domini. Sottolinea soprattutto che l’assistente deve chiedere una conferma esplicita prima di ogni operazione distruttiva.

gerdoo upgrade aggiorna anche la skill installata, a meno che tu non l’abbia modificata: in quel caso viene conservata e compare un messaggio.


# Installa solo la skill, senza modificare MCP
gerdoo setup agent --skill-only
 
# Installazione globale per tutti i progetti
gerdoo setup agent --skill-only --global