Claude of ChatGPT koppelen aan je vlootgegevens met MCP

Het Model Context Protocol (MCP) is een open standaard waarmee een AI-assistent zoals Claude of ChatGPT tools in een ander systeem kan aanroepen. Konvoi heeft een MCP-server op https://konvoi.ai/api/mcp. Voeg die URL toe als aangepaste connector in Claude, ChatGPT, Claude Code of Cursor, meld je aan met je eigen Konvoi-login, en de assistent beantwoordt vragen over je voertuigen, chauffeurs, boetes, tankbeurten en telemetrie. Hij leest met jouw rol en niets meer, en hij kan zelf niets wijzigen: elke wijziging die hij voorstelt, wordt een voorstel dat een persoon goedkeurt in Konvoi Dispatch. AI-clients via MCP zitten in een private bèta: Dispatch en AI-clients (MCP) moeten aangezet zijn voor je werkruimte voor je kunt koppelen.

Wat MCP is, in gewone woorden

Een AI-assistent weet op zich alleen wat je in de chat plakt. MCP geeft hem een standaardmanier om een ander systeem om gegevens te vragen. Dat systeem publiceert een lijst tools, zoals “voertuigen oplijsten”, “brandstofverbruik opvragen” of “voertuig lokaliseren”, elk met een beschrijving en de invoer die het verwacht. Stel je een vraag, dan kiest de assistent de tools die hij nodig heeft, roept ze aan, leest de resultaten en schrijft zijn antwoord.

Voor een vlootbeheerder betekent dat: je hoeft geen spreadsheet meer te exporteren om er een AI iets over te vragen. Je vraagt “Welke trucks zijn vorige week niet gebruikt?” en de assistent haalt het antwoord uit Konvoi, met per voertuig een link terug naar Konvoi.

Voor IT: de server spreekt Streamable HTTP, stateless, alleen POST. Aanmelden gebeurt met OAuth en PKCE (S256), en tokens zijn gebonden aan de server-URL. Elke MCP-client die met externe servers verbindt over HTTP met OAuth werkt. De volledige protocolreferentie en de actuele lijst met tools staan op de MCP-ontwikkelaarspagina.

Wat het betekent om een AI toegang te geven tot vlootgegevens

Een client koppelen is een beslissing over twee dingen: wat de assistent kan zien, en waar die gegevens naartoe gaan.

Wat hij kan zien. De koppeling handelt in jouw naam. Ze bereikt elke werkruimte die je kunt openen waar Dispatch en AI-clients aan staan, met je rol in die werkruimte. Bij het toestaan kun je ze beperken tot enkele werkruimtes. Kan je rol iets niet zien in Konvoi, dan kan de assistent het ook niet: een tool met een minimale rol boven de jouwe antwoordt met ROLE_REQUIRED.

Waar de gegevens naartoe gaan. Gegevens waarnaar je vraagt, gaan naar de client die je gebruikt. Vraag je Claude naar de boetes van een chauffeur, dan gaan die boetes als deel van het gesprek naar Anthropic; bij ChatGPT naar OpenAI. Het toestemmingsscherm van Konvoi zegt dat voor je op Toestaan klikt. Kijk na of het AI-beleid van je bedrijf de client toelaat voor je hem koppelt.

Het veiligheidsmodel: lezen met je rol, de rest voorstellen

De MCP-server van Konvoi volgt één regel: de assistent leest, mensen beslissen.

• Leestoegang met je eigen rol. Vlootgegevens lezen zit altijd in een koppeling, en elke oproep loopt met je rol in die werkruimte.
• Wijzigingen zijn voorstellen. Wijzigingen voorstellen is een aparte toegang die je bij het koppelen aanvinkt of weglaat. Zelfs dan wijzigt een propose_*-tool zelf niets. Hij maakt een voorstel in Konvoi Dispatch en geeft de link terug.
• Wie goedkeurt. Gewone voorstellen, zoals een boete toewijzen aan een chauffeur, keur je goed of wijs je af in de client als die het je kan vragen, anders in Konvoi Dispatch. Voorstellen met Beheerder keurt goed, zoals een bericht aan een chauffeur, een documentaanvraag, voertuigen samenvoegen of een brandstofdossier sluiten, vragen een werkruimtebeheerder in Konvoi Dispatch.
• Verantwoording. Een goedgekeurde wijziging loopt als de persoon die goedkeurt, met diens rol. Elke oproep en elke beslissing wordt gelogd.
• Tekst van buiten is gemarkeerd. Tekst van buiten Konvoi, zoals gescande documenten en e-mails, is gemarkeerd als onbetrouwbaar. Clients krijgen de opdracht die als gegevens te behandelen, nooit als instructies, zodat een gescande brief de assistent niet kan sturen.
• Kortlevende tokens. Toegangstokens gelden 1 uur. Vernieuwingstokens wisselen bij elk gebruik en vervallen na 30 dagen ongebruikt. Al je koppelingen worden meteen ingetrokken als je je wachtwoord wijzigt, overal afmeldt of tweestapsverificatie uitzet.

Hoe Konvoi in het algemeen met je gegevens omgaat, lees je op de beveiligingspagina.

Voor je begint

