Startseite / Artikel

Verbinden Sie einen Oracle Integration Cloud MCP-Server mit Codex unter macOS.

Richten Sie die OAuth-Klientenanmeldeinformationen ein, holen Sie sich einen Zugriffstoken, registrieren Sie den MCP-Server eines OIC-Projekts in Codex und überprüfen Sie, ob seine Tools in der CLI sowie der Desktop-App angezeigt werden.

Verlag: REACTAPP.TOP8 Min. Lesezeit1864 Wörter

Quellen: **Connect an OIC MCP Server to Codex with macOS**

Teams, die bereits Oracle Integration Cloud (OIC) nutzen, um Anwendungen miteinander zu verbinden, können über das Model Context Protocol geeignete Integrationen an Codex bereitstellen. Codex entdeckt anschließend diese Integrationen als Tools und ruft sie auf, wenn eine Frage ihre Hilfe benötigt. Eine Integration, die beispielsweise eine Bestellung abruft, kann zu einem Tool werden, das Codex verwendet, um eine Frage zu dieser Bestellung zu beantworten – vorausgesetzt, die Integration ist ordnungsgemäß eingerichtet und veröffentlicht worden.

Hier verbinden wir den MCP-Server eines OIC-Projekts mit Codex unter macOS. Sie sammeln einige Konfigurationswerte ein, beantragen einen OAuth-Zugriffstoken, registrieren den Server und stellen sicher, dass Codex seine Tools sehen kann. Es wird auch der zusätzliche Schritt für die Umgebung erläutert, den die Desktop-App benötigt, sowie was zu tun ist, wenn der Token ausgeht. Vorausgesetzt wird, dass Ihnen eine OIC-Umgebung zur Verfügung steht und jemand bereits eine OAuth-Anwendung in OCI IAM zu diesem Zweck vorbereitet hat.

Beteiligte Komponenten

