Tools en scopes

De tools zijn de acties die je AI-agent in Zippendo voor je kan uitvoeren, zoals een zending aanmaken of een bestelling lezen. De MCP-server biedt één tool voor elke actie in de API en je agent ziet alleen de tools die de rechten die je goedkeurt toestaan.

​

Hoe tools aan rechten zijn gekoppeld

Elke tool vraagt om een recht (een scope) dat past bij het onderdeel en de actie:

• Gegevens lezen vraagt om een scope met read:. Zendingen opvragen vraagt bijvoorbeeld om read:shipments.
• Gegevens wijzigen vraagt om de bijbehorende scope met write:. Een zending aanmaken vraagt bijvoorbeeld om write:shipments.

Scopes bouwen op elkaar voort, zodat je breed of smal rechten kunt geven:

• write:all omvat read:all en elke write:-scope in de tabel hieronder.
• read:all omvat elke read:-scope in de tabel hieronder.
• write:<resource> omvat read:<resource> (write:shipments omvat read:shipments).

Een agent die alleen read:shipments heeft gekregen, ziet de leestools voor zendingen (lijst, details, track & trace, documenten), maar geen van de tools die zendingen aanmaken, verzenden of verwijderen.

​

Overzicht van scopes

Het toestemmingsscherm kan ook andere rechten tonen, zoals organisaties, teamleden (org_members), retourportalen en API-tokens. Die ontgrendelen op dit moment geen MCP-tools.

​

Voorbeeldopdrachten

Zodra je bent gekoppeld, praat je met je agent in gewone taal. Hij kiest de juiste tools en vraagt het aan Zippendo:

• “Hoeveel zendingen staan nog op Pending en bij welke vervoerders zijn ze?”
• “Maak een zending aan voor bestelling #10421 met PostNord en geef me het trackingnummer.”
• “Splits de zending van bestelling #10388 in twee pakketten en verzend ze allebei.”
• “Welke bestellingen van de afgelopen 24 uur hebben nog geen zending?”
• “Volg zending shp_8f3kd9 en vertel me of die vertraagd is.”
• “Voeg een verzendregel toe die bestellingen boven 10 kg met GLS verstuurt.”

​

Tools voor documentatie en SDK’s

Naast de actietools laat de MCP-server een agent de documentatie van Zippendo lezen, zodat hij je kan helpen een integratie te bouwen in je programmeertaal. Voor deze tools is geen scope nodig en elke gekoppelde agent heeft ze. De agent krijgt de opdracht de SDK voor jouw taal te verkiezen en de ruwe OpenAPI-specificatie alleen te gebruiken als er geen SDK voor is. De inhoud komt live van zippendo.com/docs en de SDK-repositories, dus hij is altijd actueel. Probeer opdrachten zoals:

• “Schrijf met de Zippendo Python SDK een script dat een zending voor een bestelling aanmaakt en het trackingnummer print.”
• “Hoe authenticeer ik me bij de Zippendo-API in Go? Laat me de SDK-installatie zien.”
• “Ik werk in PHP. Schrijf een webhook-handler die de handtekening verifieert en reageert op shipment.dispatched.”

​

Veiligheidsmodel

Het verwijderen van zendingen, bestellingen, vervoerders, adressen, verzendregels of rollen, het verzenden van een zending en het aanmaken of intrekken van checkout-tokens en ondertekeningssleutels vragen allemaal om een uitdrukkelijke bevestiging in de toolaanroep, dus de agent hoort je eerst te vragen. Sommige gevoelige acties, zoals facturering en het beheer van API-tokens, zijn helemaal weggelaten uit de tools en geen enkele agent kan ze gebruiken, welke rechten hij ook heeft.

​

Dezelfde tools drijven Zippy aan

De MCP-server deelt zijn tools met Zippy, de assistent in de Zippendo-app. Alleen de plek verschilt: Zippy draait in de app, terwijl je met MCP je eigen AI-tool dezelfde acties laat gebruiken. Beide passen dezelfde rechten, organisatielimieten en validatie toe.