Connectors (MCP-servers)¶

Met een connector breng je de acties van een externe dienst in je organisatie: een ticketsysteem, een kennisbank of een andere toepassing die een MCP-server aanbiedt. MCP (Model Context Protocol) is een standaard waarmee een programma acties aanbiedt die een AI-model kan aanroepen. Deze pagina laat zien hoe je een connector toevoegt, het adres ervan toestaat, kiest welke acties de AI mag gebruiken en er tools van maakt die mensen en assistenten gebruiken.

Wie connectors beheert¶

Connectors toevoegen, wijzigen en verversen kan wie de tools van de organisatie mag inrichten: de beheerders van de organisatie (org-admin) en een eigen rol met write op toolbox. Een connector verwijderen vraagt delete op toolbox. Het adres van een nieuwe connector toestaan kan alleen een beheerder (hieronder).

Open Machinekamer en kies het tabblad Connectors. Vanuit de AI Toolbox kom je er ook, met Connectors in de balk bovenaan. Je ziet een tabel met per connector de Naam, de Server-URL, de Authenticatie en de Acties: Alle · 12 als de AI elke actie mag gebruiken, 8 van 12 als je er een deel hebt gekozen, of Nog niet opgehaald en Niet bereikbaar zolang OS de acties niet kent. Biedt een connector geen acties aan omdat een adres niet is toegestaan, dan staat dat boven de tabel en bij de naam van de connector (hieronder). Een connector die een abonnement heeft geïnstalleerd, kun je hier alleen bekijken.

Een connector toevoegen¶

1. Kies Connector toevoegen.
2. Vul in:
   • Naam: kleine letters, cijfers, - en _, hooguit 32 tekens. Ze staat vast zodra de connector bestaat.
   • Titel en Omschrijving: zoals de connector in OS heet.
   • Server-URL: het adres van de MCP-server, bijvoorbeeld https://mcp.example.com/mcp.
   • Regio (optioneel): waar de server staat, zoals eu of nl.

3. Kies onder Inloggegevens, bij Inloggen met, hoe de connector zich bij de server aanmeldt:

   Keuze	Wanneer
   Geen	De server vraagt geen aanmelding.
   Bearer token	De server geeft je een vast token. Vul het token in en, als de server het in een andere header verwacht dan Authorization, de naam van die header.
   OAuth — Org-breed	De connector haalt zelf een token op met een client-id en een clientgeheim, voor de hele organisatie. Vul het Token-eindpunt, de Client ID, het Clientgeheim en zo nodig de Scopes en Audience (optioneel) in.
   OAuth — Per gebruiker	Elke persoon logt met een eigen account in bij de dienst, en de acties werken met dat account (hieronder).

4. Voeg zo nodig Headers toe die bij elke aanroep meegaan, en Installatiewaarden: vaste waarden voor deze organisatie. Een installatiewaarde die je als Geheim markeert, wordt nooit meer getoond. In een header staat {$naam} voor de installatiewaarde met die naam.

5. Kies Connector toevoegen.

Geheimen kun je alleen schrijven. Een token, een clientgeheim en een geheime installatiewaarde worden versleuteld opgeslagen en daarna aan niemand meer getoond, ook niet aan jou. Bij het bewerken (Bewerken op de pagina van de connector) laat je zo'n veld leeg om te houden wat er staat (Opgeslagen; laat leeg om te houden), of kies je Inloggegevens vervangen om nieuwe in te vullen. Kies je een andere manier van inloggen, dan vul je ook het geheim daarvan opnieuw in. Sla een wijziging op met Wijzigingen opslaan.

OS weigert een header die de aanmelding zou omzeilen of lekken: Cookie, Proxy-Authorization, Authorization naast een aanmelding, of de header die de aanmelding zelf gebruikt. Een geheim in de server-URL wordt ook geweigerd. De melding noemt het veld, nooit de waarde.

Het adres toestaan¶

De AI-functies van je organisatie roepen geen enkel extern adres aan dat de organisatie niet heeft toegestaan. Dat geldt ook voor een connector: zolang het adres van de server, of het token-eindpunt van een OAuth-aanmelding, niet is toegestaan, biedt de connector geen enkele actie aan.

De pagina van de connector noemt onder Adressen elk adres dat hij gebruikt, met Niet toegestaan of Geblokkeerd door de omgeving waar dat zo is. Een beheerder staat een adres toe in het regeldocument:

1. Kies Naar de regels op de pagina van de connector, of open Gebruikersbeheer en kies Regeldocument.
2. Kies Regel toevoegen. Geef de regel onder Naam een naam, bijvoorbeeld ticketsysteem, laat Effect op permit: staat toe staan en kies bij Soort egress_host.
3. Kies onder Voorwaarden de cel Elk ding, elke persoon. Vul bij Namen het adres in, bijvoorbeeld mcp.example.com, of *.example.com voor elk adres eronder: één adres per regel. Kies Klaar.
4. Kies Regeldocument opslaan.

Kun je zelf geen regels wijzigen, vraag het dan een beheerder: een adres toestaan beslist waar de gegevens van de organisatie heen gaan.

Het adres geldt na enkele seconden. Kies daarna op de pagina van de connector Connector verversen. Geblokkeerd door de omgeving kun je niet zelf oplossen: de beheerder van de omgeving staat dat adres voor geen enkele organisatie toe.

