Model Context Protocol

L’application de bureau ChatGPT, Codex CLI et l’extension IDE prennent en charge les MCP servers et partagent la configuration MCP pour un même hôte Codex.

Les fonctionnalités de serveur prises en charge ci-dessous s’appliquent aux MCP servers configurés sur un hôte Codex. Les outils de plugins hébergés peuvent proposer des fonctionnalités différentes.

Fonctionnalités MCP prises en charge

• Serveurs STDIO : serveurs exécutés comme processus local (démarrés par une commande).
  • Variables d’environnement
• Serveurs Streamable HTTP : serveurs auxquels vous accédez à une adresse.
  • Authentification par jeton Bearer
  • Authentification OAuth, notamment Client ID Metadata Documents (CIMD) et Dynamic Client Registration (DCR)
  • Authentification par session ChatGPT pour les serveurs propriétaires de confiance
• Instructions du serveur : Codex lit le champ MCP instructions renvoyé lors de l’initialisation et l’utilise comme consignes applicables à l’ensemble du serveur, parallèlement aux outils de celui-ci.

Si vous développez ou gérez un MCP server pour Codex, utilisez instructions pour les workflows inter-outils, les contraintes et les limites de débit qui s’appliquent à l’ensemble du serveur. Veillez à ce que les 512 premiers caractères se suffisent à eux-mêmes afin que les consignes les plus importantes soient disponibles lorsque Codex décide comment utiliser le serveur.

Connecter Codex à un MCP server

Codex stocke la configuration MCP dans config.toml avec les autres paramètres de configuration de Codex. Par défaut, il s’agit de ~/.codex/config.toml, mais vous pouvez également limiter les MCP servers à un projet avec .codex/config.toml (projets approuvés uniquement).

L’application de bureau ChatGPT, Codex CLI et l’extension IDE partagent cette configuration. Une fois vos MCP servers configurés, vous pouvez passer d’un de ces clients à l’autre sans recommencer la configuration.

Configurer dans l’application de bureau ChatGPT

1. Ouvrez Paramètres, puis sélectionnez MCP servers.
2. Sélectionnez Ajouter un serveur.
3. Saisissez un nom, choisissez STDIO ou Streamable HTTP, puis indiquez la commande ou l’URL du serveur.
4. Enregistrez le serveur, puis sélectionnez Redémarrer.

La liste des serveurs indique ceux qui sont activés et ceux qui nécessitent OAuth. Sélectionnez S’authentifier lorsqu’un serveur OAuth nécessite une connexion. Dans la zone de saisie, tapez /mcp pour afficher les serveurs connectés.

Utiliser des outils reposant sur MCP dans ChatGPT web

Poursuivre sur un autre appareil une conversation utilisant l’accès à l’ordinateur local avec Work Cloud n’installe aucun plugin et n’accorde aucun accès aux comptes connectés.

Dans l’accès à l’ordinateur local avec Work Cloud, l’exigence TOML d’entreprise mcp_servers définie dans Agent Security s’applique aux exécuteurs locaux. Les conteneurs cloud conservent les politiques de Work Cloud. Les MCP servers et les transports locaux peuvent ne pas être disponibles dans le cloud ; vérifiez séparément la connectivité et l’authentification.

Pour les hooks d’entreprise dans l’accès à l’ordinateur local avec Work Cloud :

• Hooks d’entreprise. Lorsque cette option est activée pour votre espace de travail, l’accès à l’ordinateur local avec Work Cloud prend en charge les hooks MCP définis par les administrateurs, qui s’exécutent sur le coordinateur cloud (orchestrateur) pour les événements de cycle de vie et d’outils pris en charge. Les hooks de commande et les hooks issus de la configuration locale ou de plugins ne sont pas pris en charge avec l’orchestration cloud, même lorsque les outils s’exécutent localement.
• Audit. Avant de vous appuyer sur ces hooks, testez la connexion de rappel, confirmez les événements qu’elle reçoit et vérifiez l’incidence des échecs sur la tâche. Les hooks MCP ne fournissent pas de piste d’audit complète via la Compliance API.
• Limites : Les hooks de commande et les hooks issus de la configuration locale ou de plugins ne sont pas pris en charge avec l’orchestration cloud, même lorsque les outils s’exécutent localement. Les utilisateurs grand public ne bénéficient pas de la prise en charge des hooks dans cette fonctionnalité. Lorsque l’orchestration et l’exécution sont toutes deux locales, les hooks existants pris en charge continuent de fonctionner dans les fils Work et Codex entièrement locaux. Les administrateurs peuvent toujours configurer les hooks gérés pris en charge dans Agent Security pour ces workflows.

