Een AI-agent verbinden met de MCP-server

Een externe AI-client — een eigen chatbot, een voice-platform, of een assistent als Claude of ChatGPT met MCP-ondersteuning — praat met de omgeving via een endpoint dat JSON-RPC 2.0 spreekt. Er is inmiddels niet één zo'n endpoint meer, maar drie. Welke je nodig hebt is de eerste beslissing die je neemt, want een sleutel opent er precies één.

De drie deuren

Alle drie spreken hetzelfde protocol en delen dezelfde transportlaag. Ze verschillen in wat erachter ligt, en daarmee in hoeveel vertrouwen ze vragen.

De namen zeggen precies wat ze zeggen: config is beheer — dingen instellen die daarna voor iedereen gelden — en operations is uitvoering. Een tafel toewijzen is operations; bepalen welke tafels er zijn is config.

Eén sleutel opent één deur

Een AI-agent authenticeert met een gebruikerssleutel van de vorm sk_<licentie>_<gebruiker>_<geheim>. Bij het aanmaken kies je de scope, en die bepaalt welke deur de sleutel opent. Een boekingssleutel op /mcpconfig krijgt een 401 — en wel vóórdat er wordt ingelogd, zodat een sleutel voor de verkeerde deur nooit een sessie krijgt.

Twee dingen die daarbij vaak verrassen:

• Een lege scope betekent booking. Sleutels van vóór de splitsing zijn niet stilletjes versmald — dat zou werkende integraties hebben gebroken — dus de boekingsdeur accepteert zowel booking als leeg.
• De REST-API hoort bij de boekingsfamilie. Dezelfde scope wordt gecontroleerd op REST v1 en v2. Een sleutel die op /mcp geweigerd wordt, komt er via REST dus ook niet in.

Je beheert sleutels onder Configuratie › Systeem › API, waarvoor je het recht menu_config_api nodig hebt. De volledige sleutel wordt eenmalig getoond en daarna gehasht opgeslagen — bewaar hem meteen. Een sleutel kan daarnaast een einddatum krijgen en kan worden ingetrokken in plaats van verwijderd, zodat achteraf nog te zien is wat hij was. Zie Hoe werkt een API sleutel?.

Naast een sleutel kan een client ook via OAuth verbinden: de gebruiker logt dan in op de omgeving en keurt de client goed in de browser. Vanaf de deur gezien is er geen verschil — beide noemen één gebruiker van één licentie, met dezelfde rechten en hetzelfde auditspoor.

Wat een agent mag: drie lagen

Binnenkomen is niet hetzelfde als iets mogen. Achter elke deur wordt per tool dezelfde keten gecontroleerd, en het is een EN:

1. Het hoofdrecht van de deur — tool_use, tool_config_use of tool_operations_use. Eén schakelaar die de hele deur aan of uit zet.
2. Het recht op die ene tool — bijvoorbeeld tool_config_object_update_apply. Plan en apply zijn aparte rechten, dus je kunt iemand wél laten zien wat een wijziging zou doen zonder hem die wijziging te laten maken.
3. Het domeinrecht — hetzelfde recht dat het scherm gebruikt dat dezelfde handeling doet. Er komen geen aparte rechten per endpoint bij: wie in de schermen geen klant mag wijzigen, kan dat via een tool ook niet.

De rechten staan per deur in een eigen groep: MCP, MCP-Config en MCP-Operations. Zie Rechten op AI-tools.

Alleen op de boekingsdeur bestaan publieke tools — tools die een websitebezoeker zonder ingelogde gebruiker kan bereiken. Op de configuratie- en operatiedeur is niets publiek en wordt élke aanroep zonder login geweigerd, ook een leesaanroep.

Niveaus: hetzelfde getal, drie betekenissen

Elke tool draagt een niveau. Dat getal betekent per deur iets anders, en dat is met opzet zo — het beschrijft telkens de bescherming die bij díe deur hoort.

Op de configuratiedeur geldt daarnaast nog iets wat de andere twee niet hebben: twee sloten die allebei open moeten staan voordat er überhaupt geschreven wordt. Eén wordt gezet door de leverancier voor de hele omgeving, de ander door de licentiehouder zelf. Staat er één dicht, dan wordt elke schrijfaanroep geweigerd — en een leesaanroep ook, want anders zou de deur die je niet open kunt doen wel in detail vertellen wat erachter staat.

Verbinden in vijf stappen

1. Zet de agent aan

Zonder actieve agent gebeurt er niets, in geen enkel kanaal. Onder Configuratie › AI › Agent instellingen zet je Agent actief aan. Daar kies je ook de Agent-modus: reserveringen óf evenementen. Die keuze bepaalt welke tools de boekingsdeur aanbiedt, dus maak hem bewust — allebei aanzetten leidt tot verkeerde toolkeuzes. Zie Agent instellingen.

2. Maak een sleutel met de juiste scope

