Configurer MCP dans Cursor : mcp.json, paramètres et marketplace

Vous collez un extrait dans un fichier de configuration, redémarrez l’éditeur, et le nouveau serveur apparaît avec un point rouge à côté de son nom. Ce moment explique pourquoi une configuration MCP dans Cursor propre compte. Le Model Context Protocol permet à l’Agent de Cursor d’appeler des outils externes, d’un navigateur à une base de données en passant par un générateur d’images, mais seulement si la connexion est correctement établie. Cet article suit le chemin dans l’ordre. Vous verrez où se trouve mcp.json, comment écrire des entrées locales et distantes, quels interrupteurs figurent dans Paramètres, comment la Marketplace installe des serveurs en un clic, et quoi vérifier quand un échec survient. Chaque configuration ci-dessous utilise les noms de champs de la documentation de Cursor, et aucun secret ne figure dans le fichier.

Ce que fait MCP dans Cursor

MCP est un protocole ouvert qui donne à un client d’IA une manière standard de communiquer avec des programmes externes. Cursor est le client. Chaque programme connecté est un serveur, et chaque serveur expose des outils que l’Agent peut appeler pendant une conversation : lire un fichier, interroger une base de données, ouvrir une page web, créer un ticket, générer une image.

Serveurs, outils et Agent

Pensez en trois couches. L’Agent comprend ce que vous demandez. Le serveur annonce ce qu’il sait faire. Un outil est une action unique, avec un nom, une description et un ensemble d’entrées. Quand vous demandez à Cursor pourquoi un endpoint renvoie une erreur 500, l’Agent lit la liste des outils, choisit ceux qui conviennent et vous demande l’autorisation avant de les exécuter.

Deux conséquences pratiques en découlent :

• Plus de serveurs ne veut pas dire mieux. Chaque outil activé ajoute sa description au contexte que lit l’Agent, donc une douzaine de serveurs inutilisés ralentissent les réponses et dégradent les choix.
• Les noms comptent. Des libellés clairs comme github ou project-files rendent les demandes d’approbation faciles à relire plus tard.

💡 Commencez avec un ou deux serveurs que vous utiliserez tous les jours. Ajoutez les autres quand une tâche réelle en a besoin.

Voici à quoi cela ressemble dans le travail quotidien. Un serveur de navigateur permet à l’Agent d’ouvrir votre site de préproduction, de parcourir un tunnel de paiement et de signaler ce qui a cassé. Un serveur GitHub lui permet de lire un ticket, de trouver le code correspondant et de rédiger le texte de la pull request. Un serveur de base de données lui permet de vérifier une ligne avant de proposer une migration. Dans chaque cas, l’Agent cesse de deviner et commence à lire des données réelles, ce qui justifie à lui seul les dix minutes passées sur la configuration.

Serveur local ou distant

Cursor prend en charge trois transports, et ce choix détermine la façon d’écrire l’entrée dans mcp.json.

Un serveur stdio est le plus simple : Cursor lance une commande comme npx et communique avec elle par l’entrée et la sortie standard. Un serveur distant n’est qu’une URL. Vous faites confiance au fournisseur pour l’exécuter, et vous vous connectez souvent via le navigateur avec OAuth au lieu de coller un jeton.

Où se trouve mcp.json

Cursor lit les définitions MCP dans un fichier JSON nommé mcp.json. Il existe deux emplacements possibles, et vous pouvez utiliser les deux en même temps.

Fichier global ou fichier de projet

Sous Windows, le dossier personnel correspond à votre profil utilisateur, donc le fichier global se trouve dans C:\Users\YourName\.cursor\mcp.json.

Cursor fusionne les deux fichiers. Donnez des noms différents aux serveurs dans chacun pour ne jamais vous demander quelle définition est exécutée. Ne versionnez le fichier de projet que s’il ne contient aucun secret, et utilisez des variables pour tout ce qui est privé.

Un fichier de projet partagé a un autre avantage : un nouveau membre de l’équipe clone le dépôt et obtient la même liste de serveurs sans appel de configuration. Chacun fournit ensuite ses propres jetons via des variables d’environnement, si bien que le fichier reste identique pour tous tandis que les identifiants restent personnels.

Anatomie d’une entrée

Chaque fichier contient un objet de premier niveau appelé mcpServers. À l’intérieur, chaque nom de propriété est le libellé d’un serveur, et la valeur indique comment l’atteindre.

Une entrée stdio utilise command, args, env et envFile. Une entrée distante utilise url et headers. Gardez ces deux formes séparées : une entrée, un transport.

