Tema
Integrazioni — Clack MCP Server
MAIA espone un server MCP (Model Context Protocol) chiamato Clack Server che permette ad agenti AI (come Claude Desktop o Claude Code) di interrogare i dati della piattaforma in modalità sola lettura.
Cos'è il Clack MCP Server
Il Clack Server è un'interfaccia standardizzata che consente agli assistenti AI di accedere a:
- Dati di tenant, commesse, clienti e sedi
- Edifici, strutture, beni e classi bene
- Profili operatori, specializzazioni e servizi
- Planimetrie DXF delle strutture (se sulla commessa è attivo il modulo Planimetrie)
Solo lettura
Il Clack Server è read-only: non è possibile creare, modificare o eliminare dati tramite questa interfaccia.
Attivazione per commessa
L'accesso AI è governato dal modulo aggiuntivo MCP, attivabile per singola commessa: per abilitarlo su una commessa rivolgersi al supporto MAIA.
| Stato del modulo | Comportamento |
|---|---|
| Attivo | Gli strumenti di commessa restituiscono i dati normalmente |
| Disattivo (default) | Gli strumenti di commessa rispondono "La funzionalità MCP non è abilitata per questa commessa" |
Cosa resta accessibile a modulo disattivo
Il flag agisce solo sugli strumenti di contesto commessa. whoami e gli strumenti di contesto tenant continuano a funzionare: un agente può quindi elencare tenant e commesse, ma non leggere i dati operativi di una commessa con MCP disattivo.
Autenticazione
L'accesso al Clack MCP Server avviene in SSO: la pagina di login del server mostra il pulsante di accesso, che apre la stessa pagina di accesso di Clack e riporta all'autorizzazione del connettore.
Nessun account viene creato automaticamente
Un'identità SSO priva di un utente Clack corrispondente viene rifiutata, con un messaggio che invita a contattare l'amministratore. L'utente deve prima esistere su Clack. Vedi Accesso e autenticazione.
L'agente vede esattamente i dati che l'utente autenticato vedrebbe nell'interfaccia: gli stessi tenant, le stesse commesse e gli stessi permessi. Le aziende in cui il profilo dell'utente è disabilitato non compaiono nemmeno fra i risultati di whoami.
Strumenti disponibili
Il server espone 20 strumenti organizzati per contesto:
Utente
| Strumento | Descrizione |
|---|---|
whoami | Identità dell'utente autenticato, tenant accessibili e commesse associate al profilo |
Azienda
| Strumento | Descrizione |
|---|---|
get_tenant_details | Dettaglio completo del tenant |
get_commission_details | Dettaglio completo di una commessa |
find_customers | Ricerca clienti nel tenant |
get_customer_details | Dettaglio completo di un cliente |
find_sites | Ricerca sedi nel tenant |
get_site_details | Dettaglio completo di una sede |
find_profiles | Ricerca profili operatori nel tenant |
get_profile_details | Dettaglio completo di un profilo |
Commessa
| Strumento | Descrizione |
|---|---|
find_expertises | Ricerca specializzazioni nella commessa |
find_services | Ricerca servizi nella commessa |
find_buildings | Ricerca edifici nella commessa |
get_building_details | Dettaglio completo di un edificio |
find_structures | Ricerca strutture nella commessa |
get_structure_details | Dettaglio completo di una struttura (include planimetria se disponibile) |
get_dwg_viewer | Istruzioni e template HTML del visualizzatore DXF interattivo |
find_asset_classes | Ricerca classi bene nella commessa (include il numero totale di beni) |
get_asset_class_details | Dettaglio completo di una classe bene (include il numero totale di beni) |
find_assets | Ricerca beni nella commessa |
get_asset_details | Dettaglio completo di un bene |
Conteggio dei beni per classe
Dalla versione 3.2 ogni classe bene restituita dal server riporta sempre il numero totale di beni associati, anche quando la classe compare come dato collegato all'interno di find_services o find_assets. Consente di rispondere a domande come "quante caldaie ci sono in commessa" senza scorrere l'elenco completo.
Come si usa
Una volta collegato il connettore, basta fare domande all'assistente in linguaggio naturale: per esempio "quante caldaie ci sono nella commessa Comune di Roma?" oppure "quali beni ci sono nella Struttura principale dell'Asilo nido comunale?". L'assistente riconosce da solo l'utente, sceglie l'azienda e la commessa e usa gli strumenti adatti. Se si hanno più aziende o più commesse, conviene nominarle nella domanda.
Planimetrie
Se sulla commessa è attivo il modulo Planimetrie, l'assistente può mostrare la planimetria di una struttura: propone il link per scaricare il file e, se l'utente lo chiede, apre direttamente nella conversazione un visualizzatore in cui navigare il disegno. Vedi anche Planimetrie.
Da sapere
- Le ricerche per nome richiedono almeno 3 caratteri.
- Gli elementi eliminati non compaiono, a meno di chiederli esplicitamente.
- Le risposte molto lunghe arrivano a pagine: l'assistente può chiedere le successive.