Shopify AI Toolkit: koppel Claude Code of Cursor rechtstreeks aan Shopify

Wie de afgelopen twee jaar een Shopify-app probeerde te bouwen met een AI coding agent, liep tegen dezelfde muur aan: de agent schrijft vol vertrouwen een query in GraphQL (de taal waarmee je data in Shopify opvraagt en aanpast), voert die uit en krijgt Field 'productCreate' doesn't exist on type 'Mutation' terug. Of hij gebruikt een verouderde schrijfopdracht. Of hij verzint een veldnaam die aannemelijk klinkt, omdat de docs-pagina die hij zich herinnert uit 2022 stamt. Het model liegt niet. Het gokt gewoon, tegen een continu verschuivend doelwit van 800+ types en een API-versie die elk kwartaal wijzigt.

Shopify heeft daar zojuist iets aan gedaan. De Shopify AI Toolkit is het officiële package dat Claude, Cursor, Codex, Gemini CLI of VS Code rechtstreeks koppelt aan het live schema, de docs, code-validators en de CLI van Shopify. Drie installatiemethoden, één lokale MCP server (een klein lokaal programma dat via de open MCP-standaard kennis en tools aan je AI-omgeving levert), geen authenticatie bij de dev-variant. De agent stopt met gokken en werkt voortaan met de daadwerkelijke omvang van het platform.

Deze post is de praktische, end-to-end versie: wat zit erin, voor wie dit nu interessant is, de drie installatiemodi, wat elke functie precies mogelijk maakt, en de use cases die van “lastig” naar “triviaal” gaan zodra je het aansluit.

Wat het eigenlijk is

Zonder de marketingpraat is de AI Toolkit één ding: een samengestelde set tool calls en skills waarmee een AI coding agent het Shopify-platform kan bevragen, query's tegen het schema kan valideren en er acties op kan uitvoeren. Concreet:

• Een lokale MCP server (@shopify/dev-mcp) die de docs en het schema van Shopify als MCP tools ontsluit.
• Een set agent skills (markdown SKILL.md bestanden) die de agent de juiste patronen leert voor OAuth, webhooks, Polaris UI, App Bridge, Functions en Theme extensions.
• Een plugin installer die beide koppelt aan Claude Code, Cursor, Gemini CLI of VS Code en ze automatisch bijwerkt zodra Shopify nieuwe API-versies uitbrengt.

De MCP server draait lokaal en vereist geen enkele authenticatie. Dat detail is belangrijker dan het lijkt: je kunt een gloednieuwe dev-omgeving in ongeveer dertig seconden Shopify-kennis geven, zonder OAuth-tokens, partneraccounts of gedeelde credentials.

Voor wie is dit nu interessant, en voor wie nog niet?

Eerst even nuchter, want niet elke lezer hoeft vanavond iets te installeren. Shopify groeit in Nederland al jaren, maar een groot deel van de Nederlandse webshops draait nog op WooCommerce, Magento of Lightspeed. Voor die winkels verandert deze toolkit niets; het is een Shopify-instrument.

Voor drie groepen is dit wel direct relevant:

• Webshops op Shopify met een eigen developer of vast bureau. Maatwerk dat je tot nu toe uitstelde omdat het een projectje van dagen was (een importtool, een voorraadalarm, een kortingsregel die net niet in de standaard past) wordt ineens werk van een middag.
• Bureaus en freelancers die Shopify-werk doen. De kostprijs van een private app daalt hier fors. Wie zijn offertes nog baseert op het oude aantal uren, gaat dat de komende tijd merken in de concurrentie.
• Softwarebedrijven met een Shopify-koppeling op de roadmap. De grootste drempel (het ecosysteem leren) is grotendeels weggenomen.

Voor wie het nog niet is: de webshopeigenaar zonder technisch persoon in de buurt. Je gaat deze toolkit niet zelf bedienen, en dat hoeft ook niet. Wat je wel kunt doen: bij de eerstvolgende maatwerkwens je bureau vragen wat een private app tegenwoordig kost. Het eerlijke antwoord hoort lager te liggen dan een jaar geleden.

