47 /plugin install mcp-server-dev@claude-plugins-official47 /plugin install mcp-server-dev@claude-plugins-official

48 ```48 ```

49 49 

50 Se Claude Code segnala che il marketplace non è stato trovato, esegui prima `/plugin marketplace add anthropics/claude-plugins-official`, quindi riprova l'installazione. Una volta installato, esegui `/reload-plugins` per attivarlo nella sessione corrente.50 Se l'installazione non riesce, fai corrispondere il messaggio che Claude Code segnala:

51 

52 * `Marketplace "claude-plugins-official" non trovato`: aggiungi il marketplace con `/plugin marketplace add anthropics/claude-plugins-official`, quindi riprova l'installazione.

53 * Il plugin [non è trovato nel marketplace](/docs/it/discover-plugins#install-plugins): controlla il nome del plugin.

54 

55 Controlla il riepilogo dell'installazione: se segnala `Run /reload-plugins to activate.`, esegui quel comando.

51 </Step>56 </Step>

52 57 

53 <Step title="Esegui lo skill di compilazione">58 <Step title="Esegui lo skill di compilazione">

60</Steps>65</Steps>

61 66 

62<h2 id="installing-mcp-servers">67<h2 id="installing-mcp-servers">

63 Installazione dei server MCP68 Installazione di server MCP

64</h2>69</h2>

65 70 

66I server MCP possono essere configurati in diversi modi a seconda delle vostre esigenze:71I server MCP possono essere configurati in diversi modi a seconda delle tue esigenze:

67 72 

68<h3 id="option-1-add-a-remote-http-server">73<h3 id="option-1-add-a-remote-http-server">

69 Opzione 1: Aggiungi un server HTTP remoto74 Opzione 1: Aggiungere un server HTTP remoto

70</h3>75</h3>

71 76 

72I server HTTP sono l'opzione consigliata per connettersi ai server MCP remoti. Questo è il trasporto più ampiamente supportato per i servizi basati su cloud.77I server HTTP sono l'opzione consigliata per connettersi a server MCP remoti. Questo è il trasporto più ampiamente supportato per i servizi basati su cloud.

73 78 

74```bash theme={null}79```bash theme={null}

75# Sintassi di base80# Sintassi di base

83 --header "Authorization: Bearer your-token"88 --header "Authorization: Bearer your-token"

84```89```

85 90 

86Quando si configurano i server MCP tramite JSON in `.mcp.json`, `~/.claude.json`, o `claude mcp add-json`, il campo `type` accetta `streamable-http` come alias per `http`. La specifica MCP utilizza il nome `streamable-http` per questo trasporto, quindi le configurazioni copiate dalla documentazione del server funzionano senza modifiche.91Quando si configurano server MCP tramite JSON in `.mcp.json`, `~/.claude.json`, o `claude mcp add-json`, il campo `type` accetta `streamable-http` come alias per `http`. La specifica MCP utilizza il nome `streamable-http` per questo trasporto, quindi le configurazioni copiate dalla documentazione del server funzionano senza modifiche.

92 

93Una voce JSON che ha un `url` ma nessun `type` è un errore di configurazione, perché Claude Code legge una voce senza `type` come server stdio. Claude Code salta quel server e segnala `MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry`. Prima della v2.1.202, Claude Code segnalava questa configurazione errata come `command: expected string, received undefined`.

87 94 

88Una voce JSON che ha un `url` ma nessun `type` è un errore di configurazione, perché Claude Code legge una voce senza `type` come un server stdio. Claude Code salta quel server e segnala `MCP server "<name>" has a "url" but no "type"; add "type": "http" (or "sse" / "ws") to this entry`. Prima della v2.1.202, Claude Code segnalava questa configurazione errata come `command: expected string, received undefined`.95Nelle esecuzioni `--output-format stream-json`, Claude Code segnala anche una voce `--mcp-config` saltata nel campo [`mcp_server_errors` dell'evento `system/init`](/docs/it/headless#stream-responses), in modo che gli script possano rilevare che il server non è mai stato caricato. Questo richiede Claude Code v2.1.219 o successivo.

89 96 

90<h3 id="option-2-add-a-remote-sse-server">97<h3 id="option-2-add-a-remote-sse-server">

91 Opzione 2: Aggiungi un server SSE remoto98 Opzione 2: Aggiungere un server SSE remoto

92</h3>99</h3>

93 100 

94<Warning>101<Warning>

95 Il trasporto SSE (Server-Sent Events) è deprecato. Utilizza server HTTP invece, dove disponibili.102 Il trasporto SSE (Server-Sent Events) è deprecato. Utilizza server HTTP invece, dove disponibili.

96</Warning>103</Warning>

97 104 

105Alcuni servizi espongono ancora solo un endpoint SSE. Utilizza lo stesso comando del trasporto HTTP, con `--transport sse`:

106 

98```bash theme={null}107```bash theme={null}

99# Sintassi di base108# Sintassi di base

100claude mcp add --transport sse <name> <url>109claude mcp add --transport sse <name> <url>

102# Esempio reale: Connessione ad Asana111# Esempio reale: Connessione ad Asana

103claude mcp add --transport sse asana https://mcp.asana.com/sse112claude mcp add --transport sse asana https://mcp.asana.com/sse

104 113 

105# Esempio con header di autenticazione114# Esempio con intestazione di autenticazione

106claude mcp add --transport sse private-api https://api.company.com/sse \115claude mcp add --transport sse private-api https://api.company.com/sse \

107 --header "X-API-Key: your-key-here"116 --header "X-API-Key: your-key-here"

108```117```

109 118 

110<h3 id="option-3-add-a-local-stdio-server">119<h3 id="option-3-add-a-local-stdio-server">

111 Opzione 3: Aggiungi un server stdio locale120 Opzione 3: Aggiungere un server stdio locale

112</h3>121</h3>

113 122 

114I server stdio vengono eseguiti come processi locali sulla vostra macchina. Sono ideali per strumenti che necessitano di accesso diretto al sistema o script personalizzati.123I server stdio vengono eseguiti come processi locali sulla tua macchina. Sono ideali per strumenti che necessitano di accesso diretto al sistema o script personalizzati.

115 124 

116Claude Code imposta `CLAUDE_PROJECT_DIR` nell'ambiente del server generato alla radice del progetto, in modo che il vostro server possa risolvere i percorsi relativi al progetto senza dipendere dalla directory di lavoro. Questa è la stessa directory che gli hook ricevono nella loro variabile `CLAUDE_PROJECT_DIR`. Leggetela dall'interno del vostro processo server, ad esempio `process.env.CLAUDE_PROJECT_DIR` in Node o `os.environ["CLAUDE_PROJECT_DIR"]` in Python.125Claude Code imposta `CLAUDE_PROJECT_DIR` nell'ambiente del server generato alla radice del progetto, in modo che il tuo server possa risolvere i percorsi relativi al progetto senza dipendere dalla directory di lavoro. Questa è la stessa directory che gli hook ricevono nella loro variabile `CLAUDE_PROJECT_DIR`. Leggila dall'interno del processo del tuo server, ad esempio `process.env.CLAUDE_PROJECT_DIR` in Node o `os.environ["CLAUDE_PROJECT_DIR"]` in Python.

117 126 

118`CLAUDE_PROJECT_DIR` è la radice stabile del progetto e non cambia quando aggiungete o rimuovete directory di lavoro durante la sessione. Un server che limita il proprio accesso al filesystem a un insieme di directory consentite dovrebbe implementare la richiesta MCP `roots/list`. Claude Code risponde a `roots/list` con la directory di avvio della sessione più ogni [directory di lavoro aggiuntiva](/docs/it/permissions#working-directories) che avete concesso con `--add-dir`, `/add-dir`, o l'impostazione `additionalDirectories`. Claude Code invia `notifications/roots/list_changed` quando tale insieme cambia. Prima della v2.1.203, `roots/list` restituiva solo la directory di avvio e Claude Code non inviava `notifications/roots/list_changed`.127`CLAUDE_PROJECT_DIR` è la radice del progetto stabile e non cambia quando aggiungi o rimuovi directory di lavoro a metà sessione. Un server che limita il proprio accesso al file system a un insieme di directory consentite dovrebbe implementare la richiesta MCP `roots/list`. Claude Code risponde a `roots/list` con la directory di avvio della sessione più ogni [directory di lavoro aggiuntiva](/docs/it/permissions#working-directories) che hai concesso con `--add-dir`, `/add-dir`, o l'impostazione `additionalDirectories`. Claude Code invia `notifications/roots/list_changed` quando tale insieme cambia. Prima della v2.1.203, `roots/list` restituiva solo la directory di avvio e Claude Code non inviava `notifications/roots/list_changed`.

119 128 

120Questa variabile è impostata nell'ambiente del server, non nell'ambiente di Claude Code stesso, quindi farvi riferimento tramite l'espansione `${VAR}` in un `.mcp.json` con ambito progetto o utente `command` o `args` richiede un valore predefinito come `${CLAUDE_PROJECT_DIR:-.}`. Le configurazioni MCP fornite da plugin sostituiscono `${CLAUDE_PROJECT_DIR}` direttamente e non hanno bisogno del valore predefinito.129Questa variabile è impostata nell'ambiente del server, non nell'ambiente di Claude Code stesso, quindi farvi riferimento tramite l'espansione `${VAR}` nel `command` o `args` di una voce `.mcp.json` con ambito di progetto o una voce server con ambito locale o utente in `~/.claude.json` richiede un valore predefinito come `${CLAUDE_PROJECT_DIR:-.}`. Le configurazioni MCP fornite dai plugin sostituiscono `${CLAUDE_PROJECT_DIR}` direttamente e non hanno bisogno del valore predefinito.

121 130 

122```bash theme={null}131```bash theme={null}

123# Sintassi di base132# Sintassi di base

124claude mcp add [options] <name> -- <command> [args...]133claude mcp add [options] <name> -- <command> [args...]

125 134 

126# Esempio reale: Aggiungi server Airtable135# Esempio reale: Aggiungere server Airtable

127claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \136claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \

128 -- npx -y airtable-mcp-server137 -- npx -y airtable-mcp-server

129```138```

133 142 

134 Per i server stdio, il `--` (doppio trattino) separa le opzioni di Claude, come `--transport`, `--env`, e `--scope`, dal comando e dagli argomenti che eseguono il server. Tutto ciò che viene dopo `--` viene passato al server senza modifiche.143 Per i server stdio, il `--` (doppio trattino) separa le opzioni di Claude, come `--transport`, `--env`, e `--scope`, dal comando e dagli argomenti che eseguono il server. Tutto ciò che viene dopo `--` viene passato al server senza modifiche.

135 144 

136 Per esempio:145 Ad esempio:

137 146 

138 * `claude mcp add --transport stdio myserver -- npx server` → esegue `npx server`147 * `claude mcp add --transport stdio myserver -- npx server` → esegue `npx server`

139 * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → esegue `python server.py --port 8080` con `KEY=value` nell'ambiente148 * `claude mcp add --env KEY=value --transport stdio myserver -- python server.py --port 8080` → esegue `python server.py --port 8080` con `KEY=value` nell'ambiente

140 149 

141 Senza `--`, Claude Code cercherebbe di analizzare i flag del server, come `--port` sopra, come proprie opzioni.150 Senza `--`, Claude Code cercherebbe di analizzare i flag del server, come `--port` sopra, come le sue stesse opzioni.

142 151 

143 `--env` accetta più coppie `KEY=value`. Se il nome del server viene direttamente dopo `--env`, la CLI legge il nome come un'altra coppia e lo rifiuta, quindi posizionate almeno un'altra opzione tra `--env` e il nome del server, come negli esempi sopra.152 `--env` accetta più coppie `KEY=value`. Se il nome del server viene direttamente dopo `--env`, la CLI legge il nome come un'altra coppia e lo rifiuta, quindi posiziona almeno un'altra opzione tra `--env` e il nome del server, come negli esempi sopra.

144</Note>153</Note>

145 154 

146<h3 id="option-4-add-a-remote-websocket-server">155<h3 id="option-4-add-a-remote-websocket-server">

147 Opzione 4: Aggiungi un server WebSocket remoto156 Opzione 4: Aggiungere un server WebSocket remoto

148</h3>157</h3>

149 158 

150I server WebSocket mantengono una connessione bidirezionale persistente, che si adatta ai server MCP remoti che inviano eventi a Claude senza sollecitazione. Utilizza HTTP invece quando il vostro server risponde solo alle richieste, poiché HTTP supporta OAuth e il flag `claude mcp add --transport`, mentre WebSocket non supporta nessuno dei due.159I server WebSocket mantengono una connessione bidirezionale persistente, che si adatta ai server MCP remoti che inviano eventi a Claude senza sollecitazione. Utilizza HTTP quando il tuo server risponde solo alle richieste, poiché HTTP supporta OAuth e il flag `claude mcp add --transport`, mentre WebSocket non supporta nessuno dei due.

151 160 

152Configura i server WebSocket in `.mcp.json` o con `claude mcp add-json`:161Configura i server WebSocket in `.mcp.json` o con `claude mcp add-json`:

153 162 

156 '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'165 '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

157```166```

158 167 

159La voce `type: "ws"` accetta gli stessi campi `url`, `headers`, `headersHelper`, `timeout`, e `alwaysLoad` di `http`. L'autenticazione è solo tramite header, quindi passa un token statico in `headers` o generane uno al momento della connessione con [`headersHelper`](#use-dynamic-headers-for-custom-authentication). Il flag `claude mcp add --transport` non accetta `ws`.168La voce `type: "ws"` accetta gli stessi campi `url`, `headers`, `headersHelper`, `timeout`, e `alwaysLoad` di `http`. L'autenticazione è solo tramite intestazione, quindi passa un token statico in `headers` o generane uno al momento della connessione con [`headersHelper`](#use-dynamic-headers-for-custom-authentication). Il flag `claude mcp add --transport` non accetta `ws`.

169 

170<h3 id="add-a-server-from-setup-instructions-written-for-another-client">

171 Aggiungere un server dalle istruzioni di configurazione scritte per un altro client

172</h3>

173 

174I server MCP non sono specifici di Claude Code, quindi le istruzioni di configurazione di un server potrebbero essere scritte per Claude Desktop, Cursor, o un altro client MCP e non fornire alcun comando `claude mcp add`. Per aggiungere comunque il server, cerca in quelle istruzioni una di queste tre cose:

175 

176* **Un URL** come `https://mcp.example.com/mcp`: il server è remoto.

177* **Un comando di avvio** come `npx -y @example/mcp-server`: il server viene eseguito sulla tua macchina.

178* **Un blocco JSON `mcpServers`**: configurazione scritta per il file di impostazioni di un altro client.

179 

180Ognuno di questi è uno degli input che le quattro opzioni in [Installazione di server MCP](#installing-mcp-servers) accettano. Trova la forma che hai di seguito per trasformarla nel comando che Claude Code accetta. Ogni comando scrive nell'[ambito locale](#local-scope) a meno che non aggiungi `--scope project` o `--scope user`.

181 

182<h4 id="from-a-url">

183 Da un URL

184</h4>

185 

186Un URL significa che il server è remoto. Per un endpoint `https://`, aggiungilo con `--transport http`, o con `--transport sse` quando le istruzioni dicono che l'endpoint utilizza SSE. Per un endpoint `wss://`, utilizza invece l'[Opzione 4](#option-4-add-a-remote-websocket-server), poiché `--transport` non accetta `ws`:

187 

188```bash theme={null}

189claude mcp add --transport http example https://mcp.example.com/mcp

190```

191 

192Se le istruzioni forniscono anche una chiave API o un'intestazione di token, passala con `--header` come mostrato nell'[Opzione 1](#option-1-add-a-remote-http-server).

193 

194<h4 id="from-an-npx-uvx-or-binary-command">

195 Da un comando `npx`, `uvx`, o binario

196</h4>

197 

198Un comando di avvio significa che il server viene eseguito come processo stdio locale. Metti l'intero comando dopo `--`, in modo che Claude Code passi i flag come `-y` al comando che avvia il server invece di leggerli come le sue stesse opzioni. Passa le variabili di ambiente che le istruzioni richiedono con `--env`, dopo il nome del server e prima di `--`:

199 

200```bash theme={null}

201claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server

202```

203 

204L'[Opzione 3](#option-3-add-a-local-stdio-server) copre il separatore `--` completamente.

205 

206<h4 id="from-an-mcpservers-json-block">

207 Da un blocco JSON `mcpServers`

208</h4>

209 

210Un blocco `mcpServers` scritto per un altro client MCP, come Claude Desktop, utilizza la chiave wrapper e la forma di voce che Claude Code legge. Passa a `claude mcp add-json` l'oggetto all'interno di `mcpServers`, non il wrapper. Due voci hanno bisogno di una riparazione prima:

211 

212* **Un `url` senza `type`**: aggiungi `"type": "http"`, `"type": "sse"`, o `"type": "ws"` per corrispondere all'endpoint. Claude Code legge una voce senza `type` come server stdio, quindi una voce `url` senza `type` fallisce.

213* **Una chiave con caratteri diversi da lettere, numeri, trattini e sottolineature**: scegli un nome di server che utilizza solo quei caratteri. Altrimenti la chiave è il nome del server.

214 

215Ad esempio, questo blocco:

216 

217```json theme={null}

218{

219 "mcpServers": {

220 "example": {

221 "command": "npx",

222 "args": ["-y", "@example/mcp-server"]

223 }

224 }

225}

226```

227 

228diventa questo comando:

229 

230```bash theme={null}

231claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'

232```

233 

234[Aggiungere server MCP dalla configurazione JSON](#add-mcp-servers-from-json-configuration) copre l'escape della shell e il flag `--scope` per `add-json`. Per condividere il server con il tuo team, aggiungi invece `--scope project`, o aggiungi la voce sotto `mcpServers` in `.mcp.json` alla radice del tuo progetto e committala. [Ambito di progetto](#project-scope) copre come Claude Code carica e approva quel file.

235 

236Ogni comando `claude mcp add` e `claude mcp add-json` stampa una riga `Added ...`. Per verificare che Claude Code si sia connesso, esegui `claude mcp get <name>`; [Stato del server](#server-status) copre gli stati che mostra e il passaggio di approvazione per i server `.mcp.json`.

160 237 

161<h3 id="managing-your-servers">238<h3 id="managing-your-servers">

162 Gestione dei vostri server239 Gestione dei tuoi server

163</h3>240</h3>

164 241 

165Una volta configurati, potete gestire i vostri server MCP con questi comandi:242Una volta configurati, puoi gestire i tuoi server MCP con questi comandi:

166 243 

167```bash theme={null}244```bash theme={null}

168# Elenca tutti i server configurati245# Elencare tutti i server configurati

169claude mcp list246claude mcp list

170 247 

171# Ottieni dettagli per un server specifico248# Ottenere i dettagli per un server specifico

172claude mcp get github249claude mcp get notion

173 250 

174# Rimuovi un server251# Rimuovere un server

175claude mcp remove github252claude mcp remove notion

176 253 

177# (all'interno di Claude Code) Controlla lo stato del server254# (all'interno di Claude Code) Controllare lo stato del server

178/mcp255/mcp

179```256```

180 257 

181I server con ambito progetto da `.mcp.json` che sono in attesa della vostra approvazione appaiono in `claude mcp list` come `⏸ Pending approval`. Esegui `claude` in modo interattivo per esaminarli e approvarli. `claude mcp get <name>` mostra i server in sospeso come `⏸ Pending approval` e i server rifiutati come `✗ Rejected`.258Quando rimuovi un server remoto, Claude Code elimina anche i token OAuth e la registrazione del client che ha memorizzato per quel server.

259 

260<h4 id="server-status">

261 Stato del server

262</h4>

263 

264`claude mcp add` conferma un'aggiunta riuscita stampando una riga `Added ...`, il che significa che la configurazione è stata scritta. `claude mcp list` mostra quindi uno stato di salute accanto a ogni server che elenca, come `✔ Connected`, `! Needs authentication`, o `✘ Failed to connect`. Uno stato di fallimento significa che Claude Code non poteva connettersi a quel server, non che il comando list sia fallito.

265 

266Gli stati in questo elenco segnalano una decisione di configurazione piuttosto che un tentativo di connessione, quindi Claude Code li stampa senza connettersi al server:

182 267 

183A partire dalla v2.1.196, `claude mcp list` e `claude mcp get` leggono le approvazioni `.mcp.json` solo dai file di impostazioni che non sono archiviati nel repository finché non fidate dell'area di lavoro eseguendo `claude` in essa e accettando la finestra di dialogo di trust dell'area di lavoro. Un repository clonato non può approvare i propri server: [`enableAllProjectMcpServers` o `enabledMcpjsonServers`](/docs/it/settings#available-settings) committati nel `.claude/settings.json` del progetto vengono ignorati in una cartella non attendibile, e il server rimane a `⏸ Pending approval` invece di essere connesso e sottoposto a health-check.268* ``⏸ Pending approval (run `claude` to approve)``: un server con ambito di progetto da `.mcp.json` che non hai ancora approvato. Claude Code lo mostra sia in `claude mcp list` che in `claude mcp get <name>`. Esegui `claude` in modo interattivo per rivederlo e approvarlo.

269* `✘ Rejected (see disabledMcpjsonServers in settings)`: un server `.mcp.json` che una voce [`disabledMcpjsonServers`](/docs/it/settings-reference#disabledmcpjsonservers) rifiuta. Claude Code lo mostra solo in `claude mcp get <name>`.

270* `⊘ Disabled for this project (re-enable via /mcp)`: un server che l'elenco [`disabledMcpServers`](#disable-a-server-without-removing-it) del progetto nomina. Claude Code lo mostra sia in `claude mcp list` che in `claude mcp get <name>`. Riattiva il server dal pannello `/mcp`. Prima della v2.1.238, entrambi i comandi si connettevano a un server disabilitato per verificarne lo stato di salute e segnalano il risultato della connessione.

271 

272I server WebSocket non appaiono nell'output di `claude mcp list`. Utilizza `claude mcp get <name>` o il pannello `/mcp` per controllarli.

273 

274<h4 id="project-server-approvals-and-workspace-trust">

275 Approvazioni del server di progetto e fiducia dell'area di lavoro

276</h4>

277 

278A partire dalla v2.1.196, `claude mcp list` e `claude mcp get` leggono le approvazioni `.mcp.json` solo dai file di impostazioni che non sono sottoposti a commit nel repository finché non fidi dell'area di lavoro eseguendo `claude` in essa e accettando la finestra di dialogo di fiducia dell'area di lavoro. Un repository clonato non può approvare i suoi stessi server: [`enableAllProjectMcpServers`](/docs/it/settings-reference#enableallprojectmcpservers) o [`enabledMcpjsonServers`](/docs/it/settings-reference#enabledmcpjsonservers) sottoposti a commit nel `.claude/settings.json` del progetto vengono ignorati in una cartella non attendibile, e il server rimane a `⏸ Pending approval` invece di essere connesso e verificato.

184 279 

185Le approvazioni da queste fonti si applicano ancora in una cartella non attendibile:280Le approvazioni da queste fonti si applicano ancora in una cartella non attendibile:

186 281 

187* il vostro `~/.claude/settings.json` utente282* il tuo `~/.claude/settings.json` utente

188* impostazioni gestite283* impostazioni gestite

189* impostazioni passate con `--settings`284* impostazioni passate con `--settings`

190 285 

191Le approvazioni in un `.claude/settings.local.json` non tracciato si applicano anche, ma solo dopo che accettate una finestra di dialogo di trust per quella cartella o una delle sue directory padre: Claude Code esegue git per verificare se il file è tracciato, ed esegue quel controllo solo in una cartella attendibile. In una cartella che non avete mai fidata, le approvazioni del file attendono la finestra di dialogo di trust a meno che la cartella non sia la vostra home di configurazione: la vostra home directory, o una directory il cui `.claude` avete impostato come [`CLAUDE_CONFIG_DIR`](/docs/it/env-vars). Prima della v2.1.207, un `.claude/settings.local.json` non tracciato approvava i server in una cartella che non avete mai fidata.286Claude Code applica anche le approvazioni da un `.claude/settings.local.json` non tracciato, ma esegue git per verificare se il file è tracciato, ed esegue quel controllo solo in una [cartella attendibile](/docs/it/permissions#project-allow-rules-and-workspace-trust). In una cartella che non hai mai fidato, Claude Code attende la finestra di dialogo di fiducia prima di applicare le approvazioni del file, a meno che la cartella non sia la tua home di configurazione: la tua home directory, o una directory il cui `.claude` hai impostato come [`CLAUDE_CONFIG_DIR`](/docs/it/env-vars). Prima della v2.1.207, Claude Code applicava le approvazioni da un `.claude/settings.local.json` non tracciato anche in una cartella che non avevi mai fidato.

192 287 

193Una voce `disabledMcpjsonServers` in qualsiasi file di impostazioni rifiuta comunque il server.288Una voce `disabledMcpjsonServers` in qualsiasi file di impostazioni rifiuta comunque il server.

194 289 

290<h4 id="server-status-detail">

291 Dettaglio dello stato del server

292</h4>

293 

294In `/mcp`, incluso il menu di un server lì, e nel gestore [`/plugin`](/docs/it/plugins), un server HTTP o SSE remoto che hai usato prima può mostrare uno stato `cached` come `cached 2h ago · connects on first use · 5 tools`. Claude Code ha caricato l'elenco degli strumenti del server dalla sua cache di scoperta, salvata in una sessione precedente, invece di connettersi all'avvio, e Claude Code connette il server la prima volta che Claude chiama uno degli strumenti del server. Gli strumenti sono disponibili dal tuo primo messaggio, quindi non devi fare nulla. La cache di scoperta e il suo stato `cached` richiedono Claude Code v2.1.221 o successivo.

295 

296La cache di scoperta è disattivata per impostazione predefinita a meno che un rollout graduale non l'abbia abilitata per il tuo account. Imposta [`MCP_DISCOVERY_CACHE=1`](/docs/it/env-vars) per attivarla, o `0` per mantenerla disattivata anche quando il rollout l'ha abilitata. Prima della v2.1.238, la cache era attivata per impostazione predefinita.

297 

298Due azioni nel menu di un server in `/mcp` influenzano anche la voce della cache di quel server:

299 

300* **Reconnect**: su un server `cached`, Claude Code lo connette ora piuttosto che alla sua prima chiamata di strumento e mantiene la voce. Su un server connesso o fallito, Claude Code lo riconnette e scarta anche la voce.

301* **Clear authentication**: Claude Code revoca l'autenticazione del server e scarta anche la voce.

302 

303Dopo aver scartato la voce, Claude Code recupera l'elenco degli strumenti del server dal server invece che dalla cache.

304 

305Quando lo stato di un server è `✘ Failed to connect`, `claude mcp list` aggiunge il dettaglio del fallimento a quella riga di stato, e `claude mcp get <name>` lo mostra su una riga `Issue:`: il codice di stato HTTP o il codice di errore, più qualsiasi testo di errore che il server ha restituito. La vista dei dettagli del server in `/mcp` include lo stesso testo segnalato dal server nella sua riga `Issue:`. Claude Code redige il testo simile a credenziali da questo dettaglio e non include mai l'URL del server espanso, che può contenere segreti. Claude Code non aggiunge dettagli a uno stato `✘ Connection error`, perché il testo dell'eccezione che stamperebbe lì può incorporare quell'URL. Prima della v2.1.219, entrambi i comandi mostravano solo lo stato di fallimento nudo, senza il codice di stato o il testo di errore del server.

306 

307Quando completi l'autenticazione da `/mcp` e la connessione fallisce ancora con uno stato HTTP o un codice di errore di trasporto, Claude Code aggiunge quel codice e l'origine dell'URL che ha provato al messaggio che stampa dopo il tentativo. L'origine è lo schema e l'host, più la porta quando l'URL ne nomina una, come `https://mcp.example.com`.

308 

309* Il percorso e la query non appaiono mai in quel messaggio.

310* Claude Code prende l'origine dopo l'espansione `${VAR}`, quindi un host che proviene da una variabile appare espanso.

311* Per un fallimento senza codice di stato o di errore, Claude Code mostra il testo di errore senza l'origine.

312 

313Un server remoto la cui configurazione ha un `url` vuoto viene mostrato come `not configured` in `/mcp`, in `claude mcp list`, e nel gestore [`/plugin`](/docs/it/plugins), e Claude Code non tenta di connettersi ad esso. Un plugin può includere una voce segnaposto come questa per un connettore che configuri in seguito, quindi Claude Code non lo segnala come un errore o un problema di configurazione. La vista dei dettagli del server in `/mcp` legge `No URL configured for this server`; imposta l'`url` della voce per connetterlo. Prima della v2.1.208, Claude Code segnalava un `url` vuoto come un problema di configurazione con un prompt per riconnettersi.

314 

315<h4 id="configuration-warnings">

316 Avvisi di configurazione

317</h4>

318 

319Claude Code avverte sui problemi di configurazione di seguito. Ogni voce dice cosa Claude Code controlla e come cancellare l'avviso:

320 

321* **Spazi bianchi nascosti**: Claude Code avverte quando un valore di configurazione MCP contiene spazi bianchi nascosti iniziali o finali, che spesso provengono dall'incollamento di un token con una nuova riga finale. Claude Code controlla `command`, `url`, ogni voce `args`, e i valori e i nomi delle chiavi sotto `env` e `headers`. Claude Code mostra l'avviso nell'output di `claude mcp list` e in `/mcp`, nominando i campi interessati senza echeggiare i loro valori, ad esempio `Leading or trailing whitespace in: headers.Authorization`. Claude Code non taglia gli spazi bianchi e utilizza i valori esattamente come scritti, quindi modifica la configurazione per rimuoverli.

322* **Stesso nome in più di un ambito**: se definisci lo stesso nome di server in più di un [ambito](#mcp-installation-scopes) con endpoint diversi, Claude Code avverte del conflitto nell'output di `claude mcp list` e in `/mcp`. Claude Code memorizza gli accessi OAuth per endpoint, quindi quando autentichi la definizione che si carica in un progetto, devi comunque accedere separatamente in un progetto dove si carica una definizione diversa. Mantieni l'endpoint che desideri e rimuovi gli altri con `claude mcp remove <name> --scope <scope>`. Nell'avviso, Claude Code cita l'endpoint di ogni ambito come scritto nella tua configurazione, con i riferimenti [`${VAR}`](#environment-variable-expansion-in-mcp-json) non espansi, quindi non mostra mai un valore risolto come una chiave API.

323* **Nomi riservati**: Claude Code riserva i nomi dei suoi server integrati, inclusi `workspace`, `claude-in-chrome`, `computer-use`, `Claude Preview`, e `Claude Browser`. Se la tua configurazione definisce un server con un nome riservato, Claude Code lo salta al momento del caricamento e mostra un avviso chiedendoti di rinominarlo. `claude mcp add` rifiuta un nome riservato con un errore. `Claude Preview` e `Claude Browser` entrambi nominano il server integrato che il [pannello di anteprima dell'app desktop Claude Code](/docs/it/desktop#preview-your-app) utilizza. Prima della v2.1.205, `Claude Browser` non era riservato, quindi un server configurato dall'utente poteva registrarsi con quel nome.

324* **Variabile di ambiente mancante**: se un riferimento [`${VAR}`](#environment-variable-expansion-in-mcp-json) nella configurazione di un server nomina una variabile che non è impostata e non ha `:-default`, Claude Code avverte nell'output di `claude mcp list` e in `/mcp`, nominando la variabile, e carica comunque il server con il testo `${VAR}` non espanso. Imposta la variabile o aggiungi un fallback `${VAR:-default}`.

325 

326<h4 id="tool-availability">

327 Disponibilità degli strumenti

328</h4>

329 

195Il pannello `/mcp` mostra il conteggio degli strumenti accanto a ogni server connesso e contrassegna i server che pubblicizzano la capacità degli strumenti ma non espongono alcuno strumento.330Il pannello `/mcp` mostra il conteggio degli strumenti accanto a ogni server connesso e contrassegna i server che pubblicizzano la capacità degli strumenti ma non espongono alcuno strumento.

196 331 

197Un server remoto la cui configurazione ha un `url` vuoto appare come `not configured` in `/mcp`, in `claude mcp list`, e nel gestore [`/plugin`](/docs/it/plugins), e Claude Code non tenta di connettersi ad esso. Un plugin può includere una voce segnaposto come questa per un connettore che configurate in seguito, in modo che Claude Code non lo segnali come un errore o un problema di configurazione. La vista dei dettagli del server in `/mcp` legge `No URL configured for this server`; impostare l'`url` della voce per connettersi. Prima della v2.1.208, Claude Code segnalava un `url` vuoto come un problema di configurazione con un prompt per riconnettersi.332Se la tua richiesta ha bisogno di strumenti da un server che si sta ancora connettendo in background, Claude attende quel server prima di continuare. Come avviene l'attesa dipende dalla tua configurazione:

333 

334* **Con [ricerca degli strumenti](#scale-with-mcp-tool-search), l'impostazione predefinita**: l'attesa avviene all'interno della chiamata `ToolSearch`.

335* **Senza ricerca degli strumenti**: Claude utilizza lo strumento `WaitForMcpServers`. Le configurazioni senza ricerca degli strumenti includono un `ANTHROPIC_BASE_URL` personalizzato, `ENABLE_TOOL_SEARCH=false`, e un modello precedente alla generazione Claude 4.5 su Google Cloud's Agent Platform.

336* **Su una distribuzione Microsoft Foundry [ospitata su Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)**: Claude inizia sul percorso di ricerca degli strumenti piuttosto che con `WaitForMcpServers`, poiché Claude Code scopre il rifiuto lato server dell'API solo dall'API. Dopo che Claude Code passa quella distribuzione al [caricamento anticipato](#scale-with-mcp-tool-search), gli strumenti da un server che finisce di connettersi diventano disponibili sulla richiesta successiva di Claude.

337 

338Con la ricerca degli strumenti abilitata, quando un server finisce di connettersi mentre Claude sta lavorando, Claude Code elenca i nomi degli strumenti del server a Claude sulla sua richiesta successiva nello stesso turno. Claude può quindi cercare e chiamare quegli strumenti senza attendere il tuo prossimo messaggio.

339 

340<h3 id="disable-a-server-without-removing-it">

341 Disabilitare un server senza rimuoverlo

342</h3>

343 

344Attiva/disattiva un server nel pannello `/mcp` per impedire a Claude Code di connettersi ad esso senza perdere la sua configurazione. Claude Code elenca comunque il server in `/mcp`, contrassegnato come disabilitato.

345 

346Quando attivi/disattivi un server, Claude Code registra la tua scelta per progetto in `~/.claude.json`, in uno di due elenchi che coprono insiemi disgiunti di server:

347 

348* `disabledMcpServers`: un elenco di esclusione per server configurati dall'utente, server di plugin, server che la tua organizzazione [fornisce tramite impostazioni gestite](/docs/it/managed-mcp#provide-servers-through-managed-settings), i connettori claude.ai che Claude Code [recupera da solo](#how-connectors-reach-claude-code), e server integrati che sono abilitati per impostazione predefinita. Claude Code non si connette a un server che elenchi qui. Quando disabiliti un connettore claude.ai con l'attivazione/disattivazione `/mcp` per progetto descritta in [Disabilitare i connettori claude.ai](#disable-claude-ai-connectors), Claude Code lo scrive in questo elenco con il suo nome di visualizzazione, ad esempio `claude.ai Slack`.

349* `enabledMcpServers`: un elenco di inclusione per server integrati che sono disabilitati per impostazione predefinita, come `computer-use`. Claude Code si connette a un server disabilitato per impostazione predefinita solo quando lo elenchi qui.

350 

351Claude Code consulta esattamente uno dei due elenchi per ogni server, quindi nessun elenco sostituisce l'altro. Se aggiungi un server regolare a `enabledMcpServers`, o un server integrato disabilitato per impostazione predefinita a `disabledMcpServers`, Claude Code ignora la voce.

352 

353`disabledMcpServers` e `enabledMcpServers` non sono correlati a [`enabledMcpjsonServers`](/docs/it/settings-reference#enabledmcpjsonservers) e [`disabledMcpjsonServers`](/docs/it/settings-reference#disabledmcpjsonservers), che controllano l'approvazione dei server definiti nel file `.mcp.json` di un progetto.

354 

355<h3 id="mcp-client-runtimes">

356 Runtime client MCP

357</h3>

358 

359Claude Code si connette ai server MCP attraverso uno di due runtime client. Il runtime v1 è costruito su MCP TypeScript SDK 1.x. Il runtime v2 è lo stesso codice su [MCP TypeScript SDK 2.0](https://ts.sdk.modelcontextprotocol.io/v2/), che aggiunge la revisione del protocollo MCP 2026-07-28. Il resto di questa pagina si applica a entrambi i runtime, tranne dove una sezione nomina il runtime v2.

360 

361Su Claude Code v2.1.232 o successivo, Claude Code utilizza il runtime v2. Sceglie un runtime ogni volta che lo avvii e lo mantiene fino a quando non esci. Utilizza v1 quando lo esegui:

362 

363* Su Amazon Bedrock, Claude Platform su AWS, Google Cloud's Agent Platform, o Microsoft Foundry, a meno che una piattaforma host che incorpora Claude Code non imposti [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/it/env-vars)

364* Acceduto tramite un [gateway di app Claude](/docs/it/claude-apps-gateway)

365* Con [recupero dei flag di funzionalità disattivato](/docs/it/env-vars#features-that-need-feature-flag-fetching)

198 366 

199Se la vostra richiesta ha bisogno di strumenti da un server che è ancora in fase di connessione in background, Claude attende quel server prima di continuare. Con la [ricerca degli strumenti](#scale-with-mcp-tool-search) abilitata, che è l'impostazione predefinita, l'attesa avviene all'interno della chiamata `ToolSearch`. Nelle configurazioni senza ricerca degli strumenti, come Google Cloud's Agent Platform, un `ANTHROPIC_BASE_URL` personalizzato, o `ENABLE_TOOL_SEARCH=false`, Claude utilizza lo strumento `WaitForMcpServers` invece.367Su v2, Claude Code inoltre:

200 368 

201Alcuni nomi di server sono riservati per i server integrati di Claude Code: `workspace`, `claude-in-chrome`, `computer-use`, `Claude Preview`, e `Claude Browser`. Se la vostra configurazione definisce un server con un nome riservato, Claude Code lo salta al momento del caricamento e mostra un avviso chiedendovi di rinominarlo. `claude mcp add` rifiuta un nome riservato con un errore.369* Chiede ai server HTTP e ai connettori claude.ai se supportano la revisione più recente, e la utilizza con quelli che lo fanno. Chiede ai server stdio solo se imposti [`MCP_PROTOCOL_NEGOTIATION`](/docs/it/env-vars) su `auto`, e si connette a ogni altro server come v1 fa.

370* Riceve notifiche `list_changed` dai server sulla revisione più recente su un [flusso che mantiene aperto](#notification-streams-on-the-v2-runtime).

371* Non registra un server [channel](#push-messages-with-channels) che si connette sulla revisione più recente, perché quella revisione non può trasportare messaggi di canale.

372* Fallisce un [accesso OAuth MCP](#authenticate-with-remote-mcp-servers) la cui risposta di autorizzazione nomina un emittente inaspettato.

202 373 

203`Claude Preview` e `Claude Browser` denominano entrambi il server integrato che il [riquadro di anteprima dell'app desktop Claude Code](/docs/it/desktop#preview-your-app) utilizza. Prima della v2.1.205, `Claude Browser` non era riservato, quindi un server configurato dall'utente poteva registrarsi con quel nome.374Anthropic può mantenere un server specifico sul protocollo precedente, o fuori da quel flusso, con un flag di funzionalità che Claude Code recupera. In una sessione [Claude Code sul web](/docs/it/cloud-environments#network-access), Claude Code chiede ai suoi connettori MCP solo se imposti `MCP_PROTOCOL_NEGOTIATION` su `auto`.

375 

376Per scegliere il runtime tu stesso, imposta [`MCP_SDK_GENERATION`](/docs/it/env-vars) su `v1` o `v2`. Per decidere se Claude Code chiede, imposta [`MCP_PROTOCOL_NEGOTIATION`](/docs/it/env-vars) su `auto` o `legacy`. Dove Claude Code utilizza v1 per impostazione predefinita, fissare `v2` non lo fa chiedere, quindi imposta anche `auto`.

204 377 

205<h3 id="dynamic-tool-updates">378<h3 id="dynamic-tool-updates">

206 Aggiornamenti dinamici degli strumenti379 Aggiornamenti dinamici degli strumenti

207</h3>380</h3>

208 381 

209Claude Code supporta le notifiche `list_changed` di MCP, consentendo ai server MCP di aggiornare dinamicamente i loro strumenti, prompt e risorse disponibili senza richiedere di disconnettersi e riconnettersi. Quando un server MCP invia una notifica `list_changed`, Claude Code aggiorna automaticamente le capacità disponibili da quel server.382Claude Code supporta le notifiche MCP `list_changed`, consentendo ai server MCP di aggiornare dinamicamente i loro strumenti, prompt e risorse disponibili senza richiedere di disconnettersi e riconnettersi. Quando un server MCP invia una notifica `list_changed`, Claude Code aggiorna automaticamente le capacità disponibili da quel server.

383 

384Se una richiesta di aggiornamento fallisce, Claude Code mantiene gli strumenti, i prompt e le risorse precedentemente scoperti del server fino a quando un aggiornamento successivo non riesce. Prima della v2.1.214, un errore transitorio durante l'aggiornamento sostituiva gli strumenti, i prompt e le risorse del server con un elenco vuoto.

385 

386<h4 id="notification-streams-on-the-v2-runtime">

387 Flussi di notifica sul runtime v2

388</h4>

389 

390Sul [runtime v2](#mcp-client-runtimes), Claude Code riceve notifiche `list_changed` da un server sulla revisione del protocollo più recente su un flusso che mantiene aperto. Quando il flusso si chiude, Claude Code lo riapre, con due limiti:

391 

392* **Il flusso si chiude di nuovo entro 10 secondi**: Claude Code lo riapre fino a tre volte, quindi si ferma per quella connessione.

393* **Il flusso rimane aperto più a lungo di 10 secondi, quindi si chiude**, come i flussi agli host serverless comunemente fanno: dopo cinque riaperture in un'ora, Claude Code attende circa sei ore prima della prossima.

394 

395Fino a quando il flusso non si riapre, mantieni gli ultimi strumenti, prompt e risorse recuperati del server. Per raccogliere i suoi cambiamenti più presto, riconnetti il server da `/mcp`.

210 396 

211<h3 id="automatic-reconnection">397<h3 id="automatic-reconnection">

212 Riconnessione automatica398 Riconnessione automatica

213</h3>399</h3>

214 400 

215Se un server HTTP o SSE si disconnette durante una sessione, Claude Code si riconnette automaticamente con backoff esponenziale: fino a cinque tentativi, a partire da un ritardo di un secondo e raddoppiando ogni volta. Il server appare come in sospeso in `/mcp` mentre la riconnessione è in corso. Dopo cinque tentativi falliti il server è contrassegnato come non riuscito e potete riprovare manualmente da `/mcp`. I server stdio sono processi locali e non vengono riconnessi automaticamente.401Claude Code riconnette un server remoto che cade a metà sessione e ritenta la prima connessione di un server HTTP o SSE dopo un errore transitorio. I server stdio sono processi locali, e Claude Code non li riconnette automaticamente.

402 

403<h4 id="mid-session-drops-of-a-remote-server">

404 Cadute a metà sessione di un server remoto

405</h4>

406 

407Claude Code riconnette un server remoto caduto con backoff esponenziale: fino a cinque tentativi, a partire da un ritardo di un secondo e raddoppiandolo ogni volta. Quello che vedi dipende da come stai eseguendo Claude Code:

408 

409* **In una sessione interattiva**: `/mcp` mostra il server come in sospeso mentre Claude Code si riconnette. Dopo cinque tentativi falliti, Claude Code contrassegna il server come fallito, o come necessitante di autenticazione quando il server ha bisogno di autorizzazione di nuovo. Puoi ritentare manualmente da `/mcp`.

410* **In esecuzioni [`claude -p`](/docs/it/headless) e sessioni [Agent SDK](/docs/it/agent-sdk/overview)**: Claude Code si riconnette secondo lo stesso programma, senza pannello `/mcp` per mostrare i tentativi.

216 411 

217Lo stesso backoff si applica quando un server HTTP o SSE non riesce la sua connessione iniziale all'avvio. A partire dalla v2.1.121, Claude Code ritenta la connessione iniziale fino a tre volte su errori transitori come una risposta 5xx, una connessione rifiutata o un timeout, quindi contrassegna il server come non riuscito se ancora non riesce a connettersi. Gli errori di autenticazione e di non trovato non vengono ritentati perché richiedono una modifica della configurazione per essere risolti.412<h4 id="failed-first-connections">

413 Connessioni iniziali fallite

414</h4>

218 415 

219Quando un server configurato non riesce a connettersi, Claude Code dice a Claude quale server non ha avuto successo e il suo errore di connessione, incluso nei risultati `ToolSearch` che non trovano alcuno strumento corrispondente, in modo che Claude segnali l'errore di connessione nella sua risposta. Richiede la [ricerca degli strumenti](#scale-with-mcp-tool-search), che è abilitata per impostazione predefinita. Nelle configurazioni senza ricerca degli strumenti, come un `ANTHROPIC_BASE_URL` personalizzato, `ENABLE_TOOL_SEARCH=false`, o un modello che non supporta la ricerca degli strumenti, e su Amazon Bedrock, Google Cloud's Agent Platform, e Microsoft Foundry, Claude Code non segnala gli errori di connessione del server fallito a Claude. Prima della v2.1.205, Claude Code non passava gli errori di connessione a Claude, e Claude poteva rispondere come se gli strumenti del server fallito non fossero mai stati configurati.416Quando la prima connessione di un server HTTP o SSE fallisce con un errore transitorio, come una risposta 5xx, una connessione rifiutata, o un timeout, Claude Code ritenta fino a tre volte. Se la connessione fallisce ancora, Claude Code contrassegna il server come fallito. Claude Code ritenta in questo modo all'avvio e quando un server viene aggiunto a metà sessione. Questo include un server che Claude Code aggiunge a una [sessione cloud](/docs/it/claude-code-on-the-web) dalla sua configurazione e un server che aggiungi con il metodo [`setMcpServers()`](/docs/it/agent-sdk/typescript) dell'Agent SDK.

220 417 

221A partire dalla v2.1.191, le richieste di scoperta delle capacità che vengono eseguite dopo una connessione riuscita, come `tools/list`, `prompts/list`, e `resources/list`, ritentano anche gli errori di rete transitori e del server fino a tre volte con backoff breve. Gli errori di autenticazione, le risposte 4xx e i timeout delle richieste non vengono ritentati.418Claude Code non ritenta in questi casi:

419 

420* La prima connessione di un server WebSocket

421* Un errore di autenticazione o non trovato, perché richiede una modifica della configurazione per risolvere. Quando un [`headersHelper`](#use-dynamic-headers-for-custom-authentication) è l'unica fonte dell'intestazione `Authorization` del server, Claude Code ritenta comunque un errore di autenticazione, perché riesegue l'helper ad ogni tentativo e può raccogliere una credenziale fresca

422 

423<h4 id="failed-discovery-requests">

424 Richieste di scoperta fallite

425</h4>

426 

427Dopo che un server si connette, Claude Code gli invia richieste di scoperta delle capacità come `tools/list`, `prompts/list`, e `resources/list`. Claude Code ritenta quelle richieste fino a tre volte con backoff breve dopo un errore di rete o server transitorio. Non ritenta errori di autenticazione, risposte 4xx, o timeout delle richieste.

428 

429<h4 id="how-claude-learns-that-a-server-failed">

430 Come Claude apprende che un server è fallito

431</h4>

432 

433Se Claude Code dice a Claude di un server configurato che non si è connesso dipende dalla [ricerca degli strumenti](#scale-with-mcp-tool-search), che è attivata per impostazione predefinita:

434 

435* Con ricerca degli strumenti, Claude Code dice a Claude quale server è fallito e il suo errore di connessione, quindi Claude segnala il fallimento della connessione nella sua risposta. Claude Code include le stesse informazioni nei risultati di `ToolSearch` che non trovano alcuno strumento corrispondente.

436* In qualsiasi [configurazione senza ricerca degli strumenti](#configure-tool-search), Claude Code non segnala i fallimenti di connessione del server configurato a Claude.

222 437 

223<h3 id="push-messages-with-channels">438<h3 id="push-messages-with-channels">

224 Invia messaggi con canali439 Inviare messaggi con i canali

225</h3>440</h3>

226 441 

227Un server MCP può anche inviare messaggi direttamente nella vostra sessione in modo che Claude possa reagire a eventi esterni come risultati CI, avvisi di monitoraggio o messaggi di chat. Per abilitare questa funzionalità, il vostro server dichiara la capacità `claude/channel` e voi la abilitate con il flag `--channels` all'avvio. Vedi [Channels](/docs/it/channels) per utilizzare un canale ufficialmente supportato, oppure [Channels reference](/docs/it/channels-reference) per costruire il vostro.442Un server MCP può anche inviare messaggi direttamente nella tua sessione in modo che Claude possa reagire a eventi esterni come risultati CI, avvisi di monitoraggio, o messaggi di chat. Per abilitare questo, il tuo server dichiara la capacità `claude/channel` e tu lo attivi con il flag `--channels` all'avvio. Vedi [Canali](/docs/it/channels) per utilizzare un canale ufficialmente supportato, o [Riferimento dei canali](/docs/it/channels-reference) per costruire il tuo.

443 

444Sul [runtime v2](#mcp-client-runtimes), se imposti [`MCP_PROTOCOL_NEGOTIATION`](/docs/it/env-vars) su `auto` e un server di canale negozia la revisione del protocollo MCP 2026-07-28, non può consegnare messaggi di canale, quindi Claude Code non lo registra come canale. Lasciare la variabile non impostata, o impostarla su `legacy`, mantiene i server stdio sul handshake precedente.

228 445 

229<Tip>446<Tip>

230 Suggerimenti:447 Suggerimenti:

231 448 

232 * Utilizza il flag `-s` o `--scope` per specificare dove viene archiviata la configurazione:449 * Utilizza il flag `-s` o `--scope` per specificare dove viene memorizzata la configurazione:

233 * `local` (predefinito): disponibile solo per voi nel progetto corrente. Le versioni precedenti chiamavano questo ambito `project`450 * `local` (predefinito): disponibile solo per te nel progetto corrente

234 * `project`: condiviso con tutti nel progetto tramite il file `.mcp.json`451 * `project`: condiviso con tutti nel progetto tramite il file `.mcp.json`

235 * `user`: disponibile per voi in tutti i progetti. Le versioni precedenti chiamavano questo ambito `global`452 * `user`: disponibile per te in tutti i progetti

236 * Imposta le variabili di ambiente con i flag `-e` o `--env` (per esempio, `-e KEY=value`)453 * Imposta le variabili di ambiente con i flag `-e` o `--env` (ad esempio, `-e KEY=value`)

237 * I flag `--transport` e `--header` accettano anche le forme brevi `-t` e `-H`454 * I flag `--transport` e `--header` accettano anche le forme brevi `-t` e `-H`

238 * Configura il timeout di avvio del server MCP utilizzando la variabile di ambiente `MCP_TIMEOUT` (per esempio, `MCP_TIMEOUT=10000 claude` imposta un timeout di 10 secondi)455 * Configura il timeout di avvio del server MCP utilizzando la variabile di ambiente `MCP_TIMEOUT` (ad esempio, `MCP_TIMEOUT=10000 claude` imposta un timeout di 10 secondi)

239 * Imposta un timeout di esecuzione dello strumento per server aggiungendo un campo `timeout` in millisecondi alla voce `.mcp.json` di quel server, per esempio `"timeout": 600000` per dieci minuti. Questo sostituisce la variabile di ambiente `MCP_TOOL_TIMEOUT` solo per quel server456 * Imposta un timeout di esecuzione dello strumento per server aggiungendo un campo `timeout` in millisecondi alla voce `.mcp.json` di quel server, ad esempio `"timeout": 600000` per dieci minuti. Questo sostituisce la variabile di ambiente `MCP_TOOL_TIMEOUT` solo per quel server

240 * Claude Code visualizza un avviso quando l'output dello strumento MCP supera 10.000 token e limita l'output a 25.000 token per impostazione predefinita. Per aumentare il limite, imposta la variabile di ambiente `MAX_MCP_OUTPUT_TOKENS` (per esempio, `MAX_MCP_OUTPUT_TOKENS=50000`); la soglia di avviso è fissa. Vedi [Limiti di output MCP e avvisi](#mcp-output-limits-and-warnings)457 * Claude Code visualizza un avviso quando l'output dello strumento MCP supera 10.000 token e limita l'output a 25.000 token per impostazione predefinita. Per aumentare il limite, imposta la variabile di ambiente `MAX_MCP_OUTPUT_TOKENS` (ad esempio, `MAX_MCP_OUTPUT_TOKENS=50000`); la soglia di avviso è fissa. Vedi [Limiti di output MCP e avvisi](#mcp-output-limits-and-warnings)

241 * Utilizza `/mcp` per autenticarti con server remoti che richiedono l'autenticazione OAuth 2.0458 * Utilizza `/mcp` per autenticarti con server remoti che richiedono l'autenticazione OAuth 2.0

242</Tip>459</Tip>

243 460 

244Il timeout per server è un limite rigido di wall-clock per chiamata dello strumento, e le notifiche di progresso dal server non lo estendono. I valori inferiori a 1000 sono ignorati e ricadono in `MCP_TOOL_TIMEOUT`, o nel suo valore predefinito di circa 28 ore quando quella variabile non è impostata. Per un server HTTP, SSE, o [connettore claude.ai](/docs/it/mcp#use-mcp-servers-from-claude-ai) c'è anche un secondo timer per richiesta che copre ogni richiesta fino al primo byte di risposta del server. Quel timer è di 60 secondi a meno che non impostiate il timeout per server o `MCP_TOOL_TIMEOUT`; impostare uno di essi a 60 secondi o superiore aumenta il timer per richiesta a quel valore, un valore inferiore non lo accorcia, e il valore predefinito di 28 ore di un `MCP_TOOL_TIMEOUT` non impostato non lo alimenta mai. I server stdio e WebSocket non hanno un timer per richiesta. Prima della v2.1.162, i valori inferiori a 1000 erano arrotondati a un secondo.461Il `timeout` per server è un limite di wall-clock duro per chiamata di strumento, e le notifiche di progresso dal server non lo estendono. I valori inferiori a 1000 vengono ignorati e ricadono in `MCP_TOOL_TIMEOUT`, o nel suo valore predefinito di circa 28 ore quando quella variabile non è impostata. Per un server HTTP, SSE, o [connettore claude.ai](/docs/it/mcp#use-mcp-servers-from-claude-ai) c'è anche un secondo timer per richiesta che copre ogni richiesta fino al primo byte di risposta del server. Claude Code imposta quel timer al massimo di tre valori: 60 secondi, il timeout dello strumento che si applica al server, e `MCP_TIMEOUT`. Il valore predefinito di 28 ore di un `MCP_TOOL_TIMEOUT` non impostato non entra in quel confronto, e un valore inferiore a 60 secondi non accorcia il timer. I server stdio e WebSocket non hanno un timer per richiesta.

462 

463Un `timeout` per server di almeno 1000 agisce anche come un pavimento sul timeout di inattività descritto di seguito: Claude Code non interrompe mai le chiamate di strumento di quel server per inattività prima del `timeout` per server. Richiede Claude Code v2.1.203 o successivo.

464 

465Una chiamata di strumento a un server MCP che non invia risposta e nessuna notifica di progresso per la finestra di inattività interrompe con un errore invece di attendere il limite di wall-clock. Il timeout di inattività richiede Claude Code v2.1.187 o successivo. Si applica a ogni tipo di server tranne i server IDE e i server in-process dell'SDK. La finestra di inattività è predefinita a cinque minuti per i server HTTP, SSE, WebSocket, e [connettore claude.ai](#use-mcp-servers-from-claude-ai), e a 30 minuti per i server stdio. Prima della v2.1.203, i server stdio erano esenti dal timeout di inattività.

466 

467Imposta la variabile di ambiente [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/docs/it/env-vars) in millisecondi per cambiare la finestra di inattività, o impostala su `0` per disabilitare il controllo.

468 

469Questi timeout limitano quanto a lungo una chiamata può essere eseguita, non sempre quanto a lungo blocca la sessione: una chiamata della conversazione principale che viene eseguita oltre due minuti si sposta prima a un'attività in background. Vedi [Backgrounding automatico delle lunghe chiamate di strumento](#automatic-backgrounding-of-long-tool-calls).

245 470 

246Un timeout per server di almeno 1000 agisce anche come limite inferiore sul timeout di inattività descritto di seguito: Claude Code non interrompe mai le chiamate dello strumento di quel server per inattività prima del timeout per server. Richiede Claude Code v2.1.203 o successivo.471<h3 id="automatic-backgrounding-of-long-tool-calls">

472 Backgrounding automatico delle lunghe chiamate di strumento

473</h3>

474 

475Una chiamata di strumento MCP nella conversazione principale che è ancora in esecuzione dopo due minuti si sposta a un'attività in background invece di bloccare la sessione. Claude riceve l'ID dell'attività immediatamente e continua a lavorare, e il risultato arriva come una notifica di attività quando la chiamata si conclude. Il backgrounding automatico richiede Claude Code v2.1.212 o successivo.

476 

477L'attività appare in [`/tasks`](/docs/it/commands#all-commands), dove puoi anche fermarla, e non sopravvive all'uscita dalla sessione. I limiti per chiamata si applicano ancora mentre la chiamata viene eseguita in background: il limite di wall-clock impostato dal `timeout` per server o [`MCP_TOOL_TIMEOUT`](/docs/it/env-vars), e il timeout di inattività impostato da [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/docs/it/env-vars).

247 478 

248Una chiamata dello strumento a un server MCP che non invia alcuna risposta e nessuna notifica di progresso per la finestra di inattività si interrompe con un errore invece di attendere il limite di wall-clock. Il timeout di inattività richiede Claude Code v2.1.187 o successivo. Si applica a ogni tipo di server tranne i server IDE e i server in-process SDK. La finestra di inattività è predefinita a cinque minuti per i server HTTP, SSE, WebSocket, e [connettore claude.ai](#use-mcp-servers-from-claude-ai), e a 30 minuti per i server stdio. Prima della v2.1.203, i server stdio erano esenti dal timeout di inattività.479Imposta la variabile di ambiente [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](/docs/it/env-vars) in millisecondi per cambiare la soglia, o impostala su `0` per disattivare il backgrounding automatico. Impostare `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` su `1` lo disattiva anche, insieme a tutte le altre funzionalità di attività in background.

249 480 

250Imposta la variabile di ambiente [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/docs/it/env-vars) in millisecondi per modificare la finestra di inattività, o impostala su `0` per disabilitare il controllo.481Alcune chiamate non si spostano mai in background:

482 

483* Chiamate da [subagenti](/docs/it/sub-agents); Claude Code mette in background solo le chiamate della conversazione principale

484* Chiamate ai server IDE

485* Chiamate in [modalità non interattiva](/docs/it/headless), a meno che `CLAUDE_AUTO_BACKGROUND_TASKS` non sia impostato su `1`, poiché un'esecuzione una tantum può terminare prima che il risultato arrivi

486 

487Una chiamata in attesa di una [finestra di dialogo di elicitazione](#respond-to-mcp-elicitation-requests) aperta non viene messa in background mentre la finestra di dialogo è aperta; il server è bloccato sul tuo input, non lento, quindi Claude Code rinvia lo spostamento fino a quando la finestra di dialogo non si chiude.

251 488 

252<h3 id="plugin-provided-mcp-servers">489<h3 id="plugin-provided-mcp-servers">

253 Server MCP forniti da plugin490 Server MCP forniti da plugin

254</h3>491</h3>

255 492 

256I [plugin](/docs/it/plugins) possono raggruppare server MCP, fornendo automaticamente strumenti e integrazioni quando il plugin è abilitato. I server MCP dei plugin funzionano in modo identico ai server configurati dall'utente.493I [plugin](/docs/it/plugins) possono raggruppare server MCP che forniscono strumenti e integrazioni quando abiliti il plugin. I server MCP forniti da plugin funzionano in modo identico ai server configurati dall'utente.

257 494 

258**Come funzionano i server MCP dei plugin**:495**Come funzionano i server MCP forniti da plugin**:

259 496 

260* I plugin definiscono i server MCP in `.mcp.json` nella radice del plugin o inline in `plugin.json`497* I plugin definiscono i server MCP in `.mcp.json` alla radice del plugin o inline in `plugin.json`

261* Quando un plugin è abilitato, i suoi server MCP si avviano automaticamente498* Quando abiliti un plugin, Claude Code avvia automaticamente i suoi server MCP

262* Gli strumenti MCP del plugin appaiono insieme agli strumenti MCP configurati manualmente499* Claude Code offre gli strumenti MCP del plugin insieme agli strumenti MCP configurati manualmente

263* I server dei plugin vengono gestiti tramite l'installazione del plugin, non tramite comandi `/mcp`500* Aggiungi e rimuovi i server di plugin installando o disinstallando il plugin, non con i comandi `/mcp`. Puoi comunque [attivare/disattivare un server di plugin installato](#disable-a-server-without-removing-it) in `/mcp`, che impedisce a Claude Code di connettersi ad esso senza rimuovere il plugin

264 501 

265**Esempio di configurazione MCP del plugin**:502**Esempio di configurazione MCP del plugin**:

266 503 

267In `.mcp.json` nella radice del plugin:504In `.mcp.json` alla radice del plugin:

268 505 

269```json theme={null}506```json theme={null}

270{507{

296 533 

297**Funzionalità MCP del plugin**:534**Funzionalità MCP del plugin**:

298 535 

299* **Ciclo di vita automatico**: all'avvio della sessione, i server per i plugin abilitati si connettono automaticamente. Se abilitate o disabilitate un plugin durante una sessione, eseguite `/reload-plugins` per connettere o disconnettere i suoi server MCP536* **Ciclo di vita automatico**: i server si connettono e si disconnettono in questi punti:

300* **Variabili di percorso**: `${CLAUDE_PLUGIN_ROOT}` si risolve nella directory di installazione del plugin, `${CLAUDE_PLUGIN_DATA}` nella sua directory di [stato persistente](/docs/it/plugins-reference#persistent-data-directory), e `${CLAUDE_PROJECT_DIR}` nella radice stabile del progetto. La sostituzione si applica a:537 * All'avvio della sessione, Claude Code connette automaticamente i server per i plugin abilitati. In `/mcp`, un server di plugin remoto (HTTP o SSE) che hai usato prima può mostrare lo stato [`cached`](#server-status-detail) invece; Claude Code lo connette quando Claude chiama per la prima volta uno dei suoi strumenti

538 * Se abiliti o disabiliti un plugin durante una sessione, esegui `/reload-plugins` per connettere o disconnettere i suoi server MCP. In una sessione senza un terminale interattivo, il ricaricamento non connette o disconnette i server MCP del plugin; quelle modifiche hanno effetto nella tua prossima sessione

539 * Quando ricarichi, Claude Code mantiene le connessioni live dei server di plugin la cui configurazione è invariata, e fa lo stesso quando [sostituisci l'elenco dei server MCP della sessione](/docs/it/agent-sdk/typescript#mcpsetserversresult) dall'Agent SDK senza nominarli

540 * Quando [sposti la sessione con `/cd`](/docs/it/permissions#move-the-session-to-another-directory) su v2.1.246 o successivo, Claude Code connette i server dei plugin che le impostazioni della nuova directory abilitano e disconnette i server dei plugin che non sono più abilitati, quindi non devi eseguire `/reload-plugins` dopo lo spostamento

541 * Nelle [sessioni web](/docs/it/claude-code-on-the-web), una chiamata MCP a un server di plugin che non è ancora connesso, come subito dopo il risveglio di una sessione inattiva, avvia il server su richiesta e attende che si connetta

542* **Segnaposti di percorso**: `${CLAUDE_PLUGIN_ROOT}` si risolve nella directory di installazione del plugin, `${CLAUDE_PLUGIN_DATA}` nella sua directory di [stato persistente](/docs/it/plugins-reference#persistent-data-directory), e `${CLAUDE_PROJECT_DIR}` nella radice del progetto stabile. La sostituzione si applica a:

301 * server `stdio`: `command`, `args`, `env`543 * server `stdio`: `command`, `args`, `env`

302 * server `http`, `sse`, e `ws`: `url`, `headers`, e `headersHelper`. Prima della v2.1.195, `headersHelper` passava il segnaposto come una stringa letterale544 * server `http`, `sse`, e `ws`: `url`, `headers`, e `headersHelper`. Prima della v2.1.195, `headersHelper` passava il segnaposto come una stringa letterale

303* **Accesso alle variabili di ambiente dell'utente**: accesso alle stesse variabili di ambiente dei server configurati manualmente545* **Accesso all'ambiente utente**: accesso alle stesse variabili di ambiente dei server configurati manualmente

304* **Tipi di trasporto multipli**: supporto per trasporti stdio, SSE, HTTP e WebSocket, anche se il supporto del trasporto può variare a seconda del server546* **Tipi di trasporto multipli**: supporto per trasporti stdio, SSE, HTTP, e WebSocket, anche se il supporto del trasporto può variare per server

305 

306**Visualizzazione dei server MCP del plugin**:

307 547 

308```bash theme={null}548I server di plugin appaiono in `/mcp` con indicatori che mostrano che provengono da plugin.

309# All'interno di Claude Code, vedi tutti i server MCP inclusi quelli dei plugin

310/mcp

311```

312 

313I server dei plugin appaiono nell'elenco con indicatori che mostrano che provengono dai plugin.

314 549 

315**Nomi degli strumenti MCP del plugin**:550**Nomi degli strumenti MCP del plugin**:

316 551 

317Gli strumenti da un server MCP raggruppato in un plugin includono sia il nome del plugin che la chiave del server nel loro nome richiamabile. La forma completa è `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`, dove qualsiasi carattere al di fuori di `A-Z`, `a-z`, `0-9`, `_`, e `-` viene sostituito con `_`. Per il server `database-tools` raggruppato in un plugin denominato `my-plugin`, uno strumento `query` è richiamabile come:552Gli strumenti da un server MCP raggruppato da un plugin includono sia il nome del plugin che la chiave del server nel loro nome richiamabile. La forma completa è `mcp__plugin_<plugin-name>_<server-name>__<tool-name>`, dove qualsiasi carattere al di fuori di `A-Z`, `a-z`, `0-9`, `_`, e `-` viene sostituito con `_`. Per il server `database-tools` raggruppato in un plugin denominato `my-plugin`, uno strumento `query` è richiamabile come:

318 553 

319```554```

320mcp__plugin_my-plugin_database-tools__query555mcp__plugin_my-plugin_database-tools__query

321```556```

322 557 

323Utilizza questo nome completo quando fai riferimento allo strumento nelle [regole di autorizzazione](/docs/it/permissions), nell'elenco `allowed-tools` di una skill, nel [campo `tools` di un subagent](/docs/it/sub-agents#available-tools), o in un [matcher di hook](/docs/it/hooks#match-mcp-tools). Un matcher di hook scritto rispetto alla chiave del server nuda, come `mcp__database-tools__.*`, non si attiva mai per un server raggruppato in un plugin.558Utilizza questo nome completo quando fai riferimento allo strumento nelle [regole di autorizzazione](/docs/it/permissions), nell'elenco `allowed-tools` di una skill, nel [campo `tools` di un subagente](/docs/it/sub-agents#available-tools), o in un [matcher di hook](/docs/it/hooks#match-mcp-tools). Un matcher di hook scritto contro la chiave del server nudo, come `mcp__database-tools__.*`, non si attiva mai per un server raggruppato da un plugin.

324 

325Il server stesso si registra sotto il nome con ambito `plugin:<plugin-name>:<server-name>`, come `plugin:my-plugin:database-tools`. Utilizza quel nome dove è previsto un nome di server configurato, come il [campo `server` di un hook `mcp_tool`](/docs/it/hooks#mcp-tool-hook-fields).

326 

327**Vantaggi dei server MCP dei plugin**:

328 559 

329* **Distribuzione raggruppata**: strumenti e server confezionati insieme560Il server stesso si registra con il nome con ambito `plugin:<plugin-name>:<server-name>`, come `plugin:my-plugin:database-tools`. Utilizza quel nome dove è previsto un nome di server configurato, come il [campo `server` di un hook `mcp_tool`](/docs/it/hooks#mcp-tool-hook-fields).

330* **Configurazione automatica**: nessuna configurazione MCP manuale necessaria

331* **Coerenza del team**: tutti ottengono gli stessi strumenti quando il plugin è installato

332 561 

333Vedi il [riferimento dei componenti del plugin](/docs/it/plugins-reference#mcp-servers) per i dettagli su come raggruppare i server MCP con i plugin.562Vedi il [riferimento dei componenti del plugin](/docs/it/plugins-reference#mcp-servers) per i dettagli sul raggruppamento dei server MCP con i plugin.

334 563 

335<h2 id="mcp-installation-scopes">564<h2 id="mcp-installation-scopes">

336 Ambiti di installazione MCP565 Ambiti di installazione MCP

337</h2>566</h2>

338 567 

339I server MCP possono essere configurati a tre ambiti diversi. L'ambito che scegli controlla in quali progetti il server viene caricato e se la configurazione è condivisa con il tuo team. Gli amministratori possono anche distribuire server a livello aziendale tramite [configurazione gestita](#managed-mcp-configuration).568I server MCP possono essere configurati a tre ambiti diversi. L'ambito che scegli controlla in quali progetti il server viene caricato e se la configurazione è condivisa con il tuo team. Gli amministratori possono anche distribuire o fornire server a ogni utente tramite [configurazione gestita](#managed-mcp-configuration).

340 569 

341| Ambito | Carica in | Condiviso con il team | Archiviato in |570| Ambito | Carica in | Condiviso con il team | Archiviato in |

342| -------------------------- | ------------------------- | ------------------------------------ | ------------------------------------- |571| -------------------------- | ------------------------- | ------------------------------------ | ------------------------------------- |

351L'ambito locale è il predefinito. Un server con ambito locale viene caricato solo nel progetto in cui lo hai aggiunto e rimane privato per te. Claude Code lo archivia in `~/.claude.json` nel percorso di quel progetto, quindi lo stesso server non apparirà nei tuoi altri progetti. Utilizza l'ambito locale per server di sviluppo personali, configurazioni sperimentali o server con credenziali che non desideri nel controllo della versione.580L'ambito locale è il predefinito. Un server con ambito locale viene caricato solo nel progetto in cui lo hai aggiunto e rimane privato per te. Claude Code lo archivia in `~/.claude.json` nel percorso di quel progetto, quindi lo stesso server non apparirà nei tuoi altri progetti. Utilizza l'ambito locale per server di sviluppo personali, configurazioni sperimentali o server con credenziali che non desideri nel controllo della versione.

352 581 

353<Note>582<Note>

354 Il termine "ambito locale" per i server MCP differisce dalle impostazioni locali generali. I server MCP con ambito locale vengono archiviati in `~/.claude.json` (la tua directory home), mentre le impostazioni locali generali utilizzano `.claude/settings.local.json` (nella directory del progetto). Vedi [Impostazioni](/docs/it/settings#settings-files) per i dettagli sui percorsi dei file di impostazioni.583 Il termine "ambito locale" per i server MCP differisce dalle impostazioni locali generali. I server MCP con ambito locale vengono archiviati in `~/.claude.json` (la tua directory home), mentre le impostazioni locali generali utilizzano `.claude/settings.local.json` (nella directory del progetto). Vedi [Impostazioni](/docs/it/settings#where-settings-live) per i dettagli sui percorsi dei file di impostazioni.

355</Note>584</Note>

356 585 

357```bash theme={null}586```bash theme={null}

358# Aggiungi un server con ambito locale (predefinito)587# Aggiungi un server con ambio locale (predefinito)

359claude mcp add --transport http stripe https://mcp.stripe.com588claude mcp add --transport http stripe https://mcp.stripe.com

360 589 

361# Specifica esplicitamente l'ambito locale590# Specifica esplicitamente l'ambito locale

383 Ambito del progetto612 Ambito del progetto

384</h3>613</h3>

385 614 

386I server con ambito del progetto abilitano la collaborazione del team archiviando le configurazioni in un file `.mcp.json` nella directory radice del tuo progetto. Questo file è progettato per essere archiviato nel controllo della versione, assicurando che tutti i membri del team abbiano accesso agli stessi strumenti e servizi MCP. Quando aggiungi un server con ambito del progetto, Claude Code crea o aggiorna automaticamente questo file con la struttura di configurazione appropriata.615I server con ambito del progetto abilitano la collaborazione del team archiviando le configurazioni in un file `.mcp.json` nella directory radice del tuo progetto. Quando aggiungi un server con ambito del progetto, Claude Code crea o aggiorna automaticamente questo file con la struttura di configurazione appropriata. Archivia `.mcp.json` nel controllo della versione in modo che tutti nel tuo team ottengano gli stessi strumenti e servizi MCP.

387 616 

388```bash theme={null}617```bash theme={null}

389# Aggiungi un server con ambito del progetto618# Aggiungi un server con ambito del progetto

390claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp619claude mcp add --transport http shared-server --scope project https://example.com/mcp

391```620```

392 621 

393Il file `.mcp.json` risultante segue un formato standardizzato:622Il file `.mcp.json` risultante segue un formato standardizzato:

396{625{

397 "mcpServers": {626 "mcpServers": {

398 "shared-server": {627 "shared-server": {

399 "command": "/path/to/server",628 "type": "http",

400 "args": [],629 "url": "https://example.com/mcp"

401 "env": {}

402 }630 }

403 }631 }

404}632}

405```633```

406 634 

407Per motivi di sicurezza, Claude Code richiede l'approvazione prima di utilizzare server con ambito del progetto dai file `.mcp.json`. Se devi ripristinare queste scelte di approvazione, utilizza il comando `claude mcp reset-project-choices`.635Per motivi di sicurezza, Claude Code richiede l'approvazione in sessioni interattive prima di utilizzare server con ambito del progetto dai file `.mcp.json`. Per ripristinare queste scelte di approvazione, esegui `claude mcp reset-project-choices`.

636 

637Nelle esecuzioni `claude -p`, nelle sessioni [Agent SDK](/docs/it/headless) e nelle [sessioni cloud](/docs/it/claude-code-on-the-web), Claude Code non può mostrare quel prompt: carica i server con ambito del progetto senza chiedere. Claude Code salta anche il prompt in una sessione che avvii in modalità `bypassPermissions` con [`skipDangerousModePermissionPrompt`](/docs/it/settings-reference#skipdangerousmodepermissionprompt) impostato. Per mantenere un server fuori comunque:

638 

639* Aggiungilo a [`disabledMcpjsonServers`](/docs/it/settings-reference#disabledmcpjsonservers), che lo blocca in ogni modalità di autorizzazione.

640* Escludi completamente le impostazioni del progetto con [`--setting-sources`](/docs/it/cli-reference#cli-flags) o l'opzione `settingSources` dell'SDK.

641* Avvia la sessione con [`--strict-mcp-config`](/docs/it/cli-reference#cli-flags). Claude Code utilizza quindi solo i server MCP che passi con `--mcp-config`. Saltare il prompt di approvazione per i server con ambito del progetto che Claude Code non sta caricando richiede Claude Code v2.1.246 o successivo; prima di v2.1.246, una sessione ristretta attendeva comunque l'approvazione per loro, il che lasciava le sessioni in background in attesa all'avvio. Vedi [Controllo esclusivo con managed-mcp.json](/docs/it/managed-mcp#exclusive-control-with-managed-mcp-json) per quello che il flag fa sotto un file MCP gestito.

642 

643[Approvazioni del server del progetto e fiducia dell'area di lavoro](#project-server-approvals-and-workspace-trust) copre come le approvazioni impegnate nel repository interagiscono con la fiducia dell'area di lavoro.

408 644 

409<h3 id="user-scope">645<h3 id="user-scope">

410 Ambito utente646 Ambito utente

431 667 

432I tre ambiti corrispondono ai duplicati per nome. I plugin e i connettori corrispondono per endpoint, quindi uno che punta allo stesso URL o comando di un server sopra è trattato come un duplicato.668I tre ambiti corrispondono ai duplicati per nome. I plugin e i connettori corrispondono per endpoint, quindi uno che punta allo stesso URL o comando di un server sopra è trattato come un duplicato.

433 669 

670Un server che la tua organizzazione fornisce tramite l'impostazione gestita [`managedMcpServers`](/docs/it/managed-mcp#provide-servers-through-managed-settings) si classifica al di sopra di tutti questi, quindi quando uno di loro lo duplica, Claude Code si connette alla definizione dell'organizzazione. Richiede Claude Code v2.1.259 o successivo.

671 

672Se apri una sessione locale nella [scheda Code dell'app Desktop](/docs/it/desktop#mcp-servers-from-the-claude-desktop-chat-app) con lo stesso nome di server stdio al livello superiore di `~/.claude.json` (ambito utente) e in `.mcp.json`, la scheda Code utilizza la definizione `~/.claude.json`.

673 

434<h3 id="environment-variable-expansion-in-mcp-json">674<h3 id="environment-variable-expansion-in-mcp-json">

435 Espansione delle variabili di ambiente in `.mcp.json`675 Espansione delle variabili di ambiente in `.mcp.json`

436</h3>676</h3>

467}707}

468```708```

469 709 

470Se una variabile di ambiente richiesta non è impostata e non ha un valore predefinito, Claude Code lascia il testo letterale `${VAR}` nel valore e segnala un avviso di variabile mancante per quel server. La configurazione viene comunque caricata, quindi imposta la variabile o aggiungi un fallback `:-default` in modo che il server si avvii con il valore che intendi.710Se una variabile di ambiente richiesta non è impostata e non ha un valore predefinito, la configurazione viene comunque caricata: Claude Code segnala un avviso di variabile mancante per quel server nell'output di `claude mcp list` e utilizza il testo `${VAR}` non espanso così com'è. Imposta la variabile o aggiungi un fallback `:-default` in modo che il server si avvii con il valore che intendi.

471 711 

472<h2 id="practical-examples">712<h2 id="practical-examples">

473 Esempi pratici713 Esempi pratici

474</h2>714</h2>

475 715 

476<h3 id="example-monitor-errors-with-sentry">

477 Esempio: Monitora gli errori con Sentry

478</h3>

479 

480```bash theme={null}

481claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

482```

483 

484Autenticati con il tuo account Sentry:

485 

486```text theme={null}

487/mcp

488```

489 

490Quindi esegui il debug dei problemi di produzione:

491 

492```text theme={null}

493Quali sono gli errori più comuni nelle ultime 24 ore?

494```

495 

496```text theme={null}

497Mostrami la stack trace per l'errore ID abc123

498```

499 

500```text theme={null}

501Quale deployment ha introdotto questi nuovi errori?

502```

503 

504<h3 id="example-connect-to-github-for-code-reviews">716<h3 id="example-connect-to-github-for-code-reviews">

505 Esempio: Connettiti a GitHub per le revisioni del codice717 Esempio: Connettiti a GitHub per le revisioni del codice

506</h3>718</h3>

512 --header "Authorization: Bearer YOUR_GITHUB_PAT"724 --header "Authorization: Bearer YOUR_GITHUB_PAT"

513```725```

514 726 

727Sostituisci `YOUR_GITHUB_PAT` con il tuo token di accesso personale. Il comando `claude mcp add` salva la configurazione senza convalidare le credenziali, quindi un valore segnaposto è accettato qui ma il server non riesce a connettersi in seguito. Per verificare la connessione, esegui `/mcp` e controlla che il server mostri `connected`. Un server con credenziali errate mostra `failed`, e il dettaglio dell'errore include lo stato HTTP che il server ha restituito, come un 401.

728 

515Quindi lavora con GitHub:729Quindi lavora con GitHub:

516 730 

517```text theme={null}731```text wrap theme={null}

518Rivedi la PR #456 e suggerisci miglioramenti732Rivedi la PR #456 e suggerisci miglioramenti

519```733```

520 734 

521```text theme={null}735```text wrap theme={null}

522Crea un nuovo issue per il bug che abbiamo appena trovato736Crea un nuovo issue per il bug che abbiamo appena trovato

523```737```

524 738 

525```text theme={null}739```text wrap theme={null}

526Mostrami tutte le PR aperte assegnate a me740Mostrami tutte le PR aperte assegnate a me

527```741```

528 742 

530 Esempio: Interroga il tuo database PostgreSQL744 Esempio: Interroga il tuo database PostgreSQL

531</h3>745</h3>

532 746 

747[DBHub](https://github.com/bytebase/dbhub), il pacchetto `@bytebase/dbhub`, è un server MCP che connette Claude a un database relazionale attraverso la stringa di connessione che passi in `--dsn`. Utilizza un utente di database di sola lettura nella stringa di connessione in modo che le query che Claude esegue non possano modificare i dati:

748 

533```bash theme={null}749```bash theme={null}

534claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \750claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \

535 --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"751 --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

536```752```

537 753 

754Per confermare che il server si avvia, esegui `/mcp` e controlla che `db` mostri `connected`.

755 

538Quindi interroga il tuo database naturalmente:756Quindi interroga il tuo database naturalmente:

539 757 

540```text theme={null}758```text wrap theme={null}

541Qual è il nostro ricavo totale questo mese?759Qual è il nostro ricavo totale questo mese?

542```760```

543 761 

544```text theme={null}762```text wrap theme={null}

545Mostrami lo schema per la tabella orders763Mostrami lo schema per la tabella orders

546```764```

547 765 

548```text theme={null}766```text wrap theme={null}

549Trova i clienti che non hanno effettuato un acquisto negli ultimi 90 giorni767Trova i clienti che non hanno effettuato un acquisto negli ultimi 90 giorni

550```768```

551 769 

555 773 

556Molti server MCP basati su cloud richiedono l'autenticazione. Claude Code supporta OAuth 2.0 per connessioni sicure.774Molti server MCP basati su cloud richiedono l'autenticazione. Claude Code supporta OAuth 2.0 per connessioni sicure.

557 775 

558Claude Code contrassegna un server remoto come richiedente autenticazione quando il server risponde con `401 Unauthorized` o `403 Forbidden`. Per un server a cui non hai effettuato l'accesso, uno di questi codici di stato lo contrassegna in `/mcp` in modo che tu possa completare il flusso OAuth.776Claude Code contrassegna un server remoto come richiedente autenticazione quando il server risponde con `401 Unauthorized` o `403 Forbidden`. Ciò che Claude Code mostra dipende dal server:

777 

778* Per un server a cui non hai effettuato l'accesso, uno di questi codici di stato lo contrassegna in `/mcp` in modo che tu possa completare il flusso OAuth.

779* Per un [connettore claude.ai](#use-mcp-servers-from-claude-ai), un `401` causato dal rifiuto di claude.ai del tuo token di sessione non contrassegna il connettore, perché la riautorizzazione del connettore non può risolvere il tuo accesso. Claude Code mostra invece lo [stato di rifiuto del token di sessione](/docs/it/errors#claude-ai-rejected-the-session-token).

780* Per un server il cui header `Authorization` hai configurato, in `headers` o tramite un [`headersHelper`](#use-dynamic-headers-for-custom-authentication), un `401` o `403` durante la connessione non contrassegna il server, perché la credenziale da correggere è quella che hai configurato. Claude Code segnala invece la connessione come non riuscita.

559 781 

560Quando una richiesta a un server OAuth a cui hai già effettuato l'accesso restituisce `401 Unauthorized`, Claude Code aggiorna il token archiviato, si riconnette e ritenta la richiesta una volta. Contrassegna il server in `/mcp` solo se anche quel tentativo non riesce. Prima della v2.1.206, un aggiornamento del token che non riusciva per un motivo transitorio, come un errore di rete, contrassegnava un server OAuth come richiedente autenticazione per il resto della sessione anche se il suo token di aggiornamento era ancora valido.782Quando una richiesta a un server OAuth a cui hai già effettuato l'accesso restituisce `401 Unauthorized`, Claude Code aggiorna il token archiviato, si riconnette e ritenta la richiesta una volta. Contrassegna il server in `/mcp` solo se anche quel tentativo non riesce. Prima della v2.1.206, un aggiornamento del token che non riusciva per un motivo transitorio, come un errore di rete, contrassegnava un server OAuth come richiedente autenticazione per il resto della sessione anche se il suo token di aggiornamento era ancora valido.

561 783 

562A partire da v2.1.195, quando un aggiornamento del token non riesce perché il server rifiuta il token di aggiornamento archiviato, Claude Code mostra immediatamente un avviso che punta a `/mcp`. Il menu del server connesso lì offre Re-authenticate, in modo che tu possa accedere di nuovo prima che la prossima chiamata dello strumento non riesca.784Quando il server rifiuta il token di aggiornamento archiviato, Claude Code mostra immediatamente un avviso che punta a `/mcp`. Apri `/mcp` e seleziona **Re-authenticate** sul server per accedere di nuovo prima che la prossima chiamata dello strumento non riesca.

563 785 

564Un server personalizzato che restituisce un'intestazione `WWW-Authenticate` che punta al suo server di autorizzazione ottiene la stessa scoperta automatica di qualsiasi altro server remoto.786Un server personalizzato che restituisce un header `WWW-Authenticate` che punta al suo server di autorizzazione ottiene la stessa scoperta automatica di qualsiasi altro server remoto.

565 787 

566A partire da v2.1.193, Claude Code mostra anche un avviso di avvio quando uno o più server configurati richiedono l'autenticazione, quindi non è necessario aprire `/mcp` per scoprire quali server richiedono l'accesso.788Claude Code mostra anche un avviso di avvio quando uno o più server configurati richiedono l'autenticazione, quindi non è necessario aprire `/mcp` per scoprire quali server richiedono l'accesso. L'avviso richiede Claude Code v2.1.193 o successiva. Conta solo i server a cui puoi accedere da Claude Code. Prima della v2.1.218, contava anche i [connettori claude.ai](#use-mcp-servers-from-claude-ai) che non erano connessi in claude.ai, che puoi connettere solo dalle impostazioni di claude.ai.

567 789 

568In modalità non interattiva non c'è un pannello `/mcp`, quindi Claude Code non può eseguire il flusso OAuth per te. A partire da v2.1.196, quando un server configurato richiede l'autenticazione durante un'esecuzione `claude -p` o Agent SDK con [ricerca degli strumenti](#scale-with-mcp-tool-search) abilitata, che è l'impostazione predefinita, Claude Code comunica a Claude che gli strumenti del server non sono disponibili fino a quando non lo autorizzi. Claude può quindi nominare il server che richiede l'accesso invece di rispondere come se il server non fosse configurato. Completa l'accesso da una sessione interattiva con `/mcp` o `claude mcp login <name>`.790In modalità non interattiva non c'è un pannello `/mcp`, quindi Claude Code non può eseguire il flusso OAuth per te. A partire da v2.1.196, quando un server configurato richiede l'autenticazione durante un'esecuzione `claude -p` o Agent SDK con [ricerca degli strumenti](#scale-with-mcp-tool-search) abilitata, che è l'impostazione predefinita, Claude Code comunica a Claude che gli strumenti del server non sono disponibili fino a quando non lo autorizzi. Claude può quindi nominare il server che richiede l'accesso invece di rispondere come se il server non fosse configurato. Completa l'accesso da una sessione interattiva con `/mcp` o `claude mcp login <name>`.

569 791 

570Se hai configurato `headers.Authorization` per il server e il server rifiuta quell'intestazione, Claude Code segnala la connessione come non riuscita invece di ricorrere a OAuth. Verifica che il token sia valido per l'endpoint MCP, oppure rimuovi l'intestazione per utilizzare il flusso OAuth.792Se hai configurato `headers.Authorization` per il server e il server rifiuta quell'header, Claude Code segnala la connessione come non riuscita invece di ricorrere a OAuth. Verifica che il token sia valido per l'endpoint MCP, oppure rimuovi l'header per utilizzare il flusso OAuth.

571 793 

572<Steps>794<Steps>

573 <Step title="Aggiungi il server che richiede l'autenticazione">795 <Step title="Aggiungi il server che richiede l'autenticazione">

574 Per esempio:796 Se hai già aggiunto il server `sentry` nella [guida rapida MCP](/docs/it/mcp-quickstart#connect-a-server-that-requires-sign-in), salta questo passaggio: eseguire di nuovo `claude mcp add` con lo stesso nome di server nello stesso ambito non riesce con `MCP server sentry already exists in local config`. Altrimenti, esegui:

575 797 

576 ```bash theme={null}798 ```bash theme={null}

577 claude mcp add --transport http sentry https://mcp.sentry.dev/mcp799 claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

581 <Step title="Utilizza il comando /mcp all'interno di Claude Code">803 <Step title="Utilizza il comando /mcp all'interno di Claude Code">

582 In Claude Code, utilizza il comando:804 In Claude Code, utilizza il comando:

583 805 

584 ```text theme={null}806 ```text wrap theme={null}

585 /mcp807 /mcp

586 ```808 ```

587 809 

621 Utilizza una porta di callback OAuth fissa843 Utilizza una porta di callback OAuth fissa

622</h3>844</h3>

623 845 

624Alcuni server MCP richiedono un URI di reindirizzamento specifico registrato in anticipo. Per impostazione predefinita, Claude Code sceglie una porta disponibile casuale per il callback OAuth. Utilizza `--callback-port` per fissare la porta in modo che corrisponda a un URI di reindirizzamento pre-registrato della forma `http://localhost:PORT/callback`.846Alcuni server MCP richiedono un URI di reindirizzamento specifico registrato in anticipo. Per impostazione predefinita, Claude Code sceglie una porta disponibile casuale per il callback OAuth. Utilizza `--callback-port` per fissare la porta in modo che corrisponda a un URI di reindirizzamento pre-registrato della forma `http://localhost:PORT/callback`. Se l'accesso su Claude Code v2.1.229 non riesce con una mancata corrispondenza dell'URI di reindirizzamento, vedi la nota sulla versione in [Utilizza credenziali OAuth pre-configurate](#use-pre-configured-oauth-credentials).

625 847 

626Puoi utilizzare `--callback-port` da solo (con registrazione dinamica del client) o insieme a `--client-id` (con credenziali pre-configurate).848Puoi utilizzare `--callback-port` da solo (con registrazione dinamica del client) o insieme a `--client-id` (con credenziali pre-configurate).

627 849 

643 Crea un'app tramite il portale degli sviluppatori del server e annota il tuo ID client e il segreto client.865 Crea un'app tramite il portale degli sviluppatori del server e annota il tuo ID client e il segreto client.

644 866 

645 Molti server richiedono anche un URI di reindirizzamento. Se è così, scegli una porta e registra un URI di reindirizzamento nel formato `http://localhost:PORT/callback`. Utilizza quella stessa porta con `--callback-port` nel passaggio successivo.867 Molti server richiedono anche un URI di reindirizzamento. Se è così, scegli una porta e registra un URI di reindirizzamento nel formato `http://localhost:PORT/callback`. Utilizza quella stessa porta con `--callback-port` nel passaggio successivo.

868 

869 In v2.1.229, Claude Code ha inviato `http://127.0.0.1:PORT/callback` invece, e i server che corrispondevano esattamente all'URI di reindirizzamento registrato hanno rifiutato l'accesso con una mancata corrispondenza dell'URI di reindirizzamento. Claude Code v2.1.231 ha ripristinato il modulo `localhost`. Per recuperare su v2.1.229, aggiorna Claude Code, oppure aggiungi temporaneamente il modulo `http://127.0.0.1:PORT/callback` agli URI di reindirizzamento registrati del server.

646 </Step>870 </Step>

647 871 

648 <Step title="Aggiungi il server con le tue credenziali">872 <Step title="Aggiungi il server con le tue credenziali">

649 Scegli uno dei seguenti metodi. La porta utilizzata per `--callback-port` può essere qualsiasi porta disponibile. Deve solo corrispondere all'URI di reindirizzamento che hai registrato nel passaggio precedente.873 Scegli uno dei seguenti metodi. La porta utilizzata per `--callback-port` può essere qualsiasi porta disponibile. Deve corrispondere all'URI di reindirizzamento che hai registrato nel passaggio precedente.

650 874 

651 <Tabs>875 <Tabs>

652 <Tab title="claude mcp add">876 <Tab title="claude mcp add">

700 924 

701 * Il segreto client viene archiviato in modo sicuro nel tuo portachiavi di sistema (macOS) o in un file di credenziali, non nella tua configurazione925 * Il segreto client viene archiviato in modo sicuro nel tuo portachiavi di sistema (macOS) o in un file di credenziali, non nella tua configurazione

702 * Se il server utilizza un client OAuth pubblico senza segreto, utilizza solo `--client-id` senza `--client-secret`926 * Se il server utilizza un client OAuth pubblico senza segreto, utilizza solo `--client-id` senza `--client-secret`

703 * `--callback-port` può essere utilizzato con o senza `--client-id`

704 * Questi flag si applicano solo ai trasporti HTTP e SSE. Non hanno effetto sui server stdio927 * Questi flag si applicano solo ai trasporti HTTP e SSE. Non hanno effetto sui server stdio

705 * Utilizza `claude mcp get <name>` per verificare che le credenziali OAuth siano configurate per un server928 * Utilizza `claude mcp get <name>` per verificare che le credenziali OAuth siano configurate per un server

706</Tip>929</Tip>

751 974 

752`oauth.scopes` ha la precedenza sia su `authServerMetadataUrl` che sugli ambiti che il server scopre su `/.well-known`. Lascialo non impostato per consentire al server MCP di determinare l'insieme di ambiti richiesti.975`oauth.scopes` ha la precedenza sia su `authServerMetadataUrl` che sugli ambiti che il server scopre su `/.well-known`. Lascialo non impostato per consentire al server MCP di determinare l'insieme di ambiti richiesti.

753 976 

754A partire da v2.1.196, quando `oauth.scopes` non è impostato, Claude Code richiede l'ambito fornito dall'intestazione `WWW-Authenticate` del server o dai suoi metadati della risorsa protetta, e non invia alcun parametro `scope` quando nessuno dei due lo fornisce. Non richiede più il catalogo completo di `scopes_supported` dai metadati del server di autorizzazione scoperto automaticamente. La richiesta di quel catalogo ha fatto sì che i provider di identità che pubblicizzano ambiti solo amministratore o modello rifiutassero la richiesta di autorizzazione con un errore `invalid_scope`. I metadati recuperati da un `authServerMetadataUrl` configurato forniscono comunque il loro `scopes_supported` come ambiti richiesti.977A partire da v2.1.196, quando `oauth.scopes` non è impostato, Claude Code richiede l'ambito fornito dall'header `WWW-Authenticate` del server o dai suoi metadati della risorsa protetta, e non invia alcun parametro `scope` quando nessuno dei due lo fornisce. Non richiede più il catalogo completo di `scopes_supported` dai metadati del server di autorizzazione scoperto automaticamente. La richiesta di quel catalogo ha fatto sì che i provider di identità che pubblicizzano ambiti solo amministratore o modello rifiutassero la richiesta di autorizzazione con un errore `invalid_scope`. I metadati recuperati da un `authServerMetadataUrl` configurato forniscono comunque il loro `scopes_supported` come ambiti richiesti.

755 978 

756Se il server di autorizzazione pubblicizza `offline_access` in `scopes_supported`, Claude Code lo aggiunge agli ambiti fissati in modo che il token di accesso possa essere aggiornato senza un nuovo accesso al browser.979Se il server di autorizzazione pubblicizza `offline_access` in `scopes_supported`, Claude Code lo aggiunge agli ambiti fissati in modo che il token di accesso possa essere aggiornato senza un nuovo accesso al browser.

757 980 

792**Requisiti:**1015**Requisiti:**

793 1016 

794* Il comando deve scrivere un oggetto JSON di coppie chiave-valore stringa su stdout1017* Il comando deve scrivere un oggetto JSON di coppie chiave-valore stringa su stdout

795* Il comando viene eseguito in una shell con un timeout di 10 secondi, dalla directory di lavoro corrente della sessione. Utilizza un percorso assoluto o un comando su `PATH` per lo script1018* Claude Code esegue il comando in una shell e rinuncia dopo 10 secondi

1019* Claude Code sceglie la directory di lavoro del comando in base a [dove hai configurato il server](#where-the-helper-runs), quindi fornisci lo script come percorso assoluto o mettilo su `PATH`

796* Le intestazioni dinamiche sovrascrivono qualsiasi `headers` statico con lo stesso nome1020* Le intestazioni dinamiche sovrascrivono qualsiasi `headers` statico con lo stesso nome

797 1021 

798L'helper viene eseguito di nuovo ad ogni connessione, all'avvio della sessione e alla riconnessione. Non c'è caching, quindi il tuo script è responsabile di qualsiasi riutilizzo di token.1022Claude Code esegue l'helper di nuovo ad ogni connessione, all'avvio della sessione e alla riconnessione, una volta che la [regola di fiducia per i server di ambito progetto e locale](#trust-a-folder-before-its-headershelper-runs) lo consente. Non memorizza il risultato nella cache, quindi il tuo script è responsabile di qualsiasi riutilizzo di token.

1023 

1024Se una chiamata di strumento restituisce `401 Unauthorized` o `403 Forbidden`, Claude Code esegue automaticamente di nuovo l'helper secondo la stessa regola, si riconnette con le intestazioni aggiornate e ritenta la chiamata una volta. Claude Code contrassegna il server come richiedente autenticazione in `/mcp` solo se anche quel tentativo non riesce.

1025 

1026Quando l'output dell'helper include un header `Authorization`, Claude Code utilizza quella credenziale come autenticazione del server e non ricorre a OAuth per il server.

799 1027 

800A partire da v2.1.193, se una chiamata di strumento restituisce `401 Unauthorized` o `403 Forbidden`, Claude Code esegue automaticamente di nuovo l'helper, si riconnette con le intestazioni aggiornate e ritenta la chiamata una volta. Claude Code contrassegna il server come richiedente autenticazione in `/mcp` solo se anche quel tentativo non riesce.1028Se il server rifiuta la credenziale dell'helper durante la connessione, Claude Code segnala la connessione come non riuscita piuttosto che contrassegnare il server come richiedente autenticazione. Correggi la credenziale che il tuo helper restituisce, quindi riconnettiti da `/mcp` per eseguire di nuovo l'helper.

801 1029 

802Claude Code imposta queste variabili di ambiente quando esegue l'helper:1030Claude Code imposta queste variabili di ambiente quando esegue l'helper:

803 1031 

809 1037 

810Utilizza questi per scrivere un singolo script helper che serve più server MCP.1038Utilizza questi per scrivere un singolo script helper che serve più server MCP.

811 1039 

812Per un server fornito da un plugin, l'helper viene eseguito anche con la sua directory di lavoro impostata sulla radice del plugin, quindi un percorso `headersHelper` relativo si risolve all'interno della directory del plugin piuttosto che rispetto alla directory di lavoro della sessione. Richiede Claude Code v2.1.195 o successiva.1040Un `headersHelper` fornito da un plugin non può fare riferimento ai valori [`${user_config.*}`](/docs/it/plugins-reference#user-configuration) del plugin, perché il comando viene eseguito attraverso una shell. Claude Code segnala il server come non configurato correttamente con un [errore](/docs/it/errors#plugin-command-references-user-config) e non sostituisce il valore. Metti `${user_config.KEY}` nel campo `headers` del server, che non viene analizzato dalla shell, oppure fai in modo che lo script helper legga il valore da un file di configurazione. Prima della v2.1.207, `headersHelper` sostituiva i valori `${user_config.*}`.

813 1041 

814Un `headersHelper` fornito da un plugin non può fare riferimento ai valori [`${user_config.*}`](/docs/it/plugins-reference#user-configuration) del plugin, perché il comando viene eseguito attraverso una shell. Claude Code segnala il server come non configurato correttamente con un [errore](/docs/it/errors#plugin-command-references-user-config) e non sostituisce il valore. Metti `${user_config.KEY}` nel campo `headers` del server, che non viene analizzato dalla shell, oppure fai in modo che lo script helper legga il valore dal suo ambiente o da un file di configurazione. Prima della v2.1.207, `headersHelper` sostituiva i valori `${user_config.*}`.1042<h4 id="where-the-helper-runs">

1043 Dove l'helper viene eseguito

1044</h4>

815 1045 

816<Note>1046Claude Code sceglie la directory di lavoro del comando `headersHelper` dalla configurazione che dichiara il server. Un `cd` che Claude esegue in Bash non lo sposta, e [`/cd`](/docs/it/permissions#move-the-session-to-another-directory) lo sposta solo per i server che vengono eseguiti dalla directory di lavoro primaria della sessione. Ogni riga di seguito fornisce la directory rispetto alla quale un percorso relativo nel tuo comando `headersHelper` si risolve.

817 `headersHelper` esegue comandi shell arbitrari. Quando definito a livello di progetto o locale, viene eseguito solo dopo che accetti la finestra di dialogo di fiducia dell'area di lavoro.1047 

818</Note>1048| Dove hai configurato il server | Directory di lavoro |

1049| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------- |

1050| Un [plugin](/docs/it/plugins-reference#mcp-servers) | La directory radice del plugin. Richiede Claude Code v2.1.195 o successiva |

1051| Un `.mcp.json` di progetto o un server di [ambito locale](#local-scope) | La directory del progetto in cui il server è dichiarato |

1052| Un file agent nel tuo progetto, un server dall'opzione `mcpServers` dell'SDK o dal metodo `setMcpServers()`, o [`--mcp-config`](/docs/it/cli-reference) | La [directory di lavoro primaria](/docs/it/permissions#working-directories) della sessione |

1053| [Ambito utente](#user-scope), [MCP gestito](/docs/it/managed-mcp), un [connettore claude.ai](#use-mcp-servers-from-claude-ai), o un file agent da fuori dal tuo progetto, incluso uno da una directory `--add-dir` | La tua directory di configurazione, `~/.claude` a meno che tu non abbia impostato [`CLAUDE_CONFIG_DIR`](/docs/it/env-vars) |

1054 

1055Prima della v2.1.238, Claude Code eseguiva anche gli helper dei server di ambito utente, gestiti e connettore claude.ai, e dei file agent da fuori dal tuo progetto, dalla directory da cui lo hai avviato.

1056 

1057<h4 id="which-variables-a-helper-can-read">

1058 Quali variabili un helper può leggere

1059</h4>

1060 

1061Un `headersHelper` che un repository o un plugin fornisce è un comando che non hai scritto, quindi Claude Code lo esegue senza le variabili di credenziale dal tuo ambiente, come `ANTHROPIC_API_KEY`. Dove hai configurato il server decide se questo si applica:

1062 

1063* **Rimosso**: un server in un `.mcp.json` di progetto o in un plugin, e un server inline in un file agent dal tuo progetto o da una directory `--add-dir`

1064* **Non rimosso**: un server di [ambito utente](#user-scope) o [ambito locale](#local-scope), in [MCP gestito](/docs/it/managed-mcp), da un [connettore claude.ai](#use-mcp-servers-from-claude-ai), o fornito dall'SDK o da [`--mcp-config`](/docs/it/cli-reference), e un server inline in un file agent da `~/.claude/agents/`, dalle impostazioni gestite, o passato con `--agents`

1065 

1066A parte le variabili `GIT_CONFIG_KEY_<n>` di Git, Claude Code rimuove ogni variabile dal tuo ambiente il cui nome sembra una credenziale, come un nome con `TOKEN`, `SECRET`, `PASSWORD`, `KEY`, o `AUTH` in esso in entrambi i casi di lettera, quindi sia `ANTHROPIC_API_KEY` che `MY_REGISTRY_TOKEN` vengono rimossi. Claude Code rimuove anche un elenco fisso di variabili di credenziale i cui nomi non seguono quel modello, come `ANTHROPIC_CUSTOM_HEADERS`.

1067 

1068Quando questo si applica al tuo helper, fai in modo che lo script legga la sua credenziale da un file o da un archivio di credenziali. Se l'`url` del server [espande una di queste variabili](#environment-variable-expansion-in-mcp-json), il valore `CLAUDE_CODE_MCP_SERVER_URL` che l'helper riceve ha quella parte sostituita con `REDACTED` anche.

1069 

1070<h4 id="trust-a-folder-before-its-headershelper-runs">

1071 Affida una cartella prima che il suo headersHelper venga eseguito

1072</h4>

1073 

1074Claude Code esegue un `headersHelper` come comando shell arbitrario. Per un server in un `.mcp.json` di progetto o di [ambito locale](#local-scope), lo esegue solo dopo che accetti la [finestra di dialogo di fiducia](/docs/it/permissions#project-allow-rules-and-workspace-trust) per la directory del progetto in cui il server è dichiarato. Prima della v2.1.238, una sessione `claude -p` o SDK eseguiva questi helper senza controllare la fiducia, e una sessione interattiva li eseguiva una volta che avevi affidato una cartella genitore.

1075 

1076* **Fiducia che non conta**: la fiducia di una cartella genitore, e la fiducia automatica che una sessione `claude -p` o SDK ottiene per gli [hook nei file di impostazioni](/docs/it/permissions#what-runs-before-you-trust-a-folder)

1077* **Fino a quando non affidi la cartella**: Claude Code connette il server con i suoi soli `headers` statici. In una sessione `claude -p` o SDK stampa anche una riga [`headersHelper not run`](/docs/it/errors#headershelper-not-run) per server su stderr, dicendoti come concedere la fiducia.

1078* **Fiducia senza una finestra di dialogo**: imposta `projects["<path>"].hasTrustDialogAccepted` su `true` in `~/.claude.json`. `<path>` è la cartella su cui [Project allow rules and workspace trust](/docs/it/permissions#project-allow-rules-and-workspace-trust) dice che Claude Code basa la fiducia.

1079 

1080Claude Code applica la stessa regola a un server dichiarato inline in un [file agent](/docs/it/sub-agents#scope-mcp-servers-to-a-subagent), controllando da dove proveniva quel file agent: il tuo progetto, per un file nella sua directory `.claude/agents/`, o una directory `--add-dir`. Fino a quando non [affidi quel progetto o quella directory stessa](/docs/it/permissions#what-runs-before-you-trust-a-folder), Claude Code non carica il server affatto, quindi il suo helper non viene mai eseguito nemmeno.

819 1081 

820<h2 id="add-mcp-servers-from-json-configuration">1082<h2 id="add-mcp-servers-from-json-configuration">

821 Aggiungi server MCP dalla configurazione JSON1083 Aggiungi server MCP dalla configurazione JSON

893</Tip>1155</Tip>

894 1156 

895<h2 id="use-mcp-servers-from-claude-ai">1157<h2 id="use-mcp-servers-from-claude-ai">

896 Utilizza server MCP da claude.ai1158 Utilizzare i server MCP da claude.ai

897</h2>1159</h2>

898 1160 

899Se hai effettuato l'accesso a Claude Code con un account [claude.ai](https://claude.ai), i server MCP che hai aggiunto in claude.ai, noti come [connectors](https://claude.com/docs/connectors), sono automaticamente disponibili in Claude Code:1161Se hai effettuato l'accesso a Claude Code con un account [claude.ai](https://claude.ai), i server MCP che hai aggiunto in claude.ai, noti come [connettori](https://claude.com/docs/connectors), sono automaticamente disponibili in Claude Code:

900 1162 

901<Steps>1163<Steps>

902 <Step title="Configura server MCP in claude.ai">1164 <Step title="Configurare i server MCP in claude.ai">

903 Aggiungi server su [claude.ai/customize/connectors](https://claude.ai/customize/connectors). Nei piani Team ed Enterprise, solo gli amministratori possono aggiungere server.1165 Aggiungi i server su [claude.ai/customize/connectors](https://claude.ai/customize/connectors). Nei piani Team ed Enterprise, solo gli amministratori possono aggiungere server.

904 </Step>1166 </Step>

905 1167 

906 <Step title="Autentica il server MCP">1168 <Step title="Autenticare il server MCP">

907 Completa eventuali passaggi di autenticazione richiesti in claude.ai.1169 Completa eventuali passaggi di autenticazione richiesti in claude.ai.

908 </Step>1170 </Step>

909 1171 

910 <Step title="Visualizza e gestisci i server in Claude Code">1172 <Step title="Visualizzare e gestire i server in Claude Code">