Votre premier serveur, pas à pas

Quatre étapes couvrent presque tous les cas : créer le fichier, ajouter une entrée, enregistrer, puis vérifier le résultat dans Paramètres. Les deux exemples ci-dessous montrent une entrée locale et une entrée distante.

Ajouter un serveur local

1. Créez ~/.cursor/mcp.json s’il n’existe pas encore.
2. Collez l’entrée ci-dessous.
3. Enregistrez le fichier. Cursor prend généralement la modification en compte tout seul. Si le serveur n’apparaît pas, quittez Cursor puis relancez-le.

{
  "mcpServers": {
    "project-files": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]
    }
  }
}

Copier le prompt

L’option -y permet à npx d’installer le paquet sans demander de confirmation. La variable ${workspaceFolder} oriente le serveur vers le projet ouvert, si bien qu’il n’accède qu’aux fichiers de ce dossier.

Ajouter un serveur distant

Une entrée distante remplace command et args par une url. Cet exemple se connecte au serveur hébergé de GitHub et lit le jeton dans une variable d’environnement.

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${env:GITHUB_TOKEN}"
      }
    }
  }
}

Copier le prompt

Les serveurs qui prennent en charge OAuth n’ont besoin d’aucun en-tête. Cursor ouvre une fenêtre de navigateur lors de la première utilisation, vous autorisez l’accès, et la connexion est conservée pour les sessions suivantes. Lorsqu’un fournisseur vous remet un client ID et un client secret fixes, Cursor accepte un objet auth contenant CLIENT_ID, CLIENT_SECRET et scopes. Pour l’application de bureau, enregistrez http://localhost:8787/callback comme adresse de redirection.

Les variables protègent les secrets

Cursor développe ces variables dans command, args, env, url et headers :

• ${env:NAME} lit une variable d’environnement.
• ${userHome} correspond à votre répertoire personnel.
• ${workspaceFolder} correspond à la racine du projet.
• ${workspaceFolderBasename} correspond au nom du dossier du projet.
• ${pathSeparator} ou ${/} donne la barre oblique adaptée au système d’exploitation.

Un serveur local qui a besoin d’une adresse de base de données et d’un chemin de script peut combiner les deux :

{
  "mcpServers": {
    "notes-db": {
      "command": "node",
      "args": ["${userHome}${/}tools${/}notes-server${/}index.js"],
      "env": { "DB_URL": "${env:NOTES_DB_URL}" },
      "envFile": "${workspaceFolder}/.env"
    }
  }
}

Copier le prompt

💡 Ne collez jamais un vrai jeton dans un fichier que vous versionnez. Référencez une variable d’environnement, et ajoutez .env à .gitignore.

Paramètres, interrupteurs et approbations

Ouvrez Paramètres de Cursor et cherchez Tools & MCP. Les versions récentes affichent aussi les mêmes serveurs sous Customize dans la barre latérale. C’est le centre de contrôle de tout ce que vous avez écrit dans mcp.json.

Activer et désactiver les serveurs

Chaque serveur dispose d’un interrupteur et d’un nombre d’outils. Un serveur sain affiche ses outils. Un serveur en échec affiche un état d’erreur. Trois vérifications indiquent l’état en un coup d’œil :

• L’interrupteur est activé.
• Le nombre d’outils est supérieur à zéro.
• Aucun indicateur d’erreur n’apparaît à côté du nom.

Désactivez les serveurs dont vous n’avez pas besoin pour une tâche donnée au lieu de les supprimer. L’entrée reste dans le fichier, et la réactiver prend une seconde. C’est aussi le moyen le plus rapide de réduire la charge de contexte avant une longue refactorisation.

Approbation des outils et modes d’exécution

Par défaut, Cursor demande une approbation avant l’exécution d’un outil MCP. Vous voyez le nom de l’outil et ses arguments, puis vous acceptez ou refusez. Les outils MCP suivent les mêmes règles de Run Mode que les commandes du terminal : si votre mode exécute immédiatement les actions autorisées, les outils MCP autorisés s’exécutent eux aussi immédiatement.

💡 Autorisez les outils en lecture seule comme la recherche, la liste et la récupération. Gardez l’approbation activée pour tout ce qui écrit, supprime, publie ou dépense de l’argent.

Installations depuis la marketplace en un clic

Écrire le JSON à la main fonctionne, mais la plupart des gens commencent par la marketplace. Les fiches se trouvent sur cursor.com/marketplace et sur cursor.directory.

Ce que fait Add to Cursor

