MCP dans Claude Code et Cursor : ce que c'est et comment le configurer

Le résumé direct

MCP (Model Context Protocol) est un standard ouvert qui relie un agent d'IA à des outils et à des données externes, utile pour qui écrit déjà du code avec Claude Code ou Cursor et veut que l'agent interroge des systèmes réels au lieu de recevoir du texte collé dans le chat. La documentation officielle le décrit comme « an open-source standard for connecting AI applications to external systems » et utilise l'analogie du port USB-C : un connecteur, plusieurs appareils. En pratique, toute la configuration tient dans deux fichiers JSON : .cursor/mcp.json dans Cursor et .mcp.json dans Claude Code. L'agent lit ce fichier, démarre le serveur et se met à voir les outils exposés. Presque tous les problèmes de première fois tombent au même endroit : le serveur local ne démarre pas parce que la commande n'est pas dans le PATH de l'éditeur ou parce que la version de Node est trop ancienne. Vous trouverez ci-dessous les deux configurations, avec le Shopify Dev MCP en exemple, et la distinction entre erreur de fichier et erreur d'environnement.

1. Ce qu'est MCP, en trois couches

La documentation d'architecture du protocole découpe le sujet en parties qu'il vaut la peine de retenir, parce que chaque erreur apparaît dans l'une d'elles.

Participants. Il y a l'hôte (l'application d'IA, comme Claude Code ou Cursor), le client (une connexion dédiée par serveur) et le serveur (le programme qui fournit contexte et outils). L'hôte ouvre un client par serveur configuré, et c'est pour cela qu'un serveur en panne ne fait pas tomber les autres.

Couche de données. Un protocole basé sur JSON-RPC 2.0. C'est là que vivent les primitives du serveur : tools (fonctions exécutables), resources (sources de données) et prompts (modèles d'interaction). Le client découvre ce qui existe avec des appels de listage et exécute avec tools/call.

Couche de transport. Elle définit par où passent les messages. Il y a deux transports : stdio, qui utilise l'entrée et la sortie standard entre processus sur la même machine, et Streamable HTTP, qui utilise POST avec Server-Sent Events en option et accepte un bearer token, une clé d'API ou des headers. La recommandation officielle pour obtenir un token est OAuth.

Le protocole est versionné par date. La version actuelle est 2026-07-28, et le numéro ne change qu'en cas de rupture de compatibilité. La négociation se fait par requête, et le serveur refuse la version qu'il ne prend pas en charge.

2. Les deux transports et quand utiliser chacun

Le transport décide où le code tourne, qui paie l'infrastructure et comment vous vous authentifiez. Cursor documente la comparaison ainsi :

Source : Cursor Docs, page Model Context Protocol (MCP), lue le 21/09/2026.

Règle pratique : stdio pour un outil qui touche votre disque, votre base locale ou un de vos scripts. HTTP pour un service tiers dans le cloud et pour une équipe, parce qu'un serveur sert plusieurs clients et que l'authentification passe par OAuth au lieu de variables d'environnement éparpillées sur chaque machine.

Claude Code documente HTTP comme l'option recommandée pour les serveurs distants et marque SSE comme transport obsolète. Les serveurs qui n'exposent que SSE continuent de fonctionner : les versions récentes essaient d'abord HTTP et basculent sur SSE quand le serveur ne l'accepte pas.

3. Où se trouve vraiment la configuration

Le bouton d'installation d'une marketplace est une commodité. Ce qui fait foi, c'est le fichier, et savoir quel fichier l'agent a lu résout la moitié des problèmes.

Cursor

Deux emplacements, et la différence tient à la portée :

• .cursor/mcp.json à la racine du projet : vaut seulement pour ce projet.
• ~/.cursor/mcp.json dans le dossier personnel : vaut pour tous les projets.

Un serveur stdio dans Cursor utilise les champs type, command, args, env et envFile. La documentation est explicite sur command : il « must be available on your system path or contain its full path ». Retenez cette phrase, car c'est la cause de l'erreur de la section 5. envFile n'existe que pour stdio.

