Conecte un servidor MCP de Oracle Integration Cloud a Codex en macOS
Configurar las credenciales del cliente OAuth, obtener un token de acceso, registrar el servidor MCP de un proyecto OIC en Codex y confirmar que sus herramientas aparezcan en la CLI y la aplicación de escritorio.
Los equipos que ya utilizan Oracle Integration Cloud (OIC) para conectar aplicaciones pueden exponer integraciones adecuadas a Codex a través del Protocolo de Contexto de Modelo. Codex luego descubre esas integraciones como herramientas y las utiliza cuando se necesita responder a una pregunta. Por ejemplo, una integración que consulta un pedido podría convertirse en una herramienta que Codex emplea para responder a preguntas sobre dicho pedido, siempre y cuando la integración esté configurada y publicada correctamente.
Aquí conectamos el servidor MCP de un proyecto OIC a Codex en macOS. Se recogen algunos valores de configuración, se solicita un token de acceso OAuth, se registra el servidor y se confirma que Codex puede ver sus herramientas. También aborda el paso adicional del entorno necesario para la aplicación de escritorio y qué hacer cuando se agota el token. Se da por sentado que dispone de un entorno OIC y que alguien ya ha preparado una aplicación OAuth en OCI IAM para este fin.
Los componentes involucrados
Participan cuatro componentes:
- Oracle Integration Cloud alberga las integraciones que se comunican con sus aplicaciones y servicios.
- El servidor MCP del proyecto OIC publica integraciones que se registran como herramientas de Agentic AI.
- Codex es el cliente MCP. Encuentra las herramientas y las utiliza cuando es apropiado.
Una solicitud se transmite de la siguiente manera: Codex, luego el servidor OIC MCP, después la integración registrada y finalmente la aplicación conectada.
Antes de que Codex pueda llegar al servidor, se solicita a OCI IAM un token de acceso de corta duración utilizando las credenciales del cliente de la aplicación OAuth. Ese token se pasa luego a Codex a través de una variable de entorno.
Requisitos previos que deben cumplirse primero
Complete la configuración de OIC e identidad antes de tocar la terminal. Necesita:
- Un proyecto OIC con la opción del servidor MCP habilitada.
- Al menos una integración activa registrada como herramienta de Agentic AI.
- La URL del servidor MCP. Abra el proyecto en OIC, haga clic en el ícono del lápiz (Editar) y busque el campo etiquetado como “El servidor MCP se ejecuta en”. Se trata de una dirección larga que combina el host de su instancia, la región y el identificador del proyecto; el Paso 1 muestra su forma completa.
- Una aplicación OAuth confidencial de OCI IAM configurada para credenciales de cliente, con el ámbito de recursos de OIC que incluye el rol ServiceInvoker.
- Su ID de cliente, secreto de cliente y ámbito de recursos. En la Consola de OCI vaya a Identidad y Seguridad, luego a Dominios, después al dominio asociado a su instancia de OIC, seguido de Aplicaciones Integradas y, finalmente, a su aplicación confidencial. El ID y el secreto de cliente se encuentran en esa página. Elija Editar Configuración OAuth y busque en la Política de Emisión de Tokens el ámbito, que incluye
urn:opc:resource:consumer::all. - El nombre de dominio de la identidad. En la Consola OCI, haga clic en el ícono del perfil en la esquina superior derecha y elija Identity Domain para ver su URL, que tiene el formato
https://<identity_domain>.identity.oraclecloud.com. Solo necesita la parte<identity_domain>, sin el esquema ni el sufijo. Parahttps://example123.identity.oraclecloud.com, eso significaexample123. - Codex, ya sea a través de la CLI o de la aplicación de escritorio, instalado.
- Una shell zsh en macOS, ya que los comandos están escritos para ella.
Si falta algo de esa lista, resuélvalo ahora. De lo contrario, la conexión no funcionará.
Paso 1: preparar la terminal
Abra Terminal en su Mac. Todo lo que sigue asume el uso de zsh.
Verificar la presencia de Codex y jq
Ejecute:
codex --version
command -v jq
La primera línea debe imprimir la versión de Codex. La segunda debe imprimir la ruta de jq, que se utiliza para extraer el token de la respuesta de autenticación.
Si falta jq pero está instalado Homebrew:
brew install jq
Establezca sus valores
Cambie cada marcador de posición <angle bracket> por su propio valor y, a continuación, ejecute:
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'
Qué significa cada variable:
OIC_CLIENT_IDes el ID del cliente de su aplicación confidencial OAuth.OIC_RESOURCE_SCOPEcontiene la cadena de alcance completa según está configurada para OIC. Incluye el elementourn:opc:resource:consumer::all.OIC_IDENTITY_DOMAINes simplemente la parte anterior a.identity.oraclecloud.com, como por ejemploexample123.OIC_MCP_URLes la URL completa específica del proyecto, copiada del campo “El servidor MCP se ejecuta en”.
Mantenga la clave secreta del cliente fuera de este bloque. El siguiente paso la solicitará mediante un campo de entrada oculto.
Detección de valores faltantes y marcadores restantes
Este bloque verifica que las cuatro variables contengan algún valor y que ninguna siga teniendo corchetes angulares:
(
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
)
Solo verifica que existan los valores, no que las credenciales, el alcance o la URL sean correctos. Deje abierta esta sesión de terminal, ya que el siguiente paso reutilizará estas variables.
Paso 2: obtener un token de acceso OAuth
Dentro de la misma sesión, ejecute el bloque a continuación. Pide la clave secreta del cliente, solicita un token de OCI IAM y lo pone a disposición de la CLI de Codex y de las aplicaciones de escritorio que se inicien posteriormente. Escriba o pegue la clave secreta y presione Return. No se mostrará nada en la pantalla mientras escriba.
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
En caso de éxito, imprime:
Access token received and set for CLI and newly launched desktop apps.
Dado que la solicitud no contiene información adicional, la contraseña nunca se guarda en el historial de comandos, y el script elimina la variable de contraseña una vez finalizada la solicitud de token.
Confirmar que el token existe
Esta verificación indica su presencia sin imprimir nunca el token:
[[ -n "$OIC_ACCESS_TOKEN" && "$OIC_ACCESS_TOKEN" != 'null' ]] \
&& echo 'OIC access token is present' \
|| echo 'ERROR: OIC access token is missing'
Eso demuestra que la variable tiene un valor. Si OIC acepta el token solo se determinará cuando Codex se comunique realmente con el servidor.
En la aplicación de escritorio, cierre completamente Codex y ábrala nuevamente después de que launchctl setenv haya tenido éxito, para que perciba el entorno actualizado.
Trate el token como un secreto. No lo muestre en la terminal, ni lo pegue en chats, correos electrónicos, tickets o documentos.
Paso 3: registrar el servidor en Codex
Con el token en mano, ejecute lo siguiente en la misma sesión:
codex mcp add oic \
--url "$OIC_MCP_URL" \
--bearer-token-env-var OIC_ACCESS_TOKEN
Eso agrega el servidor a Codex bajo el nombre oic, utilizando la URL del Paso 1. Con --bearer-token-env-var, Codex busca el token en la variable OIC_ACCESS_TOKEN al conectarse. Indíquele el nombre de la variable sin signo de dólar, de modo que la configuración almacenada haga referencia a dicha variable y no capture el valor del token actual.
Paso 4: verificar la configuración
Enumere los servidores configurados e inspeccione el nuevo:
codex mcp list
codex mcp get oic
Asegúrese de que:
- el servidor se llame
oicy esté habilitado; - la URL coincida con el endpoint MCP de su proyecto OIC;
- el transporte sea
streamable_http; - la variable bearer-token sea
OIC_ACCESS_TOKEN.
Si el servidor falta, está deshabilitado o apunta a una URL incorrecta, solucione ese problema antes de continuar.
Paso 5: encontrar las herramientas desde la CLI
Ejecute Codex desde la terminal donde se exportó OIC_ACCESS_TOKEN, para que herede el token:
codex
Cuando se abra, ingrese este comando:
List the tools available from every MCP server with oic in its name.
Debería ver una lista de las herramientas expuestas por su proyecto OIC. Si la lista está vacía, regrese a OIC y verifique que haya una integración activa en el proyecto registrada como herramienta de Agentic AI. Si Codex muestra un problema de autenticación, vuelva a revisar la configuración de OAuth, repita el Paso 2 para obtener un token nuevo y reinicie Codex desde esa terminal.
Paso 6: úsela desde la aplicación de escritorio
Antes de abrir la aplicación, asegúrese de haber completado el Paso 2, incluyendo esta orden:
launchctl setenv OIC_ACCESS_TOKEN "$OIC_ACCESS_TOKEN"
Si ya tuvo éxito en el Paso 2, no hay necesidad de repetirlo. Cierre por completo la aplicación de escritorio y ábrala de nuevo para que pueda leer el token. Ambos clientes utilizan la misma configuración MCP, pero una variable exportada en solo una sesión de terminal nunca llega por sí sola a la aplicación de escritorio.
Inicie una nueva tarea de Codex y escriba:
/mcp
Verifique que aparezca oic, y luego envíe el mismo mensaje de descubrimiento:
List the tools available from every MCP server with oic in its name.
El Codex debe listar las herramientas de su proyecto OIC.
Cuando expira el token
El token de acceso tiene una vida útil corta, y su duración sigue la configuración IAM de OCI. Para renovar la conexión:
- Vuelva a la terminal de configuración o reintroduzca los valores del Paso 1.
- Repita el Paso 2 para obtener un nuevo token y actualizar el entorno de escritorio.
- Cierre y vuelva a abrir la aplicación de escritorio. Para uso en CLI, inicie una nueva sesión de Codex desde la terminal que contenga el nuevo token.
No es necesario registrar nuevamente al servidor a menos que su configuración haya sido eliminada o modificada.
Notas de solución de problemas
Algunos patrones de fallo aparecen repetidamente con este tipo de configuración:
- Una solicitud de token que falla de inmediato suele significar un ID de cliente, una clave secreta o un ámbito incorrectos, o un valor de dominio de identidad que aún incluye el prefijo o sufijo
https://. - Un token que funciona en la CLI pero no en la aplicación casi siempre significa que el entorno de escritorio no se actualizó, o que la aplicación no se reinició después de la actualización.
- Una lista de herramientas vacía sin errores suele indicar un problema en el lado OIC: el servidor MCP del proyecto no está habilitado o no se ha registrado ninguna integración como herramienta de Agentic AI.
- Los errores de autenticación que aparecen después de un tiempo de funcionamiento normal son muy probablemente causados por un token vencido, así que repita el Paso 2.