Consultez les pages Hooks et Référence de configuration pour connaître le périmètre de prise en charge.

Dans une conversation ChatGPT Work hébergée, installez un plugin pour utiliser ses connecteurs intégrés et ses outils MCP distants. Après l’installation, Chat et Work peuvent utiliser ces outils. Les administrateurs de l’espace de travail peuvent contrôler les plugins et outils disponibles.

ChatGPT web ne lit pas les fichiers de configuration Codex locaux et n’affiche pas le menu de commandes Codex local. Ouvrez l’onglet Plugins pour parcourir et gérer les outils disponibles.

Configurer avec la CLI

Ajouter un MCP server

codex mcp add <server-name> --env VAR1=VALUE1 --env VAR2=VALUE2 -- <stdio server-command>

Par exemple, pour ajouter Context7 (un MCP server gratuit pour la documentation destinée aux développeurs), vous pouvez exécuter la commande suivante :

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

Autres commandes CLI

Exécutez codex mcp list pour afficher les serveurs configurés. Pour afficher toutes les commandes MCP disponibles, exécutez codex mcp --help. Pour un serveur prenant en charge OAuth, exécutez codex mcp login <server-name>.

Interface utilisateur du terminal (TUI)

Dans la TUI codex, utilisez /mcp pour afficher vos MCP servers actifs.

Configurer dans l’extension IDE

1. Ouvrez le menu en forme d’engrenage, puis sélectionnez MCP servers.
2. Sélectionnez Ajouter un serveur.
3. Saisissez un nom, choisissez STDIO ou Streamable HTTP, puis indiquez la commande ou l’URL du serveur.
4. Enregistrez le serveur, puis sélectionnez Redémarrer l’extension.

La liste des MCP servers indique ceux qui sont activés et ceux qui nécessitent OAuth. Sélectionnez S’authentifier lorsqu’un serveur OAuth nécessite une connexion.

Configurer avec config.toml

Pour un contrôle plus précis, modifiez ~/.codex/config.toml ou un fichier limité au projet .codex/config.toml. Consultez la référence de configuration pour obtenir une liste consultable de toutes les options MCP prises en charge.

Configurez chaque MCP server à l’aide d’une table [mcp_servers.<server-name>] dans le fichier de configuration.

Serveurs STDIO

• command (obligatoire) : commande qui démarre le serveur.
• args (facultatif) : arguments à transmettre au serveur.
• env (facultatif) : variables d’environnement à définir pour le serveur.
• env_vars (facultatif) : variables d’environnement à autoriser et à transmettre.
• cwd (facultatif) : répertoire de travail depuis lequel démarrer le serveur.
• experimental_environment (facultatif) : définissez cette option sur remote pour démarrer le serveur stdio via un environnement d’exécution distant lorsqu’un tel environnement est disponible.

env_vars peut contenir de simples noms de variables ou des objets dotés d’une source :

env_vars = ["LOCAL_TOKEN", { name = "REMOTE_TOKEN", source = "remote" }]

Les entrées sous forme de chaîne et source = "local" sont lues depuis l’environnement local de Codex. source = "remote" est lu depuis l’environnement d’exécution distant et nécessite un accès MCP stdio distant.

Serveurs Streamable HTTP

• url (obligatoire) : adresse du serveur.
• auth (facultatif) : authentification à essayer après les jetons Bearer et les en-têtes d’autorisation configurés. Utilisez oauth (valeur par défaut) pour les identifiants OAuth MCP enregistrés. Utilisez chatgpt pour employer la session ChatGPT actuelle avec l’origine ChatGPT officielle approuvée, en utilisant OAuth enregistré comme solution de secours.
• bearer_token_env_var (facultatif) : nom de la variable d’environnement contenant le jeton Bearer à envoyer dans Authorization.
• http_headers (facultatif) : table de correspondance entre les noms d’en-têtes et des valeurs statiques.
• env_http_headers (facultatif) : table de correspondance entre les noms d’en-têtes et les noms de variables d’environnement (les valeurs sont extraites de l’environnement).
• http_headers_helper (facultatif) : commande locale qui affiche un objet JSON composé de noms d’en-têtes et de valeurs de type chaîne, comme {"X-Auth": "temporary-token"}. Pris en charge pour les connexions MCP HTTP établies depuis l’environnement local, mais pas pour les serveurs stdio ni pour les connexions établies via un environnement d’exécution distant.

