Collegare un client MCP a dosya

Collega il client remoto Model Context Protocol (MCP) della tua app IA a https://mcp.dosya.dev/mcp. dosya usa Streamable HTTP con autorizzazione OAuth, non una chiave API. Il connettore attuale è di sola lettura: trova e legge i file consentiti e fornisce link di download, ma non può caricare, modificare, condividere o eliminare file.

Controlla supporto e accesso del client

Il client richiede Streamable HTTP remoto su HTTPS, rilevamento OAuth, supporto authorization-code/PKCE e registrazione dinamica del client. Un client che offre solo server locali a comando/stdio o solo intestazioni statiche con chiave API non può completare la connessione. Piani e amministratori del client possono controllare la disponibilità dei connettori remoti; consulta le istruzioni ufficiali attuali dell’app. La pagina di consenso dosya riconosce i domini di callback Claude e ChatGPT, ma questo non certifica ogni versione né rende attendibile un client che si nomina da solo.

Usa un account dosya membro dello spazio di lavoro da esporre. Gli Spaces crittografati da un capo all’altro e il Vault non sono collegati. L’autorizzazione è vincolata a un solo spazio scelto e l’accesso ai file resta soggetto ad appartenenza, confinamento alle cartelle, contenuti nascosti o bloccati e ruolo a ogni chiamata. La connessione IA non può rivelare un file che il tuo account non può leggere.

Passaggi: autorizza il server remoto

1. Nella configurazione del server remoto o connettore del client, assegna un nome riconoscibile alla connessione e inserisci l’URL completo https://mcp.dosya.dev/mcp. Scegli HTTP/Streamable HTTP se puoi scegliere il trasporto. Non configurare un comando shell né sostituire /mcp con /sse.
2. Avvia la connessione o autorizzazione dal client. Questo rileva la risorsa protetta sull’host MCP e il server di autorizzazione su https://api.dosya.dev. Registrazione dinamica, scambio e rinnovo dei token sono gestiti dal client. Non incollare chiavi API dos_…, token mobile o password dell’account in un campo di intestazione bearer.
3. Nella schermata di consenso dosya nel browser controlla account e destinazione del callback. Un client ospitato riconosciuto mostra Verified: …; un callback locale o sconosciuto mostra Not verified · sends to …. I client loopback locali non sono automaticamente verificati: approva solo se hai appena avviato tu l’applicazione. Il nome registrato è autodichiarato.
4. In Spazio di lavoro accessibile in lettura, scegli lo spazio di lavoro previsto. Lettura di file e cartelle (files.read) è obbligatorio. Lettura del piano e dello spazio di archiviazione (account.read) è facoltativo se richiesto; lascialo disattivato se il client non ha bisogno dell’utilizzo dell’account. Il consenso elenca anche le capacità escluse: modificare, condividere, eliminare e aprire altri spazi di lavoro o il Vault.
5. Scegli Consenti (o Allow Claude/ChatGPT per client riconosciuti), torna al client iniziale e attendi la conclusione. Nega abbandona l’autorizzazione. La richiesta di consenso scade dopo 10 minuti; riavvia dal client se è scaduta.

Questi sono valori di connessione, non uno schema JSON universale specifico per client:

Server URL: https://mcp.dosya.dev/mcp
Transport: Streamable HTTP
Authorization: OAuth through the browser
Required scope: files.read
Optional scope: account.read
Workspace: selected on the Dosya consent page

Verifica con una chiamata di sola lettura

Chiedi al client di eseguire list_workspaces con un oggetto argomenti vuoto {} e mostrare ID e nome restituiti. Il suo structuredContent.workspaces dovrebbe identificare solo lo spazio autorizzato. Questo verifica la connessione senza leggere il contenuto di un file. Se indica lo spazio sbagliato, scollega l’autorizzazione e ripeti; aggiungere un altro ID agli argomenti non può ampliarla.

Se vuoi, esegui poi list_folder con {"page":1,"per_page":5}. Omettere la cartella usa la radice accessibile; per un membro confinato si risolve nell’ancoraggio consentito. Confronta i nomi restituiti con File in dosya. Gli elenchi mostrano 25 voci per pagina per impostazione predefinita e accettano 1–100. Fermati prima di chiedere al modello di leggere contenuti riservati solo per provare l’accesso.

Cosa può ricevere il client

Strumento	Risultato o capacità
list_workspaces	Identificativi e nomi degli spazi di lavoro autorizzati.
list_folder, search_files	Voci di cartelle e file consentite e paginazione; la ricerca usa nome o query, non esplora liberamente tutti gli account.
get_file_info	Nome, dimensione in byte, tipo, versione corrente, cartella/spazio e URL web senza leggere il contenuto.
read_file	Testo estratto o descrizione immagine, con metadati di sorgente e versione e cursore se troncato.
get_download_link	URL valido 300 secondi e expires_in_seconds per scaricare l’originale. Chiunque lo possieda può usarlo fino alla scadenza.
get_account_info	Piano e uso dello spazio dell’account; richiede l’ambito facoltativo account.read.
search, fetch	Ricerca per nome e testo dei documenti compatibili con la ricerca, con link alle fonti.

