Галоўная / Артыкулы

Падключэнне MCP-сервера Oracle Integration Cloud да Codex на macOS

Наладжваем OAuth client credentials, атрымліваем токен доступу, рэгіструем 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 (IAM) выдае токен доступу OAuth, які аўтэнтыфікуе запіты.
  • Запіт праходзіць так: Codex, пасля чаго — сервер OIC MCP, потым зарэгістраваная інтэграцыя, а ўжо пасля — падключаное застосунак.

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

    Прыямыя прычынкі, якія трэба спачатку вырашыць

    Заканчыце налаштаванне OIC і ідэнтычнасцяў пры першай працы з тэрміналам. Вам патрабуецца:

    • Праект OIC з увімкнутай опцыяй сервера MCP.
    • Хоць адна актыўная інтэграцыя, зарэгістраваная як інструмент Agentic AI.
  • Адрэса сервера MCP. Ачыніце праект у OIC, нажміце на іконку олівца (Рэдагаваць) і знайдзіце полье пад назвай «The MCP server runs at». Цэта дзялёга адрэса, якая ўключае хост вашай інстанцы, рэгіон і ідэнтыфікатор праекту; на 1-м кроце паказана ўся ёя структура.
  • Конфідэнцыйны аплікатыў OAuth для працы з крантальскімі дакументамі, налаштаваны ў OCI IAM, з дыяпазонам рэсурсаў 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 чы прыстроевая аплікацыя.
  • Shell 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 — гэта 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 і пераканайцеся, што актыўная інтэграцыя ў праекце зарэjestрована як адзінак 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.
    

    У Кодэксе павінны быць пераказаны інструменты з вашага праекту OIC.

    Кал заканчываецца токен

    Токен доступу мае короткі тэрмін дзейнасці, і ўсе залежыць ад налашоўках IAM у вашай сістэме OCI. Чырагчы з’ѐеднанне:

    1. Верніцеся да тэрміналу налаштавання або зноў увядзіце значэнні з Кроку 1.
    2. Павтарыце Крок 2, ўбачыце новы токен і апдэйтаваце серэдовішча рабочага столу.
    3. Закрыце і зноў ачыніце додаток на рабочым столу. Для вікорыстання праз CLI запускайце новую сесію Кодэкса з тэрміналу, у яком знаходзіцца новы токен.

    Сервера не патрэбна занова рэўістрацыя, як толькі яго налаштаванні не былі адмёненыя чы змененыя.

    Прыміткі па адлагоджэнню проблем

    Пры такім тыпе налаштавання часта з’яўляюцца певныя фарматы аберанняў:

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