Connecter un serveur MCP d’Oracle Integration Cloud à Codex sur macOS
Configurez les identifiants du client OAuth, obtenez un jeton d’accès, enregistrez le serveur MCP d’un projet OIC dans Codex et vérifiez que ses outils apparaissent dans la CLI ainsi que dans l’application desktop.
Les équipes qui utilisent déjà Oracle Integration Cloud (OIC) pour relier des applications peuvent exposer des intégrations adaptées à Codex via le Model Context Protocol. Codex découvre alors ces intégrations en tant qu’outils et les invoque lorsqu’il a besoin d’y accéder pour répondre à une question. Une intégration qui permet de rechercher une commande, par exemple, peut devenir un outil utilisé par Codex pour répondre à une question concernant cette commande, à condition que l’intégration soit correctement configurée et publiée.
Ici, nous connectons le serveur MCP d’un projet OIC à Codex sur macOS. Vous collectez quelques valeurs de configuration, demandez un jeton d’accès OAuth, enregistrez le serveur, et vous vous assurez que Codex peut voir ses outils. Ce guide aborde également l’étape supplémentaire liée à l’environnement nécessaire pour l’application de bureau, ainsi que les démarches à suivre lorsque le jeton arrive à échéance. Il part du principe qu’un environnement OIC est à votre disposition et que quelqu’un a déjà préparé une application OAuth dans OCI IAM à cette fin.
Les éléments impliqués
Quatre composants participent à ce processus :
- Oracle Integration Cloud héberge les intégrations qui communiquent avec vos applications et services.
- Le serveur MCP du projet OIC publie des intégrations enregistrées en tant qu’outils Agentic AI.
- Codex est le client MCP. Il trouve ces outils et les utilise au besoin.
Une demande est transmise de la manière suivante : Codex, puis le serveur OIC MCP, ensuite l’intégration enregistrée, et enfin l’application connectée.
Au préalable, avant que Codex ne puisse atteindre le serveur, vous demandez à OCI IAM un jeton d’accès à durée limitée en utilisant les identifiants du client de l’application OAuth. Ce jeton est ensuite transmis à Codex via une variable d’environnement.
Prérequis à remplir en premier
Terminez la configuration OIC et des identités avant d’utiliser le terminal. Vous avez besoin de :
- Un projet OIC avec l’option serveur MCP activée.
- Au moins une intégration active enregistrée en tant qu’outil Agentic AI.
- L’URL du serveur MCP. Ouvrez le projet dans OIC, cliquez sur l’icône du crayon (Éditer) et trouvez le champ intitulé « The MCP server runs at ». Il s’agit d’une adresse longue qui combine l’hôte de votre instance, la région et l’identifiant du projet ; l’Étape 1 montre sa forme complète.
- Une application OAuth confidentielle OCI IAM configurée pour les identifiants de client, avec une portée de ressource OIC qui inclut le rôle ServiceInvoker.
- Son ID de client, son secret de client et sa portée de ressource. Dans la console OCI, allez dans Identité et sécurité, puis Domaines, ensuite le domaine lié à votre instance OIC, puis Applications intégrées, enfin votre application confidentielle. L’ID de client et le secret se trouvent sur cette page. Sélectionnez Éditer la configuration OAuth et cherchez dans la politique d’émission de tokens la portée, qui inclut
urn:opc:resource:consumer::all. - Le nom de domaine d’identité. Dans la console OCI, cliquez sur l’icône du profil en haut à droite et sélectionnez « Identity Domain » pour voir son URL, qui ressemble à
https://<identity_domain>.identity.oraclecloud.com. Vous n’avez besoin que de la partie<identity_domain>, sans le protocole ni l’extension. Pourhttps://example123.identity.oraclecloud.com, cela signifieexample123. - Codex, que ce soit via la CLI ou l’application de bureau, doit être installé.
- Un shell zsh pour macOS, car les commandes sont écrites pour celui-ci.
Si un élément de cette liste manque, résolvez-le immédiatement. Sinon, la connexion ne fonctionnera pas.
Étape 1 : préparer le terminal
Ouvrez Terminal sur votre Mac. Tout ce qui suit suppose l’utilisation de zsh.
Vérifier la présence de Codex et jq
Exécutez :
codex --version
command -v jq
La première ligne doit afficher la version du Codex. La deuxième doit afficher le chemin vers jq, outil utilisé pour extraire le jeton de la réponse d’authentification.
Si jq est manquant mais que Homebrew est installé :
brew install jq
Définir vos valeurs
Remplacez chaque placeholder <angle bracket> par votre propre valeur, puis exécutez :
export OIC_CLIENT_ID='<CLIENT_ID>'
export OIC_RESOURCE_SCOPE='<RESOURCE_SCOPE>'
export OIC_IDENTITY_DOMAIN='<IDENTITY_DOMAIN>'
export OIC_MCP_URL='https://<oic-instance-host>.integration.<region>.ocp.oraclecloud.com/mcp-server/v1/projects/<project-identifier>/mcp'
Signification de chaque variable :
OIC_CLIENT_IDcorrespond à l’ID du client de votre application confidentielle OAuth.OIC_RESOURCE_SCOPEcontient la chaîne de portée complète telle qu’elle a été configurée pour OIC. Elle inclut l’élémenturn:opc:resource:consumer::all.OIC_IDENTITY_DOMAINreprésente simplement la partie avant.identity.oraclecloud.com, par exempleexample123.OIC_MCP_URLest l’URL spécifique au projet, telle qu’elle apparaît dans le champ « The MCP server runs at ».
Évitez d’inclure le secret du client dans ce bloc. L’étape suivante le demandera via un champ caché.
Détecter les valeurs manquantes et les placeholders restants
Ce bloc vérifie que toutes les quatre variables contiennent bien des valeurs et qu’aucune ne comporte encore des crochets angulaires :
(
setup_ready=true
for name in \
OIC_CLIENT_ID \
OIC_RESOURCE_SCOPE \
OIC_IDENTITY_DOMAIN \
OIC_MCP_URL
do
value="${(P)name}"
if [[ -z "$value" || "$value" == *'<'* || "$value" == *'>'* ]]; then
printf 'Check %s: missing value or unreplaced placeholder.\n' "$name"
setup_ready=false
fi
done
if [[ "$setup_ready" == true ]]; then
printf 'Required values are populated and contain no placeholders.\n'
fi
)
Il se contente de vérifier que les valeurs existent, sans s’assurer que les identifiants, la portée ou l’URL sont corrects. Laissez cette session de terminal ouverte, car l’étape suivante réutilisera ces variables.
Étape 2 : obtenir un jeton d’accès OAuth
Dans la même session, exécutez le bloc ci-dessous. Il demande le secret du client, sollicite un jeton auprès d’OCI IAM, et le met à disposition de la CLI Codex ainsi que des applications desktop lancées par la suite. Saisissez ou collez le secret puis appuyez sur Retour. Rien n’apparaît à l’écran pendant que vous tapez.
read -rs 'OIC_CLIENT_SECRET?OIC client secret: '
printf '\n'
if token="$(
curl --silent --show-error --fail \
--user "${OIC_CLIENT_ID}:${OIC_CLIENT_SECRET}" \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode "scope=${OIC_RESOURCE_SCOPE}" \
"https://${OIC_IDENTITY_DOMAIN}.identity.oraclecloud.com:443/oauth2/v1/token" \
| jq -er '.access_token'
)"; then
unset OIC_CLIENT_SECRET
export OIC_ACCESS_TOKEN="$token"
unset token
if launchctl setenv OIC_ACCESS_TOKEN "$OIC_ACCESS_TOKEN"; then
echo 'Access token received and set for CLI and newly launched desktop apps.'
else
echo 'Access token set for CLI, but desktop environment setup failed.' >&2
fi
else
unset OIC_CLIENT_SECRET token
echo 'ERROR: Token request failed. Check your values and OAuth configuration.' >&2
fi
Au succès, il affiche :
Access token received and set for CLI and newly launched desktop apps.
Puisque l’instruction n’est pas spécifiée, le secret n’est jamais enregistré dans l’historique des commandes, et le script efface la variable secrète une fois la demande de token terminée.
Vérifier l’existence du token
Cette vérification indique la présence du token sans jamais l’afficher :
[[ -n "$OIC_ACCESS_TOKEN" && "$OIC_ACCESS_TOKEN" != 'null' ]] \
&& echo 'OIC access token is present' \
|| echo 'ERROR: OIC access token is missing'
Cela prouve que la variable possède une valeur. Le fait que l’OIC accepte le jeton ne sera déterminé qu’une fois que Codex communiquera réellement avec le serveur.
Pour l’application desktop, fermez complètement Codex puis rouvrez-le après que launchctl setenv ait réussi, afin qu’il prenne en compte l’environnement mis à jour.
Tenez le jeton pour un secret. Ne l’affichez pas dans la terminal, et n’insérez-le ni dans des chats, des e-mails, des tickets ou des documents.
Étape 3 : enregistrer le serveur dans Codex
Avec le jeton en main, exécutez ceci dans la même session :
codex mcp add oic \
--url "$OIC_MCP_URL" \
--bearer-token-env-var OIC_ACCESS_TOKEN
Cela ajoute le serveur à Codex sous le nom oic, en utilisant l’URL de l’Étape 1. Avec --bearer-token-env-var, Codex recherche le jeton dans la variable OIC_ACCESS_TOKEN lors de la connexion. Indiquez le nom de la variable sans signe dollar, afin que la configuration enregistrée fasse référence à cette variable et non au valeur actuelle du jeton.
Étape 4 : vérifier la configuration
Listez les serveurs configurés et examinez le nouveau :
codex mcp list
codex mcp get oic
Vérifiez que :
- le serveur s’appelle
oicet est activé ; - l’URL correspond à l’endpoint MCP de votre projet OIC ;
- le transport est
streamable_http; - la variable bearer-token est
OIC_ACCESS_TOKEN.
Si le serveur est absent, désactivé ou orienté vers une URL incorrecte, corrigez cela avant de continuer.
Étape 5 : trouver les outils depuis la CLI
Démarrez Codex depuis le terminal où OIC_ACCESS_TOKEN a été exporté, afin qu’il hérite du jeton :
codex
Lorsqu’il s’ouvre, saisissez cette instruction :
List the tools available from every MCP server with oic in its name.
Vous devriez voir une liste des outils exposés par votre projet OIC. Si la liste est vide, retournez dans OIC et vérifiez qu’une intégration active du projet est enregistrée comme outil Agentic AI. Si Codex signale un problème d’authentification, vérifiez à nouveau la configuration OAuth, répétez l’Étape 2 pour obtenir un jeton nouveau, puis redémarrez Codex depuis ce terminal.
Étape 6 : l’utiliser depuis l’application de bureau
Avant d’ouvrir l’application, assurez-vous que l’Étape 2 a été effectuée, y compris avec cette commande :
launchctl setenv OIC_ACCESS_TOKEN "$OIC_ACCESS_TOKEN"
Si cela a déjà fonctionné lors de l’Étape 2, il n’est pas nécessaire de le répéter. Fermez complètement l’application desktop et redémarrez-la afin qu’elle puisse lire le jeton. Les deux clients utilisent la même configuration MCP, mais une variable exportée uniquement dans une session de terminal ne parvient jamais seule à l’application desktop.
Démarrez une nouvelle tâche Codex et saisissez :
/mcp
Vérifiez que oic apparaît, puis envoyez la même demande de découverte :
List the tools available from every MCP server with oic in its name.
Le Codex doit lister les outils de votre projet OIC.
Lorsque le jeton expire
Le jeton d’accès a une durée de vie courte, et sa durée est déterminée par les paramètres IAM OCI. Pour renouveler la connexion :
- Retournez à la console de configuration ou saisissez à nouveau les valeurs de l’Étape 1.
- Répétez l’Étape 2 pour obtenir un nouveau jeton et mettre à jour l’environnement de bureau.
- Fermez puis rouvrez l’application de bureau. Pour une utilisation en ligne de commande, lancez une nouvelle session Codex depuis la console qui contient le nouveau jeton.
Il n’est pas nécessaire de réenregistrer le serveur, sauf si sa configuration a été supprimée ou modifiée.
Notes de dépannage
Quelques schémas d’échec se produisent fréquemment avec ce type de configuration :
- Une demande de jeton qui échoue immédiatement indique généralement un identifiant client, un secret ou une portée incorrects, ou une valeur de domaine d’identité qui contient encore le préfixe ou le suffixe
https://. - Un jeton qui fonctionne en ligne de commande mais pas dans l’application signifie presque toujours que l’environnement de bureau n’a pas été mis à jour, ou que l’application n’a pas été redémarrée après la mise à jour.
- Une liste d’outils vide sans erreur indique généralement un problème du côté OIC : le serveur MCP du projet n’est pas activé ou aucune intégration n’a été enregistrée en tant qu’outil Agentic AI.
- Les erreurs d’authentification qui apparaissent après un certain temps de fonctionnement normal sont très probablement dues à un jeton expiré ; il faut donc répéter l’Étape 2.