Collegare un assistente AI

Come far lavorare un assistente AI esterno (Claude, un agente, un client MCP) con il tuo LimePanel: un token con i permessi minimi, le istruzioni pronte da copiare, la configurazione passo per passo e le regole di sicurezza.

Cos'è e quando serve#

LimePanel ha già un assistente AI integrato: lo apri dal pannello, legge quello che il pannello misura, spiega i problemi e propone correzioni che partono solo quando le approvi. Per diagnosi e domande sul tuo hosting non serve altro.

Questa guida è per l'altro caso: vuoi usare il tuo assistente, quello con cui lavori già, per gestire il pannello dalla sua chat o dal terminale. Per esempio: «elenca i siti con il certificato in scadenza», «crea la casella info@ sul dominio nuovo», «controlla i record DNS di questo dominio».

L'assistente esterno non entra nel pannello con le tue credenziali: usa le API di LimePanel con un token che crei apposta, con solo i permessi che decidi tu. Gli dai tre cose:

La specifica descrive ogni operazione con i suoi parametri e contiene solo le operazioni che quel token può usare: l'assistente non deve indovinare niente.

Prima di cominciare#

• Un pannello LimePanel raggiungibile dal computer (o dal servizio) su cui gira l'assistente, sulla porta 8443, con un certificato valido.
• Il permesso tokens.manage sul tuo account: se non vedi la voce «Token API e webhook», chiedilo a chi amministra il tuo account.
• Un assistente che sa fare richieste HTTP: un assistente con accesso al terminale (come Claude Code) oppure un client MCP con un server che espone una specifica OpenAPI come strumenti.

1. Crea un token con i permessi minimi#

1. Nel pannello apri Token API e webhook (in Hosting, Rivendita o Server, secondo il tuo ruolo; lo trovi anche con Ctrl+K).
2. Nuovo token.
3. Nome: uno che dica chi lo usa, per esempio Assistente AI – portatile. Ti servirà il giorno in cui va revocato.
4. Permessi: parti dal modello «Sola lettura» e togli quello che l'assistente non deve leggere. Togli in particolare files.read se non ti serve: permette di leggere il contenuto dei file, compresi quelli di configurazione con le password dei database. Aggiungi una scrittura (per esempio dns.manage o mail.manage) solo quando ti serve davvero, una alla volta.
5. Reti ammesse: se l'assistente gira sul tuo computer o su un server con IP fisso, scrivi quell'IP. Da altre reti il token viene rifiutato anche se è valido.
6. Durata in giorni: dai una scadenza breve, per esempio 30 giorni. Senza indicazioni il token vale 365 giorni; si può arrivare a 3650. Evita «Senza scadenza».
7. Crea il token e copia subito il valore: il pannello conserva solo un'impronta e non potrà mostrartelo di nuovo.

Un token non ha mai più permessi di chi l'ha creato, e se a te tolgono un permesso lo perde anche il token.

2. Copia le istruzioni per l'assistente#

Sempre in Token API e webhook, il pulsante Guida API apre la guida del tuo pannello. Nella sezione Usare un assistente AI con le API trovi:

• le istruzioni per l'assistente, già compilate con l'indirizzo del tuo pannello e il nome del tuo marchio: copiale nel suo prompt di sistema (o nel file di istruzioni del progetto);
• Specifica filtrata per te, cioè il file openapi.json con le sole operazioni che i tuoi permessi consentono.

Le istruzioni dicono all'assistente di leggere prima la specifica con il suo token, di cominciare da GET /me, di seguire le operazioni lunghe fino alla fine, di decidere in base al codice d'errore e di chiedere conferma prima di ogni operazione distruttiva.

3. Conserva il token in modo sicuro#

Il token va in una variabile d'ambiente o in un gestore di segreti, mai nel testo della chat, in un file di istruzioni o in un repository. Sul tuo computer, nel terminale da cui avvierai l'assistente:

export LP_URL="https://panel.tuodominio.it:8443/api/v1"
export LP_TOKEN="lpt_…"   # il valore che hai copiato

# verifica: deve rispondere con il tuo utente e i permessi del token
curl -s -H "Authorization: Bearer $LP_TOKEN" "$LP_URL/me"

Se la risposta è un errore, vedi Risoluzione dei problemi in fondo alla pagina.

4. Collega il tuo assistente#

Claude Code (o un altro assistente con il terminale)#

Un assistente che esegue comandi nel terminale usa le API direttamente con curl: non serve altro.

1. Imposta LP_URL e LP_TOKEN come nel passo 3, nello stesso terminale.
2. Nella cartella in cui lavori, salva le istruzioni copiate dal pannello nel file di istruzioni del progetto (per Claude Code è CLAUDE.md). Il file contiene l'indirizzo, non il token.
3. Avvia l'assistente da quel terminale e chiedi, per esempio: «Leggi la specifica di LimePanel ed elencami i miei siti con la versione di PHP».
4. Prima di approvare un comando, guardalo: deve usare $LP_TOKEN, non il token scritto per esteso.

Claude Desktop e altri client MCP#