Codex met en cache les en-têtes fournis par l’utilitaire pour la connexion. Lorsqu’une requête POST vers la même origine renvoie 401 ou 403, il actualise les en-têtes une fois et ne réessaie que si l’utilitaire renvoie des valeurs modifiées. Les jetons Bearer explicites et les identifiants OAuth ont priorité sur un en-tête Authorization fourni par l’utilitaire. Une réponse OAuth 403 signalant des autorisations insuffisantes ne déclenche pas l’actualisation par l’utilitaire.

Si aucune source d’identifiants n’est trouvée, Codex peut se connecter au serveur sans authentification. Exécutez codex mcp login <server-name> séparément pour lancer une connexion OAuth MCP.

Autres options de configuration

• startup_timeout_sec (facultatif) : délai d’expiration (en secondes) pour le démarrage du serveur. Valeur par défaut : 10.
• tool_timeout_sec (facultatif) : délai d’expiration (en secondes) dont dispose le serveur pour exécuter un outil. Valeur par défaut : 60.
• enabled (facultatif) : définissez cette option sur false pour désactiver un serveur sans le supprimer.
• required (facultatif) : définissez cette option sur true pour faire échouer le démarrage si ce serveur activé ne peut pas s’initialiser.
• enabled_tools (facultatif) : liste d’autorisation des outils.
• disabled_tools (facultatif) : liste de refus des outils (appliquée après enabled_tools).
• default_tools_approval_mode (facultatif) : comportement d’approbation par défaut pour les outils de ce serveur. Les valeurs prises en charge sont auto, prompt, writes et approve. Le mode writes demande une confirmation pour les outils qui ne sont pas marqués en lecture seule.
• tools.<tool>.approval_mode (facultatif) : remplacement du comportement d’approbation pour chaque outil.
• tools.<tool>.output_token_limit (facultatif) : budget de jetons positif pour la sortie d’un outil, avant la marge de sérialisation standard de 20 %. Remplace le budget de troncature de sortie par défaut du modèle pour cet outil.

Le paramètre de premier niveau mcp_optional_startup_grace_ms détermine combien de temps Codex attend les MCP servers facultatifs lors de la création du catalogue initial d’outils. Sa valeur par défaut est de 1000 millisecondes. Définissez-le sur 0 pour attendre à la place le délai startup_timeout_sec de chaque serveur. Les serveurs obligatoires continuent d’utiliser leurs délais d’expiration au démarrage.

Enregistrement du client OAuth et URL de rappel

Lorsque votre serveur d’autorisation exige un client OAuth préenregistré, indiquez son ID client lors de l’ajout du MCP server :

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client

Pour un client confidentiel, transmettez également --oauth-client-secret. Lisez le secret à partir d’une variable d’environnement :

codex mcp add example --url https://mcp.example.com --oauth-client-id my-client --oauth-client-secret "$MCP_CLIENT_SECRET"

Cette option exige un identifiant client et un secret non vides. Codex enregistre le secret sous mcp_servers.example.oauth.client_secret dans config.toml. Gardez ce fichier confidentiel et hors du contrôle de version.

Codex affiche l’URL de rappel complète à enregistrer auprès de votre fournisseur :

OAuth callback URL: http://127.0.0.1/callback

Codex enregistre l’URL de rappel avec l’ID client dans config.toml pour les connexions ultérieures :

[mcp_servers.example]
url = "https://mcp.example.com"

[mcp_servers.example.oauth]
client_id = "my-client"
callback_url = "http://127.0.0.1/callback"

Les clients préenregistrés nouvellement ajoutés n’utilisent une URL de rappel stable que si le serveur d’autorisation annonce authorization_response_iss_parameter_supported: true et fournit la métadonnée issuer. Si la prise en charge de l’émetteur n’est pas annoncée, Codex ajoute un ID de rappel propre au serveur, tel que http://127.0.0.1/callback/XuuuHAzzHOni. Les clients existants sans URL de rappel enregistrée continuent d’utiliser leur redirection propre à l’ID de rappel.

Lors de la connexion, le choix de l’URL de rappel dépend de la configuration OAuth et des métadonnées du serveur d’autorisation :

Le mécanisme de repli ne modifie pas l’URL de rappel enregistrée. Codex dérive l’ID de rappel de l’URL du MCP server, y compris son chemin et sa chaîne de requête. Les mêmes règles de sélection s’appliquent aux connexions automatiques et explicites.

