Shopify AI Toolkit : Le Guide Complet pour Transformer votre Éditeur en Expert Shopify

Tu demandes à ton LLM de générer une requête GraphQL Shopify, il te sort un truc qui a l’air parfait, tu colles le code dans ton projet et là : champ introuvable, type inexistant, erreur 422. Le problème a un nom : la désynchronisation entre ce que le modèle a appris pendant son entraînement et l’état réel des APIs Shopify au moment où tu codes. Les schémas GraphQL de Shopify évoluent à chaque edition. Les LLMs travaillent sur des snapshots figés.

Le Shopify AI Toolkit est la réponse officielle de Shopify à ce problème. Une infrastructure construite sur 18 mois, formalisée dans la Winter ’26 Edition, qui connecte ton éditeur directement aux schémas API vivants de Shopify. Ce guide corrige les erreurs factuelles qui circulent dans la plupart des articles (notamment la confusion entre Dev MCP et Storefront MCP), couvre les 5 outils supportés y compris Codex et ses limitations, et va au-delà de l’installation pour montrer ce que tu peux concrètement demander à l’agent.

---

Ce qu’est vraiment le Shopify AI Toolkit (et la confusion à éviter)

La distinction fondamentale que les autres guides ratent

Avant même de parler d’installation, il faut régler un problème de terminologie qui pollue tous les contenus sur le sujet. Deux outils MCP coexistent dans l’écosystème Shopify, avec des usages radicalement différents.

Le Dev MCP Server est l’outil pour les développeurs. Il donne à ton assistant IA un accès direct à la documentation Shopify, aux schémas d’API en temps réel, aux outils de validation de code Liquid et GraphQL, et aux capacités de scaffolding d’applications. C’est l’outil dont parle cet article.

Le Storefront MCP est l’outil pour les expériences client. Il connecte un assistant IA aux données commerce en temps réel d’une boutique Shopify : catalogue produit, panier, commandes, politiques. Son usage est de construire des agents conversationnels pour les acheteurs finaux, pas pour les développeurs.

Confondre les deux est l’erreur numéro 1 dans les guides concurrents. Si tu cherches à construire un agent de shopping pour tes clients marchands, la section FAQ en bas de cet article t’explique comment les deux outils peuvent coexister dans un même projet.

Le contexte : pourquoi ce toolkit existe maintenant

Shopify a construit pendant 18 mois une infrastructure pour rendre sa plateforme lisible par les LLMs. La Winter ’26 Edition est le moment où cette infrastructure est devenue accessible à tous les développeurs sous une forme cohérente et officielle. Shopify a refait son infrastructure de documentation en server-side rendering et a étendu le Dev MCP Server pour couvrir l’ensemble de la plateforme. L’objectif affiché : éliminer la latence entre avoir une idée et obtenir du code validé.

Pour les développeurs, ça se traduit par un changement concret : ton assistant IA ne travaille plus sur des snapshots figés. Il interroge les schémas réels de Shopify au moment où tu poses ta question.

La promesse réelle (sans l’hyperbole)

Le Toolkit ne remplace pas ta compréhension de la plateforme Shopify. Il élimine le travail de consultation répétitif : aller chercher le bon champ dans la doc, valider la syntaxe d’une requête GraphQL, trouver la bonne commande CLI pour scaffolder une extension.

Ce gain est réel et mesurable sur les tâches répétitives. Il est nul sur les décisions d’architecture, le choix des patterns d’intégration, ou la compréhension des implications business d’une feature. Ça reste ton terrain.

---

Anatomie du Toolkit : les 16 Agent Skills et le protocole MCP

Ce que sont les Agent Skills

Le Shopify AI Toolkit est organisé en 16 agent skills. Un skill, c’est un ensemble d’instructions et de capacités que ton assistant IA reçoit pour opérer dans un domaine précis de la plateforme Shopify. Voici comment ils se regroupent par famille fonctionnelle.

Famille Admin API. Accès à la gestion des produits, commandes, clients, collections, et webhooks via l’Admin GraphQL API. C’est la famille la plus utilisée pour l’automatisation de back-office.

Famille App Scaffolding. Génération d’une nouvelle application Shopify avec npx @shopify/app, création de Function extensions, scaffolding des structures de fichiers standards. Le skill exécute les commandes CLI à ta place depuis le chat.

Famille Storefront API. Requêtes vers la Storefront API pour des usages headless : récupération de produits, gestion de panier côté front, checkout. À ne pas confondre avec le Storefront MCP, qui est un outil séparé.

