Model Context Protocol

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

Les fonctionnalités ci-dessous s’appliquent aux serveurs MCP configurés sur un hôte Codex. Les outils des plugins hébergés peuvent offrir des fonctionnalités différentes.

Fonctionnalités MCP prises en charge

• Serveurs STDIO : serveurs exécutés dans un processus local lancé par une commande.
  • Variables d’environnement
• Serveurs Streamable HTTP : serveurs accessibles à une adresse donnée.
  • Authentification par jeton Bearer
  • Authentification OAuth, y compris les documents de métadonnées d’identifiant client (CIMD) et l’enregistrement dynamique des clients (DCR)
  • Authentification par session ChatGPT pour les serveurs de confiance d’OpenAI
• Instructions du serveur : Codex lit le champ MCP instructions renvoyé lors de l’initialisation et s’en sert pour guider l’utilisation de l’ensemble des outils du serveur.

Si vous développez ou maintenez un serveur MCP pour Codex, utilisez instructions pour décrire les workflows qui font appel à plusieurs outils, ainsi que les contraintes et les limites de débit communes à l’ensemble du serveur. Rédigez les 512 premiers caractères de façon à ce qu’ils se suffisent à eux-mêmes : Codex disposera ainsi des consignes essentielles au moment de décider comment utiliser le serveur.

Connecter Codex à un serveur MCP

Codex enregistre la configuration MCP dans config.toml, avec ses autres paramètres de configuration. Par défaut, ce fichier se trouve dans ~/.codex/config.toml. Vous pouvez aussi configurer des serveurs MCP pour un projet particulier dans .codex/config.toml (projets de confiance uniquement).

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

Configuration dans l’application de bureau ChatGPT

1. Ouvrez les Paramètres, puis sélectionnez Serveurs MCP.
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 indique quels serveurs sont activés et lesquels nécessitent OAuth. Sélectionnez S’authentifier lorsqu’un serveur OAuth exige une connexion. Dans la zone de saisie, tapez /mcp pour afficher les serveurs connectés.

Utiliser des outils MCP dans ChatGPT sur le Web

Lorsque vous reprenez sur un autre appareil une conversation qui utilise l’accès à l’ordinateur local avec Work Cloud, aucun plugin n’est installé et aucun accès aux comptes connectés n’est accordé.

Avec l’accès à l’ordinateur local dans Work Cloud, l’exigence TOML mcp_servers définie pour l’entreprise dans Agent Security s’applique aux exécuteurs locaux. Les conteneurs cloud restent soumis aux politiques de Work Cloud. Les serveurs MCP locaux et leurs modes de transport ne sont pas forcément disponibles dans le cloud. Vérifiez séparément la connectivité et l’authentification.

Pour utiliser les hooks d’entreprise avec l’accès à l’ordinateur local dans Work Cloud, tenez compte des points suivants :

• Hooks d’entreprise. Si 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. Ces hooks s’exécutent sur le coordinateur cloud (l’orchestrateur) pour les événements pris en charge du cycle de vie et des outils. L’orchestration cloud ne prend en charge ni les hooks de commande ni ceux issus de la configuration locale ou des plugins, même lorsque les outils s’exécutent localement.
• Audit. Avant de vous appuyer sur ces hooks, testez la connexion de rappel, vérifiez les événements reçus et déterminez les conséquences d’un échec sur la tâche. Les hooks MCP ne fournissent pas de piste d’audit complète pour l’API de conformité.
• Limites : l’orchestration cloud ne prend en charge ni les hooks de commande ni ceux issus de la configuration locale ou des plugins, même lorsque les outils s’exécutent localement. Les particuliers ne peuvent pas utiliser de hooks avec cette fonctionnalité. Lorsque l’orchestration et l’exécution ont toutes deux lieu localement, les hooks déjà pris en charge continuent de fonctionner dans les conversations Work et Codex entièrement locales. 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 savoir quelles fonctionnalités sont prises en charge.

Dans une conversation hébergée de ChatGPT Work, installez un plugin pour utiliser les connecteurs et les outils MCP distants qu’il contient. Une fois le plugin installé, les modes Chat et Work peuvent utiliser ces outils. Les administrateurs de l’espace de travail peuvent définir les plugins et les outils disponibles.

Sur le Web, ChatGPT ne lit pas les fichiers de configuration locaux de Codex et ne donne pas accès au menu des commandes locales de Codex. Ouvrez l’onglet Plugins pour parcourir et gérer les outils disponibles.

Configuration avec la CLI

