Documentazione dell'infrastruttura Oracle Cloud

Risoluzione dei problemi relativi al server MCP

In questa sezione vengono descritti i problemi comuni che possono verificarsi durante la connessione o l'utilizzo di Autonomous AI Database MCP Server e vengono forniti i passi per diagnosticarli e risolverli.

Problemi comuni

MCP Server restituisce HTTP 404 durante la connessione

Questione

Un client MCP non riesce a connettersi al server MCP di Autonomous AI Database e restituisce il seguente errore: HTTP 404 Not Found

Causa possibile

Di seguito sono riportate alcune delle possibili cause di un errore.

  • La configurazione del client utilizza l'endpoint di autenticazione anziché l'endpoint MCP.
  • Il server MCP non è abilitato per il database.
  • L'URL dell'endpoint contiene un OCID di database o un identificativo di area errato.
  • Il client tenta di accedere a un percorso MCP che non esiste.

Risoluzione

  1. Verificare che il server MCP sia abilitato per il database.
  2. Verificare che la configurazione del client MCP utilizzi il formato endpoint corretto: 
    https://dataaccess.adb.<region-identifier>.oraclecloudapps.com/adb/mcp/v1/databases/<database-ocid>
  3. Assicurarsi che la richiesta di autenticazione utilizzi l'endpoint del token: 
    /adb/auth/v1/databases/<database-ocid>/token
  4. Verificare che l'identificativo area e l'OCID database corrispondano all'Autonomous AI Database di destinazione.

Informazioni aggiuntive

L'endpoint MCP e l'endpoint di autenticazione utilizzano percorsi diversi.

L'endpoint di autenticazione crea problemi con i token OAuth, mentre l'endpoint MCP elabora lo strumento e le richieste dell'agente.

Verificare che il server MCP sia abilitato per il database. Vedere Abilita server MCP per informazioni su come abilitare il server MCP.

Autenticazione client MCP non riuscita durante la richiesta del token

Questione

Un client MCP non riesce a ottenere un token bearer e restituisce un errore di autenticazione durante la chiamata dell'endpoint del token.

Causa possibile

Di seguito sono riportate alcune delle possibili cause di un errore.

  • Nome utente o password del database errati.
  • La richiesta di token utilizza un endpoint errato.
  • L'account utente del database è bloccato o è scaduto.
  • Le limitazioni di accesso alla rete bloccano la richiesta.

Risoluzione

  1. Confermare che la richiesta di token utilizza l'endpoint di autenticazione.

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

  2. Verificare il nome utente e la password del database utilizzati nella richiesta.

  3. Confermare che l'account utente del database è attivo.

  4. Riprovare la richiesta con un token valido.

    Richiesta di esempio:

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

Informazioni aggiuntive

Il servizio di autenticazione emette un token inverso che i client MCP includono nell'intestazione Authorization durante la chiamata degli strumenti MCP.

Errore client non valido visualizzato nel browser durante l'autenticazione

Questione

Quando si esegue l'accesso al server MCP, nella pagina di autenticazione viene visualizzato il seguente messaggio:

Invalid Client

Causa possibile

Di seguito sono riportate alcune delle possibili cause di un errore.

  • Dati di autenticazione memorizzati nella cache dal client MCP.
  • Sessione di autenticazione non più valida creata durante un precedente tentativo di login.

Risoluzione

  1. Passare alla directory home.

  2. Individuare la directory .mcp_auth.

    Posizioni di esempio:

    Linux / macOS

    ~/.mcp_auth

    Windows

    C:\Users\<username>\.mcp_auth

  3. Eliminare la directory .mcp_auth per cancellare la sessione di autenticazione inserita nella cache.

  4. Riavviare il client MCP e ripetere l'autenticazione.

Gli strumenti MCP non vengono visualizzati nel client MCP

Questione

Un client MCP si connette correttamente al server MCP ma non visualizza alcun tool.

Causa possibile

Di seguito sono riportate alcune delle possibili cause di un errore.

  • Non sono stati creati strumenti personalizzati.
  • L'utente client non dispone di privilegi sufficienti per accedere agli strumenti.
  • Creazione dello strumento MCP non riuscita durante la creazione.
  • Lo stato dello strumento è disabilitato.

Risoluzione

  1. Verificare che gli strumenti esistano nel database.

  2. Verificare che gli strumenti siano stati creati correttamente. Per ulteriori dettagli, vedere Crea strumenti agente AI Select.

  3. Assicurarsi che l'utente del database che si connette tramite MCP disponga dei privilegi necessari per accedere allo strumento.
  4. Riavviare o riconnettere il client MCP in modo che venga aggiornato l'elenco degli strumenti.