Claude Code

Trois portées, et chacune enregistre à un endroit différent :

Source : documentation de Claude Code, page MCP, lue le 21/09/2026.

Le fichier que vous commitez est .mcp.json. Il utilise la même clé mcpServers que Cursor, ce qui permet de copier un bloc de l'un à l'autre dans la plupart des cas. Par sécurité, Claude Code demande une approbation interactive avant d'utiliser des serveurs venus de .mcp.json : un dépôt cloné n'allume pas de serveur tout seul.

Quand le même nom apparaît dans plus d'une portée, Claude Code se connecte une seule fois, avec la définition de plus haute priorité, sans mélanger les champs. L'ordre est local, project, user, serveurs de plugin et connecteurs.

4. Configurer en pratique : le même serveur dans les deux éditeurs

L'exemple utilise le Shopify Dev MCP, serveur officiel qui donne à l'agent accès à la documentation développeur, aux schémas d'API et à la validation de GraphQL, de Liquid et des extensions. Il sert d'exemple parce qu'il tourne en local, par stdio, et ne demande pas d'authentification.

Prérequis avant tout fichier

Le Shopify AI Toolkit demande Node.js 18 ou supérieur. Vérifiez la version dans le même shell que celui qui ouvre l'éditeur :

node -v
npx -y @shopify/dev-mcp@latest --help

Si la seconde commande ne répond pas, le problème vient de l'environnement, pas du JSON. Réglez-le ici avant de modifier la configuration.

Claude Code

La méthode documentée utilise le CLI, qui écrit la configuration pour vous :

claude mcp add --transport stdio shopify-dev-mcp \
  -- npx -y @shopify/dev-mcp@latest

Le -- sépare les options de Claude Code de la commande qui démarre le serveur. Sans lui, le CLI lit les flags du serveur, comme -y, comme si c'étaient les siens. Pour le partager avec l'équipe, ajoutez --scope project, qui enregistre dans .mcp.json.

Le fichier obtenu, si vous préférez l'écrire à la main à la racine du projet :

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

Ensuite, redémarrez Claude Code pour charger la nouvelle configuration. Dans la session, /mcp affiche le panneau avec le statut et le nombre d'outils par serveur.

Cursor

Même bloc, dans .cursor/mcp.json à la racine du projet :

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

Enregistrez et redémarrez Cursor. Sous Windows, la documentation de Shopify indique une alternative pour le cas où une erreur de connexion apparaît : remplacer command par cmd et passer ["/k", "npx", "-y", "@shopify/dev-mcp@latest"] dans args.

Vérification

Dans Claude Code, claude mcp list affiche le statut de chaque serveur : connecté, authentification requise ou échec de connexion. Dans Cursor, le serveur apparaît dans le panneau d'outils du chat, et le log se trouve dans Output, option MCP Logs.

5. L'erreur classique : le serveur stdio qui ne démarre pas

Un serveur distant échoue avec un statut HTTP, qui est lisible. Un serveur stdio échoue en silence, et presque toujours pour l'une de ces raisons.

Un PATH différent de celui que vous voyez dans le terminal

Un serveur stdio est un processus que l'éditeur lance, et il hérite de l'environnement de l'éditeur, pas de celui de votre terminal. Si vous avez installé Node via nvm, asdf, Volta ou Homebrew et ouvert l'éditeur depuis l'icône du bureau, le npx qui fonctionne dans le terminal peut ne pas exister pour l'éditeur. C'est ce que la documentation de Cursor anticipe en exigeant que command soit dans le PATH du système ou donné avec son chemin complet.

Deux solutions. La plus directe consiste à trouver le chemin absolu et à l'utiliser :

which node
which npx

Puis à remplacer "command": "npx" par ce chemin absolu dans le JSON. L'autre consiste à ouvrir l'éditeur depuis le terminal déjà configuré, pour que le processus hérite du bon PATH.

Version de Node inférieure à celle exigée