De realistische eerste stap voor iedereen die het wel zelf doet: een development store en een private app voor je eigen winkel. Geen publieke app, geen productie. Eerst kijken of de belofte klopt op iets kleins.

De drie installatiemethoden

1. Plugin (de aanbevolen optie)

# Claude Code, Cursor, Gemini CLI, of VS Code
npx @shopify/ai-toolkit install

Dit is het pad dat Shopify aanbeveelt en het pad waar ik standaard voor zou kiezen. De installer detecteert welke IDE je gebruikt, zet de juiste config in je settings en registreert zowel de MCP server als de meegeleverde skills. Vraag je Claude daarna om “een Shopify-app te maken die CSV-productdata importeert”, dan heeft de agent vanaf dat moment volledige toegang tot de validators en docs, zonder dat jij verder iets hoeft te doen.

De echte winst zit in het automatisch bijwerken. Shopify brengt elk kwartaal een nieuwe API-versie uit. Op de dag dat je je app upgradet van 2026-01 naar 2026-04, haalt de plugin het verse schema op en gebruikt je agent direct de nieuwe velden. Geen “alle queries herschrijven omdat er een nieuwe versie is” meer.

2. Agent skills (handmatig, gericht)

# Clone de skills repo en kies wat je nodig hebt
git clone https://github.com/Shopify/ai-toolkit-skills
cp -r ai-toolkit-skills/build-app ~/.claude/skills/

Als je niet alles wilt, kun je individuele skills installeren. Elke skill is een SKILL.md bestand plus referentiemateriaal dat de agent één vaardigheid leert: hoe je een embedded admin-app opzet, hoe je een Function schrijft, hoe je App Bridge correct koppelt, hoe je webhooks afhandelt met HMAC-verificatie (de handtekeningcontrole die bewijst dat een binnenkomend bericht echt van Shopify komt).

Dit pad is nuttig als je werkt in een omgeving waar je de MCP server niet kunt draaien (CI-machines, cloud agents in een sandbox) maar toch wilt dat de agent de goedgekeurde patronen van Shopify volgt. Skills zijn puur markdown: overdraagbaar, diff-baar en onder versiebeheer.

Codex (de open-source coding agent) ondersteunt alleen skills + de MCP server, niet de plugin. Dus als jouw stack op Codex draait, is dit het pad.

3. Dev MCP server (rauw, scriptbaar)

# Draai de MCP server rechtstreeks
npx @shopify/dev-mcp

Dit is de rauwe versie. Elke MCP-compatibele client kan verbinden via stdio, dus als gewoon lokaal proces zonder netwerkpoort. Nuttig voor:

• Eigen agents die je zelf bouwt (LangChain, custom orchestrators, interne tooling)
• CI/CD-taken waarbij je een Shopify-kundige reviewer agent wilt op elke PR
• Headless automatisering waarbij de agent draait zonder IDE

Geen authenticatie vereist. De server ontsluit alleen ontwikkelfuncties (docs, schema, validatie). Hij raakt je live winkel NIET aan. Daarvoor heb je nog steeds een Admin API-toegangstoken nodig, en dat is een ander verhaal.

Wat de agent daadwerkelijk krijgt

Na installatie krijgt de agent toegang tot ruwweg zeven tool-families. Elk daarvan lost een specifieke klasse van fouten op die AI-gedreven Shopify-ontwikkeling voorheen om zeep hielp. Het verschil in één overzicht:

GraphQL Admin API, live schema

De agent krijgt een tool die het GraphQL-schema van Shopify rechtstreeks doorlicht. 800+ types, alle mutations, alle enum-waarden, alle fragmenteerbare interfaces, alle beschikbare query-parameters. Als je vraagt “schrijf een query die de laatste 50 orders teruggeeft met hun line items, klant-e-mail en de toegepaste korting”, gokt de agent niet naar veldnamen. Hij zoekt ze op.

Het praktische effect: queries werken vrijwel altijd meteen. Ik draai dit al een week op een winkel met 2.200 producten en het percentage “query mislukt door een ongeldig veld” ging van één op de drie pogingen naar één op de twintig.

