Configurer un serveur MCP dans GitHub Copilot : registre, liste autorisée et config

Votre premier serveur MCP dans GitHub Copilot se connecte en environ deux minutes. Faire approuver ce même serveur par la sécurité, l’inscrire dans un registre et le placer sur une liste autorisée prend le reste de la semaine, sauf si vous savez quel réglage fait quoi. Cet article suit les trois couches dans l’ordre : le fichier de configuration que rédige le développeur, le registre que parcourt l’équipe et la liste autorisée qu’un administrateur impose. Chaque exemple JSON correspond à la documentation actuelle de GitHub et de VS Code, et chaque limite est signalée exactement à l’endroit où elle pose problème.

💡 En bref : les développeurs rédigent mcp.json, les équipes choisissent des serveurs dans un registre, et les administrateurs imposent allowedMcpServers dans managed-settings.json. Trois fichiers, trois responsables, et un bug dans l’un d’eux donne l’impression que « Copilot n’a aucun outil ».

Ce que fait MCP dans Copilot

Le Model Context Protocol (MCP) est la norme ouverte qui permet à Copilot d’appeler des outils situés hors de l’éditeur : une requête sur une base de données, la consultation d’un ticket Sentry, une session de navigateur, un outil de suivi de tickets. Sans MCP, Copilot ne voit que ce que votre éditeur lui affiche. Avec MCP, le mode agent peut lire le problème qui échoue, interroger les données qui s’y rattachent, puis modifier le code à l’origine du bug, le tout dans une seule conversation.

Chaque serveur expose des outils, et Copilot vous demande votre approbation avant que l’agent en exécute un. Les serveurs locaux communiquent via stdio, ce qui signifie que Copilot lance un processus sur votre machine. Les serveurs distants communiquent via HTTP en streaming ou via le transport SSE, plus ancien, ce qui signifie que Copilot se connecte à une URL. Cette différence unique, une commande ou une URL, détermine presque toutes les décisions de configuration qui suivent : elle indique quels champs JSON écrire, comment fonctionne l’authentification et comment une liste autorisée peut correspondre au serveur.

Clients compatibles

La configuration MCP n’est pas identique selon les surfaces de Copilot. Le fichier et son format changent à chacune :

Fichiers de configuration et leur emplacement

Si vous placez le fichier au mauvais endroit, Copilot l’ignore sans message d’erreur évident. Commencez par décider qui doit recevoir le serveur.

Portée espace de travail ou utilisateur

.vscode/mcp.json se trouve dans le dépôt, donc tous ceux qui le clonent reçoivent les mêmes serveurs. C’est donc le bon endroit pour les outils de projet, comme un inspecteur de base de données ou un navigateur Playwright. La configuration de votre profil utilisateur s’applique à tous les espaces de travail de votre machine. Ouvrez-la depuis la palette de commandes avec MCP: Open User Configuration et conservez-y vos outils personnels.

Une règle simple fonctionne : si un coéquipier serait déconcerté par l’absence du serveur, validez-le dans le dépôt. Si vous êtes le seul à l’utiliser, gardez-le dans votre profil.

Fichiers portables pour les autres clients

La référence de configuration MCP de VS Code liste aussi un format portable : .mcp.json à la racine de l’espace de travail, ou ~/.copilot/mcp-config.json pour votre utilisateur. Utilisez-le lorsque le même dépôt est ouvert depuis plusieurs clients Copilot et que vous voulez une seule définition au lieu de trois.

Chaque entrée de serveur est construite à partir du même petit ensemble de champs :

Deux options supplémentaires existent uniquement sous macOS et Linux : un objet sandbox de premier niveau (règles du système de fichiers et du réseau) et un interrupteur sandboxEnabled par serveur.

Rédiger votre premier mcp.json

Vous pouvez écrire le fichier à la main ou lancer MCP: Add Server depuis la palette de commandes et laisser VS Code générer l’entrée. Il vaut la peine de l’écrire une fois à la main, car chaque problème ultérieur sera plus facile à repérer lorsque vous connaîtrez à quoi ressemble un fichier sain.

Un serveur local en stdio

