Toeverything·Pubblicato 20 ago 2026 · Aggiornato 21 ago 2026
Aggiungere un server MCP a Claude Code: guida e soluzioni
Produttività
L'essenziale in 30 secondi
Claude Code parla MCP nativamente: per un server remoto basta un comando claude mcp add e qualche minuto.
La configurazione vive in uno dei tre ambiti (local, project e user). Ciò che si condivide con il team va in project; le credenziali restano nell'ambito personale.
Claude Desktop ha due strade: Connettori per i server remoti, file di configurazione o estensione desktop per quelli locali. Le sue impostazioni sono indipendenti da quelle di Claude Code.
Il server non compare? Nella sessione, il comando /mcp mostra lo stato della connessione: parti sempre da lì.
Questa guida copre il comando claude mcp add e la logica degli ambiti, la configurazione in Claude Desktop, il percorso completo con un workspace AFFiNE come esempio e la checklist per quando non compare nulla. Se il concetto è ancora nuovo, parti da cos'è un server MCP.
Aggiungere server MCP a Claude Code
Per un server remoto (HTTP), il caso più comune con i servizi hosted:
Niente token da incollare? Molti servizi hosted, Notion e Sentry per esempio, usano OAuth: aggiungi il server senza --header, poi esegui /mcp nella sessione e completa l'accesso nel browser; dal terminale, claude mcp login fa lo stesso. Nota per chi arriva da guide datate: il trasporto SSE è deprecato, i server attuali parlano HTTP.
Per un server locale (stdio), che Claude Code esegue sulla tua macchina:
claude mcp add <nome> -- <comando-che-avvia-il-server>
La manutenzione sta tutta in tre sottocomandi: claude mcp list per vedere cosa è configurato, claude mcp get per i dettagli e claude mcp remove per eliminare. Se un prodotto fornisce il JSON già pronto, claude mcp add-json '' lo accetta così com'è. Durante la sessione, il comando /mcp mostra lo stato delle connessioni e gli strumenti disponibili: il primo posto dove guardare quando qualcosa non torna. Per i casi che questa guida non copre (WebSocket, credenziali OAuth pre-registrate, timeout) c'è il riferimento MCP ufficiale, disponibile anche in italiano.
Ambiti: local, project e user
Dove viene salvata la configurazione stabilisce chi la vede:
local (predefinito): questo progetto, questa macchina, solo tu. Per esperimenti e credenziali personali.
project: scritto in un file .mcp.json alla radice del repository, versionato e condiviso con tutto il team. È il posto dei server standard del team, come la base di conoscenza; ogni persona approva il server al primo utilizzo.
user (--scope user): vale per te in tutti i progetti della macchina. Per i server personali di uso quotidiano.
La regola pratica: le credenziali restano personali; via project si condivide solo la definizione del server, e ognuno fornisce il proprio token con una variabile d'ambiente. Il meccanismo è nativo: Claude Code espande ${VAR} dentro .mcp.json (vale per URL, header e env), quindi nel file condiviso scrivi "Authorization: Bearer ${AFFINE_TOKEN}" e ogni collega imposta la variabile sulla propria macchina.
Aggiungere in Claude Desktop
Server remoto: Impostazioni → Connettori → aggiungi connettore personalizzato, incolla l'URL e autorizza. È la strada senza terminale; per i server hosted come quello di AFFiNE o di Notion basta questa.
Server locale: modifica claude_desktop_config.json (Impostazioni → Sviluppatore → modifica configurazione), aggiungi il server sotto mcpServers e riavvia l'applicazione. Se il produttore distribuisce il server come estensione desktop (un pacchetto .mcpb), installarla da Impostazioni → Estensioni salta del tutto il passaggio dal JSON.
Gli stessi server funzionano in Claude Code e in Claude Desktop, ma ciascuna app conserva la propria configurazione. Due scorciatoie contro il doppio lavoro: claude mcp add-from-claude-desktop importa in Claude Code i server già configurati in Desktop (su macOS e WSL), e i connettori aggiunti su claude.ai compaiono in Claude Code da soli quando accedi con lo stesso account.
Dall'inizio alla fine: collegare la tua base di conoscenza
Il ciclo completo con il server MCP integrato di AFFiNE, che rende ricercabili documenti e lavagne del workspace da qualsiasi client MCP:
Crea la credenziale. In AFFiNE: Impostazioni → Integrations → MCP Server → Create credential. Usa il nome del client come etichetta («Claude Code»; una credenziale per client rende la revoca indolore), lascia l'accesso predefinito in sola lettura e imposta la scadenza.
Copia la configurazione. Il token appare una sola volta, accanto al pulsante Copy JSON che genera la configurazione completa: URL dell'endpoint e header di autenticazione inclusi. L'endpoint ha la forma https://app.affine.pro/api/workspaces//mcp; sulle istanze self-hosted c'è l'indirizzo del tuo server.
Usa. Apri una sessione e fai una domanda a cui solo i tuoi appunti sanno rispondere: «trova il progetto dei retry di pagamento e riassumi i punti aperti». Claude Code chiama lo strumento di ricerca (parole chiave + semantica, lavagne comprese), legge il documento in Markdown nei limiti dei tuoi permessi e risponde con i tuoi contenuti reali.
Nessun costo aggiuntivo: funziona su AFFiNE Cloud e sulle istanze self-hosted con le funzioni IA attive.
Il trasporto stabilisce dove viene eseguito il server; i permessi delle credenziali stabiliscono a quali strumenti e dati può accedere il client.
La stessa configurazione per Cursor e ChatGPT
Cursor legge ~/.cursor/mcp.json (o .cursor/mcp.json a livello di progetto). L'output Copy JSON di AFFiNE combacia con il formato di Cursor così com'è: incolla, riavvia, fatto.
ChatGPT si collega ai server MCP remoti tramite i connettori; i server personalizzati richiedono la modalità sviluppatore (Impostazioni → Connettori → Avanzate). Stesso endpoint, stesso header, nessuna modifica. Un server, tutti gli assistenti: è proprio questo il senso di MCP.
Risoluzione dei problemi: il server non compare
Scorri la lista in ordine; la stragrande maggioranza dei casi si chiude qui:
Prima /mcp. Lì vedi se il server è connesso, se l'autenticazione è fallita o se non è mai partito. Leggere l'errore mostrato batte qualsiasi ipotesi.
Trasporto sbagliato. Un server hosted richiede --transport http; senza il flag, Claude Code tratta l'URL come un comando locale. Rimuovi e riaggiungi con il flag.
Header scritto male. Il formato è Authorization: Bearer : un Bearer mancante o uno spazio di troppo diventa un 401 senza indizi. Non digitarlo a mano; incolla da Copy JSON.
Credenziale scaduta o revocata. Un token con scadenza prima o poi scade. Emetti una credenziale nuova e registrala di nuovo.
Ambito confuso. Un server aggiunto con ambito local non esiste negli altri progetti. Esegui claude mcp list nella cartella dove ti aspettavi di trovarlo: il dubbio si chiude in dieci secondi.
Server di progetto mai approvato. Quelli condivisi via .mcp.json non partono finché non li approvi: claude mcp list li segnala come «Pending approval». Apri claude in quel repository e conferma; per ripartire da zero con le approvazioni, claude mcp reset-project-choices.
Dipendenza mancante nel server locale. Un server stdio esegue un comando; senza il runtime installato muore all'avvio. Esegui quel comando a mano una volta e leggi l'errore vero.
Si connette ma non viene usato. Le prime volte, cita la fonte nella richiesta («cerca nel mio workspace AFFiNE...»). Stabilito lo schema, Claude sceglie da solo lo strumento giusto.
Impostazioni di sicurezza da mantenere
Sola lettura finché scrivere non serve. Una connessione alla base di conoscenza raramente ha bisogno di scrivere; le credenziali AFFiNE nascono in sola lettura e la scrittura è in rilascio progressivo.
Una credenziale per client. Revocare il portatile non deve buttare giù il desktop. Con la scadenza impostata, la rotazione diventa ordinaria amministrazione.
Approvazione consapevole degli strumenti. Claude chiede prima di usare uno strumento nuovo, e i server condivisi via project si approvano al primo utilizzo. Non disattivare queste conferme per strumenti che possono modificare dati. La checklist completa è nella nostra guida alla sicurezza MCP (in inglese).
Domande frequenti
Qual è il comando per aggiungere un server MCP a Claude Code?
Il comando claude mcp add: per i server hosted con --transport http, URL e header di autenticazione; per i locali con il comando di avvio. Verifica con claude mcp list e, in sessione, /mcp mostra subito lo stato.
Claude Desktop supporta i server MCP?
Sì. I server remoti si aggiungono da Impostazioni → Connettori come connettore personalizzato; quelli locali vanno in claude_desktop_config.json, sotto mcpServers, con riavvio — oppure arrivano come estensione desktop, quando il produttore la offre. Unica attenzione: la sua configurazione è separata da quella di Claude Code.
Che differenza c'è tra gli ambiti local, project e user?
local vale per te in un solo progetto; project scrive un .mcp.json condiviso nel repository per tutto il team; user vale per te in tutti i progetti della macchina. Le credenziali restano sul lato personale: via project si condivide solo la definizione del server.
Dove viene salvata la configurazione dei server MCP?
Per Claude Code, gli ambiti local e user vivono in ~/.claude.json nella tua home (local sotto la voce del singolo progetto), mentre project scrive .mcp.json alla radice del repository, pensato per finire nel controllo versione. Claude Desktop usa un file a parte, claude_desktop_config.json. Modificarli a mano si può, ma i comandi claude mcp tengono il JSON valido e ti risparmiano la caccia alla virgola.
Claude Code può collegarsi a server MCP remoti?
Sì. I server remoti in Streamable HTTP sono supportati ufficialmente con --transport http e header di autenticazione. Gli endpoint hosted, come quello del workspace AFFiNE, si collegano senza alcun processo locale da mantenere.
Come mi autentico con un server MCP che usa OAuth?
Aggiungi il server senza header, poi esegui /mcp nella sessione e completa l'accesso nel browser; dal terminale, claude mcp login fa lo stesso senza aprire una sessione. I token vengono conservati e rinnovati in automatico, e la voce «Clear authentication» nel menu /mcp revoca l'accesso quando non ti serve più.
Perché il mio server non compare nell'elenco?
Controlla lo stato con /mcp e poi i soliti sospetti: manca --transport http su un server remoto, header Authorization malformato, credenziale scaduta o ambito confuso (local esiste solo nel progetto dove è stato aggiunto). Questi quattro spiegano quasi tutto.
Usare MCP con Claude costa qualcosa?
Il supporto MCP è incluso senza costi extra in Claude Code e Claude Desktop, e il protocollo è uno standard aperto. Le condizioni variano da server a server; quello integrato di AFFiNE, per esempio, è gratuito su Cloud e sulle istanze self-hosted con IA attiva.
In sintesi
Collegato il primo server, il secondo va da sé: la procedura è identica ovunque. Parti dal posto dove passi la giornata a cercare risposte: il tuo workspace.