Code-validatie, queries gecontroleerd voordat ze de deur uit gaan

De toolkit levert een lokale GraphQL-validator. De agent laat elke gegenereerde query eerst door de validator lopen voordat hij hem aan jou overhandigt. Als de query verwijst naar een verouderd veld of een veld dat wel bestaat in 2026-01 maar niet in 2026-04, vangt de validator dat lokaal af, nog voordat je ooit de Shopify API raakt.

Dat weegt zwaarder dan het lijkt. De Shopify API past rate limiting toe op queries die de validatie niet doorstaan. Een coding agent die tijdens development de API bestookt met kapotte queries wordt snel afgeremd. Lokale validatie vermindert het aantal API-round-trips met een factor tien.

Docs-zoekfunctie, heel shopify.dev ingebouwd

De agent heeft een zoektool die de volledige shopify.dev-documentatie doorzoekt en de resultaten per onderwerp afbakent. Vraag hem “hoe implementeer ik HMAC-verificatie voor webhooks” en in plaats van een blogpost uit 2023 uit de trainingsdata op te lepelen, haalt hij de actuele docs-pagina op, leest het huidige voorbeeld en schrijft tegen de API van vandaag.

Het skills-pakket voegt daar samengestelde patronen aan toe: er is een SKILL.md voor “bouw een embedded Admin app” die de agent door de canonieke structuur leidt (App Bridge-opzet, OAuth-flow, Polaris-componenten, deployment naar Shopify CLI). De agent verzint de structuur niet opnieuw, maar volgt de structuur die Shopify onderhoudt.

CLI store-uitvoering

Dit is het onderdeel dat van een chatbot een echte coding agent maakt. De toolkit geeft de agent toestemming om Shopify CLI-commando's rechtstreeks uit te voeren:

shopify app init      # scaffold a new app
shopify app deploy    # deploy to dev store
shopify theme dev     # local theme preview
shopify hydrogen dev  # storefront dev server

Dus als je zegt “maak een nieuwe app genaamd inventory-helper waarmee een merchant zijn producten in bulk kan bewerken”, voert de agent letterlijk shopify app init uit, kiest het juiste template, zet de app op, start de dev server en schrijft de eerste feature. End-to-end, in één prompt.

Polaris-componenten

Polaris is Shopify's React-componentenbibliotheek. Het is het verschil tussen een app die eruitziet als onderdeel van Shopify Admin en een app die eruitziet als een los Tailwind-zijprojectje. De toolkit leert de agent de canonieke Polaris-primitieven (Page, Card, DataTable, FormLayout, Button, Banner) en hoe je ze combineert.

Zonder dit heeft elke AI-gegenereerde Shopify-app die ik het afgelopen jaar heb gezien hetzelfde verraderlijke kenmerk: hij importeert Polaris maar gebruikt twee componenten en stylet de rest met Tailwind. Met de skills erbij grijpt de agent standaard naar Polaris.

App Bridge, embedding zoals het hoort

App Bridge is de runtime waarmee jouw app binnen Shopify Admin leeft (de iframe-shell, de navigatie, de modals, de toast-berichten). Dit is van oudsher een van de lastigere dingen om goed te krijgen, omdat de docs verspreid zijn over versies en het typische foutscenario is dat je app buiten Admin in een nieuw tabblad laadt.

De toolkit leert de agent de v4 App Bridge-patronen: de <App> wrapper, useNavigate, useToast, het shopify:// protocol voor navigatie. Apps worden meteen correct embedded, zonder dat jij drie docs-pagina's hoeft door te spitten.

Webhooks & Functions

Webhooks (events waarop je app zich abonneert) en Functions (custom checkout-, korting- of bezorglogica geschreven in Rust of JS) zijn de twee extensiepunten waar de meeste apps vastlopen bij de review. De skills behandelen:

• HMAC-verificatie voor webhooks (het onderdeel waar 80% van de zelfgebouwde apps de mist ingaat)
• Function input/output types en de function-runner CLI
• Het shopify.extension.toml formaat voor het declareren van extensions
• Functions deployen en terugdraaien