Définissez mcp_oauth_callback_url si vous avez besoin d’un chemin de rappel personnalisé ou d’une URL d’entrée Devbox distante. Les clients préenregistrés nouvellement ajoutés utilisent cette URL sans modification lorsque leur fournisseur prend en charge l’identification de l’émetteur. Sinon, ils utilisent l’URL configurée avec l’ajout de l’ID de rappel propre au serveur. Enregistrez toujours l’URL de rappel exacte affichée par codex mcp add.

Pour les rappels http://127.0.0.1 sans port explicite, Codex omet le port d’écoute dans l’URL qu’il affiche et enregistre, puis insère le port d’écoute actif lors de l’autorisation. Cette substitution ne s’applique pas à localhost, aux hôtes IPv6, aux URL HTTPS ni aux rappels qui incluent déjà un port. Les serveurs d’autorisation doivent accepter des ports de bouclage variables conformément à la RFC 8252, section 7.3.

Définissez mcp_oauth_callback_port pour choisir un port d’écoute global fixe, ou définissez mcp_servers.<server-name>.oauth.callback_port pour le remplacer pour un serveur donné. Un port explicite dans l’URL de rappel ne configure pas le service d’écoute. Pour un rappel direct via l’interface de bouclage, utilisez http://127.0.0.1 sans port explicite ou configurez le même port explicite pour l’URL de rappel et le service d’écoute. Un rappel via un proxy peut volontairement utiliser un port dans l’URL externe qui diffère du port du service d’écoute local. Les URL de rappel locales se lient à l’interface locale ; les URL de rappel non locales se lient à 0.0.0.0.

Codex valide toute valeur iss renvoyée avant d’échanger le code d’autorisation. Une valeur iss qui ne correspond pas entraîne toujours le rejet de la réponse. Lorsque la prise en charge de l’émetteur est annoncée, l’absence de iss entraîne également son rejet. Dans les deux cas, le code n’est pas échangé et aucun repli vers une autre URL de rappel n’a lieu. Une URL de rappel mal formée ou l’annonce de la prise en charge de l’émetteur sans émetteur dans les métadonnées reste également une erreur bloquante. Consultez Authentifier les utilisateurs.

Définissez mcp_servers.<server-name>.scopes dans config.toml pour choisir les portées OAuth pour un serveur. Pour les remplacer lors d’une seule connexion, exécutez codex mcp login <name> --scopes read,write. Si aucun des deux n’est défini, Codex utilise les portées OAuth annoncées lorsqu’elles sont disponibles.

Une liste vide (scopes = []) laisse tout de même la bibliothèque OAuth choisir les portées. La bibliothèque peut aussi ajouter offline_access lorsque le serveur d’autorisation le prend en charge.

Enregistrement du client OAuth

Codex prend en charge OAuth Client ID Metadata Documents (CIMD) et Dynamic Client Registration (DCR). Par défaut, Codex choisit automatiquement CIMD lorsque le serveur d’autorisation annonce client_id_metadata_document_supported: true, inclut none dans token_endpoint_auth_methods_supported et que le rappel utilise une URL de boucle locale prise en charge. Sinon, Codex utilise DCR lorsqu’il est disponible. Un ID de client OAuth configuré prévaut toujours et évite l’enregistrement du client.

Pour CIMD sans réponses liées à l’émetteur, Codex CLI utilise un document de métadonnées hébergé par ChatGPT propre au MCP server :

https://chatgpt.com/oauth/codex/<callback_id>/client.json

Codex déduit <callback_id> de l’URL du MCP server et l’inclut dans l’URI de redirection en boucle locale, par exemple http://127.0.0.1:<port>/callback/<callback_id>. Le document de métadonnées enregistre l’URI de boucle locale correspondante sans port. Les serveurs d’autorisation doivent accepter le port sélectionné lors de la connexion tout en exigeant une correspondance exacte de l’hôte et du chemin, conformément à RFC 8252. Les hôtes, chemins ou paramètres de requête de rappel personnalisés nécessitent DCR ou un ID client OAuth configuré.

Codex CLI prend également en charge un document CIMD stable et partagé :

https://chatgpt.com/oauth/codex/client.json

Codex CLI utilise le document stable avec le chemin partagé /callback lorsque le serveur d’autorisation annonce authorization_response_iss_parameter_supported: true, fournit une valeur valide pour issuer dans ses métadonnées et inclut un iss correspondant dans les réponses d’autorisation. Les serveurs dont les réponses ne sont pas liées à l’émetteur utilisent le document propre au rappel.