Kies de scope die hoort bij de deur uit de tabel hierboven. Wil je een client die zowel boekt als inricht, dan zijn dat twee sleutels — en dat is precies de bedoeling, want het zijn twee niveaus van vertrouwen.

3. Verbind je client

Het endpoint is het adres van je eigen omgeving met het pad erachter:

https://jouw-omgeving.example.com/mcp
https://jouw-omgeving.example.com/mcpconfig
https://jouw-omgeving.example.com/mcpoperations

Hoe je die URL invoert verschilt per client, en daar loopt het in de praktijk vast: veel clients hebben helemaal geen veld voor een header. Er zijn drie routes, en de eerste is voor de meeste mensen de juiste.

Route 1: inloggen in de browser, zonder sleutel

Een client als Claude Desktop vraagt bij een eigen connector alleen om een URL — onder Advanced settings staat hooguit een optionele OAuth Client ID en Secret, en nergens een vrij headerveld. Dat hoeft ook niet: de omgeving publiceert de standaard OAuth-documenten en meldt de client zelf aan. Je plakt de URL, er opent een browservenster, je logt in met je eigen account en ziet op een toestemmingsscherm waar de client om vraagt. Daarna is hij verbonden.

In deze route komt geen sleutel voor. Er is dus ook niets om te bewaren, te delen of kwijt te raken. De rechten zijn die van jouw account, en de deur volgt uit de URL die je hebt ingevoerd.

Twee dingen om vooraf te weten:

• De client verbindt vanaf de infrastructuur van de aanbieder, niet vanaf jouw computer. De omgeving moet dus bereikbaar zijn vanaf het internet. Een lokale testomgeving of een omgeving achter een IP-filter werkt op deze manier niet.
• Een supportaccount kan dit niet. Zo'n account heeft geen eigen licentie maar wordt er telkens één; een token doet het omgekeerde en legt juist één gebruiker voor dagen vast. Het toestemmingsscherm weigert daarom, en wijst je naar het scherm waar je eerst naar de gebruiker wisselt waar deze verbinding bij hoort.

Route 2: een client die wél headers kent

Kan je client een header meesturen, dan gaat de sleutel mee als Authorization: Bearer <sleutel> of als X-API-KEY; staan ze er allebei, dan wint Authorization. Op de commandoregel van Claude Code bijvoorbeeld:

claude mcp add --transport http ireserve-config \
  https://jouw-omgeving.example.com/mcpconfig \
  --header "Authorization: Bearer sk_..."

De sleutel belandt dan in de configuratie van de client op je eigen machine. Dat is precies waar hij hoort: in een instelling, niet in een gesprek.

Route 3: een client die alleen lokale servers kent

Sommige clients kunnen uitsluitend een lokaal programma starten en niet rechtstreeks een adres benaderen. Daartussen zet je een bruggetje dat de verbinding doorgeeft en de header toevoegt; mcp-remote is daarvoor het gangbare gereedschap. Zet in de configuratie van de client het commando met de URL en de header erachter, en zet de sleutel in een omgevingsvariabele in plaats van in het bestand zelf. Kies een recente versie — in oudere zat een ernstig beveiligingslek.

4. Controleer wat je terugkrijgt

Welke tools beschikbaar zijn vraag je op met de standaard MCP-methode tools/list; een tool voer je uit met tools/call. Dat is het protocol, niet iets eigens — een client die MCP spreekt regelt dit zelf.

De lijst is geen vaste lijst. Hij hangt af van de deur, van je rechten, van de agent-modus en van welke onderdelen zijn ingericht. Mist er een tool die je verwacht, dan is dat bijna altijd een recht of een instelling en niet een fout. Krijg je een lege lijst terwijl de sleutel het doet, kijk dan eerst naar het hoofdrecht van die deur.

5. Test zonder je client

Voordat je gaat zoeken in je eigen integratie: de tool console onder Configuratie › AI › Tool console voert één tool rechtstreeks uit, via precies dezelfde weg als het endpoint. Je ziet het ruwe resultaat én de bijbehorende regel uit de audit-trail. Werkt het daar wel en bij jou niet, dan zit het probleem in je verbinding of je sleutel. Zie De tool console gebruiken.

Let op: schrijvende tools doen daar echte dingen. Een testboeking is een echte boeking.

Als het misgaat

Elke geweigerde aanroep schrijft een regel in het beveiligingslogboek, met de reden en met welke deur het betrof. Het antwoord bevat een verwijzing naar die regel, zodat een melding "hij zegt unauthorized" meteen bij zijn eigen logregel uitkomt. De meest voorkomende oorzaken, op volgorde: de header komt niet aan, de licentiebrede API-sleutel is gebruikt in plaats van een gebruikerssleutel, of de sleutel is voor een andere deur gemaakt.

De widget is iets anders

De eigen chatwidget heeft geen ingelogde gebruiker en draait daarom op een vaste lijst bezoekerstools op de boekingsdeur. Die heeft geen sleutel met scope nodig — zie AI Widget toevoegen aan je website.