Fehlerbehebung für MCP-Server

In diesem Abschnitt werden allgemeine Probleme beschrieben, die beim Herstellen einer Verbindung zum oder Verwenden des Autonomous AI Database MCP-Servers auftreten können. Außerdem werden Schritte zum Diagnostizieren und Beheben dieser Probleme beschrieben.

Häufige Probleme

MCP-Server gibt HTTP 404 zurück, wenn eine Verbindung hergestellt wird

Problem

Ein MCP-Client kann keine Verbindung zum MCP-Server der autonomen KI-Datenbank herstellen und gibt den folgenden Fehler zurück: HTTP 404 Not Found

Mögliche Ursache

Mögliche Ursachen sind:

Die Clientkonfiguration verwendet den Authentifizierungsendpunkt anstelle des MCP-Endpunkts.
Der MCP-Server ist für die Datenbank nicht aktiviert.
Die Endpunkt-URL enthält eine falsche Datenbank-OCID oder Regions-ID.
Der Client versucht, auf einen nicht vorhandenen MCP-Pfad zuzugreifen.

Lösung

Prüfen Sie, ob der MCP-Server für die Datenbank aktiviert ist.

Stellen Sie sicher, dass die MCP-Clientkonfiguration das richtige Endpunktformat verwendet:

https://dataaccess.adb.<region-identifier>.oraclecloudapps.com/adb/mcp/v1/databases/<database-ocid>

Stellen Sie sicher, dass die Authentifizierungsanforderung den Tokenendpunkt verwendet:
```
/adb/auth/v1/databases/<database-ocid>/token
```
Prüfen Sie, ob die Regions-ID und die Datenbank-OCID mit der autonomen Zieldatenbank übereinstimmen.

Weitere Informationen

Der MCP-Endpunkt und der Authentifizierungsendpunkt verwenden unterschiedliche Pfade.

Der Authentifizierungsendpunkt gibt OAuth-Token aus, während der MCP-Endpunkt Tool- und Agent-Anforderungen verarbeitet.

Prüfen Sie, ob der MCP-Server für die Datenbank aktiviert ist. Informationen zum Aktivieren des MCP-Servers finden Sie unter MCP-Server aktivieren.

MCP-Clientauthentifizierung beim Anfordern von Token nicht erfolgreich

Problem

Ein MCP-Client kann kein Bearer-Token abrufen und gibt beim Aufrufen des Tokenendpunkts einen Authentifizierungsfehler zurück.

Mögliche Ursache

Mögliche Ursachen sind:

Benutzername oder Kennwort der Datenbank ist falsch.
Die Tokenanforderung verwendet einen falschen Endpunkt.
Der Datenbankbenutzeraccount ist gesperrt oder abgelaufen.
Netzwerkzugriffseinschränkungen blockieren die Anforderung.

Lösung

Bestätigen Sie, dass die Tokenanforderung den Authentifizierungsendpunkt verwendet.

https://dataaccess.adb.<region>.oraclecloudapps.com/adb/auth/v1/databases/<database-ocid>/token

Prüfen Sie den Benutzernamen und das Kennwort der Datenbank, die in der Anforderung verwendet werden.
Vergewissern Sie sich, dass der Datenbankbenutzeraccount aktiv ist.

Wiederholen Sie die Anforderung mit einem gültigen Token.

Beispielanforderung:

curl --location "https://dataaccess.adb.<region>.oraclecloudapps.com/adb/auth/v1/databases/<database-ocid>/token" \
--header "Content-Type: application/json" \
--data '{"grant_type":"password","username":"ADMIN","password":"<password>"}'

Weitere Informationen

Der Authentifizierungsservice gibt ein Bearer-Token aus, das MCP-Clients beim Aufrufen von MCP-Tools in den Authorization-Header aufnehmen.

Ungültiger Clientfehler wird während der Authentifizierung im Browser angezeigt

Problemfall

Auf der Authentifizierungsseite wird die folgende Meldung angezeigt, wenn Sie sich beim MCP-Server anmelden:

Invalid Client

Mögliche Ursache

Mögliche Ursachen sind:

