MCP-server

MCP (Model Context Protocol) is de manier waarop AI-clients gereedschap krijgen. schakl. biedt zo’n server aan op /mcp: elk eindpunt van de API is er een tool. Je koppelt Claude Desktop, Claude Code of een andere MCP-client aan je eigen installatie en stelt je vraag in gewone taal, zonder eerst iets te exporteren. Wat de AI mag zien en doen, bepaal je met de scopes van de sleutel die je hem geeft.

Waar je het vindt

De server draait op https://<jouw-adres>/mcp, op het eigen adres van je organisatie. Er is geen scherm voor: je regelt het aan de kant van de client, met een sleutel uit Instellingen → Mijn account (blok API-sleutels) of uit Instellingen → Service-accounts.

Opgepast

De MCP-server is een gelicentieerde module. Zonder dekkende licentie antwoordt /mcp in zijn geheel met een licentiefout, ook op lezen. Dat is bewust: MCP wordt vooral gebruikt om te lezen, dus een lezen-mag-toch-splitsing zou hier niets afschermen. Zie Licenties.

Aansluiten

1. Maak een sleutel aan zoals beschreven bij de REST API. Vink onder Scopes alleen aan wat de AI mag; voor vragen stellen is dat meestal alleen leesrecht.

2. Kopieer de sleutel meteen. Hij wordt maar één keer getoond.

3. Voeg de server toe aan je client. Voor Claude Code:

   claude mcp add --transport http schakl https://<jouw-adres>/mcp \
     --header "Authorization: Bearer schakl_…"

4. Een andere client die Streamable HTTP spreekt, wijs je naar hetzelfde adres met de header Authorization: Bearer schakl_… of X-API-Key: schakl_….

5. Vraag de client de tools op te halen. Verschijnt er niets, controleer dan of je het eigen adres van je organisatie gebruikt: een sleutel bestaat alleen op de hostnaam van zijn eigen organisatie.

Welk gereedschap de AI krijgt

De toollijst wordt rechtstreeks afgeleid van de API zelf, dus hij loopt nooit achter. Elk eindpunt onder /api/v1 is een tool, met de korte naam van de bewerking: list_companies, create_task, time_summary.

Alleen de modules die jouw organisatie aan heeft staan hebben eindpunten, dus de toollijst volgt vanzelf welke modules je gebruikt. Zet je een module uit, dan verdwijnt zijn gereedschap.

Een paar dingen doen bewust niet mee:

Niet als tool	Waarom
Inloggen en de eerste-start-wizard	sessieafhandeling, zinloos voor een sleutel
Het beheerderscherm van de instantie	dat is de instantie-eigenaar, niet de organisatie
Import: bestand inspecteren en importeren	daar hoort een bestand en menselijk kolommen-koppelen bij

De rest van import en export blijft wel beschikbaar: kolommen opvragen en gegevens exporteren zijn allebei bruikbaar voor een AI.

Te veel tools voor een chatclient

Het volledige oppervlak telt zo’n 620 tools, en dat is de juiste standaard voor een programmeerassistent, die de lijst één keer leest. Het is de verkeerde voor een chatclient, die elke tool bij elke beurt in de context van het model zet en daar dus een budget voor heeft: ChatGPT staat 5.000 tokens toe voor alle tools samen, en de volledige lijst zit rond de 527.000. Snoeien lost dat niet op: bij dat aantal houd je zo’n 85 tokens per tool over, en daar past nog geen naam in. Alleen minder tools werkt.

Dezelfde server antwoordt daarom ook op smallere adressen, en je plakt het adres dat bij je client past:

Adres	Wat het aanbiedt
/mcp	Alles. De standaard, en wat een programmeerassistent wil
/mcp/compact	Een samengestelde, alleen-lezen veertien, klein genoeg voor het plafond van een chatclient
/mcp/<module>	De endpoints van één module, bijvoorbeeld /mcp/google-ads of /mcp/invoicing
/mcp/<bundel>	Een benoemde klus over meerdere modules heen, bijvoorbeeld /mcp/infra of /mcp/growth

Een modulesectie wordt afgeleid uit de routes van die module zelf, dus een endpoint dat er morgen bij komt wordt morgen aangeboden; een bundel noemt modules en nooit tools, waardoor hij zichzelf net zo goed bijhoudt als de secties die hij samenvoegt. Een adres dat nergens naar verwijst wordt geweigerd, met erbij wat er wél bestaat, in plaats van stilletjes terug te vallen op alle 620: dat zou eruitzien alsof het werkte en met lezen niet te ontdekken zijn.

Een kortere lijst is geen kleiner recht

De lijst versmallen versmalt wat de client te zien krijgt, niet wat de sleutel mag. Een tool buiten de sectie antwoordt gewoon als hij rechtstreeks wordt aangeroepen, langs precies dezelfde rechtencontrole. Wat een sleutel mag, bepaal je bij het aanmaken en nergens anders.

Wat de AI wel en niet mag

Een toolaanroep loopt precies dezelfde weg als een gewoon verzoek uit het scherm: hostnaam naar organisatie, afscherming op databaseniveau, en daarna de rechtencontrole van dat eindpunt. Er is geen tweede route naar de gegevens. Een aanroep waar de sleutel geen recht voor heeft komt gewoon terug als een foutmelding bij de tool.

Let wel op wat je aanvinkt: het gereedschap bevat ook schrijfacties, want het is de hele API. Wil je dat de AI alleen kan meelezen, geef de sleutel dan uitsluitend leesrechten. Dat is een keuze bij het aanmaken van de sleutel, niet iets wat de server voor je afdwingt.

Opgepast

Voor een AI-client is een sleutel met alleen leesrechten meestal genoeg. Vink je ook schrijfrechten aan, dan kan de client uit zichzelf records aanmaken, wijzigen en verwijderen, zonder dat er nog iemand op Opslaan klikt.

Rechten

Recht	Wat het opent	Standaard
apikeys.personal.manage	Eigen API-sleutels beheren	Beheerder, Medewerker
apikeys.service_account.manage	Serviceaccounts beheren	Beheerder

Daarna bepaalt de sleutel zelf alles: elke aangevinkte scope is een recht uit dezelfde catalogus als Instellingen → Rollen. Een persoonlijke sleutel wordt daarbovenop elk verzoek opnieuw begrensd door de actuele rechten van de eigenaar.

Goed om te weten

• API-sleutels zijn vandaag de enige manier om in te loggen. De volledige OAuth-aanmeldstroom die sommige MCP-clients verwachten is nog niet ingebouwd; zo’n client kan dus (nog) niet koppelen.
• Het transport is Streamable HTTP met losstaande JSON-antwoorden. De oudere SSE-variant wordt niet aangeboden.
• 600 aanroepen per minuut per sleutel. Een AI die enthousiast doorzoekt kan daar tegenaan lopen.
• Intrekken in het sleutelscherm haalt de toegang er per direct af, zonder dat er aan de kant van de client iets hoeft te gebeuren.
• De toollijst komt volledig uit de API-beschrijving. Handgeschreven, slimmere tools (zoals “zoek deze klant”) bestaan wel binnen de app-assistent, maar zitten niet in deze lijst.
• Wil je de server helemaal niet aanbieden, dan zet je op de server SCHAKL_MCP_ENABLED=false. Daarmee verdwijnt /mcp volledig.

Verder lezen

REST API Sleutels aanmaken, scopes kiezen en de API zelf aanroepen.

Licenties Wat er gebeurt als de licentie voor MCP niet meer dekt.