Model Context Protocol

L’application de bureau ChatGPT, Codex CLI et l’extension IDE prennent en charge les serveurs MCP 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 serveurs MCP 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 serveur MCP 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 serveur MCP

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 serveurs MCP à 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 serveurs MCP 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 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 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

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 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 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 serveurs MCP actifs.

Configurer dans l’extension IDE

1. Ouvrez le menu en forme d’engrenage, 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 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 serveur MCP à 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 serveurs MCP 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 serveur MCP :

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

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 serveur MCP, 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 URL de rappel http://127.0.0.1 sans port, Codex omet le port d’écoute de 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 URL de rappel qui comportent déjà un port. Les serveurs d’autorisation doivent accepter les 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 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 processus d’écoute. Pour une URL de rappel directe sur l’interface de bouclage, utilisez http://127.0.0.1 sans port ou configurez le même port explicite pour l’URL de rappel et le processus d’écoute. Une URL de rappel passant par un proxy peut intentionnellement utiliser un port d’URL externe différent du port 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.

Si le serveur MCP annonce scopes_supported, Codex privilégie ces portées annoncées par le serveur lors de la connexion OAuth. Sinon, Codex utilise les portées configurées dans config.toml.

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, Codex utilise un document de métadonnées hébergé par ChatGPT et propre au serveur MCP :

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

Codex déduit <callback_id> de l’URL du serveur MCP 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é.

La prise en charge d’un document CIMD stable et partagé est en cours de développement et sera bientôt disponible :

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

Codex utilisera le document stable avec le chemin partagé /callback lorsque le serveur d’autorisation annonce authorization_response_iss_parameter_supported: true, fournit un issuer valide 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 continueront d’utiliser 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

Serveurs MCP fournis par des plugins

Les plugins installés peuvent inclure des serveurs MCP 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 serveurs MCP 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 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 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 serveurs MCP utiles

La liste des serveurs MCP 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).