Connecter des outils via le protocole Model Context Protocol (MCP) : donner des interfaces à Codex

📚 Navigation dans la série : Le chapitre précédent [19 · Système de mémoire (Memories et Chronicle)] a présenté le fonctionnement de la mémoire Memories pour conserver le contexte d'une session à l'autre. Ce chapitre aborde l'intégration d'outils externes : par défaut, Codex est limité à vos fichiers locaux et à la console, sans accès à vos bases de données, à Figma ou à vos documentations tierces. Le protocole MCP fournit une interface d'accès universelle à ces outils et sources de données. Le chapitre suivant [21 · Sous-agents (Subagents) : paralléliser le travail avec des agents secondaires] détaillera la délégation de tâches à des sous-agents dotés de contextes d'exécution isolés.

Laissez-moi vous raconter une erreur classique commise lors de ma première configuration MCP.

Habitué à Claude Code, j'avais le réflexe d'ajouter un serveur avec la commande claude mcp add --scope user xxx, l'option --scope définissant le périmètre d'action du serveur. En passant sur Codex, j'ai saisi une commande similaire avec l'option --scope. Le terminal a immédiatement rejeté l'argument. J'ai cru d'abord à une version obsolète de mon CLI, que j'ai mis à jour sans succès ; j'ai modifié la syntaxe plusieurs fois, mais la commande a été systématiquement rejetée.

Après vingt minutes de recherche dans la documentation officielle, j'ai compris mon erreur : Codex ne gère pas l'argument --scope. La configuration MCP est centralisée dans le fichier config.toml, et le périmètre d'action dépend de l'emplacement de ce fichier : le placer dans ~/.codex/config.toml applique le serveur à tous les projets, tandis que le placer dans le .codex/config.toml local d'un projet restreint l'usage à ce projet. J'appliquant la logique de Claude Code à Codex, ce qui bloquait l'exécuton.

Ce retour d'expérience vise à vous éviter de perdre du temps : le protocole MCP reste le même, mais sa configuration sous Codex s'appuie sur une logique différente de celle de Claude Code.

À la fin de ce chapitre, vous aurez en main :

• Le rôle du protocole MCP et comment il étend les capacités d'accès de Codex.
• La différence entre les deux types de serveurs (STDIO en local vs HTTP Streamable dans le cloud) résumée sous forme de tableau.
• Les deux méthodes de configuration : la commande codex mcp add et l'édition directe de config.toml, ainsi que l'effet de l'emplacement du fichier sur la portée des droits.
• La configuration des accès de serveurs via les clés enabled, disabled_tools et default_tools_approval_mode.
• Un exercice pratique guidé pour connecter le serveur de documentation Context7 et valider son fonctionnement.

---

01 Le rôle du protocole MCP : Ouvrir Codex sur l'extérieur

En résumé : Codex est par défaut limité aux actions locales de modification de fichiers et d'exécution de commandes. Le protocole MCP lui sert d'interface pour accéder à des outils et à des données externes.

Jusqu'ici, les actions de Codex présentées se cantonnaient à votre répertoire de projet (lire et modifier des fichiers de code ou lancer des scripts de test). L'assistant n'a pas accès à vos maquettes Figma, ne peut pas vérifier les versions de documentations d'API sur internet ou interagir avec un navigateur. Pour traiter ces données, vous deviez copier les textes ou prendre des captures d'écran pour les lui soumettre.