Famille Theme et Liquid. Validation de templates Liquid, détection d’erreurs de syntaxe, vérification des références via Theme Check. Cette famille nécessite une configuration spécifique dans le fichier MCP (détail dans la section Installation).

Famille UI Extensions. Scaffolding et validation des extensions Checkout, POS, Admin et Customer Account. L’agent génère les fichiers et valide leur structure contre les schémas Shopify officiels.

Famille Shopify Functions. Génération et débogage de Functions (discounts, shipping, payment customization). L’agent accède à la documentation des targets disponibles en temps réel.

Famille Documentation. Recherche dans la documentation officielle shopify.dev. C’est le skill de base qui alimente tous les autres : quand l’agent génère du code, il vérifie la pertinence contre la doc officielle.

Famille Store Management. Exécution d’opérations sur ta boutique de développement via les capacités store execute du CLI Shopify. C’est le skill qui permet de tester des mutations directement depuis le chat.

Le protocole MCP : pourquoi c’est une vraie rupture

MCP (Model Context Protocol) est un protocole de communication standardisé qui permet à n’importe quel assistant IA compatible de se connecter à n’importe quel serveur MCP. Shopify a choisi de construire sur ce protocole ouvert plutôt que sur une intégration propriétaire.

La conséquence pratique : le même Dev MCP Server fonctionne avec Claude Code, Cursor, VS Code, Gemini CLI et Codex. Tu configures une fois, tu bénéficies de la mise à jour automatique de la documentation Shopify quel que soit ton outil. Pour une agence qui utilise plusieurs IDEs selon les développeurs de l’équipe, ça signifie une configuration centrale cohérente plutôt qu’une intégration par outil.

---

Prérequis et choix de l’outil

Trois prérequis, pas un de plus

Node.js 18 ou supérieur. C’est la seule dépendance technique pour tous les chemins d’installation. Si tu n’es pas sûr de ta version :

node --version

Si la réponse est inférieure à v18.0.0, mets à jour avant de continuer. Aucun des trois chemins d’installation ne fonctionnera avec une version antérieure.

Un compte Partenaire Shopify. Gratuit. Il te donne accès à la création de boutiques de développement et à l’Admin API. Le point d’entrée est partners.shopify.com.

Une boutique de développement. Gratuite dans un compte Partenaire. Elle est nécessaire pour tester les skills Admin API et Store Management. Les skills de documentation et de validation Liquid fonctionnent sans boutique.

Quel outil choisir : le tableau complet

Voici la réalité du support par outil, avec la précision que la plupart des guides omettent sur Codex :

Outil	Plugin complet	Skills manuels	Dev MCP Server	Interface
Claude Code	Oui	Oui	Oui	Terminal
Cursor	Oui	Oui	Oui	IDE graphique
VS Code	Oui (preview activée)	Oui	Oui	IDE graphique
Gemini CLI	Oui	Oui	Oui	Terminal
Codex (OpenAI)	Non	Oui	Oui	Terminal

La ligne Codex est le point à retenir : Codex ne supporte pas le plugin complet. Si tu utilises Codex, tu travailles nécessairement avec les skills manuels ou le Dev MCP Server. Cette limitation n’est pas temporaire, c’est une contrainte d’architecture du côté de Codex (format TOML au lieu de JSON, pas de support plugin natif).

Cursor vs Claude Code vs VS Code : le vrai comparatif

Cursor est le meilleur choix si tu veux l’expérience la plus fluide avec un minimum de configuration. L’intégration MCP est native dans les paramètres, et le Marketplace simplifie l’installation du plugin.

Claude Code est le meilleur choix si tu travailles déjà en terminal et que tu veux la commande /plugin install la plus rapide du lot. C’est aussi le plus adapté si tu as une infrastructure MCP globale existante (fichier ~/.claude/ déjà configuré).

VS Code est le choix de la compatibilité. Si ton équipe est sur VS Code, ne change rien à l’environnement. L’étape à ne pas rater : activer l’Agent plugins preview dans les settings avant d’installer, sinon le plugin ne sera pas reconnu.

---

Les 3 Chemins d’Installation : Lequel Choisir

Avant les commandes, voici l’arbre de décision :

Tu veux des mises à jour automatiques et tous les skills ?
    → Plugin (recommandé)

Tu es sur Codex, ou tu veux n'activer qu'un sous-ensemble de skills ?
    → Skills manuels

Tu veux uniquement la documentation et l'accès API
sans les skills de gestion de store ?
    → Dev MCP Server

Le Plugin (recommandé pour 90% des cas)

