Подключите сервер MCP Oracle Integration Cloud к Codex на macOS
Настройте учетные данные клиента OAuth, получите токен доступа, зарегистрируйте сервер MCP проекта OIC в Codex и убедитесь, что его инструменты отображаются в CLI и десктопном приложении.
Источники: **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. Он находит эти инструменты и использует их по мере необходимости.
Запрос передается следующим образом: сначала в 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.
- Повторите шаг 2, чтобы получить новый токен и обновить среду рабочего стола.
- Закройте и снова откройте приложение для рабочего стола. Для использования в командной строке запустите новую сессию Codex из терминала, в котором находится новый токен.
Сервер не требуется заново регистрировать, если его конфигурация не была удалена или изменена.
Заметки по устранению неполадок
При такой настройке часто возникают определенные типы сбоев:
- Сразу же происходящая ошибка при запросе токена обычно означает неверный клиентский ID, секрет или диапазон полномочий, либо значение домена идентичности, в котором все еще присутствует префикс или суффикс
https://.