Serveurs MCP Codex : migrer depuis Claude sans erreur

Ce qui change - et ce qui ne change pas

Pour un serveur installé avec Node.js, la configuration côté Claude peut ressembler à ceci :

{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp"]
}
}
}

Côté Codex, l'équivalent devient :

[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]

La correspondance est assez directe : context7 devient le nom de la table, command reste une commande et args reste une liste. Là où vous devez être plus vigilant, c'est surtout sur les détails de syntaxe et sur ce qui concerne les serveurs distants (URL, en-têtes, authentification).

Autrement dit : vous évitez souvent de réinstaller un serveur qui fonctionnait déjà. Mais ne confondez pas migration du fichier et compatibilité. Le fait que la déclaration soit transposée ne garantit pas que le serveur aura exactement les mêmes capacités selon le client. Et avant de passer à la suite, vérifiez aussi que la version de Codex que vous utilisez gère bien le mode de connexion et les options dont vous avez besoin.

Où Codex lit-il la configuration ?

En règle générale, la configuration globale se trouve dans ~/.codex/config.toml. Codex peut aussi utiliser un fichier .codex/config.toml à l'intérieur d'un projet de confiance. La distinction compte si vous voulez que certains serveurs soient disponibles partout, tout en réservant d'autres outils à un dépôt précis.

Sur un poste personnel, un réglage global est pratique. En équipe, une configuration liée au projet aide souvent à rendre les choses plus reproductibles. Dans tous les cas, ne faites pas n'importe quoi avec les secrets : ils doivent rester hors du dépôt, même si vous stockez le fichier de configuration dedans.

Les correspondances à connaître

En JSON, les objets imbriqués se traduisent souvent par des tables TOML. Les tableaux JSON deviennent des listes entre crochets. Les chaînes restent entre guillemets. Par exemple :

[mcp_servers.outil_interne]
command = "node"
args = ["serveur.js"]
env = { API_KEY = "valeur" }

La syntaxe inline env = { ... } est importante : côté JSON, env est un objet ; en TOML, cette écriture donne une table intégrée sur une seule ligne. Et même si l'exemple montre la structure, il ne faut pas y mettre un secret en clair.

Gardez aussi des noms de serveurs explicites et stables. docs ou base_clients sera plus facile à diagnostiquer que mcp1 et mcp2, surtout quand vous testez plusieurs environnements. Évitez simplement d'y coller une info confidentielle ou un identifiant de client.

Une méthode de conversion qui limite les oublis

Avant de passer au serveur suivant, vérifiez systématiquement :

• Le nom de la table correspond bien à celui du serveur dans la configuration d'origine.
• La commande est exacte et disponible sur la machine qui exécute Codex.
• Les arguments sont dans le même ordre qu'avant.
• Les variables d'environnement nécessaires sont bien présentes, sans secret en clair.
• Les paramètres de connexion correspondent au bon type de serveur : local ou distant.

Cette vérification est souvent plus fiable qu'une conversion « globale » faite d'un bloc. Elle vous aide aussi à isoler les problèmes : si un seul serveur ne démarre pas, vous savez où regarder. Pour une dizaine de serveurs, une conversion automatisée peut gagner du temps, mais vous devrez quand même relire : un convertisseur peut transformer des structures, sans savoir si une clé est encore pertinente, ni si le serveur est adapté à votre contexte.

Déclarer un serveur distant

Pour une entrée distante, vous utilisez url. Les en-têtes HTTP éventuels se déclarent avec http_headers. Par exemple :

[mcp_servers.service_distant]
url = "https://exemple.fr/mcp"
http_headers = { X-Client = "codex" }

Le domaine et le chemin sont des exemples : adaptez à votre service et relisez la documentation du fournisseur. Certaines intégrations demandent une authentification, d'autres non. Et surtout : ne « copiez-collez » pas des en-têtes d'une autre appli sans vérifier qu'ils s'appliquent bien au serveur concerné.

Garder les jetons hors du fichier

Mettre un jeton directement dans http_headers peut vite devenir un problème : sauvegarde, capture d'écran, dépôt partagé... bref, tout ce qu'on ne contrôle plus. Pour éviter ça, Codex peut récupérer un jeton depuis une variable d'environnement via bearer_token_env_var :