Vom MCP-Client gespeicherte Authentifizierungsdaten im Cache.
Eine veraltete Authentifizierungssession, die bei einem vorherigen Anmeldeversuch erstellt wurde.

Lösung

Navigieren Sie zu Ihrem Home-Verzeichnis.
Suchen Sie das Verzeichnis .mcp_auth.

Beispielspeicherorte:

Linux / macOS
```
~/.mcp_auth
```
Fenster
```
C:\Users\<username>\.mcp_auth
```
Löschen Sie das Verzeichnis .mcp_auth, um die gecachte Authentifizierungssession zu löschen.
Starten Sie den MCP-Client neu, und authentifizieren Sie sich erneut.

MCP-Tools werden nicht im MCP-Client angezeigt

Problemfall

Ein MCP-Client stellt erfolgreich eine Verbindung zum MCP-Server her, zeigt aber keine Tools an.

Mögliche Ursache

Mögliche Ursachen sind:

Es wurden keine benutzerdefinierten Tools erstellt.
Der Clientbenutzer verfügt nicht über ausreichende Berechtigungen für den Zugriff auf die Tools.
Das MCP-Tool konnte während der Erstellung nicht erstellt werden.
Der Werkzeugstatus ist deaktiviert.

Lösung

Prüfen Sie, ob Tools in der Datenbank vorhanden sind.
Prüfen Sie, ob die Tools erfolgreich erstellt wurden. Weitere Informationen finden Sie unter Select AI Agent-Tools erstellen.
Stellen Sie sicher, dass der Datenbankbenutzer, der sich über MCP anmeldet, über die erforderlichen Berechtigungen für den Zugriff auf das Tool verfügt.
Starten Sie den MCP-Client neu, oder verbinden Sie ihn erneut, damit die Toolliste aktualisiert wird.

Toolaufruf nach Genehmigung nicht erfolgreich

Problemfall

Der Toolaufruf ist auch nach der Genehmigung durch den Benutzer nicht erfolgreich.

Mögliche Ursache

Das Bearer-Token ist abgelaufen, oder der Schemabenutzer stimmt nicht mit dem Tool-Eigentümer überein.

Lösung

Generieren Sie ein neues Bearer-Token.
Prüfen Sie, ob der Schemabenutzer die Tools erstellt hat.

Bestätigen Sie, dass die Tools vorhanden sind.

SELECT tool_name FROM user_cloud_ai_tools;

Starten Sie den Client neu, und wiederholen Sie den Vorgang.

Streamable HTTP-Fehler – 401

Problem

Der Client zeigt die Meldung Streamable HTTP error an: Der Server hat nach erfolgreicher Authentifizierung 401 zurückgegeben.

Mögliche Ursache

Das Bearer Token ist abgelaufen oder nicht mehr gültig. Bearer-Token sind ungefähr eine Stunde lang gültig.

Lösung

Generieren Sie ein neues Bearer-Token mit dem Endpunkt OAuth.
Ersetzen Sie den Autorisierungsheaderwert durch das neue Token.
```
"Authorization": "Bearer <new-access-token>"
```
Speichern Sie die MCP-Konfigurationsdatei.
Starten Sie den Client neu.
Melden Sie sich erneut beim MCP-Server an.
Geben Sie den Prompt erneut aus.

Unerwartete leere Ergebnisse

Problem

Der Toolaufruf ist erfolgreich, gibt aber keine Zeilen zurück.

Mögliche Ursache

Die Tabelle enthält keine übereinstimmenden Zeilen, oder die Filterbedingungen sind zu restriktiv.

Lösung

Prüfen Sie, ob die Tabelle Daten enthält.
Prüfen Sie die in der Abfrage verwendeten Filterbedingungen.
Vergewissern Sie sich, dass das richtige Schema und die richtige Tabelle referenziert werden.

Abfrage in SQL Worksheet testen

SELECT COUNT(*) FROM <table_name>;

MCP-Serververbindung nicht erfolgreich, wenn Datenbank einen privaten Endpunkt verwendet

Problemfall

Ein MCP-Client kann keine Verbindung zum MCP-Server für eine Datenbank herstellen, die mit einem privaten Endpunkt konfiguriert ist.

