Головна / Статті

Під’єднайте сервер 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) для з’єднання додатків, можуть зробити відповідні інтеграції доступними для 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. Він знаходить інструменти та використовує їх за потреби.
  • OCI Identity and Access Management (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-адреса, специфічна для проекту, скопійована з поля „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. Поверніться до терміналу налаштувань або знову введіть значення з Кроку 1.
    2. Повторіть Крок 2, щоб отримати новий токен та оновити середовище робочого столу.
    3. Закрийте та знову відкрийте додаток робочого столу. Для використання через CLI запустіть нову сесію Codex з терміналу, у якому зберігається новий токен.

    Сервера не потрібно знову реєструвати, якщо його конфігурація не була видалена чи змінена.

    Примітки щодо усунення проблем

    Під час такої налаштування постійно трапляються певні типи помилок:

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