Emplacement de mcp.json dans VS Code : configuration des serveurs MCP et registre, étape par étape

Vous ajoutez un serveur MCP à VS Code, rechargez la fenêtre, ouvrez Copilot Chat, et les nouveaux outils sont introuvables. Le plus souvent, le serveur fonctionne et c’est le fichier qui pose problème : il se trouve dans le mauvais dossier, il utilise la mauvaise propriété de premier niveau, ou VS Code lit une autre copie que celle que vous venez de modifier. Cet article précise l’emplacement de mcp.json dans VS Code pour chaque configuration, montre la structure JSON attendue par l’éditeur, et explique comment le registre MCP s’intègre pour ajouter des serveurs sans copier de commandes depuis des README au hasard.

Le Model Context Protocol (MCP) est le standard ouvert qui permet à un assistant d’IA d’appeler des outils externes : lire un dossier, interroger une base de données, ouvrir une pull request. VS Code joue le rôle de client MCP, et chaque serveur activé apparaît sous forme d’ensemble d’outils en mode agent. Toute la configuration tient dans un petit fichier JSON, ce qui explique pourquoi un mauvais chemin ou un mauvais nom de propriété échoue si discrètement.

Où se trouve mcp.json

VS Code lit les définitions des serveurs MCP à deux endroits principaux, auxquels s’ajoute un format portable décrit plus loin. Considérez-les comme une étagère d’équipe et une étagère personnelle.

Fichier de l’espace de travail : .vscode/mcp.json

Le fichier de l’espace de travail se trouve dans le dossier du projet, à .vscode/mcp.json. Créez le dossier .vscode s’il n’existe pas, placez-y le fichier, et VS Code le détecte. Comme il voyage avec le dépôt, toute personne qui clone le projet obtient la même liste de serveurs.

Vous pouvez aussi l’ouvrir depuis la palette de commandes (Ctrl+Shift+P sous Windows et Linux, Cmd+Shift+P sous macOS) avec MCP: Open Workspace Folder Configuration, ou créer une entrée via MCP: Add Server en choisissant l’option espace de travail.

Fichier utilisateur selon le système d’exploitation

Le fichier utilisateur s’applique à chaque fenêtre que vous ouvrez. Le moyen le plus rapide d’y accéder est la commande de la palette MCP: Open User Configuration, qui ouvre la copie appartenant à votre profil actif. Sur une installation standard, le fichier se trouve dans le dossier de données utilisateur de VS Code :

💡 Astuce : VS Code Insiders dispose de son propre dossier de données, généralement nommé Code - Insiders au lieu de Code. Si une modification ne change rien, vérifiez que vous ne modifiez pas la copie stable pendant que vous utilisez Insiders. En cas de doute, faites confiance à la commande de la palette plutôt qu’à un chemin tapé de mémoire.

Lequel choisir

Le choix dépend de la personne qui a besoin du serveur et de la présence ou non d’un token personnel.

Évitez de définir le même nom de serveur dans les deux fichiers. Avec deux copies, vous ne savez plus laquelle est réellement en cours d’exécution, et un rapport de bug disant « le serveur est cassé » se transforme en une après-midi de devinettes.

Bien rédiger le format du fichier

Le fichier comporte jusqu’à trois sections de premier niveau : servers (obligatoire, un objet qui associe les noms de serveurs à leurs paramètres), inputs (facultative, des demandes de saisie pour les valeurs que vous ne voulez pas stocker) et sandbox (facultative, règles d’accès aux fichiers et au réseau sur macOS et Linux). Tout le reste dépend de ces trois sections.

Un serveur stdio minimal

Un serveur stdio est un programme que VS Code lance sur votre machine et avec lequel il communique via l’entrée et la sortie standard. La plupart des serveurs communautaires fonctionnent ainsi, généralement via npx ou uvx.

{
  "servers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${workspaceFolder}"]
    }
  }
}

Copier le prompt

La variable ${workspaceFolder} correspond au projet ouvert, si bien que le même fichier fonctionne sur la machine de chaque coéquipier. Vous pouvez ajouter cwd pour le répertoire de travail, env pour les variables d’environnement, et envFile pour charger des variables depuis un fichier.

Un serveur HTTP distant

Un serveur distant tourne ailleurs, et VS Code se connecte à son URL. Pas de processus local, pas de npx, pas de problèmes de version de Node.

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

Copier le prompt

Utilisez "type": "http" pour les serveurs distants actuels et "type": "sse" pour les serveurs qui utilisent encore l’ancien transport par événements envoyés par le serveur (server-sent events). Les entrées distantes peuvent aussi contenir headers pour l’authentification, et un objet oauth lorsque le serveur prend en charge une connexion via le navigateur.

Le piège servers ou mcpServers

C’est la cause la plus fréquente d’une configuration copiée qui ne fait rien.

Pourquoi votre serveur n’apparaît jamais