De acties ophalen¶

Na het toevoegen en na elke wijziging haalt OS de lijst met acties bij de server op, meestal binnen een minuut, en daarna elk uur opnieuw. Op de pagina van de connector zie je bij Acties waar dat staat:

Kies Connector verversen om de lijst meteen opnieuw op te halen. Zolang het ophalen mislukt, biedt de connector geen actie aan.

Kiezen welke acties de AI mag gebruiken¶

Een nieuwe connector biedt nog niets aan: je kiest eerst. Onder Acties beheren staat elke actie die de server aanbiedt, met haar omschrijving. Kies bovenaan:

• Kiezen: alleen de acties die je aanzet. Een actie die de server later toevoegt, komt er pas bij als je haar aanzet. Zo krijgt een connector er niet ongemerkt een mogelijkheid bij.
• Alles, ook wat later komt: elke actie, ook die de server later toevoegt.

Kies Opslaan. Een actie die aan staat, is beschikbaar: een assistent kan haar krijgen en je kunt er een tool van maken. Een actie die uit staat, kan niemand in de organisatie gebruiken. Een actie die aan staat maar die de server niet meer aanbiedt, blijft staan met Niet gevonden bij het laatste ophalen; zet haar uit om haar weg te halen.

Testversies van de acties¶

Onder de acties staat de kaart Testversies. Elke actie die de connector aanbiedt, kan een testversie krijgen: een vast antwoord of een andere tool, die in runs van een evaluatie en in proeven antwoordt in plaats van de actie. In een gesprek wordt altijd de echte actie gebruikt. Kies per actie wat er antwoordt en kies Testversies opslaan; dat is een nieuwe versie van de connector. Een connector die een abonnement heeft geïnstalleerd, toont de testversies grijs.

Een actie in de toolbox zetten¶

Een beschikbare actie is nog geen tool in de AI Toolbox. Kies bij de actie Toevoegen aan de toolbox. Het scherm Nieuwe tool aanmaken opent met Voorinstelling al gekozen, over die actie:

1. Kies onder Voor wie is het? Voor mensen of Alleen voor assistenten, en kies Verder.
2. De Naam is voorgesteld, en de Beschrijving is de omschrijving van de server. Vul een Titel in en pas de rest aan waar je wilt.
3. Kies Tool aanmaken.

Daarna staat bij de actie Tool: naam, met een link naar de tool.

Het formulier waarmee iemand de tool uitvoert, volgt de server: verandert de server de invoer van een actie, dan verandert het formulier mee. Haalt de server de actie weg, dan is de tool niet meer beschikbaar.

Inloggen per gebruiker instellen¶

Bij OAuth — Per gebruiker werkt elke actie met het account van de persoon die haar gebruikt. Registreer OS daarvoor eerst als toepassing bij de dienst (de provider), en vul in OS in:

• het Autorisatie-eindpunt en het Token-eindpunt van de provider;
• de Client ID en, als de provider dat vraagt, het Clientgeheim (optioneel). Een publieke client gebruikt geen geheim;
• de Scopes, gescheiden door spaties, en zo nodig de Audience (optioneel).

Het formulier toont de Redirect-URI. Kopieer die met Kopiëren en registreer haar bij de provider: daar komt een persoon na het inloggen terug. Sta ook het adres van het token-eindpunt toe (hierboven).

Elke persoon verbindt daarna een eigen account op de pagina Mijn verbindingen. Tot iemand dat heeft gedaan, vraagt een tool over zo'n actie die persoon eerst in te loggen. Verwijder je iemand uit de organisatie, dan vergeet OS diens verbinding vanzelf.

Een AI-app die een lid met een groep van de AI Toolbox verbindt, kan zo'n actie niet gebruiken: de app werkt met een sleutel, niet met het account van de persoon (Een AI-app verbinden).

Versies en terugzetten¶

Elke wijziging van het adres, de headers, de installatiewaarden of de gekozen acties is een nieuwe versie. Onder Versies staan ze, nieuwste eerst, met de tijd, het adres, de namen van de headers en de acties. Elke wijziging geldt meteen; er zijn geen concepten.

Kies Terugzetten bij een oudere versie om haar adres, headers, installatiewaarden en acties de nieuwste te maken. Geheime installatiewaarden houden wat de nieuwste versie heeft: was een geheim toen anders, dan typ je het opnieuw. De aanmelding van de connector hoort bij de connector zelf, niet bij een versie, en blijft bij terugzetten zoals ze is.

Een connector verwijderen¶

Kies in de tabel Verwijderen bij de connector en bevestig. OS weigert zolang:

• een tool voor een van zijn acties staat. Verwijder die tools eerst;
• een assistent een van zijn acties gebruikt. Haal de actie eerst uit die assistent.

Na het verwijderen kan niemand de acties van de connector nog gebruiken.

Via de API¶

Alles op deze pagina kan ook via de API van OS, onder /api/v1/organisations/{id}/toolbox/mcp-servers. Een adres toestaan kan een beheerder ook met POST /api/v1/organisations/{id}/allowed-hosts en {"host": "mcp.example.com"}; dat voegt de regel aan het regeldocument toe (Het regeldocument).