Vier Komponenten sind beteiligt:

  • Oracle Integration Cloud hostet die Integrationen, die mit Ihren Anwendungen und Diensten kommunizieren.
  • Der MCP-Server des OIC-Projekts veröffentlicht Integrationen, die als Agentic AI-Tools registriert sind.
  • Codex ist der MCP-Klient. Er findet die Tools und verwendet sie bei Bedarf.
  • OCI Identity and Access Management (IAM) stellt das OAuth-Zugriffstoken aus, mit dem Anfragen authentifiziert werden.
  • Eine Anfrage verläuft wie folgt: Codex, anschließend der OIC MCP-Server, dann die registrierte Integration und schließlich die verbundene Anwendung.

    Bevor Codex den Server erreichen kann, beantragen Sie bei OCI IAM ein kurzlebiges Zugriffstoken unter Verwendung der Client-Zertifikate der OAuth-Anwendung. Dieses Token wird anschließend über eine Umgebungsvariable an Codex weitergegeben.

    Voraussetzungen, die zuerst erfüllt werden müssen

    Fertigen Sie die OIC- und Identitätskonfiguration ab, bevor Sie den Terminal verwenden. Sie benötigen:

    • Ein OIC-Projekt mit der MCP-Server-Option aktiviert.
    • Zumindest eine aktive Integration, die als Agentic AI-Tool registriert ist.
    • Die URL des MCP-Servers. Öffnen Sie das Projekt in OIC, klicken Sie auf das Bleistift-(Bearbeiten)-Icon und suchen Sie nach dem Feld mit der Bezeichnung „The MCP server runs at“. Es handelt sich um eine lange Adresse, die Ihren Instanz-Host, die Region sowie den Projektidentifikator kombiniert; Schritt 1 zeigt ihre vollständige Form.
    • Eine für Client-Zertifikate konfigurierte vertrauliche OAuth-Anwendung von OCI IAM mit dem OIC-Ressourcenumfang, der die Rolle ServiceInvoker enthält.
    • Ihre Client-ID, Client-Geheimzahl sowie der Ressourcenumfang. Gehen Sie in der OCI-Konsole zu Identity & Security, anschließend zu Domains, dann zum mit Ihrer OIC-Instanz verknüpften Domain, danach zu Integrated Applications und schließlich zu Ihrer vertraulichen Anwendung. Die Client-ID und das Geheimnis befinden sich auf dieser Seite. Wählen Sie „Edit OAuth Configuration“ aus und suchen Sie unter Token Issuance Policy nach dem Umfang, der urn:opc:resource:consumer::all enthält.
    • Der Domainname der Identität. Klicken Sie in der OCI-Konsole auf das Profilicon oben rechts und wählen Sie „Identity Domain“, um die URL anzusehen, die wie https://<identity_domain>.identity.oraclecloud.com aussieht. Sie benötigen nur den Teil <identity_domain>, ohne Protokoll oder Suffix. Für https://example123.identity.oraclecloud.com bedeutet das example123.
    • Codex, entweder die CLI oder die Desktop-App, muss installiert sein.
    • Eine macOS zsh-Shell, da die Befehle dafür geschrieben sind.

    Falls etwas auf dieser Liste fehlt, kümmern Sie sich bitte sofort darum. Andernfalls wird die Verbindung nicht funktionieren.

    Schritt 1: Terminal vorbereiten

    Öffnen Sie das Terminal auf Ihrem Mac. Alles, was weiter unten steht, setzt voraus, dass zsh verwendet wird.

    Codex und jq überprüfen

    Führen Sie aus:

    codex --version
    command -v jq
    

    Die erste Zeile sollte die Codex-Version ausgeben. Die zweite sollte den Pfad zu jq anzeigen, das verwendet wird, um den Token aus der Authentifizierungsantwort abzurufen.

    Falls jq fehlt und Homebrew installiert ist:

    brew install jq
    

    Setzen Sie Ihre Werte

    Ersetzen Sie jeden <Anglebracket>-Platzhalter durch Ihren eigenen Wert und führen Sie anschließend aus:

    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'
    

    Was jede Variable bedeutet:

    • OIC_CLIENT_ID ist die Client-ID Ihrer OAuth-Vertrauensanwendung.
    • OIC_RESOURCE_SCOPE enthält den vollständigen Scope-String, wie er für OIC konfiguriert ist. Er beinhaltet das Element urn:opc:resource:consumer::all.
    • OIC_IDENTITY_DOMAIN ist einfach der Teil vor .identity.oraclecloud.com, wie z. B. example123.
    • OIC_MCP_URL ist die vollständige, projektbezogene URL, die aus dem Feld „Der MCP-Server läuft unter“ kopiert wurde.

    Lassen Sie das Client-Secret außerhalb dieses Blocks. Im nächsten Schritt wird es über ein verstecktes Eingabefeld abgefragt.

    Fehlende Werte und verbleibende Platzhalter erkennen

    Dieser Block überprüft, ob alle vier Variablen einen Inhalt enthalten und keine noch Schrägstriche aufweisen:

    (
      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
    )
    

    Es überprüft lediglich, ob die Werte vorhanden sind, nicht jedoch, ob die Anmeldeinformationen, der Umfang oder die URL korrekt sind. Lassen Sie diese Terminal-Sitzung geöffnet, da im nächsten Schritt diese Variablen wiederverwendet werden.

    Schritt 2: Ein OAuth-Zugriffstoken erhalten

    Führen Sie in derselben Sitzung den untenstehenden Block aus. Er fragt nach dem Client-Secret, beantragt ein Token bei OCI IAM und stellt es der Codex CLI sowie den danach gestarteten Desktop-Apps zur Verfügung. Geben Sie den Secret ein oder kopieren Sie ihn ein und drücken Sie Return. Während des Eingabevorgangs wird nichts auf dem Bildschirm angezeigt.

    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
    

    Bei Erfolg gibt es aus:

    Access token received and set for CLI and newly launched desktop apps.
    

    Weil die Anfrage stumm ist, gelangt das Geheimnis niemals in Ihre Shell-Historie, und die Skript löscht die Geheimnisvariable, sobald die Token-Anfrage abgeschlossen ist.

    Überprüfen Sie, ob das Token existiert

    Diese Überprüfung meldet die Existenz, ohne das Token jemals auszugeben:

    [[ -n "$OIC_ACCESS_TOKEN" && "$OIC_ACCESS_TOKEN" != 'null' ]] \
      && echo 'OIC access token is present' \
      || echo 'ERROR: OIC access token is missing'
    

    Dies beweist, dass die Variable einen Wert hat. Ob OIC das Token akzeptiert, wird erst geklärt, wenn Codex tatsächlich mit dem Server kommuniziert.

    Für die Desktop-App sollten Sie Codex vollständig beenden und es nach erfolgreichem Ausführen von launchctl setenv erneut öffnen, damit es die aktualisierte Umgebung wahrnimmt.

    Betrachten Sie das Token als Geheimnis. Spiegeln Sie es nicht in der Konsole wider und fügen Sie es auch nicht in Chats, E-Mails, Tickets oder Dokumente ein.

    Schritt 3: Den Server in Codex registrieren

    Mit dem Token in der Hand führen Sie dies in derselben Sitzung aus:

    codex mcp add oic \
      --url "$OIC_MCP_URL" \
      --bearer-token-env-var OIC_ACCESS_TOKEN
    

    Dadurch wird der Server unter dem Namen oic im Codex unter Verwendung der URL aus Schritt 1 hinzugefügt. Mit --bearer-token-env-var sucht Codex beim Verbinden nach dem Token in der Variablen OIC_ACCESS_TOKEN. Geben Sie den Namen der Variablen ohne Dollarzeichen an, damit die gespeicherte Konfiguration auf die Variable verweist und nicht den aktuellen Token-Wert enthält.

    Schritt 4: Konfiguration überprüfen

    Listen Sie die konfigurierten Server auf und prüfen Sie den neuen:

    codex mcp list
    codex mcp get oic
    

    Stellen Sie sicher, dass:

    • der Server oic heißt und aktiviert ist;
    • die URL mit dem MCP-Endpunkt Ihres OIC-Projekts übereinstimmt;
    • der Transportmodus streamable_http ist;
    • die Variable für den Token OIC_ACCESS_TOKEN lautet.

    Falls der Server fehlt, deaktiviert ist oder auf die falsche URL ausgerichtet ist, beheben Sie das vor dem Weitermachen.

    Schritt 5: Tools über die CLI finden

    Starten Sie Codex aus dem Terminal, in dem OIC_ACCESS_TOKEN exportiert wurde, damit es den Token erbt:

    codex
    

    Wenn es geöffnet wird, geben Sie diesen Befehl ein:

    List the tools available from every MCP server with oic in its name.
    

    Sie sollten eine Liste der von Ihrem OIC-Projekt bereitgestellten Tools sehen. Falls die Liste leer ist, kehren Sie zu OIC zurück und überprüfen Sie, ob eine aktive Integration im Projekt als Agentic AI-Tool registriert ist. Wenn Codex stattdessen Probleme mit der Authentifizierung hat, überprüfen Sie erneut die OAuth-Einstellungen, wiederholen Sie Schritt 2, um einen neuen Token zu erhalten, und starten Sie Codex von diesem Terminal aus neu.

    Schritt 6: Verwendung über die Desktop-App

    Vor dem Öffnen der App stellen Sie sicher, dass Schritt 2 abgeschlossen ist, einschließlich dieses Befehls:

    launchctl setenv OIC_ACCESS_TOKEN "$OIC_ACCESS_TOKEN"
    

    Falls es bereits in Schritt 2 erfolgreich war, gibt es keinen Grund, dies zu wiederholen. Beenden Sie die Desktop-App vollständig und starten Sie sie erneut, damit sie den Token lesen kann. Beide Clients verwenden dieselbe MCP-Konfiguration, doch eine in nur einer Terminal-Sitzung exportierte Variable erreicht die Desktop-App von selbst niemals.

    Starten Sie eine neue Codex-Aufgabe und geben Sie ein:

    /mcp
    

    Überprüfen Sie, ob oic angezeigt wird, und senden Sie anschließend dieselbe Entdeckungsanfrage:

    List the tools available from every MCP server with oic in its name.
    

    Der Codex sollte die Tools aus Ihrem OIC-Projekt auflisten.

    Wenn das Token abläuft

    Das Zugriffstoken hat eine kurze Gültigkeitsdauer und folgt den Einstellungen Ihres OCI IAM. Um die Verbindung zu erneuern:

    1. Gehen Sie zurück zum Konfigurationsterminal oder geben Sie die Werte aus Schritt 1 erneut ein.
    2. Wiederholen Sie Schritt 2, um ein neues Token zu erhalten und die Desktop-Umgebung zu aktualisieren.
    3. Beenden und erneut öffnen Sie die Desktop-App. Für die Verwendung über die CLI starten Sie eine neue Codex-Sitzung vom Terminal aus, das das neue Token enthält.

    Der Server muss nicht erneut registriert werden, es sei denn, seine Konfiguration wurde entfernt oder geändert.

    Hinweise zur Fehlerbehebung

    Mit dieser Art der Konfiguration treten immer wieder einige Fehlermuster auf:

    • Eine sofort fehlgeschlagene Tokenanfrage bedeutet in der Regel einen falschen Client-ID-, Secret- oder Scope-Wert oder einen Identitätsdomänennamen, der noch das Präfix oder Suffix https:// enthält.
    • Ein Token, das in der CLI funktioniert, aber nicht in der Anwendung, bedeutet fast immer, dass die Desktop-Umgebung nicht aktualisiert wurde oder die Anwendung nach der Aktualisierung nicht neu gestartet wurde.
    • Eine leere Tool-Liste ohne Fehler weist in der Regel auf die OIC-Seite hin: Der MCP-Server des Projekts ist nicht aktiviert oder keine Integration wurde als Agentic AI-Tool registriert.
    • Authentifizierungsfehler, die nach einer Weile des normalen Betriebs auftreten, sind höchstwahrscheinlich auf ein abgelaufenes Token zurückzuführen, daher wiederholen Sie Schritt 2.