La plupart des README présentent un extrait écrit pour Claude Desktop, Claude Code ou Cursor. Ces clients utilisent une propriété de premier niveau appelée mcpServers. Le format propre à mcp.json attend servers. Collez la mauvaise structure dans .vscode/mcp.json et le fichier peut échouer discrètement : l’éditeur peut signaler la propriété, mais l’avertissement est facile à manquer, et aucun outil n’apparaît.

{
  "mcpServers": {
    "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] }
  }
}

Copier le prompt

Ce bloc appartient à un autre client. Pour VS Code, renommez la propriété de premier niveau en servers et ajoutez "type": "stdio" afin que l’entrée corresponde au format présenté plus haut.

VS Code documente aussi un format portable : un fichier .mcp.json à la racine du projet, ou ~/.copilot/mcp-config.json pour l’utilisateur. Ces fichiers portables utilisent bien mcpServers. La règle est simple : servers dans le mcp.json de VS Code, mcpServers dans les fichiers portables.

Noms des propriétés par client

Parcourez cette courte liste chaque fois que des outils disparaissent :

• Vérifiez le nom de la propriété en premier. servers pour mcp.json, mcpServers pour les fichiers portables.
• Vérifiez le type. Un programme local a besoin de stdio, une URL a besoin de http ou de sse.
• Vérifiez le fichier que vous avez ouvert. Exécutez MCP: List Servers et confirmez que votre serveur apparaît.
• Rechargez la fenêtre après une modification importante si la liste des serveurs semble obsolète.

Garder les secrets hors du fichier

Un fichier mcp.json de l’espace de travail finit généralement dans Git. Tout ce que vous y saisissez, token compris, y finit aussi.

Demander les tokens avec inputs

La section inputs définit les valeurs que VS Code demande au lieu de les stocker. Référencez-en une n’importe où dans une entrée de serveur avec ${input:id}.

{
  "inputs": [
    {
      "type": "promptString",
      "id": "api-token",
      "description": "API token for the image service",
      "password": true
    }
  ],
  "servers": {
    "image-service": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": { "Authorization": "Bearer ${input:api-token}" }
    }
  }
}

Copier le prompt

L’URL ci-dessus est un exemple. Ce qui compte, c’est le schéma : promptString associé à password: true affiche un champ masqué, VS Code demande la valeur au démarrage du serveur, et le token n’a jamais besoin de figurer dans le fichier. Deux autres types d’inputs existent : pickString pour une liste fixe d’options, et command pour une valeur produite par l’exécution d’une commande.

💡 Astuce : le même schéma convient à tout service REST qui utilise un token Bearer, y compris l’API développeur Picasso IA sur api.picassoia.com/v1, dont les tokens commencent par pia_sk_. Conservez ce token dans un input ou une variable d’environnement, jamais dans un fichier commité.

envFile et confiance de l’espace de travail

Pour les serveurs stdio, envFile charge des variables depuis un fichier tel que ${workspaceFolder}/.env. Ajoutez ce fichier à .gitignore avant le premier commit, et non après.

La confiance fonctionne en deux couches. Les serveurs définis dans l’espace de travail héritent de la Workspace Trust, si bien qu’un dossier non approuvé ne les démarre pas. Les serveurs définis hors de l’espace de travail déclenchent leur propre demande de confiance la première fois qu’ils s’exécutent. Le paramètre chat.mcp.autostart contrôle les redémarrages lorsqu’une configuration change, avec les valeurs never, onlyNew et newAndOutdated (la valeur par défaut).

Trouver des serveurs dans le registre

Écrire chaque entrée à la main devient vite fastidieux. VS Code vous propose deux façons de l’éviter.

Parcourir @mcp dans les extensions

Ouvrez la vue Extensions (Ctrl+Shift+X) et tapez @mcp dans la zone de recherche. La liste qui apparaît est la galerie intégrée des serveurs MCP. Choisissez-en un, décidez s’il doit être installé dans votre profil utilisateur ou dans l’espace de travail, et VS Code ajoute l’entrée au mcp.json correspondant. Ouvrez ensuite le fichier et relisez ce qui a été écrit. C’est un bon moyen de voir la syntaxe correcte pour les serveurs que vous ajouterez ensuite à la main.

Ce qu’ajoute le registre officiel

Le registre MCP officiel est le répertoire public dans lequel les auteurs de serveurs publient leurs serveurs. Chaque entrée indique le paquet ou l’URL distante, ce que vous devriez sinon coller vous-même dans mcp.json. Utilisez-le lorsqu’un serveur n’est pas dans la galerie des extensions, et vérifiez le nom du paquet par rapport à l’entrée du registre avant d’exécuter quoi que ce soit. Une faute de frappe dans un argument npx peut installer un autre paquet.

Détecter automatiquement les serveurs d’autres applications

