Automatisering & API Beschikbaar
MCP (Model Context Protocol)
Wijs een AI-client naar je eigen instance en stel je vraag in gewone taal. Er wordt niets geëxporteerd en er ontstaat geen tweede datapad: de MCP-server praat in-process met dezelfde API als de webapp.
Wat je nodig hebt
- Je eigen tenant-hostname over HTTPS: het geverifieerde eigen domein, of <slug>.<basisdomein>
- Een licentie die de sku mcp dekt; zonder dekking antwoordt de hele /mcp-mount met 402
- SCHAKL_MCP_ENABLED mag niet op false staan (standaard staat hij aan)
- Het recht apikeys.personal.manage voor een persoonlijke sleutel, of apikeys.service_account.manage voor een service-account
- Een client die Streamable HTTP spreekt, bijvoorbeeld Claude Code of Claude Desktop
Zo koppel je het
- 1 Controleer je licentie onder Instellingen → Licentie. MCP heeft een eigen sku (
mcp); wordt die niet gedekt, dan antwoordt/mcpmet een 402 en is er niets aan te sluiten. - 2 Maak een persoonlijke sleutel aan onder Instellingen → Mijn account, sectie API-sleutels. Vul Naam in, laat Verloopt op leeg voor een sleutel die nooit verloopt, en vink onder Scopes precies de rechten aan die de AI mag uitoefenen. Druk op Sleutel aanmaken.
- 3 Of maak een sleutel die niemands account nodig heeft: Instellingen → Service-accounts → Service-account toevoegen, daarna Nieuwe sleutel met zijn eigen scopes.
- 4 Kopieer de sleutel meteen. Hij heeft de vorm
schakl_<prefix>_<secret>en wordt één keer getoond; daarna geeft de API alleen nogschakl_<prefix>_********terug. - 5 Koppel Claude Code:
claude mcp add --transport http schakl https://<je-host>/mcp --header "Authorization: Bearer schakl_…" - 6 Een andere Streamable-HTTP-client: endpoint
https://<je-host>/mcp, headerAuthorization: Bearer schakl_…ofX-API-Key: schakl_…. Gebruik altijd je eigen tenant-hostname; een sleutel die op de hostname van een andere organisatie wordt aangeboden, wordt simpelweg niet gevonden. - 7 Klaar met de koppeling of sleutel kwijt: druk op Intrekken naast de sleutel, of verwijder het hele service-account. Alles wat hem nog gebruikt, verliest per direct toegang.
Dezelfde poort als de webapp
Er is geen tweede datapad. Een tool-aanroep gaat in-process door dezelfde afhandeling als een HTTP-verzoek: de hostname wijst de organisatie aan, row-level security wordt gebonden en de rechten van de sleutel worden opgelost. Een aanroep die niet mag, geeft de 401 of 403 van de API zelf terug als fout op de tool. De binnenkomende sleutel wordt nooit doorgegeven aan een externe dienst; de proxy praat alleen in-process met de API.
Read-first is een keuze bij het aanmaken
De toolset bevat ook schrijfacties, omdat de hele API erin zit. Wat een client feitelijk mag, staat in de scopes van de sleutel: vink alleen leesrechten aan en er valt niets te veranderen. Een persoonlijke sleutel wordt daarbovenop bij elk verzoek afgetopt op de actuele rechten van de eigenaar, dus wie gedegradeerd wordt, verliest dat via zijn sleutels ook. Een service-account-sleutel draagt precies de scopes die je hem gaf.
- Scopes komen uit dezelfde rechtencatalogus als rollen, inclusief de eigen/alle-variant zoals time.entry.read:own
- De deny-by-default-regel van de API beantwoordt elke aanroep, ook die van een AI
- Alleen modules die aanstaan leveren routes, dus de toolset volgt vanzelf wat je draait
Transport en tempo
Streamable HTTP, stateless, met JSON-antwoorden: elke JSON-RPC-POST staat op zichzelf, dus het werkt achter elke load balancer en vanaf een kale curl. Per sleutel geldt een limiet van 600 verzoeken per minuut, ruim voor automatisering en een vaste bovengrens onder een gelekte sleutel. De kolom Laatst gebruikt loopt bewust achter: die wordt buiten het verzoek om bijgewerkt, zodat een tool-aanroep er nooit op hoeft te wachten.
Rechten
Geef deze rechten aan de rol die deze koppeling beheert (Instellingen → Rollen). Standaard alleen voor beheerders, en nooit voor de rol client.
-
apikeys.personal.manageEigen API-sleutels beheren: zelf een sleutel aanmaken en intrekken. Standaard voor beheerder en medewerker, want de sleutel kan nooit meer dan de eigenaar zelf. -
apikeys.service_account.manageServiceaccounts beheren: gedeelde, persoonsonafhankelijke sleutels. Standaard alleen voor beheerders.
Wat het bewust niet doet
- Geen OAuth 2.1: de resource-server-laag (RFC 9728) is nog niet gebouwd. Een client die een volledige OAuth-flow eist, kan vandaag niet koppelen; een API-sleutel is de enige credential.
- Niet alles is een tool: /api/v1/auth, /api/v1/setup, /api/v1/instance, /api/v1/users en de upload-endpoints van import (/inspect en /import) zitten er bewust niet in. De kolommenlijst en de export van import & export blijven wel bereikbaar.
- De handgeschreven tools per module (companies.find, projects.budget_status) voeden vandaag de assistent in de app; de MCP-toolset komt puur uit de OpenAPI-spec.
- De oudere SSE-transport wordt niet aangeboden, die is afgeschreven.
- 600 verzoeken per minuut per sleutel is een vaste grens, geen instelling.
- SCHAKL_MCP_ENABLED=false haalt de hele /mcp-surface weg; er is geen uitschakeling per tool.
Waar je het vindt Instellingen → Mijn account, sectie API-sleutels voor een persoonlijke sleutel, of Instellingen → Service-accounts voor een sleutel die iemands vertrek overleeft. Het endpoint zelf is https://<je-host>/mcp.
Lees de handleiding