Le toolkit de Shopify exige Node.js 18 ou supérieur. Avec nvm, la version active dans le terminal n'est pas forcément celle que voit l'éditeur. Le symptôme est un serveur qui apparaît en échec sans message clair, ou qui meurt juste après avoir démarré. Lancez node -v avec le chemin absolu que vous avez mis dans le JSON, pas avec celui de votre shell.

Entrée avec url et sans type

Une erreur de fichier, pas d'environnement. Claude Code lit une entrée sans type comme un serveur stdio. Donc une entrée avec url et sans type est une configuration invalide : le serveur est ignoré et le message est MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry. Dans les versions antérieures à 2.1.202, la même configuration apparaissait comme command: expected string, received undefined, ce qui envoie le développeur chercher au mauvais endroit. Quand vous copiez un bloc mcpServers écrit pour un autre client, vérifiez que les entrées avec url déclarent type.

Espace invisible dans un token collé

Claude Code avertit quand une valeur de configuration porte un espace au début ou à la fin, typique d'un token collé avec un saut de ligne. La vérification couvre command, url, chaque élément de args ainsi que les valeurs et les noms de clé dans env et headers. L'avertissement nomme le champ sans afficher la valeur, et l'agent ne supprime pas l'espace tout seul. Corrigez-le dans le fichier.

Délai de démarrage trop court

Un serveur qui télécharge un paquet au premier npx met plus de temps que d'habitude. Dans Claude Code, le délai de démarrage se règle par une variable d'environnement :

MCP_TIMEOUT=10000 claude

La valeur est en millisecondes, donc cet exemple laisse dix secondes au serveur pour démarrer.

La reconnexion qui n'existe pas

Les serveurs distants qui tombent en cours de session sont reconnectés par Claude Code avec un backoff exponentiel, jusqu'à cinq tentatives. Pas les serveurs stdio : ce sont des processus locaux, sans reconnexion automatique. Si le processus est mort, reconnectez-le depuis le panneau /mcp ou redémarrez la session.

6. Secrets, portée et ce qu'il ne faut pas commiter

.mcp.json à la racine est fait pour aller dans le dépôt, et c'est là que le risque apparaît : une clé d'API écrite directement dans le JSON part avec le commit.

Les deux éditeurs règlent cela par l'interpolation. Cursor résout les variables dans command, args, env, url et headers, avec les syntaxes ${env:NOME}, ${userHome} et ${workspaceFolder} (le dossier qui contient .cursor/mcp.json). Claude Code développe ${VAR} et accepte une valeur par défaut sous la forme ${VAR:-default}.

Le bloc partagé référence la variable, et chaque personne de l'équipe définit la valeur sur sa propre machine :

{ "mcpServers": {
  "api-interna": {
    "type": "http", "url": "https://api.exemplo.com/mcp",
    "headers": { "Authorization": "Bearer ${env:API_TOKEN}" }
  }
} }

Trois précautions qui valent plus que n'importe quelle astuce de configuration :

1. Une clé avec le minimum de permissions. Si l'agent n'a besoin que de lire des commandes, la clé n'a pas besoin de créer des clients.
2. Un serveur tiers, c'est du code qui s'exécute sur votre machine, avec vos accès. La documentation de Claude Code vous demande sans détour de vérifier que vous faites confiance au serveur avant de le connecter, parce que les serveurs qui vont chercher du contenu externe vous exposent au risque de prompt injection. Cursor recommande de relire le code source des intégrations critiques.
3. Un environnement sensible appelle du stdio local plutôt qu'un endpoint distant, conformément à la recommandation de Cursor lui-même sur les données sensibles.

7. Les limites qui apparaissent quand le serveur fonctionne

Un serveur connecté ne veut pas dire un flux résolu. Deux limites documentées apparaissent vite en usage réel.

