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.
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.
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::allenthä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.comaussieht. Sie benötigen nur den Teil<identity_domain>, ohne Protokoll oder Suffix. Fürhttps://example123.identity.oraclecloud.combedeutet dasexample123. - 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_IDist die Client-ID Ihrer OAuth-Vertrauensanwendung.OIC_RESOURCE_SCOPEenthält den vollständigen Scope-String, wie er für OIC konfiguriert ist. Er beinhaltet das Elementurn:opc:resource:consumer::all.OIC_IDENTITY_DOMAINist einfach der Teil vor.identity.oraclecloud.com, wie z. B.example123.OIC_MCP_URList 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
oicheißt und aktiviert ist; - die URL mit dem MCP-Endpunkt Ihres OIC-Projekts übereinstimmt;
- der Transportmodus
streamable_httpist; - die Variable für den Token
OIC_ACCESS_TOKENlautet.
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:
- Gehen Sie zurück zum Konfigurationsterminal oder geben Sie die Werte aus Schritt 1 erneut ein.
- Wiederholen Sie Schritt 2, um ein neues Token zu erhalten und die Desktop-Umgebung zu aktualisieren.
- 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.