Ajouter un serveur MCP

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

Par exemple, pour ajouter Context7 (un serveur MCP gratuit de documentation pour les développeurs), exécutez la commande suivante :

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

Autres commandes de la 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 vous connecter à un serveur qui prend en charge OAuth, exécutez codex mcp login <server-name>. Si vous utilisez un terminal sans navigateur local, exécutez codex mcp login <server-name> --no-browser. Ouvrez l’URL d’autorisation affichée dans un navigateur et authentifiez-vous. Collez ensuite l’URL de redirection complète dans le terminal, même si le navigateur ne parvient pas à charger la page de rappel.

Interface utilisateur du terminal (TUI)

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

Configuration dans l’extension IDE

1. Ouvrez le menu à l’aide de l’icône en forme de roue dentée, puis sélectionnez Serveurs MCP.
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 serveurs MCP indique quels serveurs sont activés et lesquels nécessitent OAuth. Sélectionnez S’authentifier lorsqu’un serveur OAuth exige une connexion.

Configuration avec config.toml

Pour un réglage plus fin, modifiez ~/.codex/config.toml ou le fichier .codex/config.toml d’un projet. La référence de configuration vous permet de rechercher une option parmi toutes les options MCP prises en charge.

Configurez chaque serveur MCP dans une table [mcp_servers.<server-name>] du fichier de configuration.

Serveurs STDIO

• command (obligatoire) : commande qui lance 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 à partir duquel lancer le serveur.

env_vars accepte des noms de variables ou des objets qui précisent leur source :

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

Pour les entrées de type chaîne et celles qui indiquent source = "local", Codex lit les variables dans son environnement local. Avec source = "remote", Codex les lit dans l’environnement d’exécution distant, ce qui nécessite le transport stdio MCP à distance.

Serveurs Streamable HTTP

• url (obligatoire) : adresse du serveur.
• auth (facultatif) : méthode d’authentification à essayer après les jetons Bearer et les en-têtes d’autorisation configurés. Utilisez oauth (valeur par défaut) pour employer les identifiants OAuth MCP enregistrés. Utilisez chatgpt pour employer la session ChatGPT en cours avec l’origine ChatGPT de confiance d’OpenAI. Les identifiants OAuth enregistrés servent alors de solution de repli.
• bearer_token_env_var (facultatif) : nom de la variable d’environnement contenant le jeton Bearer à envoyer dans Authorization.
• http_headers (facultatif) : correspondance entre les noms d’en-têtes et des valeurs statiques.
• env_http_headers (facultatif) : correspondance entre les noms d’en-têtes et les noms de variables d’environnement dont proviennent les valeurs.
• http_headers_helper (facultatif) : commande locale qui affiche un objet JSON associant des noms d’en-têtes à des chaînes de caractères, par exemple {"X-Auth": "temporary-token"}. Cette option est disponible pour les connexions MCP via HTTP établies depuis l’environnement local. Elle ne s’applique ni aux serveurs stdio ni aux connexions établies via un environnement d’exécution distant.

Codex met en cache les en-têtes fournis par la commande auxiliaire pour la connexion. Lorsqu’une requête POST de même origine renvoie 401 ou 403, Codex actualise les en-têtes une fois et ne réessaie que si la commande renvoie des valeurs différentes. Les jetons Bearer explicites et les identifiants OAuth ont priorité sur l’en-tête Authorization fourni par la commande. Une réponse OAuth 403 signalant une portée insuffisante ne déclenche pas d’actualisation des en-têtes.

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

Autres options de configuration

• environment_id permet de choisir l’environnement d’un serveur stdio ou Streamable HTTP. Sa valeur par défaut est local. Pour vous connecter via un exécuteur distant, utilisez l’identifiant d’environnement enregistré pour cet exécuteur.
• startup_timeout_sec (facultatif) : délai maximal de démarrage du serveur, en secondes. Valeur par défaut : 10.
• tool_timeout_sec (facultatif) : délai maximal accordé au serveur pour exécuter un outil, en secondes. Valeur par défaut : 60.
• enabled (facultatif) : utilisez false pour désactiver un serveur sans le supprimer.
• Définissez required = true pour que le démarrage échoue si ce serveur est activé mais n’est pas prêt. Par défaut, startup_readiness = "connection" exige une connexion active. Définissez startup_readiness = "catalog" pour qu’un catalogue d’outils valide en cache suffise au démarrage pendant que le serveur établit la connexion. Les appels d’outils nécessitent toujours une connexion active.
• enabled_tools (facultatif) : liste des outils autorisés.
• disabled_tools (facultatif) : liste des outils interdits (appliquée après enabled_tools).
• default_tools_approval_mode (facultatif) : mode d’approbation par défaut des outils de ce serveur. Les valeurs prises en charge sont auto, prompt, writes et approve. Le mode writes demande une approbation pour les outils qui ne sont pas déclarés en lecture seule.
• tools.<tool>.approval_mode (facultatif) : remplace le mode d’approbation par défaut pour un outil donné.
• tools.<tool>.output_token_limit (facultatif) : nombre strictement positif de tokens alloués à la sortie d’un outil, avant application de la marge de sérialisation habituelle de 20 %. Cette valeur remplace le seuil de troncature par défaut du modèle pour la sortie de cet outil.