Ci sono 9 strumenti e nessuno scrive, carica o elimina. Emissione di link di download e conversione del testo generano comunque attività di accesso o utilizzo, pur senza modificare i file. Il client riceve il contenuto leggibile che scegli di esporre; questo può entrare nella chat o cronologia dell’app IA secondo le sue impostazioni. Scollegare dopo non richiama byte o conversazioni già ricevuti. Non inserire URL di download firmati in chat o registri pubblici.

Limiti, durata e nuova autorizzazione

Il piano gratuito consente 100 letture di file e 25 conversioni di immagini per connessione per giorno UTC. I piani a pagamento non hanno un limite giornaliero di queste operazioni MCP; restano applicabili frequenza delle richieste, traffico di download in uscita e altri limiti API. Elenchi e metadati non eseguono la lettura del testo. Ogni finestra di testo richiesta può contare come lettura, anche da estrazione in cache. I conteggi si azzerano alle 00:00 UTC; attendi l’azzeramento indicato nella risposta invece di riprovare ripetutamente.

La finestra di testo predefinita distribuita è di 100.000 caratteri. La conversione normalmente accetta file sorgente fino a 26.214.400 byte (25 MiB) con un termine di 45 secondi; le impostazioni di distribuzione possono cambiare questi limiti. Tipi troppo grandi o non supportati possono usare get_download_link se consentito. read_file restituisce truncated, cursor, offset, total_chars, file_version e informazioni sulla sorgente. Continua con il cursore restituito e riparti senza di esso se cambia la versione; mescolare finestre di versioni diverse viene rifiutato.

I token di accesso OAuth durano 1 ora. Il client li rinnova; la connessione scade dopo 30 giorni senza uso e comunque entro 180 giorni, quando serve una nuova autorizzazione. Non c’è una sessione MCP persistente da gestire al posto dell’autorizzazione OAuth. Blocco o eliminazione dell’account e cambi di piano sono verificati alle chiamate; la perdita dell’appartenenza allo spazio blocca gli accessi successivi.

Risolvi errori di autorizzazione e strumenti

Risposta o stato	Passaggio successivo
Il consenso nel browser non si apre	Controlla supporto HTTP remoto/OAuth/DCR e rete verso host MCP e API. Una chiave API non è un’alternativa.
Non hai uno spazio di lavoro leggibile da questa app. Gli spazi crittografati da un capo all’altro non possono essere collegati.	Usa uno spazio ordinario e appartenenza consentiti, non uno Space crittografato.
This connection is not authenticated. Sign in to dosya again to reconnect.	Riavvia l’autorizzazione dopo aver controllato scadenza o revoca.
dosya could not be reached just now. This is temporary: try again in a moment. Do not reconnect.	Attendi e riprova; un’interruzione dell’infrastruttura è diversa da una revoca.
Permesso account.read mancante	Concedi l’ambito facoltativo con una nuova autorizzazione se vuoi get_account_info; gli altri strumenti file usano files.read.
Not visible to this connection.	Controlla spazio di lavoro, confinamento, ruolo e stato del file in dosya. Non provare l’ID di un altro account.
dosya is rate limiting this connection right now. Wait a minute, then try again.	Riduci le chiamate parallele e attendi almeno il minuto indicato.
Rifiuto per conversione, tipo o dimensione	Usa il link di download originale se necessario oppure fornisci un documento supportato più piccolo.
Cursore non valido o scaduto	Riavvia read_file senza il vecchio cursore e usa la versione attuale.

Scollega e cambia spazio di lavoro

Apri Impostazioni → App IA collegate in dosya, individua la riga esatta di client e spazio di lavoro e fai clic su Scollega. Rimuovi il connettore anche dal client IA se non vuoi più che sia offerto. La revoca ferma i nuovi controlli di autorizzazione, ma un token già validato può funzionare fino a 60 secondi perché la validazione riuscita è in cache. Byte scaricati, testo esposto e URL di download già emessi non vengono cancellati dalla disconnessione.

Per cambiare spazio di lavoro, revoca la vecchia autorizzazione e collegati di nuovo con la nuova scelta. Concedere, negare o scollegare l’app IA non cambia i file archiviati.

Risultato previsto

Il client rileva gli strumenti di sola lettura dosya, list_workspaces identifica l’autorizzazione prevista e un elenco consentito corrisponde all’app web. Puoi esaminare e revocare quella connessione in Connected AI apps senza gestire una chiave API.

Guide correlate

• Esaminare i permessi delle app IA
• Provare un’operazione MCP di sola lettura