Le plugin bundle les 16 skills et le MCP en un seul install. Il se met à jour automatiquement quand Shopify publie de nouvelles capacités. Si tu installes les skills manuellement, tu es figé sur la version du jour de l’installation.

Claude Code

/plugin marketplace add Shopify/shopify-ai-toolkit
/plugin install shopify-plugin@shopify-ai-toolkit

C’est tout. Claude Code redémarre automatiquement et charge le plugin.

Cursor

Ouvre Cursor, va dans Cursor > Settings > Cursor Settings, cherche “Marketplace” dans les paramètres Tools and integrations, et recherche “Shopify”. Clique sur Install.

VS Code

Étape préalable obligatoire : ouvre settings.json et ajoute :

{
  "chat.agent.enabled": true
}

Ensuite, ouvre la Command Palette avec Cmd+Shift+P (Mac) ou Ctrl+Shift+P (Windows/Linux), exécute “Chat: Install Plugin From Source”, et colle l’URL du dépôt officiel :

https://github.com/Shopify/shopify-ai-toolkit

Gemini CLI

gemini extensions install https://github.com/Shopify/shopify-ai-toolkit

Pour rendre le plugin disponible sur tous tes projets :

gemini extensions install https://github.com/Shopify/shopify-ai-toolkit --scope user

Les Skills Manuels (pour Codex et environnements contraints)

Ce chemin est pertinent dans trois cas : tu utilises Codex, tu veux n’activer qu’une partie des 16 skills, ou tu travailles dans un environnement qui ne supporte pas les plugins.

Codex : la configuration se fait dans ~/.codex/config.toml (format TOML, pas JSON) :

[mcp_servers.shopify-dev]
command = "npx"
args = ["-y", "@shopify/dev-mcp@latest"]

Note la syntaxe mcp_servers en snake_case. Codex n’accepte pas la syntaxe camelCase mcpServers utilisée par les autres outils. C’est la source d’erreur la plus fréquente sur ce setup. Redémarre Codex après la modification.

Le Dev MCP Server (pour les setups sécurité-first)

Pro-Tip sécurité : Le Dev MCP Server tourne localement dans ton environnement de développement et ne nécessite aucune authentification. Aucune donnée ne transite par un service externe. Pour les agences qui travaillent sur des comptes clients avec des accès Admin API sensibles, c’est l’argument à mettre en avant dans ta charte sécurité interne.

Claude Code (via terminal)

Ajoute le serveur MCP Shopify Dev à ma configuration globale

Claude Code met à jour ~/.claude/mcp_servers.json automatiquement et confirme l’ajout. Redémarre pour charger.

Cursor

Va dans Cursor > Settings > Cursor Settings > Tools and MCP > New MCP server et ajoute :

{
  "mcpServers": {
    "shopify-dev": {
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp@latest"]
    }
  }
}

VS Code

Ouvre la Command Palette, exécute “MCP: Open User Configuration”, et ajoute la même configuration JSON dans ton fichier mcp.json de niveau utilisateur.

Gemini CLI

gemini mcp add shopify-dev npx -y @shopify/dev-mcp@latest --scope user

Codex

Même fichier ~/.codex/config.toml que pour les skills manuels. La configuration MCP utilise le même format TOML.

Configuration spéciale pour la validation Liquid

Si tu travailles sur des thèmes Shopify et que tu veux activer la validation Liquid complète, ajoute la variable d’environnement suivante dans ta configuration MCP :

{
  "mcpServers": {
    "shopify-dev": {
      "command": "npx",
      "args": ["-y", "@shopify/dev-mcp@latest"],
      "env": {
        "LIQUID_VALIDATION_MODE": "full"
      }
    }
  }
}

Sans cette variable, la validation Liquid fonctionne en mode partial : elle analyse les fichiers individuellement mais ne détecte pas les erreurs cross-fichiers. Le mode full active Theme Check sur l’ensemble du répertoire de thème.

---

Tutoriels Pas-à-Pas par Outil

Claude Code

Après l’installation du plugin via /plugin marketplace add Shopify/shopify-ai-toolkit et /plugin install shopify-plugin@shopify-ai-toolkit, vérifie que le toolkit est actif :

Quels skills Shopify sont disponibles dans ma configuration actuelle ?

Claude Code liste les skills chargés et leur statut. Si un skill manque, c’est généralement un problème de version de Node.js ou un redémarrage manqué. Les deux configurations (plugin et Dev MCP Server) sont compatibles et peuvent tourner simultanément.

Cursor

