MCP — een externe AI-agent op Omniscol aansluiten

Wat de agent kan doen

De MCP-agent werkt bijzonder goed bij raadpleegvragen waarvan het antwoord in Omniscol staat:

• “Geef me de bezettingsgraad van de lokalen ten opzichte van de openingstijden deze week.”
• “Zoek een lokaal dat drie maandagen in oktober op hetzelfde tijdslot van 2 uur vrij is.”
• “Hoeveel lesuren heeft Jan de Boer in het lopende schooljaar gegeven?”
• “Wat zijn alle wiskundelessen van vandaag?”
• “Geef een lijst van de docenten die dit trimester minder dan 70 % van hun diensturen hebben gedaan.”

Zulke vragen combineren doorgaans meerdere tools: het rooster, de statistische dashboards, de berekende beschikbaarheid, de docentfiches. De agent stuurt de aanroepen aan en formuleert het antwoord in natuurlijke taal.

De aangeboden tools

De MCP-server bouwt zijn tools op uit de Omniscol-API-routes die voor MCP zijn toegestaan. Routes die uitdrukkelijk worden overgeslagen en sommige technische modules (bijvoorbeeld rond de authenticatie van gebruikers) worden geen tool. De lijst weerspiegelt dus de API die aan MCP wordt aangeboden, niet alles wat er intern in de toepassing zit. Toch is het een zeer groot deel. Bovendien bestaat er een aantal routes die specifiek voor MCP zijn gemaakt en die Omniscol zelf niet gebruikt. Dat geldt voor de tools voor geavanceerd zoeken, waarmee Omniscol de vrije tekst die een entiteit aanduidt (“docent Jan de Boer”, “klas 4V”) terugvindt met de technische identificatie die daarna dient om de gegevens precies te bevragen. Dat geldt ook voor complexe tools waarvoor Omniscol geen grafische interface heeft, omdat ze zich beter lenen voor een prompt: het zoeken naar de bezetting en de beschikbaarheid van een entiteit bijvoorbeeld (“zoek een lokaal dat 3 maandagen achter elkaar 2 uur in de middag vrij is”, “is er een wiskundedocent beschikbaar in de week van 14 oktober voor 3 uur?”).

De tools bestrijken onder meer:

• de module Beheer (gebruikers, vakken, schooljaren, instellingen),
• de module Roosterbeheer (configuratie, vestigingen, lokalen, klassen, lessen),
• de module Rooster (planning, dashboards, zoekopdrachten),
• de module Afwezigheidsbeheer (melding, statistieken),
• de globale zoekfunctie.

De leesroutes lenen zich het best voor gebruik door een agent. Er kunnen ook schrijfbewerkingen in de catalogus staan, afhankelijk van de rechten van het token en de beschikbare API, maar die moeten onder toezicht blijven: een verzoek dat meerdere functionele objecten wijzigt, moet door een gebruiker worden gecontroleerd voordat u het als betrouwbaar beschouwt.

De MCP-server inschakelen

De MCP-server is beschikbaar op Premium-accounts. Alles begint bij het MCP-scherm, dat u opent vanuit de module Beheer met Configureren: het toont de URL van de server volgens het gekozen bereik (globaal of beperkt tot één module) en levert, klaar om te kopiëren, de configuratiegegevens voor uw client.

De standaardauthenticatie van MCP is OAuth2. Een compatibele client (zoals Claude) maakt gewoon verbinding met de URL van de server, vindt daar de OAuth2-configuratie van het account, en de gebruiker keurt de toegang goed via een toestemmingsscherm: u hoeft niets anders op te geven dan de URL. Het toegekende bereik volgt de rechten van het account en de zichtbaarheidsbeperkingen ervan. De OAuth2-server van Omniscol, het beheerscherm voor de clients en de details van de toestemming staan beschreven op OAuth2 / OIDC (aanbieder).

Voor een client die geen OAuth2 ondersteunt, genereert hetzelfde scherm een token (API-sleutel, vervaldatum, optionele gekoppelde gebruiker, aan te vinken schrijfrechten) en biedt het daarna, klaar om te plakken, de bruikbare formaten aan naargelang het geval: de header Authorization: Bearer, de URL met token, het configuratieblok voor Claude Desktop (gratis versie) en het commando voor een lokale proxy. Het token steunt op het sleutelsysteem dat in Omniscol-API wordt beschreven.

Aanbevolen werkwijzen voor de beveiliging

• OAuth2-authenticatie — handiger, en te verkiezen zodra uw agent die ondersteunt (Claude in de betaalde versie).
• Een apart token voor de AI — maak een token aan met een sprekend label (AI-agent — Claude desktop) dat u zo nodig kunt intrekken.
• Minimaal bereik — selecteer bij een API-token alleen de API-endpoints die nodig zijn. Beperk bij een OAuth-token de scopes tot wat echt nodig is.
• Activiteitenlogboeken (logs) — een aanroep verschijnt in de logboeken van het token wanneer de betrokken route wordt gelogd. Die logboeken registreren de aanroep; ze bewaren niet de inhoud van de teruggegeven gegevens en evenmin de herspeelbare inhoud van de aanvraag.
• Zichtbaarheidsbeperkingen — de agent ziet wat Omniscol hem teruggeeft. Hebt u strikte zichtbaarheidsbeperkingen ingesteld voor de rol van het token, dan gelden die.