Главная / Статьи

Подключите сервер MCP Oracle Integration Cloud к Codex на macOS

Настройте учетные данные клиента OAuth, получите токен доступа, зарегистрируйте сервер MCP проекта OIC в Codex и убедитесь, что его инструменты отображаются в CLI и десктопном приложении.

Издатель: REACTAPP.TOP8 мин чтения1864 слов

Источники: **Connect an OIC MCP Server to Codex with macOS**

Команды, которые уже используют Oracle Integration Cloud (OIC) для связи приложений, могут с помощью протокола Model Context Protocol сделать соответствующие интеграции доступными в Codex. Codex затем обнаруживает эти интеграции в качестве инструментов и вызывает их при необходимости. Например, интеграция, предназначенная для поиска информации о заказе, может стать инструментом, который использует Codex для ответа на вопросы об этом заказе, при условии, что она правильно настроена и опубликована.

Здесь мы подключаем сервер MCP проекта OIC к Codex на macOS. Необходимо собрать несколько значений конфигурации, запросить токен доступа OAuth, зарегистрировать сервер и убедиться, что Codex может видеть его инструменты. Также рассматривается дополнительный шаг настройки среды, необходимый десктопному приложению, и действия, которые следует предпринять при истечении срока действия токена. Предполагается, что у вас уже есть доступ к среде OIC и что кто-то уже подготовил приложение OAuth в OCI IAM для этой цели.

Участвующие компоненты