Après l’installation via Marketplace, vérifie que le MCP est bien actif dans Cursor > Settings > Cursor Settings > Tools and MCP. La liste des serveurs MCP actifs doit afficher “shopify-dev” avec un statut vert.

Si le serveur apparaît en rouge ou avec un statut “error”, la cause est presque toujours Node.js inférieur à 18. Vérifie avec node --version dans le terminal intégré de Cursor.

Pour l’indexation contextuelle, ajoute les extensions .liquid et .graphql dans les paramètres d’indexation de Cursor (Cursor Settings > Codebase indexing).

VS Code

L’étape la plus souvent ratée : l’activation de l’Agent plugins preview. Sans elle, l’installation du plugin réussit mais les skills ne sont pas chargés dans le chat. Vérifie que settings.json contient bien "chat.agent.enabled": true.

Après l’installation, le panneau Chat de VS Code doit afficher le logo Shopify dans la barre de contexte d’agent. Si ce n’est pas le cas, redémarre VS Code complètement (pas juste recharger la fenêtre).

Le fichier mcp.json de niveau utilisateur se trouve dans :

• Mac : ~/Library/Application Support/Code/User/mcp.json
• Windows : %APPDATA%\Code\User\mcp.json
• Linux : ~/.config/Code/User/mcp.json

Gemini CLI

Deux commandes à bien distinguer :

Pour le plugin : gemini extensions install [url]
Pour le MCP : gemini mcp add [nom] [commande]

Le flag --scope user rend la configuration globale. Sans ce flag, la configuration est locale au projet courant. Redémarre Gemini CLI après chaque modification de configuration.

Codex

Rappel de la contrainte principale : Codex ne supporte pas le plugin complet. Format TOML obligatoire, snake_case obligatoire.

Pour ajouter des skills manuels en complément du MCP, référence les fichiers de skills localement :

[agent_skills]
paths = [
  "~/.shopify/skills/admin-api.md",
  "~/.shopify/skills/storefront-api.md"
]

Les fichiers de skills sont disponibles dans le dépôt officiel github.com/Shopify/shopify-ai-toolkit dans le répertoire /skills.

---

Cas d’Usage Concrets : Ce que Tu Peux Demander à l’Agent

Cas 1 : Scaffolding d’une extension Checkout

Contexte : tu veux ajouter une case à cocher “Emballage cadeau” sur la page de checkout.

Prompt à utiliser :

Crée une extension de checkout Shopify qui ajoute une case à cocher 
"Emballage cadeau" avant le récapitulatif de commande. 
Utilise les UI extensions Checkout et le skill App Scaffolding.

Ce que l’agent fait : il exécute npx @shopify/app generate extension --type checkout-ui dans ton répertoire de projet, génère les fichiers de base (src/Checkout.jsx, shopify.extension.toml), et adapte le code selon les schémas de targets disponibles pour le point d’injection demandé. Tu n’as jamais à ouvrir la documentation sur les targets de checkout : l’agent vérifie en temps réel quels points d’injection sont disponibles dans la version API courante.

Cas 2 : Requête GraphQL Admin API

Contexte : tu veux récupérer les 10 produits les plus vendus avec leur stock actuel pour un tableau de bord interne.

Prompt à utiliser :

Génère une requête GraphQL Admin API Shopify pour récupérer 
les 10 produits avec le plus grand nombre de ventes totales, 
en incluant pour chaque produit : le titre, le handle, 
l'image principale, et le stock total de tous les variants.

Ce que l’agent fait : il interroge le schéma Admin GraphQL en temps réel, vérifie les champs disponibles (notamment totalInventory vs inventoryQuantity selon la version API), et génère une requête syntaxiquement valide avec les variables appropriées. Sans le Toolkit, le modèle aurait pu utiliser un champ déprécié ou inexistant dans ta version API. Avec le Toolkit, le schéma est consulté au moment de la génération.

Prompt de suivi pour tester :

Exécute cette requête sur ma boutique de développement 
et affiche les résultats.

L’agent utilise le skill Store Management pour exécuter la requête via le CLI Shopify sans que tu aies à ouvrir l’API Explorer.

Cas 3 : Validation d’un thème Liquid

Prérequis : avoir configuré LIQUID_VALIDATION_MODE=full dans ta configuration MCP (voir la section Installation).

Prompt à utiliser :

Valide l'ensemble de mon répertoire de thème Shopify 
et liste toutes les erreurs Theme Check par ordre de criticité.

