Dove ogni client MCP tiene la sua configurazione

Aggiungi lo stesso server MCP a due strumenti diversi e ti ritrovi con due file, in due posti, con due nomi di chiave diversi, uno dei quali non fa niente e non te lo dice. Non è che stai sbagliando tu. È lo stato reale dell'ecosistema, e ha una causa precisa e comprensibile.

Il protocollo è standard. Il file di configurazione non lo è mai stato.

MCP è stato introdotto da Anthropic alla fine del 2024 e rilasciato come standard aperto. Quello standard copre il protocollo di trasporto: come client e server si parlano, come i tool vengono elencati e chiamati, quali trasporti sono ammessi.

Quello che non ha mai coperto è come un client debba tenere su disco il suo elenco di server. È stato lasciato a ciascun client, e ciascun client se l'è puntualmente inventato. La prima forma copiata su larga scala è arrivata da Claude Desktop, la cui configurazione usava un oggetto mcpServers alla radice. Quasi tutti l'hanno seguita, perché era l'unica che esistesse. Qualcuno no.

Due domande che vengono continuamente fuse in una

Quasi tutta la confusione nasce dal trattarle come una domanda sola, mentre sono indipendenti:

• Quale file legge il client? Decide l'ambito. Un file dentro il repository vale per quel progetto e si può committare e condividere. Un file nella tua home vale per ogni progetto della tua macchina e riguarda solo te.
• Che forma ha il contenuto? Decide cosa incolli: la chiave di radice, e se il file è JSON o TOML.

Per quasi tutti gli strumenti, i due file, quello di progetto e quello globale, contengono esattamente la stessa cosa. Incolli lo stesso blocco, cambia solo la posizione. Ed è per questo che la frammentazione è fastidiosa più che difficile: le forme vere sono meno dei percorsi dei file.

La mappa

Va letta per modalità, non come un elenco di strumenti. Ogni riga è un modo di scrivere il server, e l'ultima colonna dice chi legge in quel modo. Uno strumento può stare su due righe: Claude Code accetta un blocco JSON standard in un file, ma il modo previsto per aggiungere un server è il comando claude mcp add, quindi compare due volte.

Corretto al momento della scrittura. Questa roba si muove, quindi se qualcosa non si collega controlla il tuo strumento.

L'oggetto mcpServers nudo è la forma più diffusa, ma "più diffusa" non vuol dire "standard": le righe che se ne discostano sono più o meno tante quante quelle che la seguono.

La colonna dell'ambito vale per la modalità, non è una promessa su ogni strumento della riga. LM Studio, nella prima riga, ha solo il file globale: non esiste l'equivalente di progetto.

La tabella si ferma alla chiave di radice e all'ambito. Due cose che lascia fuori contano nella pratica: diversi strumenti vogliono un campo in più dentro la voce del server, e uno di questi non è nemmeno JSON. Sono entrambe qui sotto.

L'unico file che più di un fornitore legge

Guarda i nomi dei file. .vscode/mcp.json e .cursor/mcp.json stanno dentro una cartella che porta il nome di un prodotto. Sono privati per costruzione: quel file lo legge quel programma e nient'altro. Se tu usi Cursor e un collega usa VS Code, tenete due file con lo stesso contenuto e dovete ricordarvi entrambi di aggiornarli.

.mcp.json sta nella radice del repository e non porta il nome di nessun fornitore. È tutto il punto. Oggi lo leggono Claude Code e l'Agent Host di VS Code con GitHub Copilot CLI: due fornitori concorrenti, un file solo. Microsoft ha spinto attivamente chi usa Copilot CLI a spostare la propria configurazione da .vscode/mcp.json verso di lui.

È questo che qui significa "portabile", e vale la pena essere precisi sui limiti. Il contenuto non ha niente di speciale: è lo stesso oggetto mcpServers che usa Cursor. Quello che è portabile è la posizione, un nome neutro che nessuno rivendica. Ed è portabile fra i client che hanno scelto di leggerlo, non universalmente. Niente obbliga un client nuovo a guardare lì.

Se stai preparando un repository per un team, è questo il file da scrivere. Viene committato insieme al codice, e chiunque cloni il progetto si ritrova il server già configurato, con qualunque strumento lo apra.

