Connetti Claude Code ai tuoi strumenti tramite MCP

Scopri come connettere Claude Code ai tuoi strumenti con il Model Context Protocol.

Claude Code può connettersi a centinaia di strumenti e fonti di dati esterni attraverso il Model Context Protocol (MCP), uno standard open source per le integrazioni AI-tool. I server MCP danno a Claude Code accesso ai tuoi strumenti, database e API.

Connetti un server quando ti trovi a copiare dati in chat da un altro strumento, come un issue tracker o un dashboard di monitoraggio. Una volta connesso, Claude può leggere e agire su quel sistema direttamente invece di lavorare da quello che incolla.

Se stai connettendo il tuo primo server, inizia con la guida rapida MCP per una procedura dettagliata. Questa pagina è il riferimento completo.

Cosa puoi fare con MCP

Con i server MCP connessi, puoi chiedere a Claude Code di:

• Implementare funzionalità da issue tracker: "Aggiungi la funzionalità descritta nel ticket JIRA ENG-4521 e crea una PR su GitHub."
• Analizzare dati di monitoraggio: "Controlla Sentry e Statsig per verificare l'utilizzo della funzionalità descritta in ENG-4521."
• Interrogare database: "Trova gli indirizzi email di 10 utenti casuali che hanno utilizzato la funzionalità ENG-4521, in base al nostro database PostgreSQL."
• Integrare design: "Aggiorna il nostro modello di email standard in base ai nuovi design Figma che sono stati pubblicati su Slack"
• Automatizzare flussi di lavoro: "Crea bozze Gmail invitando questi 10 utenti a una sessione di feedback sulla nuova funzionalità."
• Reagire a eventi esterni: Un server MCP può anche agire come un canale che invia messaggi nella tua sessione, in modo che Claude reagisca ai messaggi Telegram, chat Discord o eventi webhook mentre sei assente.

Trovare e costruire server MCP

Sfoglia i connettori verificati nella Anthropic Directory. I connettori della Directory utilizzano la stessa infrastruttura MCP di Claude Code, quindi puoi aggiungere qualsiasi server remoto elencato lì con claude mcp add.

[!WARNING]

Verifica di fidarti di ogni server prima di collegarlo. I server che recuperano contenuti esterni possono esporti al rischio di prompt injection.

Per costruire il tuo server, consulta la guida al server MCP per i fondamenti del protocollo e la documentazione sulla creazione di connettori Claude per l'autenticazione, i test e l'invio alla Directory.

Puoi anche far scaffoldare un server da Claude con il plugin ufficiale mcp-server-dev.

1. Installa il plugin

Nell'estensione VS Code o nell'app desktop, segui Installare un plugin invece di questo passaggio. In un terminale, avvia Claude Code eseguendo claude, quindi inserisci questo al suo prompt:

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

Se l'installazione non riesce, fai corrispondere il messaggio che Claude Code segnala:

• Marketplace "claude-plugins-official" not found: aggiungi il marketplace con /plugin marketplace add anthropics/claude-plugins-official, quindi riprova l'installazione.
• Plugin "<name>" not found in marketplace "claude-plugins-official": la tua copia locale del catalogo del marketplace potrebbe non essere aggiornata. Aggiornala con /plugin marketplace update claude-plugins-official, quindi riprova l'installazione. Se il nuovo tentativo mostra lo stesso messaggio, consulta Plugin not found in marketplace.

Se il riepilogo dell'installazione segnala Run /reload-plugins to apply., Claude Code esegue quindi quel ricaricamento per te. Se il ricaricamento avverte che il tuo prossimo messaggio rileggerebbe la conversazione, esegui /reload-plugins --force.

2. Esegui la skill di creazione

/mcp-server-dev:build-mcp-server

Claude ti chiede informazioni sul tuo caso d'uso e scaffolda un server HTTP remoto o un server stdio locale.

Installazione dei server MCP

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

Opzione 1: aggiungere un server HTTP remoto

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

# Basic syntax
claude mcp add --transport http <name> <url>

# Real example: Connect to Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# Example with Bearer token
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

Quando 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.

Una 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.

Solo un'applicazione host dell'SDK, come un'applicazione Agent SDK o l'app desktop, 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.

[!NOTE]

Nelle esecuzioni con --output-format stream-json, Claude Code segnala anche una voce --mcp-config saltata nel campo mcp_server_errors dell'evento system/init, così gli script possono rilevare che il server non è mai stato caricato.

Opzione 2: aggiungere un server SSE remoto

[!WARNING]

Il trasporto SSE (Server-Sent Events) è deprecato. Usa invece i server HTTP, dove disponibili.

Alcuni servizi espongono ancora solo un endpoint SSE. Aggiungili con lo stesso comando claude mcp add --transport http <name> <url> usato per un server HTTP. 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.

Su una versione precedente, o per connetterti direttamente tramite SSE, passa invece --transport sse:

# Basic syntax
claude mcp add --transport sse <name> <url>

# Real example: Connect to Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Example with authentication header
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

Opzione 3: aggiungere un server stdio locale

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

Claude 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.

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 che hai concesso con --add-dir, /add-dir o l'impostazione additionalDirectories. Claude Code invia notifications/roots/list_changed quando quell'insieme cambia.

Questa 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.

# Basic syntax
claude mcp add [options] <name> -- <command> [args...]

# Real example: Add Airtable server
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

[!NOTE]

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.

Ad esempio:

• claude mcp add --transport stdio myserver -- npx server → esegue npx server
• 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

Senza --, Claude Code cercherebbe di interpretare i flag del server, come --port qui sopra, come proprie opzioni.

--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.

Come Claude Code arresta un server stdio

Quando 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:

• 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.
• 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.

Prima della v2.1.296, Claude Code su Windows terminava subito l'albero dei processi del server, senza prima chiudere lo stdin né attendere.

Opzione 4: aggiungere un server WebSocket remoto

I 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.

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

claude mcp add-json events-server \
  '{"type":"ws","url":"wss://mcp.example.com/socket","headers":{"Authorization":"Bearer YOUR_TOKEN"}}'

La 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. Il flag claude mcp add --transport non accetta ws.

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

I 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:

• Un URL come https://mcp.example.com/mcp: il server è remoto.
• Un comando di avvio come npx -y @example/mcp-server: il server viene eseguito sulla tua macchina.
• Un blocco JSON mcpServers: configurazione scritta per il file di impostazioni di un altro client.

Ciascuno è uno degli input accettati dalle quattro opzioni in Installazione dei server MCP. Trova qui sotto la forma che hai per trasformarla nel comando che Claude Code accetta. Ogni comando scrive nell'ambito locale a meno che tu non aggiunga --scope project o --scope user.

Aggiungere un server da un URL

Un URL significa che il server è remoto. Per un endpoint https://, aggiungilo con --transport http, oppure segui l'Opzione 2 quando le istruzioni indicano che l'endpoint usa SSE. Per un endpoint wss://, usa invece l'Opzione 4, poiché --transport non accetta ws:

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

Se le istruzioni forniscono anche una chiave API o un header con un token, passalo con --header come mostrato nell'Opzione 1.

Aggiungere un server da un comando npx, uvx o binario

Un 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 --:

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

L'Opzione 3 tratta in modo completo il separatore --.

Aggiungere un server da un blocco JSON mcpServers

Un 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:

• 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.
• 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.

Ad esempio, questo blocco:

{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@example/mcp-server"]
    }
  }
}

diventa questo comando:

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

Aggiungere server MCP da una configurazione JSON 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 spiega come Claude Code carica e approva quel file.

Ogni 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 descrive gli stati che mostra e il passaggio di approvazione per i server di .mcp.json.

Gestire i tuoi server

Una volta configurati, puoi gestire i tuoi server MCP con questi comandi:

# List all configured servers
claude mcp list

# Get details for a specific server
claude mcp get notion

# Remove a server
claude mcp remove notion

# (within Claude Code) Check server status
/mcp

Quando rimuovi un server remoto, Claude Code elimina anche i token OAuth e la registrazione del client che aveva memorizzato per quel server. Claude Code non revoca i token presso il server di autorizzazione che li ha emessi. Per revocare i token dove il server di autorizzazione supporta la revoca, esegui claude mcp logout <name> nella tua shell prima di claude mcp remove <name>.

Stato del server

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; per un messaggio may not have been saved, consulta MCP server may not have been saved or removed.

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.

Gli stati in questo elenco riportano una decisione di configurazione anziché un tentativo di connessione, quindi Claude Code li stampa senza connettersi al server:

• ⏸ 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.
• ✘ Rejected (see disabledMcpjsonServers in settings): un server di .mcp.json rifiutato da una voce disabledMcpjsonServers. Claude Code lo mostra solo in claude mcp get <name>.
• ⊘ Disabled for this project (re-enable via /mcp): un server indicato nell'elenco disabledMcpServers del progetto. Claude Code lo mostra sia in claude mcp list sia in claude mcp get <name>. Riattiva il server dal pannello /mcp.
• ✘ 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 è nascosto in entrambi i comandi anziché essere mostrato con questo stato. Chiedi al tuo amministratore quale policy blocca il server.

Approvazioni dei server di progetto e attendibilità del workspace

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 o 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.

Le approvazioni provenienti da queste fonti si applicano comunque in una cartella non attendibile:

• il tuo ~/.claude/settings.json utente
• le impostazioni gestite
• le impostazioni passate con --settings

Claude 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. 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. 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.

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

Dettagli dello stato del server

In /mcp, incluso il menu di un server al suo interno, e nel gestore /plugin, 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.

La 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 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.

Quando 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.

Errori di connessione e server non configurati

Quando 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:.

Claude 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.

Quando 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.

• Il percorso e la query non compaiono mai in quel messaggio.
• Per un server nell'ambito 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.
• Per un errore senza stato o codice di errore, Claude Code mostra il testo dell'errore senza l'origine.

Un server remoto la cui configurazione ha un url vuoto appare come not configured in /mcp, in claude mcp list e nel gestore /plugin, 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.

Avvisi di configurazione

Claude Code avvisa dei problemi di configurazione elencati di seguito. Ogni voce indica cosa controlla Claude Code e come eliminare l'avviso:

• 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.
• Stesso nome in più ambiti: se definisci lo stesso nome di server in più ambiti 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} non espansi, quindi non mostra mai un valore risolto come una chiave API.
• 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.
• Variabile d'ambiente mancante: se un riferimento ${VAR} 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, senza alcun avviso.

Disponibilità degli strumenti

Il pannello /mcp mostra il numero di strumenti accanto a ogni server connesso e segnala i server che dichiarano la capacità tools ma non espongono alcuno strumento.

Numero di strumenti in una sessione cloud

In una sessione cloud, un conteggio come 3 of 13 tools available significa che Claude non può usare gli altri 10. Verifica queste cause, tra le altre:

• Una regola di negazione nel file .claude/settings.json del tuo repository indica lo strumento o il suo intero server: rimuovi la regola, se la tua sessione legge quel file
• Il nome completo dello strumento supera i 128 caratteri: segui i passaggi per un nome troppo lungo
• Il server elenca lo strumento per la propria interfaccia e non per Claude: se gestisci il server, aggiungi model a _meta.ui.visibility dello strumento per renderlo disponibile a Claude. Altrimenti, non c'è nulla da correggere.

Strumenti di un server ancora in fase di connessione

Se 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:

• Con la ricerca degli strumenti, l'impostazione predefinita: l'attesa avviene all'interno della chiamata ToolSearch.
• 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.
• Su un deploy Microsoft Foundry ospitato su Azure: 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, gli strumenti di un server che completa la connessione diventano disponibili alla richiesta successiva di Claude.

Con 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.

Dopo 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, la chiamata fallisce con l'errore dello strumento No such tool available.

Disabilitare un server senza rimuoverlo

Disattiva 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.

Quando 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:

• 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, i connettori claude.ai che Claude Code recupera autonomamente 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, Claude Code lo scrive in questo elenco con il suo nome visualizzato, ad esempio claude.ai Slack.
• 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.

Claude 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.

disabledMcpServers e enabledMcpServers non hanno relazione con enabledMcpjsonServers e disabledMcpjsonServers, che controllano l'approvazione dei server definiti nel file .mcp.json di un progetto.

Runtime dei client MCP

Claude 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, 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.