Ce que l’agent fait : il lance Theme Check sur l’ensemble du répertoire, agrège les erreurs cross-fichiers (une référence à un snippet inexistant dans templates/product.liquid, par exemple), et retourne une liste priorisée avec des suggestions de correction pour chaque erreur.

Pro-Tip : utilise la validation Liquid après chaque merge sur une branche de développement partagée. L’agent peut être configuré pour faire tourner cette vérification automatiquement avant chaque push via un hook Git.

Cas 4 : Débogage d’une erreur de webhook

Contexte : tu reçois une erreur 422 sur ton endpoint de webhook orders/paid.

Prompt à utiliser :

Mon endpoint de webhook Shopify orders/paid retourne une erreur 422. 
Voici le payload reçu et le log d'erreur côté serveur : [coller ici].
Identifie la cause et propose la correction.

Ce que l’agent fait : il croise le payload avec la documentation du webhook orders/paid (version API actuelle), identifie si l’erreur vient d’un champ mal parsé, d’un HMAC de vérification incorrect, ou d’un problème de timeout de réponse, et propose le correctif ciblé.

Cas 5 : Shopify Catalog et Agentic Commerce (nouveau depuis Winter ’26)

Contexte : tu construis un agent de shopping qui doit rechercher des produits sur plusieurs boutiques Shopify partenaires.

Prompt à utiliser :

Configure un accès Shopify Catalog pour rechercher des produits 
en laine mérinos disponibles chez des marchands partenaires. 
Génère le code d'intégration MCP pour connecter Shopify Catalog 
à mon agent et affiche les 5 premiers résultats de test.

Shopify Catalog est désormais disponible pour tous les développeurs utilisant des outils MCP ou une REST API. Il donne accès à l’ensemble du catalogue Shopify via une seule requête, sans gestion manuelle de l’indexation ni contrainte de rate limits. C’est l’usage le plus avancé du Toolkit : construire des agents qui conduisent l’acheteur de la découverte produit jusqu’au checkout dans un flux entièrement automatisé.

---

FAQ : Les Questions que Personne ne Pose Clairement

---

Conclusion : Ce que Ça Change pour les Agences et les Freelances

Le Shopify AI Toolkit ne va pas remplacer ton expertise. Ce qu’il fait, c’est éliminer la consultation répétitive : ouvrir la doc pour trouver le bon champ GraphQL, vérifier la syntaxe d’une target d’extension, chercher la commande CLI exacte pour scaffolder un nouveau composant.

Pour une agence qui facture au temps passé, c’est un gain net sur les tâches à faible valeur ajoutée. Pour un freelance qui jongle entre plusieurs projets Shopify simultanément, c’est une réduction du coût de context-switch entre les APIs de différents clients. L’avantage concurrentiel réel ne vient pas d’aller “plus vite en solo”. Il vient de pouvoir embarquer des développeurs juniors sur des projets Shopify complexes avec un filet de sécurité : l’agent valide le code contre les schémas officiels avant même le premier commit.

Par où commencer maintenant

Si tu utilises Claude Code :

/plugin install shopify

Redémarre, puis essaie ce prompt de vérification :

Génère une requête GraphQL Admin API Shopify pour récupérer 
les 5 dernières commandes avec leur total et le nom du client.

Si la requête générée référence des champs avec des types corrects et une syntaxe valide, le Toolkit est actif et fonctionnel.

Si ton objectif suivant est de construire un agent de shopping pour des clients marchands plutôt qu’un workflow développeur, la documentation du Storefront MCP sur shopify.dev/docs/apps/build/storefront-mcp est la prochaine étape logique.

---

À propos de l’auteur

Frédéric Kinzi est le fondateur de Node6.ai, agence spécialisée dans les agents IA pour PME, et de ia-insights.fr, le premier annuaire francophone d’outils IA avec plus de 2 800 références. Il accompagne les entreprises dans le déploiement concret de l’IA et publie régulièrement des analyses sur l’écosystème Claude et l’automatisation.

---

Sources

• Shopify – Documentation officielle du Shopify AI Toolkit : https://shopify.dev/docs/apps/build/ai-toolkit
• Shopify – Dev MCP Server : https://shopify.dev/docs/apps/build/devmcp
• Shopify – Winter ’26 Edition pour les développeurs : https://www.shopify.com/news/winter-26-edition-dev
• Shopify – Storefront MCP : https://shopify.dev/docs/apps/build/storefront-mcp
• GitHub – Dépôt officiel Shopify AI Toolkit : https://github.com/Shopify/Shopify-AI-Toolkit
• Shopify Engineering – MCP UI : https://shopify.engineering/mcp-ui-breaking-the-text-wall