Documentation Oracle Cloud Infrastructure

Dépannage du serveur MCP

Cette section décrit les problèmes courants qui peuvent survenir lors de la connexion ou de l'utilisation du serveur Autonomous AI Database MCP et fournit des étapes pour les diagnostiquer et les résoudre.

Problèmes courants

Le serveur MCP renvoie HTTP 404 lors de la connexion

Sortie

Un client MCP ne parvient pas à se connecter au serveur Autonomous AI Database MCP et renvoie l'erreur suivante : HTTP 404 Not Found

Cause possible

Les motifs possibles sont les suivants :

  • La configuration client utilise l'adresse d'authentification au lieu de l'adresse MCP.
  • Le serveur MCP n'est pas activé pour la base de données.
  • L'URL endpoint contient un OCID de base de données ou un identificateur de région incorrect.
  • Le client tente d'accéder à un chemin MCP qui n'existe pas.

Résolution

  1. Vérifiez que le serveur MCP est activé pour la base de données.
  2. Vérifiez que la configuration du client MCP utilise le format d'adresse correct : 
    https://dataaccess.adb.<region-identifier>.oraclecloudapps.com/adb/mcp/v1/databases/<database-ocid>
  3. Assurez-vous que la demande d'authentification utilise l'adresse de jeton : 
    /adb/auth/v1/databases/<database-ocid>/token
  4. Vérifiez que l'identificateur de région et l'OCID de base de données correspondent à la base de données Autonomous AI cible.

Informations supplémentaires

L'adresse MCP et l'adresse d'authentification utilisent des chemins différents.

L'adresse d'authentification émet des jetons OAuth, tandis que l'adresse MCP traite l'outil et les demandes d'agent.

Vérifiez que le serveur MCP est activé pour la base de données. Pour savoir comment activer le serveur MCP, reportez-vous à Activation du serveur MCP.

Echec de l'authentification du client MCP lors de la demande de jeton

Sortie

Un client MCP ne parvient pas à obtenir un jeton de support et renvoie une erreur d'authentification lors de l'appel de l'adresse de jeton.

Cause possible

Les motifs possibles sont les suivants :

  • Le nom utilisateur ou le mot de passe de base de données est incorrect.
  • La demande de jeton utilise une adresse incorrecte.
  • Le compte utilisateur de la base de données est verrouillé ou a expiré.
  • Les restrictions d'accès réseau bloquent la demande.

Résolution

  1. Vérifiez que la demande de jeton utilise l'adresse d'authentification.

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

  2. Vérifiez le nom utilisateur et le mot de passe de base de données utilisés dans la demande.

  3. Vérifiez que le compte utilisateur de la base de données est actif.

  4. Réessayez la demande avec un jeton valide.

    Exemple de demande :

    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>"}'

Informations supplémentaires

Le service d'authentification émet un jeton de support que les clients MCP incluent dans l'en-tête Authorization lors de l'appel des outils MCP.

Une erreur client non valide apparaît dans le navigateur lors de l'authentification

Sortie

La page d'authentification affiche le message suivant lors de la connexion au serveur MCP :

Invalid Client

Cause possible

Les motifs possibles sont les suivants :

  • Données d'authentification mises en cache stockées par le client MCP.
  • Session d'authentification obsolète créée lors d'une tentative de connexion précédente.

Résolution

  1. Accédez à votre répertoire de base.

  2. Localisez le répertoire .mcp_auth.

    Exemples d'emplacements :

    Linux / macOS

    ~/.mcp_auth

    Fenêtres

    C:\Users\<username>\.mcp_auth

  3. Supprimez le répertoire .mcp_auth pour effacer la session d'authentification mise en cache.

  4. Redémarrez le client MCP et authentifiez à nouveau.

Les outils MCP n'apparaissent pas dans le client MCP

Sortie

Un client MCP se connecte au serveur MCP mais n'affiche aucun outil.

Cause possible

Les motifs possibles sont les suivants :

  • Aucun outil personnalisé n'a été créé.
  • L'utilisateur client ne dispose pas des privilèges suffisants pour accéder aux outils.
  • Echec de la création de l'outil MCP lors de la création.
  • Le statut de l'outil est désactivé.

Résolution

  1. Vérifiez que les outils existent dans la base de données.

  2. Vérifiez que les outils ont bien été créés. Pour plus de détails, reportez-vous à Création d'outils d'agent AI Select.

  3. Assurez-vous que l'utilisateur de base de données qui se connecte via MCP dispose des privilèges requis pour accéder à l'outil.
  4. Redémarrez ou reconnectez le client MCP afin qu'il actualise la liste d'outils.

