Risolvere i problemi di una connessione MCP a dosya

Parti dall’errore esatto e dal primo punto in cui si verifica il problema. Se un client non riesce a rilevare il server, il problema riguarda il trasporto; se elenca gli strumenti ma non riesce a chiamarne uno, può riguardare autorizzazione, ambito, spazio di lavoro, visibilità, utilizzo o conversione. Riconnettersi per ogni errore può eliminare informazioni utili e non risolve un guasto temporaneo del servizio.

Passaggi

L’URL del server è https://mcp.dosya.dev/mcp e usa Streamable HTTP remoto su HTTPS e OAuth tramite browser. Non configurare /sse, un comando stdio locale, una chiave API dos_…, un token mobile o la password di dosya.

Il client deve supportare il rilevamento OAuth, il codice di autorizzazione con PKCE, la registrazione dinamica del client e il trasporto remoto. Se la configurazione accetta solo un comando da eseguire localmente o un’intestazione bearer statica, quella modalità non può completare l’autorizzazione a dosya. Verifica che il piano del client o l’amministratore dell’organizzazione consenta i connettori remoti.

Quando si apre la schermata di consenso, controlla l’account, la destinazione del callback e Spazio di lavoro accessibile in lettura. Lettura di file e cartelle (files.read) è obbligatorio. Lettura del piano e dello spazio di archiviazione (account.read) è facoltativo e serve solo a get_account_info. La procedura di consenso scade dopo 10 minuti; riavviala dal client se la pagina del browser è rimasta aperta più a lungo.

Usa il messaggio restituito per scegliere come risolvere

Messaggio o sintomo	Significato e azione successiva
La pagina di consenso nel browser non si apre	Ricontrolla l’URL esatto del server, il supporto HTTP/OAuth remoto e l’accesso di rete sia a mcp.dosya.dev sia a api.dosya.dev. Una chiave API non è un trasporto alternativo.
Non hai uno spazio di lavoro leggibile da questa app. Gli spazi crittografati da un capo all’altro non possono essere collegati.	Accedi a uno spazio di lavoro ordinario leggibile o selezionalo. Vault e Space crittografati sono esclusi intenzionalmente da questo connettore.
This connection is not authenticated. Sign in to dosya again to reconnect.	Il token di accesso o l’autorizzazione non è valido, è scaduto o è stato revocato. Avvia una nuova autorizzazione nel client.
dosya could not be reached just now. This is temporary: try again in a moment. Do not reconnect.	Mantieni l’autorizzazione e riprova quando il servizio è di nuovo disponibile. Autorizzare di nuovo non risolve il problema della dipendenza.
Il client elenca gli strumenti ma get_account_info viene rifiutato	Rinnova l’autorizzazione con account.read solo se servono informazioni sul piano o sullo spazio di archiviazione. Gli strumenti per i file continuano a usare files.read.
Not visible to this connection.	Verifica lo spazio di lavoro selezionato, l’appartenenza attuale, la limitazione alla cartella, il ruolo, l’eventuale stato nascosto o bloccato e l’ID attuale del file in dosya. Un altro ID di spazio di lavoro in un argomento dello strumento non può ampliare l’autorizzazione.
dosya is rate limiting this connection right now. Wait a minute, then try again.	Interrompi le chiamate parallele e attendi almeno il minuto indicato prima di riprovare. Riconnettersi non aumenta il limite.
La quota giornaliera di letture o conversioni di immagini è esaurita	Le connessioni gratuite consentono 100 letture di file e 25 conversioni di immagini al giorno UTC. Attendi le 00:00 UTC o usa un piano a pagamento idoneo; le chiamate per metadati ed elenchi sono conteggiate separatamente.
Un cursore di continuazione non è valido o è obsoleto	Riavvia read_file senza il cursore e usa la versione attuale del file. Non puoi combinare finestre di versioni diverse del file.

Risultato previsto

Chiedi al client di eseguire list_workspaces con {}. Una risposta corretta identifica esattamente lo spazio di lavoro fissato durante il consenso. Se mostra quello sbagliato, apri Impostazioni → App IA collegate in dosya, disconnetti la riga corrispondente a quel client e a quello spazio di lavoro, poi autorizza di nuovo selezionando quello desiderato.

Poi esegui list_folder con {"page":1,"per_page":5} e senza ID cartella. La dimensione predefinita della pagina è 25 e l’intervallo consentito è 1–100. Un’appartenenza limitata parte dal punto di accesso consentito. Confronta i nomi restituiti con la vista File di dosya per lo stesso account, senza chiedere al modello di leggere un file riservato.

dosya espone nove strumenti in sola lettura. Non ha strumenti MCP per caricare, modificare, condividere o eliminare. Se dopo OAuth il client non mostra strumenti, rimuovi e aggiungi di nuovo il connettore o aggiorna il rilevamento; permessi più ampi sui file non possono far comparire strumenti di scrittura inesistenti.

Diagnostica i problemi di lettura dei file e dei link di download

read_file può restituire finestre di testo fino a 100.000 caratteri per impostazione predefinita. La conversione normalmente accetta file di origine supportati fino a 26.214.400 byte (25 MiB) e ha un limite di 45 secondi; le impostazioni di distribuzione possono ridurre questi valori. Per un tipo non supportato o un file troppo grande, usa i metadati o get_download_link quando l’accesso è consentito.

Un URL generato per il file originale dura 300 secondi. Chiunque lo possieda può scaricare il file fino alla scadenza, quindi non incollarlo in log pubblici o messaggi all’assistenza. La generazione di un link o la conversione di contenuti può registrare attività di accesso o utilizzo anche se il connettore non può modificare i file archiviati.

I token di accesso OAuth durano un’ora e devono essere aggiornati dal client. Una connessione deve essere autorizzata di nuovo dopo 30 giorni di inutilizzo o dopo 180 giorni complessivi. A ogni chiamata vengono ricontrollati perdita dell’appartenenza, stato dell’account e modifiche al piano. La disconnessione può richiedere fino a 60 secondi per raggiungere un token già accettato dalla cache di convalida e non può richiamare contenuti, trascrizioni o URL di download già ricevuti dall’applicazione esterna.

Contatta l’assistenza con informazioni sicure

Se list_workspaces continua a non funzionare, annota nome e versione del client, URL del server, ora approssimativa e fuso orario, fase raggiunta, messaggio esatto privo di dati segreti e presenza o meno del consenso in App IA collegate. Non includere nel ticket token bearer, codici di autorizzazione, URL di download firmati o contenuti dei file.

Guide correlate

• Connettere MCP
• Disconnettere un’app di IA
• Contattare l’assistenza