Come collegare ClickHouse Cloud a Gemini via MCP

💡 Niente installazione? Vai direttamente su cloud.anythingmcp.com. Accedi, clicca Connectors → ClickHouse Cloud, inserisci le credenziali, genera una MCP API key e hai finito. Niente Docker, niente git clone, niente server locale.

ClickHouse Cloud + Gemini

Gestisci un'organizzazione ClickHouse Cloud dal tuo agente AI: elenca i servizi con stato, endpoint e scaling, avviali, fermali o risvegliali, modifica accesso IP, tag e autoscaling, controlla backup e ClickPipes, leggi i costi di utilizzo in ClickHouse Credits e i crediti residui, e consulta notifiche, quote, membri, ruoli, chiavi API e audit log.

Prerequisiti

Le istruzioni di setup complete sono incluse nel connettore stesso (visibili nello store quando lo selezioni). Le variabili d'ambiente richieste sono:

CLICKHOUSE_CLOUD_KEY_ID, CLICKHOUSE_CLOUD_KEY_SECRET

Step 1 — Ottieni le credenziali

La configurazione richiede circa 3 minuti. Ti serve l'accesso alla console ClickHouse Cloud dell'organizzazione.

1. Nella console ClickHouse Cloud (https://console.clickhouse.cloud) apri Organization, API keys e fai clic su New API key.
2. Dai alla chiave un nome, una scadenza, facoltativamente una allow list di IP e il ruolo necessario: per le letture basta un ruolo read-only o developer; avviare, fermare, scalare e modificare i servizi richiede admin o un ruolo personalizzato con il permesso di gestire i servizi.
3. Copia il Key ID in CLICKHOUSE_CLOUD_KEY_ID e il Key secret in CLICKHOUSE_CLOUD_KEY_SECRET. Il secret viene mostrato una sola volta; se lo perdi, crea una nuova chiave. L'API li riceve come HTTP Basic auth (key id come nome utente, secret come password).
4. Installa il connettore ed esegui clickhouse_cloud_list_organizations: restituisce l'organization_id che serve a tutti gli altri tool e conferma la chiave.

Il connettore parla con il control plane di Cloud (https://api.clickhouse.cloud/v1) e non esegue SQL. Per le query sulle tue tabelle installa il connettore ClickHouse, che usa l'interfaccia HTTPS di un servizio.

Cosa legge:

• Organizzazione e chiave: clickhouse_cloud_list_organizations, clickhouse_cloud_get_organization (private endpoint, impostazioni BYOC) e clickhouse_cloud_whoami (la chiave, la sua organizzazione e i ruoli; un endpoint beta di ClickHouse).
• Servizi: clickhouse_cloud_list_services (filtrabile per tag come tag:Environment=Production) e clickhouse_cloud_get_service con stato, cloud provider e regione, versione di ClickHouse, tier, endpoint, memoria e numero di repliche, idle scaling, lista di accesso IP, release channel e tag. clickhouse_cloud_get_service_settings mostra le impostazioni del server diverse dai default, clickhouse_cloud_get_service_metrics le metriche Prometheus attuali in formato testo (filtered_metrics per la lista breve selezionata).
• Backup: clickhouse_cloud_list_backups, clickhouse_cloud_get_backup (stato, inizio e fine, dimensione, durata, completo o incrementale) e clickhouse_cloud_get_backup_configuration (intervallo, conservazione e orario di avvio giornaliero).
• Ingestione: clickhouse_cloud_list_clickpipes e clickhouse_cloud_get_clickpipe per le ClickPipes da Kafka, S3, Postgres, MySQL e altre sorgenti. Richiedono una chiave con il permesso di gestire le ClickPipes.
• Costi e stato: clickhouse_cloud_get_usage_cost per giorno e per entità (data warehouse, servizio, ClickPipe) con le metriche sottostanti (compute, storage, backup, trasferimento dati), clickhouse_cloud_get_credit_balances (richiede il permesso di vedere la fatturazione), clickhouse_cloud_list_notifications (fatturazione, salute dei servizi, errori delle ClickPipes, aggiornamenti; filtrabili per gravità, tipo, risorsa o date) e clickhouse_cloud_list_quotas.
• Persone e accessi: clickhouse_cloud_list_members, clickhouse_cloud_list_invitations, clickhouse_cloud_list_roles, clickhouse_cloud_list_api_keys (i secret non vengono mai restituiti) e clickhouse_cloud_list_activities, l'audit log con autore, indirizzo IP e id dei destinatari.

Cosa modifica:

• clickhouse_cloud_change_service_state avvia, ferma o risveglia (awake) un servizio. Fermarlo spegne il compute: i dati restano e la fatturazione del compute si ferma, ma le query falliscono finché il servizio non viene riavviato, quindi l'AI te lo chiede prima.
• clickhouse_cloud_update_service rinomina un servizio, imposta il release channel (slow, default o fast) e aggiunge o rimuove voci della lista di accesso IP e tag. Cambiano solo i campi passati; le rimozioni avvengono prima delle aggiunte.
• clickhouse_cloud_update_replica_scaling cambia la memoria per replica (minimo e massimo in GB, multipli di 4; limiti di memoria solo nel tier Production), la modalità di autoscaling, il numero di repliche, l'idle scaling e il timeout di inattività (almeno 5 minuti).
• clickhouse_cloud_change_clickpipe_state avvia, ferma o risincronizza una ClickPipe. Un resync copia di nuovo le tabelle sorgente, quindi l'AI lo conferma con te.
• clickhouse_cloud_create_invitation invita una persona via e-mail con gli id dei ruoli da clickhouse_cloud_list_roles.

Tutti i 26 tool sono attivi dopo l'installazione; nessuno è disattivato. Dai alla chiave un ruolo read-only se l'AI deve solo guardare.

Formati dei dati: ogni risposta è {status, requestId, result} e i dati stanno in result. Gli id sono UUID, gli orari ISO 8601 in UTC. I costi sono in ClickHouse Credits (CHC): grandTotalCHC per il periodo e totalCHC per record. La memoria è in GB, la dimensione dei backup in byte, le durate in secondi. Lo state di un servizio passa per starting o stopping prima di running o stopped; idle significa scalato a zero, e la query successiva lo risveglia.

Paginazione: clickhouse_cloud_list_organizations, clickhouse_cloud_list_api_keys e clickhouse_cloud_list_notifications accettano limit (fino a 250) e restituiscono nextCursor quando ci sono altri elementi; l'AI lo passa come cursor finché non manca. Tutte le altre liste arrivano complete in una volta.

Limiti: un report dei costi copre al massimo 31 giorni (to_date al massimo 30 giorni dopo from_date); per periodi più lunghi l'AI fa più chiamate. L'API ha un rate limit per chiave.

Errori comuni: 401 indica key id o secret errati, oppure una chiave scaduta o disattivata. 403 indica che il ruolo della chiave non ha il permesso per la chiamata (fatturazione, ClickPipes e gestione dei servizi sono permessi separati) o che l'IP del chiamante è fuori dalla allow list della chiave: su AnythingMCP Cloud aggiungi l'IP in uscita del server, in self-hosting l'IP del tuo server. 404 indica un id di organizzazione, servizio o backup errato. 429 è il rate limit; aspetta qualche secondo e riprova.

Il connettore non esegue SQL, non crea né elimina servizi, non ripristina né elimina backup, non crea né revoca chiavi API e non rimuove membri.

Step 2 — Installa l'adapter

curl -fsSL https://raw.githubusercontent.com/HelpCode-ai/anythingmcp/main/docker-compose.quickstart.yml -o docker-compose.yml
printf 'JWT_SECRET=%s\nENCRYPTION_KEY=%s\n' "$(openssl rand -hex 32)" "$(openssl rand -hex 32)" > .env
docker compose up -d

Step 3 — Aggiungi il connettore in Gemini

L'URL del tuo server: in AnythingMCP apri MCP Servers → il server su cui si trova questo connettore e copia il suo URL (https://cloud.anythingmcp.com/mcp/…). Usalo ovunque questa guida mostra YOUR_SERVER_ID.

Gemini CLI legge i server MCP da ~/.gemini/settings.json (su Windows %USERPROFILE%\.gemini\settings.json). Aggiungi:

{
  "mcpServers": {
    "anythingmcp": {
      "httpUrl": "https://cloud.anythingmcp.com/mcp/YOUR_SERVER_ID",
      "headers": { "X-API-Key": "YOUR_MCP_API_KEY" }
    }
  }
}

1. Crea una chiave API MCP in AnythingMCP da MCP Servers → il tuo server → API keys e incollala al posto di YOUR_MCP_API_KEY.
2. Salva il file e riavvia gemini.
3. Esegui /mcp in Gemini CLI (oppure gemini mcp list dal terminale): anythingmcp dovrebbe risultare connesso.
4. Inizia a scrivere prompt: Gemini CLI ora può chiamare i tool di ClickHouse Cloud.

Tool disponibili

Esempi di prompt

• "Quali dei nostri servizi ClickHouse Cloud sono in esecuzione adesso, e quali sono idle o fermi?"
• "Quanti ClickHouse Credits abbiamo consumato a ottobre, divisi per servizio? Qual è stato il giorno più costoso?"
• "Il backup di stanotte del servizio di produzione è terminato? Mostrami dimensione e durata."
• "Aggiungi 203.0.113.0/24 con la descrizione 'ufficio' alla lista di accesso IP del servizio di staging."
• "Chi ha fermato o scalato un servizio negli ultimi 7 giorni? Mostrami le voci dell'audit log."

FAQ

Dove cerca i server MCP Gemini CLI? In ~/.gemini/settings.json per il tuo utente, oppure in .gemini/settings.json dentro un progetto. gemini mcp list mostra ogni server e se si connette.

Prossimi passi

• Landing del connettore
• Collegare a Claude
• Collegare a ChatGPT
• Collegare a Cursor
• Collegare a Meta Muse
• Collegare a Microsoft Copilot