schakl.
Alle koppelingen

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. Een client die OAuth spreekt heeft niet eens een sleutel nodig, alleen het adres.

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)
  • Voor een sleutel: het recht apikeys.personal.manage, of apikeys.service_account.manage voor een service-account. Voor OAuth: niets extra, alleen een gewone login
  • Voor een OAuth-client met een vaste client-ID en secret: het recht settings.oauth.manage om hem aan te maken
  • Een client die Streamable HTTP spreekt, bijvoorbeeld Claude, Claude Code, Claude Desktop of ChatGPT

Zo koppel je het

  1. 1 Controleer je licentie onder Instellingen → Licentie. MCP heeft een eigen sku (mcp); wordt die niet gedekt, dan antwoordt /mcp met een 402 en is er niets aan te sluiten.
  2. 2 Claude of ChatGPT als connector: voeg https://<je-host>/mcp toe als eigen connector (ChatGPT: /mcp/compact). De client registreert zichzelf, je komt op het inlogscherm van je eigen werkruimte en daarna op Toegang toestaan, waar je kiest tussen Alles wat ik zelf mag, Alleen lezen of Zelf kiezen. Er wordt nergens een geheim gekopieerd.
  3. 3 Een client met een sleutel: open Instellingen → API en MCP, kies bij Wat koppel je? voor AI-assistent (MCP), geef de sleutel een Naam, kies bij Wat mag die doen? (standaard Alleen lezen) en bij Welke tools de sectie. Laat Verloopt op leeg voor een sleutel die nooit verloopt en druk op Sleutel aanmaken.
  4. 4 Het scherm drukt de koppelregel voor je client af met de nieuwe sleutel er al in, bijvoorbeeld voor Claude Code: claude mcp add --transport http schakl https://<je-host>/mcp --header "Authorization: Bearer schakl_…". De sleutel wordt één keer getoond.
  5. 5 Een sleutel die niemands account nodig heeft: Instellingen → Service-accounts → Service-account toevoegen, daarna Nieuwe sleutel met zijn eigen scopes.
  6. 6 Een tool die om een vaste client-ID en secret vraagt (een zakelijke connectorconfiguratie, een automatiseringstool): een beheerder maakt die aan onder OAuth-clients op hetzelfde scherm, met één redirect-URI per regel. Het secret wordt één keer getoond.
  7. 7 Gebruik altijd je eigen tenant-hostname; een sleutel die op de hostname van een andere organisatie wordt aangeboden, wordt simpelweg niet gevonden.
  8. 8 Klaar met een koppeling: Ontkoppelen bij Gekoppelde clients beëindigt elke sessie van die client, Intrekken naast een sleutel haalt de toegang er per direct af.

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.

OAuth geeft een sleutel uit, geen tweede soort toegang

Clients die een connector willen in plaats van een geplakt geheim, Claude en ChatGPT voorop, krijgen een volledige OAuth 2.1-flow: zelfregistratie, autorisatiecode met PKCE, vernieuwen, intrekken en discovery. Wat die flow oplevert is een gewone API-sleutel van de persoon die toestemming gaf, dus elke regel die voor een persoonlijke sleutel geldt, geldt ook hier. En de autorisatieserver logt niemand in: de toestemming loopt over de sessie die de webapp al heeft, met je wachtwoord en tweestapsverificatie of met de SSO van je organisatie. Een anonieme aanroep op /mcp krijgt een 401 met de uitnodiging om OAuth te doen, zodat een client de server vindt door geweigerd te worden en een onbekende niet kan zien welke modules je draait.

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 rechten van zijn sleutel, en het scherm begint op Alleen lezen. Een persoonlijke sleutel en een OAuth-koppeling worden daarbovenop bij elk verzoek afgetopt op de actuele rechten van de eigenaar, dus wie gedegradeerd wordt, verliest dat via zijn koppelingen ook. Kies je bij de toestemming voor Alles wat ik zelf mag of Alleen lezen, dan wordt dat bewaard als regel en niet als lijst van vandaag: komt er later een module bij, dan hoort die er vanzelf bij, zonder dat een chatclient om opnieuw toestemming hoeft te vragen, en nooit ruimer dan de persoon zelf. Zelf kiezen blijft een vaste lijst, en het scherm zegt dat erbij. 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

Een adres per klus

Het volledige oppervlak telt zo'n 620 tools. Een programmeerassistent leest die lijst één keer; een chatclient zet elke tool bij elke beurt in de context van het model, en ChatGPT staat voor alle tools samen 5.000 tokens toe. Dezelfde server antwoordt daarom ook op smallere adressen. Een modulesectie wordt afgeleid uit de routes van die module, dus wat er morgen bij komt staat er morgen in; een bundel noemt modules en nooit losse tools; en de compacte veertien is de enige lijst die met de hand is samengesteld, omdat een extern plafond dat afdwingt. Een smallere lijst is geen kleiner recht: wat een sleutel mag, bepaal je bij het aanmaken.

  • /mcp/compact: veertien alleen-lezen tools, de juiste keuze voor ChatGPT
  • /mcp/agent: klanten, contactpersonen, projecten, taken, uren en contactmomenten
  • /mcp/infra: domeinen, websites, hosting, Cloudflare, OXXA, uptime en WordPress
  • /mcp/finance: facturen, abonnementen en betalingen
  • /mcp/growth: Google Ads, Analytics, Search Console, Tag Manager, marketing en rapportage
  • /mcp/<module>: één module, bijvoorbeeld /mcp/google-analytics, /mcp/google-search-console of /mcp/wordpress
  • Een adres dat nergens naar verwijst wordt geweigerd met de lijst van wat wel bestaat

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.manage Eigen 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.manage Serviceaccounts beheren: gedeelde, persoonsonafhankelijke sleutels. Standaard alleen voor beheerders.
  • settings.oauth.manage OAuth-clients met een vaste client-ID en secret aanmaken, een nieuw secret uitgeven en een client intrekken, met elke sleutel die hij ooit uitgaf. Standaard alleen beheerders, want een blijvende toegang tot MCP is een beslissing van de organisatie.

Wat het bewust niet doet

  • 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.
  • Een route die een bestand als multipart neemt is geen tool; waar dat ertoe doet is er een JSON-tweeling, zoals het uploaden van een bijlage als base64.
  • Een OAuth-koppeling die met Zelf kiezen is gemaakt houdt de lijst van die dag. Een module die later aangaat komt er pas bij als je opnieuw koppelt.
  • 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 → API en MCP: een sleutel aanmaken met de koppelinstructies erbij, de gekoppelde OAuth-clients, en voor beheerders de OAuth-clients met een client-ID en secret. Instellingen → Service-accounts voor een sleutel die iemands vertrek overleeft. Het endpoint zelf is https://<je-host>/mcp.

Lees de handleiding

Meer in deze categorie

REST API & API-sleutels Webhooks

Andere koppelingen

Mollie Stripe Adyen Exact Online SnelStart Timeon