VS Code peut aussi importer les serveurs que vous avez déjà configurés dans d’autres outils. Ouvrez les Paramètres, recherchez chat.mcp, et repérez le paramètre qui contrôle la détection automatique depuis d’autres applications. Si vous voulez repartir de zéro, désactivez-le. Si vous venez de Claude Desktop, le laisser activé vous évite de tout ressaisir.

Réparer un serveur qui ne démarre pas

Lorsqu’un serveur affiche une erreur, la réponse se trouve presque toujours dans son propre journal.

Lire le journal de sortie

Exécutez MCP: List Servers, sélectionnez le serveur et ouvrez sa sortie. Vous pouvez aussi ouvrir mcp.json et regarder au-dessus du nom du serveur, où VS Code affiche des actions en ligne pour démarrer, arrêter, redémarrer et afficher la sortie. Le journal affiche la commande exacte lancée par VS Code, ainsi que tout ce que le processus a écrit sur la sortie d’erreur standard. Lisez la première erreur, pas la dernière.

Schémas d’échec courants

Mode développement et bac à sable

Si vous créez des serveurs, l’objet dev d’une entrée stdio est utile. watch prend un motif glob et redémarre le serveur lorsque les fichiers correspondants changent, et debug attache un débogueur (Node.js et Python sont pris en charge pour les serveurs stdio). Sous macOS et Linux, l’objet sandbox restreint ce qu’un serveur peut toucher : filesystem.allowWrite, filesystem.denyRead, filesystem.denyWrite, network.allowedDomains et network.deniedDomains. Définissez sandboxEnabled sur un serveur particulier pour l’appliquer. Commencez par des règles strictes et n’ouvrez que ce dont le serveur prouve avoir besoin.

Rédiger votre configuration avec Claude Sonnet 5

Si un modèle de langage doit vous aider avec le JSON, choisissez un modèle conçu pour le code. Claude Sonnet 5 sur Picasso IA écrit et corrige du code, lit des captures d’écran, et vous permet de choisir l’intensité de sa réflexion. Voici le flux de travail qui fonctionne pour mcp.json.

1. Ouvrez la page du modèle. Rendez-vous sur Claude Sonnet 5 sur Picasso IA.
2. Renseignez le System Prompt une seule fois. Par exemple : You write VS Code mcp.json files. Use the servers property, never mcpServers. Always set type. Output JSON only.
3. Décrivez la configuration dans Prompt. Indiquez les serveurs souhaités, le système d’exploitation, et si chacun doit être stdio ou distant.
4. Réglez effort. Laissez-le sur low pour une correction en une ligne. Utilisez medium ou high lorsque le fichier combine plusieurs serveurs et inputs. Le paramètre low désactive la réflexion, c’est donc le plus rapide et le moins coûteux.
5. Gardez Max Tokens à la valeur par défaut de 8 192. Un fichier de configuration en demande bien moins.
6. Joignez une capture d’écran si vous avez une erreur. Le champ Image facultatif en accepte une, et Max Image Resolution est fixé par défaut à 0,5 mégapixel pour rester économique.
7. Lancez, puis vérifiez. Collez le résultat dans mcp.json, comparez chaque nom de paquet et chaque URL avec l’entrée du registre, et surveillez le journal de sortie au premier démarrage.

Un prompt qui donne un premier brouillon utilisable :

Create a VS Code mcp.json for Windows with two servers: a stdio filesystem
server limited to the workspace folder, and a remote HTTP server at
https://mcp.example.com/mcp that needs a Bearer token. Ask for the token
with an input so it is never stored in the file.

Copier le prompt

💡 Astuce : les modèles peuvent inventer des noms de paquets qui semblent corrects sans exister. Considérez tout tableau args généré comme un brouillon tant que vous ne l’avez pas comparé au registre.

D’autres modèles de chat et de code de la plateforme font le même travail. Essayez-en plusieurs et gardez celui qui suit le mieux votre system prompt :

Créer vos propres visuels avec Picasso IA

Une configuration MCP fonctionnelle mérite une documentation que les gens lisent vraiment. Un README avec une belle image d’en-tête, un schéma qui montre comment vos serveurs se connectent, ou une courte miniature de tutoriel donne à une page de configuration un aspect achevé. Picasso IA peut produire tout cela.

Commencez avec Picasso IA Image pour un premier brouillon rapide, essayez GPT Image 2 lorsque votre visuel doit contenir du texte lisible, et utilisez Picasso IA Image Editor Pro pour retoucher une image que vous possédez déjà. Pour les scènes photoréalistes, Seedream 4.5 mérite un essai. La plateforme propose aussi le texte vers vidéo et d’autres générateurs, et vous pouvez parcourir toutes les options sur la page de tous les modèles.

Rédigez un prompt, générez quelques variantes, choisissez celle qui convient à votre page et intégrez-la à votre documentation. La meilleure façon de savoir ce qui fonctionne pour votre projet est de l’essayer : ouvrez Picasso IA, tapez une scène que vous voulez voir, et créez votre première image dès aujourd’hui.