Chiamata allo strumento non riuscita dopo l'approvazione

Questione

La chiamata allo strumento non riesce anche dopo l'approvazione da parte dell'utente.

Causa possibile

Il token bearer è scaduto o l'utente dello schema non corrisponde al proprietario dello strumento.

Risoluzione

  1. Generare un nuovo token bearer.
  2. Verificare che l'utente dello schema abbia creato gli strumenti.

  3. Verificare che gli strumenti esistano.

    SELECT tool_name FROM user_cloud_ai_tools;
  4. Riavviare il client e riprovare.

Errore HTTP Streamable: 401

Questione

Il client mostra il messaggio Streamable HTTP error: il server ha restituito 401 dopo l'autenticazione riuscita.

Causa possibile

Il token bearer è scaduto o non è più valido. I token bearer sono validi per circa un'ora.

Risoluzione

  1. Generare un nuovo token bearer utilizzando l'endpoint OAuth.

  2. Sostituire il valore dell'intestazione di autorizzazione con il nuovo token.

    "Authorization": "Bearer <new-access-token>"
  3. Salvare il file di configurazione MCP.
  4. Riavviare il client.
  5. Eseguire la riconnessione al server MCP.
  6. Riemettere il prompt.

Risultati vuoti imprevisti

Questione

La chiamata allo strumento ha esito positivo, ma non restituisce alcuna riga.

Causa possibile

La tabella non contiene righe corrispondenti oppure le condizioni di filtro sono troppo restrittive.

Risoluzione

  1. Verificare che la tabella contenga dati.
  2. Controllare le condizioni di filtro utilizzate nella query.
  3. Verificare che lo schema e la tabella corretti facciano riferimento.
  4. Eseguire il test della query nel foglio di lavoro SQL. 
    SELECT COUNT(*) FROM <table_name>;

Connessione al server MCP non riuscita quando il database utilizza un endpoint privato

Questione

Un client MCP non può connettersi al server MCP per un database configurato con un endpoint privato.

Causa possibile

Di seguito sono riportate alcune delle possibili cause di un errore.

  • Il client tenta di connettersi dall'esterno della VCN configurata.
  • L'URL dell'endpoint MCP utilizza il nome host pubblico anziché il nome host dell'endpoint privato.
  • Le regole di sicurezza di rete bloccano la richiesta.

Risoluzione

  1. Confermare che il database utilizza un endpoint privato.
  2. Recupera il prefisso del nome host dell'endpoint privato dalla console di Autonomous AI Database.

  3. Aggiornare l'URL dell'endpoint MCP. Per ulteriori dettagli, vedere Accesso agli endpoint privati.

    Formato di esempio:

    https://<hostname_prefix>.adb.<region>.oraclecloudapps.com/adb/mcp/v1/databases/<database-ocid>
  4. Assicurarsi che il client MCP venga eseguito all'interno della rete VCN o connessa.

Errore di recupero non riuscito

Questione

Il client mostra un errore di recupero non riuscito durante la connessione al server MCP.

Causa possibile

L'URL MCP è errato, viene utilizzato HTTP anziché HTTPS, l'identificativo dell'area è errato.

Risoluzione

  1. Verificare che l'endpoint utilizzi https e non http.
  2. Verificare che il dominio utilizzi oraclecloudapps.com e non oraclecloud.com.
  3. Verificare l'identificativo dell'area e l'OCID del database.
  4. Riprovare la connessione dopo l'aggiornamento della configurazione.

Eliminazioni connessione durante la sessione

Questione

Il client smette di funzionare durante una sessione attiva.

Causa possibile

Il token bearer è scaduto durante la sessione.

Risoluzione

  1. Generare un nuovo token bearer.
  2. Aggiornare il file configurazione.
  3. Riavviare il client.
  4. Eseguire la riconnessione al server MCP.

Risoluzione dei problemi di Claude

Claude non richiede le credenziali del database

Questione

Claude Desktop non visualizza un prompt di login per le credenziali del database dopo il riavvio.

Causa possibile

I dati di autenticazione inseriti nella cache interferiscono.