В процессе участвуют четыре компонента:

  • Oracle Integration Cloud хранит интеграции, которые взаимодействуют с вашими приложениями и сервисами.
  • Сервер MCP проекта OIC публикует интеграции, зарегистрированные как инструменты Agentic AI.
  • Codex является клиентом MCP. Он находит эти инструменты и использует их по мере необходимости.
  • Система управления идентичностями и доступом OCI IAM выдает токен доступа OAuth, который аутентифицирует запросы.
  • Запрос передается следующим образом: сначала в Codex, затем на сервер OIC MCP, далее к зарегистрированной интеграции и, наконец, к подключенному приложению.

    Прежде чем Codex сможет связаться с сервером, вы запрашиваете у OCI IAM временный токен доступа с использованием учетных данных клиента приложения OAuth. Этот токен затем передается Codex через переменную окружения.

    Предварительные требования

    Сначала завершите настройку OIC и идентичностей, прежде чем приступать к работе с терминалом. Вам понадобится:

    • Проект OIC с включенной опцией сервера MCP.
    • Хотя бы одна активная интеграция, зарегистрированная как инструмент Agentic AI.
    • URL сервера MCP. Откройте проект в OIC, нажмите иконку карандаша (Редактировать) и найдите поле с надписью «The MCP server runs at». Это длинный адрес, в котором сочетаются хост вашей инстанции, регион и идентификатор проекта; на шаге 1 показано его полное составление.
    • Конфиденциальное приложение OAuth IAM OCI, настроенное для использования клиентских учетных данных, с диапазоном ресурсов OIC, предоставляющим роль ServiceInvoker.
    • Клиентский ID, клиентский секрет и диапазон ресурсов. В консоли OCI перейдите в раздел Identity & Security, затем в Domains, выберите домен, связанный с вашей инстанцией OIC, затем — Integrated Applications и, наконец, ваше конфиденциальное приложение. Клиентский ID и секрет находятся на этой странице. Выберите опцию Edit OAuth Configuration и в разделе Token Issuance Policy найдите диапазон ресурсов, включающий urn:opc:resource:consumer::all.
    • Имя домена идентификатора. В консоли OCI нажмите иконку профиля в верхнем правом углу и выберите «Identity Domain», чтобы увидеть его URL вида https://<identity_domain>.identity.oraclecloud.com. Вам понадобится только часть <identity_domain>, без протокола и суффикса. Для https://example123.identity.oraclecloud.com это означает example123.
    • Установленный Codex — либо через CLI, либо через приложение для рабочего стола.
    • Шелл zsh для macOS, поскольку команды написаны для него.

    Если что-то из этого списка отсутствует, устраните проблему немедленно. В противном случае подключение не сработает.

    Шаг 1: подготовка терминала

    Откройте Terminal на своем Mac. Все дальнейшие действия предполагают использование zsh.

    Проверка наличия Codex и jq

    Запустите:

    codex --version
    command -v jq
    

    В первой строке должна быть выведена версия Codex. Во второй — путь к jq, который используется для извлечения токена из ответа аутентификации.

    Если jq отсутствует, но установлен Homebrew:

    brew install jq
    

    Установите свои значения

    Замените каждый заместитель <angle bracket> на своё собственное значение, затем запустите:

    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'
    

    Что означает каждая переменная:

    • OIC_CLIENT_ID — это идентификатор клиента вашего конфиденциального приложения OAuth.
    • OIC_RESOURCE_SCOPE содержит полную строку диапазона, настроенную для OIC; в ней присутствует элемент urn:opc:resource:consumer::all.
    • OIC_IDENTITY_DOMAIN — это часть текста, предшествующая .identity.oraclecloud.com, например example123.
    • OIC_MCP_URL — это полный URL проекта, скопированный из поля «Адрес сервера MCP».

    Не включайте секрет клиента в этот блок; на следующем шаге он будет запрашиваться с помощью скрытого поля ввода.

    Обнаружение отсутствующих значений и оставшихся маркеров

    Этот блок проверяет, что все четыре переменные содержат данные и что ни в одной из них больше нет угловых скобок:

    (
      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
    )
    

    Он проверяет лишь наличие значений, но не правильность учетных данных, диапазона полномочий или URL. Оставьте эту сессию терминала открытой, поскольку на следующем этапе будут использоваться эти переменные.

    Шаг 2: получение токена доступа OAuth

    В той же сессии запустите приведенный ниже блок кода. Он запрашивает секрет клиента, получает токен от OCI IAM и делает его доступным для Codex CLI и для приложений на рабочем столе, запущенных позже. Введите или вставьте секрет и нажмите Return. На экране ничего не появится во время ввода.

    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
    

    При успешном выполнении выводится:

    Access token received and set for CLI and newly launched desktop apps.
    

    Поскольку запрос остаётся без ответа, секретный код никогда не попадает в историю команд, а скрипт удаляет переменную с секретным кодом сразу после завершения запроса токена.

    Подтвердите наличие токена

    Эта проверка сообщает о наличии токена, но при этом никогда не выводит его содержимое:

    [[ -n "$OIC_ACCESS_TOKEN" && "$OIC_ACCESS_TOKEN" != 'null' ]] \
      && echo 'OIC access token is present' \
      || echo 'ERROR: OIC access token is missing'
    

    Это доказывает, что у переменной есть значение. Вопрос о том, примет ли OIC токен, будет решен только тогда, когда Codex фактически свяжется с сервером.

    Для десктопного приложения полностью закройте Codex и снова откройте его после того, как команда launchctl setenv выполнится успешно, чтобы приложение увидело обновленную среду.

    Считайте токен секретной информацией. Не выводите его в терминал и не вставляйте в чаты, электронную почту, заявки или документы.

    Шаг 3: регистрация сервера в Codex

    Имея токен, выполните следующую команду в той же сессии:

    codex mcp add oic \
      --url "$OIC_MCP_URL" \
      --bearer-token-env-var OIC_ACCESS_TOKEN
    

    Это добавляет сервер в Codex под именем oic с использованием URL из шага 1. С помощью параметра --bearer-token-env-var Codex при подключении ищет токен в переменной OIC_ACCESS_TOKEN. Укажите имя переменной без знака доллара, чтобы сохранённая конфигурация ссылалась на переменную, а не на значение токена текущего дня.

    Шаг 4: проверка конфигурации

    Списайте настроенные серверы и изучите новый из них:

    codex mcp list
    codex mcp get oic
    

    Убедитесь, что:

    • сервер называется oic и включен;
    • URL совпадает с конечной точкой MCP вашего проекта OIC;
    • тип передачи данных — streamable_http;
    • значение переменной bearer-token — OIC_ACCESS_TOKEN.

    Если сервер отсутствует, отключен или настроен на неверный URL, исправьте это перед продолжением.

    Шаг 5: поиск инструментов через CLI

    Запустите Codex из терминала, где был экспортирован OIC_ACCESS_TOKEN, чтобы он унаследовал этот токен:

    codex
    

    Когда он откроется, введите следующую команду:

    List the tools available from every MCP server with oic in its name.
    

    Вы должны увидеть список инструментов, предоставляемых вашим проектом OIC. Если список пуст, вернитесь в OIC и убедитесь, что активная интеграция в проекте зарегистрирована как инструмент Agentic AI. Если Codex сообщает об ошибках аутентификации, перепроверьте настройки OAuth, выполните шаг 2 для получения нового токена и запустите Codex заново из этой терминалы.

    Шаг 6: использование из десктопного приложения

    Перед открытием приложения убедитесь, что выполнен шаг 2, включая выполнение этой команды:

    launchctl setenv OIC_ACCESS_TOKEN "$OIC_ACCESS_TOKEN"
    

    Если на втором шаге операция уже прошла успешно, нет необходимости повторять её. Полностью закройте приложение для рабочего стола и запустите его заново, чтобы оно могло прочитать токен. Оба клиента используют одну и ту же конфигурацию MCP, однако переменная, экспортированная только в одной сессии терминала, сама по себе никогда не попадает в приложение для рабочего стола.

    Запустите новое задание Codex и введите:

    /mcp
    

    Проверьте, что появляется oic, затем отправьте тот же запрос на обнаружение:

    List the tools available from every MCP server with oic in its name.
    

    В кодексе должен быть перечислен список инструментов из вашего проекта OIC.

    Когда истекает токен

    Токен доступа имеет короткий срок действия, и его продолжительность определяется настройками IAM OCI. Чтобы обновить подключение:

    1. Вернитесь в терминал настройки или введите снова значения из шага 1.
    2. Повторите шаг 2, чтобы получить новый токен и обновить среду рабочего стола.
    3. Закройте и снова откройте приложение для рабочего стола. Для использования в командной строке запустите новую сессию Codex из терминала, в котором находится новый токен.

    Сервер не требуется заново регистрировать, если его конфигурация не была удалена или изменена.

    Заметки по устранению неполадок

    При такой настройке часто возникают определенные типы сбоев:

    • Сразу же происходящая ошибка при запросе токена обычно означает неверный клиентский ID, секрет или диапазон полномочий, либо значение домена идентичности, в котором все еще присутствует префикс или суффикс https://.
  • Токен, который работает в CLI, но не в приложении, почти всегда означает, что среда рабочего стола не была обновлена или приложение не было перезапущено после обновления.
  • Пустой список инструментов без ошибок обычно указывает на проблемы с стороны OIC: сервер MCP проекта не включен или никакая интеграция не зарегистрирована как инструмент Agentic AI.
  • Ошибки аутентификации, появляющиеся спустя некоторое время нормальной работы, скорее всего, связаны с истекшим токеном, поэтому повторите шаг 2.