Cette entrée lance le serveur MCP Playwright via npx chaque fois que Copilot en a besoin :

{
  "servers": {
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Copier le prompt

Enregistrez le fichier et VS Code affiche les actions Start, Stop et Restart au-dessus de l’entrée. Démarrez-le, ouvrez le chat Copilot en mode agent et vérifiez le sélecteur d’outils : les outils du serveur doivent maintenant apparaître et pouvoir être activés.

Un serveur HTTP distant

Un serveur distant a besoin d’une URL au lieu d’une commande. Celui-ci pointe vers le serveur MCP GitHub hébergé :

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

Copier le prompt

Si le serveur prend en charge OAuth, VS Code ouvre un flux de connexion la première fois qu’un outil s’exécute. S’il attend un jeton statique, transmettez-le via headers, et ne collez jamais le jeton lui-même dans un fichier validé.

Garder les secrets hors de la configuration

VS Code résout ce problème grâce aux variables d’entrée. Vous déclarez une entrée une seule fois, vous la marquez comme mot de passe et vous la référencez avec ${input:id} :

{
  "inputs": [
    {
      "type": "promptString",
      "id": "sentry-token",
      "description": "Sentry auth token",
      "password": true
    }
  ],
  "servers": {
    "sentry": {
      "type": "stdio",
      "command": "npx",
      "args": ["@sentry/mcp-server@latest"],
      "env": { "SENTRY_TOKEN": "${input:sentry-token}" }
    }
  }
}

Copier le prompt

VS Code demande la valeur la première fois que le serveur démarre, de sorte que le dépôt ne contient jamais que l’espace réservé. Les entrées existent en trois types : promptString pour un texte saisi, pickString pour une liste déroulante et command pour une valeur produite en exécutant une commande. Chaque entrée nécessite type, id et description.

💡 Un fichier .vscode/mcp.json validé contenant un jeton collé est la fuite MCP la plus courante. Si vous utilisez envFile, ajoutez ce fichier à .gitignore dans le même commit.

Trouver des serveurs dans le registre

Écrire à la main le JSON de chaque serveur finit vite par lasser. Le registre existe justement pour vous en éviter la peine.

Le registre MCP de GitHub

github.com/mcp répertorie des serveurs de la communauté qui connectent les modèles aux fichiers, aux API et aux bases de données. Au moment de la rédaction, il en affiche 375, de Markitdown de Microsoft à Stripe et Figma, chacun avec un bouton Install. L’installation ajoute une entrée à votre configuration, donc lisez-la avant de démarrer le serveur : vérifiez la commande, le nom du paquet et l’URL.

VS Code liste aussi les serveurs MCP directement dans l’éditeur. Saisissez @mcp dans la zone de recherche de la vue Extensions pour les parcourir, installez-en un, et VS Code ajoute l’entrée à votre configuration utilisateur ou d’espace de travail. Considérez une fiche du registre comme un point de départ, pas comme un audit de sécurité.

Exécuter votre propre registre

Les organisations peuvent héberger leur propre registre MCP et y faire pointer Copilot. Si vous le construisez sur Azure API Center, saisissez l’URL de base sous cette forme :

https://SERVICE-NAME.data.REGION.azure-apicenter.ms/workspaces/WORKSPACE-NAME

N’ajoutez pas de suffixe de route tel que /v0.1/servers. Copilot ajoute lui-même le chemin MCP v0.1, et un suffixe fait échouer le registre. Les propriétaires d’entreprise définissent l’URL sous AI controls, puis MCP. Les propriétaires d’organisation la définissent sous Copilot, puis Policies.

Verrouiller les serveurs avec des listes autorisées

Les administrateurs disposent de deux moyens pour décider quels serveurs les développeurs peuvent exécuter. Ils ne sont pas équivalents, choisissez donc en connaissance de cause.

La documentation de GitHub présente les paramètres gérés comme la méthode plus sûre et disponible en général, et décrit la politique « registry only » comme n’étant pas celle recommandée.

La méthode des paramètres gérés

Ajoutez l’un ou les deux de allowedMcpServers et deniedMcpServers à copilot/managed-settings.json dans le dépôt .github-private de votre organisation, puis validez sur la branche par défaut :

{
  "allowedMcpServers": [
    { "serverUrl": "https://api.githubcopilot.com/*" },
    { "serverCommand": ["npx", "@playwright/mcp@latest"] }
  ],
  "deniedMcpServers": [
    { "serverUrl": "https://untrusted.example/*" }
  ]
}

Copier le prompt

Il existe trois types de correspondance :

• serverUrl correspond aux serveurs HTTP et SSE distants, prend en charge les caractères génériques * et canonicalise les URL pour empêcher le contournement.
• serverCommand correspond à un serveur stdio local par sa commande et ses arguments exacts.
• serverName correspond au libellé saisi par un utilisateur dans sa configuration. C’est une commodité, pas une frontière de sécurité.

Fonctionnement de la correspondance

Copilot évalue un serveur dans un ordre fixe :

1. Les valeurs par défaut intégrées sont toujours autorisées.
2. La liste de refus bloque tout ce qui correspond.
3. S’il existe une liste autorisée, le serveur doit correspondre à une entrée, sinon il est bloqué.
4. Toute ${VARIABLE} non résolue dans la configuration bloque le serveur.

En l’absence de toute liste autorisée, un serveur s’exécute sauf s’il est refusé ou contient une variable non résolue. Lorsque plusieurs sources managed-settings.json s’appliquent, chaque paramètre s’applique et une règle de refus provenant de n’importe quelle source bloque le serveur. Vous pouvez marquer des paramètres overridable afin qu’une équipe puisse personnaliser sa propre couche.

💡 La correspondance des commandes est exacte. Si vous autorisez ["npx", "@playwright/mcp@latest"], un développeur qui exécute npx -y @playwright/mcp@latest ne correspond pas, car les arguments diffèrent. Publiez l’entrée exacte que vous voulez que les gens copient.

La politique registry only

Vous restez sur la voie de l’aperçu ? Activez la politique MCP servers in Copilot, saisissez l’URL de votre registre, puis réglez Restrict MCP access to registry servers sur Registry only. Le changement s’applique immédiatement. Comme elle correspond sur le nom ou l’ID, considérez-la comme un garde-fou contre les erreurs de bonne foi, et réservez les environnements à risque élevé aux paramètres gérés. Les étapes complètes figurent dans la documentation GitHub sur l’accès MCP.

Configuration de l’agent cloud et de la CLI

L’agent cloud Copilot (anciennement l’agent de codage) s’exécute sur l’infrastructure de GitHub, donc il ne peut pas lire votre .vscode/mcp.json local. Il possède sa propre configuration, et c’est là que surviennent la plupart des erreurs de copier-coller.

Ouvrez le dépôt, allez dans Settings, choisissez Copilot sous Code & automation, et modifiez la zone MCP configuration :

{
  "mcpServers": {
    "sentry": {
      "type": "local",
      "command": "npx",
      "args": ["@sentry/mcp-server@latest"],
      "tools": ["list_issues"],
      "env": { "SENTRY_TOKEN": "$COPILOT_MCP_SENTRY_TOKEN" }
    }
  }
}

Copier le prompt

Cinq règles distinguent ce format de celui de VS Code :

• Le champ de premier niveau est mcpServers, et non servers.
• type accepte local, stdio, http ou sse.
• tools est obligatoire. Utilisez ["*"] pour tout, ou listez les noms d’outils pour limiter fortement la marge de manœuvre de l’agent.
• Les secrets doivent être ajoutés comme secrets ou variables de l’agent dont les noms commencent par COPILOT_MCP_, et la configuration doit référencer ces noms exacts.
• Seuls les outils sont pris en charge, et les serveurs distants ne peuvent pas utiliser OAuth.

Les serveurs MCP GitHub et Playwright sont déjà activés dans chaque dépôt, vous n’ajoutez donc que ce qui manque. Lisez la documentation MCP de l’agent cloud avant d’ajouter quoi que ce soit qui écrit des données.

Copilot CLI. La CLI lit ~/.copilot/mcp-config.json. Dans une session interactive, /mcp add vous guide pour ajouter un serveur sans modifier le JSON à la main. Les listes autorisées issues des paramètres gérés sont aussi appliquées ici, donc un serveur qui fonctionne dans VS Code mais est bloqué dans le terminal indique généralement un décalage de politique, et non une installation défaillante.

Corriger rapidement les erreurs courantes

La plupart des échecs se ramènent à cinq causes. Repérez votre symptôme dans le tableau avant de réinstaller quoi que ce soit.

Le serveur démarre mais sans outils

Exécutez MCP: List Servers, choisissez le serveur et ouvrez sa sortie. Un plantage au lancement révèle généralement un environnement d’exécution manquant (Node ou Python absent du chemin d’accès) ou un mauvais nom de paquet. Si le processus fonctionne, ouvrez le sélecteur d’outils en mode agent et vérifiez que les outils sont activés.

Bloqué par la politique

Un serveur bloqué a presque toujours l’une de trois causes : une liste autorisée existe et rien ne correspond, une règle de refus provenant d’une autre source managed-settings.json s’applique, ou la configuration contient une ${VARIABLE} non résolue. Comme les politiques bloquent en cas d’échec, un fichier de paramètres malformé bloque les serveurs au lieu de les laisser passer. Demandez à l’administrateur quelle source a bloqué le serveur avant de modifier votre propre configuration.

Extraits collés depuis d’autres clients. Un extrait copié depuis la documentation d’un autre client MCP utilise presque toujours mcpServers. Collez-le dans .vscode/mcp.json et rien ne se charge, sans aucun message. Renommez le champ, ajoutez type explicitement et déplacez les secrets vers des entrées au passage.

Mettre PicassoIA à profit

Un second regard repère les bugs fastidieux : un mauvais nom de champ, une liste tools manquante, un argument qui casse une correspondance exacte. Vous pouvez en obtenir un en une minute.

Utiliser Claude Sonnet 5 sur PicassoIA

Claude Sonnet 5 lit une configuration, raisonne sur des problèmes en plusieurs étapes et accepte une image, ce qui le rend bien adapté à cette tâche. Voici une façon reproductible de l’utiliser :

1. Ouvrez la page de Claude Sonnet 5 sur PicassoIA.
2. Dans System Prompt, définissez le rôle une fois : « Vous examinez des configurations MCP de GitHub Copilot. Vérifiez le champ de premier niveau, le type de transport, la liste des outils, la gestion des secrets et les entrées de liste autorisée en correspondance exacte. »
3. Collez votre mcp.json ou managed-settings.json dans Prompt. Remplacez au préalable chaque jeton réel par un espace réservé.
4. Réglez Effort sur high pour la logique des listes autorisées. La valeur par défaut low convient pour une vérification des fautes de frappe et répond en quelques secondes.
5. Laissez Max Tokens à 8192, ce qui suffit pour une revue complète.
6. Joignez une capture d’écran de l’erreur dans le champ Image si vous en avez une, car le modèle lit les images.
7. Lancez-le, puis appliquez les corrections une à une et redémarrez le serveur après chacune.

Pour un second avis, envoyez le même prompt à GPT 5.6 Sol, Gemini 3.1 Pro ou Kimi K2.6 et comparez les points de désaccord. Un désaccord indique généralement la ligne qui mérite votre propre lecture.

Créer vos propres images ensuite

Déployer cela dans une équipe implique une page de wiki, une diapositive pour la revue de sécurité et une image d’en-tête qui n’ait pas l’air d’un clipart générique. Picasso IA génère tout cela à partir d’un prompt textuel. Essayez Qwen Image 3 pour des scènes photoréalistes, Seedream 5 Pro pour une sortie nette en 2K, ou GPT Image 2.5 Flare lorsque vous avez besoin d’un brouillon rapide. Décrivez la scène, choisissez un format 16:9 et itérez jusqu’à ce que le résultat convienne à votre document. Ouvrez Picasso IA, rédigez votre premier prompt et voyez à quoi ressemble votre prochain article de déploiement avec une vraie image d’en-tête.