Le paramètre de premier niveau mcp_optional_startup_grace_ms détermine combien de temps Codex attend les serveurs MCP facultatifs lors de la création du catalogue initial d’outils. Sa valeur par défaut est de 1000 millisecondes. Réglez-le sur 0 pour que Codex applique à chaque serveur son propre délai startup_timeout_sec. Les serveurs obligatoires conservent leur délai de démarrage.

Enregistrement des clients OAuth et URL de rappel

Si votre serveur d’autorisation exige un client OAuth préenregistré, indiquez l’identifiant du client lorsque vous ajoutez le serveur MCP :

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

Pour un client confidentiel, ajoutez également --oauth-client-secret. Lisez le secret depuis 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 nécessite un identifiant client et un secret, tous deux non vides. Codex enregistre le secret sous mcp_servers.example.oauth.client_secret dans config.toml. Gardez ce fichier privé et excluez-le du contrôle de version.

Enregistrez l’URL de rappel exacte affichée par codex mcp add. Lorsque le serveur d’autorisation annonce la prise en charge de l’identification de l’émetteur, la CLI peut afficher l’URL suivante :

OAuth callback URL: http://127.0.0.1/callback

Pour le client public de cet exemple, Codex enregistre l’URL de rappel et l’identifiant 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 un champ issuer dans ses métadonnées. Si le serveur n’annonce pas la prise en charge de l’identification de l’émetteur, Codex ajoute à l’URL un identifiant de rappel propre au serveur, ce qui donne par exemple http://127.0.0.1/callback/XuuuHAzzHOni. Les clients existants sans URL de rappel enregistrée continuent d’utiliser leur URI de redirection contenant leur identifiant de rappel.

Lors de la connexion, Codex choisit l’URL de rappel en fonction de la configuration OAuth et des métadonnées du serveur d’autorisation :

Le recours à une autre URL ne modifie pas l’URL de rappel enregistrée. Codex calcule l’identifiant de rappel à partir de l’URL du serveur MCP, en tenant compte du chemin et de la 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 pour une Devbox distante. Les clients préenregistrés nouvellement ajoutés utilisent cette URL telle quelle si leur fournisseur prend en charge l’identification de l’émetteur. Sinon, ils utilisent l’URL configurée à laquelle s’ajoute l’identifiant de rappel propre au serveur. Enregistrez toujours l’URL de rappel exacte affichée par codex mcp add.

Pour les URL de rappel http://127.0.0.1 sans port explicite, Codex omet le port d’écoute dans l’URL qu’il affiche et enregistre, puis y 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 URL de rappel qui contiennent déjà un port. Les serveurs d’autorisation doivent accepter des ports de bouclage variables conformément à la section 7.3 de la RFC 8252.

Définissez mcp_oauth_callback_port pour choisir un port d’écoute global fixe, ou 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 port d’écoute. Pour un rappel direct sur 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 pour l’écoute. Si le rappel passe par un proxy, le port de l’URL externe peut volontairement différer du port d’écoute local. Pour les URL de rappel locales, Codex écoute sur l’interface locale. Pour les autres, il écoute sur 0.0.0.0.

Codex valide toute valeur iss renvoyée avant d’échanger le code d’autorisation. Si la valeur iss ne correspond pas à celle attendue, Codex rejette systématiquement la réponse. Si le serveur annonce la prise en charge de l’identification de l’émetteur, l’absence de iss entraîne également le rejet de la réponse. Dans ces deux cas, Codex n’échange pas le code et n’essaie pas d’autre URL de rappel. La connexion échoue également si l’URL de rappel est mal formée ou si le serveur annonce la prise en charge de l’identification de l’émetteur sans fournir d’émetteur dans ses métadonnées. Consultez Authentifier les utilisateurs.