Mögliche Ursache

Mögliche Ursachen sind:

Der Client versucht, eine Verbindung von außerhalb des konfigurierten VCN herzustellen.
Die MCP-Endpunkt-URL verwendet den öffentlichen Hostnamen anstelle des Hostnamens des privaten Endpunkts.
Netzwerksicherheitsregeln blockieren die Anforderung.

Lösung

Vergewissern Sie sich, dass die Datenbank einen privaten Endpunkt verwendet.
Rufen Sie das Hostnamenspräfix des privaten Endpunkts aus der Konsole für die autonome KI-Datenbank ab.
Aktualisieren Sie die MCP-Endpunkt-URL. Weitere Informationen finden Sie unter Privater Endpunktzugriff.

Beispielformat:
```
https://<hostname_prefix>.adb.<region>.oraclecloudapps.com/adb/mcp/v1/databases/<database-ocid>
```
Stellen Sie sicher, dass der MCP-Client im VCN oder verbundenen Netzwerk ausgeführt wird.

Fehler beim Abrufen

Problemfall

Der Client zeigt einen nicht erfolgreichen Abruffehler beim Herstellen einer Verbindung zum MCP-Server an.

Mögliche Ursache

Die MCP-URL ist falsch. HTTP wird anstelle von HTTPS verwendet. Die Regions-ID ist falsch.

Lösung

Stellen Sie sicher, dass der Endpunkt https und nicht http verwendet.
Stellen Sie sicher, dass die Domain oraclecloudapps.com und nicht oraclecloud.com verwendet.
Prüfen Sie die Regions-ID und die Datenbank-OCID.
Wiederholen Sie die Verbindung, nachdem Sie die Konfiguration aktualisiert haben.

Verbindung wird während Session gelöscht

Problem

Der Client funktioniert während einer aktiven Session nicht mehr.

Mögliche Ursache

Das Bearer-Token ist während der Session abgelaufen.

Lösung

Generieren Sie ein neues Bearer-Token.
Aktualisieren Sie die Konfigurationsdatei.
Starten Sie den Client neu.
Melden Sie sich erneut beim MCP-Server an.

Claude - Fehlerbehebung

Claude fragt nicht nach Datenbankzugangsdaten

Problemfall

Claude Desktop zeigt nach dem Neustart keine Anmeldeaufforderung für Datenbankzugangsdaten an.

Mögliche Ursache

Zwischengespeicherte Authentifizierungsdaten stören.

Lösung

Öffnen Sie Claude Desktop.
Klicken Sie auf Menü, wählen Sie Hilfe aus, und klicken Sie dann auf Fehlerbehebung.
Wählen Sie Clear Cache and Restart.
Starten Sie Claude neu und wiederholen Sie die Verbindung.
Wenn das Problem weiterhin besteht, löschen Sie den Ordner .mcp_auth aus Ihrem Benutzerverzeichnis.
Browser-Cookies für dataaccess.adb.<region>.oraclecloudapps.com löschen.
Starten Sie Claude erneut und versuchen Sie es erneut.

MCP-Server wird nicht als aktiv angezeigt

Problemfall

Claude Desktop zeigt den MCP-Server nicht im Status "Wird ausgeführt" an.

Mögliche Ursache

Das MCP-Feature ist deaktiviert, der Endpunkt ist falsch oder die Clientkonfiguration ist unvollständig.

Lösung

Prüfen Sie, ob der Freiformtagwert korrekt festgelegt ist.
```
{"name":"mcp_server","enable":true}
```
Stellen Sie sicher, dass der Endpunkt Folgendes verwendet:
```
https://dataaccess.adb.<region>.oraclecloudapps.com
```
.
Starten Sie Claude neu, nachdem Sie die Konfiguration validiert haben.

Claude Desktop zeigt MCP-Server als deaktiviert an

Problem

Nachdem Sie eine MCP-Serverkonfiguration in Claude Desktop hinzugefügt haben, erscheint der MCP-Server deaktiviert, und die Tools sind nicht verfügbar.

Mögliche Ursache

Mögliche Ursachen sind:

