Serveurs MCP dans Codex CLI : ajouter, configurer, s'authentifier
Les serveurs MCP apportent de nouveaux outils à Codex : documentation à jour, votre base de données, vos dépôts GitHub. Ce pas à pas exécute codex mcp add pour un serveur stdio local, passe à un serveur distant avec --url et OAuth, inspecte les entrées config.toml des deux et montre les vérifications qui prouvent qu'un serveur fonctionne vraiment.
L'essentiel
- Codex lit les serveurs MCP depuis ~/.codex/config.toml (global) ou .codex/config.toml (projet). Chaque entrée est une table [mcp_servers.<name>] avec command/args pour un serveur stdio local ou url pour un serveur distant.
- codex mcp add context7 -- npx -y @upstash/context7-mcp installe un serveur stdio sans toucher au fichier ; codex mcp add <name> --url https://mcp.example.com/mcp enregistre un serveur distant.
- Les serveurs distants s'authentifient dans le navigateur à la première connexion (Codex affiche Detected OAuth support et ouvre l'écran de consentement), ou plus tard via codex mcp login <name>.
- Vérifiez avec /mcp dans la TUI ou codex mcp list dans le shell. Codex 0.160.1 préserve en outre SYSTEMROOT, TEMP et TMP au lancement de serveurs stdio distants avec variables d'environnement distantes.
OpenAI Codex + MCP: How to Install MCP Servers in Codex (Step by Step)
Chaîne : Nathan Sebhastian8:48
OpenAI Codex Tutorial #9 - MCP Servers
Chaîne : Net Ninja6:46
How to Add MCP Servers to OpenAI Codex CLI
Chaîne : Snyk9:14
Connect Codex to an MCP server — official documentation
Documentation officielle : developers.openai.com/codex
Chaque commande, chemin de fichier et clé de configuration de cette page est vérifié contre la documentation officielle MCP de Codex ; les vidéos ci-dessus sont les sources visuelles et factuelles, y compris les écrans de consentement OAuth et le menu MCP de l'application de bureau.
Les captures d'écran sont attribuées à leurs créateurs, avec des liens profonds vers les horodatages exacts. Aucune image de visage filmé n'est utilisée.
Ajouter des serveurs MCP à Codex, pas à pas
Partie 1 — Votre premier serveur stdio
- 1
Choisir un serveur dans la documentation MCP officielle
Ouvrez developers.openai.com/codex/mcp — la documentation de Codex elle-même garde la syntaxe de commande à jour, et la CLI comme l'extension IDE partagent cette configuration. La doc liste des serveurs prêts à l'emploi à essayer d'abord : Context7 pour la documentation des bibliothèques en direct, Figma, GitHub et d'autres. Il existe des centaines de serveurs MCP ; pour un premier test, choisissez quelque chose en lecture seule comme Context7.
La page officielle Connect Codex to an MCP server, avec la syntaxe de codex mcp add et un exemple Context7 prêt à copier.Voir à 0:20 - 2
L'installer avec codex mcp add
Copiez l'exemple et lancez-le dans votre terminal : codex mcp add context7 -- npx -y @upstash/context7-mcp. Tout ce qui suit le double tiret est la commande qui lance le processus du serveur. Codex répond "Added global MCP server 'context7'" — global signifiant qu'il est entré dans votre configuration utilisateur et qu'il est disponible dans tous les projets.
Une commande, sans édition de fichier : la CLI confirme l'ajout du serveur à la configuration globale.Voir à 0:45 - 3
Voir ce que la CLI a écrit dans config.toml
codex mcp add n'est qu'un générateur pour ~/.codex/config.toml. Ouvrez le fichier et vous trouverez [mcp_servers.context7] avec command = "npx" et args = ["-y", "@upstash/context7-mcp"]. Les entrées peuvent aussi s'écrire à la main : ajoutez une table env pour les clés d'API, ou réglez startup_timeout_sec (10 par défaut) et tool_timeout_sec (60 par défaut) pour les serveurs lents. L'édition manuelle est justement la voie qu'empruntent les vidéos de Snyk et Net Ninja dans la carte des sources.
- 4
Lancer Codex et vérifier avec /mcp
Démarrez codex dans votre projet et tapez /mcp. Le panneau MCP Tools liste chaque serveur configuré avec son statut, sa commande de lancement exacte et les outils qu'il expose — Context7 montre query_docs et resolve-library-id. Tout élément absent ici signifie que l'entrée a atterri dans le mauvais fichier ou que le serveur n'a pas démarré.
Le panneau /mcp dans la TUI de Codex : context7 est activé et ses deux outils sont listés nommément.Voir à 1:05
Partie 2 — L'utiliser, puis passer au distant
- 5
Formuler un prompt qui utilise vraiment le serveur
Les outils MCP s'invoquent à la demande, demandez donc quelque chose qui en a besoin : « Utilise Context7 pour consulter la documentation actuelle de Tailwind CSS ». Codex résout la bibliothèque, rapatrie la documentation via le serveur MCP et cite ses sources dans la réponse. Voir défiler les appels d'outils, voilà la preuve que le serveur fonctionne de bout en bout.
La réponse de Codex cite les URLs exactes de la documentation Context7 qu'il a rapatriées via le serveur MCP.Voir à 1:30 - 6
Ajouter un serveur distant avec --url
Beaucoup de fournisseurs hébergent aussi leur serveur MCP à distance — sans processus local, sans npx. Enregistrez-en un avec codex mcp add context7 --url https://mcp.context7.com/mcp. Codex détecte automatiquement la prise en charge d'OAuth, affiche "Detected OAuth support. Starting OAuth flow..." et ouvre votre navigateur pour autorisation. Dans config.toml, l'entrée se réduit à url = "https://mcp.context7.com/mcp" sous [mcp_servers.context7].
Le flux distant complet dans un seul terminal : l'ajout --url, la détection OAuth, l'URL d'autorisation et Successfully logged in.Voir à 2:22 - 7
Approuver l'écran de consentement OAuth
Le navigateur demande si Codex peut accéder à votre compte au nom du fournisseur. Relisez les scopes demandés, cliquez Allow, et le terminal confirme "Successfully logged in". Pour les serveurs dépourvus de flux OAuth, authentifiez-vous séparément avec codex mcp login <name> ; les serveurs à jeton prennent plutôt bearer_token_env_var pointant vers une variable d'environnement.
L'écran de consentement de Context7 : relisez les scopes demandés par Codex, puis Allow.Voir à 2:02 - 8
Limiter un serveur à un projet avec .codex/config.toml
Les serveurs qui n'ont de sens que dans un dépôt — comme DBHub, un serveur stdio qui dialogue avec votre base de données — relèvent de la configuration de projet. Créez un dossier .codex dans le dépôt, ajoutez un config.toml avec l'entrée [mcp_servers.dbhub] et passez votre chaîne de connexion par l'argument --dsn (adaptez l'exemple Postgres de la documentation à MySQL ou à votre moteur). Commitez, et vos collègues héritent du même serveur ; le dossier doit être un projet approuvé pour se charger.
Un .codex/config.toml de projet : DBHub tourne en stdio avec le DSN de la base du dépôt dans les args.Voir à 3:30
Partie 3 — Vrais serveurs et pilotage au quotidien
- 9
Interroger votre base de données via les outils MCP
DBHub configuré, interrogez Codex sur la base : « Trouve la base de données Petco et explique les tables », puis « Quel est le produit le mieux vendu ? ». Codex appelle les outils describe_table et execute_sql du serveur, demande la permission avant d'exécuter du SQL et répond avec de vrais chiffres tirés de vos données. C'est le moyen le plus rapide de déboguer des schémas et de valider des données pendant qu'on travaille sur un backend.
Codex a lancé l'outil execute_sql de dbhub et répondu avec le produit le mieux vendu et son chiffre d'affaires.Voir à 4:40 - 10
Connecter GitHub via son serveur MCP distant
Le README de github/github-mcp-server documente la configuration Codex : ajoutez une entrée [mcp_servers.github] avec url = "https://api.githubcopilot.com/mcp/", puis authentifiez-vous soit par OAuth soit en exportant un jeton d'accès personnel en variable d'environnement (créez un PAT fine-grained dans GitHub Settings, Developer settings, en accordant Administration et Contents). Les serveurs distant-d'abord comme celui-ci et le serveur MCP de Figma suivent le même schéma qu'à l'étape 6.
Le guide d'installation du serveur MCP de GitHub : l'entrée pour Codex CLI plus la note d'authentification OAuth/PAT.Voir à 5:22 - 11
Relancer et mettre les outils au travail
Redémarrez codex et regardez le bandeau : "Starting servers (0/3): context7, dbhub, github". Désormais, une seule instruction comme « Fork le dépôt openai/codex sur mon compte » suffit — Codex choisit l'outil fork de GitHub, demande l'approbation et exécute. Aucun réglage par tâche : les outils font simplement partie de chaque session à partir de maintenant.
- 12
Gérer les serveurs avec codex mcp list et l'application de bureau
codex mcp list affiche chaque serveur configuré depuis le shell ; en supprimer un revient à effacer son bloc de config.toml puis relancer la commande pour confirmer. L'application de bureau et l'extension IDE lisent le même ~/.codex/config.toml, si bien que les serveurs installés ici apparaissent dans Settings, MCP servers de l'application de bureau avec interrupteurs on/off.
Les réglages MCP servers de l'application de bureau Codex : context7, dbhub et github avec interrupteurs, plus des serveurs recommandés.Voir à 7:30
Serveurs MCP stdio locaux vs distants dans Codex
Les deux vivent dans les mêmes tables [mcp_servers.*] et apparaissent dans le même panneau /mcp — la différence tient à l'endroit où tourne le serveur et à la façon dont il s'authentifie. Choisissez par serveur, pas par projet.
- 1stdio local : Codex lance lui-même un processus avec command et args — typiquement npx ou un binaire. Il tourne sur votre machine et peut donc joindre des services localhost comme une base de développement (c'est ainsi que DBHub a interrogé MySQL dans le pas à pas), mais vous fournissez le runtime et les mises à jour.
- 2Distant : Codex parle à une url hébergée en HTTP streamable. Aucun processus à maintenir en vie et une authentification centralisée — OAuth par défaut, ou bearer_token_env_var et http_headers pour les montages à jeton. L'exemple de la documentation elle-même est [mcp_servers.figma] avec url = "https://mcp.figma.com/mcp".
- 3stdio exécuté à distance : un entre-deux expérimental. Poser experimental_environment = "remote" sur une entrée stdio déplace son exécution vers un exécuteur distant, env_vars décidant quelles variables voyagent — y compris les entrées marquées source = "remote". C'est la voie durcie par Codex 0.160.1.
- 4Portée : codex mcp add écrit toujours dans le ~/.codex/config.toml global ; les serveurs propres à un projet vont dans le .codex/config.toml du dépôt (projets approuvés uniquement). Global pour les outils voulus partout, projet pour tout ce qui porte des identifiants propres à l'environnement.
- 5Contrôles communs aux deux : startup_timeout_sec (10 par défaut) et tool_timeout_sec (60 par défaut) pour les serveurs lents, enabled/disabled_tools pour autoriser en liste blanche ce que Codex peut appeler, et required = true si un serveur doit obligatoirement démarrer, faute de quoi Codex doit refuser de se lancer.
Une valeur par défaut pratique : les serveurs de documentation en lecture seule comme Context7 peuvent être globaux ; tout ce qui touche aux identifiants ou aux données — DBHub, GitHub avec un PAT — relève de la configuration de projet, où on peut le relire et le révoquer avec le dépôt.
Configuré mais inopérant : les suspects habituels
La plupart des échecs MCP dans Codex sont des problèmes de portée, de délai ou d'authentification — dans cet ordre. Parcourez cette liste avant de toucher au serveur.
- 1Serveur absent de /mcp : vérifiez quel fichier vous avez modifié. Les entrées globales vivent dans ~/.codex/config.toml ; les entrées de projet dans .codex/config.toml, et pour les seuls projets approuvés. Lancer codex mcp list depuis le shell montre ce que Codex voit réellement.
- 2Le serveur dépasse le délai au démarrage : le startup_timeout_sec par défaut est de 10 secondes, et un téléchargement npx à froid d'un gros paquet peut largement dépasser. Préinstallez le paquet ou augmentez le startup_timeout_sec de l'entrée.
- 3Les appels d'outils échouent en 401/403 : l'identifiant manque ou a expiré. Lancez codex mcp login <name> pour les serveurs OAuth, ou posez bearer_token_env_var et exportez la variable. Une fois corrigé, /mcp devrait de nouveau montrer le serveur comme activé.
- 4Un serveur stdio distant plante avec d'étranges erreurs Windows : avant 0.160.1, lancer un serveur MCP stdio distant avec des variables d'environnement distantes explicitement configurées pouvait perdre SYSTEMROOT, TEMP et TMP, cassant l'environnement de démarrage de l'exécuteur Windows. Mettez à jour vers 0.160.1 ou plus.
- 5Le serveur démarre mais les réponses sont fausses ou vides : beaucoup de serveurs hébergés réclament leur propre clé d'API même par-dessus OAuth — Context7, par exemple, veut une clé d'API passée via env. Consultez la documentation du fournisseur pour le nom exact de la variable et ajoutez-la à la table env de l'entrée.
Deux leviers utiles pendant le débogage : posez required = true sur un serveur dont vous dépendez, pour que Codex ne démarre jamais silencieusement sans lui, et enabled = false pour couper l'un sans effacer sa configuration.