Analogie : L'adaptateur multiport pour smartphone. Les téléphones modernes ne possèdent souvent qu'un unique port USB-C, ce qui empêche d'y connecter une clé USB, un câble HDMI ou une carte SD de appareil photo. La solution consiste à utiliser un adaptateur multiport : branché sur l'unique port du téléphone, il met à disposition des prises USB, HDMI et un lecteur de cartes. Le protocole MCP (Model Context Protocol, un standard ouvert définissant l'accès des IA aux outils externes) joue le rôle de cet adaptateur pour Codex : une fois connecté, l'IA accède à une multitude de ressources externes.

La documentation officielle définit ainsi son rôle :

Le protocole Model Context Protocol (MCP) connecte le modèle à des outils et à du contexte. Utilisez-le pour associer Codex à des documentations tierces ou lui permettre d'interagir avec des outils de développement comme votre navigateur ou Figma.

Le terme clé est standard. Le protocole MCP est une spécification ouverte et partagée. Un connecteur développé pour un outil peut être réutilisé par un autre : le serveur MCP conçu pour vos documentations sera utilisable par Codex, mais également par Claude Code ou Cursor. Codex supporte ce standard, avec sa propre logique de configuration (détaillée à la section 03).

Un détail d'intégration propre à Codex est à noter : Codex analyse la clé instructions renvoyée par le serveur lors de sa connexion et l'intègre comme consigne de comportement pour l'usage des outils associés. Un serveur bien conçu transmet ainsi ses propres règles de fonctionnement ou limites de requêtes pour guider l'assistant.

Le besoin d'un serveur MCP se fait sentir dès lors que vous vous retrouvez à copier des données d'un outil externe pour les soumettre manuellement à Codex. Exemples d'usage :

• « Applique les modifications de style sur cette page d'après la maquette Figma du projet » : l'assistant consulte la maquette directement sans exiger de captures d'écran manuelles.
• « Mets à jour ce code en utilisant la dernière version de cette bibliothèque logicielle » : Codex interroge la documentation d'API à jour, évitant de s'appuyer sur des connaissances obsolètes.
• « Effectue une capture d'écran du rendu de cette page sur écran mobile » : l'assistant pilote directement le navigateur pour effectuer le test.

💡 En résumé : Codex est par défaut limité au système de fichiers local et à la console. Le protocole MCP sert d'adaptateur pour l'ouvrir sur vos maquettes, documentations en ligne et outils de navigation. Il intègre de plus les consignes (instructions) renvoyées par le serveur.

Schéma : Codex interagit localement avec les fichiers et commandes. L'interface MCP agit comme un concentrateur USB pour y connecter des serveurs externes comme GitHub, des bases de données ou Figma.

---

02 Les deux types de serveurs : Local ou distant

Les serveurs MCP se répartissent en deux catégories. Le choix dépend de l'emplacement d'exécution du serveur : s'exécute-t-il sur votre machine locale ou sur un serveur cloud externe ?

Analogie : Les appareils électriques de votre maison, alimentés par prise murale ou connectés en Wi-Fi. Une lampe ou un ventilateur sont des équipements locaux branchés sur vos prises et présents physiquement dans la pièce. Une enceinte connectée accède à des services météo ou de musique hébergés sur des serveurs distants en Wi-Fi. Les serveurs MCP suivent cette logique : les serveurs locaux s'exécutent sur votre machine (processus local), les serveurs distants sont accédés via une adresse réseau.

La documentation officielle détaille ces deux types de serveurs :

Type de serveur	Emplacement d'exécution	Initialisation	Cas d'usage type
STDIO (Processus local)	Votre machine physique	Lancement par une commande locale (ex: npx ...)	Accès aux fichiers locaux, pilotage du navigateur local, connexion aux outils installés
Streamable HTTP (Distant)	Serveur cloud externe	Connexion via une URL réseau	Services cloud, documentations partagées, maquettes Figma (requiert une authentification)

Détails importants de mise en œuvre :

La commande de démarrage des serveurs STDIO. Ces serveurs s'exécutent sous la forme de processus lancés en arrière-plan par Codex. Vous devez fournir la commande d'initialisation (par exemple : npx -y @upstash/context7-mcp). Leur exécution suppose que l'environnement requis soit présent sur votre machine (l'usage de npx exige par exemple l'installation préalable de Node.js). Ces serveurs acceptent la déclaration de variables d'environnement (option --env ou clé env) pour y associer des jetons d'accès.

L'authentification des serveurs HTTP. La documentation officielle liste deux méthodes d'authentification pour les serveurs HTTP distants :

• Jeton Bearer (Bearer token) : Déclarer le nom de la variable d'environnement contenant le jeton dans la configuration.
• Authentification OAuth : Exécuter la commande codex mcp login <nom_serveur> pour associer les droits d'accès.

Les services cloud (comme Figma ou des documentations distantes) se connectent en fournissant simplement leur URL et leur jeton, sans installation de processus sur votre machine.

Notez une différence avec d'autres clients : alors que certains outils supportent encore d'anciennes liaisons de type SSE (Server-Sent Events), Codex se concentre sur les liaisons STDIO et Streamable HTTP. Ce sont les deux seuls formats à configurer.

Visualisons les voies d'accès de Codex vers l'extérieur :

Ce schéma montre le fonctionnement : les capacités par défaut de Codex se limitent aux fichiers et commandes locales (à gauche). Le protocole MCP établit une connexion via STDIO (lancement d'un processus local sur la machine) ou HTTP Streamable (requête réseau vers une URL sécurisée) pour intégrer les outils externes (à droite).

💡 En résumé : Utilisez les serveurs STDIO pour interagir avec votre machine locale (commande de lancement requise, dépendante de votre environnement local) et les serveurs Streamable HTTP pour vous connecter à des services cloud (connexion par URL avec authentification par jeton Bearer ou OAuth via la commande codex mcp login).

---

03 Configuration d'un serveur : Commande CLI ou édition du fichier config.toml

Comme vu précedemment, les serveurs MCP se configurent au sein de votre fichier config.toml. La documentation le précise :

Codex enregistre la configuration MCP dans le fichier config.toml global ou local. Par défaut, la configuration globale se situe dans ~/.codex/config.toml ; vous pouvez également limiter un serveur à un projet en déclarant sa configuration dans le fichier .codex/config.toml local (pour les projets marqués comme de confiance).

L'emplacement du fichier définit le périmètre d'action du serveur (remplaçant l'argument --scope de Claude Code) :

Fichier de configuration	Portée des serveurs	Usage typique
Global : ~/.codex/config.toml	Actif sur l'ensemble de vos projets	Serveur de recherche globale ou de documentation courante
Local : <projet>/.codex/config.toml	Actif sur ce projet uniquement (si marqué comme de confiance)	Outil de base de données spécifique ou connecteur propre au projet

De plus, ces paramètres de configuration sont partagés entre la console (CLI) et les extensions d'éditeur (IDE). Un serveur configuré dans votre terminal sera accessible lors de vos sessions sous VS Code ou JetBrains.

Rappel de sécurité : Les configurations de projets locaux ne sont lues que si le dépôt a été marqué comme fiable lors du premier accès. Cette sécurité empêche qu'un dépôt externe cloné ne lance des processus ou des serveurs locaux à votre insu.

Méthode 1 : Via la commande de console codex mcp (recommandé)

Pour ajouter un serveur STDIO, utilisez la commande codex mcp add. L'argument -- sépare les options de configuration de la commande de démarrage du serveur :

codex mcp add <nom_serveur> --env CLE_API=valeur -- <commande_demarrage_stdio>

Exemple pour connecter le serveur de documentation Context7 (un service gratuit pour charger des documentations d'API) :

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

La partie npx -y @upstash/context7-mcp désigne la commande d'initialisation, le paramètre -y forçant l'installation automatique par npm. La commande codex mcp --help liste l'ensemble des commandes d'administration. Pour les serveurs HTTP nécessitant une authentification OAuth, utilisez la commande codex mcp login <nom_serveur> après l'ajout.

Pendant une session active (CLI), vous pouvez afficher les serveurs connectés avec la commande slash :

/mcp

Méthode 2 : Édition manuelle du fichier config.toml

Pour configurer finement un serveur (limiter des outils ou ajuster les délais d'attente), vous pouvez éditer directement le fichier config.toml sous le bloc [mcp_servers.<nom_serveur>].

Exemple pour un serveur STDIO (équivalent à la commande de Context7 ci-dessus) :

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

Les clés command and args définissent le processus et ses arguments. Vous pouvez également configurer les variables d'environnement (env), le répertoire de travail (cwd) ou les variables autorisées à la transmission (env_vars).

Exemple pour un serveur Streamable HTTP (maquette Figma) :

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"

Le paramètre url indique l'adresse du serveur, et bearer_token_env_var désigne le nom de la variable d'environnement contenant le jeton Bearer. Évitez d'écrire les clés API en clair dans le fichier de configuration ; référencez une variable d'environnement.

Note de structure : Ce bloc mcp_servers s'intègre au fichier config.toml principal détaillé au chapitre 18. L'outil codex mcp add écrit ces lignes automatiquement, mais vous pouvez les éditer ou les ajouter manuellement.

💡 En résumé : Codex centralise ses configurations MCP dans config.toml. La portée dépend de la localisation du fichier (global sous ~/.codex/ ou local au projet sous .codex/). L'ajout s'effectue via codex mcp add ou par édition manuelle du bloc [mcp_servers.<nom>].

---

04 Sécuriser les accès : Limiter les outils et ajuster les autorisations

Une fois le serveur connecté, vous devez pouvoir en restreindre les accès. Codex propose des paramètres dans config.toml pour encadrer le fonctionnement de chaque serveur : limiter les outils disponibles, ajuster les temps d'attente ou forcer la validation des commandes.

Analogie : Définir les droits d'accès sur le badge d'un collaborateur. Vous n'accordez pas un accès universel à tous les locaux. Vous déterminez les bureaux accessibles, interdisez l'accès aux salles serveurs, et exigez une validation téléphonique pour les locaux sensibles. La configuration des droits MCP suit cette logique : pour un serveur donné, vous déterminez les outils autorisés, ceux à bloquer et ceux nécessitant une invite de confirmation.

Voici la liste des paramètres d'encadrement applicables dans config.toml :

Option de configuration	Rôle	Valeurs supportées
enabled	Désactive temporairement le serveur sans supprimer sa configuration	true (par défaut) / false
enabled_tools	Liste blanche d'outils autorisés (tous les autres sont bloqués)	Tableau de chaînes
disabled_tools	Liste noire d'outils exclus (s'applique après la liste blanche)	Tableau de chaînes
default_tools_approval_mode	Mode de validation par défaut des outils du serveur	auto / prompt / approve
startup_timeout_sec	Temps maximum alloué pour le démarrage du serveur (secondes)	10 (par défaut)
tool_timeout_sec	Temps maximum alloué pour l'exécution d'un outil (secondes)	60 (par défaut)

Règles importantes à retenir :

Priorité de filtrage des outils. Le paramètre disabled_tools s'applique après l'évaluation de enabled_tools. Vous pouvez ainsi déclarer un ensemble d'outils autorisés, puis en exclure un spécifique. Exemple de la documentation : si enabled_tools = ["open", "screenshot"] et disabled_tools = ["screenshot"], seul l'outil open sera accessible.

Choix des modes d'approbation (default_tools_approval_mode) :

• auto : Laisse Codex décider de la validation d'après ses règles par défaut.
• prompt : Affiche systématiquement une invite de confirmation avant chaque appel d'outil.
• approve : Autorise l'exécution directe des outils sans invite de confirmation.

Vous pouvez également surcharger ce comportement pour un outil spécifique avec la syntaxe tools.<nom_outil>.approval_mode (par exemple pour autoriser la lecture directe mais exiger une confirmation sur l'outil de modification).

Délais d'attente (timeout). Par défaut, un serveur dispose de 10 secondes pour démarrer et de 60 secondes pour exécuter un outil. Si vous utilisez un serveur local lourd dont le démarrage à froid prend plus de temps, la connexion échouera. Vous devez alors ajuster startup_timeout_sec :

[mcp_servers.serveur_lent]
command = "python"
args = ["-m", "serveur_lent"]
startup_timeout_sec = 30   # Augmente le délai d'initialisation du serveur
tool_timeout_sec = 120     # Augmente le temps d'exécution accordé aux outils

Exemple de configuration d'un serveur HTTP sécurisé avec restrictions :

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"]          # Filtre final : bloque screenshot, maintient open
default_tools_approval_mode = "prompt"   # Demande confirmation pour ce serveur
startup_timeout_sec = 20
enabled = true

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"                # Surcharge locale : autorise l'outil open sans invite

💡 En résumé : Le fichier config.toml permet de restreindre l'usage des serveurs connectés. Utilisez enabled comme interrupteur, filtrez avec enabled_tools / disabled_tools, gérez les invites avec default_tools_approval_mode (auto/prompt/approve) et ajustez les délais d'attente si nécessaire.

---

05 Risques associés aux serveurs tiers

Cette section aborde les enjeux de sécurité liés au protocole MCP (faisant écho aux principes de sécurité présentés au chapitre 16).

Règle de sécurité essentielle : les serveurs MCP tiers exécutent du code ou des requêtes réseau externes, et OpenAI n'effectue pas d'audit de sécurité sur ces composants. Connecter un serveur STDIO local revient à autoriser l'exécusion d'un programme externe sur votre machine. Connecter un serveur HTTP de récupération de données l'ouvre sur des flux réseau externes. Vous devez évaluer la fiabilité de ces sources.

Analogie : Installer une bibliothèque logicielle tierce dans votre code de production. Vous n'utilisez pas un package npm inconnu et sans historique de maintenance. Vous vérifiez son origine, son audience et sa documentation. Les serveurs MCP doivent faire l'objet de la même attention : validez la réputation du serveur avant de le connecter.

Les serveurs chargés de récupérer du contenu sur internet (comme des pages web, des tickets de support ou des documentations d'API) constituent des vecteurs d'injection de requêtes (prompt injection). Si un document externe lu par le serveur contient des consignes cachées destinées à l'IA, Codex pourrait les exécuter. C'est pourquoi la configuration de droits présentée à la section 04 est indispensable : utiliser le mode prompt ou restreindre les outils dangereux limite la surface d'exposition.

Recommandations de sécurité pour la connexion de serveurs :

Source du serveur	Décision de connexion
Documentations officielles recommandées (OpenAI Docs, Context7, Figma, Playwright)	✅ Utilisable en confiance
Connecteurs éditeurs reconnus (GitHub, Sentry officiel)	✅ Utilisable en confiance
Dépôts tiers ou serveurs personnels sans historique de commits	⚠️ Analyser le code source avant connexion
Serveurs configurés sur default_tools_approval_mode = "approve" (exécution directe)	⚠️ Limiter cette confiance aux serveurs officiels vérifiés
Serveurs MCP disposant d'accès en écriture sur vos données de production	❌ Privilégier des accès en lecture seule

La règle du privilège minimal reste d'actualité : limitez les droits d'écriture et configurez des validations par invite (prompt) pour les actions sensibles. Bien que Codex applique des limites de bac à sable sur ses processus, un serveur MCP configuré avec des droits d'exécution directe de commandes peut contourner ces barrières si vous l'autorisez sans contrôle.

💡 En résumé : Les serveurs MCP tiers constituent des extensions de code non auditées par l'éditeur. Privilégiez les serveurs reconnus, limitez les droits d'écriture, et configurez le mode d'approbation sur prompt pour garder le contrôle des actions sensibles.

---

06 En pratique : Connecter et tester le serveur de documentation Context7

Voici un exercice pratique pour connecter le serveur gratuit Context7, vérifier sa présence et tester une interrogation de documentation d'API.

Note technique : L'exercice s'appuie sur npx et exige que Node.js soit installé sur votre machine (vérifiez la présence avec la commande node -v en console). Le serveur devant interroger des API de documentation sur internet, une connexion active est requise.

Étape 1 : Ajouter le serveur Context7

Exécutez dans le terminal de votre système (hors session Codex active) :

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

Comportement attendu : Le CLI confirme la prise en compte du serveur. La configuration correspondante est automatiquement écrite dans votre fichier global ~/.codex/config.toml sous le bloc [mcp_servers.context7].

Étape 2 : Vérifier la connexion du serveur

Lancez une session Codex dans votre terminal :

codex

Une fois l'interface ouverte, interrogez la liste des serveurs MCP connectés :

/mcp

Comportement attendu : Le nom du serveur context7 doit apparaître dans la liste des serveurs actifs, confirmant la bonne lecture du fichier de configuration.

Étape 3 : Interroger la documentation d'un framework

Saisissez la consigne suivante dans le chat de Codex, en ciblant explicitement la recherche sur le serveur :

Utilise le serveur context7 pour rechercher la structure recommandée de configuration de routes avec React Router dans sa dernière version stable.

Comportement attendu : Codex détecte l'usage requis du serveur MCP. Une invite de confirmation s'affiche au premier appel d'outil pour valider l'action. Validez la demande. Codex interroge le serveur de documentation, extrait les structures de code à jour et vous les présente dans le chat. L'intégration fonctionne.

Étape 4 : Retrait du serveur (optionnel)

Si vous souhaitez désactiver ou retirer ce serveur de test, vous pouvez :

• Consulter les commandes de retrait en console avec codex mcp --help et exécuter la commande de suppression correspondante.
• Ou éditer manuellement le fichier ~/.codex/config.toml pour supprimer la section [mcp_servers.context7] ou lui attribuer le paramètre enabled = false.

Cet exercice valide le processus d'intégration d'un serveur MCP. Le raccordement d'autres serveurs (comme Figma ou des connecteurs de bases de données) repose sur la même logique.

💡 En résumé : L'exercice consiste à ajouter le serveur en console, valider son statut avec /mcp en session, exécuter une requête de documentation et nettoyer la configuration si souhaité.

---

07 Résumé

Ce chapitre a détaillé le raccordement d'outils et de services externes à Codex via le protocole ouvert MCP.

Voici les points clés à retenir :

Aspect	Règle de fonctionnement
Utilité	Ouvre Codex sur des données externes (maquettes, bases de données, API distantes).
Types de serveurs	STDIO pour les processus locaux, HTTP Streamable pour les URLs distantes.
Portée des droits	Définie par l'emplacement du fichier config.toml (global dans ~/.codex/ ou local dans le projet).
Ajout	Commande codex mcp add (avec l'argument -- avant la commande STDIO) ou édition de config.toml.
Sécurisation	Limitation des outils (enabled_tools/disabled_tools) et choix de l'approbation (prompt requis par sécurité).
Vigilance	Les serveurs tiers ne sont pas audités par l'éditeur et peuvent être exposés aux injections de requêtes.

Vous êtes désormais en mesure de comprendre les capacités d'intégration du protocole MCP, d'identifier le type de serveur adapté à votre outil, de configurer la portée globale ou locale des connecteurs, d'utiliser les commandes d'administration MCP, de restreindre les privilèges des outils connectés dans le fichier config.toml, et d'appliquer les règles de sécurité indispensables lors de la connexion de services tiers.

---

Le chapitre suivant 21 · Sous-agents (Subagents) : paralléliser le travail avec des agents secondaires présente la délégation de tâches : comment permettre à Codex d'ouvrir d'autres sessions en arrière-plan pour traiter des sous-tâches en parallèle, comment configurer ces sous-agents et comment gérer leur communication ? Nous verrons comment orchestrer un travail d'équipe automatisé.

---

Lectures recommandées

• Workflows de développement : exemples pratiques
• Sélection des modèles : adapter la puissance de calcul à la tâche
• Fichier de consignes projet AGENTS.md