58 58
59Claude ti chiede informazioni sul tuo caso d'uso e scaffolda un server HTTP remoto o un server stdio locale.59Claude ti chiede informazioni sul tuo caso d'uso e scaffolda un server HTTP remoto o un server stdio locale.
60 60
61## Installare i server MCP61## Installazione dei server MCP
62 62
63I server MCP possono essere configurati in diversi modi a seconda delle tue esigenze:63I server MCP possono essere configurati in diversi modi a seconda delle tue esigenze:
64 64
65### Opzione 1: aggiungere un server HTTP remoto65### Opzione 1: aggiungere un server HTTP remoto
66 66
67I server HTTP sono l'opzione consigliata per connettersi a server MCP remoti. È il trasporto più ampiamente supportato per i servizi basati su cloud.67I server HTTP sono l'opzione consigliata per connettersi a server MCP remoti. Questo è il trasporto più ampiamente supportato per i servizi basati sul cloud.
68 68
69```bash theme={null}69```bash theme={null}
70# Basic syntax70# Basic syntax
78 --header "Authorization: Bearer your-token"78 --header "Authorization: Bearer your-token"
79```79```
80 80
81Quando configuri i server MCP tramite JSON in `.mcp.json`, `~/.claude.json` o `claude mcp add-json`, il campo `type` accetta `streamable-http` come alias di `http`. La specifica MCP usa il nome `streamable-http` per questo trasporto, quindi le configurazioni copiate dalla documentazione del server funzionano senza modifiche.81Quando configuri i server MCP tramite JSON in `.mcp.json`, `~/.claude.json` o `claude mcp add-json`, il campo `type` accetta `streamable-http` come alias di `http`. La specifica MCP usa il nome `streamable-http` per questo trasporto, quindi le configurazioni copiate dalla documentazione dei server funzionano senza modifiche.
82 82
83Una 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`.83Una voce JSON che ha un `url` ma nessun `type` è un errore di configurazione, perché Claude Code interpreta 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`.
84 84
85Solo un'applicazione host dell'SDK, come un'applicazione [Agent SDK](https://code.claude.com/docs/it/agent-sdk/mcp.md) o l'[app desktop](https://code.claude.com/docs/it/desktop.md), può registrare un server in-process `"type": "sdk"`. Claude Code salta una voce `"type": "sdk"` in `.mcp.json`, `~/.claude.json` o nelle impostazioni e segnala `Skipped — MCP server "<name>" declares type "sdk", which only an SDK host application can register`.85Solo un'applicazione host dell'SDK, come un'applicazione [Agent SDK](https://code.claude.com/docs/it/agent-sdk/mcp.md) o l'[app desktop](https://code.claude.com/docs/it/desktop.md), può registrare un server in-process `"type": "sdk"`. Claude Code salta una voce `"type": "sdk"` in `.mcp.json`, `~/.claude.json` o nelle impostazioni e segnala `Skipped — MCP server "<name>" declares type "sdk", which only an SDK host application can register`.
86 86
87> [!NOTE]87> [!NOTE]
88>88>
89> Nelle esecuzioni con `--output-format stream-json`, Claude Code segnala una voce `--mcp-config` saltata anche nel [campo `mcp_server_errors`](https://code.claude.com/docs/it/headless#stream-responses) dell'evento `system/init`, così gli script possono rilevare che il server non è mai stato caricato.89> Nelle esecuzioni con `--output-format stream-json`, Claude Code segnala anche una voce `--mcp-config` saltata nel [campo `mcp_server_errors`](https://code.claude.com/docs/it/headless#stream-responses) dell'evento `system/init`, così gli script possono rilevare che il server non è mai stato caricato.
90 90
91### Opzione 2: aggiungere un server SSE remoto91### Opzione 2: aggiungere un server SSE remoto
92 92
94>94>
95> Il trasporto SSE (Server-Sent Events) è deprecato. Usa invece i server HTTP, dove disponibili.95> Il trasporto SSE (Server-Sent Events) è deprecato. Usa invece i server HTTP, dove disponibili.
96 96
97Alcuni servizi espongono ancora solo un endpoint SSE. Aggiungili con lo stesso comando `claude mcp add --transport http <name> <url>` usato per [un server HTTP](#option-1-add-a-remote-http-server). Claude Code prova prima il trasporto HTTP e passa a SSE quando il server non lo accetta. Il passaggio automatico richiede Claude Code v2.1.265 o successiva.97Alcuni servizi espongono ancora solo un endpoint SSE. Aggiungili con lo stesso comando `claude mcp add --transport http <name> <url>` usato per [un server HTTP](#option-1-add-a-remote-http-server). Claude Code prova prima il trasporto HTTP e passa a SSE quando il server non lo accetta. Il passaggio automatico richiede Claude Code v2.1.265 o successivo.
98 98
99In una versione precedente, o per connetterti direttamente tramite SSE, passa invece `--transport sse`:99Su una versione precedente, o per connetterti direttamente tramite SSE, passa invece `--transport sse`:
100 100
101```bash theme={null}101```bash theme={null}
102# Basic syntax102# Basic syntax
114 114
115I server stdio vengono eseguiti come processi locali sulla tua macchina. Sono ideali per strumenti che richiedono accesso diretto al sistema o per script personalizzati.115I server stdio vengono eseguiti come processi locali sulla tua macchina. Sono ideali per strumenti che richiedono accesso diretto al sistema o per script personalizzati.
116 116
117Claude Code imposta `CLAUDE_PROJECT_DIR` nell'ambiente del server avviato sulla radice del progetto, così il tuo server può risolvere i percorsi relativi al progetto senza dipendere dalla directory di lavoro. È 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.117Claude Code imposta `CLAUDE_PROJECT_DIR` nell'ambiente del server avviato sulla radice del progetto, così il tuo server può risolvere i percorsi relativi al progetto senza dipendere dalla directory di lavoro. È la stessa directory che gli hook ricevono nella loro variabile `CLAUDE_PROJECT_DIR`. Leggila dall'interno del processo del tuo server, ad esempio con `process.env.CLAUDE_PROJECT_DIR` in Node o `os.environ["CLAUDE_PROJECT_DIR"]` in Python.
118 118
119`CLAUDE_PROJECT_DIR` è la radice stabile del progetto e non cambia quando aggiungi o rimuovi directory di lavoro a metà sessione. Un server che limita il proprio accesso al filesystem a un insieme di directory consentite dovrebbe invece 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](https://code.claude.com/docs/it/permissions.md#working-directories) che hai concesso con `--add-dir`, `/add-dir` o l'impostazione `additionalDirectories`. Claude Code invia `notifications/roots/list_changed` quando quell'insieme cambia.119`CLAUDE_PROJECT_DIR` è la radice stabile del progetto e non cambia quando aggiungi o rimuovi directory di lavoro durante la sessione. Un server che limita il proprio accesso al filesystem a un insieme di directory consentite dovrebbe invece 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](https://code.claude.com/docs/it/permissions.md#working-directories) che hai concesso con `--add-dir`, `/add-dir` o l'impostazione `additionalDirectories`. Claude Code invia `notifications/roots/list_changed` quando quell'insieme cambia.
120 120
121Questa variabile è impostata nell'ambiente del server, non nell'ambiente di Claude Code stesso, quindi fare riferimento a essa tramite espansione `${VAR}` nel `command` o negli `args` di una voce `.mcp.json` con ambito di progetto o di una voce di 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.121Questa variabile è impostata nell'ambiente del server, non nell'ambiente di Claude Code stesso, quindi farvi riferimento tramite l'espansione `${VAR}` nel `command` o negli `args` di una voce `.mcp.json` con ambito di progetto o di una voce di 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 necessitano del valore predefinito.
122 122
123```bash theme={null}123```bash theme={null}
124# Basic syntax124# Basic syntax
131 131
132> [!NOTE]132> [!NOTE]
133>133>
134> Per i server stdio, il `--` (doppio trattino) separa le opzioni proprie di Claude, come `--transport`, `--env` e `--scope`, dal comando e dagli argomenti che eseguono il server. Tutto ciò che segue `--` viene passato al server senza modifiche.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 segue `--` viene passato al server senza modifiche.
135>135>
136> Ad esempio:136> Ad esempio:
137>137>
138> * `claude mcp add --transport stdio myserver -- npx server` → esegue `npx server`138> * `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'ambiente139> * `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>140>
141> Senza `--`, Claude Code proverebbe ad analizzare i flag del server, come `--port` qui sopra, come se fossero opzioni proprie.141> Senza `--`, Claude Code cercherebbe di interpretare i flag del server, come `--port` qui sopra, come proprie opzioni.
142>142>
143> `--env` accetta più coppie `KEY=value`. Se il nome del server segue direttamente `--env`, la CLI legge il nome come un'altra coppia e lo rifiuta, quindi inserisci almeno un'altra opzione, come `--transport stdio`, tra `--env` e il nome del server.143> `--env` accetta più coppie `KEY=value`. Se il nome del server segue direttamente `--env`, la CLI legge il nome come un'altra coppia e lo rifiuta, quindi inserisci almeno un'altra opzione, come `--transport stdio`, tra `--env` e il nome del server.
144 144
145#### Come Claude Code arresta un server stdio145#### Come Claude Code arresta un server stdio
146 146
147Quando Claude Code disconnette un server stdio, ad esempio quando la tua sessione termina, invia un segnale al processo del server e attende brevemente che termini prima di forzarne l'arresto. Se il tuo server salva lo stato o rimuove file di lock all'arresto, gestisci il segnale per la tua piattaforma e completa le operazioni entro quel tempo:147Quando Claude Code disconnette un server stdio, ad esempio quando la tua sessione termina, invia un segnale al processo del server e attende brevemente che termini prima di forzarne l'arresto. Se il tuo server salva lo stato o rimuove file di lock durante l'arresto, gestisci il segnale per la tua piattaforma e completa l'operazione entro quel tempo:
148 148
149* **Su macOS e Linux**: Claude Code invia `SIGINT`, poi `SIGTERM` se il processo è ancora in esecuzione 100 millisecondi dopo, poi `SIGKILL` dopo ulteriori 400 millisecondi.149* **Su macOS e Linux**: Claude Code invia `SIGINT`, poi `SIGTERM` se il processo è ancora in esecuzione 100 millisecondi dopo, poi `SIGKILL` dopo altri 400 millisecondi.
150* **Su Windows**: Claude Code chiude lo stdin del server, poi termina l'albero dei processi del server se il processo è ancora in esecuzione 300 millisecondi dopo.150* **Su Windows**: Claude Code chiude lo stdin del server, poi termina l'albero dei processi del server se il processo è ancora in esecuzione 300 millisecondi dopo.
151 151
152Prima della v2.1.296, Claude Code su Windows terminava subito l'albero dei processi del server, senza prima chiudere lo stdin né attendere.152Prima della v2.1.296, Claude Code su Windows terminava subito l'albero dei processi del server, senza prima chiudere lo stdin né attendere.
153 153
154### Opzione 4: aggiungere un server WebSocket remoto154### Opzione 4: aggiungere un server WebSocket remoto
155 155
156I server WebSocket mantengono una connessione bidirezionale persistente, adatta ai server MCP remoti che inviano eventi a Claude senza che venga richiesto. Usa invece 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.156I server WebSocket mantengono una connessione bidirezionale persistente, adatta ai server MCP remoti che inviano eventi a Claude senza che vengano richiesti. Usa invece 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.
157 157
158Configura i server WebSocket in `.mcp.json` o con `claude mcp add-json`:158Configura i server WebSocket in `.mcp.json` o con `claude mcp add-json`:
159 159
164 164
165La voce `type: "ws"` accetta gli stessi campi `url`, `headers`, `headersHelper`, `timeout` e `alwaysLoad` di `http`. L'autenticazione avviene 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`.165La voce `type: "ws"` accetta gli stessi campi `url`, `headers`, `headersHelper`, `timeout` e `alwaysLoad` di `http`. L'autenticazione avviene 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`.
166 166
167### Aggiungere un server da istruzioni di configurazione scritte per un altro client167### Aggiungere un server dalle istruzioni di configurazione scritte per un altro client
168 168
169I 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 un URL, un comando di avvio o un blocco JSON:169I 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 un URL, un comando di avvio o un blocco JSON:
170 170
171* **Un URL** come `https://mcp.example.com/mcp`: il server è remoto.171* **Un URL** come `https://mcp.example.com/mcp`: il server è remoto.
172* **Un comando di avvio** come `npx -y @example/mcp-server`: il server viene eseguito sulla tua macchina.172* **Un comando di avvio** come `npx -y @example/mcp-server`: il server viene eseguito sulla tua macchina.
173* **Un blocco JSON `mcpServers`**: configurazione scritta per il file delle impostazioni di un altro client.173* **Un blocco JSON `mcpServers`**: configurazione scritta per il file di impostazioni di un altro client.
174 174
175Ciascuno è uno degli input accettati dalle quattro opzioni in [Installare i server MCP](#installing-mcp-servers). Trova qui sotto la forma che hai per trasformarla nel comando accettato da Claude Code. Ogni comando scrive nell'[ambito locale](#local-scope) a meno che tu non aggiunga `--scope project` o `--scope user`.175Ciascuno è uno degli input accettati dalle quattro opzioni in [Installazione dei server MCP](#installing-mcp-servers). Trova qui sotto la forma che hai per trasformarla nel comando che Claude Code accetta. Ogni comando scrive nell'[ambito locale](#local-scope) a meno che tu non aggiunga `--scope project` o `--scope user`.
176 176
177#### Aggiungere un server da un URL177#### Aggiungere un server da un URL
178 178
186 186
187#### Aggiungere un server da un comando `npx`, `uvx` o binario187#### Aggiungere un server da un comando `npx`, `uvx` o binario
188 188
189Un comando di avvio significa che il server viene eseguito come processo stdio locale. Inserisci l'intero comando dopo `--`, così Claude Code passa flag come `-y` al comando che avvia il server invece di leggerli come opzioni proprie. Passa le eventuali variabili d'ambiente richieste dalle istruzioni con `--env`, dopo il nome del server e prima di `--`:189Un comando di avvio significa che il server viene eseguito come processo stdio locale. Inserisci l'intero comando dopo `--`, così Claude Code passa i flag come `-y` al comando che avvia il server invece di interpretarli come proprie opzioni. Passa le variabili d'ambiente richieste dalle istruzioni con `--env`, dopo il nome del server e prima di `--`:
190 190
191```bash theme={null}191```bash theme={null}
192claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server192claude mcp add example --env API_KEY=your-key -- npx -y @example/mcp-server
193```193```
194 194
195L'[Opzione 3](#option-3-add-a-local-stdio-server) descrive in dettaglio il separatore `--`.195L'[Opzione 3](#option-3-add-a-local-stdio-server) tratta in modo completo il separatore `--`.
196 196
197#### Aggiungere un server da un blocco JSON `mcpServers`197#### Aggiungere un server da un blocco JSON `mcpServers`
198 198
199Un blocco `mcpServers` scritto per un altro client MCP, come Claude Desktop, usa la chiave contenitore e la forma delle voci che Claude Code legge. Passa a `claude mcp add-json` l'oggetto all'interno di `mcpServers`, non il contenitore. Due tipi di voci richiedono prima una correzione:199Un blocco `mcpServers` scritto per un altro client MCP, come Claude Desktop, usa la chiave contenitore e la forma delle voci che Claude Code legge. Passa a `claude mcp add-json` l'oggetto all'interno di `mcpServers`, non il contenitore. Due tipi di voci richiedono prima una correzione:
200 200
201* **Un `url` senza `type`**: aggiungi `"type": "http"`, `"type": "sse"` o `"type": "ws"` in base all'endpoint. Claude Code legge una voce senza `type` come un server stdio, quindi una voce `url` senza `type` fallisce.201* **Un `url` senza `type`**: aggiungi `"type": "http"`, `"type": "sse"` o `"type": "ws"` in base all'endpoint. Claude Code interpreta una voce senza `type` come un server stdio, quindi una voce `url` senza `type` non funziona.
202* **Una chiave con caratteri diversi da lettere, numeri, trattini e underscore**: scegli un nome di server che usi solo quei caratteri. Altrimenti la chiave è il nome del server.202* **Una chiave con caratteri diversi da lettere, numeri, trattini e underscore**: scegli un nome di server che usi solo quei caratteri. Altrimenti la chiave è il nome del server.
203 203
204Ad esempio, questo blocco:204Ad esempio, questo blocco:
220claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'220claude mcp add-json example '{"command":"npx","args":["-y","@example/mcp-server"]}'
221```221```
222 222
223[Aggiungere server MCP da una configurazione JSON](#add-mcp-servers-from-json-configuration) descrive l'escape nella shell e il flag `--scope` per `add-json`. Per condividere invece il server con il tuo team, aggiungi `--scope project`, oppure aggiungi la voce sotto `mcpServers` in `.mcp.json` nella radice del progetto ed esegui il commit. [Ambito di progetto](#project-scope) descrive come Claude Code carica e approva quel file.223[Aggiungere server MCP da una configurazione JSON](#add-mcp-servers-from-json-configuration) tratta l'escape nella shell e il flag `--scope` per `add-json`. Per condividere invece il server con il tuo team, aggiungi `--scope project`, oppure aggiungi la voce sotto `mcpServers` in `.mcp.json` nella radice del tuo progetto ed esegui il commit. [Ambito di progetto](#project-scope) spiega come Claude Code carica e approva quel file.
224 224
225Ogni comando `claude mcp add` e `claude mcp add-json` stampa una riga `Added ...` in caso di successo. Per verificare che Claude Code si sia connesso, esegui `claude mcp get <name>`; [Stato del server](#server-status) descrive gli stati mostrati e il passaggio di approvazione per i server `.mcp.json`.225Ogni comando `claude mcp add` e `claude mcp add-json` stampa una riga `Added ...` in caso di successo. Per verificare che Claude Code si sia connesso, esegui `claude mcp get <name>`; [Stato del server](#server-status) descrive gli stati che mostra e il passaggio di approvazione per i server di `.mcp.json`.
226 226
227### Gestire i tuoi server227### Gestire i tuoi server
228 228
246 246
247#### Stato del server247#### Stato del server
248 248
249`claude mcp add` conferma un'aggiunta riuscita stampando una riga `Added ...`, che significa che la configurazione è stata scritta. Se invece il comando stampa un messaggio `was not saved`, consulta [MCP server was not saved or removed](https://code.claude.com/docs/it/errors.md#mcp-server-was-not-saved-or-removed); per un messaggio `may not have been saved`, consulta [MCP server may not have been saved or removed](https://code.claude.com/docs/it/errors.md#mcp-server-may-not-have-been-saved-or-removed).249`claude mcp add` conferma un'aggiunta riuscita stampando una riga `Added ...`, il che significa che la configurazione è stata scritta. Se invece il comando stampa un messaggio `was not saved`, consulta [MCP server was not saved or removed](https://code.claude.com/docs/it/errors.md#mcp-server-was-not-saved-or-removed); per un messaggio `may not have been saved`, consulta [MCP server may not have been saved or removed](https://code.claude.com/docs/it/errors.md#mcp-server-may-not-have-been-saved-or-removed).
250 250
251`claude mcp list` mostra uno stato di salute accanto a ogni server elencato, come `✔ Connected`, `! Needs authentication` o `✘ Failed to connect`. Uno stato di errore significa che Claude Code non è riuscito a connettersi a quel server, non che il comando list sia fallito.251`claude mcp list` mostra uno stato di salute accanto a ogni server elencato, come `✔ Connected`, `! Needs authentication` o `✘ Failed to connect`. Uno stato di errore significa che Claude Code non è riuscito a connettersi a quel server, non che il comando list abbia avuto esito negativo.
252 252
253Gli stati in questo elenco riportano una decisione di configurazione anziché un tentativo di connessione, quindi Claude Code li stampa senza connettersi al server:253Gli stati in questo elenco riportano una decisione di configurazione anziché un tentativo di connessione, quindi Claude Code li stampa senza connettersi al server:
254 254
255* ``⏸ 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` sia in `claude mcp get <name>`. Esegui `claude` in modo interattivo per esaminarlo e approvarlo.255* ``⏸ 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` sia in `claude mcp get <name>`. Esegui `claude` in modo interattivo per esaminarlo e approvarlo.
256* `✘ Rejected (see disabledMcpjsonServers in settings)`: un server `.mcp.json` rifiutato da una voce [`disabledMcpjsonServers`](https://code.claude.com/docs/it/settings-reference#disabledmcpjsonservers). Claude Code lo mostra solo in `claude mcp get <name>`.256* `✘ Rejected (see disabledMcpjsonServers in settings)`: un server di `.mcp.json` rifiutato da una voce [`disabledMcpjsonServers`](https://code.claude.com/docs/it/settings-reference#disabledmcpjsonservers). Claude Code lo mostra solo in `claude mcp get <name>`.
257* `⊘ Disabled for this project (re-enable via /mcp)`: un server indicato nell'elenco [`disabledMcpServers`](#disable-a-server-without-removing-it) del progetto. Claude Code lo mostra sia in `claude mcp list` sia in `claude mcp get <name>`. Riattiva il server dal pannello `/mcp`.257* `⊘ Disabled for this project (re-enable via /mcp)`: un server indicato nell'elenco [`disabledMcpServers`](#disable-a-server-without-removing-it) del progetto. Claude Code lo mostra sia in `claude mcp list` sia in `claude mcp get <name>`. Riattiva il server dal pannello `/mcp`.
258* `✘ Blocked by enterprise managed policy`: un server rifiutato da una delle policy della tua organizzazione. Claude Code lo mostra sia in `claude mcp list` sia in `claude mcp get <name>`. Un server bloccato da un'allowlist, una denylist o un'altra restrizione nella [configurazione MCP gestita](https://code.claude.com/docs/it/managed-mcp.md#how-restrictions-appear-to-users) viene nascosto da entrambi i comandi anziché essere mostrato con questo stato. Chiedi al tuo amministratore quale policy blocca il server.258* `✘ Blocked by enterprise managed policy`: un server rifiutato da una delle policy della tua organizzazione. Claude Code lo mostra sia in `claude mcp list` sia in `claude mcp get <name>`. Un server bloccato da un'allowlist, una denylist o un'altra restrizione nella [configurazione MCP gestita](https://code.claude.com/docs/it/managed-mcp.md#how-restrictions-appear-to-users) è nascosto in entrambi i comandi anziché essere mostrato con questo stato. Chiedi al tuo amministratore quale policy blocca il server.
259 259
260#### Approvazioni dei server di progetto e attendibilità del workspace260#### Approvazioni dei server di progetto e attendibilità del workspace
261 261
262`claude mcp list` e `claude mcp get` leggono le approvazioni di `.mcp.json` solo dai file delle impostazioni che non sono inclusi nel repository finché non consideri attendibile il workspace eseguendo `claude` al suo interno e accettando la finestra di dialogo sull'attendibilità del workspace. Un repository clonato non può approvare i propri server: [`enableAllProjectMcpServers`](https://code.claude.com/docs/it/settings-reference#enableallprojectmcpservers) o [`enabledMcpjsonServers`](https://code.claude.com/docs/it/settings-reference#enabledmcpjsonservers) inclusi nel commit del file `.claude/settings.json` del progetto vengono ignorati in una cartella non attendibile, e il server resta in `⏸ Pending approval` invece di essere connesso e sottoposto al controllo di salute.262`claude mcp list` e `claude mcp get` leggono le approvazioni di `.mcp.json` solo dai file di impostazioni non inclusi nel repository finché non consideri attendibile il workspace eseguendovi `claude` e accettando la finestra di dialogo di attendibilità del workspace. Un repository clonato non può approvare i propri server: [`enableAllProjectMcpServers`](https://code.claude.com/docs/it/settings-reference#enableallprojectmcpservers) o [`enabledMcpjsonServers`](https://code.claude.com/docs/it/settings-reference#enabledmcpjsonservers) inclusi nel commit nel file `.claude/settings.json` del progetto vengono ignorati in una cartella non attendibile, e il server resta in `⏸ Pending approval` invece di essere connesso e sottoposto al controllo di salute.
263 263
264Le approvazioni da queste fonti si applicano comunque in una cartella non attendibile:264Le approvazioni provenienti da queste fonti si applicano comunque in una cartella non attendibile:
265 265
266* il tuo `~/.claude/settings.json` utente266* il tuo `~/.claude/settings.json` utente
267* le impostazioni gestite267* le impostazioni gestite
268* le impostazioni passate con `--settings`268* le impostazioni passate con `--settings`
269 269
270Claude 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](https://code.claude.com/docs/it/permissions.md#project-allow-rules-and-workspace-trust). In una cartella che non hai mai considerato attendibile, Claude Code attende la finestra di dialogo sull'attendibilità prima di applicare le approvazioni del file, a meno che la cartella non sia la tua home di configurazione: la tua directory home, o una directory il cui `.claude` hai impostato come [`CLAUDE_CONFIG_DIR`](https://code.claude.com/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 considerato attendibile.270Claude Code applica anche le approvazioni da un file `.claude/settings.local.json` non tracciato, ma esegue git per verificare se il file è tracciato, e esegue quel controllo solo in una [cartella attendibile](https://code.claude.com/docs/it/permissions.md#project-allow-rules-and-workspace-trust). In una cartella che non hai mai considerato attendibile, Claude Code attende la finestra di dialogo di attendibilità prima di applicare le approvazioni del file, a meno che la cartella non sia la tua home di configurazione: la tua directory home, o una directory il cui `.claude` hai impostato come [`CLAUDE_CONFIG_DIR`](https://code.claude.com/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 considerato attendibile.
271 271
272Una voce `disabledMcpjsonServers` in qualsiasi file delle impostazioni rifiuta comunque il server.272Una voce `disabledMcpjsonServers` in qualsiasi file di impostazioni rifiuta comunque il server.
273 273
274#### Dettagli sullo stato del server274#### Dettagli dello stato del server
275 275
276In `/mcp`, incluso il menu di un server al suo interno, e nel gestore [`/plugin`](https://code.claude.com/docs/it/plugins/install), un server HTTP o SSE remoto che hai già usato 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 rilevamento, 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 rilevamento e il relativo stato `cached` richiedono Claude Code v2.1.221 o successiva.276In `/mcp`, incluso il menu di un server al suo interno, e nel gestore [`/plugin`](https://code.claude.com/docs/it/plugins/install), un server HTTP o SSE remoto che hai già usato 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 discovery, salvata in una sessione precedente, invece di connettersi all'avvio, e Claude Code connette il server la prima volta che Claude chiama uno dei suoi strumenti. Gli strumenti sono disponibili fin dal tuo primo messaggio, quindi non devi fare nulla. La cache di discovery e il suo stato `cached` richiedono Claude Code v2.1.221 o successivo.
277 277
278La cache di rilevamento è disattivata per impostazione predefinita, a meno che un rilascio graduale non l'abbia attivata per il tuo account. Imposta [`MCP_DISCOVERY_CACHE=1`](https://code.claude.com/docs/it/env-vars) per attivarla, oppure `0` per mantenerla disattivata anche quando il rilascio l'ha attivata. Prima della v2.1.238, la cache era attiva per impostazione predefinita.278La cache di discovery è disattivata per impostazione predefinita, a meno che un rilascio graduale non l'abbia abilitata per il tuo account. Imposta [`MCP_DISCOVERY_CACHE=1`](https://code.claude.com/docs/it/env-vars) per attivarla, oppure `0` per mantenerla disattivata anche quando il rilascio l'ha abilitata. Prima della v2.1.238, la cache era attiva per impostazione predefinita.
279 279
280Quando selezioni **Disable** o **Clear authentication** dal menu di un server in `/mcp`, Claude Code scarta anche la voce della cache di quel server. Anche **Reconnect** la scarta su un server connesso o in errore; su un server `cached`, **Reconnect** connette subito il server e mantiene la voce. La volta successiva in cui Claude Code si connette al server dopo aver scartato la voce, recupera l'elenco degli strumenti dal server invece che dalla cache.280Quando selezioni **Disable** o **Clear authentication** dal menu di un server in `/mcp`, Claude Code scarta anche la voce della cache di quel server. Anche **Reconnect** la scarta su un server connesso o in errore; su un server `cached`, **Reconnect** connette subito il server e mantiene la voce. La volta successiva in cui Claude Code si connette al server dopo aver scartato la voce, recupera l'elenco degli strumenti dal server invece che dalla cache.
281 281
282##### Errori di connessione e server non configurati282##### Errori di connessione e server non configurati
283 283
284Quando lo stato di un server è `✘ Failed to connect`, `claude mcp list` aggiunge il dettaglio dell'errore a quella riga di stato, e `claude mcp get <name>` lo mostra in una riga `Issue:`. Il dettaglio è lo stato HTTP o il codice di errore, più l'eventuale testo di errore restituito dal server. La vista di dettaglio del server in `/mcp` include lo stesso testo riportato dal server nella sua riga `Issue:`.284Quando lo stato di un server è `✘ Failed to connect`, `claude mcp list` aggiunge il dettaglio dell'errore a quella riga di stato, e `claude mcp get <name>` lo mostra su una riga `Issue:`. Il dettaglio è lo stato HTTP o il codice di errore, più l'eventuale testo di errore restituito dal server. La vista di dettaglio del server in `/mcp` include lo stesso testo riportato dal server nella sua riga `Issue:`.
285 285
286Claude Code oscura da questo dettaglio il testo simile a credenziali e non include mai l'URL del server espanso, che può contenere segreti. Claude Code non aggiunge alcun dettaglio a uno stato `✘ Connection error`, perché il testo dell'eccezione che vi stamperebbe può incorporare quell'URL.286Claude Code oscura da questo dettaglio il testo simile a credenziali e non include mai l'URL espanso del server, che può contenere segreti. Claude Code non aggiunge alcun dettaglio a uno stato `✘ Connection error`, perché il testo dell'eccezione che stamperebbe lì può incorporare quell'URL.
287 287
288Quando completi l'autenticazione da `/mcp` e la connessione fallisce ancora con uno stato HTTP o un codice di errore del trasporto, Claude Code aggiunge quel codice e l'origine dell'URL del server al messaggio che stampa dopo il tentativo. L'origine è lo schema e l'host, più la porta quando l'URL ne specifica una, come `https://mcp.example.com`.288Quando completi l'autenticazione da `/mcp` e la connessione fallisce comunque con uno stato HTTP o un codice di errore del trasporto, Claude Code aggiunge quel codice e l'origine dell'URL del server al messaggio che stampa dopo il tentativo. L'origine è lo schema e l'host, più la porta quando l'URL ne specifica una, come `https://mcp.example.com`.
289 289
290* Il percorso e la query non compaiono mai in quel messaggio.290* Il percorso e la query non compaiono mai in quel messaggio.
291* Per un server nell'[ambito](#mcp-installation-scopes) locale, di progetto o utente o nella configurazione MCP gestita, l'origine mostra l'host come scritto in quella configurazione, quindi un riferimento `${VAR}` nell'host non viene espanso nel messaggio.291* Per un server nell'[ambito](#mcp-installation-scopes) locale, di progetto o utente, o nella configurazione MCP gestita, l'origine mostra l'host come scritto in quella configurazione, quindi un riferimento `${VAR}` nell'host non viene espanso nel messaggio.
292* Per un errore senza stato o codice di errore, Claude Code mostra il testo dell'errore senza l'origine.292* Per un errore senza stato o codice di errore, Claude Code mostra il testo dell'errore senza l'origine.
293 293
294Un server remoto la cui configurazione ha un `url` vuoto viene mostrato come `not configured` in `/mcp`, in `claude mcp list` e nel gestore [`/plugin`](https://code.claude.com/docs/it/plugins/install), e Claude Code non tenta di connettersi a esso. Un plugin può includere una voce segnaposto di questo tipo per un connettore che configuri in seguito, così Claude Code non la segnala come un errore o un problema di configurazione. La vista di dettaglio del server in `/mcp` riporta `No URL configured for this server`; imposta l'`url` della voce per connetterlo.294Un server remoto la cui configurazione ha un `url` vuoto appare come `not configured` in `/mcp`, in `claude mcp list` e nel gestore [`/plugin`](https://code.claude.com/docs/it/plugins/install), e Claude Code non tenta di connettersi. Un plugin può includere una voce segnaposto di questo tipo per un connettore che configuri in seguito, così Claude Code non la segnala come errore o problema di configurazione. La vista di dettaglio del server in `/mcp` riporta `No URL configured for this server`; imposta l'`url` della voce per connetterlo.
295 295
296#### Avvisi di configurazione296#### Avvisi di configurazione
297 297
298Claude Code avvisa dei problemi di configurazione riportati di seguito. Ogni voce indica cosa controlla Claude Code e come eliminare l'avviso:298Claude Code avvisa dei problemi di configurazione elencati di seguito. Ogni voce indica cosa controlla Claude Code e come eliminare l'avviso:
299 299
300* **Spazi nascosti**: Claude Code avvisa quando un valore di configurazione MCP contiene spazi iniziali o finali nascosti, che spesso derivano dall'incollare un token con un a capo finale. Claude Code controlla `command`, `url`, ogni voce di `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`, indicando i campi interessati senza mostrarne i valori, ad esempio `Leading or trailing whitespace in: headers.Authorization`. Claude Code non rimuove gli spazi e usa i valori esattamente come scritti, quindi modifica la configurazione per rimuoverli.300* **Spazi nascosti**: Claude Code avvisa quando un valore della configurazione MCP contiene spazi nascosti iniziali o finali, che spesso derivano dall'incollare un token con un a capo finale. Claude Code controlla `command`, `url`, ogni voce di `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`, indicando i campi interessati senza riportarne i valori, ad esempio `Leading or trailing whitespace in: headers.Authorization`. Claude Code non rimuove gli spazi e usa i valori esattamente come scritti, quindi modifica la configurazione per rimuoverli.
301* **Stesso nome in più ambiti**: se definisci lo stesso nome di server in più di un [ambito](#mcp-installation-scopes) con endpoint diversi, Claude Code avvisa del conflitto nell'output di `claude mcp list` e in `/mcp`. Claude Code memorizza gli accessi OAuth per endpoint, quindi quando ti autentichi con la definizione che viene caricata in un progetto, devi comunque accedere separatamente in un progetto in cui viene caricata una definizione diversa. Mantieni l'endpoint che desideri e rimuovi gli altri con `claude mcp remove <name> --scope <scope>`. Nell'avviso, Claude Code riporta l'endpoint di ciascun 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.301* **Stesso nome in più ambiti**: se definisci lo stesso nome di server in più [ambiti](#mcp-installation-scopes) con endpoint diversi, Claude Code avvisa 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 viene caricata in un progetto, devi comunque accedere separatamente in un progetto in cui viene caricata una definizione diversa. Mantieni l'endpoint che desideri e rimuovi gli altri con `claude mcp remove <name> --scope <scope>`. Nell'avviso, Claude Code riporta 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.
302* **Nomi riservati**: Claude Code riserva i nomi dei suoi server integrati, tra cui `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 caricamento e mostra un avviso che ti chiede di rinominarlo. `claude mcp add` rifiuta un nome riservato con un errore. `Claude Preview` e `Claude Browser` indicano entrambi il server integrato usato dal [riquadro di anteprima dell'app desktop di Claude Code](https://code.claude.com/docs/it/desktop.md#preview-your-app).302* **Nomi riservati**: Claude Code riserva i nomi dei suoi server integrati, tra cui `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 caricamento e mostra un avviso che ti chiede di rinominarlo. `claude mcp add` rifiuta un nome riservato con un errore. `Claude Preview` e `Claude Browser` indicano entrambi il server integrato usato dal [riquadro di anteprima dell'app desktop di Claude Code](https://code.claude.com/docs/it/desktop.md#preview-your-app).
303* **Variabile d'ambiente mancante**: se un [riferimento `${VAR}`](#environment-variable-expansion-in-mcp-json) nella configurazione di un server indica una variabile non impostata e priva di `:-default`, Claude Code avvisa nell'output di `claude mcp list` e in `/mcp`, indicando la variabile, e carica comunque il server con il testo `${VAR}` non espanso. Imposta la variabile o aggiungi un fallback `${VAR:-default}`. Nell'`url` e negli `headers` di un server remoto, alcune variabili di credenziali [vengono invece lette come vuote](#credential-variables-that-read-as-empty), senza avviso.303* **Variabile d'ambiente mancante**: se un [riferimento `${VAR}`](#environment-variable-expansion-in-mcp-json) nella configurazione di un server indica una variabile non impostata e senza `:-default`, Claude Code avvisa nell'output di `claude mcp list` e in `/mcp`, indicando la variabile, e carica comunque il server con il testo `${VAR}` non espanso. Imposta la variabile o aggiungi un fallback `${VAR:-default}`. Nell'`url` e negli `headers` di un server remoto, alcune variabili di credenziali [vengono invece lette come vuote](#credential-variables-that-read-as-empty), senza alcun avviso.
304 304
305#### Disponibilità degli strumenti305#### Disponibilità degli strumenti
306 306
316 316
317##### Strumenti di un server ancora in fase di connessione317##### Strumenti di un server ancora in fase di connessione
318 318
319Se la tua richiesta necessita di strumenti di un server che si sta ancora connettendo in background, Claude attende quel server prima di continuare. Il modo in cui avviene l'attesa dipende dalla tua configurazione:319Se la tua richiesta necessita di strumenti da un server che si sta ancora connettendo in background, Claude attende quel server prima di continuare. Il modo in cui avviene l'attesa dipende dalla tua configurazione:
320 320
321* **Con la [ricerca degli strumenti](#scale-with-mcp-tool-search), il comportamento predefinito**: l'attesa avviene all'interno della chiamata `ToolSearch`.321* **Con la [ricerca degli strumenti](#scale-with-mcp-tool-search), l'impostazione predefinita**: l'attesa avviene all'interno della chiamata `ToolSearch`.
322* **Senza ricerca degli strumenti**: Claude usa invece lo strumento `WaitForMcpServers`. Le configurazioni senza ricerca degli strumenti includono `ENABLE_TOOL_SEARCH=false` e un modello precedente a Claude Opus 4.5, Claude Sonnet 4.5 e Claude Haiku 4.5 su Agent Platform di Google Cloud. Per un gateway `ANTHROPIC_BASE_URL`, consulta [Ricerca degli strumenti tramite un gateway LLM](#tool-search-through-a-gateway).322* **Senza ricerca degli strumenti**: Claude usa invece lo strumento `WaitForMcpServers`. Le configurazioni senza ricerca degli strumenti includono `ENABLE_TOOL_SEARCH=false` e un modello precedente a Claude Opus 4.5, Claude Sonnet 4.5 e Claude Haiku 4.5 su Agent Platform di Google Cloud. Per un gateway `ANTHROPIC_BASE_URL`, consulta [Ricerca degli strumenti tramite un gateway LLM](#tool-search-through-a-gateway).
323* **Su un [deploy di Microsoft Foundry ospitato su Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)**: Claude parte dal percorso della ricerca degli strumenti anziché con `WaitForMcpServers`, poiché Claude Code scopre il rifiuto lato server del deploy solo dall'API. Dopo che Claude Code ha spostato quel deploy al [caricamento anticipato](#scale-with-mcp-tool-search), gli strumenti di un server che completa la connessione diventano disponibili alla successiva richiesta di Claude.323* **Su un [deploy Microsoft Foundry ospitato su Azure](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options)**: Claude parte sul percorso della ricerca degli strumenti anziché con `WaitForMcpServers`, poiché Claude Code scopre il rifiuto lato server del deploy solo dall'API. Dopo che Claude Code passa quel deploy al [caricamento anticipato](#scale-with-mcp-tool-search), gli strumenti di un server che completa la connessione diventano disponibili alla richiesta successiva di Claude.
324 324
325Con la ricerca degli strumenti attiva, quando un server completa la connessione mentre Claude sta lavorando, Claude Code elenca i nomi degli strumenti del server a Claude nella sua richiesta successiva all'interno dello stesso turno. Claude può quindi cercare e chiamare quegli strumenti senza attendere il tuo messaggio successivo.325Con la ricerca degli strumenti abilitata, quando un server completa la connessione mentre Claude sta lavorando, Claude Code elenca i nomi degli strumenti del server a Claude nella sua richiesta successiva dello stesso turno. Claude può quindi cercare e chiamare quegli strumenti senza attendere il tuo messaggio successivo.
326 326
327Dopo aver ripreso una sessione, Claude può chiamare uno strumento della conversazione salvata mentre il server MCP dello strumento si sta ancora connettendo. Mentre il server è al suo primo tentativo di connessione, Claude Code trattiene la chiamata per un massimo di 10 secondi e la esegue non appena lo strumento è disponibile. Se il server non si connette in tempo, o sta già [riprovando dopo un tentativo fallito](#automatic-reconnection), la chiamata fallisce con l'[errore dello strumento](https://code.claude.com/docs/it/errors.md#no-such-tool-available) `No such tool available`.327Dopo aver ripreso una sessione, Claude può chiamare uno strumento dalla conversazione salvata mentre il server MCP dello strumento si sta ancora connettendo. Mentre il server è al primo tentativo di connessione, Claude Code trattiene la chiamata per un massimo di 10 secondi e la esegue non appena lo strumento è disponibile. Se il server non si connette in tempo, o sta già [riprovando dopo un tentativo fallito](#automatic-reconnection), la chiamata fallisce con l'[errore dello strumento](https://code.claude.com/docs/it/errors.md#no-such-tool-available) `No such tool available`.
328 328
329### Disattivare un server senza rimuoverlo329### Disabilitare un server senza rimuoverlo
330 330
331Disattiva un server nel pannello `/mcp` per impedire a Claude Code di connettersi a esso senza perderne la configurazione. Claude Code continua a elencare il server in `/mcp`, contrassegnato come disattivato.331Disattiva un server nel pannello `/mcp` per impedire a Claude Code di connettersi senza perderne la configurazione. Claude Code continua a elencare il server in `/mcp`, contrassegnato come disabilitato.
332 332
333Quando attivi o disattivi un server, Claude Code registra la tua scelta per progetto in `~/.claude.json`, in uno di due elenchi che coprono insiemi di server disgiunti:333Quando attivi o 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:
334 334
335* `disabledMcpServers`: un elenco di esclusione per i server configurati dall'utente, i server dei plugin, i server che la tua organizzazione [fornisce tramite le impostazioni gestite](https://code.claude.com/docs/it/managed-mcp.md#provide-servers-through-managed-settings), i connettori claude.ai che Claude Code [recupera autonomamente](#how-connectors-reach-claude-code) e i server integrati attivi per impostazione predefinita. Claude Code non si connette a un server che elenchi qui. Quando disattivi un connettore claude.ai con l'interruttore per progetto di `/mcp` descritto in [Disattivare i connettori claude.ai](#disable-claude-ai-connectors), Claude Code lo scrive in questo elenco con il suo nome visualizzato, ad esempio `claude.ai Slack`.335* `disabledMcpServers`: un elenco di esclusione per i server configurati dall'utente, i server dei plugin, i server che la tua organizzazione [fornisce tramite impostazioni gestite](https://code.claude.com/docs/it/managed-mcp.md#provide-servers-through-managed-settings), i connettori claude.ai che Claude Code [recupera autonomamente](#how-connectors-reach-claude-code) e i server integrati attivi per impostazione predefinita. Claude Code non si connette a un server che elenchi qui. Quando disabiliti un connettore claude.ai con l'interruttore `/mcp` per progetto descritto in [Disabilitare i connettori claude.ai](#disable-claude-ai-connectors), Claude Code lo scrive in questo elenco con il suo nome visualizzato, ad esempio `claude.ai Slack`.
336* `enabledMcpServers`: un elenco di inclusione per i server integrati disattivati per impostazione predefinita, come `computer-use`. Claude Code si connette a un server disattivato per impostazione predefinita solo quando lo elenchi qui.336* `enabledMcpServers`: un elenco di inclusione per i server integrati disattivati per impostazione predefinita, come `computer-use`. Claude Code si connette a un server disattivato per impostazione predefinita solo quando lo elenchi qui.
337 337
338Claude Code consulta esattamente uno dei due elenchi per ciascun server, quindi nessuno dei due elenchi sovrascrive l'altro. Se aggiungi un server normale a `enabledMcpServers`, o un server integrato disattivato per impostazione predefinita a `disabledMcpServers`, Claude Code ignora la voce.338Claude Code consulta esattamente uno dei due elenchi per ogni server, quindi nessuno dei due sovrascrive l'altro. Se aggiungi un server normale a `enabledMcpServers`, o un server integrato disattivato per impostazione predefinita a `disabledMcpServers`, Claude Code ignora la voce.
339 339
340`disabledMcpServers` e `enabledMcpServers` non hanno relazione con [`enabledMcpjsonServers`](https://code.claude.com/docs/it/settings-reference#enabledmcpjsonservers) e [`disabledMcpjsonServers`](https://code.claude.com/docs/it/settings-reference#disabledmcpjsonservers), che controllano l'approvazione dei server definiti nel file `.mcp.json` di un progetto.340`disabledMcpServers` e `enabledMcpServers` non hanno relazione con [`enabledMcpjsonServers`](https://code.claude.com/docs/it/settings-reference#enabledmcpjsonservers) e [`disabledMcpjsonServers`](https://code.claude.com/docs/it/settings-reference#disabledmcpjsonservers), che controllano l'approvazione dei server definiti nel file `.mcp.json` di un progetto.
341 341
342### Runtime del client MCP342### Runtime dei client MCP
343 343
344Claude Code si connette ai server MCP tramite uno di due runtime del client. Il runtime v1 è basato 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 indica il runtime v2.344Claude Code si connette ai server MCP tramite uno di due runtime client. Il runtime v1 è basato 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 indica il runtime v2.
345 345
346Claude Code sceglie un runtime ogni volta che lo avvii e lo mantiene finché non esci. Nelle sessioni in cui [recupera i feature flag](https://code.claude.com/docs/it/env-vars.md#features-that-need-feature-flag-fetching), usa il runtime v2 su Claude Code v2.1.232 o successiva.346Claude Code sceglie un runtime ogni volta che lo avvii e lo mantiene fino all'uscita. Nelle sessioni in cui [recupera i feature flag](https://code.claude.com/docs/it/env-vars.md#features-that-need-feature-flag-fetching), usa il runtime v2 su Claude Code v2.1.232 o successivo.
347 347
348Nelle sessioni in cui non recupera i feature flag, Claude Code usa il runtime v2 per impostazione predefinita su Claude Code v2.1.274 o successiva:348Nelle sessioni in cui non recupera i feature flag, Claude Code usa il runtime v2 per impostazione predefinita su Claude Code v2.1.274 o successivo:
349 349
350* Sessioni su Amazon Bedrock, Claude Platform on AWS, Agent Platform di Google Cloud o Microsoft Foundry, a meno che una piattaforma host che incorpora Claude Code non imposti [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/it/env-vars)350* Sessioni su Amazon Bedrock, Claude Platform on AWS, Agent Platform di Google Cloud o Microsoft Foundry, a meno che una piattaforma host che incorpora Claude Code non imposti [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](https://code.claude.com/docs/it/env-vars)
351* Sessioni con accesso tramite un [gateway delle app Claude](https://code.claude.com/docs/it/claude-apps-gateway)351* Sessioni con accesso tramite un [gateway delle app Claude](https://code.claude.com/docs/it/claude-apps-gateway)
352* Sessioni in cui disattivi la telemetria o il recupero dei feature flag, ad esempio con `DISABLE_TELEMETRY`352* Sessioni in cui disattivi la telemetria o il recupero dei feature flag, ad esempio con `DISABLE_TELEMETRY`
353 353
354Su v2, Claude Code inoltre:354Con v2, Claude Code inoltre:
355 355
356* Chiede ai server HTTP, stdio e connettori claude.ai se supportano la revisione più recente, e la usa con quelli che la supportano. Sono inclusi i connettori delle sessioni cloud e delle sessioni [Remote Control](https://code.claude.com/docs/it/remote-control.md). Claude Code si connette a tutti gli altri server come fa v1.356* Chiede ai server HTTP, stdio e ai connettori claude.ai se supportano la revisione più recente e la usa con quelli che la supportano. Ciò include i connettori delle sessioni cloud e di [Remote Control](https://code.claude.com/docs/it/remote-control.md). Claude Code si connette a tutti gli altri server come fa v1.
357* Riceve le notifiche `list_changed` dai server sulla revisione più recente tramite uno [stream che mantiene aperto](#notification-streams-on-the-v2-runtime).357* Riceve le notifiche `list_changed` dai server sulla revisione più recente tramite uno [stream che mantiene aperto](#notification-streams-on-the-v2-runtime).
358* Non registra un server di [canale](#push-messages-with-channels) che si connette sulla revisione più recente, perché quella revisione non può trasportare messaggi di canale.358* Non registra un server di [canale](#push-messages-with-channels) che si connette sulla revisione più recente, perché quella revisione non può trasportare messaggi di canale.
359* Fa fallire un [accesso OAuth MCP](#authenticate-with-remote-mcp-servers) la cui risposta di autorizzazione indica un emittente inatteso.359* Fa fallire un [accesso MCP OAuth](#authenticate-with-remote-mcp-servers) la cui risposta di autorizzazione indica un emittente inatteso.
360* Invia le credenziali [OAuth MCP](#authenticate-with-remote-mcp-servers) solo a un endpoint dei token servito tramite HTTPS o su `localhost`, `127.0.0.1` o `::1`. L'accesso fallisce per un server il cui endpoint dei token è `http://` semplice in qualsiasi altra posizione, come un dispositivo sulla tua rete locale. Consulta [Refusing to send credentials to non-https token endpoint](https://code.claude.com/docs/it/errors.md#refusing-to-send-credentials-to-non-https-token-endpoint).360* Invia le credenziali [MCP OAuth](#authenticate-with-remote-mcp-servers) solo a un endpoint dei token servito tramite HTTPS o su `localhost`, `127.0.0.1` o `::1`. L'accesso fallisce per un server il cui endpoint dei token è un semplice `http://` in qualsiasi altro punto, come un dispositivo sulla tua rete locale. Consulta [Refusing to send credentials to non-https token endpoint](https://code.claude.com/docs/it/errors.md#refusing-to-send-credentials-to-non-https-token-endpoint).
361 361
362Anthropic può mantenere un server specifico sul protocollo precedente, o fuori da quello stream, con un feature flag recuperato da Claude Code. Per scegliere tu il runtime, imposta [`MCP_SDK_GENERATION`](https://code.claude.com/docs/it/env-vars) su `v1` o `v2`.362Anthropic può mantenere un server specifico sul protocollo precedente, o fuori da quello stream, con un feature flag che Claude Code recupera. Per scegliere tu il runtime, imposta [`MCP_SDK_GENERATION`](https://code.claude.com/docs/it/env-vars) su `v1` o `v2`.
363 363
364Per decidere se Claude Code chiede ai server della revisione più recente, imposta [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/it/env-vars) su `auto` o `legacy`. Con quella variabile non impostata, Claude Code può evitare di chiedere a un server stdio per 7 giorni, per esempio dopo che il server termina quando interrogato. Per fare in modo che un server aggiornato venga interrogato prima, imposta `auto`.364Per decidere se Claude Code chiede ai server della revisione più recente, imposta [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/it/env-vars) su `auto` o `legacy`. Con quella variabile non impostata, Claude Code può evitare di chiederlo a un server stdio per 7 giorni, ad esempio dopo che il server è terminato quando gli è stato chiesto. Per fare in modo che un server aggiornato venga interpellato prima, imposta `auto`.
365 365
366### Aggiornamenti dinamici degli strumenti366### Aggiornamenti dinamici degli strumenti
367 367
368Un server MCP può modificare gli strumenti, i prompt o le risorse che offre mentre è connesso e inviare una notifica `list_changed`. Quando ne arriva una:368Un server MCP può cambiare gli strumenti, i prompt o le risorse che offre mentre è connesso e inviare una notifica `list_changed`. Quando ne arriva una:
369 369
370* **In una sessione interattiva del terminale**, Claude Code recupera l'elenco aggiornato da quel server, quindi non devi riconnetterlo.370* **In una sessione di terminale interattiva**, Claude Code recupera l'elenco aggiornato da quel server, quindi non devi riconnetterlo.
371* **In [modalità non interattiva](https://code.claude.com/docs/it/headless.md) con il flag `-p` e nell'[Agent SDK](https://code.claude.com/docs/it/agent-sdk/overview.md)**, Claude Code aggiorna solo l'elenco degli strumenti in risposta a queste notifiche.371* **In [modalità non interattiva](https://code.claude.com/docs/it/headless.md) con il flag `-p` e nell'[Agent SDK](https://code.claude.com/docs/it/agent-sdk/overview.md)**, Claude Code aggiorna solo l'elenco degli strumenti con queste notifiche.
372 372
373Se una richiesta di aggiornamento fallisce, Claude Code mantiene gli strumenti, i prompt e le risorse rilevati in precedenza per il server fino al successivo aggiornamento riuscito.373Se una richiesta di aggiornamento fallisce, Claude Code mantiene gli strumenti, i prompt e le risorse scoperti in precedenza dal server finché un aggiornamento successivo non riesce.
374 374
375#### Stream di notifiche sul runtime v2375#### Stream di notifiche sul runtime v2
376 376
377Sul [runtime v2](#mcp-client-runtimes), Claude Code riceve le notifiche `list_changed` da un server sulla revisione più recente del protocollo tramite uno stream che mantiene aperto. Quando lo stream si chiude, Claude Code lo riapre, con due limiti:377Sul [runtime v2](#mcp-client-runtimes), Claude Code riceve le notifiche `list_changed` da un server sulla revisione del protocollo più recente tramite uno stream che mantiene aperto. Quando lo stream si chiude, Claude Code lo riapre, con due limiti:
378 378
379* **Lo stream si richiude entro 10 secondi**: Claude Code lo riapre fino a tre volte, poi si ferma per quella connessione.379* **Lo stream si richiude entro 10 secondi**: Claude Code lo riapre fino a tre volte, poi si ferma per quella connessione.
380* **Lo stream resta aperto più di 10 secondi, poi si chiude**, come accade comunemente con gli stream verso host serverless: dopo cinque riaperture in un'ora, Claude Code attende circa sei ore prima della successiva.380* **Lo stream resta aperto più di 10 secondi, poi si chiude**, come accade comunemente agli stream verso host serverless: dopo cinque riaperture in un'ora, Claude Code attende circa sei ore prima della successiva.
381 381
382Finché lo stream non si riapre, mantieni gli ultimi strumenti, prompt e risorse recuperati dal server. Per acquisire prima le sue modifiche, riconnetti il server da `/mcp`.382Finché lo stream non si riapre, mantieni gli ultimi strumenti, prompt e risorse recuperati dal server. Per recepire prima le sue modifiche, riconnetti il server da `/mcp`.
383 383
384### Riconnessione automatica384### Riconnessione automatica
385 385
386Claude Code riconnette un server remoto che si disconnette a metà sessione e riprova la prima connessione di un server HTTP o SSE dopo un errore temporaneo. Per un server stdio, consulta [Server stdio che terminano o non si avviano](#stdio-servers-that-exit-or-fail-to-start).386Claude Code riconnette un server remoto che cade durante la sessione e riprova la prima connessione di un server HTTP o SSE dopo un errore transitorio. Per un server stdio, consulta [Server stdio che terminano o non si avviano](#stdio-servers-that-exit-or-fail-to-start).
387 387
388#### Disconnessioni di un server remoto a metà sessione388#### Cadute di un server remoto durante la sessione
389 389
390Claude Code prova innanzitutto a riconnettere un server remoto disconnesso fino a cinque volte con backoff esponenziale, partendo da un ritardo di un secondo e raddoppiandolo ogni volta:390Claude Code prova innanzitutto a riconnettere un server remoto caduto fino a cinque volte con backoff esponenziale, partendo da un ritardo di un secondo e raddoppiandolo ogni volta:
391 391
392* **In una sessione interattiva**: `/mcp` mostra il server come in attesa mentre Claude Code si riconnette. Dopo cinque tentativi falliti, Claude Code contrassegna il server come in errore, o come bisognoso di autenticazione quando il server deve essere nuovamente autorizzato. Quando contrassegna il server come in errore, vedi una notifica `MCP server "<name>" disconnected · open /mcp to reconnect`. Puoi riprovare manualmente da `/mcp`.392* **In una sessione interattiva**: `/mcp` mostra il server come in attesa mentre Claude Code si riconnette. Dopo cinque tentativi falliti, Claude Code contrassegna il server come in errore, o come bisognoso di autenticazione quando il server richiede una nuova autorizzazione. Quando contrassegna il server come in errore, vedi una notifica `MCP server "<name>" disconnected · open /mcp to reconnect`. Puoi riprovare manualmente da `/mcp`.
393* **Nelle esecuzioni [`claude -p`](https://code.claude.com/docs/it/headless) e nelle sessioni dell'[Agent SDK](https://code.claude.com/docs/it/agent-sdk/overview.md)**: Claude Code effettua gli stessi cinque tentativi, senza alcun pannello `/mcp` per mostrarli. Se falliscono tutti e cinque, l'esecuzione continua senza gli strumenti del server:393* **Nelle esecuzioni [`claude -p`](https://code.claude.com/docs/it/headless) e nelle sessioni [Agent SDK](https://code.claude.com/docs/it/agent-sdk/overview.md)**: Claude Code effettua gli stessi cinque tentativi, senza un pannello `/mcp` che li mostri. Se tutti e cinque falliscono, l'esecuzione continua senza gli strumenti del server:
394 * **Dopo un errore temporaneo, come una risposta 5xx o un timeout**: Claude Code continua a riprovare un server HTTP o SSE in background. I nuovi tentativi durano fino a circa mezz'ora, e gli strumenti del server tornano disponibili quando uno di essi riesce a connettersi. Fino ad allora, una sessione dell'Agent SDK riporta lo [stato](https://code.claude.com/docs/it/agent-sdk/mcp.md#error-handling) `failed`, e il tuo codice può [riconnettere il server](https://code.claude.com/docs/it/agent-sdk/mcp.md#error-handling). Per riconnetterlo in `claude -p`, avvia di nuovo l'esecuzione.394 * **Dopo un errore transitorio, come una risposta 5xx o un timeout**: Claude Code continua a riprovare un server HTTP o SSE in background. I nuovi tentativi durano fino a circa mezz'ora, e gli strumenti del server tornano disponibili quando uno riesce a connettersi. Fino ad allora, una sessione Agent SDK riporta lo [stato](https://code.claude.com/docs/it/agent-sdk/mcp.md#error-handling) `failed`, e il tuo codice può [riconnettere il server](https://code.claude.com/docs/it/agent-sdk/mcp.md#error-handling). Per riconnetterlo in `claude -p`, avvia di nuovo l'esecuzione.
395 * **Quando il server [richiede di accedere di nuovo](#authenticate-with-remote-mcp-servers)**: Claude Code smette di riprovare, e una sessione dell'Agent SDK riporta lo stato del server come `needs-auth`. Accedi con [`claude mcp login <name>`](#authenticate-from-the-command-line) nella tua shell. Poi avvia di nuovo l'esecuzione oppure, in una sessione dell'Agent SDK, [riconnetti invece il server](https://code.claude.com/docs/it/agent-sdk/mcp.md#error-handling).395 * **Quando il server [richiede di accedere di nuovo](#authenticate-with-remote-mcp-servers)**: Claude Code smette di riprovare, e una sessione Agent SDK riporta lo stato del server come `needs-auth`. Accedi con [`claude mcp login <name>`](#authenticate-from-the-command-line) nella tua shell. Poi avvia di nuovo l'esecuzione oppure, in una sessione Agent SDK, [riconnetti invece il server](https://code.claude.com/docs/it/agent-sdk/mcp.md#error-handling).
396 396
397#### Prime connessioni fallite397#### Prime connessioni fallite
398 398
399Quando la prima connessione di un server HTTP o SSE fallisce con un errore temporaneo, come una risposta 5xx, una connessione rifiutata o un timeout, Claude Code riprova fino a tre volte. Se la connessione fallisce ancora, Claude Code contrassegna il server come in errore.399Quando 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 riprova fino a tre volte. Se la connessione fallisce ancora, Claude Code contrassegna il server come in errore.
400 400
401Questi nuovi tentativi non si applicano nei seguenti casi:401Questi nuovi tentativi non si applicano in questi casi:
402 402
403* La prima connessione di un server stdio. Per riprovarla, consulta [Server stdio che terminano o non si avviano](#stdio-servers-that-exit-or-fail-to-start)403* La prima connessione di un server stdio. Per riprovarla, consulta [Server stdio che terminano o non si avviano](#stdio-servers-that-exit-or-fail-to-start)
404* La prima connessione di un server WebSocket. Per riprovarla in una sessione interattiva del terminale, seleziona **Reconnect** dal menu del server in `/mcp`404* La prima connessione di un server WebSocket. Per riprovarla in una sessione di terminale interattiva, seleziona **Reconnect** dal menu del server in `/mcp`
405* Un errore di autenticazione o di risorsa non trovata, perché per risolverlo è necessaria una modifica alla configurazione. Quando un [`headersHelper`](#use-dynamic-headers-for-custom-authentication) è l'unica fonte dell'header `Authorization` del server, Claude Code riprova comunque un errore di autenticazione, perché riesegue l'helper a ogni tentativo e può ottenere una credenziale nuova405* Un errore di autenticazione o di risorsa non trovata, perché richiede una modifica della configurazione per essere risolto. Quando un [`headersHelper`](#use-dynamic-headers-for-custom-authentication) è l'unica fonte dell'header `Authorization` del server, Claude Code riprova comunque un errore di autenticazione, perché esegue di nuovo l'helper a ogni tentativo e può ottenere una credenziale nuova
406 406
407#### Server stdio che terminano o non si avviano407#### Server stdio che terminano o non si avviano
408 408
409Per avviare di nuovo un server stdio, leggi la colonna che corrisponde a ciò che gli è successo. Trova la tua riga in base a come esegui Claude Code: una sessione interattiva, un'esecuzione `claude -p` o una sessione dell'Agent SDK.409Per avviare di nuovo un server stdio, leggi la colonna che corrisponde a ciò che gli è successo. Trova la tua riga in base a come esegui Claude Code: una sessione interattiva, un'esecuzione `claude -p` o una sessione Agent SDK.
410 410
411| Come esegui Claude Code | Il processo del server termina a metà sessione | La prima connessione del server fallisce |411| Come esegui Claude Code | Il processo del server termina durante la sessione | La prima connessione del server fallisce |
412| - | - | - |412| - | - | - |
413| Sessione interattiva | Claude Code contrassegna il server come in errore. Per avviarlo di nuovo, seleziona **Reconnect** dal menu del server in `/mcp` | Claude Code contrassegna il server come in errore. Per avviarlo di nuovo, seleziona **Reconnect** dal menu del server in `/mcp` |413| Sessione interattiva | Claude Code contrassegna il server come in errore. Per avviarlo di nuovo, seleziona **Reconnect** dal menu del server in `/mcp` | Claude Code contrassegna il server come in errore. Per avviarlo di nuovo, seleziona **Reconnect** dal menu del server in `/mcp` |
414| Esecuzione `claude -p` | Claude Code avvia di nuovo il server la volta successiva in cui Claude chiama uno degli strumenti del server, e la chiamata viene eseguita non appena il server si connette | L'esecuzione continua senza gli strumenti del server. Per fare in modo che Claude Code riprovi la connessione, avvia di nuovo l'esecuzione. Quando il server è fornito da un plugin, le nuove esecuzioni saltano la connessione per 15 minuti dopo un errore, quindi attendi prima quel tempo oppure [riprova prima](https://code.claude.com/docs/it/errors.md#skipping-connection-recent-failure-cached) |414| Esecuzione `claude -p` | Claude Code avvia di nuovo il server la volta successiva in cui Claude chiama uno dei suoi strumenti, e la chiamata viene eseguita non appena il server si connette | L'esecuzione continua senza gli strumenti del server. Per fare in modo che Claude Code riprovi la connessione, avvia di nuovo l'esecuzione. Quando il server è fornito da un plugin, le nuove esecuzioni saltano la connessione per 15 minuti dopo un errore, quindi attendi prima quel tempo oppure [riprova prima](https://code.claude.com/docs/it/errors.md#skipping-connection-recent-failure-cached) |
415| Sessione dell'Agent SDK | Claude Code avvia di nuovo il server la volta successiva in cui Claude chiama uno degli strumenti del server, e la chiamata viene eseguita non appena il server si connette | La sessione continua senza gli strumenti del server. Il tuo codice può [riconnettere il server](https://code.claude.com/docs/it/agent-sdk/mcp.md#error-handling) |415| Sessione Agent SDK | Claude Code avvia di nuovo il server la volta successiva in cui Claude chiama uno dei suoi strumenti, e la chiamata viene eseguita non appena il server si connette | La sessione continua senza gli strumenti del server. Il tuo codice può [riconnettere il server](https://code.claude.com/docs/it/agent-sdk/mcp.md#error-handling) |
416 416
417#### Richieste di rilevamento fallite417#### Richieste di discovery fallite
418 418
419Dopo che un server si è connesso, Claude Code gli invia richieste di rilevamento delle capacità come `tools/list`, `prompts/list` e `resources/list`. Claude Code riprova queste richieste fino a tre volte con un breve backoff dopo un errore temporaneo di rete o del server. Non riprova in caso di errori di autenticazione, risposte 4xx o timeout delle richieste.419Dopo che un server si è connesso, Claude Code gli invia richieste di discovery delle capacità come `tools/list`, `prompts/list` e `resources/list`. Claude Code riprova queste richieste fino a tre volte con un breve backoff dopo un errore transitorio di rete o del server. Non riprova in caso di errori di autenticazione, risposte 4xx o timeout delle richieste.
420 420
421#### Riprovare tu stesso i server in errore421#### Riprovare tu stesso i server in errore
422 422
423Per riprovare ogni server in errore o che richiede autenticazione, esegui `/mcp reconnect all` al prompt di Claude Code in una sessione interattiva del terminale. Questo richiede Claude Code v2.1.284 o successivo. Le versioni precedenti stampano `MCP server "all" not found`.423Per riprovare tutti i server in errore o che richiedono autenticazione, esegui `/mcp reconnect all` al prompt di Claude Code in una sessione di terminale interattiva. Questo richiede Claude Code v2.1.284 o successivo. Le versioni precedenti stampano `MCP server "all" not found`.
424 424
425#### Come Claude viene a sapere che un server è in errore425#### Come Claude viene a sapere che un server è in errore
426 426
427Se Claude Code comunica a Claude che un server configurato non è riuscito a connettersi dipende dalla [ricerca degli strumenti](#scale-with-mcp-tool-search), che è attiva per impostazione predefinita:427Se Claude Code comunica a Claude che un server configurato non è riuscito a connettersi dipende dalla [ricerca degli strumenti](#scale-with-mcp-tool-search), che è attiva per impostazione predefinita:
428 428
429* Con la ricerca degli strumenti, Claude Code comunica a Claude quale server è in errore e il relativo errore di connessione, così Claude segnala l'errore di connessione nella sua risposta. Claude Code include le stesse informazioni nei risultati di `ToolSearch` che non trovano alcuno strumento corrispondente.429* Con la ricerca degli strumenti, Claude Code comunica a Claude quale server è in errore e il relativo errore di connessione, così Claude riporta l'errore di connessione nella sua risposta. Claude Code include le stesse informazioni nei risultati di `ToolSearch` che non trovano alcuno strumento corrispondente.
430* In qualsiasi [configurazione senza ricerca degli strumenti](#configure-tool-search), Claude Code non segnala a Claude le connessioni ai server fallite.430* In qualsiasi [configurazione senza ricerca degli strumenti](#configure-tool-search), Claude Code non segnala a Claude le connessioni ai server fallite.
431 431
432### Inviare messaggi con i canali432### Inviare messaggi con i canali
433 433
434Un server MCP può anche inviare messaggi direttamente nella tua sessione, così Claude può reagire a eventi esterni come risultati della CI, avvisi di monitoraggio o messaggi di chat. Per abilitarlo, il tuo server dichiara la capacità `claude/channel` e tu lo abiliti con il flag `--channels` all'avvio. Consulta [Canali](https://code.claude.com/docs/it/channels.md) per usare un canale supportato ufficialmente, oppure [Riferimento dei canali](https://code.claude.com/docs/it/channels-reference.md) per crearne uno tuo.434Un server MCP può anche inviare messaggi direttamente nella tua sessione, così Claude può reagire a eventi esterni come risultati della CI, avvisi di monitoraggio o messaggi di chat. Per abilitarlo, il tuo server dichiara la capacità `claude/channel` e tu lo abiliti con il flag `--channels` all'avvio. Consulta [Canali](https://code.claude.com/docs/it/channels.md) per usare un canale supportato ufficialmente, oppure [Riferimento dei canali](https://code.claude.com/docs/it/channels-reference.md) per crearne uno tuo.
435 435
436Sul [runtime v2](#mcp-client-runtimes), un server di canale che negozia la revisione del protocollo MCP 2026-07-28 non può consegnare messaggi di canale, quindi Claude Code non lo registra come canale. Un server di canale che non supporta quella revisione si connette con l'handshake precedente e viene registrato come prima.436Sul [runtime v2](#mcp-client-runtimes), un server di canale che negozia la revisione del protocollo MCP 2026-07-28 non può consegnare messaggi di canale, quindi Claude Code non lo registra come canale. Un server di canale che non supporta quella revisione si connette con l'handshake precedente e si registra come prima.
437 437
438Claude Code chiede quella revisione ai server stdio per impostazione predefinita. Per mantenere un server di canale stdio sull'handshake precedente, imposta [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/it/env-vars) su `legacy`, che mantiene tutti i server su di esso.438Claude Code chiede quella revisione ai server stdio per impostazione predefinita. Per mantenere un server di canale stdio sull'handshake precedente, imposta [`MCP_PROTOCOL_NEGOTIATION`](https://code.claude.com/docs/it/env-vars) su `legacy`, che mantiene tutti i server su di esso.
439 439
447> * `user`: disponibile per te in tutti i progetti447> * `user`: disponibile per te in tutti i progetti
448> * Imposta le variabili d'ambiente con i flag `-e` o `--env` (ad esempio, `-e KEY=value`)448> * Imposta le variabili d'ambiente con i flag `-e` o `--env` (ad esempio, `-e KEY=value`)
449> * I flag `--transport` e `--header` accettano anche le forme brevi `-t` e `-H`449> * I flag `--transport` e `--header` accettano anche le forme brevi `-t` e `-H`
450> * Configura il timeout di avvio del server MCP usando la variabile d'ambiente `MCP_TIMEOUT` (ad esempio, `MCP_TIMEOUT=10000 claude` imposta un timeout di 10 secondi)450> * Configura il timeout di avvio dei server MCP usando la variabile d'ambiente `MCP_TIMEOUT` (ad esempio, `MCP_TIMEOUT=10000 claude` imposta un timeout di 10 secondi)
451> * Imposta un timeout di esecuzione degli strumenti per server aggiungendo un campo `timeout` in millisecondi alla voce `.mcp.json` di quel server, ad esempio `"timeout": 600000` per dieci minuti. Questo sovrascrive la variabile d'ambiente `MCP_TOOL_TIMEOUT` solo per quel server451> * Imposta un timeout di esecuzione degli strumenti per singolo server aggiungendo un campo `timeout` in millisecondi alla voce `.mcp.json` di quel server, ad esempio `"timeout": 600000` per dieci minuti. Questo sovrascrive la variabile d'ambiente `MCP_TOOL_TIMEOUT` solo per quel server
452> * Claude Code mostra un avviso quando l'output di uno strumento MCP supera i 10.000 token e limita l'output a 25.000 token per impostazione predefinita. Per modificare il limite di token, imposta la variabile d'ambiente `MAX_MCP_OUTPUT_TOKENS`, ad esempio `MAX_MCP_OUTPUT_TOKENS=50000`. La soglia di avviso è fissa. A meno che il server non aumenti il limite specifico di uno strumento, i risultati testuali riusciti più lunghi di 50.000 caratteri vengono salvati in un file indipendentemente da questa variabile. Consulta [Limiti e avvisi sull'output MCP](#mcp-output-limits-and-warnings)452> * Claude Code mostra un avviso quando l'output di uno strumento MCP supera i 10.000 token e limita l'output a 25.000 token per impostazione predefinita. Per cambiare il limite di token, imposta la variabile d'ambiente `MAX_MCP_OUTPUT_TOKENS`, ad esempio `MAX_MCP_OUTPUT_TOKENS=50000`. La soglia di avviso è fissa. A meno che il server non aumenti il limite proprio di uno strumento, i risultati testuali riusciti più lunghi di 50.000 caratteri vengono salvati in un file indipendentemente da questa variabile. Consulta [Limiti e avvisi sull'output MCP](#mcp-output-limits-and-warnings)
453> * Usa `/mcp` per autenticarti con i server remoti che richiedono l'autenticazione OAuth 2.0453> * Usa `/mcp` per autenticarti con i server remoti che richiedono l'autenticazione OAuth 2.0
454 454
455### Limiti di tempo sulle chiamate agli strumenti MCP455### Limiti di tempo sulle chiamate agli strumenti MCP
459* **Per server**: aggiungi un campo `timeout` in millisecondi alla voce di configurazione di quel server459* **Per server**: aggiungi un campo `timeout` in millisecondi alla voce di configurazione di quel server
460* **Per tutti i server**: imposta [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/it/env-vars)460* **Per tutti i server**: imposta [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/it/env-vars)
461 461
462Il `timeout` per server è un limite rigido di tempo reale per ogni chiamata a uno strumento, e le notifiche di avanzamento del server non lo estendono. I valori inferiori a 1000 vengono ignorati e si ricade su `MCP_TOOL_TIMEOUT`, o sul suo valore predefinito di circa 28 ore quando quella variabile non è impostata. Per un server HTTP, SSE o [connettore claude.ai](https://code.claude.com/docs/it/mcp.md#use-mcp-servers-from-claude-ai) esiste anche un secondo timer per richiesta che copre ogni richiesta fino al primo byte della risposta del server. Claude Code imposta quel timer sul maggiore di tre valori: 60 secondi, il timeout degli strumenti 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.462Il `timeout` per server è un limite rigido in tempo reale per ogni chiamata a uno strumento, e le notifiche di avanzamento del server non lo estendono. I valori inferiori a 1000 vengono ignorati e si ricade su `MCP_TOOL_TIMEOUT`, o sul suo valore predefinito di circa 28 ore quando quella variabile non è impostata. Per un server HTTP, SSE o [connettore claude.ai](https://code.claude.com/docs/it/mcp.md#use-mcp-servers-from-claude-ai) esiste anche un secondo timer per richiesta che copre ogni richiesta fino al primo byte di risposta del server. Claude Code imposta quel timer sul maggiore di tre valori: 60 secondi, il timeout degli strumenti applicabile 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.
463 463
464Un `timeout` per server di almeno 1000 funge anche da soglia minima per il timeout di inattività descritto di seguito: Claude Code non interrompe mai per inattività le chiamate agli strumenti di quel server prima del `timeout` per server.464Un `timeout` per server di almeno 1000 funge anche da soglia minima per il timeout di inattività descritto di seguito: Claude Code non interrompe mai per inattività le chiamate agli strumenti di quel server prima del `timeout` per server.
465 465
466Una chiamata a uno strumento di un server MCP che non invia alcuna risposta e alcuna notifica di avanzamento per la durata della finestra di inattività viene interrotta con un errore invece di attendere il limite di tempo reale. Il timeout di inattività si applica a tutti i tipi di server tranne i server IDE e i server in-process dell'SDK. La finestra di inattività è per impostazione predefinita di cinque minuti per i server HTTP, SSE, WebSocket e [connettori claude.ai](#use-mcp-servers-from-claude-ai), e di 30 minuti per i server stdio.466Una chiamata a uno strumento di un server MCP che non invia alcuna risposta né notifica di avanzamento per la finestra di inattività viene interrotta con un errore invece di attendere il limite in tempo reale. Il timeout di inattività si applica a tutti i tipi di server tranne i server IDE e i server SDK in-process. La finestra di inattività è di cinque minuti per impostazione predefinita per i server HTTP, SSE, WebSocket e [connettori claude.ai](#use-mcp-servers-from-claude-ai), e di 30 minuti per i server stdio.
467 467
468Imposta la variabile d'ambiente [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/it/env-vars) in millisecondi per modificare la finestra di inattività, oppure impostala su `0` per disattivare il controllo.468Imposta la variabile d'ambiente [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/it/env-vars) in millisecondi per cambiare la finestra di inattività, oppure impostala su `0` per disabilitare il controllo.
469 469
470Questi timeout limitano per quanto tempo può essere eseguita una chiamata, non sempre per quanto tempo blocca la sessione: una chiamata nella conversazione principale che supera i due minuti passa prima a un'attività in background. Consulta [Spostamento automatico in background delle chiamate lunghe agli strumenti](#automatic-backgrounding-of-long-tool-calls).470Questi timeout limitano la durata di una chiamata, non sempre il tempo per cui blocca la sessione: una chiamata della conversazione principale che supera i due minuti viene prima spostata in un'attività in background. Consulta [Spostamento automatico in background delle chiamate lunghe agli strumenti](#automatic-backgrounding-of-long-tool-calls).
471 471
472### Spostamento automatico in background delle chiamate lunghe agli strumenti472### Spostamento automatico in background delle chiamate lunghe agli strumenti
473 473
474Se la vista di dettaglio di una chiamata in background in [`/tasks`](https://code.claude.com/docs/it/commands#all-commands) mostra `runs on the server; survives exiting this session`, consulta [Attività MCP eseguite sul server](#mcp-tasks-that-run-on-the-server).474Se la vista di dettaglio di una chiamata in background in [`/tasks`](https://code.claude.com/docs/it/commands#all-commands) mostra `runs on the server; survives exiting this session`, consulta [Attività MCP eseguite sul server](#mcp-tasks-that-run-on-the-server).
475 475
476Una chiamata a uno strumento MCP nella conversazione principale che è ancora in esecuzione dopo due minuti passa a un'attività in background invece di bloccare la sessione. Claude riceve immediatamente l'ID dell'attività e continua a lavorare, e il risultato arriva come notifica dell'attività quando la chiamata si conclude.476Una chiamata a uno strumento MCP nella conversazione principale ancora in esecuzione dopo due minuti viene spostata in un'attività in background invece di bloccare la sessione. Claude riceve subito l'ID dell'attività e continua a lavorare, e il risultato arriva come notifica dell'attività quando la chiamata si conclude.
477 477
478L'attività compare in [`/tasks`](https://code.claude.com/docs/it/commands#all-commands), dove puoi anche arrestarla, e non sopravvive all'uscita dalla sessione. La voce dell'attività mostra l'ultimo avanzamento riportato dal server. Se arresti l'attività, Claude Code annulla la chiamata e comunica a Claude che non arriverà alcun risultato. L'arresto non garantisce che il server si fermi: potrebbe aver già svolto parte del lavoro, o potrebbe comunque completarlo.478L'attività compare in [`/tasks`](https://code.claude.com/docs/it/commands#all-commands), dove puoi anche arrestarla, e non sopravvive all'uscita dalla sessione. La voce dell'attività mostra l'ultimo avanzamento riportato dal server. Se arresti l'attività, Claude Code annulla la chiamata e comunica a Claude che non arriverà alcun risultato. L'arresto non garantisce che il server si fermi: potrebbe aver già svolto parte del lavoro, o potrebbe comunque completarlo.
479 479
480I limiti per chiamata si applicano anche mentre la chiamata è in esecuzione in background: il limite di tempo reale impostato dal `timeout` per server o da [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/it/env-vars), e il timeout di inattività impostato da [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/it/env-vars).480I limiti per chiamata continuano ad applicarsi mentre la chiamata viene eseguita in background: il limite in tempo reale impostato dal `timeout` per server o da [`MCP_TOOL_TIMEOUT`](https://code.claude.com/docs/it/env-vars), e il timeout di inattività impostato da [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](https://code.claude.com/docs/it/env-vars).
481 481
482Per modificare o disattivare lo spostamento automatico in background:482Per modificare o disattivare lo spostamento automatico in background:
483 483
484* Imposta la variabile d'ambiente [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/it/env-vars) in millisecondi per modificare la soglia, oppure impostala su `0` per disattivare lo spostamento automatico in background. Con `0`, Claude [attende anche le attività MCP](#make-claude-wait-for-the-result-of-an-mcp-task) in una sessione interattiva484* Imposta la variabile d'ambiente [`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/it/env-vars) in millisecondi per cambiare la soglia, oppure impostala su `0` per disattivare lo spostamento automatico in background. Con `0`, Claude [attende anche le attività MCP](#make-claude-wait-for-the-result-of-an-mcp-task) in una sessione interattiva
485* Imposta [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/it/env-vars) su `1` per disattivare il passaggio automatico in background e i [comandi in background](https://code.claude.com/docs/it/tools-reference.md#background-commands)485* Imposta [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/it/env-vars) su `1` per disattivare lo spostamento automatico in background e i [comandi in background](https://code.claude.com/docs/it/tools-reference.md#background-commands)
486 486
487Alcune chiamate non passano mai in background:487Alcune chiamate non vengono mai spostate in background:
488 488
489* Le chiamate dai [subagent](https://code.claude.com/docs/it/sub-agents.md); Claude Code sposta in background solo le chiamate della conversazione principale489* Le chiamate dei [subagent](https://code.claude.com/docs/it/sub-agents.md); Claude Code sposta in background solo le chiamate della conversazione principale
490* Le chiamate ai server IDE490* Le chiamate ai server IDE
491* Le chiamate in [modalità non interattiva](https://code.claude.com/docs/it/headless.md), a meno che `CLAUDE_AUTO_BACKGROUND_TASKS` non sia impostato su `1`, poiché un'esecuzione singola può terminare prima che arrivi il risultato491* Le chiamate in [modalità non interattiva](https://code.claude.com/docs/it/headless.md), a meno che `CLAUDE_AUTO_BACKGROUND_TASKS` non sia impostato su `1`, poiché un'esecuzione singola può terminare prima dell'arrivo del risultato
492 492
493Una chiamata in attesa di una [finestra di dialogo di elicitation](#respond-to-mcp-elicitation-requests) aperta non viene spostata in background mentre la finestra è aperta; il server è bloccato in attesa del tuo input, non è lento, quindi Claude Code rinvia lo spostamento finché la finestra non si chiude.493Una chiamata in attesa di una [finestra di dialogo di elicitation](#respond-to-mcp-elicitation-requests) aperta non viene spostata in background mentre la finestra è aperta; il server è bloccato in attesa del tuo input, non è lento, quindi Claude Code rimanda lo spostamento finché la finestra non si chiude.
494 494
495### Attività MCP eseguite sul server495### Attività MCP eseguite sul server
496 496
497Un'attività MCP è un lavoro lungo, come l'esportazione di un report o una build, che un server MCP esegue autonomamente usando l'[estensione MCP tasks](https://modelcontextprotocol.io/extensions/tasks/overview). La chiamata allo strumento di Claude ritorna non appena il server accetta il lavoro, quindi Claude continua a lavorare a meno che tu non [faccia attendere Claude](#make-claude-wait-for-the-result-of-an-mcp-task). Quando il lavoro termina, la trascrizione lo indica e Claude riceve il risultato. Chiedilo a Claude.497Un'attività MCP è un lavoro lungo, come l'esportazione di un report o una build, che un server MCP esegue autonomamente usando l'[estensione MCP tasks](https://modelcontextprotocol.io/extensions/tasks/overview). La chiamata di Claude allo strumento restituisce non appena il server accetta il lavoro, quindi Claude continua a lavorare a meno che tu non [faccia attendere Claude](#make-claude-wait-for-the-result-of-an-mcp-task). Quando il lavoro termina, la trascrizione lo indica e Claude riceve il risultato. Chiedilo a Claude.
498 498
499Nel frattempo, il piè di pagina mostra un conteggio come `1 MCP task`, e Claude Code segue l'attività controllandone lo stato con il server. Un'attività su un server remoto continua a essere eseguita dopo che esci. Per seguirla di nuovo, [riprendi la stessa sessione](#exit-clear-or-resume-while-an-mcp-task-runs).499Nel frattempo, il piè di pagina mostra un conteggio come `1 MCP task`, e Claude Code segue l'attività controllandone lo stato con il server. Un'attività su un server remoto continua a essere eseguita dopo che esci. Per seguirla di nuovo, [riprendi la stessa sessione](#exit-clear-or-resume-while-an-mcp-task-runs).
500 500
501> [!NOTE]501> [!NOTE]
502>502>
503> Le attività MCP sono in beta pubblica nella CLI di Claude Code e richiedono Claude Code v2.1.304 o successiva. [Cosa serve a una chiamata per diventare un'attività MCP](#requirements-for-mcp-tasks) elenca le sessioni e i server che le supportano.503> Le attività MCP sono in beta pubblica nella CLI di Claude Code e richiedono Claude Code v2.1.304 o successivo. [Cosa serve a una chiamata per diventare un'attività MCP](#requirements-for-mcp-tasks) elenca le sessioni e i server che le supportano.
504 504
505#### Arrestare un'attività MCP o ottenerne il risultato505#### Arrestare un'attività MCP o ottenerne il risultato
506 506
512MCP task <server task id> (<server>/<tool>) completed.512MCP task <server task id> (<server>/<tool>) completed.
513```513```
514 514
515Il risultato va a Claude, non nella trascrizione, quindi chiedilo a Claude. Se Claude è inattivo quando arriva il risultato, Claude inizia a lavorarci senza sollecitazione.515Il risultato va a Claude, non nella trascrizione, quindi chiedilo a Claude. Se Claude è inattivo quando arriva il risultato, Claude inizia a elaborarlo senza che tu glielo chieda.
516 516
517#### Rispondere a una domanda di un'attività MCP517#### Rispondere a una domanda di un'attività MCP
518 518
519Un'attività in esecuzione può aprire una [finestra di dialogo di elicitazione](#respond-to-mcp-elicitation-requests) per chiederti un input. Mentre `/tasks` è aperto, la finestra di dialogo resta nascosta, quindi chiudi `/tasks` per rispondere. Rifiutare o premere `Esc` è una risposta al server, che poi decide se l'attività prosegue.519Un'attività in esecuzione può aprire una [finestra di dialogo di elicitation](#respond-to-mcp-elicitation-requests) per chiederti un input. Mentre `/tasks` è aperto, la finestra di dialogo resta nascosta, quindi chiudi `/tasks` per rispondere. Rifiutare o premere `Esc` è una risposta al server, che decide poi se l'attività prosegue.
520 520
521In una sessione [non interattiva](https://code.claude.com/docs/it/headless.md), Claude Code chiede al server di annullare un'attività che richiede un input, senza eseguire i tuoi [hook `Elicitation`](https://code.claude.com/docs/it/hooks#elicitation) né chiamare il callback `onElicitation` dell'Agent SDK.521In una sessione [non interattiva](https://code.claude.com/docs/it/headless.md), Claude Code chiede al server di annullare un'attività che richiede input, senza eseguire i tuoi [hook `Elicitation`](https://code.claude.com/docs/it/hooks#elicitation) né chiamare il callback `onElicitation` dell'Agent SDK.
522 522
523#### Uscire, cancellare o riprendere mentre un'attività MCP è in esecuzione523#### Uscire, cancellare o riprendere mentre un'attività MCP è in esecuzione
524 524
525Un'attività su un server remoto continua a essere eseguita dopo che esci. Il processo di un server stdio si arresta quando Claude Code esce, anche se le sue attività mostrano `runs on the server; survives exiting this session` in `/tasks`. A meno che la documentazione di quel server non indichi che il lavoro sopravvive al processo, lascia che quelle attività terminino o arrestale prima in `/tasks`.525Un'attività su un server remoto continua a essere eseguita dopo che esci. Il processo di un server stdio si arresta quando Claude Code termina, anche se le sue attività mostrano `runs on the server; survives exiting this session` in `/tasks`. A meno che la documentazione di quel server non indichi che il lavoro sopravvive al processo, lascia prima completare quelle attività oppure arrestale in `/tasks`.
526 526
527| Situazione | Cosa succede all'attività | Cosa puoi fare |527| Situazione | Cosa succede all'attività | Cosa puoi fare |
528| - | - | - |528| - | - | - |
529| Esegui `/clear` o `/branch`, oppure `/resume` su un'altra sessione | Finché Claude Code resta aperto, il risultato arriva nella conversazione corrente | Dopo un'uscita, esegui `claude --resume` sulla sessione in cui è iniziata l'attività |529| Esegui `/clear` o `/branch`, oppure `/resume` su un'altra sessione | Finché Claude Code resta aperto, il risultato arriva nella tua conversazione corrente | Dopo un'uscita, esegui `claude --resume` sulla sessione in cui è iniziata l'attività |
530| Esci da Claude Code | Nessuna opzione di uscita annulla l'attività di un server remoto, anche quando la finestra di dialogo di uscita la elenca sotto `The following will stop when you exit:` | Arrestala prima in `/tasks`, oppure riprendi la stessa sessione in seguito |530| Esci da Claude Code | Nessuna opzione di uscita annulla l'attività di un server remoto, anche quando la finestra di dialogo di uscita la elenca sotto `The following will stop when you exit:` | Arrestala prima in `/tasks`, oppure riprendi la stessa sessione in seguito |
531| Torni alla sessione dell'attività in modo interattivo: `claude --resume`, `claude --continue` o `/resume` | Una volta che il server si connette, Claude Code segue di nuovo l'attività, e Claude riceve il risultato se nel frattempo è terminata e il server la conosce ancora | Mantieni invariati il nome e le impostazioni di connessione del server |531| Torni alla sessione dell'attività in modo interattivo: `claude --resume`, `claude --continue` o `/resume` | Una volta che il server si connette, Claude Code segue di nuovo l'attività, e Claude riceve il risultato se nel frattempo è terminata e il server la conosce ancora | Mantieni invariati il nome e le impostazioni di connessione del server |
532| Riprendi la sessione dell'attività con `--resume` o `--continue` in un'esecuzione singola `claude -p "<prompt>"` | Quell'esecuzione non segue l'attività | Riprendi in modo interattivo, oppure con `--input-format stream-json` |532| Riprendi la sessione dell'attività con `--resume` o `--continue` in un'esecuzione singola `claude -p "<prompt>"` | Quell'esecuzione non segue l'attività | Riprendi in modo interattivo, oppure con `--input-format stream-json` |
539* Il server supporta le attività539* Il server supporta le attività
540* Il server è un server HTTP, stdio o connettore claude.ai connesso sulla [revisione del protocollo 2026-07-28](#mcp-client-runtimes). Impostare [`MCP_SDK_GENERATION=v1` o `MCP_PROTOCOL_NEGOTIATION=legacy`](https://code.claude.com/docs/it/env-vars) lo esclude540* Il server è un server HTTP, stdio o connettore claude.ai connesso sulla [revisione del protocollo 2026-07-28](#mcp-client-runtimes). Impostare [`MCP_SDK_GENERATION=v1` o `MCP_PROTOCOL_NEGOTIATION=legacy`](https://code.claude.com/docs/it/env-vars) lo esclude
541* La sessione [recupera i feature flag](https://code.claude.com/docs/it/env-vars.md#features-that-need-feature-flag-fetching), quindi non su un provider di terze parti come Amazon Bedrock, e non con la telemetria o il recupero dei flag disattivati541* La sessione [recupera i feature flag](https://code.claude.com/docs/it/env-vars.md#features-that-need-feature-flag-fetching), quindi non su un provider di terze parti come Amazon Bedrock, e non con la telemetria o il recupero dei flag disattivati
542* Anthropic ha attivato le attività MCP per il tuo tipo di sessione. Dalla v2.1.304 in poi ciò copre le sessioni CLI nel terminale, le sessioni dell'[Agent SDK](https://code.claude.com/docs/it/agent-sdk/overview.md) e le esecuzioni di [GitHub Actions](https://code.claude.com/docs/it/github-actions.md). Altre superfici, come l'[estensione VS Code](https://code.claude.com/docs/it/vs-code.md) e l'[app desktop](https://code.claude.com/docs/it/desktop.md), non hanno le attività MCP542* Anthropic ha attivato le attività MCP per il tuo tipo di sessione. Su v2.1.304 o successivo ciò copre le sessioni della CLI nel terminale, le sessioni [Agent SDK](https://code.claude.com/docs/it/agent-sdk/overview.md) e le esecuzioni di [GitHub Actions](https://code.claude.com/docs/it/github-actions.md). Altre superfici, come l'[estensione VS Code](https://code.claude.com/docs/it/vs-code.md) e l'[app desktop](https://code.claude.com/docs/it/desktop.md), non hanno le attività MCP
543* La chiamata proviene dalla conversazione principale, non da un [subagent](https://code.claude.com/docs/it/sub-agents.md)543* La chiamata proviene dalla conversazione principale, non da un [subagent](https://code.claude.com/docs/it/sub-agents.md)
544* La sessione è interattiva, oppure una sessione dell'[Agent SDK](https://code.claude.com/docs/it/agent-sdk/overview.md) o un'esecuzione `claude -p` che legge `--input-format stream-json` ha:544* La sessione è interattiva, oppure una sessione [Agent SDK](https://code.claude.com/docs/it/agent-sdk/overview.md) o un'esecuzione `claude -p` che legge `--input-format stream-json` ha:
545 * [`CLAUDE_AUTO_BACKGROUND_TASKS`](https://code.claude.com/docs/it/env-vars) impostato su `1`545 * [`CLAUDE_AUTO_BACKGROUND_TASKS`](https://code.claude.com/docs/it/env-vars) a `1`
546 * `CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND` diverso da `1`546 * `CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND` diverso da `1`
547 * `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` diverso da `0`547 * `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` diverso da `0`
548 548
549Qualsiasi altra chiamata è una normale chiamata a uno strumento, e [Spostamento automatico in background delle chiamate lunghe agli strumenti](#automatic-backgrounding-of-long-tool-calls) indica quali di queste passano in background.549Qualsiasi altra chiamata è una normale chiamata a uno strumento, e [Spostamento automatico in background delle chiamate lunghe agli strumenti](#automatic-backgrounding-of-long-tool-calls) indica quali di esse vengono spostate in background.
550 550
551Mantieni aperto l'input di una sessione dell'Agent SDK o stream-json, perché l'esecuzione [non attende le attività MCP](https://code.claude.com/docs/it/headless.md#mcp-work-when-a-non-interactive-run-ends) dopo la chiusura dell'input. Un'esecuzione singola `claude -p "<prompt>"` non supporta le attività MCP.551Mantieni aperto l'input di una sessione Agent SDK o stream-json, perché l'esecuzione [non attende le attività MCP](https://code.claude.com/docs/it/headless.md#mcp-work-when-a-non-interactive-run-ends) dopo la chiusura dell'input. Un'esecuzione singola `claude -p "<prompt>"` non ottiene attività MCP.
552 552
553#### Messaggi di stato su un'attività MCP553#### Messaggi di stato su un'attività MCP
554 554
555Questi messaggi, nella voce `/tasks` di un'attività o nella sua riga di chiusura nella trascrizione, indicano che Claude Code non riesce a raggiungere il server o l'attività. Mentre uno di essi è visibile in `/tasks`, il lavoro potrebbe essere ancora in esecuzione: Claude Code lo lascia stare e continua a controllare. Il messaggio `300s` e quelli di configurazione restano sulla voce anche dopo il ripristino del contatto.555Questi messaggi, nella voce `/tasks` di un'attività o nella sua riga di chiusura nella trascrizione, indicano che Claude Code non riesce a raggiungere il server o l'attività. Mentre uno di essi è visibile in `/tasks`, il lavoro potrebbe essere ancora in esecuzione: Claude Code lo lascia stare e continua a controllare. I messaggi `300s` e quelli di configurazione restano sulla voce anche dopo il ripristino del contatto.
556 556
557| Messaggio | Cosa sta succedendo | Cosa puoi fare |557| Messaggio | Cosa sta succedendo | Cosa puoi fare |
558| - | - | - |558| - | - | - |
559| `reconnecting…` | Il server non ha risposto dopo una ripresa, oppure i controlli di stato non ricevono risposta | Se persiste, riconnetti da `/mcp` |559| `reconnecting…` | Il server non ha risposto dopo una ripresa, oppure i controlli di stato non ricevono risposta | Se persiste, riconnetti da `/mcp` |
560| `needs a sign-in to <server>` | Il server ha rifiutato un controllo di stato | Accedi da `/mcp` |560| `needs a sign-in to <server>` | Il server ha rifiutato un controllo di stato | Accedi da `/mcp` |
561| `status requests come back with errors; retrying…` | Il server, o un proxy davanti a esso, risponde ai controlli di stato con errori | Attendi mentre Claude Code riprova |561| `status requests come back with errors; retrying…` | Il server, o un proxy davanti a esso, risponde ai controlli di stato con errori | Attendi mentre Claude Code riprova |
562| `server '<name>' did not reconnect within 300s` | Nessun controllo con risposta per cinque minuti, ad esempio con la connessione interrotta o il server disattivato | Riconnetti da `/mcp` |562| `server '<name>' did not reconnect within 300s` | Nessun controllo con risposta per cinque minuti, ad esempio con la connessione interrotta o il server disabilitato | Riconnetti da `/mcp` |
563| `server '<name>' asked for a sign-in, and none was accepted within 300s` | Dopo cinque minuti il server richiede ancora un accesso | Accedi da `/mcp` |563| `server '<name>' asked for a sign-in, and none was accepted within 300s` | Dopo cinque minuti il server richiede ancora un accesso | Accedi da `/mcp` |
564| `status requests to server '<name>' came back with errors, and none succeeded in 300s` | Cinque minuti di risposte con errori | Controlla lo stato di salute o i log del server |564| `status requests to server '<name>' came back with errors, and none succeeded in 300s` | Cinque minuti di risposte con errori | Controlla lo stato di salute o i log del server |
565| `server '<name>' is not configured in this session; the task may still be running on it` | La sessione non ha alcun server con quel nome, ad esempio perché è stato rimosso, rinominato o escluso da `--mcp-config`, oppure un connettore claude.ai si sta ancora caricando | Ripristina il server con lo stesso nome, poi riprendi di nuovo la sessione. Per un connettore in caricamento, nulla: Claude Code segue l'attività non appena compare |565| `server '<name>' is not configured in this session; the task may still be running on it` | La sessione non ha alcun server con quel nome, ad esempio perché è stato rimosso, rinominato o escluso da `--mcp-config`, oppure un connettore claude.ai si sta ancora caricando | Ripristina il server con lo stesso nome, poi riprendi di nuovo la sessione. Per un connettore in caricamento, niente: Claude Code segue l'attività non appena compare |
566| Un messaggio che inizia con `server '<name>' was reconfigured to a different transport since this task was created` | Esiste un server con quel nome le cui impostazioni di connessione sono cambiate dall'avvio dell'attività, come URL, command, args, env, headers o timeout | Ripristina le impostazioni precedenti, poi riprendi di nuovo la sessione |566| Un messaggio che inizia con `server '<name>' was reconfigured to a different transport since this task was created` | Esiste un server con quel nome ma con impostazioni di connessione cambiate dall'avvio dell'attività, come URL, comando, argomenti, env, header o timeout | Ripristina le impostazioni precedenti, poi riprendi di nuovo la sessione |
567| `the server rejected this task's id; asking again…` | Il server dichiara di non conoscere l'ID dell'attività. Claude Code continua a chiedere per un massimo di cinque minuti | Attendi: il messaggio scompare se il server riconosce di nuovo l'ID, altrimenti segue la riga `outcome unknown.` |567| `the server rejected this task's id; asking again…` | Il server dice di non conoscere l'ID dell'attività. Claude Code continua a chiedere per un massimo di cinque minuti | Attendi: il messaggio scompare se il server riconosce di nuovo l'ID, altrimenti segue la riga `outcome unknown.` |
568| Una riga della trascrizione che termina con `outcome unknown.`, in una delle forme `expired on the server: outcome unknown.` | Il server ha rifiutato l'ID o ha risposto con un altro errore permanente, e Claude Code ha smesso di seguire l'attività | Una seconda chiamata potrebbe ripetere il lavoro. Prima di chiamare di nuovo lo strumento, scopri dal server cosa è stato fatto, ad esempio chiedendo a Claude di usare gli altri strumenti del server |568| Una riga della trascrizione che termina con `outcome unknown.`, in una forma `expired on the server: outcome unknown.` | Il server ha rifiutato l'ID o ha risposto con un altro errore permanente, e Claude Code ha smesso di seguire l'attività | Una seconda chiamata potrebbe ripetere il lavoro. Prima di chiamare di nuovo lo strumento, scopri dal server cosa è stato fatto, ad esempio chiedendo a Claude di usare gli altri strumenti del server |
569 569
570#### Limiti di tempo sulle attività MCP570#### Limiti di tempo sulle attività MCP
571 571
572Per impostazione predefinita, un'attività in background non ha alcun limite di tempo di Claude Code. I [limiti di tempo delle chiamate agli strumenti](#time-limits-on-mcp-tool-calls), inclusi il limite di tempo reale e il timeout di inattività, si applicano finché il server non risponde alla chiamata con l'attività. Se [fai attendere Claude](#make-claude-wait-for-the-result-of-an-mcp-task), si applicano per l'intera attività. I controlli di stato con risposta contano come attività ai fini del timeout di inattività.572Per impostazione predefinita, un'attività in background non ha alcun limite di tempo di Claude Code. I [limiti di tempo delle chiamate agli strumenti](#time-limits-on-mcp-tool-calls), inclusi il limite in tempo reale e il timeout di inattività, si applicano finché il server non risponde alla chiamata con l'attività. Se [fai attendere Claude](#make-claude-wait-for-the-result-of-an-mcp-task), si applicano per l'intera attività. I controlli di stato con risposta contano come attività ai fini del timeout di inattività.
573 573
574#### Far attendere a Claude il risultato di un'attività MCP574#### Far attendere Claude il risultato di un'attività MCP
575 575
576Per far attendere a Claude il risultato di un'attività in una sessione interattiva, imposta una di due variabili d'ambiente, ad esempio nel blocco `env` di [`settings.json`](https://code.claude.com/docs/it/settings):576Per far attendere a Claude il risultato di un'attività in una sessione interattiva, imposta una di due variabili d'ambiente, ad esempio nel blocco `env` di [`settings.json`](https://code.claude.com/docs/it/settings):
577 577
578* **[`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/it/env-vars) impostata su `0`**: Claude attende ogni chiamata a uno strumento MCP finché la chiamata non termina578* **[`CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS`](https://code.claude.com/docs/it/env-vars) impostata su `0`**: Claude attende ogni chiamata a uno strumento MCP fino al suo termine
579* **[`CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND`](https://code.claude.com/docs/it/env-vars) impostata su `1`**: Claude attende il risultato di un'attività. Finché lo [spostamento automatico in background](#automatic-backgrounding-of-long-tool-calls) è attivo, sposta la chiamata dopo due minuti per impostazione predefinita, così le attività brevi terminano sul posto e quelle lunghe non ti bloccano. La chiamata spostata è una normale chiamata in background anziché un'attività MCP. Non sopravvive all'uscita dalla sessione579* **[`CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND`](https://code.claude.com/docs/it/env-vars) impostata su `1`**: Claude attende il risultato di un'attività. Mentre lo [spostamento automatico in background](#automatic-backgrounding-of-long-tool-calls) è attivo, sposta la chiamata dopo due minuti per impostazione predefinita, così le attività brevi terminano sul posto e quelle lunghe non ti bloccano. La chiamata spostata è una normale chiamata in background anziché un'attività MCP. Non sopravvive all'uscita dalla sessione
580 580
581Mentre Claude attende, premere `Esc` o raggiungere il [limite di tempo reale o il timeout di inattività](#time-limits-on-mcp-tasks) termina la chiamata, e Claude Code chiede al server di annullare l'attività.581Mentre Claude attende, premere `Esc` o raggiungere il [limite in tempo reale o il timeout di inattività](#time-limits-on-mcp-tasks) termina la chiamata, e Claude Code chiede al server di annullare l'attività.
582 582
583Se imposti `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` su `1` o avvii in [modalità bare](https://code.claude.com/docs/it/headless.md#start-faster-with-bare-mode), ciò da solo non fa attendere a Claude le attività MCP. Questo esempio imposta `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` su `0`, così Claude attende ogni chiamata a uno strumento MCP:583Se imposti `CLAUDE_CODE_DISABLE_BACKGROUND_TASKS` su `1` o avvii in [modalità bare](https://code.claude.com/docs/it/headless.md#start-faster-with-bare-mode), questo da solo non fa attendere a Claude le attività MCP. Questo esempio imposta `CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS` su `0`, quindi Claude attende ogni chiamata a uno strumento MCP:
584 584
585```json settings.json theme={null}585```json settings.json theme={null}
586{586{
592 592
593### Attività MCP per gli autori di server593### Attività MCP per gli autori di server
594 594
595Se sviluppi un server MCP, puoi rispondere a un `tools/call` di lunga durata con un'attività. L'[estensione MCP tasks](https://modelcontextprotocol.io/extensions/tasks/overview) definisce i messaggi da inviare. Su una connessione con la [revisione del protocollo 2026-07-28](#mcp-client-runtimes), ogni richiesta riporta le capacità client di Claude Code in `params._meta["io.modelcontextprotocol/clientCapabilities"]`, con `"io.modelcontextprotocol/tasks": {}` sotto `extensions`. Una richiesta `tools/call` che [non può diventare un'attività](#requirements-for-mcp-tasks) omette quell'estensione.595Se sviluppi un server MCP, puoi rispondere a una `tools/call` di lunga durata con un'attività. L'[estensione MCP tasks](https://modelcontextprotocol.io/extensions/tasks/overview) definisce i messaggi che invii. Su una connessione con [revisione del protocollo 2026-07-28](#mcp-client-runtimes), ogni richiesta riporta le capacità client di Claude Code in `params._meta["io.modelcontextprotocol/clientCapabilities"]`, con `"io.modelcontextprotocol/tasks": {}` sotto `extensions`. Una richiesta `tools/call` che [non può diventare un'attività](#requirements-for-mcp-tasks) omette quell'estensione.
596 596
597#### Rispondere alla chiamata con un'attività597#### Rispondere alla chiamata con un'attività
598 598
599Rispondi con un'attività solo quando la richiesta contiene l'estensione, altrimenti la chiamata fallisce con l'errore dello strumento `Unsupported result type 'task' for tools/call`. La chiamata fallisce allo stesso modo se la tua risposta non ha un `taskId` o uno `status` valido. L'oggetto attività è il `result` JSON-RPC della tua risposta a `tools/call`, non ha bisogno di un array `content` e qui include i campi opzionali `statusMessage` e `pollIntervalMs`:599Rispondi con un'attività solo quando la richiesta riporta l'estensione, altrimenti la chiamata fallisce con l'errore dello strumento `Unsupported result type 'task' for tools/call`. La chiamata fallisce allo stesso modo se la tua risposta non ha un `taskId` o uno `status` valido. L'oggetto attività è il `result` JSON-RPC della tua risposta `tools/call`, non richiede un array `content` e qui include i campi facoltativi `statusMessage` e `pollIntervalMs`:
600 600
601```json theme={null}601```json theme={null}
602{602{
613 613
614| Campo | Come lo gestisce Claude Code |614| Campo | Come lo gestisce Claude Code |
615| - | - |615| - | - |
616| `resultType` | Impostalo su `"task"` per contrassegnare la risposta come attività. Senza di esso, Claude Code interpreta la risposta come un risultato normale |616| `resultType` | Impostalo su `"task"` per contrassegnare la risposta come attività. Senza di esso, Claude Code interpreta la risposta come un normale risultato |
617| `taskId` | Obbligatorio. Al massimo 128 caratteri ASCII stampabili senza spazi, altrimenti Claude riceve un errore dello strumento che inizia con `MCP server "<name>" returned a malformed task handle for tool "<tool>"`. Mantieni l'ID interrogabile tra connessioni diverse, perché dopo una ripresa Claude Code lo richiede su una nuova connessione |617| `taskId` | Obbligatorio. Al massimo 128 caratteri ASCII stampabili senza spazi, altrimenti Claude riceve un errore dello strumento che inizia con `MCP server "<name>" returned a malformed task handle for tool "<tool>"`. Mantieni l'ID interrogabile tra connessioni diverse, perché dopo una ripresa Claude Code lo chiede su una nuova connessione |
618| `status` | Obbligatorio. Uno tra `working`, `input_required`, `completed`, `failed` o `cancelled`. Un altro valore produce l'errore `Unsupported result type` |618| `status` | Obbligatorio. Uno tra `working`, `input_required`, `completed`, `failed` o `cancelled`. Un altro valore produce l'errore `Unsupported result type` |
619| `createdAt`, `lastUpdatedAt`, `ttlMs` | Richiesti dall'estensione tasks, e `ttlMs` può essere `null`. Claude Code non scarta un'attività perché il suo `ttlMs` è trascorso |619| `createdAt`, `lastUpdatedAt`, `ttlMs` | Richiesti dall'estensione tasks, e `ttlMs` può essere `null`. Claude Code non scarta un'attività perché il suo `ttlMs` è trascorso |
620| `pollIntervalMs` | Opzionale. Millisecondi tra le richieste `tasks/get`, limitati tra 250 e 30000. Claude Code usa 2000 quando il campo è assente o `null`, e rilegge il valore da ogni risposta a `tasks/get` |620| `pollIntervalMs` | Facoltativo. Millisecondi tra le richieste `tasks/get`, limitati a un valore tra 250 e 30000. Claude Code usa 2000 quando il campo è assente o `null`, e rilegge il valore da ogni risposta `tasks/get` |
621| `statusMessage` | Facoltativo. `/tasks` mostra il valore della tua ultima risposta `tasks/get`, non di questa prima, e una risposta che omette il campo lo cancella. Un [messaggio di stato di Claude Code](#status-messages-on-an-mcp-task) può prenderne il posto |621| `statusMessage` | Facoltativo. `/tasks` mostra il valore della tua ultima risposta `tasks/get`, non di questa prima, e una risposta che omette il campo lo cancella. Un [messaggio di stato di Claude Code](#status-messages-on-an-mcp-task) può prenderne il posto |
622 622
623Claude Code accetta una risposta con attività che omette `createdAt`, `lastUpdatedAt` o `ttlMs`, oppure che imposta `pollIntervalMs` su `null`. Prima della v2.1.317, la chiamata falliva invece con l'errore `Unsupported result type`. Per funzionare anche con quelle versioni, invia i tre campi richiesti dall'estensione tasks, e invia `pollIntervalMs` come numero oppure non inviarlo affatto.623Claude Code accetta una risposta con attività che omette `createdAt`, `lastUpdatedAt` o `ttlMs`, o che imposta `pollIntervalMs` su `null`. Prima della v2.1.317, la chiamata falliva invece con l'errore `Unsupported result type`. Per funzionare anche con quelle versioni, invia i tre campi richiesti dall'estensione tasks, e invia `pollIntervalMs` come numero oppure non inviarlo affatto.
624 624
625Su un server HTTP o connettore claude.ai, la risposta con l'attività deve iniziare entro il [timer per richiesta](#time-limits-on-mcp-tool-calls), quindi accetta il lavoro e rispondi per prima cosa, poi esegui il lavoro.625Su un server HTTP o connettore claude.ai, la risposta con l'attività deve iniziare entro il [timer per richiesta](#time-limits-on-mcp-tool-calls), quindi accetta il lavoro e rispondi prima, poi esegui il lavoro.
626 626
627#### Riportare stato, risultati e domande627#### Riportare stato, risultati e domande
628 628
629Subito dopo la risposta con l'attività, Claude Code invia `tasks/get` con `{ "taskId": ... }`, poi lo ripete una volta per intervallo di polling. L'estensione tasks richiede che la tua risposta riporti `"resultType": "complete"` insieme a `taskId`, `status`, `createdAt`, `lastUpdatedAt` e `ttlMs`. `ttlMs` può essere `null`, e `statusMessage` e `pollIntervalMs` sono facoltativi. Questo esempio riporta la build come completata:629Subito dopo la risposta con l'attività, Claude Code invia `tasks/get` con `{ "taskId": ... }`, poi lo ripete a ogni intervallo di polling. L'estensione tasks richiede che la tua risposta contenga `"resultType": "complete"` insieme a `taskId`, `status`, `createdAt`, `lastUpdatedAt` e `ttlMs`. `ttlMs` può essere `null`, e `statusMessage` e `pollIntervalMs` sono facoltativi. Questo esempio riporta la build come completata:
630 630
631```json theme={null}631```json theme={null}
632{632{
645| Stato, metodo o risposta | Come lo gestisce Claude Code |645| Stato, metodo o risposta | Come lo gestisce Claude Code |
646| - | - |646| - | - |
647| `working` | Continua il polling |647| `working` | Continua il polling |
648| `completed` | Fornisce a Claude il normale risultato di `tools/call` nell'oggetto `result` di primo livello. Un `isError: true` al suo interno viene riportato come errore |648| `completed` | Fornisce a Claude il normale risultato di `tools/call` nell'oggetto `result` di primo livello. `isError: true` al suo interno viene riportato come errore |
649| `failed` | Comunica a Claude il `message` dell'oggetto `error` di primo livello `{ code, message, data }`, che l'estensione tasks richiede su un'attività fallita. Senza quel `message`, Claude riceve invece `statusMessage`, oppure `Task failed` |649| `failed` | Comunica a Claude il `message` dell'oggetto `error` di primo livello `{ code, message, data }`, che l'estensione tasks richiede su un'attività fallita. Senza quel `message`, Claude riceve invece `statusMessage`, oppure `Task failed` |
650| `cancelled` | Comunica a Claude `statusMessage`, oppure `Task was cancelled by the server` |650| `cancelled` | Comunica a Claude `statusMessage`, oppure `Task was cancelled by the server` |
651| `input_required` | Legge `inputRequests`, un oggetto che associa una chiave a tua scelta a `{ method, params }`. Claude Code risponde a ogni chiave una volta tramite `tasks/update` con `{ taskId, inputResponses }`, dove `inputResponses` associa la stessa chiave al risultato di quella richiesta. Le chiavi oltre le 16 per attività vengono ignorate |651| `input_required` | Legge `inputRequests`, un oggetto che associa una chiave a tua scelta a `{ method, params }`. Claude Code risponde a ogni chiave una sola volta tramite `tasks/update` con `{ taskId, inputResponses }`, dove `inputResponses` associa la stessa chiave al risultato di quella richiesta. Le chiavi oltre le 16 per attività vengono ignorate |
652| Metodi in `inputRequests` | `elicitation/create` viene servito solo nelle sessioni interattive del terminale, e `roots/list` ovunque. Quando Claude Code non può servire una richiesta, chiede al server di annullare l'attività |652| Metodi in `inputRequests` | `elicitation/create` viene servito solo nelle sessioni di terminale interattive, e `roots/list` ovunque. Quando Claude Code non può servire una richiesta, chiede al server di annullare l'attività |
653| Un altro valore di `status` | Claude Code chiede al server di annullare l'attività e la riporta a Claude come fallita |653| Un altro valore di `status` | Claude Code chiede al server di annullare l'attività e la riporta a Claude come fallita |
654| Errore JSON-RPC `-32602` | Interpretato come ID di attività sconosciuto. Per un'attività in background, Claude Code continua a chiedere per un massimo di cinque minuti, poi riporta a Claude l'esito come sconosciuto |654| Errore JSON-RPC `-32602` | Interpretato come ID dell'attività sconosciuto. Per un'attività in background, Claude Code continua a chiedere per un massimo di cinque minuti, poi riporta a Claude l'esito come sconosciuto |
655| `tasks/cancel` | Inviato, ad esempio, quando Claude o la persona arresta l'attività mentre il server è connesso. Non viene inviato all'uscita |655| `tasks/cancel` | Inviato, ad esempio, quando Claude o la persona arresta l'attività mentre il server è connesso. Non inviato all'uscita |
656| `tasks/result`, `tasks/list`, `notifications/tasks` | Non utilizzati, quindi inserisci l'esito nelle tue risposte `tasks/get` |656| `tasks/result`, `tasks/list`, `notifications/tasks` | Non usati, quindi inserisci l'esito nelle tue risposte `tasks/get` |
657 657
658### Server MCP forniti dai plugin658### Server MCP forniti dai plugin
659 659
661 661
662**Come funzionano i server MCP dei plugin**:662**Come funzionano i server MCP dei plugin**:
663 663
664* I plugin definiscono i server MCP in `.mcp.json` nella radice del plugin o inline in `plugin.json`664* I plugin definiscono i server MCP in `.mcp.json` nella root del plugin oppure inline in `plugin.json`
665* Quando abiliti un plugin, Claude Code avvia automaticamente i suoi server MCP665* Quando abiliti un plugin, Claude Code avvia automaticamente i suoi server MCP
666* Claude Code offre gli strumenti MCP dei plugin insieme agli strumenti MCP configurati manualmente666* Claude Code offre gli strumenti MCP dei plugin insieme agli strumenti MCP configurati manualmente
667* Aggiungi e rimuovi i server dei plugin installando o disinstallando il plugin, non con i comandi `/mcp`. Puoi comunque [disattivare un server di un plugin installato](#disable-a-server-without-removing-it) in `/mcp`, il che impedisce a Claude Code di connettersi a esso senza rimuovere il plugin667* Aggiungi e rimuovi i server dei plugin installando o disinstallando il plugin, non con i comandi `/mcp`. Puoi comunque [disattivare il server di un plugin installato](#disable-a-server-without-removing-it) in `/mcp`, il che impedisce a Claude Code di connettersi a esso senza rimuovere il plugin
668 668
669**Esempio di configurazione MCP di un plugin**:669**Esempio di configurazione MCP di un plugin**:
670 670
671In `.mcp.json` nella radice del plugin:671In `.mcp.json` nella root del plugin:
672 672
673```json theme={null}673```json theme={null}
674{674{
701**Funzionalità MCP dei plugin**:701**Funzionalità MCP dei plugin**:
702 702
703* **Ciclo di vita automatico**: i server si connettono e si disconnettono in questi momenti:703* **Ciclo di vita automatico**: i server si connettono e si disconnettono in questi momenti:
704 * All'avvio della sessione, Claude Code connette automaticamente i server dei plugin abilitati. In `/mcp`, un server di plugin remoto (HTTP o SSE) che hai già usato può invece mostrare lo [stato `cached`](#server-status-detail); Claude Code lo connette quando Claude chiama per la prima volta uno dei suoi strumenti. Quando la connessione di un server stdio di un plugin è fallita meno di 15 minuti prima, Claude Code [salta la connessione](https://code.claude.com/docs/it/errors.md#skipping-connection-recent-failure-cached)704 * All'avvio della sessione, Claude Code connette automaticamente i server dei plugin abilitati. In `/mcp`, un server remoto (HTTP o SSE) di un plugin che hai già usato in precedenza può invece mostrare lo [stato `cached`](#server-status-detail); Claude Code lo connette quando Claude chiama per la prima volta uno dei suoi strumenti. Quando la connessione di un server stdio di un plugin è fallita meno di 15 minuti prima, Claude Code [salta la connessione](https://code.claude.com/docs/it/errors.md#skipping-connection-recent-failure-cached)
705 * Se abiliti o disabiliti un plugin durante una sessione, Claude Code connette o disconnette i suoi server MCP quando la modifica viene applicata. [Applicare le modifiche ai plugin senza riavviare](https://code.claude.com/docs/it/plugins/cli-reference.md#reload-plugins) descrive quando ciò avviene. In una sessione senza terminale interattivo, `/reload-plugins` non connette né disconnette i server MCP dei plugin; queste modifiche hanno effetto nella sessione successiva705 * Se abiliti o disabiliti un plugin durante una sessione, Claude Code connette o disconnette i suoi server MCP quando la modifica viene applicata. [Applicare le modifiche ai plugin senza riavviare](https://code.claude.com/docs/it/plugins/cli-reference.md#reload-plugins) descrive quando ciò avviene. In una sessione senza un terminale interattivo, `/reload-plugins` non connette né disconnette i server MCP dei plugin; queste modifiche hanno effetto nella sessione successiva
706 * Quando ricarichi, Claude Code mantiene le connessioni attive dei server dei plugin la cui configurazione non è cambiata, e fa lo stesso quando [sostituisci l'elenco dei server MCP della sessione](https://code.claude.com/docs/it/agent-sdk/typescript.md#mcpsetserversresult) dall'Agent SDK senza indicarli706 * Quando ricarichi, Claude Code mantiene le connessioni attive dei server dei plugin la cui configurazione non è cambiata, e fa lo stesso quando [sostituisci l'elenco dei server MCP della sessione](https://code.claude.com/docs/it/agent-sdk/typescript.md#mcpsetserversresult) dall'Agent SDK senza nominarli
707 * Quando [sposti la sessione con `/cd`](https://code.claude.com/docs/it/permissions#move-the-session-to-another-directory) su v2.1.246 o successiva, Claude Code connette i server dei plugin abilitati dalle impostazioni della nuova directory e disconnette i server dei plugin che non sono più abilitati, quindi non devi eseguire `/reload-plugins` dopo lo spostamento707 * Quando [sposti la sessione con `/cd`](https://code.claude.com/docs/it/permissions#move-the-session-to-another-directory) nella v2.1.246 o successiva, Claude Code connette i server dei plugin abilitati dalle impostazioni della nuova directory e disconnette i server dei plugin che non sono più abilitati, quindi non devi eseguire `/reload-plugins` dopo lo spostamento
708 * Nelle [sessioni cloud](https://code.claude.com/docs/it/claude-code-on-the-web.md), una chiamata MCP a un server di plugin non ancora connesso, ad esempio subito dopo il risveglio di una sessione inattiva, avvia il server su richiesta e attende che si connetta708 * Nelle [sessioni cloud](https://code.claude.com/docs/it/claude-code-on-the-web.md), una chiamata MCP a un server di un plugin non ancora connesso, ad esempio subito dopo il risveglio di una sessione inattiva, avvia il server su richiesta e attende che si connetta
709* **Segnaposto di percorso**: `${CLAUDE_PLUGIN_ROOT}` viene risolto nella directory di installazione del plugin, `${CLAUDE_PLUGIN_DATA}` nella sua directory di [stato persistente](https://code.claude.com/docs/it/plugins/components.md#path-variables-and-persistent-data) e `${CLAUDE_PROJECT_DIR}` nella radice stabile del progetto. La sostituzione si applica a:709* **Segnaposto per i percorsi**: `${CLAUDE_PLUGIN_ROOT}` viene risolto nella directory di installazione del plugin, `${CLAUDE_PLUGIN_DATA}` nella sua directory di [stato persistente](https://code.claude.com/docs/it/plugins/components.md#path-variables-and-persistent-data) e `${CLAUDE_PROJECT_DIR}` nella root stabile del progetto. La sostituzione si applica a:
710 * server `stdio`: `command`, `args`, `env`710 * server `stdio`: `command`, `args`, `env`
711 * server `http`, `sse` e `ws`: `url`, `headers` e `headersHelper`711 * server `http`, `sse` e `ws`: `url`, `headers` e `headersHelper`
712* **Accesso all'ambiente utente**: accesso alle stesse variabili d'ambiente dei server configurati manualmente712* **Accesso all'ambiente dell'utente**: accesso alle stesse variabili d'ambiente dei server configurati manualmente
713* **Più tipi di trasporto**: supporto per i trasporti stdio, SSE, HTTP e WebSocket, anche se il supporto dei trasporti può variare in base al server713* **Più tipi di trasporto**: supporto per i trasporti stdio, SSE, HTTP e WebSocket, anche se il supporto dei trasporti può variare a seconda del server
714 714
715I server dei plugin compaiono in `/mcp` con indicatori che mostrano che provengono da plugin.715I server dei plugin compaiono in `/mcp` con indicatori che mostrano che provengono da plugin.
716 716
717`claude mcp get` nasconde i valori configurati per il server stdio o WebSocket di un plugin, perché possono contenere credenziali:717`claude mcp get` nasconde i valori configurati per il server stdio o WebSocket di un plugin, perché possono contenere credenziali:
718 718
719* **Server stdio**: stampa `Command: stdio`, una riga `Args:` vuota e ogni variabile d'ambiente come `NAME=[REDACTED]`719* **server stdio**: stampa `Command: stdio`, una riga `Args:` vuota e ogni variabile d'ambiente come `NAME=[REDACTED]`
720* **Server WebSocket**: stampa `URL: ws` e ogni header come `<name>: [REDACTED]`, e `claude mcp list` mostra `ws` al posto dell'URL720* **server WebSocket**: stampa `URL: ws` e ogni header come `<name>: [REDACTED]`, e `claude mcp list` mostra `ws` al posto dell'URL
721 721
722Per vedere cosa ha configurato il plugin, [trova il plugin sul disco](https://code.claude.com/docs/it/plugins/loading.md#find-plugins-on-disk) e leggi il suo `.mcp.json` o `plugin.json`.722Per vedere cosa ha configurato il plugin, [trova il plugin su disco](https://code.claude.com/docs/it/plugins/loading.md#find-plugins-on-disk) e leggi il suo `.mcp.json` o `plugin.json`.
723 723
724**Nomi degli strumenti MCP dei plugin**:724**Nomi degli strumenti MCP dei plugin**:
725 725
726Gli strumenti di un server MCP incluso in un plugin contengono sia il nome del plugin sia 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` incluso in un plugin chiamato `my-plugin`, uno strumento `query` è richiamabile come:726Gli strumenti di un server MCP incluso in un plugin contengono nel loro nome richiamabile sia il nome del plugin sia la chiave del server. 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` incluso in un plugin chiamato `my-plugin`, uno strumento `query` è richiamabile come:
727 727
728```728```
729mcp__plugin_my-plugin_database-tools__query729mcp__plugin_my-plugin_database-tools__query
730```730```
731 731
732Usa questo nome completo quando fai riferimento allo strumento nelle [regole di permesso](https://code.claude.com/docs/it/permissions.md), nell'elenco `allowed-tools` di una skill, nel [campo `tools` di un subagent](https://code.claude.com/docs/it/sub-agents#available-tools) o in un [matcher di hook](https://code.claude.com/docs/it/hooks.md#match-mcp-tools). Un matcher di hook scritto sulla semplice chiave del server, come `mcp__database-tools__.*`, non si attiva mai per un server incluso in un plugin.732Usa questo nome completo quando fai riferimento allo strumento nelle [regole di permesso](https://code.claude.com/docs/it/permissions.md), nell'elenco `allowed-tools` di una skill, nel [campo `tools` di un subagent](https://code.claude.com/docs/it/sub-agents#available-tools) o in un [matcher di un hook](https://code.claude.com/docs/it/hooks.md#match-mcp-tools). Un matcher di un hook scritto sulla sola chiave del server, come `mcp__database-tools__.*`, non si attiva mai per un server incluso in un plugin.
733 733
734Il server stesso viene registrato con il nome qualificato `plugin:<plugin-name>:<server-name>`, come `plugin:my-plugin:database-tools`. Usa quel nome dove è previsto il nome di un server configurato, come nel [campo `server` di un hook `mcp_tool`](https://code.claude.com/docs/it/hooks#mcp-tool-hook-fields).734Il server stesso viene registrato con il nome con ambito `plugin:<plugin-name>:<server-name>`, ad esempio `plugin:my-plugin:database-tools`. Usa questo nome dove è previsto il nome di un server configurato, come nel [campo `server` di un hook `mcp_tool`](https://code.claude.com/docs/it/hooks#mcp-tool-hook-fields).
735 735
736Consulta il [riferimento dei componenti dei plugin](https://code.claude.com/docs/it/plugins/components.md#mcp-servers) per i dettagli sull'inclusione di server MCP nei plugin.736Consulta il [riferimento ai componenti dei plugin](https://code.claude.com/docs/it/plugins/components.md#mcp-servers) per i dettagli su come includere server MCP nei plugin.
737 737
738## Ambiti di installazione MCP738## Ambiti di installazione MCP
739 739
1800* **Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 e successivi**: la ricerca di strumenti è attiva per impostazione predefinita, come su Anthropic API.1800* **Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 e successivi**: la ricerca di strumenti è attiva per impostazione predefinita, come su Anthropic API.
1801* **Modelli precedenti di Agent Platform**: Claude Code carica tutti gli strumenti MCP in anticipo, perché i loro stack di servizio rifiutano l'intestazione beta richiesta. `ENABLE_TOOL_SEARCH=true` non sovrascrive questo comportamento.1801* **Modelli precedenti di Agent Platform**: Claude Code carica tutti gli strumenti MCP in anticipo, perché i loro stack di servizio rifiutano l'intestazione beta richiesta. `ENABLE_TOOL_SEARCH=true` non sovrascrive questo comportamento.
1802 1802
1803Prima della v2.1.221, Claude Code disabilitava la ricerca di strumenti per tutti i modelli su Google Cloud's Agent Platform a meno che non impostassi `ENABLE_TOOL_SEARCH=true`.
1804
1805Controlla il comportamento della ricerca di strumenti con la variabile d'ambiente `ENABLE_TOOL_SEARCH`:1803Controlla il comportamento della ricerca di strumenti con la variabile d'ambiente `ENABLE_TOOL_SEARCH`:
1806 1804
1807| Valore | Comportamento |1805| Valore | Comportamento |