Le eccezioni, e perché non sono arbitrarie

VS Code usa servers nel suo file, e vuole che il trasporto sia dichiarato esplicitamente con un campo type. C'è una segnalazione aperta da tempo che gli chiede di accettare anche la chiave comune; il report elenca altri sette client che usano tutti mcpServers e fa notare che gli script di installazione devono trattare VS Code come un caso a parte. Resta di gran lunga la causa più frequente di una configurazione che sembra giusta e non fa niente.

GitHub Copilot CLI usa la chiave comune mcpServers, ma come VS Code vuole type: "http" scritto dentro ogni voce di server. Se lo ometti, la voce viene letta e scartata senza una parola. Il file condiviso .mcp.json che legge ha lo stesso requisito.

Antigravity tiene la chiave di radice comune ma chiama l'indirizzo serverUrl invece di url, una differenza di una parola che è facilissimo non vedere. In compenso altrove è insolitamente ordinato: dalla 2.x il builder desktop, l'IDE e la CLI condividono una configurazione sola, quindi il server lo imposti una volta per tutti e tre. Non ha alcun file di progetto.

opencode annida i server sotto mcp e richiede type: "remote" su ogni voce remota. Un blocco copiato da uno strumento che usa la forma comune lì non funziona: la chiave è sbagliata e manca il campo obbligatorio.

Codex non è JSON. La sua configurazione è TOML, e i server vanno sotto [mcp_servers.<nome>] in ~/.codex/config.toml, nella tua home e non nel progetto.

Claude Desktop non ha un file da modificare

Una riga della tabella qui sopra c'è solo per dire che non c'è niente da incollare. Claude Desktop i server MCP remoti non li prende affatto da un file di configurazione. Il file claude_desktop_config.json serve per i server locali. Quelli remoti si aggiungono dalle Impostazioni, sotto Connectors, incollando l'indirizzo del server dentro una finestra. Non c'è niente da copiare in un file.

Se il tuo server si autentica con un token fisso invece che con OAuth, quella finestra ha una sezione Request headers dove inserisci il valore dell'header esattamente come il server se lo aspetta, parola Bearer e spazio compresi, perché Claude manda il valore alla lettera e non aggiunge alcun prefisso. I nomi degli header sono limitati a un elenco approvato. Al momento della scrittura questa possibilità è in beta e viene distribuita gradualmente, quindi potrebbe non essere ancora visibile sul tuo account.

Uno standard è stato proposto. Non è ratificato.

Nel repository del protocollo c'è una proposta aperta, chiamata SEP-2633, per un formato unico di configurazione lato client: un file chiamato mcp.json con la solita chiave di radice mcpServers. La motivazione dichiarata è esattamente la situazione descritta qui sopra: ogni client si è inventato nome del file, formato e chiave di radice.

È ancora una bozza, e le questioni aperte non sono di forma: se debba stare nel protocollo di base o in un'estensione separata, come vada espresso OAuth, come vadano gestiti i segreti. Trattala come una direzione di marcia, non come qualcosa su cui contare. Chi ti dice che un formato di configurazione standard esiste già sta descrivendo una consuetudine, non una specifica.

Cosa farci

Tre abitudini tolgono quasi tutto il fastidio. Primo, scegli l'ambito di proposito: nel progetto quando deve arrivare a tutto il team, nella tua home quando è tuo. Secondo, quando un server sembra collegarsi ma non espone niente, controlla la chiave di radice prima di qualunque altra cosa: è il modo in cui questo ecosistema fallisce più spesso, e fallisce in silenzio. Terzo, occhio ai link di installazione a un click: i gestori di VS Code e di Cursor accettano solo la configurazione del server e non ti lasciano scegliere dove finisce, quindi scrivono nella tua configurazione globale, che sia quello che volevi o no.

E quando un file di configurazione viene ignorato in silenzio, cosa che capita con percorsi che sembrano plausibili ma che lo strumento non legge mai, non ricevi alcun errore. Il server semplicemente non compare. Se una configurazione non funziona e nessuno si lamenta, sospetta della posizione prima che del server.