Vijf dingen die je nu in een middag kunt bouwen

Concrete voorbeelden, elk iets dat voorheen 1-2 dagen kostte en nu 1-2 uur duurt.

1. Bulk product translator

Eén prompt naar een Claude Code met de toolkit geïnstalleerd:

“Bouw een private Shopify-app die alle producten uit de catalogus ophaalt, Claude aanroept met een Nederlandse vertaalprompt voor elke titel en beschrijving, en de vertalingen terugzet als translatableResources. Gebruik de GraphQL Admin API. Verifieer de veldstructuur voordat je de mutation schrijft.”

De agent zet nu een app op met shopify app init, bevraagt het live schema voor translatableResource en translationsRegister, schrijft een gepagineerde fetcher, genereert de vertaalflow en levert een werkende Polaris UI om de voortgang te monitoren. Ik heb precies dit gedaan op een winkel met 2.200 producten en de agent leverde een werkende versie in 90 minuten.

2. Inventory monitoring agentspace

“Zet een webhook op voor inventory_levels/update, een kleine Express-server die hem ontvangt, en een Slack-bericht wanneer de voorraad onder een per-product drempel zakt die is gedefinieerd in een metafield.”

De agent leest het payload-schema van de webhook uit de toolkit, zet de HMAC-verificatie correct op (het onderdeel waar zelfgebouwde pogingen doorgaans op stuklopen), definieert het metafield en koppelt de Slack-webhook. Vijf bestanden, allemaal geldig tegen de huidige API.

3. Discount Function

“Schrijf een Shopify Function die 10% korting geeft wanneer het winkelmandje 3+ items uit de collectie ‘Sale’ bevat. Genereer het input/output-schema, de JavaScript-implementatie en de shopify.extension.toml.”

Functions waren voorheen de lastigste extensie om goed te krijgen, omdat de input GraphQL-query, de JS-functie en de TOML-config allemaal op elkaar moeten aansluiten. De skill dekt alle drie. De agent genereert ze in samenhang en draait shopify app function build + function-runner om lokaal te valideren.

4. CSV-naar-producten importer

“Neem deze CSV met 800 SKU's (sku, title, price, vendor, weight) en importeer ze in Shopify, waarbij je varianten aanmaakt voor rijen die een bovenliggend product delen op basis van de kolom ‘parent_sku’. Gebruik de bulk operation API.”

De bulk operations API is misschien wel het lastigste onderdeel van Shopify: staged uploads, JSONL-formaten en pollen tot de operatie is voltooid. De toolkit kent het patroon. De agent schrijft een script dat naar het staged target uploadt, bulkOperationRunMutation start, de status pollt en fouten per rij rapporteert.

5. Hydrogen storefront met AI-zoekfunctie

“Zet een Hydrogen storefront op, voeg een zoekroute toe die Algolia aanroept, en koppel de productkaarten aan het live ophalen van voorraad via de Storefront API.”