• Een werkruimte met Dispatch en AI-clients (MCP) aangezet. Dit is een private bèta. Meldt de client DISPATCH_OFF, dan staat het voor die werkruimte nog niet aan: vraag het een werkruimtebeheerder of neem contact op met Konvoi om mee te doen aan de bèta.
• Je Konvoi-login, met je passkey of tweede stap als je die gebruikt.
• Een MCP-client die met externe servers verbindt over HTTP met OAuth. Claude, ChatGPT, Claude Code, Cursor en VS Code kunnen dat allemaal. Aangepaste connectors zitten niet in elk abonnement van elke client, dus kijk dat van jou na.

De server-URL is voor elke client dezelfde: https://konvoi.ai/api/mcp. In Konvoi vind je hem ook onder Dispatch → Koppelen.

Stap voor stap: je client koppelen

Claude

1. Open Instellingen → Connectors.
2. Kies Aangepaste connector toevoegen.
3. Plak de server-URL.
4. Meld je aan bij Konvoi en sta toegang toe.

ChatGPT

1. Open Instellingen → Connectors → Geavanceerd.
2. Zet de ontwikkelaarsmodus aan.
3. Maak een connector met de server-URL en authenticatie OAuth.
4. Meld je aan bij Konvoi en sta toegang toe.

Claude Code

Voer dit uit in een terminal:

claude mcp add --transport http konvoi https://konvoi.ai/api/mcp

Voer daarna /mcp uit in Claude Code en meld je aan bij Konvoi.

Cursor en VS Code

Voeg de server in Cursor toe aan ~/.cursor/mcp.json:

{
  "mcpServers": {
    "konvoi": {
      "url": "https://konvoi.ai/api/mcp"
    }
  }
}

In VS Code kies je MCP: Add Server → HTTP en plak je de server-URL. Meld je aan bij Konvoi wanneer gevraagd.

Het toestemmingsscherm van Konvoi

Elke client komt uit op dezelfde Konvoi-pagina, “[client] koppelen aan Konvoi”. Ze toont als wie je aangemeld bent en vraagt twee dingen:

• Werkruimtes: Alle werkruimtes met Dispatch, of Alleen deze werkruimtes.
• Toegang: Vlootgegevens lezen, dat altijd aan staat, en Wijzigingen voorstellen, dat optioneel is.

Klik op Toestaan en je bent terug in je client, gekoppeld.

Voor scripts en automatiseringen zonder aanmeldvenster maak je een persoonlijk token aan via Profiel → AI-clients → Persoonlijk token aanmaken, en stuur je het mee als bearer-token. Persoonlijke tokens gelden 30, 90 of 365 dagen, en je ziet ze maar één keer.

Voorbeeldvragen

Je hoeft de namen van de tools niet te kennen. Vraag het zoals je het een collega zou vragen, noem de werkruimte als je er meerdere hebt, en vraag om links zodat je de bron kunt nakijken.

Vloot en voertuigen

• “Welke trucks hebben gisteren niet gereden, en bij welke is de tracker stilgevallen?”
• “Waar staat 1-ABC-123 nu, en waar stond hij vanochtend?”
• “Wat zijn de totale kosten van onze vijf oudste trekkers dit jaar?”

Brandstof

• “Toon het brandstofverbruik van september per chauffeur, slechtste eerst.”
• “Welke brandstofdossiers staan nog open, en wat zegt elk ervan?”

Boetes, documenten en vergunningen

• “Welke boetes zijn deze week binnengekomen, en wie had elk voertuig op dat moment? Stel de toewijzingen voor.”
• “Wat vervalt er in de komende 30 dagen: verzekering, keuring, vergunningen?”

Konvoi publiceert ook kant-en-klare prompts, dezelfde draaiboeken als in Dispatch: de boetes van deze week afhandelen, brandstof nalopen op afwijkingen, wat er in de komende 30 dagen vervalt, en een wekelijkse vlootreview. Clients die MCP-prompts ondersteunen, tonen ze in hun prompt- of slash-menu.

Limieten

De server heeft vaste limieten, zodat één drukke koppeling de rest niet vertraagt:

• Per koppeling: 120 oproepen per minuut, 5 tegelijk.
• Zware tools (analyses en rapporten die aan de kant van Konvoi draaien): 10 oproepen per minuut per koppeling.
• Per persoon: 300 oproepen per minuut over alle koppelingen.
• Grootte van een resultaat: 100 KB. Langere lijsten worden ingekort, en het resultaat zegt wat er weg is.

Boven een limiet antwoordt de tool met RATE_LIMITED en het aantal seconden dat je moet wachten.

De praktische limieten wegen zwaarder:

• De assistent kan zich vergissen. Hij kan een tabel verkeerd lezen of een conclusie trekken die de gegevens niet dragen. Open de link en kijk het na in Konvoi voor je handelt op een cijfer dat ertoe doet.
• Hij kent alleen wat in Konvoi zit. Werd een tankkaartexport nooit ingelezen, dan vindt geen enkele assistent die tankbeurten.
• Het is een bèta. Tools en hun gedrag kunnen nog veranderen. De lijst met tools op de ontwikkelaarspagina komt rechtstreeks van de server, dus die is altijd actueel.

Een koppeling verwijderen

• Profiel → AI-clients toont je koppelingen. Ontkoppelen beëindigt er meteen een.
• Een werkruimtebeheerder kan een koppeling uit zijn werkruimte verwijderen via Dispatch → Koppelen. De koppeling van die persoon blijft werken voor zijn andere werkruimtes.

Wil je liever geen externe client koppelen, dan werken dezelfde vragen ook in Konvoi zelf, in de chat van Konvoi Dispatch.