Echec de l'appel d'outil après approbation

Sortie

L'appel de l'outil échoue même après que l'utilisateur l'ait approuvé.

Cause possible

Le jeton du porteur a expiré ou l'utilisateur de schéma ne correspond pas au propriétaire de l'outil.

Résolution

  1. Générez un nouveau jeton porteur.
  2. Vérifiez que l'utilisateur du schéma a créé les outils.

  3. Vérifiez que les outils existent.

    SELECT tool_name FROM user_cloud_ai_tools;
  4. Redémarrez le client et réessayez.

Erreur HTTP transmissible - 401

Sortie

Le client affiche le message Streamable HTTP error : le serveur a renvoyé 401 après une authentification réussie.

Cause possible

Le jeton du porteur a expiré ou n'est plus valide. Les jetons porteurs sont valides pendant environ une heure.

Résolution

  1. Générez un nouveau jeton de support à l'aide de l'adresse OAuth.

  2. Remplacez la valeur d'en-tête d'autorisation par le nouveau jeton.

    "Authorization": "Bearer <new-access-token>"
  3. Enregistrez le fichier de configuration MCP.
  4. Redémarrez le client.
  5. Reconnectez-vous au serveur MCP.
  6. Relancez l'invite.

Résultats vides inattendus

Sortie

L'appel de l'outil réussit mais ne renvoie aucune ligne.

Cause possible

La table ne contient aucune ligne correspondante ou les conditions de filtre sont trop restrictives.

Résolution

  1. Vérifiez que la table contient des données.
  2. Vérifiez les conditions de filtre utilisées dans la requête.
  3. Vérifiez que le schéma et la table appropriés sont référencés.
  4. Testez la requête dans une feuille de calcul SQL. 
    SELECT COUNT(*) FROM <table_name>;

Echec de la connexion au serveur MCP lorsque la base de données utilise une adresse privée

Sortie

Un client MCP ne peut pas se connecter au serveur MCP pour une base de données configurée avec une adresse privée.

Cause possible

Les motifs possibles sont les suivants :

  • Le client tente de se connecter depuis l'extérieur du VCN configuré.
  • L'URL d'adresse MCP utilise le nom d'hôte public au lieu du nom d'hôte d'adresse privée.
  • Les règles de sécurité réseau bloquent la demande.

Résolution

  1. Vérifiez que la base de données utilise une adresse privée.
  2. Extrayez le préfixe de nom d'hôte de l'adresse privée à partir de la console Autonomous AI Database.

  3. Mettez à jour l'URL d'adresse MCP. Pour plus d'informations, reportez-vous à Accès à une adresse privée.

    Exemple de format :

    https://<hostname_prefix>.adb.<region>.oraclecloudapps.com/adb/mcp/v1/databases/<database-ocid>
  4. Assurez-vous que le client MCP s'exécute dans le VCN ou le réseau connecté.

Erreur d'échec de l'extraction

Sortie

Le client affiche une erreur d'échec d'extraction lors de la connexion au serveur MCP.

Cause possible

L'URL MCP est incorrecte, HTTP est utilisé à la place de HTTPS, l'identificateur de région est incorrect.

Résolution

  1. Vérifiez que l'adresse utilise https, et non http.
  2. Vérifiez que le domaine utilise oraclecloudapps.com, et non oraclecloud.com.
  3. Vérifiez l'identificateur de région et l'OCID de base de données.
  4. Réessayez la connexion après la mise à jour de la configuration.

Suppressions de connexion pendant la session

Sortie

Le client cesse de travailler pendant une session active.

Cause possible

Le jeton du porteur a expiré pendant la session.

Résolution

  1. Générez un nouveau jeton porteur.
  2. Mettez à jour ce fichier.
  3. Redémarrez le client.
  4. Reconnectez-vous au serveur MCP.

Claude Dépannage

Claude n'invite pas les informations d'identification de base de données

Sortie

Claude Desktop n'affiche pas d'invite de connexion pour les informations d'identification de base de données après le redémarrage.

Cause possible

Les données d'authentification mises en cache interfèrent.