Claude Code sceglie un runtime ogni volta che lo avvii e lo mantiene fino all'uscita. Nelle sessioni in cui recupera i feature flag, usa il runtime v2 su Claude Code v2.1.232 o successivo.

Nelle 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:

• 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
• Sessioni con accesso tramite un gateway delle app Claude
• Sessioni in cui disattivi la telemetria o il recupero dei feature flag, ad esempio con DISABLE_TELEMETRY

Con v2, Claude Code inoltre:

• 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. Claude Code si connette a tutti gli altri server come fa v1.
• Riceve le notifiche list_changed dai server sulla revisione più recente tramite uno stream che mantiene aperto.
• Non registra un server di canale che si connette sulla revisione più recente, perché quella revisione non può trasportare messaggi di canale.
• Fa fallire un accesso MCP OAuth la cui risposta di autorizzazione indica un emittente inatteso.
• Invia le credenziali MCP OAuth 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.

Anthropic 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 su v1 o v2.

Per decidere se Claude Code chiede ai server della revisione più recente, imposta MCP_PROTOCOL_NEGOTIATION 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.

Aggiornamenti dinamici degli strumenti

Un 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:

• In una sessione di terminale interattiva, Claude Code recupera l'elenco aggiornato da quel server, quindi non devi riconnetterlo.
• In modalità non interattiva con il flag -p e nell'Agent SDK, Claude Code aggiorna solo l'elenco degli strumenti con queste notifiche.

Se 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.

Stream di notifiche sul runtime v2

Sul runtime v2, 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:

• Lo stream si richiude entro 10 secondi: Claude Code lo riapre fino a tre volte, poi si ferma per quella connessione.
• 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.

Finché 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.

Riconnessione automatica

Claude 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.

Cadute di un server remoto durante la sessione

Claude 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:

• 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.
• Nelle esecuzioni claude -p e nelle sessioni Agent SDK: 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:
  • 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 failed, e il tuo codice può riconnettere il server. Per riconnetterlo in claude -p, avvia di nuovo l'esecuzione.
  • Quando il server richiede di accedere di nuovo: Claude Code smette di riprovare, e una sessione Agent SDK riporta lo stato del server come needs-auth. Accedi con claude mcp login <name> nella tua shell. Poi avvia di nuovo l'esecuzione oppure, in una sessione Agent SDK, riconnetti invece il server.

Prime connessioni fallite

Quando 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.

Questi nuovi tentativi non si applicano in questi casi:

• La prima connessione di un server stdio. Per riprovarla, consulta Server stdio che terminano o non si avviano
• La prima connessione di un server WebSocket. Per riprovarla in una sessione di terminale interattiva, seleziona Reconnect dal menu del server in /mcp
• Un errore di autenticazione o di risorsa non trovata, perché richiede una modifica della configurazione per essere risolto. Quando un headersHelper è 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

Server stdio che terminano o non si avviano

Per 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.

Richieste di discovery fallite

Dopo 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.

Riprovare tu stesso i server in errore

Per 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.

Come Claude viene a sapere che un server è in errore

Se Claude Code comunica a Claude che un server configurato non è riuscito a connettersi dipende dalla ricerca degli strumenti, che è attiva per impostazione predefinita:

• 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.
• In qualsiasi configurazione senza ricerca degli strumenti, Claude Code non segnala a Claude le connessioni ai server fallite.

Inviare messaggi con i canali

Un 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 per usare un canale supportato ufficialmente, oppure Riferimento dei canali per crearne uno tuo.

Sul runtime v2, 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.

Claude Code chiede quella revisione ai server stdio per impostazione predefinita. Per mantenere un server di canale stdio sull'handshake precedente, imposta MCP_PROTOCOL_NEGOTIATION su legacy, che mantiene tutti i server su di esso.

[!TIP]

Suggerimenti:

• Usa il flag -s o --scope per specificare dove viene memorizzata la configurazione:
  • local (predefinito): disponibile solo per te nel progetto corrente
  • project: condiviso con tutti nel progetto tramite il file .mcp.json
  • user: disponibile per te in tutti i progetti
• Imposta le variabili d'ambiente con i flag -e o --env (ad esempio, -e KEY=value)
• I flag --transport e --header accettano anche le forme brevi -t e -H
• 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)
• 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
• 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
• Usa /mcp per autenticarti con i server remoti che richiedono l'autenticazione OAuth 2.0

Limiti di tempo sulle chiamate agli strumenti MCP

Per limitare la durata di una chiamata a uno strumento MCP:

• Per server: aggiungi un campo timeout in millisecondi alla voce di configurazione di quel server
• Per tutti i server: imposta MCP_TOOL_TIMEOUT

Il 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 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.

Un 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.

Una 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, e di 30 minuti per i server stdio.

Imposta la variabile d'ambiente CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT in millisecondi per cambiare la finestra di inattività, oppure impostala su 0 per disabilitare il controllo.

Questi 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.

Spostamento automatico in background delle chiamate lunghe agli strumenti

Se la vista di dettaglio di una chiamata in background in /tasks mostra runs on the server; survives exiting this session, consulta Attività MCP eseguite sul server.

Una 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.

L'attività compare in /tasks, 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.

I 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, e il timeout di inattività impostato da CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT.

Per modificare o disattivare lo spostamento automatico in background:

• Imposta la variabile d'ambiente CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS 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 in una sessione interattiva
• Imposta CLAUDE_CODE_DISABLE_BACKGROUND_TASKS su 1 per disattivare lo spostamento automatico in background e i comandi in background

Alcune chiamate non vengono mai spostate in background:

• Le chiamate dei subagent; Claude Code sposta in background solo le chiamate della conversazione principale
• Le chiamate ai server IDE
• Le chiamate in modalità non interattiva, a meno che CLAUDE_AUTO_BACKGROUND_TASKS non sia impostato su 1, poiché un'esecuzione singola può terminare prima dell'arrivo del risultato

Una chiamata in attesa di una finestra di dialogo di elicitation 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.

Attività MCP eseguite sul server

Un'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. 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. Quando il lavoro termina, la trascrizione lo indica e Claude riceve il risultato. Chiedilo a Claude.

Nel 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.

[!NOTE]

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 elenca le sessioni e i server che le supportano.

Arrestare un'attività MCP o ottenerne il risultato

Per arrestare un'attività in esecuzione, selezionala in /tasks e premi x, oppure chiedilo a Claude. Claude Code smette di seguire l'attività e chiede al server di annullarla, anche se il server potrebbe comunque completarla. Riconnetti prima da /mcp un server disconnesso, altrimenti non viene inviata alcuna richiesta di annullamento e Claude Code dimentica l'attività e non può più seguirla. Premere Esc non arresta un'attività in background.

Quando l'attività termina, nella trascrizione compare una riga come questa:

MCP task <server task id> (<server>/<tool>) completed.

Il 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.

Rispondere a una domanda di un'attività MCP

Un'attività in esecuzione può aprire una finestra di dialogo di elicitation 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.

In una sessione non interattiva, Claude Code chiede al server di annullare un'attività che richiede input, senza eseguire i tuoi hook Elicitation né chiamare il callback onElicitation dell'Agent SDK.

Uscire, cancellare o riprendere mentre un'attività MCP è in esecuzione

Un'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.

Cosa serve a una chiamata per diventare un'attività MCP

Una chiamata a uno strumento diventa un'attività MCP solo quando valgono tutte queste condizioni:

• Il server supporta le attività
• Il server è un server HTTP, stdio o connettore claude.ai connesso sulla revisione del protocollo 2026-07-28. Impostare MCP_SDK_GENERATION=v1 o MCP_PROTOCOL_NEGOTIATION=legacy lo esclude
• La sessione recupera i feature flag, quindi non su un provider di terze parti come Amazon Bedrock, e non con la telemetria o il recupero dei flag disattivati
• 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 e le esecuzioni di GitHub Actions. Altre superfici, come l'estensione VS Code e l'app desktop, non hanno le attività MCP
• La chiamata proviene dalla conversazione principale, non da un subagent
• La sessione è interattiva, oppure una sessione Agent SDK o un'esecuzione claude -p che legge --input-format stream-json ha:
  • CLAUDE_AUTO_BACKGROUND_TASKS a 1
  • CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND diverso da 1
  • CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS diverso da 0

Qualsiasi altra chiamata è una normale chiamata a uno strumento, e Spostamento automatico in background delle chiamate lunghe agli strumenti indica quali di esse vengono spostate in background.

Mantieni aperto l'input di una sessione Agent SDK o stream-json, perché l'esecuzione non attende le attività MCP dopo la chiusura dell'input. Un'esecuzione singola claude -p "<prompt>" non ottiene attività MCP.

Messaggi di stato su un'attività MCP

Questi 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.

Limiti di tempo sulle attività MCP

Per impostazione predefinita, un'attività in background non ha alcun limite di tempo di Claude Code. I limiti di tempo delle chiamate agli strumenti, 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, si applicano per l'intera attività. I controlli di stato con risposta contano come attività ai fini del timeout di inattività.

Far attendere Claude il risultato di un'attività MCP

Per 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:

• CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS impostata su 0: Claude attende ogni chiamata a uno strumento MCP fino al suo termine
• CLAUDE_CODE_DISABLE_MCP_TASK_BACKGROUND impostata su 1: Claude attende il risultato di un'attività. Mentre lo spostamento automatico in background è 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

Mentre Claude attende, premere Esc o raggiungere il limite in tempo reale o il timeout di inattività termina la chiamata, e Claude Code chiede al server di annullare l'attività.

Se imposti CLAUDE_CODE_DISABLE_BACKGROUND_TASKS su 1 o avvii in modalità bare, 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:

{
  "env": {
    "CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS": "0"
  }
}

Attività MCP per gli autori di server

Se sviluppi un server MCP, puoi rispondere a una tools/call di lunga durata con un'attività. L'estensione MCP tasks definisce i messaggi che invii. Su una connessione con revisione del protocollo 2026-07-28, 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à omette quell'estensione.

Rispondere alla chiamata con un'attività

Rispondi 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:

{
  "resultType": "task",
  "taskId": "build-7f3a9c2e",
  "status": "working",
  "statusMessage": "Compiling, 40 of 212 files done",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:03:07Z",
  "ttlMs": null,
  "pollIntervalMs": 5000
}

Claude 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.

Su un server HTTP o connettore claude.ai, la risposta con l'attività deve iniziare entro il timer per richiesta, quindi accetta il lavoro e rispondi prima, poi esegui il lavoro.

Riportare stato, risultati e domande

Subito 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:

{
  "resultType": "complete",
  "taskId": "build-7f3a9c2e",
  "status": "completed",
  "createdAt": "2026-10-22T14:03:07Z",
  "lastUpdatedAt": "2026-10-22T14:09:41Z",
  "ttlMs": null,
  "result": {
    "content": [{ "type": "text", "text": "Build succeeded: 212 files, 0 warnings" }]
  }
}

Server MCP forniti dai plugin

I plugin possono includere server MCP che forniscono strumenti e integrazioni quando abiliti il plugin.

Come funzionano i server MCP dei plugin:

• I plugin definiscono i server MCP in .mcp.json nella root del plugin oppure inline in plugin.json
• Quando abiliti un plugin, Claude Code avvia automaticamente i suoi server MCP
• Claude Code offre gli strumenti MCP dei plugin insieme agli strumenti MCP configurati manualmente
• 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 in /mcp, il che impedisce a Claude Code di connettersi a esso senza rimuovere il plugin

Esempio di configurazione MCP di un plugin:

In .mcp.json nella root del plugin:

{
  "mcpServers": {
    "database-tools": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

Oppure inline in plugin.json:

{
  "name": "my-plugin",
  "mcpServers": {
    "plugin-api": {
      "command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
      "args": ["--port", "8080"]
    }
  }
}

Funzionalità MCP dei plugin:

• Ciclo di vita automatico: i server si connettono e si disconnettono in questi momenti:
  • 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; 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
  • 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 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
  • 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 dall'Agent SDK senza nominarli
  • Quando sposti la sessione con /cd 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
  • Nelle sessioni cloud, 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
• Segnaposto per i percorsi: ${CLAUDE_PLUGIN_ROOT} viene risolto nella directory di installazione del plugin, ${CLAUDE_PLUGIN_DATA} nella sua directory di stato persistente e ${CLAUDE_PROJECT_DIR} nella root stabile del progetto. La sostituzione si applica a:
  • server stdio: command, args, env
  • server http, sse e ws: url, headers e headersHelper
• Accesso all'ambiente dell'utente: accesso alle stesse variabili d'ambiente dei server configurati manualmente
• 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

I server dei plugin compaiono in /mcp con indicatori che mostrano che provengono da plugin.

claude mcp get nasconde i valori configurati per il server stdio o WebSocket di un plugin, perché possono contenere credenziali:

• server stdio: stampa Command: stdio, una riga Args: vuota e ogni variabile d'ambiente come NAME=[REDACTED]
• server WebSocket: stampa URL: ws e ogni header come <name>: [REDACTED], e claude mcp list mostra ws al posto dell'URL

Per vedere cosa ha configurato il plugin, trova il plugin su disco e leggi il suo .mcp.json o plugin.json.

Nomi degli strumenti MCP dei plugin:

Gli 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:

mcp__plugin_my-plugin_database-tools__query

Usa questo nome completo quando fai riferimento allo strumento nelle regole di permesso, nell'elenco allowed-tools di una skill, nel campo tools di un subagent o in un matcher di un hook. 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.

Il 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.

Consulta il riferimento ai componenti dei plugin per i dettagli su come includere server MCP nei plugin.

Ambiti di installazione MCP

I server MCP possono essere configurati a tre ambiti diversi. L'ambito che scegli controlla in quali progetti il server viene caricato e se la configurazione è condivisa con il tuo team. Gli amministratori possono anche distribuire o fornire server a ogni utente tramite configurazione gestita.

Ambito locale

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

[!NOTE]

Il termine "ambito locale" per i server MCP differisce dalle impostazioni locali generali. I server MCP con ambito locale vengono archiviati in ~/.claude.json (la tua directory home), mentre le impostazioni locali generali utilizzano .claude/settings.local.json (nella directory del progetto). Vedi Impostazioni per i dettagli sui percorsi dei file di impostazioni.

# Aggiungi un server con ambito locale (predefinito)
claude mcp add --transport http stripe https://mcp.stripe.com

# Specifica esplicitamente l'ambito locale
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

Il comando scrive il server nella voce per il tuo progetto corrente all'interno di ~/.claude.json. L'esempio seguente mostra il risultato quando lo esegui da /path/to/your/project:

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "stripe": {
          "type": "http",
          "url": "https://mcp.stripe.com"
        }
      }
    }
  }
}

Ambito del progetto

I server con ambito del progetto abilitano la collaborazione del team archiviando le configurazioni in un file .mcp.json nella directory radice del tuo progetto. Quando aggiungi un server con ambito del progetto, Claude Code crea o aggiorna automaticamente questo file con la struttura di configurazione appropriata. Archivia .mcp.json nel controllo della versione in modo che tutti nel tuo team ottengano gli stessi strumenti e servizi MCP.

# Aggiungi un server con ambito del progetto
claude mcp add --transport http shared-server --scope project https://example.com/mcp

Il file .mcp.json risultante segue un formato standardizzato:

{
  "mcpServers": {
    "shared-server": {
      "type": "http",
      "url": "https://example.com/mcp"
    }
  }
}

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

Nelle esecuzioni claude -p, nelle sessioni Agent SDK e nelle sessioni cloud al di fuori dei thread di un progetto, Claude Code non può mostrare quel prompt: carica i server con ambito del progetto senza chiedere. Claude Code salta anche il prompt in una sessione che avvii in modalità bypassPermissions con skipDangerousModePermissionPrompt impostato nelle tue impostazioni utente o nelle impostazioni gestite. Per mantenere un server fuori comunque:

• Aggiungilo a disabledMcpjsonServers, che lo blocca in ogni modalità di autorizzazione.
• Escludi completamente le impostazioni del progetto con --setting-sources o l'opzione settingSources dell'SDK.
• Avvia la sessione con --strict-mcp-config. Claude Code utilizza quindi solo i server MCP che passi con --mcp-config. Saltare il prompt di approvazione per i server con ambito del progetto che Claude Code non sta caricando richiede Claude Code v2.1.246 o successivo; prima di v2.1.246, una sessione ristretta attendeva comunque l'approvazione per loro, il che lasciava le sessioni in background in attesa all'avvio. Vedi Controllo esclusivo con managed-mcp.json per quello che il flag fa sotto un file MCP gestito.

Approvazioni del server del progetto e fiducia dell'area di lavoro copre come le approvazioni impegnate nel repository interagiscono con la fiducia dell'area di lavoro.

Ambito utente

I server con ambito utente vengono archiviati in ~/.claude.json e forniscono accessibilità tra progetti, rendendoli disponibili in tutti i progetti sulla tua macchina mentre rimangono privati al tuo account utente. Questo ambito funziona bene per server di utilità personali, strumenti di sviluppo o servizi che utilizzi frequentemente in diversi progetti.

# Aggiungi un server utente
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

Gerarchia e precedenza dell'ambito

Quando lo stesso server è definito in più di un posto, Claude Code si connette ad esso una volta, utilizzando la definizione dalla fonte con la precedenza più alta. L'intera voce del server da quella fonte viene utilizzata; i campi non vengono uniti tra gli ambiti.

1. Ambito locale
2. Ambito del progetto
3. Ambito utente
4. Server forniti da plugin
5. Connettori claude.ai

Claude Code corrisponde ai duplicati nei tre ambiti per nome. Corrisponde ai plugin e ai connettori per endpoint, quindi uno che punta allo stesso URL o comando di un server sopra è trattato come un duplicato.

Due ortografie di URL contano come lo stesso endpoint quando differiscono solo nella lettera maiuscola/minuscola dello schema o dell'host, la porta predefinita dello schema, come :443 su https, o una barra finale. Un percorso diverso, una stringa di query, userinfo o una porta non predefinita rendono due server diversi.

Un server che la tua organizzazione fornisce tramite l'impostazione gestita managedMcpServers si classifica al di sopra di tutti questi, quindi quando uno di loro lo duplica, Claude Code si connette alla definizione dell'organizzazione. Richiede Claude Code v2.1.259 o successivo.

Se apri una sessione locale nella scheda Code dell'app Desktop con lo stesso nome di server stdio al livello superiore di ~/.claude.json (ambito utente) e in .mcp.json, la scheda Code utilizza la definizione ~/.claude.json.

Espansione delle variabili di ambiente in .mcp.json

Claude Code supporta l'espansione delle variabili di ambiente nei file .mcp.json, consentendo ai team di condividere configurazioni mantenendo flessibilità per i percorsi specifici della macchina e i valori sensibili come le chiavi API.

Puoi fare riferimento a una variabile d'ambiente nel valore command, args, env, url o headers di un server, in una delle due forme seguenti:

• ${VAR}: si espande al valore della variabile di ambiente VAR
• ${VAR:-default}: si espande al valore di VAR se VAR è impostata, oppure a default se non è impostata

Esempio con espansione di variabili

In questa voce di server, l'URL è il valore di API_BASE_URL seguito da /mcp, con https://api.example.com come valore predefinito, e la chiave API proviene da API_KEY:

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

Variabili non impostate senza un valore predefinito

Se una variabile di ambiente richiesta non è impostata e non ha un valore predefinito, la configurazione viene comunque caricata: Claude Code segnala un avviso di variabile mancante per quel server nell'output di claude mcp list e utilizza il testo ${VAR} non espanso così com'è. Imposta la variabile o aggiungi un fallback :-default in modo che il server si avvii con il valore che intendi. Negli url e headers di un server remoto, alcune variabili di credenziali leggono come vuote invece, senza avviso.

Variabili impostate su una stringa vuota

Se imposti una variabile su una stringa vuota, conta come impostata, quindi un riferimento ${VAR:-default} si espande alla stringa vuota anziché a default. Con il server di esempio, se imposti API_BASE_URL su una stringa vuota, il suo url diventa /mcp e claude mcp list segnala 'url' is not a valid URL. Per usare il valore predefinito, rimuovi la variabile anziché impostarla su una stringa vuota.

Variabili di credenziali che leggono come vuote

Negli url e headers di un server remoto, Claude Code legge le variabili di credenziali dal tuo ambiente come vuote piuttosto che espanderle. Questo impedisce che il .mcp.json di un progetto o un plugin invii le tue credenziali di Claude Code o del provider cloud a un server che nomina. Se scrivi Bearer ${ANTHROPIC_AUTH_TOKEN}, il server riceve Bearer senza credenziale e rifiuta la richiesta, di solito con un 401. Claude Code lo segnala come una connessione non riuscita.

I nomi coperti sono:

• Le credenziali di Claude Code stesso, come ANTHROPIC_API_KEY e ANTHROPIC_AUTH_TOKEN
• Le credenziali del tuo provider cloud, come AWS_BEARER_TOKEN_BEDROCK
• Altre credenziali che il tuo ambiente contiene, come HTTPS_PROXY e NPM_TOKEN

Un nome coperto legge come vuoto indipendentemente dal fatto che tu abbia impostato la variabile, e un fallback :-default su di esso viene ignorato. Un URL di base del provider come ANTHROPIC_BASE_URL si espande comunque, quindi "url": "${ANTHROPIC_BASE_URL}/mcp" funziona, a meno che il valore dell'URL stesso non incorpori una credenziale come un nome utente e una password.

Un nome al di fuori di questo set, come API_KEY, si espande come scritto. Per dare al server una delle credenziali coperte, copiala in una variabile con un nome di tua scelta e fai riferimento a quel nome invece.

Quando url o headers di un server remoto fanno riferimento a una variabile coperta che hai impostato, Claude Code la nomina in una riga di log di debug. Per leggere la riga, esegui claude --debug-file /tmp/claude-debug.log e cerca in quel file never expanded toward a remote server.

Come i riferimenti appaiono in /mcp e nell'output CLI

Per un server negli ambiti locale, progetto o utente, le seguenti superfici mostrano un riferimento ${VAR} per nome piuttosto che come valore risolto:

• L'URL o la riga di comando nella vista dettagli /mcp di un server
• Output di claude mcp list e claude mcp get

La vista dettagli /mcp mostra i riferimenti in questo modo in Claude Code v2.1.268 o successivo.

Per un server che la tua organizzazione fornisce tramite l'impostazione managedMcpServers, queste superfici mostrano solo l'host dell'URL.

Per verificare cosa mostrano claude mcp list, claude mcp get e /mcp quando una connessione non riesce, vedi Dettagli dello stato del server.

Esempi pratici

Esempio: Connettiti a GitHub per le revisioni del codice

Il server MCP remoto di GitHub si autentica con un token di accesso personale GitHub passato come header. Per ottenerne uno, apri le impostazioni del token GitHub, genera un nuovo token con granularità fine con accesso ai repository con cui desideri che Claude lavori, quindi aggiungi il server:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

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

Quindi lavora con GitHub:

Rivedi la PR #456 e suggerisci miglioramenti

Crea un nuovo issue per il bug che abbiamo appena trovato

Mostrami tutte le PR aperte assegnate a me

Esempio: Interroga il tuo database PostgreSQL

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

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

Per confermare che il server si avvia, esegui /mcp e controlla che la riga db mostri un segno di spunta.

Quindi interroga il tuo database naturalmente:

Qual è il nostro ricavo totale questo mese?

Mostrami lo schema per la tabella orders

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

Autenticazione con server MCP remoti

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

Claude Code contrassegna un server remoto come richiedente autenticazione quando il server risponde con 401 Unauthorized o 403 Forbidden. Ciò che Claude Code mostra dipende dal server:

• Per un server a cui non hai effettuato l'accesso, uno di questi codici di stato lo contrassegna in /mcp in modo che tu possa completare il flusso OAuth.
• Per un connettore claude.ai, un 401 causato dal rifiuto di claude.ai del tuo token di sessione non contrassegna il connettore, perché la riautorizzazione del connettore non può risolvere il tuo accesso. Claude Code mostra invece lo stato di rifiuto del token di sessione.
• Per un server il cui header Authorization hai configurato, in headers o tramite un headersHelper, un 401 o 403 durante la connessione non contrassegna il server, perché la credenziale da correggere è quella che hai configurato. Claude Code segnala invece la connessione come non riuscita. Se hai impostato quell'header da un riferimento ${VAR}, verifica se quella variabile è una che Claude Code legge come vuota.
• Per un connettore consegnato a una sessione cloud, Claude Code non esegue un flusso di accesso, perché il proxy della sessione si autentica al connettore con l'autorizzazione che hai concesso in claude.ai. Quando un connettore lì ha bisogno di autorizzazione di nuovo, riconnettilo su claude.ai/customize/connectors piuttosto che dalla sessione.