LimePanel non installa un proprio server MCP: espone API REST descritte da una specifica OpenAPI standard. Per usarle da un client MCP (Claude Desktop o un altro) si usa un server MCP che trasforma una specifica OpenAPI in strumenti; ne esistono diversi, anche open source. Qualunque scegli, gli servono le stesse tre informazioni:

In Claude Desktop i server MCP si aggiungono da Impostazioni → Sviluppatore → Modifica configurazione, che apre claude_desktop_config.json. La forma della voce è questa; comando, argomenti e nomi delle variabili sono quelli indicati dalla documentazione del server MCP che hai scelto:

{
  "mcpServers": {
    "limepanel": {
      "command": "<comando del server MCP>",
      "args": ["<argomenti: specifica e indirizzo base>"],
      "env": {
        "LP_TOKEN": "lpt_…"
      }
    }
  }
}

Poi riavvia Claude Desktop: gli strumenti di LimePanel compaiono tra quelli disponibili e Claude ti chiede il permesso prima di usarli. Aggiungi le istruzioni copiate dal pannello a quelle del progetto o della conversazione.

Il file di configurazione contiene il token: tienilo solo sul tuo computer, non sincronizzarlo e non condividerlo.

Assistenti che importano una specifica OpenAPI#

Alcuni assistenti permettono di creare «azioni» o «strumenti» importando una specifica OpenAPI. Importa il file openapi.json scaricato dalla Guida API e scegli l'autenticazione con chiave API di tipo Bearer, con il token come valore.

Tieni presente che in questo caso le richieste partono dai server di chi fornisce l'assistente, non dal tuo computer: il pannello deve essere raggiungibile da internet sulla porta 8443 e non puoi limitare il token al tuo IP. Compensa con meno permessi e una scadenza più breve.

Cosa può fare l'assistente, e cosa no#

Può fare, con le API, solo quello che i permessi del token consentono: leggere siti, DNS, posta, database, certificati, backup e WordPress, e, se gliel'hai concesso, creare o modificare. Le operazioni lunghe (creare un dominio, un backup, un ripristino) rispondono subito e continuano in sottofondo: l'assistente le segue fino all'esito.

Non può, nemmeno con un token creato da un amministratore:

• usare le funzioni dell'identità: password, sessioni, verifica in due passaggi;
• entrare per conto di un altro utente;
• aprire il terminale;
• creare altri token;
• aggiornare il pannello, gestire la licenza o gestire gli utenti.

Queste funzioni restano legate a una persona collegata con il secondo fattore. In più:

• vede solo le risorse del tuo account (o dei tuoi clienti, se sei un rivenditore): una risorsa di un altro cliente risponde come se non esistesse;
• i ripristini e le altre operazioni irreversibili chiedono una conferma esplicita nella richiesta;
• i limiti del tuo pacchetto valgono anche per lui.

Sicurezza#

• Minimo privilegio. Un token apposta per l'assistente, in sola lettura, con le scritture aggiunte una per una. Mai un token con tutti i permessi in uno strumento di terzi.
• Un token per ogni strumento. Se ne revochi uno, gli altri continuano a funzionare, e nel registro sai chi ha fatto cosa.
• Reti e scadenza. Limita il token all'IP da cui lavori e dagli una scadenza breve. Per ruotarlo: crea il nuovo, sostituiscilo, revoca il vecchio.
• I dati escono dal server. Quello che l'assistente legge con le API arriva al servizio che lo fa funzionare. L'assistente integrato del pannello toglie password, chiavi e dati personali prima di inviare qualunque cosa; con un assistente esterno questa ripulitura non c'è. Non dare files.read se non serve.
• Conferma prima di agire. Lascia attive le richieste di permesso del tuo assistente e leggi ogni operazione che modifica dati prima di approvarla.
• Controlla cosa fa. In Token API e webhook vedi per ogni token l'ultimo uso e da quale IP. Nel registro delle attività ogni azione fatta con un token porta l'identificativo del token.
• Revoca. Revoca sul token: smette di funzionare dalla richiesta successiva. Fallo subito se pensi che il token sia finito nelle mani sbagliate, o quando smetti di usare l'assistente.

Risoluzione dei problemi#

Ogni errore ha la stessa forma: error.code (stabile, è quello da guardare), error.message e un request_id da citare all'assistenza.

Altri casi frequenti:

• Nessuna risposta o connessione rifiutata. La porta 8443 non è raggiungibile da dove gira l'assistente: controlla il firewall. Per gli assistenti che lavorano dal cloud il pannello deve essere raggiungibile da internet.
• Errore di certificato. Il nome del pannello non punta ancora al server e il pannello usa un certificato temporaneo. Sistema il record DNS: il certificato di Let's Encrypt arriva da solo.
• L'assistente inventa percorsi o campi. Fagli leggere la specifica con il suo token prima di cominciare: i campi sconosciuti vengono rifiutati.
• La specifica scaricata contiene operazioni che il token non può usare. Il file della Guida API è filtrato sui tuoi permessi, il token può averne meno: l'assistente rilegge la specifica da /api/v1/openapi.json con il suo token.
• Messaggi in inglese o in italiano. L'intestazione X-LimePanel-Lang (it o en) sceglie la lingua dei testi composti dal server; per decidere cosa fare conta sempre error.code.