Hydrogen (Shopify's React-gebaseerde storefront framework) is een eigen omgeving met eigen conventies. De skills dekken de routing, data loaders en SDK. De agent draait shopify hydrogen init, voegt de route toe, roept de zoekindex van Algolia aan en integreert de voorraadcheck erin.

Waarom dit meer betekent dan alleen “agent-productiviteit”

De diepere verschuiving is dat Shopify AI coding agents voortaan als volwaardige gebruikers van het platform behandelt. Niet alleen “ontwikkelaars die toevallig AI gebruiken” maar agents zelf als doelgroep. De MCP server, de samengestelde skills, de dev-time validatie: dit alles is infrastructuur die specifiek bestaat omdat LLM's nu de code schrijven.

Mijn inschatting is dat dit patroon de norm wordt bij developer-platformen die relevant willen blijven. Supabase heeft al een eigen MCP server, en het zou me verbazen als partijen als Stripe en Vercel hier lang mee wachten. Platformen die hun schema, docs en validatie als agent-tools ontsluiten, worden door AI agents beter bediend; platformen die dat nalaten, worden in de praktijk lastiger te gebruiken en dat gaat meewegen in welke tools ontwikkelaars kiezen. Wie hier de Nederlandse softwaremarkt naast legt, ziet trouwens hoe groot het gat is: veel Nederlandse SaaS-partijen hebben nog geen fatsoenlijke publieke API of actuele documentatie, laat staan een MCP server. De lat die Shopify hier legt, is voor een flink deel van de markt nog jaren weg.

Voor Shopify specifiek verandert dit wie apps kan bouwen. Voorheen kostte het bouwen van een gepolijste Shopify-app 2-4 weken, voor iemand die het ecosysteem al kende. Nu kan een indie-ontwikkelaar met een Claude-abonnement en 90 minuten tijd een werkende private app leveren voor zijn eigen winkel, of een werkende publieke app voor review. De drempel is verschoven van “maanden Polaris en App Bridge leren” naar “weten wat je wilt”.

Wat het NIET oplost

Drie dingen om eerlijk over te zijn:

• Productiegeheimen blijven jouw probleem. De dev MCP server heeft geen authenticatie nodig omdat hij nooit je live winkel aanraakt. Zodra je wilt dat de agent daadwerkelijk naar een echte Shopify Admin API schrijft, geef je een toegangstoken mee. Vanaf dat moment geldt hetzelfde als bij elk ander risicovol hulpmiddel: je sandboxt de agent, of je vertrouwt hem.
• Polaris-gebruik wordt niet afgedwongen. De agent weet dat Polaris de voorkeur heeft. Hij weet niet dat jouw team een eigen designtaal heeft. Als je een eigen designsysteem hebt, moet je de agent nog steeds leren (via je eigen skill of CLAUDE.md) wanneer hij van de standaard moet afwijken.
• App review blijft mensenwerk. De toolkit helpt je snel aan een werkende app. Goedkeuring in de App Store vereist nog steeds handmatige beoordeling van UX, beschrijvingen, screenshots en prijsstelling. AI kan dat onderdeel niet versnellen.

Hoe je in 5 minuten begint

# 1. Zorg dat je Node 18+ hebt
node -v

# 2. Installeer de plugin in je IDE naar keuze
npx @shopify/ai-toolkit install

# 3. Open een nieuwe projectmap, vraag de agent om een app op te zetten
claude
> Use the Shopify AI Toolkit to scaffold a new app called bulk-translate-helper
  that translates product titles and descriptions to Dutch using Claude.
  Use the latest API version. Validate every query.

De agent zet de app op, schrijft geldige GraphQL, draait shopify app dev tegen je dev-winkel en levert je een werkende Polaris UI. Het is de vijf minuten waard om dit op iets echts uit te proberen, voordat je oordeelt of het bij jouw workflow past.

Drie regels die ik mezelf achteraf had willen meegeven

1. Gebruik het plugin-pad tenzij je een reden hebt om het niet te doen. Dankzij het automatisch bijwerken blijft dit op de lange termijn toekomstbestendig. Handmatige skill-installaties raken achterhaald zodra Shopify een nieuwe API-versie uitbrengt, en dat is elk kwartaal.
2. Zet de API-versie expliciet vast in je app-config. De agent gebruikt gewoon wat het live schema op dat moment als actueel aangeeft. Prima voor development. Voor productiedeployments moet je de versie vastpinnen, zodat een onaangekondigde deprecatie van een veld je niet onderuit haalt. shopify app config link + een expliciete api_version in shopify.app.toml.
3. Behandel de dev MCP als een docs-versneller, niet als vervanging voor het lezen van het deprecation log. De toolkit maakt het happy path snel. Hij waarschuwt je niet dat het veld dat je net gebruikt hebt over twee API-versies verouderd is. Dat blijft jouw verantwoordelijkheid.

Dit is wat mij betreft een van de sterkste dev-tool-integraties die ik dit jaar heb gezien. Als je het bouwen van een Shopify-app hebt uitgesteld omdat de API te groot leek voor een LLM om te overzien, is de muur net een stuk lager geworden. Probeer het dit weekend op een klein idee.