Codex lit les serveurs MCP depuis config.toml, et vous pouvez les ajouter avec une seule commande codex mcp add. Cet article présente les réglages exacts pour les serveurs locaux et distants, la connexion OAuth, les délais d’attente et les filtres d’outils, ainsi que les solutions aux erreurs qui font perdre un après-midi.
Codex est un agent de code performant à lui seul, mais il ne voit que ce que vous lui donnez : vos fichiers, votre shell et ce que le modèle connaît déjà. Les serveurs MCP changent cela. En en ajoutant un, Codex peut interroger une base de données, lire un gestionnaire de tickets, rechercher dans la documentation d’une bibliothèque ou générer une image à partir du même prompt que celui où vous demandez du code. Le piège, c’est que la configuration se trouve dans un fichier TOML et quelques options CLI, et qu’un seul mauvais réglage suffit pour que le serveur n’apparaisse jamais, sans aucun message d’erreur.
Cet article vous donne la configuration MCP de Codex exacte pour les serveurs locaux et distants, les commandes qui l’écrivent à votre place, et les solutions aux erreurs que l’on rencontre le plus souvent. Les réglages et valeurs par défaut présentés ci-dessous correspondent à la documentation d’OpenAI Codex en date d’octobre 2026.
MCP, le Model Context Protocol, est un standard ouvert qui permet à un client d’IA d’appeler des outils exposés par un programme séparé. Ce programme est le serveur. Codex est le client. Chaque serveur publie une liste d’outils avec leurs noms, leurs descriptions et leurs schémas d’entrée, et Codex décide, pendant une tâche, quand l’un d’eux mérite d’être appelé.
Sans serveurs, Codex modifie des fichiers et exécute des commandes shell. Avec eux, la même session peut interroger votre base de données de préproduction, récupérer une spécification de design ou demander à un index de documentation comment une bibliothèque se comporte dans sa dernière version, au lieu de deviner à partir de ses données d’entraînement.
Codex prend en charge deux types de serveurs, et chaque réglage que vous écrivez appartient à l’un d’eux.
| Type | Où il s’exécute | Réglage requis | Exemple type |
|---|---|---|---|
| stdio | Un processus que Codex démarre sur votre machine | command | Un serveur lancé avec npx ou node |
| Streamable HTTP | Un service distant joint par URL | url | Un gestionnaire de tickets hébergé ou un hébergeur de code en ligne |
Les serveurs stdio locaux démarrent avec Codex et s’arrêtent à sa fermeture. Les serveurs distants tournent déjà ailleurs : Codex n’a besoin que de leur adresse et, en général, d’un identifiant.
💡 Astuce : Commencez avec un ou deux serveurs. Chaque outil exposé s’ajoute à ce que le modèle lit avant d’agir, et une liste d’outils trop chargée rend ses choix moins précis.
Codex conserve les entrées MCP dans le même config.toml que pour tous ses autres réglages. Il n’existe aucun fichier MCP séparé à chercher.
L’emplacement par défaut est ~/.codex/config.toml. Sous Windows, il correspond à un dossier .codex dans votre profil utilisateur. Les serveurs définis ici sont disponibles dans chaque projet que vous ouvrez. L’application de bureau ChatGPT, la CLI de Codex et l’extension pour l’IDE lisent tous ce même fichier : un serveur ajouté une seule fois apparaît donc dans les trois.
Vous pouvez aussi placer un .codex/config.toml à l’intérieur d’un dépôt pour limiter les serveurs à ce projet. Codex ne le lit que pour les projets approuvés, ce qui empêche un dépôt fraîchement cloné de lancer discrètement des commandes sur votre machine. Les fichiers de projet conviennent aux serveurs qui n’ont de sens que dans une seule base de code, comme une base de données pointant vers le schéma de développement de cette application, et ils permettent aux membres de l’équipe de partager une configuration via le contrôle de version.
💡 Astuce : Ne versionnez jamais de jetons. Référencez les variables d’environnement par leur nom, comme indiqué ci-dessous, et conservez les valeurs dans votre profil shell ou un gestionnaire de secrets.
La méthode la plus rapide est codex mcp add. Elle écrit l’entrée TOML à votre place, ce qui évite les fautes de frappe dans les noms de tables et les guillemets. Utilisez-la en premier, puis ouvrez le fichier pour affiner.
Tout ce qui suit le double tiret est la commande que Codex exécutera :
codex mcp add context7 -- npx -y @upstash/context7-mcp
Cela enregistre un serveur nommé context7, lancé via npx. Pour transmettre des variables d’environnement, placez les options --env avant le double tiret :
codex mcp add postgres --env DATABASE_URL=postgresql://localhost:5432/mydb -- node pg-mcp-server.js
Choisissez des noms courts, en minuscules et sans espaces. Le nom devient le nom de la table TOML et identifie le serveur dans chaque liste.
Les serveurs distants utilisent --url à la place d’une commande finale :
codex mcp add github --url https://api.githubcopilot.com/mcp/ --bearer-token-env-var GITHUB_PAT_TOKEN
--bearer-token-env-var désigne la variable d’environnement qui contient le jeton. Le jeton lui-même n’est jamais écrit sur le disque, seul le nom de la variable l’est, ce qui vaut mieux que de coller un secret dans un en-tête. Exportez la variable dans le shell qui lance Codex :
export GITHUB_PAT_TOKEN="paste-your-token-here"
Certains serveurs hébergés n’utilisent pas de jetons statiques et passent par OAuth. Ajoutez le serveur avec son URL, puis authentifiez-vous :
codex mcp add linear --url https://mcp.linear.app/mcp
codex mcp login linear
login lance le flux OAuth, en général dans votre navigateur, et enregistre les identifiants obtenus. Lorsqu’un serveur documente des autorisations précises, ajoutez --scopes suivi d’une liste de valeurs séparées par des virgules. Pour supprimer les identifiants enregistrés, exécutez codex mcp logout linear.
La CLI est rapide, mais les délais d’attente, les filtres d’outils et les variables transmises se trouvent dans le fichier lui-même. Chaque entrée est une table nommée mcp_servers.<name>, avec un tiret bas et un pluriel.
Voici ce que produit la commande context7 vue précédemment :
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
Voici les réglages qu’accepte un serveur stdio :
| Réglage | Requis | Rôle |
|---|---|---|
command | Oui | Le programme qui démarre le serveur |
args | Non | Les arguments transmis à ce programme |
env | Non | Les variables d’environnement définies pour le processus du serveur |
env_vars | Non | Les variables d’environnement existantes à autoriser et à transmettre |
cwd | Non | Le répertoire de travail utilisé au démarrage |
env définit des valeurs littérales, tandis que env_vars transmet des variables déjà présentes dans votre shell. Privilégiez env_vars pour tout secret, afin que la valeur n’apparaisse jamais dans le fichier :
[mcp_servers.postgres]
command = "node"
args = ["pg-mcp-server.js"]
cwd = "/home/dev/db-tools"
env_vars = ["DATABASE_URL"]
[mcp_servers.postgres.env]
LOG_LEVEL = "info"
Les entrées distantes remplacent command par url :
[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"
bearer_token_env_var = "LINEAR_TOKEN"
| Réglage | Requis | Rôle |
|---|---|---|
url | Oui | L’adresse du serveur |
bearer_token_env_var | Non | Nom de la variable qui contient un jeton porteur |
http_headers | Non | Noms d’en-têtes statiques associés à des valeurs |
env_http_headers | Non | Noms d’en-têtes associés à des noms de variables d’environnement |
Lorsqu’un service attend un en-tête personnalisé plutôt qu’un jeton porteur, utilisez les deux tables d’en-têtes. La seconde garde les secrets hors du fichier :
[mcp_servers.docs]
url = "https://docs.example.com/mcp"
[mcp_servers.docs.http_headers]
X-Team = "platform"
[mcp_servers.docs.env_http_headers]
X-Api-Token = "DOCS_API_TOKEN"
Les deux types de serveurs acceptent les mêmes réglages facultatifs :
| Réglage | Valeur par défaut | Rôle |
|---|---|---|
startup_timeout_sec | 10 | Le temps que Codex attend le démarrage du serveur |
tool_timeout_sec | 60 | La durée maximale d’un appel d’outil |
enabled | true | Passez à false pour désactiver un serveur sans le supprimer |
enabled_tools | Aucun filtre | Une liste d’autorisation des outils que Codex peut appeler |
disabled_tools | Aucun filtre | Une liste de refus des outils que Codex ne doit pas appeler |
required | false | Passez à true pour faire échouer le démarrage si le serveur est indisponible |
Une entrée réglée ressemble à ceci. Remplacez les noms d’outils par ceux que /mcp liste pour votre serveur :
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 120
enabled_tools = ["tool_one", "tool_two"]
Une liste d’autorisation est le choix le plus sûr pour les serveurs qui peuvent écrire ou supprimer des données. Utilisez disabled_tools lorsque vous faites confiance à un serveur et ne voulez bloquer qu’un ou deux outils risqués. Utilisez required = true dans les exécutions automatisées, où un serveur manquant doit faire échouer la tâche en signalant clairement l’erreur au lieu de laisser Codex continuer sans ses données.
💡 Astuce : Réglez
enabled = falseplutôt que de supprimer une entrée dont vous n’avez besoin qu’occasionnellement. Les réglages restent en place, et il suffit de changer une ligne pour la réactiver.
Ajouter un serveur ne prouve rien tant que Codex ne liste pas ses outils. Effectuez les deux vérifications à chaque fois.
Dans une session interactive, tapez /mcp. Codex affiche les serveurs connectés et les outils que chacun expose. Si votre serveur est absent, ou apparaît sans aucun outil, rien d’autre n’a d’importance tant que ce point n’est pas réglé. Redémarrez la session après avoir modifié le fichier pour que Codex lise les nouveaux réglages.
La famille codex mcp gère tout sans ouvrir d’éditeur :
| Commande | Rôle |
|---|---|
codex mcp list | Afficher les serveurs configurés avec l’état de leur authentification |
codex mcp get <name> | Inspecter la configuration d’un serveur |
codex mcp add <name> | Enregistrer un serveur stdio ou HTTP |
codex mcp remove <name> | Supprimer une entrée de serveur |
codex mcp login <name> | Démarrer l’authentification OAuth |
codex mcp logout <name> | Supprimer les identifiants OAuth enregistrés |
Ajoutez --json à list ou get lorsqu’un script doit lire la sortie. Une fois le serveur visible, donnez à Codex une tâche que seul ce serveur peut résoudre, par exemple demander la signature actuelle d’une fonction de bibliothèque indexée par votre serveur de documentation.
La plupart des échecs se ramènent à une poignée de causes. Parcourez-les dans cet ordre.
npx -y télécharge le paquet, et 10 secondes sont souvent trop courtes. Portez startup_timeout_sec à 30 ou plus.command lui-même, donc le programme doit se trouver dans le PATH du shell qui a démarré Codex. Un chemin absolu lève le doute.npx est un script sous Windows, et un lancement direct peut échouer. Passez-le par cmd :[mcp_servers.context7]
command = "cmd"
args = ["/c", "npx", "-y", "@upstash/context7-mcp"]
required = true pendant les tests pour qu’un serveur défaillant arrête la session avec une erreur lisible.bearer_token_env_var et env_vars lisent l’environnement du processus qui a lancé Codex. Une variable définie dans un autre onglet de terminal, ou une application de bureau ouverte depuis le dock sans votre profil shell, ne la verra pas. Vérifiez avec echo $GITHUB_PAT_TOKEN.codex mcp logout <name> puis codex mcp login <name> pour obtenir une session neuve..codex/config.toml dans un projet non approuvé est ignorée. Approuvez le projet, ou déplacez l’entrée dans le fichier global.tool_timeout_sec au-dessus de sa valeur par défaut de 60 secondes.Les sessions de code ont souvent besoin d’images : une image principale pour une page d’accueil, une maquette de produit, un court clip pour un README. PicassoIA propose ses modèles de génération via une API pour développeurs et via des connexions MCP, si bien que la même configuration Codex peut demander des médias sans quitter le terminal.
Voici les faits utiles à connaître avant de vous lancer :
https://api.picassoia.com/v1, et les identifiants commencent par pia_sk_.picassoia.com/en/mcp/accounts après connexion, et l’adresse du serveur y est affichée plutôt que publiée sur le site public.Une fois l’adresse en main, le côté Codex suit le schéma vu plus haut. Si la page vous donne une URL distante, enregistrez-la avec codex mcp add picassoia --url <address> et ajoutez une variable de jeton porteur si elle en demande un. Si elle vous donne une commande à exécuter localement, utilisez plutôt la forme stdio. Les conditions d’abonnement pour l’accès API et MCP sont indiquées sur la page des tarifs, consultez-la avant de construire un flux de travail autour de cet accès.
Avant d’automatiser quoi que ce soit, testez un prompt à la main pour savoir à quoi ressemble une bonne requête :
Les modèles de chat vous aident aussi pour la configuration. Collez une erreur confuse dans GPT 5.6 Sol ou Claude Sonnet 5 et demandez quel réglage TOML elle désigne. Les deux figurent sur PicassoIA pour les tâches de code, et un second avis ne coûte rien avant de modifier le fichier.
Vous disposez maintenant de tout ce qu’il faut pour une configuration MCP de Codex fonctionnelle : les emplacements des fichiers, les commandes CLI, les réglages pour les deux types de serveurs, une routine de vérification et une courte liste de solutions. Ajoutez un serveur, confirmez-le avec /mcp, puis confiez à Codex une vraie tâche.
Si vous voulez le mettre au service de vos visuels, ouvrez PicassoIA Image et écrivez votre premier prompt. Décrivez une scène comme le ferait un photographe, avec la lumière, l’objectif et les textures, puis comparez le résultat avec une version PicassoIA Video de la même idée. Parcourez le catalogue complet sur picassoia.com/en/all-models et découvrez ce que PicassoIA peut créer pour vous.
Choisissez votre langue
