.mcp.json in Claude Code: ambiti e risoluzione dei problemi

Il formato di .mcp.json

Un file di progetto con un server remoto e un server locale è fatto così:

{
  "mcpServers": {
    "hosttracker": {
      "type": "http",
      "url": "https://mcp.host-tracker.com/mcp"
    },
    "local-tool": {
      "type": "stdio",
      "command": "/path/to/executable",
      "args": ["--flag", "value"],
      "env": { "KEY": "value" },
      "timeout": 600000
    }
  }
}

Il campo type è obbligatorio ogni volta che è presente url. Un url senza type viene segnalato come errore di configurazione (il messaggio dice di aggiungere "type": "http", oppure sse o ws), il che ha sostituito un vecchio messaggio molto meno utile su un command mancante. Il valore streamable-http è accettato come alias di http. Un server remoto che richiede una credenziale fissa usa un oggetto headers; uno locale usa command, args ed env. Il timeout opzionale è un limite per singola chiamata a uno strumento, in millisecondi. I server WebSocket possono essere dichiarati solo in un file o tramite claude mcp add-json; il flag --transport non accetta ws.

Il comando claude mcp add con --scope project scrive questo file per te, quindi modificarlo a mano serve solo per campi che il comando non espone, o quando preferisci rivedere la modifica in una pull request.

Tenere i segreti fuori dal file

Poiché .mcp.json è pensato per essere sottoposto a commit, i token non dovrebbero esservi scritti direttamente. Claude Code espande le variabili d'ambiente in command, args, env, url e headers: ${VAR} prende il valore della variabile, e ${VAR:-default} ripiega sul valore predefinito quando non è impostata.

{
  "mcpServers": {
    "secure-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

Una variabile referenziata che non è impostata e non ha un valore predefinito non impedisce il caricamento del server; il testo letterale ${API_KEY} viene inviato così com'è, e claude mcp list stampa un avviso. Quell'avviso è la prima cosa da controllare quando un server si connette ma ogni chiamata viene rifiutata come non autorizzata.

Per un server che supporta OAuth non c'è proprio nulla da nascondere: lascia la voce con solo type e url, e ogni utente accede una volta da /mcp. Il token viene memorizzato per singolo utente, fuori dal repository, e rimosso di nuovo con claude mcp remove.

Approvazione, precedenza e server gestiti

La prima volta che Claude Code vede un server nel .mcp.json di un progetto, una sessione interattiva chiede se usarlo; le esecuzioni non interattive (claude -p, l'Agent SDK, le sessioni cloud) lo caricano senza chiedere. La decisione viene ricordata per progetto; claude mcp reset-project-choices la dimentica, così puoi riapprovare dopo una modifica.

Quando lo stesso nome è definito in più punti, l'ordine è ambito locale, poi ambito progetto, poi ambito utente, poi i server forniti dai plugin, poi i connettori da claude.ai. Viene usata l'intera voce vincente. Le organizzazioni possono imporre un elenco fisso di server tramite un file di configurazione gestito o l'impostazione managedMcpServers (Claude Code 2.1.259 o successivo); questi hanno la precedenza su ogni ambito a livello utente, e un file gestito che rivendica il controllo esclusivo fa rifiutare claude mcp add con un messaggio che segnala una configurazione aziendale attiva. Le liste di consenso e di blocco (allowedMcpServers, deniedMcpServers) possono anche limitare quali URL o comandi gli utenti possono aggiungere, e un blocco vince sempre.

Leggere l'output di stato

claude mcp list riporta ogni server come connesso, richiede autenticazione, connessione fallita, in attesa di approvazione, rifiutato tramite disabledMcpjsonServers, oppure disabilitato per questo progetto. Vale la pena conoscere alcuni avvisi meno ovvi che stampa: spazi bianchi nascosti all'inizio o alla fine di un valore (un token incollato che terminava con un a capo), lo stesso nome che punta a endpoint diversi in due ambiti, e una manciata di nomi riservati che non possono essere usati per i tuoi server. I server WebSocket non compaiono affatto nell'elenco; controllali con claude mcp get <name> o /mcp.

Guasti comuni e come risolverli

1. Un server remoto mostra "richiede autenticazione" oppure risponde 401 o 403. Apri /mcp, seleziona il server e completa l'accesso nel browser, oppure esegui claude mcp login <name>. Se il server usa un token statico, controlla il valore dell'intestazione e l'avviso sulle variabili non espanse.
2. Un server locale non riesce a connettersi all'avvio. Esegui il suo comando a mano nella stessa shell per vedere l'errore reale; le cause solite sono un runtime mancante, un pacchetto da installare, o una variabile d'ambiente richiesta. I server lenti ad avviarsi raggiungono il limite di avvio, che MCP_TIMEOUT alza in millisecondi, per esempio MCP_TIMEOUT=10000 claude.
3. Il server si connette ma uno strumento restituisce un risultato troncato. L'output di uno strumento è limitato per impostazione predefinita a 25.000 token, con un avviso a partire da 10.000; MAX_MCP_OUTPUT_TOKENS alza il limite.
4. Gli strumenti sembrano mancare dalla conversazione. Claude Code rimanda le definizioni degli strumenti finché non servono, per tenere il contesto ridotto, quindi all'inizio si caricano solo i nomi e le istruzioni del server; l'assistente li trova comunque quando una richiesta corrisponde. Imposta "alwaysLoad": true su una voce di server se vuoi che le sue definizioni complete siano presenti fin dal primo turno.
5. Un server remoto si disconnette a metà sessione. Claude Code riprova una connessione caduta fino a cinque volte con ritardi crescenti, e una prima connessione HTTP fallita fino a tre volte, ma non per gli errori di autenticazione e non per i server locali, quindi un guasto di autenticazione non si risolverà da solo.

Testare la configurazione su un servizio reale

Il modo più veloce per validare il .mcp.json di un progetto è un server le cui risposte puoi controllare in modo indipendente. Con { "type": "http", "url": "https://mcp.host-tracker.com/mcp" } nel commit e ogni sviluppatore che ha effettuato l'accesso una volta tramite /mcp, una richiesta come "esegui un controllo HTTP sul nostro URL di staging da Europa e Asia" deve tornare con codici di stato e tempi di risposta reali dai checkpoint di HostTracker, il che dimostra che il file viene letto correttamente oppure restringe il guasto all'accesso. La guida correlata, come aggiungere un server MCP a Claude Code, copre il percorso da riga di comando e gli ambiti in maggiore dettaglio.