Quando un server OAuth a cui hai già effettuato l'accesso rifiuta il tuo token archiviato con 401 Unauthorized, Claude Code si riconnette con o senza un nuovo token:

• Il tuo accesso archiviato ha un token di aggiornamento: aggiorna il token, si riconnette e riprova la richiesta una volta. Il server viene contrassegnato in /mcp solo se anche quel nuovo tentativo non riesce.
• Il tuo accesso archiviato non ha un token di aggiornamento: si connette una volta senza il token. Se il server risponde, i suoi strumenti funzionano mentre sei disconnesso e il token rifiutato viene eliminato. Se il server rifiuta anche quella connessione, /mcp mostra che il server richiede l'autenticazione.

In un'esecuzione claude -p o Agent SDK su macOS, una richiesta che Claude Code ha inviato mentre non riusciva a leggere il tuo token archiviato non riesce con un errore delle credenziali archiviate.

Quando il server rifiuta il token di aggiornamento archiviato, Claude Code mostra immediatamente un avviso che punta a /mcp. Apri /mcp e seleziona Re-authenticate sul server per accedere di nuovo prima che la prossima chiamata a uno strumento non riesca.

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

Claude Code mostra anche un avviso di avvio quando uno o più server configurati richiedono l'autenticazione, quindi non è necessario aprire /mcp per scoprire quali server richiedono l'accesso. L'avviso conta solo i server a cui puoi accedere da Claude Code. Prima della v2.1.218, contava anche i connettori claude.ai che non erano connessi in claude.ai, che puoi connettere solo dalle impostazioni di claude.ai.

L'avviso annuncia ogni server una volta e lo esclude dal conteggio ai successivi avvii fino a quando quel server non si è connesso e ha bisogno di accesso di nuovo. /mcp elenca comunque ogni server che ha bisogno di accesso.

Un'esecuzione claude -p o Agent SDK non ha un pannello /mcp, quindi lì Claude Code non può eseguire il flusso OAuth. Per utilizzare un server che richiede l'autenticazione, completa prima l'accesso da una sessione interattiva: esegui /mcp nella sessione, oppure claude mcp login <name> nella tua shell. Quando un server configurato richiede l'autenticazione durante un'esecuzione claude -p o Agent SDK con la ricerca degli strumenti abilitata, Claude Code comunica a Claude che gli strumenti del server non sono disponibili fino a quando non lo autorizzi.

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

1. Aggiungi il server che richiede l'autenticazione

Se hai già aggiunto il server sentry nella guida rapida MCP, salta questo passaggio: eseguire di nuovo claude mcp add con lo stesso nome di server nello stesso ambito non riesce con MCP server sentry already exists in local config. Altrimenti, esegui:

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

2. Utilizza il comando /mcp all'interno di Claude Code

In Claude Code, utilizza il comando:

/mcp

Quindi segui i passaggi nel tuo browser per accedere.

[!TIP]

Suggerimenti:

• I token di autenticazione vengono archiviati in modo sicuro e aggiornati automaticamente
• Utilizza "Clear authentication" nel menu /mcp per revocare l'accesso
• Se il tuo browser non si apre automaticamente, copia l'URL fornito e aprilo manualmente
• Se il reindirizzamento del browser non riesce con un errore di connessione dopo l'autenticazione, incolla l'URL di callback completo dalla barra degli indirizzi del tuo browser nel prompt dell'URL che appare in Claude Code
• L'autenticazione OAuth funziona con i server HTTP

Autenticazione dalla riga di comando

Il comando claude mcp login <name> esegue il flusso OAuth di un server configurato direttamente dalla tua shell, quindi non è necessario aprire il pannello /mcp all'interno di una sessione. Per un connettore claude.ai, segui Autorizzare di nuovo un connettore dalla tua shell.

claude mcp login sentry

Per cancellare le credenziali archiviate in seguito, esegui claude mcp logout <name>.

claude mcp login rileva quando nessun browser locale è disponibile, ad esempio durante una sessione SSH o su Linux senza un server di visualizzazione, e stampa l'URL di autorizzazione invece di provare ad aprire un browser. Apri l'URL sulla tua macchina locale, quindi incolla l'URL di reindirizzamento completo dalla barra degli indirizzi del tuo browser al prompt. Il comando ha bisogno di un terminale interattivo per il passaggio di incollamento, quindi connettiti con ssh -t. Passa --no-browser per forzare il prompt dell'URL anche quando viene rilevato un browser locale.

claude mcp login sentry --no-browser

Utilizza una porta di callback OAuth fissa

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

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

# Porta di callback fissa con registrazione dinamica del client
claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

Utilizza credenziali OAuth pre-configurate

Alcuni server MCP non supportano la configurazione OAuth automatica tramite Dynamic Client Registration. Se vedi un errore come "Incompatible auth server: does not support dynamic client registration," il server richiede credenziali pre-configurate. Claude Code supporta anche server che utilizzano un Client ID Metadata Document (CIMD) invece di Dynamic Client Registration e li scopre automaticamente. Se la scoperta automatica non riesce, registra prima un'app OAuth tramite il portale degli sviluppatori del server, quindi fornisci le credenziali quando aggiungi il server.

1. Registra un'app OAuth con il server

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

Se il modulo di registrazione chiede un URI di reindirizzamento, scegli una porta disponibile e inserisci http://localhost:PORT/callback con quella porta. Utilizzerai la stessa porta nel passaggio successivo.

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

2. Aggiungi il server con le tue credenziali

Le schede coprono entrambi i comandi: claude mcp add accetta il tuo ID client e la porta di callback come flag, e claude mcp add-json li accetta in un oggetto oauth. Se hai registrato un URI di reindirizzamento, imposta la porta di callback sulla porta in quell'URI.

[tab] claude mcp add

Utilizza --client-id per passare l'ID client della tua app. Il flag --client-secret richiede il segreto con input mascherato:

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

[tab] claude mcp add-json

Includi l'oggetto oauth nella configurazione JSON e passa --client-secret come flag separato:

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
  --client-secret

[tab] claude mcp add-json (solo porta di callback)

Per fissare solo la porta di callback e consentire a Claude Code di registrare il client automaticamente, imposta callbackPort da solo:

claude mcp add-json my-server \
  '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'

[tab] CI / env var

Imposta il segreto tramite variabile d'ambiente per saltare il prompt interattivo:

MCP_CLIENT_SECRET=your-secret claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

3. Autenticati in Claude Code

Esegui /mcp in Claude Code e segui il flusso di accesso del browser.

[!TIP]

Suggerimenti:

• Il segreto client viene archiviato in modo sicuro nel tuo portachiavi di sistema (macOS) o in un file di credenziali, non nella tua configurazione
• Puoi impostare il segreto client solo quando aggiungi il server. Quando ti autentichi con claude mcp login o da /mcp, Claude Code utilizza il segreto archiviato e non ne chiede uno né legge MCP_CLIENT_SECRET
• Per aggiungere o modificare il segreto in seguito, rimuovi il server con claude mcp remove <name>, quindi aggiungilo di nuovo con --client-secret e lo stesso --scope
• Se il server utilizza un client OAuth pubblico senza segreto, utilizza solo --client-id senza --client-secret
• Questi flag si applicano solo ai trasporti HTTP e SSE. Non hanno effetto sui server stdio
• Utilizza claude mcp get <name> per verificare che le credenziali OAuth siano configurate per un server

Sovrascrivi la scoperta dei metadati OAuth

Indirizza Claude Code a un URL specifico di metadati del server di autorizzazione OAuth per bypassare la catena di scoperta predefinita. Imposta authServerMetadataUrl quando gli endpoint standard del server MCP generano errori, o quando desideri instradare la scoperta attraverso un proxy interno. Per impostazione predefinita, Claude Code controlla prima i metadati della risorsa protetta RFC 9728 su /.well-known/oauth-protected-resource, quindi ricade sui metadati del server di autorizzazione RFC 8414 su /.well-known/oauth-authorization-server.

Imposta authServerMetadataUrl nell'oggetto oauth della configurazione del tuo server in .mcp.json:

{
  "mcpServers": {
    "my-server": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "oauth": {
        "authServerMetadataUrl": "https://auth.example.com/.well-known/openid-configuration"
      }
    }
  }
}

L'URL deve utilizzare https://. Il scopes_supported dell'URL dei metadati sovrascrive gli scope che il server upstream pubblicizza.

Limita gli scope OAuth

Imposta oauth.scopes per fissare gli scope che Claude Code richiede durante il flusso di autorizzazione. Questo è il modo supportato per limitare un server MCP a un sottoinsieme approvato dal team di sicurezza quando il server di autorizzazione upstream pubblicizza più scope di quelli che desideri concedere. Il valore è una singola stringa separata da spazi, corrispondente al formato del parametro scope in RFC 6749 §3.3.

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "https://mcp.slack.com/mcp",
      "oauth": {
        "scopes": "channels:read chat:write search:read"
      }
    }
  }
}

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

Quando oauth.scopes non è impostato, Claude Code non richiede il catalogo completo di scopes_supported dai metadati del server di autorizzazione scoperti automaticamente. I metadati recuperati da un authServerMetadataUrl configurato forniscono comunque il loro scopes_supported come scope richiesti.

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

Se il server successivamente restituisce un 403 insufficient_scope per una chiamata a uno strumento, la chiamata non riesce con un messaggio needs additional permissions che nomina lo scope che il server richiede. Il server viene mostrato come richiedente autenticazione in /mcp.

Se quello scope non è nei tuoi oauth.scopes fissati, aggiungilo, quindi esegui /mcp e autentica di nuovo il server. Claude Code richiede gli scope fissati piuttosto che lo scope che il server ha nominato, quindi se ti autentichi di nuovo senza aggiungerlo, il token che ottieni ancora non lo ha.

Utilizza OAuth con un server dietro un proxy che richiede autenticazione

Se il tuo server MCP utilizza OAuth dietro un proxy o un gateway che controlla un proprio header, l'accesso non riesce quando le richieste OAuth arrivano senza quell'header. L'accesso tramite il proxy richiede Claude Code v2.1.299 o successiva, con l'header e l'accesso entrambi configurati:

• L'header del proxy: passalo con --header, con il campo headers o con un headersHelper, con il nome che il proxy legge
• L'accesso OAuth: escludi Authorization dagli header configurati, quindi accedi con claude mcp login <name> nella tua shell. Se configuri un header Authorization, Claude Code lo utilizza come credenziale del server e non ricorre a OAuth per quel server.

Utilizza intestazioni dinamiche per l'autenticazione personalizzata

Quando un'autenticazione come Kerberos, token di breve durata o un SSO interno richiede intestazioni generate al momento della connessione, imposta il headersHelper del server su un comando. Claude Code lo esegue durante la connessione ed esegue il merge del suo output nelle intestazioni che invia. Questo esempio utilizza uno script:

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

Il comando può anche essere inline:

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "echo '{\"Authorization\": \"Bearer '\"$(get-token)\"'\"}'"
    }
  }
}

Requisiti:

• Il comando deve scrivere un oggetto JSON di coppie chiave-valore stringa su stdout
• Claude Code esegue il comando in una shell e rinuncia dopo 10 secondi
• Claude Code sceglie la directory di lavoro del comando in base a dove hai configurato il server, quindi fornisci lo script come percorso assoluto o mettilo su PATH
• Le intestazioni dinamiche sovrascrivono qualsiasi headers statico con lo stesso nome

Claude Code esegue l'helper di nuovo ad ogni connessione, all'avvio della sessione e alla riconnessione, una volta che la regola di fiducia per i server di ambito progetto e locale lo consente. Non memorizza il risultato nella cache, quindi il tuo script è responsabile di qualsiasi riutilizzo di token.

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

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

Se il server rifiuta la credenziale dell'helper durante la connessione, Claude Code segnala la connessione come non riuscita piuttosto che contrassegnare il server come richiedente autenticazione. Correggi la credenziale che il tuo helper restituisce, quindi riconnettiti da /mcp per eseguire di nuovo l'helper.

Claude Code imposta queste variabili d'ambiente quando esegue l'helper:

