MCP connesso ma non funziona? Individua il problema in Mono

Un server MCP salvato non significa che lo strumento funzioni. L’indirizzo può essere giusto mentre l’accesso non è finito. L’accesso può riuscire mentre gli strumenti del server non si caricano. E uno strumento può caricarsi ma ricevere comunque una richiesta sbagliata. Trova il primo passaggio che fallisce prima di cambiare qualsiasi impostazione.

Questa guida riguarda la risoluzione dei problemi in Mono by Reunified, che non è ancora disponibile (iscriviti alla lista d’attesa). Per un primo collegamento usa la guida alla configurazione MCP. Qui l’obiettivo è trasformare un vago «non funziona» in un’osservazione chiara e ripetibile, senza ripetere per sbaglio una scrittura.

1. Registra il sintomo e interrompi i tentativi incerti

Annota nome del server, trasporto, dispositivo, versione dell’app, cosa stavi cercando di fare e l’errore esatto, senza segreti. Indica se la stessa configurazione funzionava prima e cosa è cambiato da allora. «L’elenco degli strumenti è vuoto dopo l’accesso» è più utile di «MCP è rotto».

Se l’ultima richiesta poteva creare, inviare o aggiornare qualcosa, controlla la destinazione prima di riprovare. Una risposta persa non significa che l’azione non sia avvenuta. Per i test passa a una piccola richiesta di sola lettura, come elencare un elemento in un progetto di prova che puoi controllare.

Tieni in privato una copia delle ultime impostazioni funzionanti. Non incollare token, codici di autorizzazione o risultati privati degli strumenti in una richiesta di supporto pubblica.

2. Controlla il trasporto prima dell’account

Una connessione HTTP in Mono ha bisogno dell’indirizzo di un server MCP, non di una normale home page o dell’indirizzo dell’API di un modello. Confronta l’URL completo, percorso compreso, con la documentazione attuale di chi pubblica il server. Una pagina che si apre nel browser dimostra solo che quella pagina è raggiungibile, non che MCP funzioni lì.

Con Input/output standard (stdio), controlla comando e argomenti sul dispositivo che deve avviarli. Rifare l’accesso non risolve un comando mancante o un dispositivo che non può eseguirlo. Telefoni e computer sono diversi, quindi non aspettarti che un comando da computer funzioni su un telefono.

Un indirizzo con localhost indica il dispositivo che invia la richiesta. Prova dal dispositivo reale, tramite un percorso supportato e con accesso effettuato. Non indebolire i controlli di accesso di un server che funziona solo per far passare un test.

3. Distingui impostazioni salvate e autorizzazione completata

Controlla il metodo di autenticazione scelto. Un Token Bearer richiede il token giusto del servizio nel suo campo. OAuth richiede l’account giusto, i requisiti del server e un ritorno completo a Mono; chiudere il browser troppo presto non è un accesso riuscito.

Mono può salvare un server prima che l’accesso sia finito, quindi un server salvato non dimostra che l’accesso abbia funzionato. Anche dopo un accesso riuscito, il caricamento degli strumenti del server può fallire per un po’. Né una voce salvata né un messaggio «Connesso a» dimostrano che uno strumento preciso sia pronto.

Se cambi l’URL o il trasporto del server, Mono lo considera una nuova connessione, quindi potresti dover rifare l’accesso. Correggi un vero errore di indirizzo, ma non cambiare di continuo un URL che funziona come se fosse un reset generico. Segui le impostazioni di client e reindirizzamento documentate da chi pubblica il server invece di inventare valori.

4. Verifica capacità e modello selezionato

L’architettura MCP distingue strumenti, risorse e prompt. Un server può offrirne solo alcuni, quindi un server che offre solo risorse non darà all’assistente nessuno strumento da chiamare.

Per uno skill MCP installato, apri la sua sezione Configurazione per vedere gli strumenti trovati da Mono. Se è vuota, controlla l’accesso e se il server elenca i suoi strumenti; non dare per scontato che ogni azione del servizio sia disponibile. Salvare un server non è un controllo completo del suo stato.

Controlla anche il modello usato nella chat. Non tutti i modelli sanno chiamare strumenti, compresi alcuni che colleghi tu. Un modello che risponde bene in testo può comunque essere il motivo per cui uno strumento collegato non viene mai usato. La guida agli endpoint personalizzati lo spiega.

5. Prova un’operazione conosciuta

Usa una richiesta innocua e confronta il risultato con il servizio originale:

Leggi il titolo dell’elemento dimostrativo esistente che indico.
Non creare, modificare, inviare o eliminare nulla.
Se l’accesso fallisce, segnala il problema invece di indovinare il titolo.

L’errore di uno strumento è diverso da un risultato vuoto ma riuscito. Conserva insieme lo stato restituito e il testo rilevante, senza segreti.

6. Verifica la soluzione e conserva una traccia

Cambia una cosa alla volta, ripeti lo stesso test di sola lettura e annota il risultato. Se in seguito ti serve una scrittura, controlla la destinazione esatta e conferma il risultato nel servizio prima di riprovare.

Tieni una breve nota del passaggio che fallisce, delle versioni, della modifica fatta e dell’ultimo test riuscito. Rimuovere una connessione in Mono e revocare l’accesso presso il fornitore sono passaggi separati. Per decidere i permessi durante l’uso, leggi la guida ai permessi degli strumenti; approvare più e più volte non ripara una connessione.