[mcp_servers.service_distant]
url = "https://exemple.fr/mcp"
bearer_token_env_var = "SERVICE_MCP_TOKEN"

La variable doit exister dans l'environnement où Codex tourne. Si elle est définie seulement dans votre terminal, ne partez pas du principe qu'une application lancée depuis un menu système la trouvera automatiquement. Cette différence d'environnement explique beaucoup d'échecs « bêtes » : le fichier TOML est bon, mais l'authentification ne passe pas.

Si vous travaillez en équipe, mettez en place une procédure claire pour les secrets : stockage adapté, droits limités, renouvellement, révocation si un jeton fuit. Le fichier TOML décrit comment se connecter ; il ne remplace pas une politique de gestion des identifiants. Ça compte encore plus si le serveur peut accéder à des dépôts privés, à des données clients ou à des outils internes.

Quand la commande est plus pratique

Pour ajouter rapidement un serveur local, vous pouvez utiliser :

codex mcp add context7 -- npx -y @upstash/context7-mcp

Puis vérifier ce qui est déclaré :

codex mcp list

C'est pratique quand l'ajout est simple et reproductible. Vous limitez aussi le risque d'une faute de syntaxe dans le TOML. Mais la commande ne décide pas à votre place du « bon » périmètre (global ou projet) ni des permissions. Après l'ajout, relisez le fichier et testez vraiment la connexion.

Où retrouver l'ancienne configuration Claude

Sur macOS, le fichier de Claude Desktop se trouve généralement ici :

~/Library/Application Support/Claude/claude_desktop_config.json

Sous Windows :

%APPDATA%\Claude\claude_desktop_config.json

Ces chemins servent à retrouver l'existant, mais ils ne garantissent pas que votre installation utilise exactement la valeur standard. Si votre contexte est particulier, vérifiez plutôt le fichier réellement chargé par l'application.

Si vous avez beaucoup de serveurs, un outil de conversion peut accélérer le premier passage, y compris dans le sens inverse (TOML vers JSON). Dans ce cas, considérez-le comme une aide à la saisie : ce n'est ni une validation de sécurité, ni une preuve de compatibilité. Pour une migration ponctuelle, faire la conversion à la main reste souvent plus rapide que d'introduire un outil en plus.

Liste de contrôle avant usage

• Le bon fichier est bien utilisé : ~/.codex/config.toml ou celui du projet concerné.
• Chaque serveur a bien une table [mcp_servers.nom] avec le bon nom.
• Commandes et arguments sont repris sans erreur.
• Les serveurs distants ont une URL correcte et les en-têtes nécessaires.
• Les jetons ne sont pas stockés en clair dans un fichier partagé.
• Les serveurs n'obtiennent que les accès dont ils ont besoin pour leur rôle.
• Tout est testé après un redémarrage ou un rechargement de Codex.

Les erreurs les plus fréquentes sont rarement « mystérieuses » : chemin incorrect, variable d'environnement absente, argument oublié, URL copiée avec une faute. Un autre piège courant : modifier la configuration globale alors que Codex lit celle du projet (ou l'inverse). Pour diagnostiquer, changez un élément à la fois et appuyez-vous sur les messages de l'application ou de la commande pour repérer l'étape qui échoue.

Mesurer le risque à la bonne échelle

Un serveur MCP peut exposer des fonctions ou des données à l'assistant. Le risque dépend donc de plus que le format TOML : il dépend des permissions réelles du serveur, des données qu'il peut atteindre et du contexte d'utilisation. En environnement pro, commencez par n'activer que les outils nécessaires au projet, limitez les accès, et évitez d'ajouter par défaut tous les serveurs disponibles.

Cette logique est plus utile qu'une règle absolue du type « ne jamais utiliser de serveur distant ». Un serveur local peut aussi être risqué s'il a trop de droits. Un service distant peut être acceptable si son accès est encadré. La migration est surtout une bonne occasion de relire ce que chaque outil peut réellement lire ou modifier - au lieu de transporter à l'identique une configuration qui n'est peut-être plus pertinente.