Résolution

  1. Ouvrez Claude Desktop.
  2. Cliquez sur Menu, sélectionnez Aide, puis cliquez sur Dépannage.
  3. Sélectionnez Clear Cache and Restart.
  4. Redémarrez Claude et réessayez la connexion.
  5. Si le problème persiste, supprimez le dossier .mcp_auth de votre répertoire utilisateur.
  6. Effacez les cookies du navigateur pour dataaccess.adb.<region>.oraclecloudapps.com.
  7. Redémarrez Claude et réessayez.

Le serveur MCP ne s'affiche pas comme en cours d'exécution

Sortie

Claude Desktop n'affiche pas le serveur MCP en cours d'exécution.

Cause possible

La fonctionnalité MCP est désactivée, l'adresse est incorrecte ou la configuration du client est incomplète.

Résolution

  1. Vérifiez que la valeur de la balise à format libre est correctement définie.

    {"name":"mcp_server","enable":true}
  2. Vérifiez que l'adresse utilise :
    https://dataaccess.adb.<region>.oraclecloudapps.com
    .
  3. Redémarrez Claude après avoir validé la configuration.

Claude Desktop affiche le serveur MCP comme désactivé

Sortie

Après l'ajout d'une configuration de serveur MCP dans le bureau Claude, le serveur MCP apparaît désactivé et les outils ne sont pas disponibles.

Cause possible

Les motifs possibles sont les suivants :

  • Aucun outil Select AI Agent n'est créé pour l'utilisateur de base de données.
  • Claude Desktop a démarré avant la création des outils MCP.
  • Le client MCP a mis en cache une configuration d'outil antérieure.

Résolution

  1. Vérifiez que les outils Select AI Agent existent pour l'utilisateur de base de données. Pour obtenir la liste des outils de l'utilisateur de base de données, reportez-vous à USER_AI_AGENT_TOOLS View.

    Exemple :

    BEGIN
DBMS_CLOUD_AI_AGENT.CREATE_TOOL(
tool_name  => 'RUN_SQL',
attributes => '{...}'
);
END;
/
  2. Redémarrez Claude Desktop après avoir ajouté ou modifié des outils MCP.
  3. Reconnectez le serveur MCP dans le bureau Claude.

Les outils n'apparaissent pas après la connexion à Claude

Sortie

Claude se connecte avec succès, mais les outils attendus n'apparaissent pas.

Cause possible

Vous êtes connecté en tant qu'utilisateur de schéma différent, les outils ont été créés sous un autre schéma ou Claude doit être redémarré après la création de l'outil.

Résolution

  1. Confirmez que vous êtes connecté en tant qu'utilisateur de schéma ayant créé les outils.

  2. Vérifiez que les outils existent dans la base de données.

    SELECT tool_name FROM user_cloud_ai_tools;
  3. Redémarrez Claude Desktop après la vérification.

Claude se connecte mais se comporte de manière inattendue

Sortie

Claude se charge et se connecte, mais les réponses ne correspondent pas au comportement attendu.

Cause possible

La session de discussion en cours contient un contexte obsolète, la session doit être actualisée ou les droits d'accès à l'outil ne sont pas configurés comme prévu.

Résolution

  1. Démarrez une nouvelle session de chat.
  2. Redémarrez Claude Desktop.
  3. Reconnectez-vous au serveur MCP.
  4. Vérifiez les autorisations de l'outil sous Connecteurs.

Dépannage Cline

Aucun chat visible dans Cline

Sortie

La zone d'entrée de discussion Cline n'est pas visible après l'affichage de la configuration et des outils du serveur MCP.

Cause possible

L'utilisateur se trouve toujours dans le panneau de configuration MCP.

Résolution

  1. Cliquez sur Done dans le panneau de configuration MCP.
  2. Revenez à l'interface de discussion Cline.
  3. Saisissez à nouveau l'invite dans la zone de discussion.

Echec inattendu de la demande de métadonnées

Sortie

La demande de métadonnées échoue ou renvoie un résultat inattendu lorsque l'utilisateur demande des métadonnées de table.

Cause possible

La connexion de session est devenue obsolète, l'historique des invites a affecté la sélection d'outils ou la même table existe dans plusieurs schémas.

Résolution

  1. Reconnectez-vous au serveur MCP.
  2. Effacez l'historique des invites ou démarrez une nouvelle session de discussion.
  3. Réémettez l'invite de métadonnées.
  4. Si la même table existe dans plusieurs schémas, qualifiez-la avec le nom de schéma. 
    Show the metadata details of SALES_USER.CUSTOMERS
  5. Vérifiez les noms de table en double dans la base de données. 
    SELECT owner, table_name
                FROM all_tables
                WHERE table_name = 'CUSTOMERS';