Під’єднайте сервер MCP Oracle Integration Cloud до Codex на macOS
Налаштуйте облікові дані клієнта OAuth, отримайте токен доступу, зареєструйте сервер MCP проекту OIC у Codex та переконайтеся, що його інструменти з’являються у CLI та десктопному додатку.
Команди, які вже використовують Oracle Integration Cloud (OIC) для з’єднання додатків, можуть зробити відповідні інтеграції доступними для Codex через Model Context Protocol. 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.
urn:opc:resource:consumer::all.https://<identity_domain>.identity.oraclecloud.com. Вам потрібна лише частина <identity_domain>, без протоколу та суфікса. Для https://example123.identity.oraclecloud.com це означає example123.Якщо щось із цього списку відсутнє, вирішіть це проблему негайно. Інакше підключення не спрацює.
Крок 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-адреса, специфічна для проекту, скопійована з поля „The MCP server runs at“.
Не включайте таємний ключ клієнта до цього блоку. Наступний крок вимагатиме його через приховане поле введення.
Виявлення відсутніх значень та залишкових місць для заповнення
Цей блок перевіряє, чи всі чотири змінні містять якісь дані, і чи немає серед них елементів у форматі кутових дужок:
(
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"
Якщо це вже вдалося на кроці 2, немає потреби повторювати це. Повністю закрийте десктопний додаток та запустіть його знову, щоб він міг прочитати токен. Обидва клієнти використовують однакову конфігурацію MCP, проте змінна, експортована лише в одній сесії терміналу, сама по собі ніколи не потрапляє до десктопного додатку.
Запустіть нове завдання Codex та введіть:
/mcp
Перевірте, чи з’являється oic, а потім надішліть ту саму запитання для виявлення:
List the tools available from every MCP server with oic in its name.
У Codex має бути перелік інструментів з вашого проекту OIC.
Коли токен закінчується термін дії
Токен доступу має короткий термін дії, і його тривалість визначається налаштуваннями OCI IAM. Щоб оновити з’єднання:
- Поверніться до терміналу налаштувань або знову введіть значення з Кроку 1.
- Повторіть Крок 2, щоб отримати новий токен та оновити середовище робочого столу.
- Закрийте та знову відкрийте додаток робочого столу. Для використання через CLI запустіть нову сесію Codex з терміналу, у якому зберігається новий токен.
Сервера не потрібно знову реєструвати, якщо його конфігурація не була видалена чи змінена.
Примітки щодо усунення проблем
Під час такої налаштування постійно трапляються певні типи помилок:
- Помилка у запиті на токен, яка виникає миттєво, зазвичай означає неправильний ID клієнта, секрет чи область дії, або значення домену ідентичності, яке все ще містить префікс чи суфікс
https://.