Für den Datenbankbenutzer wurden keine Select AI Agent-Tools erstellt.
Claude Desktop wurde gestartet, bevor die MCP-Tools erstellt wurden.
Der MCP-Client hat eine frühere Toolkonfiguration im Cache gespeichert.

Lösung

Stellen Sie sicher, dass Select AI Agent-Tools für den Datenbankbenutzer vorhanden sind. Eine Liste der Tools für den Datenbankbenutzer finden Sie unter Ansicht USER_AI_AGENT_TOOLS.
Beispiel:
```
BEGIN
DBMS_CLOUD_AI_AGENT.CREATE_TOOL(
tool_name  => 'RUN_SQL',
attributes => '{...}'
);
END;
/
            
```
Starten Sie Claude Desktop neu, nachdem Sie MCP-Tools hinzugefügt oder geändert haben.
Schließen Sie den MCP-Server in Claude Desktop erneut an.

Werkzeuge werden nach der Anmeldung in Claude nicht angezeigt

Problemfall

Claude verbindet sich erfolgreich, aber die erwarteten Werkzeuge erscheinen nicht.

Mögliche Ursache

Sie haben sich als anderer Schemabenutzer angemeldet, die Tools wurden unter einem anderen Schema erstellt, oder Claude muss nach der Toolerstellung neu gestartet werden.

Lösung

Bestätigen Sie, dass Sie sich als derselbe Schemabenutzer angemeldet haben, der die Tools erstellt hat.
Prüfen Sie, ob die Tools in der Datenbank vorhanden sind.
```
SELECT tool_name FROM user_cloud_ai_tools;
```
Starten Sie Claude Desktop nach der Überprüfung neu.

Claude verbindet sich, verhält sich aber unerwartet

Problemfall

Claude lädt und verbindet sich, aber die Antworten stimmen nicht mit dem erwarteten Verhalten überein.

Mögliche Ursache

Die aktuelle Chatsession enthält veralteten Kontext, die Session muss aktualisiert werden, oder Toolberechtigungen sind nicht wie erwartet konfiguriert.

Lösung

Starten Sie eine neue Chatsession.
Starten Sie Claude Desktop neu.
Melden Sie sich erneut beim MCP-Server an.
Prüfen Sie die Toolberechtigungen unter Connectors.

Cline-Fehlerbehebung

Keine Chatbox in Cline sichtbar

Problemfall

Das Eingabefeld für den Cline-Chat wird nach der Anzeige der MCP-Serverkonfiguration und -Tools nicht angezeigt.

Mögliche Ursache

Der Benutzer befindet sich noch im MCP-Konfigurationsbereich.

Lösung

Klicken Sie im MCP-Konfigurationsbereich auf Done.
Kehren Sie zur Cline-Chatschnittstelle zurück.
Geben Sie die Eingabeaufforderung erneut in das Chatfeld ein.

Metadatenanforderung nicht erfolgreich

Problemfall

Die Metadatenanforderung ist nicht erfolgreich oder gibt ein unerwartetes Ergebnis zurück, wenn der Benutzer nach Tabellenmetadaten fragt.

Mögliche Ursache

Die Sessionverbindung ist veraltet, die Auswahl des betroffenen Tools in der Prompt-Historie oder dieselbe Tabelle ist in mehreren Schemas vorhanden.

Lösung

Melden Sie sich erneut beim MCP-Server an.
Löschen Sie den Prompt-Verlauf, oder starten Sie eine neue Chatsession.
Geben Sie die Metadaten-Eingabeaufforderung erneut aus.
Wenn dieselbe Tabelle in mehreren Schemas vorhanden ist, kennzeichnen Sie die Tabelle mit dem Schemanamen.
```
Show the metadata details of SALES_USER.CUSTOMERS
```

Prüfen Sie doppelte Tabellennamen in der Datenbank.

SELECT owner, table_name
                FROM all_tables
                WHERE table_name = 'CUSTOMERS';

Übergeordnetes Thema: Autonome KI-Datenbank - MCP-Server

Oracle Cloud Infrastructure-Dokumentation

Fehlerbehebung für MCP-Server