Strona główna / Artykuły

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.

Wydawca: REACTAPP.TOP8 min czytania1864 słów

Źródła: **Connect an OIC MCP Server to Codex with macOS**

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.
  • OCI Identity and Access Management (IAM) wydaje token dostępu OAuth, który uwierzytelnia żądania.
  • Żą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 przypadku https://example123.identity.oraclecloud.com chodzi o example123.
    • 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_ID to identyfikator klienta Twojej poufnej aplikacji OAuth.
    • OIC_RESOURCE_SCOPE zawiera pełną ścieżkę zakresu skonfigurowaną dla OIC. Zawiera element urn:opc:resource:consumer::all.
    • OIC_IDENTITY_DOMAIN to część przed .identity.oraclecloud.com, na przykład example123.
    • OIC_MCP_URL to 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ę oic i 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:

    1. Wróć do terminala konfiguracyjnego lub wprowadź ponownie wartości z kroku 1.
    2. Powtórz krok 2, aby otrzymać nowy token i zaktualizować środowisko biurkowe.
    3. 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.