Volume de sortie. Claude Code avertit quand la sortie d'un outil MCP dépasse 10 000 tokens et limite la sortie à 25 000 tokens par défaut. On peut relever le plafond avec MAX_MCP_OUTPUT_TOKENS ; le seuil d'avertissement est fixe. Un outil qui renvoie le dump entier d'une table bute sur ce plafond, et la solution consiste en général à filtrer côté serveur, pas à augmenter la limite.

Inactivité par appel. Un appel qui ne répond pas et n'envoie pas de notification de progression dans la fenêtre d'inactivité échoue avec une erreur au lieu d'attendre la limite de temps réel. La fenêtre par défaut est de cinq minutes pour HTTP, SSE, WebSocket et les connecteurs, et de 30 minutes pour stdio. Un travail long exige un serveur qui émet de la progression.

Source : documentation de Claude Code, page MCP, lue le 21/09/2026.

Si votre usage consiste à faire tourner un agent sur une machine allumée en permanence, la logique d'environnement et de PATH de cette section s'applique de la même façon, et le sujet de garder Claude Code sur un serveur est traité dans Claude Code 24/7 sur un VPS Hostinger.

Questions fréquentes

MCP remplace-t-il l'API du système que je veux intégrer ?

Non. MCP est la couche de connexion entre agent et outil ; l'API reste l'API. Le serveur MCP parle à votre système et l'expose sous forme de tools, resources ou prompts. Si le système n'a ni API ni base accessible, MCP ne crée pas un accès qui n'existe pas.

Puis-je utiliser la même configuration dans Cursor et dans Claude Code ?

Dans la plupart des cas, oui : les deux lisent la clé mcpServers dans le même format. La documentation de Claude Code signale les deux corrections courantes quand on réutilise un bloc écrit pour un autre client : ajouter type aux entrées avec url et renommer les serveurs dont le nom contient des caractères autres que lettres, chiffres, tiret et tiret bas.

Pourquoi le serveur fonctionne-t-il dans le terminal et échoue-t-il dans l'éditeur ?

Parce que le processus du serveur hérite de l'environnement de l'éditeur, pas de celui de votre terminal. Les gestionnaires de versions de Node modifient le PATH par shell, et l'éditeur ouvert depuis une icône ne passe pas par ce shell. Utilisez le chemin absolu dans le champ command ou ouvrez l'éditeur depuis le terminal déjà configuré.

Un serveur MCP tiers est-il sûr ?

Cela dépend de qui l'a publié et de ce à quoi il accède. La documentation de Claude Code vous demande de vérifier que vous faites confiance au serveur avant de le connecter, parce que les serveurs qui apportent du contenu externe créent un risque de prompt injection. Cursor recommande d'installer depuis une source de confiance, de vérifier ce à quoi le serveur accède, d'utiliser une clé aux permissions restreintes et de lire le code des intégrations critiques.

Ai-je besoin de MCP pour que l'agent comprenne mon projet Shopify ?

Pas forcément. Shopify propose le toolkit sous forme de plugin, d'agent skills et de Dev MCP, et présente le plugin comme la voie recommandée, avec mise à jour automatique. MCP est la voie à suivre quand l'agent doit parler à un système que vous seul possédez, comme un ERP, une base interne ou votre propre tableau de bord.

Conclusion

MCP résout un problème précis : donner à l'agent un chemin standardisé jusqu'à l'outil, au lieu que vous colliez des données dans le chat. La configuration est petite et vit dans deux fichiers, .cursor/mcp.json et .mcp.json, avec la même clé mcpServers. Ce qui casse n'est presque jamais le JSON lui-même : c'est la commande absente du PATH de l'éditeur, la version de Node inférieure à celle exigée ou l'entrée avec url et sans type. Commencez par un seul serveur, vérifiez son statut avant de demander quoi que ce soit à l'agent et n'ajoutez le second qu'ensuite.

Si ce dont vous avez besoin, c'est l'agent qui lit votre ERP, votre boutique ou votre base de données, c'est de l'intégration sur mesure (MCP, webhook, file d'attente). Décrivez le système et ce que vous voulez automatiser sur oailton.dev/fr/contato.