| Problema |
Messaggio di errore |
Causa |
Procedura di correzione/risoluzione dei problemi |
Errore non specificato di "Recupera strumenti" |
"Impossibile recuperare i dettagli del server MCP. Riprova". (o se il pulsante Recupera strumenti non funziona senza un messaggio di errore specifico). |
Connected Console non è riuscita a completare la richiesta al tuo endpoint MCP a causa di un URL non valido, di un server offline o di un errore di rete. |
Verifica quanto segue:
- Controlla che l'URL dell'endpoint MCP sia corretto e utilizzi
https://.
- Assicurati che il tuo server MCP sia in esecuzione.
- Verifica che il tuo server MCP sia accessibile da internet pubblico (Google non può raggiungere
localhost o indirizzi intranet privati).
|
Il server MCP non è raggiungibile |
"Il server MCP non è raggiungibile" |
Il backend di Google non è riuscito a stabilire una connessione con il tuo endpoint MCP. |
Di seguito sono elencate alcune delle possibili cause e soluzioni:
- Limitazioni del firewall: assicurati che il firewall o il WAF non blocchi gli intervalli IP in uscita di Google.
- Regole di API Gateway: verifica che API Gateway accetti le richieste
POST e non rifiuti le richieste clientInfo di Google durante l'handshake MCP initialize.
- Sottodominio non corrispondente: se utilizzi un sottodominio dedicato (ad esempio
gemini.mcp.company.com), assicurati che i relativi metadati /.well-known/oauth-protected-resource corrispondano a quel sottodominio anziché puntare a un dominio di base diverso (mcp.company.com).
|
Trasporto MCP non supportato (HTTP 405) |
"Il server MCP ha rifiutato la richiesta (HTTP 405 Method Not Allowed). Assicurati che l'URL punti a un endpoint HTTP trasmissibile in streaming che accetta richieste POST, non a un endpoint SSE legacy." |
L'URL dell'endpoint punta a un endpoint HTTP+SSE legacy che accetta solo richieste GET o rifiuta richieste JSON-RPC POST. |
Aggiorna il server MCP e l'URL dell'endpoint per utilizzare il trasporto HTTP trasmissibile in streaming di MCP che accetta richieste POST per initialize e tools/list.
|
File di risorse protette OAuth mancante |
"Il file /.well-known/oauth-protected-resource non esiste sul server MCP" |
Google ha tentato il rilevamento dei metadati delle risorse protette OAuth 2.0 (RFC 9728), che non è riuscito. |
- Se il tuo server MCP NON richiede l'autenticazione: questo errore si verifica in genere quando l'URL dell'endpoint MCP contiene un errore di battitura o un segmento di percorso mancante (ad esempio,
https://mcp.example.com anziché https://mcp.example.com/mcp) e restituisce HTTP 404 o 500, causando il ritorno del client al rilevamento OAuth. Verifica che il percorso esatto dell'endpoint MCP restituisca HTTP 200 OK alle richieste POST initialize e tools/list non autenticate e seleziona No in Il tuo server richiede l'autorizzazione? in Credenziali di accesso.
- Se il tuo server MCP richiede l'autenticazione: ospita un file JSON
/.well-known/oauth-protected-resource valido sul tuo server MCP che annuncia i tuoi server di autorizzazione attendibili nell'array authorization_servers.
|
Metadati del server di autorizzazione OAuth mancanti o non validi |
"Il file /.well-known/oauth-authorization-server non esiste sul server OAuth" o "contiene un JSON non valido o incompleto" |
Il tuo server OAuth non espone un documento di metadati RFC 8414 valido in /.well-known/oauth-authorization-server. |
- Ospita un documento di rilevamento RFC 8414 valido all'indirizzo
/.well-known/oauth-authorization-server (o /.well-known/openid-configuration) contenente authorization_endpoint e token_endpoint.
- In alternativa, nella sezione Credenziali, inserisci manualmente gli URL di Endpoint di autorizzazione personalizzato ed Endpoint token personalizzato.
|
La verifica del dominio non va a buon fine |
Certificato di dominio mostra "Verifica non riuscita" o "Verifica non riuscita" con un messaggio di descrizione comando (ad esempio HTTP 404, reindirizzamento non consentito o mancata corrispondenza del token). |
Google non è riuscita a verificare il tuo token di verifica all'indirizzo https://<domain>/.well-known/google-connected-apps. |
- File non trovato (HTTP 404): assicurati che i contenuti
google-connected-apps.json scaricati siano pubblicati all'indirizzo https://<domain>/.well-known/google-connected-apps (senza un'estensione .json nel percorso dell'URL).
- Reindirizzamenti non consentiti: pubblica il payload di verifica direttamente con
HTTP 200 OK; non reindirizzare /.well-known/google-connected-apps a un altro URL.
- Token non corrispondente: verifica che la risposta JSON contenga
"verification_tokens": ["<YOUR_TOKEN>"] con il token esatto generato per il tuo account sviluppatore.
|
Errore di Dynamic Client Registration (DCR) o CIMD |
"Dynamic Client Registration (RFC 7591) non riuscita", "Il server OAuth non supporta Dynamic Client Registration (RFC 7591)" o "Registrazione del documento dei metadati dell'ID client (CIMD) non riuscita" |
La registrazione automatica del client OAuth non è riuscita o non è supportata dal tuo provider OAuth oppure gli URI di reindirizzamento di Google sono stati rifiutati. |
- Assicurati che il tuo server OAuth inserisca nella lista consentita tutti e sei gli URI di reindirizzamento di Google specifici per l'app mostrati in Credenziali di autenticazione del server (
https://oauth-redirect.googleusercontent.com/r/<app-id>-<sanitized-domain> e così via). Tieni presente che molti server OAuth 2.1 rifiutano gli URI di reindirizzamento con caratteri jolly (*).
- Se il tuo provider OAuth non supporta CIMD o RFC 7591 DCR, seleziona Preregistrato (per OAuth delegato dall'utente) o Machine-to-machine (credenziali client OAuth) in Credenziali di accesso e fornisci un ID client e un client secret statici.
|
Popup di accesso OAuth bloccato o vuoto |
"Il popup di autenticazione è stato bloccato dal browser" o la finestra di accesso OAuth non viene visualizzata correttamente durante la sincronizzazione o il test dello strumento. |
I blocchi popup del browser o le intestazioni X-Frame-Options/Content-Security-Policy rigide nella pagina di accesso hanno impedito il flusso dei popup. |
- Consenti i popup per la console nel browser e riprova.
- In Access credentials (Credenziali di accesso) in Authenticate with your developer credentials (Autenticati con le tue credenziali di sviluppatore), passa da Authenticate via Pop up (Autentica tramite popup) ad Authenticate via Redirect (fallback) (Autentica tramite reindirizzamento (opzione di riserva)) in modo che il flusso di autenticazione si apra a schermo intero nella stessa scheda.
|
Istruzioni del server MCP mancanti |
Messaggio di avviso: "Il tuo server MCP non ha istruzioni. Ti consigliamo di aggiungere istruzioni allo schema del server." |
Il tuo server MCP non ha restituito un campo instructions nella risposta initialize. |
- Definisci esplicitamente le istruzioni di sistema durante l'inizializzazione del server MCP (parametro
instructions nella definizione del server).
- Per le implementazioni HTTP stateless o personalizzate, assicurati che il campo
instructions sia incluso nel payload della risposta JSON-RPC per il metodo initialize, quindi seleziona Strumenti di risincronizzazione.
|
Limite di dimensioni della risorsa UI o tipo MIME non supportato |
Scheda di errore Problemi con il recupero: "La dimensione cumulativa delle risorse non può superare i 100 MB" o "Tipo MIME '<type>' non supportato per la risorsa '<uri>'". |
Il tuo server MCP ha restituito risorse UI le cui dimensioni totali superano il limite o che utilizzano un tipo MIME non supportato. |
- Riduci le dimensioni cumulative di tutte le risorse UI del manifest restituite dal tuo server in modo che non superino il limite.
- Assicurati che tutte le risorse della UI utilizzino uno dei tipi MIME supportati:
text/html, text/html;profile=mcp-app, text/javascript o text/css.
|
Caricamento dell'icona bloccato o "Errore imprevisto" |
Quando carichi un'icona dell'app in Dettagli sull'app, il caricamento si blocca su un'icona di caricamento o viene visualizzato il messaggio "Si è verificato un errore imprevisto. Riprova" (spesso con il codice 4E696748). |
In genere, questo problema è causato da una sessione del browser obsoleta, da estensioni del browser in conflitto o da uno stato di autenticazione memorizzato nella cache. |
Prova a seguire questi passaggi nell'ordine indicato:
- Utilizza un nuovo profilo del browser: apri una nuova finestra utilizzando un profilo del browser pulito.
- Utilizza la modalità di navigazione in incognito/privata: accedi alla Google Connected Console in una finestra di navigazione privata e carica l'icona.
- Svuota la cache: svuota la cache ed elimina i cookie del browser prima di riprovare e verifica che l'icona sia un file PNG o JPEG valido di 512 x 512 px e di dimensioni inferiori a 1 MB.
|
