Падключэнне MCP-сервера Oracle Integration Cloud да Codex на macOS
Наладжваем OAuth client credentials, атрымліваем токен доступу, рэгіструем 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— гэта 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.
- Павтарыце Крок 2, ўбачыце новы токен і апдэйтаваце серэдовішча рабочага столу.
- Закрыце і зноў ачыніце додаток на рабочым столу. Для вікорыстання праз CLI запускайце новую сесію Кодэкса з тэрміналу, у яком знаходзіцца новы токен.
Сервера не патрэбна занова рэўістрацыя, як толькі яго налаштаванні не былі адмёненыя чы змененыя.
Прыміткі па адлагоджэнню проблем
Пры такім тыпе налаштавання часта з’яўляюцца певныя фарматы аберанняў:
- Абэранне запіту на токен, якое відбываецца адразу, зазвычай означае некарэктны ID кліента, секрэт чы дыяпазон, або значэнне домэна ідэнтычнасці, якое ўсё шчэ мае прыфікс чы суфікс
https://.