Définissez mcp_servers.<server-name>.scopes dans config.toml pour choisir les portées OAuth d’un serveur. Pour les remplacer le temps d’une connexion, exécutez codex mcp login <name> --scopes read,write. Si vous ne les précisez ni dans le fichier ni dans la commande, Codex demande les portées indiquées par le serveur dans son défi d’authentification initial WWW-Authenticate. Si ce défi ne précise aucune portée, Codex utilise les portées annoncées dans les métadonnées de la ressource protégée, lorsqu’elles y figurent.

Une liste vide (scopes = []) laisse la bibliothèque OAuth choisir les portées. La bibliothèque peut également ajouter offline_access si le serveur d’autorisation le prend en charge.

Enregistrement des clients OAuth

Codex prend en charge les documents de métadonnées d’identifiant client OAuth (CIMD) et l’enregistrement dynamique des clients (DCR). Par défaut, Codex choisit automatiquement CIMD si 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 bouclage prise en charge. Sinon, Codex utilise DCR lorsque cette méthode est disponible. Si un identifiant client OAuth est configuré, il est toujours prioritaire et Codex ignore l’étape d’enregistrement du client.

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

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

Codex calcule <callback_id> à partir de l’URL du serveur MCP et l’inclut dans l’URI de redirection de bouclage, par exemple http://127.0.0.1:<port>/callback/<callback_id>. Le document de métadonnées déclare l’URI de bouclage correspondante sans port. Les serveurs d’autorisation doivent accepter le port choisi lors de la connexion tout en exigeant une correspondance exacte de l’hôte et du chemin, conformément à la RFC 8252. Un hôte, un chemin ou des paramètres de requête de rappel personnalisés nécessitent DCR ou un identifiant 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 si le serveur d’autorisation annonce authorization_response_iss_parameter_supported: true, fournit un issuer valide dans ses métadonnées et inclut la valeur iss correspondante dans ses 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 la méthode d’enregistrement pour une seule connexion depuis la CLI, 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. Le choix de la méthode d’enregistrement ne s’applique qu’à la connexion en cours et n’est pas enregistré dans config.toml.

Exemples de configuration dans 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

Serveurs MCP fournis par des plugins

Les plugins installés peuvent inclure des serveurs MCP dans leur manifeste. Le plugin lance ces serveurs, de sorte que la configuration utilisateur ne définit pas leur commande de transport. Vous pouvez toutefois activer ou désactiver ces serveurs et définir les règles d’utilisation de leurs outils dans la configuration utilisateur, 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 serveurs MCP HTTP fournis par des plugins peuvent également déclarer des paramètres OAuth dans .mcp.json. Les manifestes des 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 serveurs MCP fournis par des plugins suivent les mêmes règles de sélection de l’URL de rappel que les autres serveurs MCP. Si un plugin fournit un clientId, que son fournisseur ne prend pas en charge les rappels liés à l’émetteur et que callbackUrl ne contient pas l’identifiant de rappel propre au serveur, Codex ignore cette URL pour la connexion. Il utilise mcp_oauth_callback_url ou, si ce paramètre n’est pas défini, http://127.0.0.1/callback, et y ajoute l’identifiant de rappel. La valeur configurée de callbackUrl reste inchangée.

Le paramètre oauth.callbackPort d’un plugin a priorité sur le paramètre global mcp_oauth_callback_port. Si aucun des deux n’est défini, Codex choisit un port éphémère. Le port indiqué dans callbackUrl ne détermine pas le port d’écoute. Pour un rappel direct sur l’interface de bouclage avec un port fixe, configurez le même port aux deux endroits :

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

Avec un point d’entrée distant ou un autre proxy, le port de l’URL de rappel peut volontairement différer du port d’écoute local si le proxy transmet les requêtes au port d’écoute configuré.

Exemples de serveurs MCP utiles

Le nombre de serveurs MCP ne cesse d’augmenter. En voici quelques-uns parmi les plus courants :

• OpenAI Docs MCP : recherchez et consultez la documentation d’OpenAI destinée aux développeurs.
• Context7 : accédez à une documentation à jour pour les développeurs.
• Figma en local et à distance : accédez à vos maquettes Figma.
• Playwright : pilotez et inspectez un navigateur avec Playwright.
• Outils de développement Chrome : pilotez et inspectez Chrome.
• Sentry : consultez les journaux Sentry.
• GitHub : gérez les éléments de GitHub que git ne prend pas en charge, comme les pull requests et les issues.