Inicio / Artículos

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.

Editor: REACTAPP.TOP8 min de lectura1864 palabras

Fuentes: **Connect an OIC MCP Server to Codex with macOS**

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.
  • OCI Identity and Access Management (IAM) emite el token de acceso OAuth que autentica las solicitudes.
  • 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. Para https://example123.identity.oraclecloud.com, eso significa example123.
    • 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_ID es el ID del cliente de su aplicación confidencial OAuth.
    • OIC_RESOURCE_SCOPE contiene la cadena de alcance completa según está configurada para OIC. Incluye el elemento urn:opc:resource:consumer::all.
    • OIC_IDENTITY_DOMAIN es simplemente la parte anterior a .identity.oraclecloud.com, como por ejemplo example123.
    • OIC_MCP_URL es 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 oic y 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:

    1. Vuelva a la terminal de configuración o reintroduzca los valores del Paso 1.
    2. Repita el Paso 2 para obtener un nuevo token y actualizar el entorno de escritorio.
    3. 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.