Połącz serwer MCP Oracle Integration Cloud z Codexem na macOS
Ustaw kredencje klienta OAuth, pobierz token dostępu, zarejestruj serwer MCP projektu OIC w Codex i upewnij się, że jego narzędzia pojawiają się w CLI oraz aplikacji na komputerze.
Zespoły, które już używają Oracle Integration Cloud (OIC) do łączenia aplikacji, mogą udostępnić odpowiednie integracje w Codex za pośrednictwem Model Context Protocol. Codex następnie odkrywa te integracje jako narzędzia i wykorzystuje je, gdy jest to konieczne do odpowiedzi na pytanie. Integracja, która na przykład wyszukuje zamówienie, może stać się narzędziem używanym przez Codex do odpowiedzi na pytanie dotyczące tego zamówienia, pod warunkiem że integracja jest prawidłowo skonfigurowana i opublikowana.
Tutaj łączymy serwer MCP projektu OIC z Codex na macOS. Musisz uzyskać kilka wartości konfiguracyjnych, poprosić o token dostępu OAuth, zarejestrować serwer i upewnić się, że Codex może widzieć jego narzędzia. Opisano również dodatkowy krok dotyczący środowiska potrzebnego aplikacji desktopowej oraz to, co robić, gdy token się wyczerpie. Zakłada się, że masz dostęp do środowiska OIC oraz że ktoś już przygotował w OCI IAM aplikację OAuth do tego celu.
Współgrające elementy
Bierze w tym udział cztery komponenty:
- Oracle Integration Cloud hostuje integracje, które komunikują się z twoimi aplikacjami i usługami.
- Serwer MCP projektu OIC publikuje integracje zarejestrowane jako narzędzia Agentic AI.
- Codex jest klientem MCP. Znajduje te narzędzia i używa ich w odpowiednich sytuacjach.
Żądanie przemieszcza się w następujący sposób: Codex, potem serwer OIC MCP, następnie zarejestrowana integracja, a w końcu połączone aplikacje.
Zanim Codex może dotrzeć do serwera, prosisz OCI IAM o krótkotrwały token dostępu przy użyciu danych klienta aplikacji OAuth. Ten token jest następnie przekazywany do Codex poprzez zmienną środowiskową.
Wymagania wstępne do spełnienia najpierw
Zakończ konfigurację OIC i tożsamości przed użyciem terminala. Potrzebujesz:
- Projektu OIC z włączoną opcją serwera MCP.
- Jednej lub więcej aktywnych integracji zarejestrowanych jako narzędzia Agentic AI.
- Adres serwera MCP. Otwórz projekt w OIC, kliknij ikonę ołówka (Edytuj) i znajdź pole oznaczone jako „The MCP server runs at”. Jest to długi adres, który łączy host instancji, region oraz identyfikator projektu; krok 1 pokazuje jego pełną postać.
- Aplikacja OAuth poufna OCI IAM skonfigurowana do obsługi uprawnień klienta, z zakresem zasobów OIC obejmującym rolę ServiceInvoker.
- Jego identyfikator klienta, sekret klienta oraz zakres zasobów. W konsoli OCI przejdź do zakładki Identity & Security, następnie do Domains, potem do domeny powiązanej z twoją instancją OIC, dalej do zakładki Integrated Applications i wreszcie do twojej aplikacji poufnej. Identyfikator klienta oraz sekret znajdują się na tej stronie. Wybierz opcję Edit OAuth Configuration i sprawdź w sekcji Token Issuance Policy zakres uprawnień, który powinien zawierać
urn:opc:resource:consumer::all. - Nazwa domeny tożsamości. W konsoli OCI kliknij ikonę profilu w prawym górnym rogu i wybierz „Identity Domain”, aby zobaczyć jej adres URL, który wygląda tak:
https://<identity_domain>.identity.oraclecloud.com. Potrzebna jest tylko część<identity_domain>, bez schematu ani sufiksu. W przypadkuhttps://example123.identity.oraclecloud.comchodzi oexample123. - Zainstalowany Codex, zarówno w wersji CLI, jak i aplikacji na komputerze stacjonarnym.
- Shell zsh w macOS, ponieważ polecenia są napisane specjalnie dla niego.
Jeśli brakuje czegoś z tej listy, napraw to natychmiast. W przeciwnym razie połączenie nie zadziała.
Krok 1: przygotowanie terminala
Otwórz Terminal na swoim Macu. Wszystko poniżej zakłada użycie zsh.
Zrób to:
codex --version
command -v jq
Pierwszy wiersz powinien wyświetlić wersję Codex. Drugi powinien wyświetlić ścieżkę do jq, który jest używany do wydobycia tokena z odpowiedzi autoryzacyjnej.
Jeśli jq nie jest dostępny, a Homebrew jest zainstalowane:
brew install jq
Ustaw swoje wartości
Zamień każdą zastępczą frazę <angle bracket> na swoją własną wartość, a następnie uruchom:
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'
Co oznacza każda zmienna:
OIC_CLIENT_IDto identyfikator klienta Twojej poufnej aplikacji OAuth.OIC_RESOURCE_SCOPEzawiera pełną ścieżkę zakresu skonfigurowaną dla OIC. Zawiera elementurn:opc:resource:consumer::all.OIC_IDENTITY_DOMAINto część przed.identity.oraclecloud.com, na przykładexample123.OIC_MCP_URLto pełna ścieżka URL specyficzna dla projektu, skopiowana z pola „The MCP server runs at”.
Nie umieszczaj tajemnicy klienta w tym bloku. W następnym kroku zostanie ona wymagana za pomocą ukrytego pola wprowadzania danych.
Złap brakujące wartości i pozostałe miejsca zastępcze
Ten blok sprawdza, czy wszystkie cztery zmienne zawierają jakieś dane, a żadna z nich nie ma jeszcze nawiasów skośnych:
(
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
)
Sprawdza jedynie, czy wartości istnieją, a nie czy dane uwierzytelniające, zakres lub adres URL są poprawne. Zachowaj tę sesję terminalową otwartą, ponieważ w następnym kroku zostaną one ponownie wykorzystane.
Krok 2: uzyskanie tokena dostępu OAuth
W tej samej sesji uruchom poniższy blok. Zapyta on o sekret klienta, poprosi o token od OCI IAM i udostępni go narzędziu Codex CLI oraz aplikacjom na komputerze uruchomionym później. Wpisz lub wklej sekret i naciśnij Return. Podczas pisania nic się nie pojawi na ekranie.
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
W przypadku sukcesu wyświetla:
Access token received and set for CLI and newly launched desktop apps.
Ponieważ polecenie nie zawiera żadnych danych, sekret nigdy nie trafia do historii zadań, a skrypt usuwa zmienną z sekretem po zakończeniu żądania tokena.
Potwierdź istnienie tokena
To sprawdzenie informuje o jego obecności, nie wyświetlając przy tym samego tokena:
[[ -n "$OIC_ACCESS_TOKEN" && "$OIC_ACCESS_TOKEN" != 'null' ]] \
&& echo 'OIC access token is present' \
|| echo 'ERROR: OIC access token is missing'
To dowodzi, że zmienna ma wartość. To, czy OIC zaakceptuje token, zostanie ustalone dopiero wtedy, gdy Codex faktycznie nawiąże połączenie z serwerem.
W przypadku aplikacji na komputer stacjonarny należy całkowicie zamknąć Codex i ponownie go otworzyć po tym, jak polecenie launchctl setenv zakończy się sukcesem, aby aplikacja widziała zaktualizowane środowisko.
Traktuj token jako tajemnicę. Nie wyświetlaj go w terminalu, a także nie wklejaj go do czatów, e-maili, zgłoszeń ani dokumentów.
Krok 3: zarejestruj serwer w Codex
Mając token przy sobie, uruchom to w tej samej sesji:
codex mcp add oic \
--url "$OIC_MCP_URL" \
--bearer-token-env-var OIC_ACCESS_TOKEN
To dodaje serwer do Codex pod nazwą oic, używając adresu URL z kroku 1. Dzięki opcji --bearer-token-env-var Codex szuka tokena w zmiennej OIC_ACCESS_TOKEN podczas połączenia. Podaj nazwę tej zmiennej bez znaku dolara, aby przechowywana konfiguracja odnosiła się do właściwej zmiennej, a nie do aktualnej wartości tokena.
Krok 4: sprawdzenie konfiguracji
Wylistuj skonfigurowane serwery i przyjrzyj się nowemu:
codex mcp list
codex mcp get oic
Upewnij się, że:
- serwer nazywa się
oici jest włączony; - adres URL odpowiada punktowi końcowemu MCP twojego projektu OIC;
- transport to
streamable_http; - zmienna bearer-token to
OIC_ACCESS_TOKEN.
Jeśli serwer nie istnieje, jest wyłączony lub skierowany na niewłaściwy adres URL, napraw to przed kontynuowaniem.
Krok 5: znalezienie narzędzi z CLI
Zapuść Codex z terminala, z którego został eksportowany OIC_ACCESS_TOKEN, aby narzędzie odziedziczyło ten token:
codex
Gdy się otworzy, wpisz następującą komendę:
List the tools available from every MCP server with oic in its name.
Powinieneś zobaczyć listę narzędzi dostępnych w twoim projekcie OIC. Jeśli lista jest pusta, wróć do OIC i sprawdź, czy aktywna integracja w projekcie jest zarejestrowana jako narzędzie Agentic AI. Jeśli Codex skarży się na problemy z autoryzacją, sprawdź ponownie ustawienia OAuth, powtórz krok 2, aby uzyskać nowy token, i uruchom ponownie Codex z tego terminala.
Krok 6: użycie w aplikacji na komputerze
Zanim otworzysz aplikację, upewnij się, że krok 2 został wykonany, w tym z użyciem tego polecenia:
launchctl setenv OIC_ACCESS_TOKEN "$OIC_ACCESS_TOKEN"
Jeśli już się udało to w kroku 2, nie ma potrzeby powtarzania tego procesu. Zamknij całkowicie aplikację na pulpicie i uruchom ją ponownie, aby mogła odczytać token. Obie aplikacje korzystają z tej samej konfiguracji MCP, jednak zmienna eksportowana tylko w jednej sesji terminala sama w sobie nigdy nie trafia do aplikacji na pulpicie.
Rozpocznij nowe zadanie w Codex i wpisz:
/mcp
Sprawdź, czy pojawia się oic, a następnie wyślij to samo zapytanie o odkrycie:
List the tools available from every MCP server with oic in its name.
Kodeks powinien wymieniać narzędzia z Twojego projektu OIC.
Gdy token wygasa
Token dostępu ma krótki okres ważności, a jego czas trwania zależy od ustawień OCI IAM. Aby odnowić połączenie:
- Wróć do terminala konfiguracyjnego lub wprowadź ponownie wartości z kroku 1.
- Powtórz krok 2, aby otrzymać nowy token i zaktualizować środowisko biurkowe.
- Zamknij i ponownie otwórz aplikację biurkową. Do używania w CLI uruchom nową sesję Codex z terminala, który zawiera nowy token.
Serwer nie musi być ponownie rejestrowany, chyba że jego konfiguracja została usunięta lub zmieniona.
Uwagi dotyczące rozwiązywania problemów
Podczas takiej konfiguracji często występują pewne wzorce błędów:
- Błąd w żądaniu tokena, który pojawia się natychmiastowo, zazwyczaj oznacza błędny identyfikator klienta, hasło lub zakres, albo wartość domeny tożsamości, która nadal zawiera przedrostek lub sufiks
https://. - Język programowania, który działa w interfejsie linii poleceń, ale nie w aplikacji, prawie zawsze oznacza, że środowisko biurowe nie zostało zaktualizowane lub aplikacja nie została ponownie uruchomiona po aktualizacji.
- Pusta lista narzędzi bez błędów zazwyczaj wskazuje na problem po stronie OIC: serwer MCP projektu nie jest włączony lub żadna integracja nie została zarejestrowana jako narzędzie Agentic AI.
- Błędy autoryzacji, które pojawiają się po pewnym czasie normalnej pracy, najprawdopodobniej wynikają z wygasłego języka programowania, więc należy powtórzyć krok 2.