MCP — collegare un agente IA esterno a Omniscol

Ciò che l'agente può fare

L'agente MCP funziona molto bene sulle domande di consultazione in cui il dato si trova in Omniscol:

• «Dammi il tasso di occupazione delle aule rispetto agli orari di apertura questa settimana.»
• «Trovami un'aula disponibile tre lunedì di ottobre sullo stesso slot di 2 ore.»
• «Quante ore di lezione ha erogato Jean Dupont nell'anno scolastico corrente?»
• «Quali sono tutte le lezioni di matematica di oggi?»
• «Elenca i professori che hanno svolto meno del 70% delle loro ore di servizio in questo trimestre.»

Queste richieste incrociano tipicamente più strumenti: orario, dashboard statistiche, disponibilità calcolate, schede professori. L'agente orchestra le chiamate e formula la risposta in linguaggio naturale.

Gli strumenti esposti

Il server MCP costruisce i suoi strumenti a partire dalle route API Omniscol autorizzate per MCP. Le route ignorate esplicitamente, e alcuni moduli tecnici (per esempio, relativi all'autenticazione degli utenti) non diventano strumenti. La lista riflette quindi l'API esposta a MCP, non l'intera superficie interna dell'applicazione. È tuttavia una parte molto ampia. Per di più, esiste un certo numero di route dedicate a MCP e non utilizzate da Omniscol stesso. È il caso di strumenti di ricerca avanzata perché il testo libero che designa un'entità ("professore Jean Dupont", "classe 6A") sia ritrovato da Omniscol con il suo identificativo tecnico, poi usato per interrogare precisamente i dati. È anche il caso di strumenti complessi in cui Omniscol non possiede un'interfaccia grafica, perché ciò si presta meglio a un prompt: la ricerca di occupazione e di disponibilità di un'entità, per esempio ("trovami un'aula disponibile per 2 ore il pomeriggio 3 lunedì di fila", "un professore di matematica è disponibile nella settimana del 14 ottobre per 3 ore?").

Gli strumenti coprono in particolare:

• modulo Amministrazione (utenti, materie, anni scolastici, parametri),
• modulo Gestione degli orari (configurazione, sedi, aule, classi, lezioni),
• modulo Orario (planning, dashboard, ricerche),
• modulo Gestione delle assenze (dichiarazione, statistiche),
• ricerca globale.

Le route di lettura sono le più adatte a un uso agentico. Alcune operazioni di scrittura possono esistere nel catalogo, a seconda dei diritti del token e dell'API disponibile, ma devono restare inquadrate: una richiesta che modifica più oggetti di lavoro deve essere verificata da un utente prima di essere considerata affidabile.

Attivare il server MCP

Il server MCP è disponibile sugli account Premium. Tutto parte dalla schermata MCP, aperta dal modulo Amministrazione con Configura: mostra l'URL del server secondo il perimetro scelto (globale o ristretto a un modulo) e fornisce, pronti da copiare, gli elementi di configurazione del Suo client.

L'autenticazione standard di MCP è OAuth2. Un client compatibile (come Claude) si connette semplicemente all'URL del server, vi scopre la configurazione OAuth2 dell'account, e l'utente approva l'accesso tramite una schermata di consenso: non c'è nient'altro da fornire oltre all'URL. Il perimetro concesso segue i diritti dell'account e le sue restrizioni di visibilità. Il server OAuth2 di Omniscol, la sua schermata di gestione dei client e il dettaglio del consenso sono descritti in OAuth2 / OIDC (provider).

Per un client che non gestisce OAuth2, la stessa schermata genera un token (chiave API, scadenza, utente associato facoltativo, diritti di scrittura da spuntare) poi propone, pronti da incollare, i formati utili secondo il caso: intestazione Authorization: Bearer, URL con token, blocco di configurazione Claude Desktop (modalità gratuita) e comando di proxy locale. Il token si appoggia sul sistema di chiavi descritto in API Omniscol.

Buone pratiche di sicurezza

• Autenticazione OAuth2 — più pratica e da preferire quando il Suo agente la supporta (Claude versione a pagamento).
• Token dedicato all'IA — crei un token con un'etichetta parlante (Agente IA — Claude desktop) che può revocare se necessario.
• Perimetro minimo — con un token API, selezioni solo gli endpoint API necessari. Con un token OAuth, limiti gli scope al bisogno reale.
• Registri di attività (log) — una chiamata compare nei registri associati al token quando la route interessata è registrata. Questi registri tracciano la chiamata; non conservano né il dettaglio dei dati restituiti né il contenuto riproducibile della richiesta.
• Restrizioni di visibilità — l'agente vede ciò che Omniscol gli restituisce. Se ha configurato restrizioni di visibilità strette per il ruolo del token, esse si applicano.