Chaque fiche comporte un bouton Add to Cursor. Un clic l’ouvre dans Cursor, vous demande de confirmer, puis écrit l’entrée dans votre ~/.cursor/mcp.json globale. Si le serveur demande OAuth, Cursor vous redirige ensuite vers la page de connexion du fournisseur.

Ensuite, ouvrez la liste MCP et vérifiez le nombre d’outils. L’entrée est un JSON ordinaire, vous pouvez donc la modifier plus tard : la renommer, ajouter une valeur env ou la déplacer dans un fichier de projet.

Vérifier avant d’installer

Un serveur s’exécute avec vos droits, alors une installation en un clic mérite dix secondes de méfiance.

• Vérifiez l’éditeur. Privilégiez les serveurs édités par le service lui-même ou par un projet dont le code source est public.
• Lisez la commande. npx télécharge du code depuis un registre et l’exécute sur votre machine.
• Lisez la liste des outils. Un serveur de notes qui demande un accès au shell est un signal d’alerte.
• Épinglez les versions avec package@version quand la stabilité compte davantage que les mises à jour.
• Privilégiez les serveurs distants d’un fournisseur auquel vous faites déjà confiance et que vous connectez via OAuth.

Si vous ne savez pas quoi ajouter en premier, cette courte liste correspond aux tâches quotidiennes les plus courantes :

Réparer un serveur qui ne démarre pas

La plupart des échecs proviennent de cinq ou six causes. Commencez par les journaux, puis faites correspondre le symptôme.

Lire les journaux MCP

Ouvrez le panneau Output avec Cmd+Shift+U sur Mac, ou Ctrl+Shift+U sous Windows et Linux, puis choisissez MCP Logs dans la liste déroulante. Le journal enregistre l’initialisation des serveurs, les appels d’outils et les messages d’erreur. Lisez la première erreur, pas la dernière. Les lignes suivantes sont généralement des effets de bord.

Six pannes courantes

Quand aucune de ces lignes ne correspond, lancez le serveur à la main. Copiez command et args de votre entrée dans un terminal, avec les mêmes valeurs d’environnement, et observez ce qu’il affiche. S’il échoue là, le problème vient du serveur ou de son installation, pas de Cursor. S’il fonctionne, comparez le PATH et les variables du terminal avec ce que Cursor transmet via env, puis relisez le journal jusqu’à la première ligne qui mentionne le serveur par son nom.

Associer MCP aux outils PicassoIA

La connexion ne représente que la moitié du travail. Trois fonctionnalités de PicassoIA aident autour d’elle.

Rédiger et relire les configurations. Un grand modèle de langage peut repérer une virgule finale, expliquer une erreur tirée des journaux MCP ou transformer un extrait d’installation de README en entrée Cursor. Sur PicassoIA, vous pouvez utiliser Claude Sonnet 5, GPT 5.6 Sol, Kimi K2.6 ou Gemini 3.5 Flash depuis un même endroit, et comparer la façon dont chacun lit la même erreur. Remplacez chaque token par un placeholder avant de coller une configuration.

Visuels pour la documentation et les README. Les pages de configuration gagnent à avoir une image d’en-tête claire. Seedream 4.5, Flux 2 Pro et GPT Image 2 transforment un prompt textuel en image photographique, et l’image vers vidéo peut transformer une image fixe en courte séquence pour un changelog ou une publication sur les réseaux sociaux.

Sa propre connexion MCP. PicassoIA propose une API à https://api.picassoia.com/v1 ainsi que des connexions MCP gérées depuis votre compte, couvrant la génération d’images, l’édition d’images et la génération de vidéos avec audio. Jusqu’à cinq prédictions s’exécutent simultanément par compte, partagées entre les tokens et les connexions MCP, si bien qu’une session qui enchaîne de nombreuses requêtes se mettra en file d’attente. L’adresse du serveur est affichée dans votre compte, donc cet article n’en imprime aucune. Une fois que vous l’avez, l’entrée suit la même structure url que l’exemple github ci-dessus. Consultez la page de votre forfait pour confirmer quelles offres incluent les connexions MCP avant de construire un flux de travail dessus.

Créez ensuite vos propres visuels

Choisissez un serveur de cet article, ajoutez-le aujourd’hui et approuvez vous-même son premier appel d’outil. Ensuite, ouvrez PicassoIA et générez une image d’en-tête pour vos notes de configuration : une photo de votre bureau, un fond calme pour un schéma ou une courte séquence pour une annonce de version. Essayez trois prompts différents, comparez les résultats et gardez celui qui convient à votre page. La liste complète des modèles se trouve sur picassoia.com/en/all-models.