Utilizza queste variabili per scrivere un singolo script helper che serve più server MCP.

Un headersHelper fornito da un plugin non può fare riferimento ai valori ${user_config.*} del plugin, perché il comando viene eseguito attraverso una shell. Claude Code segnala il server come non configurato correttamente con un errore e non sostituisce il valore. Metti ${user_config.KEY} nel campo headers del server, che non viene analizzato dalla shell, oppure fai in modo che lo script helper legga il valore da un file di configurazione. Prima della v2.1.207, headersHelper sostituiva i valori ${user_config.*}.

Dove l'helper viene eseguito

Claude Code sceglie la directory di lavoro del comando headersHelper dalla configurazione che dichiara il server. Un cd che Claude esegue in Bash non lo sposta, e /cd lo sposta solo per i server che vengono eseguiti dalla directory di lavoro primaria della sessione. Ogni riga di seguito fornisce la directory rispetto alla quale un percorso relativo nel tuo comando headersHelper si risolve.

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

Quali variabili un helper può leggere

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

• Rimosso: un server in un .mcp.json di progetto o in un plugin, e un server inline in un file agent dal tuo progetto o da una directory --add-dir
• Non rimosso: un server di ambito utente o ambito locale, in MCP gestito, da un connettore claude.ai, o fornito dall'SDK o da --mcp-config, e un server inline in un file agent da ~/.claude/agents/, dalle impostazioni gestite, o passato con --agents

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

Quando questo si applica al tuo helper, fai in modo che lo script legga la sua credenziale da un file o da un archivio di credenziali. Se l'url del server contiene il valore effettivo di una di queste variabili, come MY_REGISTRY_TOKEN, anche nel valore CLAUDE_CODE_MCP_SERVER_URL che l'helper riceve quella parte viene sostituita con REDACTED.

Affida una cartella prima che il suo headersHelper venga eseguito

Claude Code esegue un headersHelper come comando shell arbitrario. Per un server in un .mcp.json di progetto o di ambito locale, lo esegue solo dopo che accetti la finestra di dialogo di fiducia per la directory del progetto in cui il server è dichiarato. Prima della v2.1.238, una sessione claude -p o SDK eseguiva questi helper senza controllare la fiducia, e una sessione interattiva li eseguiva una volta che avevi affidato una cartella genitore.

• Fiducia che non conta: la fiducia di una cartella genitore, e la fiducia automatica che una sessione claude -p o SDK ottiene per gli hook nei file di impostazioni
• Fino a quando non affidi la cartella: Claude Code connette il server con i suoi soli headers statici. In una sessione claude -p o SDK stampa anche una riga headersHelper not run per server su stderr, dicendoti come concedere la fiducia.
• Fiducia senza una finestra di dialogo: imposta projects["<path>"].hasTrustDialogAccepted su true in ~/.claude.json. <path> è la cartella su cui Project allow rules and workspace trust dice che Claude Code basa la fiducia.

Claude Code applica la stessa regola a un server dichiarato inline in un file agent, controllando da dove proveniva quel file agent: il tuo progetto, per un file nella sua directory .claude/agents/, o una directory --add-dir. Fino a quando non affidi quel progetto o quella directory stessa, Claude Code non carica il server affatto, quindi il suo helper non viene mai eseguito nemmeno.

Accedere a un server MCP dietro un gateway che richiede un header

L'accesso OAuth a un server MCP non riesce quando un gateway richiede un header, come X-API-Key, e Claude Code non lo invia. Per fare in modo che Claude Code invii quell'header, aggiungilo alla configurazione del server e utilizza Claude Code v2.1.299 o successiva:

• Un server di cui puoi modificare la configurazione: impostalo in headers o restituiscilo da un headersHelper
• Un server fornito da MCP gestito o da un plugin: chiedi al tuo amministratore o all'autore del plugin di aggiungere l'header alla voce del server

Claude Code aggiunge quindi gli header configurati, tranne Authorization, alle richieste di accesso, di aggiornamento del token e di revoca del token che invia all'origine del server. L'origine del server è costituita da schema, host e porta nel suo url. Un gateway che richiede l'header può comunque bloccare l'accesso alla pagina di autorizzazione o a un server di autorizzazione su un'altra origine:

• La pagina di autorizzazione: accedi su questa pagina nel tuo browser, che non invia gli header configurati. Se il tuo browser riceve l'errore del gateway invece della pagina, chiedi a chi gestisce il gateway di lasciar passare la pagina senza l'header.
• Un server di autorizzazione su un'altra origine: se anche un gateway davanti a quel server richiede l'header, l'accesso non riesce lì. Chiedi a chi gestisce quel gateway di lasciar passare le richieste OAuth senza l'header.

Aggiungi server MCP dalla configurazione JSON

Se hai una configurazione JSON per un server MCP, puoi aggiungerla direttamente:

1. Aggiungi un server MCP da JSON

# Sintassi di base
claude mcp add-json <name> '<json>'

# Esempio: Aggiunta di un server HTTP con configurazione JSON
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# Esempio: Aggiunta di un server stdio con configurazione JSON
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

# Esempio: Aggiunta di un server HTTP con credenziali OAuth pre-configurate
claude mcp add-json my-server '{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' --client-secret

2. Verifica che il server sia stato aggiunto

claude mcp get weather-api

[!TIP]

Suggerimenti:

• Assicurati che il JSON sia correttamente sfuggito nella tua shell
• Il JSON deve conformarsi allo schema di configurazione del server MCP
• Puoi utilizzare --scope user per aggiungere il server alla tua configurazione utente invece di quella specifica del progetto

Importa server MCP da Claude Desktop

Se hai già configurato server MCP in Claude Desktop, puoi importarli:

1. Importa server da Claude Desktop

# Sintassi di base 
claude mcp add-from-claude-desktop 

2. Seleziona quali server importare

Dopo aver eseguito il comando, vedrai una finestra di dialogo interattiva che ti consente di selezionare quali server desideri importare.

3. Verifica che i server siano stati importati

claude mcp list 

I nomi dei server aggiunti tramite i comandi claude mcp possono contenere solo lettere, numeri, trattini e caratteri di sottolineatura. Claude Desktop non applica questa restrizione, quindi un server Claude Desktop il cui nome contiene qualsiasi altro carattere, come uno spazio, non può essere importato. L'importazione segnala ogni nome che rifiuta e continua comunque a importare gli altri server che hai selezionato.

[!TIP]

Suggerimenti:

• Questa funzionalità funziona solo su macOS e Windows Subsystem for Linux (WSL)
• Legge il file di configurazione di Claude Desktop dalla sua posizione standard su quelle piattaforme
• Utilizza il flag --scope user per aggiungere server alla tua configurazione utente
• I server importati mantengono gli stessi nomi di Claude Desktop quando il nome contiene solo lettere, numeri, trattini e caratteri di sottolineatura. Claude Code segnala un server il cui nome contiene qualsiasi altro carattere e lo salta
• Se server con gli stessi nomi esistono già, riceveranno un suffisso numerico (per esempio, server_1)

Utilizzare i server MCP da claude.ai

Se hai effettuato l'accesso a Claude Code con un account claude.ai, i server MCP che hai aggiunto in claude.ai, noti come connettori, sono automaticamente disponibili in Claude Code:

1. Configurare i server MCP in claude.ai

Aggiungi i server su claude.ai/customize/connectors. Nei piani Team ed Enterprise, solo gli amministratori possono aggiungere server.

2. Autenticare il server MCP

Completa eventuali passaggi di autenticazione richiesti in claude.ai.

3. Visualizzare e gestire i server in Claude Code

In Claude Code, utilizza il comando:

/mcp

I server da claude.ai vengono visualizzati nell'elenco con indicatori che mostrano che provengono da claude.ai.

Anthropic fornisce anche alcuni connettori da sola, senza che tu o un amministratore li aggiunga. Negli account in cui Claude Docs è disponibile, /mcp elenca claude.ai Claude Docs senza configurazione, e Claude lo utilizza quando chiedi un documento destinato ad altre persone. Per disattivare solo questo connettore, consulta Disabilitare i connettori claude.ai.

Claude Code contrassegna un connettore come managed in /mcp e nel gestore /plugin quando la tua organizzazione gestisce la sua autenticazione in claude.ai. Lo stato managed non cambia il modo in cui Claude Code si connette al connettore o applica i controlli degli strumenti della tua organizzazione.

I connettori a cui non hai mai effettuato l'accesso sono compressi dietro una riga Show unused connectors alla fine della sezione claude.ai, in modo che un elenco fornito dall'organizzazione non riempia il pannello. Seleziona la riga per espanderli. Un connettore a cui hai effettuato l'accesso in precedenza rimane visibile anche quando attualmente necessita di una nuova autenticazione.

I connettori da claude.ai vengono recuperati solo quando il tuo metodo di autenticazione attivo è un accesso con abbonamento a claude.ai. Non vengono caricati, anche se hai precedentemente eseguito /login, quando:

• ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, o apiKeyHelper è attivo
• Un provider di terze parti come Amazon Bedrock o Agent Platform di Google Cloud è attivo
• ANTHROPIC_PROFILE, le variabili di federazione, o un profilo Anthropic attivo fornisce le credenziali
• CLAUDE_CODE_OAUTH_TOKEN contiene un token da claude setup-token, che può solo effettuare richieste di modello

Se /mcp non elenca un connettore che hai aggiunto, esegui /status per confermare quale metodo di autenticazione è attivo. Annulla l'impostazione di quella variabile di ambiente, rimuovi l'impostazione apiKeyHelper, o disattiva il profilo, quindi esegui /login per selezionare il tuo account claude.ai.

Se un problema di rete temporaneo impedisce il caricamento dell'elenco dei connettori all'avvio della sessione, Claude Code ritenta il recupero fino a tre volte in background, e i connettori vengono visualizzati una volta che un tentativo ha successo. Se ancora non sono apparsi, riavvia Claude Code per recuperare di nuovo l'elenco.

Se /mcp mostra un connettore come session token rejected, o la sua vista dettagliata mostra claude.ai rejected the session token, claude.ai ha rifiutato il token dal tuo accesso a Claude Code. Autorizzare di nuovo il connettore non cancella questo stato, perché l'autorizzazione propria del connettore in claude.ai non è quello che è stato rifiutato. Per cancellarlo:

1. Esegui /login per accedere di nuovo.
2. Ricollega il connettore da /mcp.

Prima della v2.1.222, Claude Code contrassegnava i connettori come necessitanti di autenticazione, e autorizzarli non lo risolveva.

Un server che hai aggiunto in Claude Code ha precedenza su un connettore claude.ai che punta allo stesso URL. Quando ciò accade, /mcp elenca il connettore come nascosto e mostra come rimuovere il duplicato se preferisci utilizzare il connettore.

Alcuni connettori ospitati da Anthropic, come Microsoft 365, Gmail e Google Calendar, non supportano OAuth locale da Claude Code perché il provider di identità upstream accetta solo l'URL di reindirizzamento che claude.ai ha registrato. Quando un server che hai aggiunto con claude mcp add o in .mcp.json punta a uno di questi host e accedi da /mcp o con claude mcp login, Claude Code mostra is Anthropic-hosted and doesn't support local OAuth, indirizzandoti a connettere il servizio su claude.ai/customize/connectors.

Dopo aver rimosso la tua voce con claude mcp remove <name> e aver connesso il servizio su claude.ai, il connettore viene visualizzato in Claude Code automaticamente.

Come i connettori raggiungono Claude Code

Quali impostazioni governano un connettore claude.ai dipende da dove viene eseguita la tua sessione, perché solo alcune sessioni recuperano i connettori da claude.ai stesse. Ogni riga sottostante nomina come i connettori arrivano in un tipo di sessione e cosa li controlla lì. Le sessioni WSL dell'app desktop non hanno una riga perché i connettori sono ancora in fase di distribuzione per esse.

disableClaudeAiConnectors, ENABLE_CLAUDEAI_MCP_SERVERS, e allowAllClaudeAiMcps agiscono solo sulla prima riga, i connettori che Claude Code recupera da solo. Le altre due righe differiscono da essa in questi modi:

• Sessioni cloud: le voci allowedMcpServers e deniedMcpServers che raggiungono la sessione, ad esempio attraverso impostazioni gestite dal server, filtrano anche i connettori forniti. Il proxy della sessione riscrive l'URL di ogni connettore, quindi un pattern serverUrl scritto per l'URL del connettore stesso non lo corrisponde. Per ammettere i connettori forniti insieme a un allowlist di URL in un ambiente auto-ospitato, aggiungi le voci serverUrl elencate sotto Connector traffic leaves your network. Claude Code elimina i connettori forniti quando un managed-mcp.json è presente sull'host che esegue la sessione, come un host di runner auto-ospitato, indipendentemente dal fatto che tu imposti allowAllClaudeAiMcps.
• Sessioni locali e SSH dell'app desktop: l'app desktop registra i connettori come server type: "sdk" in-process, e nessuna impostazione MCP o managed-mcp.json li raggiunge. Un utente mantiene un connettore fuori dalle proprie sessioni disconnettendolo su claude.ai/customize/connectors. Un'organizzazione blocca i strumenti di un connettore o disattiva completamente Claude Code nell'app desktop.

Controlli dell'organizzazione sugli strumenti del connettore

La tua organizzazione può impostare controlli per strumento sui connettori claude.ai. Claude Code legge queste impostazioni all'avvio e le applica localmente, tranne nelle sessioni locali e SSH dell'app desktop. Lì, l'app desktop trattiene gli strumenti blocked prima di fornire un connettore, e l'impostazione ask non raggiunge Claude Code, quindi applica le regole di autorizzazione ordinarie della sessione a quegli strumenti invece di richiedere su ogni chiamata. Nelle sessioni in cui Claude Code recupera i connettori da solo, esegui /mcp per vedere quale impostazione si applica a ogni strumento su un connettore.

• Strumento impostato su ask: Claude Code chiede conferma a ogni chiamata con il motivo Your organization requires approval for this tool. La richiesta appare anche nelle modalità di permesso acceptEdits, auto e bypassPermissions. Nel terminale, la richiesta non offre alcuna opzione per ricordare la tua scelta. Nemmeno le regole Allow che corrispondono allo strumento saltano la richiesta. In modalità dontAsk, che non chiede mai, Claude Code nega invece la chiamata.
• Strumento impostato su blocked: Claude Code filtra lo strumento prima che Claude lo veda, quindi non appare mai nell'elenco degli strumenti di Claude. Nelle sessioni in cui Claude Code recupera i connettori da solo, l'elenco degli strumenti /mcp mostra ancora lo strumento, contrassegnato disabled by your organization.

L'app desktop e la chat claude.ai applicano la stessa impostazione blocked, quindi Claude non può usare uno strumento bloccato neanche lì, e non puoi trattenere uno strumento dalle sessioni dell'app desktop mantenendolo disponibile in chat. L'app desktop salta un connettore i cui strumenti sono tutti bloccati.

Disabilitare i connettori claude.ai

Claude Code applica disableClaudeAiConnectors solo ai connettori che recupera da solo, non ai connettori che un host cloud o l'app desktop fornisce. Per disattivare i connettori che recupera, imposta l'impostazione su true in qualsiasi ambito di impostazioni:

{
  "disableClaudeAiConnectors": true
}

Questa impostazione utilizza la semantica any-source-true: true in qualsiasi fonte di impostazioni ha la precedenza. Un .claude/settings.json di progetto archiviato può escludere un repository dai connettori che Claude Code recupera da solo, ma un false a livello di progetto non può riabilitare i connettori che un true a livello di utente o politica ha disabilitato. I server passati esplicitamente tramite --mcp-config non sono interessati.

Puoi anche impostare la variabile di ambiente ENABLE_CLAUDEAI_MCP_SERVERS su false, che ha lo stesso effetto per la sessione shell corrente:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

Per bloccare i singoli connettori claude.ai invece di tutti loro, aggiungili a deniedMcpServers per nome o per pattern di URL. Ad esempio, una voce serverName di "claude.ai Slack" blocca il connettore Slack. Puoi anche eseguire /mcp per attivare o disattivare qualsiasi connettore che Claude Code recupera solo per il progetto corrente.

Usa Claude Code come server MCP

Puoi usare Claude Code stesso come server MCP a cui altre applicazioni possono connettersi:

# Avvia Claude come server MCP stdio
claude mcp serve

Il comando non stampa nulla all'avvio. Un server MCP stdio comunica tramite stdin e stdout, quindi un terminale silenzioso e bloccato significa che il server è in esecuzione e in attesa che un client si connetta.

Puoi usarlo in Claude Desktop aggiungendo questa configurazione a claude_desktop_config.json:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

[!WARNING]

Configurazione del percorso dell'eseguibile: il campo command deve fare riferimento all'eseguibile di Claude Code. Se il comando claude non è nel PATH del tuo sistema, dovrai specificare il percorso completo dell'eseguibile.

Per trovare il percorso completo:

which claude

Quindi usa il percorso completo nella tua configurazione:

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "/full/path/to/claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

Senza il percorso dell'eseguibile corretto, incontrerai errori come spawn claude ENOENT.

[!TIP]

Suggerimenti:

• In Claude Desktop, prova a chiedere a Claude di leggere file in una directory, fare modifiche e altro ancora.
• Questo server MCP espone solo gli strumenti di Claude Code al tuo client MCP, quindi il tuo client è responsabile dell'implementazione della conferma dell'utente per le singole chiamate agli strumenti.

Leggere l'output di un comando in background come client MCP

Un campo backgroundOutputPath in un risultato Bash o PowerShell di claude mcp serve significa che la chiamata ha lasciato il suo comando in esecuzione in background. Un comando viene eseguito in background quando il tuo client imposta run_in_background: true nella chiamata. Anche un comando in primo piano può passare in background quando raggiunge il suo timeout.

Il campo si trova nel testo JSON del risultato e contiene il percorso del file di output del comando.

• Per leggere l'output prodotto finora: apri il file in quel percorso dal tuo client, oppure passa il percorso come file_path allo strumento Read del server
• Per capire quando il comando è terminato: aggiungi in coda al valore di command un echo di una stringa fissa, come in npm test; echo DONE. Il comando è terminato quando quella stringa compare nel file. Senza la stringa, nulla ne segnala la fine, perché Claude Code non aggiunge alcuna riga di chiusura al file e non notifica il tuo client.
• Per leggere la fine di un output lungo: Read con il solo file_path restituisce la prima pagina, oppure fallisce quando il file supera il limite di dimensione. Passa anche offset e limit, cosa che funziona con qualsiasi dimensione del file:
  1. Chiama Read con offset e limit entrambi impostati a 1, e prendi totalLines dal risultato
  2. Chiama di nuovo Read con offset impostato a totalLines meno nove e limit impostato a 10
  3. Cerca la tua stringa echo nelle ultime dieci righe, restituite dalla seconda chiamata

Il campo backgroundOutputPath richiede Claude Code v2.1.295 o successivo.

Limiti di output MCP e avvisi

Quando gli strumenti MCP producono output di grandi dimensioni, Claude Code aiuta a gestire l'utilizzo dei token per evitare di sovraccaricare il contesto della conversazione:

• Soglia di avviso di output: Claude Code visualizza un avviso quando l'output di qualsiasi strumento MCP supera 10.000 token
• Limite configurabile: puoi regolare il numero massimo di token di output MCP consentiti utilizzando la variabile d'ambiente MAX_MCP_OUTPUT_TOKENS
• Limite predefinito: il massimo predefinito è 25.000 token
• Ambito: la variabile d'ambiente si applica agli strumenti che non dichiarano il proprio limite. Gli strumenti che impostano anthropic/maxResultSizeChars utilizzano invece quel valore per il contenuto di testo, indipendentemente dal valore impostato per MAX_MCP_OUTPUT_TOKENS. Gli strumenti che restituiscono dati di immagine sono comunque soggetti a MAX_MCP_OUTPUT_TOKENS
• Oltre il limite: quando un risultato riuscito senza contenuto di immagine supera il limite di token, Claude Code lo salva in un file e lo sostituisce nella conversazione con un messaggio che nomina il percorso del file, in modo che Claude legga il file quando ha bisogno del contenuto. Il file si trova nella directory tool-results della sessione sotto ~/.claude/projects/.
• Dimensione della risposta dai server HTTP e SSE: quando una risposta da un server HTTP o SSE supera i 16 MiB, Claude Code smette di leggerla e la richiesta non riesce. Il limite si applica dopo la decompressione a un singolo corpo di risposta JSON o a un singolo evento di un flusso di eventi. Se gestisci il server, restituisci meno dati per risposta per rimanere sotto il limite, ad esempio impaginando i risultati
• Dimensione dei messaggi dai server WebSocket: quando un server WebSocket invia un singolo messaggio di oltre 16 MiB, Claude Code chiude la connessione e le chiamate in corso su quel server non riescono. Se gestisci il server, restituisci meno dati per messaggio per rimanere sotto il limite

Una chiamata che Claude Code ha spostato in un'attività in background riporta il proprio risultato tramite la notifica dell'attività. A una chiamata che si completa in primo piano si applicano altri due limiti:

• Limite di caratteri per i risultati di testo: per uno strumento che non dichiara anthropic/maxResultSizeChars, Claude Code salva in un file un risultato riuscito senza contenuto di immagine quando supera i 50.000 caratteri, indipendentemente dal numero di token. L'impostazione di MAX_MCP_OUTPUT_TOKENS non modifica questa soglia
• Risultati di errore: quando uno strumento restituisce un risultato contrassegnato con isError: true, Claude riceve il testo del risultato come messaggio di errore dello strumento. Di un testo di errore più lungo di circa 11.000 caratteri vengono mantenuti solo i primi 5.000 e gli ultimi 5.000 caratteri, con un indicatore tra di essi che riporta quanti caratteri sono stati rimossi

Per modificare il limite di token, imposta MAX_MCP_OUTPUT_TOKENS nella tua shell prima di avviare Claude Code:

export MAX_MCP_OUTPUT_TOKENS=50000
claude

Aumentare il limite per uno strumento specifico

Se stai creando un server MCP, puoi consentire ai singoli strumenti di restituire risultati più grandi della soglia predefinita di persistenza su disco di 50.000 caratteri impostando _meta["anthropic/maxResultSizeChars"] nella voce di risposta tools/list dello strumento. Claude Code aumenta la soglia di quello strumento al valore annotato, fino a un limite massimo di 500.000 caratteri.

Questo è utile per gli strumenti che restituiscono output intrinsecamente grandi ma necessari, come schemi di database o alberi di file completi. Senza l'annotazione, i risultati riusciti che superano la soglia predefinita vengono persistiti su disco e sostituiti con un riferimento a file nella conversazione.

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

L'annotazione si applica indipendentemente da MAX_MCP_OUTPUT_TOKENS per il contenuto di testo, quindi gli utenti non hanno bisogno di aumentare la variabile d'ambiente per gli strumenti che la dichiarano. Gli strumenti che restituiscono dati di immagine sono comunque soggetti al limite di token.

Immagini nei risultati degli strumenti

Quando uno strumento MCP restituisce un'immagine PNG, JPEG, GIF o WebP, Claude vede l'immagine inline nella conversazione. La copia inline può essere ridimensionata o compressa per adattarsi ai limiti di dimensione dell'immagine del modello. Claude Code salva anche i byte originali in un file nella directory tool-results della sessione sotto ~/.claude/projects/ e fornisce a Claude il percorso. Claude può quindi ritagliare, convertire o riutilizzare il file a risoluzione completa con strumenti come Bash.

Se disabiliti la persistenza della sessione con --no-session-persistence o CLAUDE_CODE_SKIP_PROMPT_HISTORY, Claude Code non scrive alcun file di immagine e Claude riceve solo la copia inline.

Il salvataggio dei risultati delle immagini MCP in un file richiede Claude Code v2.1.283 o versioni successive.

Tool input schemas con un combinatore a livello radice

Alcuni server MCP dichiarano lo schema di input di uno strumento come un'unione JSON Schema, con anyOf, oneOf, o allOf al livello superiore dello schema. L'API Claude non accetta queste parole chiave alla radice dello schema. Accetta combinatori annidati all'interno di properties, che Claude Code invia invariati.

Gli strumenti con un combinatore a livello radice rimangono disponibili. Prima di inviare lo strumento all'API, Claude Code appiattisce lo schema in un singolo oggetto e antepone una frase alla descrizione dello strumento che dice a Claude quali gruppi di parametri appartengono insieme:

