Documentation sur Oracle Cloud Infrastructure

Dépannage du serveur MCP

Cette section décrit les problèmes courants qui peuvent survenir lors de la connexion au serveur MCP de base de données d'IA autonome ou de son utilisation et fournit des étapes pour les diagnostiquer et les résoudre.

Problèmes courants

Le serveur MCP retourne HTTP 404 lors de la connexion

Problème

Un client MCP ne parvient pas à se connecter au serveur MCP de base de données de l'IA autonome et retourne l'erreur suivante : HTTP 404 Not Found

Cause possible

Causes possibles :

  • La configuration client utilise le point d'extrémité d'authentification au lieu du point d'extrémité MCP.
  • Le serveur MCP n'est pas activé pour la base de données.
  • L'URL du point d'extrémité 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 de point d'extrémité correct : 
    https://dataaccess.adb.<region-identifier>.oraclecloudapps.com/adb/mcp/v1/databases/<database-ocid>
  3. Assurez-vous que la demande d'authentification utilise le point d'extrémité du jeton : 
    /adb/auth/v1/databases/<database-ocid>/token
  4. Vérifiez que l'identificateur de région et l'OCID de la base de données correspondent à la base de données IA autonome cible.

Informations supplémentaires

Le point d'extrémité MCP et le point d'extrémité d'authentification utilisent des chemins différents.

Le point d'extrémité d'authentification émet des jetons OAuth, tandis que le point d'extrémité MCP traite les demandes d'outil et d'agent.

Vérifiez que le serveur MCP est activé pour la base de données. Voir Activer le serveur MCP pour savoir comment activer le serveur MCP.

Échec de l'authentification de client MCP lors de la demande de jeton

Problème

Un client MCP ne parvient pas à obtenir un jeton porteur et retourne une erreur d'authentification lors de l'appel du point d'extrémité du jeton.

Cause possible

Causes possibles :

  • Le nom d'utilisateur ou le mot de passe de la base de données est incorrect.
  • La demande de jeton utilise un point d'extrémité incorrect.
  • Le compte d'utilisateur de la base de données est verrouillé ou expiré.
  • Les restrictions d'accès au réseau bloquent la demande.

Résolution

  1. Vérifiez que la demande de jeton utilise le point d'extrémité 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 la base de données utilisés dans la demande.

  3. Vérifiez que le compte d'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 porteur que les clients MCP incluent dans l'en-tête Authorization lors de l'appel des outils MCP.

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

Problème

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

Invalid Client

Cause possible

Causes possibles :

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

Résolution

  1. Accédez à votre répertoire d'origine.

  2. Localisez le répertoire .mcp_auth.

    Exemples d'emplacement :

    Linux / macOS

    ~/.mcp_auth

    Windows

    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-le de nouveau.

Les outils MCP n'apparaissent pas dans le client MCP

Problème

Un client MCP se connecte avec succès au serveur MCP, mais n'affiche aucun outil.

Cause possible

Causes possibles :

  • Aucun outil personnalisé n'a été créé.
  • L'utilisateur client ne dispose pas de privilèges suffisants pour accéder aux outils.
  • Échec 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 été créés avec succès. Pour plus de détails, voir Créer des outils d'agent d'intelligence artificielle sélectionnés.

  3. Assurez-vous que l'utilisateur de base de données se connectant au moyen de 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.

Échec de l'appel de l'outil après approbation

Problème

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

Cause possible

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

Résolution

  1. Générer un nouveau jeton de 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 diffusable – 401

Problème

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

Cause possible

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

Résolution

  1. Générez un nouveau jeton de porteur à l'aide du point d'extrémité OAuth.

  2. Remplacez la valeur d'en-tête Authorization 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. Réémettez l'invite.

Résultats vides inattendus

Problème

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

Cause possible

La table ne contient aucune rangée 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 l'interrogation.
  3. Vérifiez que le schéma et la table appropriés sont référencés.
  4. Testez l'interrogation dans SQL Worksheet. 
    SELECT COUNT(*) FROM <table_name>;

Échec de la connexion au serveur MCP lorsque la base de données utilise un point d'extrémité privé

Problème

Un client MCP ne peut pas se connecter au serveur MCP pour une base de données configurée avec un point d'extrémité privé.

Cause possible

Causes possibles :

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

Résolution

  1. Vérifiez que la base de données utilise un point d'extrémité privé.
  2. Extraire le préfixe du nom d'hôte du point d'extrémité privé à partir de la console de la base de données du service d'intelligence artificielle autonome.

  3. Mettez à jour l'URL du point d'extrémité MCP. Pour plus de détails, voir Accès au point d'extrémité privé.

    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'extraction en échec

Problème

Le client affiche une erreur d'extraction en échec 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 le point d'extrémité 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 la base de données.
  4. Réessayez la connexion après la mise à jour de la configuration.

Abandons de connexion pendant la session

Problème

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érer un nouveau jeton de porteur.
  2. Mettez à jour le fichier de configuration.
  3. Redémarrez le client.
  4. Reconnectez-vous au serveur MCP.

Dépannage de Claude

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

Problème

Claude Desktop n'affiche pas d'invite de connexion pour les données 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 des utilisateurs.
  6. Effacer les témoins 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

Problème

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

Cause possible

La fonction MCP est désactivée, le point d'extrémité est incorrect ou la configuration du client est incomplète.

Résolution

  1. Vérifiez que la valeur du marqueur à structure libre est définie correctement.

    {"name":"mcp_server","enable":true}
  2. Vérifiez que le point d'extrémité utilise les éléments suivants :
    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é

Problème

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

Cause possible

Causes possibles :

  • Aucun outil Sélectionner un agent d'intelligence artificielle n'est créé pour l'utilisateur de base de données.
  • Claude Desktop a commencé 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. Voir Vue USER_AI_AGENT_TOOLS pour obtenir la liste des outils pour l'utilisateur de base de données.

    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 Claude Desktop.

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

Problème

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

Cause possible

Vous 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 du schéma qui a 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 vérification.

Claude se connecte mais se comporte de manière inattendue

Problème

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

Cause possible

La session de clavardage courante contient un contexte périmé, la session doit être actualisée ou les autorisations d'outil ne sont pas configurées comme prévu.

Résolution

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

Dépannage de Cline

Aucune boîte de discussion visible dans Cline

Problème

La zone d'entrée Cline chat n'est pas visible après avoir consulté la configuration et les outils du serveur MCP.

Cause possible

L'utilisateur est toujours dans le panneau de configuration MCP.

Résolution

  1. Cliquez sur Done dans le panneau de configuration MCP.
  2. Retournez à l'interface de clavardage Cline.
  3. Entrez de nouveau l'invite dans la zone de clavardage.

Échec inattendu de la demande de métadonnées

Problème

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 à la 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 clavardage.
  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 du 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';