Pour choisir une méthode d’enregistrement pour une connexion CLI donnée, utilisez --oauth-client-registration :

codex mcp login <server-name> --oauth-client-registration cimd
codex mcp login <server-name> --oauth-client-registration dcr

La valeur par défaut est auto. Les choix d’enregistrement s’appliquent uniquement à la connexion en cours et ne sont pas enregistrés dans config.toml.

Exemples de config.toml

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

[mcp_servers.context7.env]
MY_ENV_VAR = "MY_ENV_VALUE"

# Optional MCP OAuth callback overrides (used by `codex mcp login`)
mcp_oauth_callback_port = 5555
mcp_oauth_callback_url = "https://devbox.example.internal/callback"

[mcp_servers.figma]
url = "https://mcp.figma.com/mcp"
bearer_token_env_var = "FIGMA_OAUTH_TOKEN"
http_headers = { "X-Figma-Region" = "us-east-1" }

[mcp_servers.chrome_devtools]
url = "http://localhost:3000/mcp"
enabled_tools = ["open", "screenshot"]
disabled_tools = ["screenshot"] # applied after enabled_tools
default_tools_approval_mode = "prompt"
startup_timeout_sec = 20
tool_timeout_sec = 45
enabled = true

[mcp_servers.chrome_devtools.tools.open]
approval_mode = "approve"
output_token_limit = 30000

MCP servers fournis par des plugins

Les plugins installés peuvent inclure des MCP servers dans leur manifeste. Ces serveurs sont lancés depuis le plugin ; la configuration utilisateur ne définit donc pas leur commande de transport. Elle peut néanmoins contrôler leur activation et la politique applicable aux outils sous plugins.<plugin>.mcp_servers.<server>.

[plugins."sample@test".mcp_servers.sample]
enabled = true
default_tools_approval_mode = "prompt"
enabled_tools = ["read", "search"]

[plugins."sample@test".mcp_servers.sample.tools.search]
approval_mode = "approve"

Les MCP servers HTTP fournis par des plugins peuvent également déclarer des paramètres OAuth dans .mcp.json. Les manifestes de plugins utilisent les noms de champs en camelCase clientId, callbackUrl et callbackPort :

{
  "mcpServers": {
    "sample": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "clientId": "my-pre-registered-client",
        "callbackUrl": "http://127.0.0.1/callback/registered"
      }
    }
  }
}

Les MCP servers fournis par des plugins suivent les mêmes règles de sélection de l’URL de rappel que les autres MCP servers. Si un plugin fournit un clientId, que son fournisseur ne prend pas en charge les URL de rappel liées à l’émetteur et que callbackUrl ne contient pas l’ID de rappel propre au serveur, Codex ignore cette URL pour la connexion et utilise mcp_oauth_callback_url ou, si cette valeur n’est pas définie, http://127.0.0.1/callback, avec l’ajout de l’ID de rappel. La valeur callbackUrl configurée reste inchangée.

La valeur oauth.callbackPort d’un plugin remplace la valeur globale mcp_oauth_callback_port ; si aucune des deux n’est définie, Codex choisit un port éphémère. Le port inclus dans callbackUrl ne sélectionne pas le port d’écoute. Pour une URL de rappel directe sur l’interface de bouclage avec un port fixe, configurez les deux valeurs à l’identique :

{
  "callbackUrl": "http://127.0.0.1:4321/callback/registered",
  "callbackPort": 4321
}

Pour une entrée distante ou un autre proxy, le port de l’URL de rappel et le port d’écoute local peuvent intentionnellement être différents lorsque le proxy transfère les requêtes vers le processus d’écoute configuré.

Exemples de MCP servers utiles

La liste des MCP servers ne cesse de s’allonger. Voici quelques exemples courants :

• OpenAI Docs MCP : recherchez et consultez la documentation OpenAI destinée aux développeurs.
• Context7 : accédez à une documentation développeur à jour.
• Figma Local et Remote : accédez à vos conceptions Figma.
• Playwright : contrôlez et inspectez un navigateur avec Playwright.
• Chrome Developer Tools : contrôlez et inspectez Chrome.
• Sentry : accédez aux journaux Sentry.
• GitHub : gérez GitHub au-delà des fonctionnalités prises en charge par git (par exemple, les pull requests et les issues).