Risoluzione

  1. Apri Claude Desktop.
  2. Fare clic su Menu, selezionare Guida, quindi fare clic su Risoluzione dei problemi.
  3. Scegliere Clear Cache and Restart.
  4. Riavviare Claude e riprovare la connessione.
  5. Se il problema persiste, eliminare la cartella .mcp_auth dalla directory utenti.
  6. Cancella i cookie del browser per dataaccess.adb.<region>.oraclecloudapps.com.
  7. Riavviare Claude e riprovare.

Il server MCP non viene visualizzato come in esecuzione

Questione

Claude Desktop non mostra il server MCP in stato In esecuzione.

Causa possibile

La funzione MCP è disabilitata, l'endpoint non è corretto o la configurazione del client è incompleta.

Risoluzione

  1. Verificare che il valore della tag in formato libero sia impostato correttamente.

    {"name":"mcp_server","enable":true}
  2. Confermare che l'endpoint utilizzi:
    https://dataaccess.adb.<region>.oraclecloudapps.com
    .
  3. Riavviare Claude dopo aver convalidato la configurazione.

Claude Desktop mostra il server MCP come disabilitato

Questione

Dopo aver aggiunto una configurazione del server MCP in Claude Desktop, il server MCP appare disabilitato e gli strumenti non sono disponibili.

Causa possibile

Di seguito sono riportate alcune delle possibili cause di un errore.

  • Non vengono creati strumenti Select AI Agent per l'utente del database.
  • Claude Desktop è stato avviato prima della creazione degli strumenti MCP.
  • Il client MCP ha inserito nella cache una configurazione degli strumenti precedente.

Risoluzione

  1. Verificare che gli strumenti Seleziona agente AI esistano per l'utente del database. Per ottenere una lista degli strumenti per l'utente del database, vedere USER_AI_AGENT_TOOLS View.

    Esempio:

    BEGIN
DBMS_CLOUD_AI_AGENT.CREATE_TOOL(
tool_name  => 'RUN_SQL',
attributes => '{...}'
);
END;
/
  2. Riavviare Claude Desktop dopo aver aggiunto o modificato gli strumenti MCP.
  3. Ricollegare il server MCP in Claude Desktop.

Gli strumenti non appaiono dopo il login in Claude

Questione

Claude si connette con successo, ma gli strumenti previsti non appaiono.

Causa possibile

È stato eseguito il login come utente di schema diverso, gli strumenti sono stati creati in un altro schema oppure Claude deve essere riavviato dopo la creazione dello strumento.

Risoluzione

  1. Confermare di aver eseguito il login come utente dello stesso schema che ha creato gli strumenti.

  2. Verificare che gli strumenti esistano nel database.

    SELECT tool_name FROM user_cloud_ai_tools;
  3. Riavviare Claude Desktop dopo la verifica.

Claude si collega ma si comporta inaspettatamente

Questione

Claude carica e si connette, ma le risposte non corrispondono al comportamento previsto.

Causa possibile

La sessione di chat corrente contiene un contesto non più valido, la sessione deve essere aggiornata o le autorizzazioni dello strumento non sono configurate come previsto.

Risoluzione

  1. Avviare una nuova sessione di chat.
  2. Riavviare Claude Desktop.
  3. Eseguire la riconnessione al server MCP.
  4. Verificare le autorizzazioni degli strumenti in Connettori.

Risoluzione dei problemi Cline

Nessuna casella di chat visibile nella riga

Questione

La casella di input della chat Cline non è visibile dopo aver visualizzato la configurazione e gli strumenti del server MCP.

Causa possibile

L'utente è ancora nel pannello di configurazione MCP.

Risoluzione

  1. Fare clic su Done nel pannello di configurazione MCP.
  2. Tornare all'interfaccia di chat Cline.
  3. Immettere di nuovo il prompt nella casella di chat.

Richiesta metadati non riuscita in modo imprevisto

Questione

La richiesta di metadati non riesce o restituisce un risultato imprevisto quando l'utente richiede i metadati della tabella.

Causa possibile

La connessione alla sessione è diventata obsoleta, la cronologia dei prompt ha interessato la selezione degli strumenti o la stessa tabella esiste in più schemi.

Risoluzione

  1. Eseguire la riconnessione al server MCP.
  2. Cancellare la cronologia dei prompt o avviare una nuova sessione di chat.
  3. Riemettere il prompt dei metadati.
  4. Se la stessa tabella esiste in più schemi, qualificare la tabella con il nome dello schema. 
    Show the metadata details of SALES_USER.CUSTOMERS
  5. Verificare i nomi di tabella duplicati nel database. 
    SELECT owner, table_name
                FROM all_tables
                WHERE table_name = 'CUSTOMERS';