• allOf: le proprietà di ogni ramo vengono unite, e l'elenco required di ogni ramo si applica ancora
• anyOf e oneOf: le proprietà di ogni ramo vengono unite, e l'elenco required di ogni ramo viene descritto nella descrizione dello strumento invece di essere applicato dallo schema

Il server riceve gli argomenti che Claude ha scelto, quindi continuate a convalidare la combinazione lato server.

Quando Claude Code non riesce a produrre uno schema che l'API accetta, o su una distribuzione che non riceve la configurazione remota che abilita la riscrittura, salta quello strumento, registra il motivo nel log del server e lascia disponibili gli altri strumenti del server.

Strumenti con schemi di input non validi

[!NOTE]

Se la tua sessione fallisce con un errore 400 che nomina uno strumento in base alla sua posizione, segui i passaggi in Tool input schema is invalid.

Se uno degli strumenti del tuo server MCP ha uno schema di input che viola una delle due regole imposte dall'API, Claude Code esclude quello strumento. Gli altri strumenti del server non ne risentono. Claude Code verifica entrambe le regole mentre carica gli strumenti del server:

• I nomi delle proprietà di primo livello devono essere lunghi da 1 a 64 caratteri e utilizzare solo lettere ASCII e cifre, _, . e -
• Lo schema deve essere valido rispetto al meta-schema JSON Schema draft 2020-12. Claude Code applica questo controllo agli schemi che non dichiarano alcun $schema e agli schemi che dichiarano draft 2020-12. Uno schema che dichiara qualsiasi altro dialetto salta questo controllo, anche se il controllo del nome della proprietà sopra indicato si applica comunque

Quando Claude Code esclude uno strumento, registra il motivo nel log del server e comunica a Claude quali strumenti ha escluso e perché, in modo che tu possa chiedere a Claude perché uno strumento manca. Se correggi lo schema sul server, lo strumento riappare la prossima volta che Claude Code carica gli strumenti del server.

Quando il recupero dei feature flag è disattivato o i flag non sono mai arrivati, come su una macchina air-gapped, uno strumento che viola una regola non viene escluso:

• Claude riceve lo strumento invariato e il log del server registra input schema would be rejected by the Anthropic API per quello strumento
• Se poi l'API rifiuta lo schema, consulta Strumenti il cui schema di input viene rifiutato dall'API

Prima della v2.1.216, nessuna distribuzione eseguiva questi controlli.

La gestione del combinatore a livello di root è separata e mantiene il suo comportamento quando il recupero dei flag è disattivato o i flag non sono mai arrivati.

Strumenti il cui schema di input viene rifiutato dall'API

Se una riga nel log di debug contiene the API refused this tool's input schema, nomina uno strumento il cui schema è stato rifiutato dall'API in una richiesta. Claude Code invia di nuovo quella richiesta con lo strumento dichiarato senza parametri.

• Se la tua sessione fallisce con un errore 400 che nomina uno strumento in base alla sua posizione: segui i passaggi in Tool input schema is invalid
• Se usi il server: non devi fare nulla. Claude può comunque chiamare lo strumento, ma non ne vede i parametri
• Se gestisci il server: correggi lo schema di input dello strumento sul server. La riga del log termina con The API said: seguito dal motivo per cui l'API ha rifiutato lo schema. Convalida gli argomenti che il server riceve, perché Claude chiama lo strumento senza vederne i parametri

Prima della v2.1.300, ogni turno che includeva lo schema rifiutato falliva con un errore 400 che nomina lo strumento in base alla sua posizione.

Strumenti con nomi più lunghi di 128 caratteri

Se /mcp elenca uno strumento che Claude non riesce a chiamare, verifica se il nome completo dello strumento supera i 128 caratteri. Esegui /mcp nella tua sessione e seleziona lo strumento per vederne il nome completo, ad esempio mcp__<server>__<tool>. Claude Code esclude uno strumento MCP dagli strumenti che invia a Claude quando il suo nome completo supera i 128 caratteri. La Claude API rifiuta una richiesta che include uno strumento di questo tipo, quindi escluderlo permette agli altri strumenti del server di continuare a funzionare.

Per il messaggio che indica lo strumento e i modi per abbreviarne il nome completo, consulta MCP tool name over 128 characters.

Richiedere l'approvazione per uno strumento specifico

Se stai creando un server MCP, puoi contrassegnare uno strumento come soggetto ad approvazione esplicita a ogni chiamata impostando _meta["anthropic/requiresUserInteraction"] a true nella voce dello strumento all'interno della risposta tools/list. Il valore deve essere il booleano JSON true; qualsiasi altro valore viene ignorato.

Claude Code mostra la richiesta di permesso di quello strumento a ogni chiamata, anche nelle modalità di permesso acceptEdits, auto e bypassPermissions, e non offre per esso un'opzione "non chiedere più". Nemmeno le regole allow che corrispondono allo strumento permettono di saltare la richiesta. In modalità dontAsk, che non chiede mai nulla, Claude Code invece nega la chiamata.

La richiesta deve raggiungere una persona. In modalità non interattiva con --permission-prompt-tool, un risultato allow restituito dallo strumento di prompt per uno strumento contrassegnato viene convertito in un rifiuto con il messaggio MCP tool requires user interaction; not supported via --permission-prompt-tool. Il callback canUseTool dell'Agent SDK invece riceve queste chiamate e può approvarle, perché ci si aspetta che la tua applicazione SDK le mostri a un utente.

Usa questa funzionalità per gli strumenti la cui richiesta di permesso è proprio lo scopo, come un passaggio di consenso o di concessione dell'accesso in cui l'approvazione automatica significherebbe che nessun essere umano ha mai dato il proprio consenso. Gli altri strumenti dello stesso server mantengono il normale comportamento dei permessi.

La seguente voce tools/list contrassegna uno strumento come sempre soggetto ad approvazione.

{
  "name": "grant_access",
  "description": "Requests access to a protected resource",
  "_meta": {
    "anthropic/requiresUserInteraction": true
  }
}

Alcune superfici, come Remote Control e le applicazioni create con l'Agent SDK, normalmente ti permettono di approvare le chiamate agli strumenti con un solo tocco. Per uno strumento contrassegnato con questa annotazione, Claude Code non offre l'azione a un tocco e mostra invece la richiesta di permesso completa dello strumento, così l'approvazione arriva comunque da una persona che risponde alla richiesta anziché da un tocco.

Claude Code non offre l'approvazione a un tocco, allo stesso modo, per qualsiasi richiesta di permesso che solo la finestra di dialogo del terminale può visualizzare per intero, come una che include un avviso di sicurezza o un'opzione "consenti sempre" che la superficie remota non può mostrare. Rispondi a quella richiesta nella finestra di dialogo del terminale anziché da Remote Control.

Contrassegnare gli strumenti che è sicuro chiamare due volte

Se crei un server MCP, contrassegna gli strumenti che è sicuro chiamare due volte, in modo che Claude Code possa ripetere una chiamata rimasta in sospeso quando una connessione si è chiusa. Claude Code può ripetere una chiamata di questo tipo a un server HTTP o a un connettore claude.ai una sola volta, su una nuova connessione. Una chiamata che Claude Code non ripete può fallire con connection closed before the tool call was answered.

Per contrassegnare uno strumento, imposta una di queste annotations su true nella sua voce tools/list:

• idempotentHint: lo strumento può modificare qualcosa, e chiamarlo di nuovo con gli stessi argomenti è sicuro
• readOnlyHint: lo strumento non modifica nulla. Claude Code esegue inoltre le chiamate allo strumento in parallelo con altre chiamate di sola lettura.

Ad esempio, questi campi in una voce tools/list contrassegnano lo strumento set_issue_status come sicuro da ripetere:

{
  "name": "set_issue_status",
  "annotations": {
    "idempotentHint": true
  }
}

Rispondere alle richieste di elicitazione MCP

I server MCP possono richiederti input strutturato durante un'attività utilizzando l'elicitazione. Quando un server ha bisogno di informazioni che non può ottenere da solo, Claude Code visualizza una finestra di dialogo interattiva nel terminale e trasmette la tua risposta al server. Non è richiesta alcuna configurazione da parte tua: le finestre di dialogo di elicitazione vengono visualizzate automaticamente quando un server le richiede.

I server possono richiedere input in due modi:

• Modalità modulo: Claude Code mostra una finestra di dialogo con campi modulo definiti dal server (ad esempio, un prompt di nome utente e password). Compilate i campi e inviate.
• Modalità URL: Claude Code chiede se aprire un collegamento nel tuo browser. I server utilizzano questa modalità per un flusso che si conclude al di fuori del terminale, come l'accesso.

In modalità URL, Claude Code trasmette l'URL come argomento della riga di comando al gestore URL del vostro sistema e limita la lunghezza di tale argomento. Quando l'URL, una volta sottoposto a escape per la riga di comando, supera tale limite, potete solo rifiutare la richiesta. Ogni carattere che necessita di escape, come % o &, conta quattro volte verso il limite: il suo carattere più tre caratteri di escape. Un URL senza nessuno di essi raggiunge il limite a circa 8.000 caratteri. Un URL costruito principalmente con escape percentuali, dove ogni terzo carattere è un %, lo raggiunge a circa 4.000.

Per rispondere automaticamente alle richieste di elicitazione senza mostrare una finestra di dialogo, utilizzate l'hook Elicitation.

Se state creando un server MCP che utilizza l'elicitazione, consultate la specifica di elicitazione MCP per i dettagli del protocollo e gli esempi di schema.

Rispondere a una richiesta di elicitazione in una sessione cloud

Quando l'attività di Claude nella tua sessione cloud è in attesa della richiesta di un server MCP, il server ha bisogno di qualcosa da te, come un valore o un accesso. Se la richiesta appare come una scheda su claude.ai/code o nella scheda Code dell'app Desktop, rispondi sulla scheda:

• Modalità modulo: compila i campi, quindi fai clic su Submit
• Modalità URL: fai clic su Open link, completa il flusso che si apre, quindi fai clic su I’m done, continue sulla scheda

Per rifiutare la richiesta, fai clic su Decline. Claude prosegue non appena il server risponde.

Se non vedi alcuna scheda in nessuno dei due punti, non puoi rispondere alla richiesta lì. Nella tua sessione, fai clic sul pulsante di interruzione per terminare il turno.

Modalità di elicitazione dichiarate da Claude Code

Se crei un server MCP, le capacità client che Claude Code invia quando si connette indicano al tuo server quali modalità di elicitazione può richiedere. Claude Code dichiara elicitation: {form: {}, url: {}} sulle seguenti connessioni, quindi un server su una qualsiasi di esse può richiedere entrambe le modalità:

• Connessioni che utilizzano la revisione del protocollo 2026-07-28
• Connessioni sulle revisioni precedenti del protocollo, 2025-11-25 e anteriori, ai server stdio, sse, http e ws presenti nella configurazione MCP di Claude Code di un utente. Richiede Claude Code v2.1.287 o versioni successive

Sulle sue altre connessioni con le revisioni precedenti, come quelle ai connettori di claude.ai, Claude Code dichiara il semplice elicitation: {}, che consente richieste di elicitazione solo in modalità modulo.

Un server basato su Java MCP SDK 0.17.0 o versioni precedenti può rifiutare una dichiarazione che contiene form e url. Consulta MCP server rejected the elicitation capability.

Utilizzare le risorse MCP

I server MCP possono esporre risorse che è possibile referenziare utilizzando menzioni @, in modo simile a come si referenziano i file.

Referenziare le risorse MCP

1. Elencare le risorse disponibili

Digiti @ nel suo prompt per visualizzare le risorse disponibili da tutti i server MCP connessi. Le risorse vengono visualizzate insieme ai file nel menu di completamento automatico.

2. Referenziare una risorsa specifica

Utilizzi il formato @server:protocol://resource/path per referenziare una risorsa:

Can you analyze @github:issue://123 and suggest a fix?

Please review the API documentation at @docs:file://api/authentication

3. Riferimenti a risorse multiple

È possibile referenziare più risorse in un singolo prompt:

Compare @postgres:schema://users with @docs:file://database/user-model

[!TIP]

Suggerimenti:

• Le risorse vengono recuperate automaticamente e incluse come allegati quando referenziate
• I percorsi delle risorse sono ricercabili in modo fuzzy nel completamento automatico della menzione @
• Claude Code fornisce automaticamente strumenti per elencare e leggere le risorse MCP quando i server le supportano
• Le risorse possono contenere qualsiasi tipo di contenuto fornito dal server MCP (testo, JSON, dati strutturati, ecc.)

Le risorse dell'interfaccia utente delle app MCP sono voci con un URI ui:// o il tipo di media text/html;profile=mcp-app: pagine per un'applicazione host da renderizzare piuttosto che contenuti per Claude da leggere. Non vengono visualizzate nei suggerimenti @ o nei risultati dello strumento di elenco delle risorse, e un server che offre solo risorse dell'interfaccia utente mostra un elenco di risorse vuoto. La lettura di una risorsa dell'interfaccia utente tramite il suo URI funziona comunque.

Scalare con la ricerca di strumenti MCP

La ricerca di strumenti mantiene basso l'utilizzo del contesto MCP rimandando le definizioni degli strumenti fino a quando Claude non ne ha bisogno. Solo i nomi degli strumenti e le istruzioni del server si caricano all'inizio della sessione, quindi aggiungere più server MCP ha un impatto minimo sulla finestra di contesto. Claude Code non impone un limite fisso di strumenti per server; il limite pratico è il budget della finestra di contesto.

[!NOTE]

La ricerca di strumenti non è supportata sui deploy di Microsoft Foundry ospitati su Azure, che la rifiutano lato server: Claude Code rileva il rifiuto e carica invece gli strumenti MCP in anticipo per quel deploy. ENABLE_TOOL_SEARCH non può sovrascrivere questo comportamento, poiché il rifiuto proviene dal deploy stesso.

Ricerca di strumenti per gli autori di server MCP

Se stai creando un server MCP, il campo delle istruzioni del server diventa più utile con la ricerca di strumenti abilitata. Le istruzioni del server aiutano Claude a capire quando cercare i tuoi strumenti, in modo simile a come funzionano le skill.

Aggiungi istruzioni del server chiare e descrittive che spieghino:

• Quale categoria di attività gestiscono i tuoi strumenti
• Quando Claude dovrebbe cercare i tuoi strumenti
• Capacità chiave che il tuo server fornisce

Claude Code tronca una descrizione di strumento o le istruzioni del server che superano questi limiti predefiniti, e Claude vede solo il testo prima del taglio:

• Istruzioni del server e descrizione di uno strumento caricato in anticipo: 4.096 caratteri
• Descrizione di uno strumento che Claude carica tramite la ricerca di strumenti: 16.384 caratteri

Mantieni concise le descrizioni e le istruzioni e metti i dettagli critici all'inizio. Quando la ricerca di strumenti confronta la query di Claude con la descrizione di uno strumento, legge solo la parte entro il limite più breve, quindi metti all'inizio anche le parole che Claude cercherebbe. Uno strumento viene caricato in anticipo e mantiene il limite più breve ogni volta che non è rimandato, ad esempio quando la ricerca di strumenti è disattivata, quando lo strumento è contrassegnato per il caricamento anticipato o quando il suo server è esentato dal rinvio.

Prima della v2.1.296, il limite più breve era di 2.048 caratteri, e prima della v2.1.295 si applicava a ogni descrizione di strumento, incluse quelle caricate tramite la ricerca di strumenti.

Modificare i limiti di lunghezza delle descrizioni

Per modificare i limiti predefiniti di 4.096 e 16.384 caratteri per i server MCP nella tua sessione, imposta CLAUDE_CODE_MAX_MCP_DESCRIPTION_LENGTH a un numero di caratteri. Claude Code usa quel numero per entrambi i limiti. Con 8192, ad esempio, alzi il limite di 4.096 caratteri sulle istruzioni del server e sulle descrizioni degli strumenti caricati in anticipo, e abbassi il limite di 16.384 caratteri sulle descrizioni degli strumenti caricati tramite la ricerca di strumenti. Questa variabile richiede Claude Code v2.1.280 o successivo.

Le descrizioni e le istruzioni di alcuni dei server MCP che Anthropic ospita su api.anthropic.com arrivano a Claude per intero, e impostare questa variabile non le tronca.

Contrassegnare uno strumento da caricare in anticipo o da mantenere rimandato

Per controllare come viene caricato uno degli strumenti del tuo server, imposta "anthropic/alwaysLoad" nell'oggetto _meta di quello strumento. Chi aggiunge il tuo server a Claude Code può anche impostare alwaysLoad per l'intero server nella propria configurazione, e la sua impostazione può sovrascrivere la tua:

La seguente voce tools/list chiede che uno strumento venga caricato in anticipo:

{
  "name": "search_tickets",
  "description": "Searches the ticket tracker by keyword",
  "_meta": {
    "anthropic/alwaysLoad": true
  }
}

Configurare la ricerca di strumenti

La ricerca di strumenti è abilitata per impostazione predefinita: gli strumenti MCP vengono rimandati e scoperti su richiesta.

L'impostazione CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS mantiene la ricerca di strumenti disattivata. Non puoi sovrascriverla impostando tu stesso ENABLE_TOOL_SEARCH. Su Claude Code v2.1.227 o successivo, la tua organizzazione può mantenere attiva la ricerca di strumenti anche con questa variabile impostata, tramite le impostazioni gestite. In una sessione che riceve la configurazione HIPAA, la ricerca di strumenti è disattivata, e né ENABLE_TOOL_SEARCH né le impostazioni gestite la riattivano. Disabilitare le capacità pre-release spiega dove si applica l'override e cosa rimuove la variabile.

Claude Code usa la ricerca di strumenti su Claude Opus 4, Claude Sonnet 4, Claude Haiku 4.5 e modelli successivi, oppure su Opus 4.5, Sonnet 4.5, Haiku 4.5 e modelli successivi su Google Cloud's Agent Platform. Sui modelli precedenti, Claude Code carica tutti gli strumenti MCP in anticipo, e ENABLE_TOOL_SEARCH=true non sovrascrive questo comportamento.

Su Google Cloud's Agent Platform, Claude Code decide in base alla generazione del modello:

• Claude Opus 4.5, Sonnet 4.5, Haiku 4.5 e successivi: la ricerca di strumenti è attiva per impostazione predefinita, come su Anthropic API.
• 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.

Controlla il comportamento della ricerca di strumenti con la variabile d'ambiente ENABLE_TOOL_SEARCH:

# Usa una soglia personalizzata del 5%
ENABLE_TOOL_SEARCH=auto:5 claude

# Disabilita completamente la ricerca di strumenti
ENABLE_TOOL_SEARCH=false claude

Oppure imposta il valore nel campo env di settings.json.

Puoi anche disabilitare specificamente lo strumento ToolSearch:

{
  "permissions": {
    "deny": ["ToolSearch"]
  }
}

Se neghi ToolSearch o lo escludi da --tools, gli strumenti MCP vengono invece caricati in anticipo, ma una richiesta può comunque contenere una voce segnaposto defer_loading. Se un gateway rifiuta quella voce, consulta Ricerca di strumenti tramite un gateway LLM.

Ricerca di strumenti tramite un gateway LLM

[!NOTE]

Questi casi sono trattati altrove:

• Hai impostato CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS: consulta come influisce sulla ricerca di strumenti
• Una richiesta è fallita con un errore che menziona defer_loading o tool_reference: consulta Extra inputs are not permitted

Quando ANTHROPIC_BASE_URL punta a un gateway, Claude Code si aspetta che il gateway inoltri i campi degli strumenti defer_loading e i blocchi tool_reference insieme all'intestazione anthropic-beta. La ricerca di strumenti è attiva per impostazione predefinita dietro il gateway, quindi gli strumenti MCP vengono rimandati e le richieste includono quei campi e blocchi. Prima della v2.1.304, la ricerca di strumenti era disattivata dietro un gateway a meno che ENABLE_TOOL_SEARCH non fosse true, auto o auto:N.

Su v2.1.305 o successivo, Claude Code può riprovare una richiesta senza la ricerca di strumenti dopo un 400 o 422. Quando il nuovo tentativo riesce, sullo schermo non appare nulla e non devi fare niente: gli strumenti MCP vengono invece caricati in anticipo. Claude Code riprova la ricerca di strumenti più tardi, al costo di un'altra richiesta rifiutata.

Strumenti che restano rimandati sotto la soglia ENABLE_TOOL_SEARCH=auto

Se /context etichetta gli strumenti come (deferred) o (loaded on-demand) anche se le loro definizioni totalizzano meno della soglia auto, la ricerca di strumenti era già attiva in questa conversazione ed è rimasta attiva. Il totale può diminuire in seguito, ad esempio mentre i server MCP si riconnettono dopo che riprendi una sessione. Non devi fare niente: Claude carica ciascuno di quegli strumenti quando un'attività ne ha bisogno.

Esentare un server dal rinvio

Se gli strumenti di un server dovrebbero essere sempre visibili a Claude senza un passaggio di ricerca, imposta alwaysLoad a true nella configurazione di quel server. Gli strumenti del server vengono quindi caricati nel contesto indipendentemente dall'impostazione ENABLE_TOOL_SEARCH. Usa questa opzione per un piccolo numero di strumenti di cui Claude ha bisogno a ogni turno, poiché ogni strumento caricato in anticipo consuma contesto che altrimenti sarebbe disponibile per la tua conversazione.

La seguente voce .mcp.json esenta un server HTTP lasciando rimandati gli altri server:

{
  "mcpServers": {
    "core-tools": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "alwaysLoad": true
    }
  }
}

Il campo alwaysLoad è disponibile su tutti i tipi di server.

L'impostazione alwaysLoad: true fa anche sì che l'avvio attenda gli strumenti del server, entro il timeout di connessione standard di 5 secondi, poiché devono essere presenti quando viene costruito il primo prompt. Un server remoto con una voce cached valida fornisce i suoi strumenti dalla cache senza connettersi, quindi non ritarda l'avvio. Gli altri server si connettono in background per impostazione predefinita; imposta MCP_CONNECTION_NONBLOCKING=0 per far sì che l'avvio attenda anche loro.

Rimandare gli strumenti di un server

Per mantenere tutti gli strumenti di un server dietro la ricerca di strumenti, imposta "alwaysLoad": false nella voce di quel server nella tua configurazione MCP. Questo include gli strumenti che l'autore del server ha contrassegnato per il caricamento anticipato. Se ometti alwaysLoad, quegli strumenti contrassegnati vengono caricati in anticipo. Richiede Claude Code v2.1.287 o successivo.

Usa i prompt MCP come comandi

I server MCP possono esporre prompt che diventano disponibili come comandi in Claude Code.

I prompt da un server denominato anthropic-skills non vengono visualizzati, perché Claude Code riserva quel nome per le skills sincronizzate da claude.ai. Gli strumenti del server funzionano comunque. Rinomina il server nella tua configurazione MCP per elencare i suoi prompt.

Esegui i prompt MCP

1. Scopri i prompt disponibili

Digita / per vedere i comandi disponibili, inclusi quelli dai server MCP. Claude Code elenca ogni prompt MCP come /servername:promptname (MCP). Digitando /mcp__servername__promptname lo esegui anche.

2. Esegui un prompt senza argomenti

/mcp__github__list_prs

3. Esegui un prompt con argomenti

Molti prompt accettano argomenti. Passali separati da spazi dopo il comando. Claude Code divide gli argomenti su spazi bianchi, quindi ogni argomento è un singolo token:

/mcp__github__pr_review 456

/mcp__jira__create_issue login-bug high

[!TIP]

Suggerimenti:

• I prompt MCP vengono scoperti dinamicamente dai server connessi
• Gli argomenti vengono analizzati in base ai parametri definiti del prompt
• I risultati del prompt vengono iniettati direttamente nella conversazione
• Nel modulo /mcp__servername__promptname, Claude Code sostituisce qualsiasi carattere nel nome del server al di fuori di A-Z, a-z, 0-9, _ e - con _, e utilizza il nome del prompt come dichiarato dal server

Configurazione MCP gestita

Per le organizzazioni che necessitano di un controllo centralizzato su quali server MCP gli utenti possono connettere, vedere Configurazione MCP gestita. Copre la distribuzione di un set di server fisso con managed-mcp.json, la fornitura di server a ogni utente con managedMcpServers, la restrizione dei server con allowedMcpServers e deniedMcpServers, e ciò che gli utenti vedono quando un server è bloccato.