> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 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)](https://modelcontextprotocol.io/introduction), 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](/it/mcp-quickstart) 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](/it/channels) 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](https://claude.ai/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`.
Verifica di fidarti di ogni server prima di collegarlo. I server che recuperano contenuti esterni possono esporti al rischio di [prompt injection](/it/security#protect-against-prompt-injection).
Per costruire il tuo server, consulta la [guida al server MCP](https://modelcontextprotocol.io/docs/develop/build-server) per i fondamenti del protocollo e la [documentazione sulla creazione di connettori Claude](https://claude.com/docs/connectors/building) 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`](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/mcp-server-dev).
In una sessione Claude Code, esegui:
```
/plugin install mcp-server-dev@claude-plugins-official
```
Se Claude Code segnala che il marketplace non è stato trovato, esegui prima `/plugin marketplace add anthropics/claude-plugins-official`, quindi riprova l'installazione. Una volta installato, esegui `/reload-plugins` per attivarlo nella sessione corrente.
```
/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 vostre esigenze:
Opzione 1: Aggiungi un server HTTP remoto
I server HTTP sono l'opzione consigliata per connettersi ai server MCP remoti. Questo è il trasporto più ampiamente supportato per i servizi basati su cloud.
```bash theme={null}
# Sintassi di base
claude mcp add --transport http
# Esempio reale: Connessione a Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp
# Esempio con token Bearer
claude mcp add --transport http secure-api https://api.example.com/mcp \
--header "Authorization: Bearer your-token"
```
Quando si configurano i server MCP tramite JSON in `.mcp.json`, `~/.claude.json`, o `claude mcp add-json`, il campo `type` accetta `streamable-http` come alias per `http`. La specifica MCP utilizza il nome `streamable-http` per questo trasporto, quindi le configurazioni copiate dalla documentazione del server funzionano senza modifiche.
Opzione 2: Aggiungi un server SSE remoto
Il trasporto SSE (Server-Sent Events) è deprecato. Utilizza server HTTP invece, dove disponibili.
```bash theme={null}
# Sintassi di base
claude mcp add --transport sse
# Esempio reale: Connessione ad Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse
# Esempio con header di autenticazione
claude mcp add --transport sse private-api https://api.company.com/sse \
--header "X-API-Key: your-key-here"
```
Opzione 3: Aggiungi un server stdio locale
I server stdio vengono eseguiti come processi locali sulla vostra macchina. Sono ideali per strumenti che necessitano di accesso diretto al sistema o script personalizzati.
Claude Code imposta `CLAUDE_PROJECT_DIR` nell'ambiente del server generato alla radice del progetto, in modo che il vostro server possa risolvere i percorsi relativi al progetto senza dipendere dalla directory di lavoro. Questa è la stessa directory che gli hook ricevono nella loro variabile `CLAUDE_PROJECT_DIR`. Leggetela dall'interno del vostro processo server, ad esempio `process.env.CLAUDE_PROJECT_DIR` in Node o `os.environ["CLAUDE_PROJECT_DIR"]` in Python.
Il vostro server può anche chiamare la richiesta MCP `roots/list`, che restituisce la directory da cui Claude Code è stato avviato.
Questa variabile è impostata nell'ambiente del server, non nell'ambiente di Claude Code stesso, quindi farvi riferimento tramite l'espansione `${VAR}` in un `.mcp.json` con ambito progetto o utente `command` o `args` richiede un valore predefinito come `${CLAUDE_PROJECT_DIR:-.}`. Le configurazioni MCP fornite da plugin sostituiscono `${CLAUDE_PROJECT_DIR}` direttamente e non hanno bisogno del valore predefinito.
```bash theme={null}
# Sintassi di base
claude mcp add [options] -- [args...]
# Esempio reale: Aggiungi server Airtable
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
-- npx -y airtable-mcp-server
```
**Importante: Separare gli argomenti del server con `--`**
Per i server stdio, il `--` (doppio trattino) separa le opzioni di Claude, come `--transport`, `--env`, e `--scope`, dal comando e dagli argomenti che eseguono il server. Tutto ciò che viene dopo `--` viene passato al server senza modifiche.
Per 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 analizzare i flag del server, come `--port` sopra, come proprie opzioni.
`--env` accetta più coppie `KEY=value`. Se il nome del server viene direttamente dopo `--env`, la CLI legge il nome come un'altra coppia e lo rifiuta, quindi posizionate almeno un'altra opzione tra `--env` e il nome del server, come negli esempi sopra.
Opzione 4: Aggiungi un server WebSocket remoto
I server WebSocket mantengono una connessione bidirezionale persistente, che si adatta ai server MCP remoti che inviano eventi a Claude senza sollecitazione. Utilizza HTTP invece quando il vostro server risponde solo alle richieste, poiché HTTP supporta OAuth e il flag `claude mcp add --transport`, mentre WebSocket non supporta nessuno dei due.
Configura i server WebSocket in `.mcp.json` o con `claude mcp add-json`:
```bash theme={null}
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 è solo tramite header, quindi passa un token statico in `headers` o generane uno al momento della connessione con [`headersHelper`](#use-dynamic-headers-for-custom-authentication). Il flag `claude mcp add --transport` non accetta `ws`.
Gestione dei vostri server
Una volta configurati, potete gestire i vostri server MCP con questi comandi:
```bash theme={null}
# Elenca tutti i server configurati
claude mcp list
# Ottieni dettagli per un server specifico
claude mcp get github
# Rimuovi un server
claude mcp remove github
# (all'interno di Claude Code) Controlla lo stato del server
/mcp
```
I server con ambito progetto da `.mcp.json` che sono in attesa della vostra approvazione appaiono in `claude mcp list` come `⏸ Pending approval`. Esegui `claude` in modo interattivo per esaminarli e approvarli. `claude mcp get ` mostra i server in sospeso come `⏸ Pending approval` e i server rifiutati come `✗ Rejected`.
A partire dalla v2.1.196, `claude mcp list` e `claude mcp get` leggono le approvazioni `.mcp.json` solo dai file di impostazioni che non sono archiviati nel repository finché non fidate dell'area di lavoro eseguendo `claude` in essa e accettando la finestra di dialogo di trust dell'area di lavoro. Un repository clonato non può approvare i propri server: [`enableAllProjectMcpServers` o `enabledMcpjsonServers`](/it/settings#available-settings) committati nel `.claude/settings.json` del progetto vengono ignorati in una cartella non attendibile, e il server rimane a `⏸ Pending approval` invece di essere connesso e sottoposto a health-check.
Le approvazioni da queste fonti si applicano ancora in una cartella non attendibile:
* il vostro `~/.claude/settings.json` utente
* impostazioni gestite
* impostazioni passate con `--settings`
* `.claude/settings.local.json`, purché git non lo traccia
Una voce `disabledMcpjsonServers` in qualsiasi file di impostazioni rifiuta comunque il server.
Il pannello `/mcp` mostra il conteggio degli strumenti accanto a ogni server connesso e contrassegna i server che pubblicizzano la capacità degli strumenti ma non espongono alcuno strumento.
Se la vostra richiesta ha bisogno di strumenti da un server che è ancora in fase di connessione in background, Claude attende quel server prima di continuare. Con la [ricerca degli strumenti](#scale-with-mcp-tool-search) abilitata, che è l'impostazione predefinita, l'attesa avviene all'interno della chiamata `ToolSearch`. Nelle configurazioni senza ricerca degli strumenti, come Vertex AI, un `ANTHROPIC_BASE_URL` personalizzato, o `ENABLE_TOOL_SEARCH=false`, Claude utilizza lo strumento `WaitForMcpServers` invece.
Il nome del server `workspace` è riservato per uso interno. Se la vostra configurazione definisce un server con quel nome, Claude Code lo salta al momento del caricamento e mostra un avviso chiedendovi di rinominarlo.
Claude Code supporta le notifiche `list_changed` di MCP, consentendo ai server MCP di aggiornare dinamicamente i loro strumenti, prompt e risorse disponibili senza richiedere di disconnettersi e riconnettersi. Quando un server MCP invia una notifica `list_changed`, Claude Code aggiorna automaticamente le capacità disponibili da quel server.
Riconnessione automatica
Se un server HTTP o SSE si disconnette durante una sessione, Claude Code si riconnette automaticamente con backoff esponenziale: fino a cinque tentativi, a partire da un ritardo di un secondo e raddoppiando ogni volta. Il server appare come in sospeso in `/mcp` mentre la riconnessione è in corso. Dopo cinque tentativi falliti il server è contrassegnato come non riuscito e potete riprovare manualmente da `/mcp`. I server stdio sono processi locali e non vengono riconnessi automaticamente.
Lo stesso backoff si applica quando un server HTTP o SSE non riesce la sua connessione iniziale all'avvio. A partire dalla v2.1.121, Claude Code ritenta la connessione iniziale fino a tre volte su errori transitori come una risposta 5xx, una connessione rifiutata o un timeout, quindi contrassegna il server come non riuscito se ancora non riesce a connettersi. Gli errori di autenticazione e di non trovato non vengono ritentati perché richiedono una modifica della configurazione per essere risolti.
A partire dalla v2.1.191, le richieste di scoperta delle capacità che vengono eseguite dopo una connessione riuscita, come `tools/list`, `prompts/list`, e `resources/list`, ritentano anche gli errori di rete transitori e del server fino a tre volte con backoff breve. Gli errori di autenticazione, le risposte 4xx e i timeout delle richieste non vengono ritentati.
Invia messaggi con canali
Un server MCP può anche inviare messaggi direttamente nella vostra sessione in modo che Claude possa reagire a eventi esterni come risultati CI, avvisi di monitoraggio o messaggi di chat. Per abilitare questa funzionalità, il vostro server dichiara la capacità `claude/channel` e voi la abilitate con il flag `--channels` all'avvio. Vedi [Canali](/it/channels) per utilizzare un canale ufficialmente supportato, oppure [Riferimento canali](/it/channels-reference) per costruire il vostro.
Suggerimenti:
* Utilizza il flag `--scope` per specificare dove viene archiviata la configurazione:
* `local` (predefinito): disponibile solo per voi nel progetto corrente. Le versioni precedenti chiamavano questo ambito `project`
* `project`: condiviso con tutti nel progetto tramite il file `.mcp.json`
* `user`: disponibile per voi in tutti i progetti. Le versioni precedenti chiamavano questo ambito `global`
* Imposta le variabili di ambiente con i flag `--env` (per esempio, `--env KEY=value`)
* Configura il timeout di avvio del server MCP utilizzando la variabile di ambiente `MCP_TIMEOUT` (per esempio, `MCP_TIMEOUT=10000 claude` imposta un timeout di 10 secondi)
* Imposta un timeout di esecuzione dello strumento per server aggiungendo un campo `timeout` in millisecondi alla voce `.mcp.json` di quel server, per esempio `"timeout": 600000` per dieci minuti. Questo sostituisce la variabile di ambiente `MCP_TOOL_TIMEOUT` solo per quel server
* Claude Code visualizza un avviso quando l'output dello strumento MCP supera 10.000 token. Per aumentare questo limite, imposta la variabile di ambiente `MAX_MCP_OUTPUT_TOKENS` (per esempio, `MAX_MCP_OUTPUT_TOKENS=50000`)
* Utilizza `/mcp` per autenticarti con server remoti che richiedono l'autenticazione OAuth 2.0
Il timeout per server è un limite rigido di wall-clock per chiamata dello strumento, e le notifiche di progresso dal server non lo estendono. I valori inferiori a 1000 sono ignorati e ricadono in `MCP_TOOL_TIMEOUT`, o nel suo valore predefinito di circa 28 ore quando quella variabile non è impostata. {/* min-version: 2.1.162 */}Prima della v2.1.162, i valori inferiori a 1000 erano arrotondati a un secondo.
Per i server HTTP e SSE, il budget del primo byte per richiesta fetch ha un minimo di 60 secondi.
A partire dalla v2.1.187, una chiamata dello strumento a un server HTTP remoto, SSE, WebSocket, o [connettore claude.ai](#use-mcp-servers-from-claude-ai) che non invia alcuna risposta e nessuna notifica di progresso per 5 minuti si interrompe con un errore invece di attendere il limite di wall-clock. Imposta la variabile di ambiente [`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`](/it/env-vars) in millisecondi per modificare la finestra di inattività, o impostala su `0` per disabilitare il controllo. I server stdio sono processi locali e non sono soggetti al timeout di inattività.
Server MCP forniti da plugin
I [plugin](/it/plugins) possono raggruppare server MCP, fornendo automaticamente strumenti e integrazioni quando il plugin è abilitato. I server MCP dei plugin funzionano in modo identico ai server configurati dall'utente.
**Come funzionano i server MCP dei plugin**:
* I plugin definiscono i server MCP in `.mcp.json` nella radice del plugin o inline in `plugin.json`
* Quando un plugin è abilitato, i suoi server MCP si avviano automaticamente
* Gli strumenti MCP del plugin appaiono insieme agli strumenti MCP configurati manualmente
* I server dei plugin vengono gestiti tramite l'installazione del plugin, non tramite comandi `/mcp`
**Esempio di configurazione MCP del plugin**:
In `.mcp.json` nella radice del plugin:
```json theme={null}
{
"mcpServers": {
"database-tools": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server",
"args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"],
"env": {
"DB_URL": "${DB_URL}"
}
}
}
}
```
O inline in `plugin.json`:
```json theme={null}
{
"name": "my-plugin",
"mcpServers": {
"plugin-api": {
"command": "${CLAUDE_PLUGIN_ROOT}/servers/api-server",
"args": ["--port", "8080"]
}
}
}
```
**Funzionalità MCP del plugin**:
* **Ciclo di vita automatico**: all'avvio della sessione, i server per i plugin abilitati si connettono automaticamente. Se abilitate o disabilitate un plugin durante una sessione, eseguite `/reload-plugins` per connettere o disconnettere i suoi server MCP
* **Variabili di ambiente**: Utilizza `${CLAUDE_PLUGIN_ROOT}` per i file del plugin raggruppati, `${CLAUDE_PLUGIN_DATA}` per lo [stato persistente](/it/plugins-reference#persistent-data-directory) che sopravvive agli aggiornamenti del plugin, e `${CLAUDE_PROJECT_DIR}` per la radice stabile del progetto
* **Accesso alle variabili di ambiente dell'utente**: accesso alle stesse variabili di ambiente dei server configurati manualmente
* **Tipi di trasporto multipli**: supporto per trasporti stdio, SSE, HTTP e WebSocket, anche se il supporto del trasporto può variare a seconda del server
**Visualizzazione dei server MCP del plugin**:
```bash theme={null}
# All'interno di Claude Code, vedi tutti i server MCP inclusi quelli dei plugin
/mcp
```
I server dei plugin appaiono nell'elenco con indicatori che mostrano che provengono dai plugin.
**Nomi degli strumenti MCP del plugin**:
Gli strumenti da un server MCP raggruppato in un plugin includono sia il nome del plugin che la chiave del server nel loro nome richiamabile. La forma completa è `mcp__plugin____`, dove qualsiasi carattere al di fuori di `A-Z`, `a-z`, `0-9`, `_`, e `-` viene sostituito con `_`. Per il server `database-tools` raggruppato in un plugin denominato `my-plugin`, uno strumento `query` è richiamabile come:
```
mcp__plugin_my-plugin_database-tools__query
```
Utilizza questo nome completo quando fai riferimento allo strumento nelle [regole di autorizzazione](/it/permissions), nell'elenco `allowed-tools` di una skill, o nel [campo `tools` di un subagent](/it/sub-agents#available-tools).
**Vantaggi dei server MCP dei plugin**:
* **Distribuzione raggruppata**: strumenti e server confezionati insieme
* **Configurazione automatica**: nessuna configurazione MCP manuale necessaria
* **Coerenza del team**: tutti ottengono gli stessi strumenti quando il plugin è installato
Vedi il [riferimento dei componenti del plugin](/it/plugins-reference#mcp-servers) per i dettagli su come raggruppare i server MCP con i 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 server a livello aziendale tramite [configurazione gestita](#managed-mcp-configuration).
| Ambito | Carica in | Condiviso con il team | Archiviato in |
| -------------------------- | ------------------------- | ------------------------------------ | ------------------------------------- |
| [Locale](#local-scope) | Solo il progetto corrente | No | `~/.claude.json` |
| [Progetto](#project-scope) | Solo il progetto corrente | Sì, tramite controllo della versione | `.mcp.json` nella radice del progetto |
| [Utente](#user-scope) | Tutti i tuoi progetti | No | `~/.claude.json` |
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.
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](/it/settings#settings-files) per i dettagli sui percorsi dei file di impostazioni.
```bash theme={null}
# 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`:
```json theme={null}
{
"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. Questo file è progettato per essere archiviato nel controllo della versione, assicurando che tutti i membri del team abbiano accesso agli stessi strumenti e servizi MCP. Quando aggiungi un server con ambito del progetto, Claude Code crea o aggiorna automaticamente questo file con la struttura di configurazione appropriata.
```bash theme={null}
# Aggiungi un server con ambito del progetto
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp
```
Il file `.mcp.json` risultante segue un formato standardizzato:
```json theme={null}
{
"mcpServers": {
"shared-server": {
"command": "/path/to/server",
"args": [],
"env": {}
}
}
}
```
Per motivi di sicurezza, Claude Code richiede l'approvazione prima di utilizzare server con ambito del progetto dai file `.mcp.json`. Se devi ripristinare queste scelte di approvazione, utilizza il comando `claude mcp reset-project-choices`.
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.
```bash theme={null}
# 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](/it/plugins)
5. [Connettori claude.ai](#use-mcp-servers-from-claude-ai)
I tre ambiti corrispondono ai duplicati per nome. I plugin e i connettori corrispondono per endpoint, quindi uno che punta allo stesso URL o comando di un server sopra è trattato come un duplicato.
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.
**Sintassi supportata:**
* `${VAR}`: si espande al valore della variabile di ambiente `VAR`
* `${VAR:-default}`: si espande a `VAR` se impostato, altrimenti utilizza `default`
**Posizioni di espansione:**
Le variabili di ambiente possono essere espanse in:
* `command`: il percorso dell'eseguibile del server
* `args`: argomenti della riga di comando
* `env`: variabili di ambiente passate al server
* `url`: per i tipi di server HTTP
* `headers`: per l'autenticazione del server HTTP
**Esempio con espansione di variabili:**
```json theme={null}
{
"mcpServers": {
"api-server": {
"type": "http",
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": {
"Authorization": "Bearer ${API_KEY}"
}
}
}
}
```
Se una variabile di ambiente richiesta non è impostata e non ha un valore predefinito, Claude Code non riuscirà ad analizzare la configurazione.
Esempi pratici
Esempio: Monitora gli errori con Sentry
```bash theme={null}
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
```
Autenticati con il tuo account Sentry:
```text theme={null}
/mcp
```
Quindi esegui il debug dei problemi di produzione:
```text theme={null}
Quali sono gli errori più comuni nelle ultime 24 ore?
```
```text theme={null}
Mostrami la stack trace per l'errore ID abc123
```
```text theme={null}
Quale deployment ha introdotto questi nuovi errori?
```
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](https://github.com/settings/personal-access-tokens), genera un nuovo token con granularità fine con accesso ai repository con cui desideri che Claude lavori, quindi aggiungi il server:
```bash theme={null}
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
--header "Authorization: Bearer YOUR_GITHUB_PAT"
```
Quindi lavora con GitHub:
```text theme={null}
Rivedi la PR #456 e suggerisci miglioramenti
```
```text theme={null}
Crea un nuovo issue per il bug che abbiamo appena trovato
```
```text theme={null}
Mostrami tutte le PR aperte assegnate a me
```
Esempio: Interroga il tuo database PostgreSQL
```bash theme={null}
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
--dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"
```
Quindi interroga il tuo database naturalmente:
```text theme={null}
Qual è il nostro ricavo totale questo mese?
```
```text theme={null}
Mostrami lo schema per la tabella orders
```
```text theme={null}
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`. Uno di questi codici di stato contrassegna il server in `/mcp` in modo che tu possa completare il flusso OAuth.
A partire da v2.1.195, quando un aggiornamento del token non riesce perché il server rifiuta il token di aggiornamento archiviato, Claude Code mostra immediatamente un avviso che punta a `/mcp`. Il menu del server connesso lì offre Re-authenticate, in modo che tu possa accedere di nuovo prima che la prossima chiamata dello strumento non riesca.
Un server personalizzato che restituisce un'intestazione `WWW-Authenticate` che punta al suo server di autorizzazione ottiene la stessa scoperta automatica di qualsiasi altro server remoto.
A partire da v2.1.193, Claude Code mostra anche un avviso di avvio quando uno o più server configurati richiedono l'autenticazione, quindi non è necessario aprire `/mcp` per scoprire quali server richiedono l'accesso.
In modalità non interattiva non c'è un pannello `/mcp`, quindi Claude Code non può eseguire il flusso OAuth per te. A partire da v2.1.196, quando un server configurato richiede l'autenticazione durante un'esecuzione `claude -p` o Agent SDK con [ricerca degli strumenti](#scale-with-mcp-tool-search) abilitata, che è l'impostazione predefinita, Claude Code comunica a Claude che gli strumenti del server non sono disponibili fino a quando non lo autorizzi. Claude può quindi nominare il server che richiede l'accesso invece di rispondere come se il server non fosse configurato. Completa l'accesso da una sessione interattiva con `/mcp` o `claude mcp login `.
Se hai configurato `headers.Authorization` per il server e il server rifiuta quell'intestazione, Claude Code segnala la connessione come non riuscita invece di ricorrere a OAuth. Verifica che il token sia valido per l'endpoint MCP, oppure rimuovi l'intestazione per utilizzare il flusso OAuth.
Per esempio:
```bash theme={null}
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
```
In Claude Code, utilizza il comando:
```text theme={null}
/mcp
```
Quindi segui i passaggi nel tuo browser per accedere.
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
Da v2.1.186, `claude mcp login ` esegue il flusso OAuth di un server configurato direttamente dalla tua shell, quindi non è necessario aprire il pannello `/mcp` all'interno di una sessione.
```bash theme={null}
claude mcp login sentry
```
Per cancellare le credenziali archiviate in seguito, esegui `claude mcp logout `.
A partire da v2.1.191, il comando 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.
```bash theme={null}
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`.
Puoi utilizzare `--callback-port` da solo (con registrazione dinamica del client) o insieme a `--client-id` (con credenziali pre-configurate).
```bash theme={null}
# Porta di callback fissa con registrazione dinamica del client
claude mcp add --transport http \
--callback-port 8080 \
my-server https://mcp.example.com/mcp
```
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.
Crea un'app tramite il portale degli sviluppatori del server e annota il tuo ID client e il segreto client.
Molti server richiedono anche un URI di reindirizzamento. Se è così, scegli una porta e registra un URI di reindirizzamento nel formato `http://localhost:PORT/callback`. Utilizza quella stessa porta con `--callback-port` nel passaggio successivo.
Scegli uno dei seguenti metodi. La porta utilizzata per `--callback-port` può essere qualsiasi porta disponibile. Deve solo corrispondere all'URI di reindirizzamento che hai registrato nel passaggio precedente.
Utilizza `--client-id` per passare l'ID client della tua app. Il flag `--client-secret` richiede il segreto con input mascherato:
```bash theme={null}
claude mcp add --transport http \
--client-id your-client-id --client-secret --callback-port 8080 \
my-server https://mcp.example.com/mcp
```
Includi l'oggetto `oauth` nella configurazione JSON e passa `--client-secret` come flag separato:
```bash theme={null}
claude mcp add-json my-server \
'{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"clientId":"your-client-id","callbackPort":8080}}' \
--client-secret
```
Utilizza `--callback-port` senza un ID client per fissare la porta mentre utilizzi la registrazione dinamica del client:
```bash theme={null}
claude mcp add-json my-server \
'{"type":"http","url":"https://mcp.example.com/mcp","oauth":{"callbackPort":8080}}'
```
Imposta il segreto tramite variabile di ambiente per saltare il prompt interattivo:
```bash theme={null}
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
```
Esegui `/mcp` in Claude Code e segui il flusso di accesso del browser.
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
* Se il server utilizza un client OAuth pubblico senza segreto, utilizza solo `--client-id` senza `--client-secret`
* `--callback-port` può essere utilizzato con o senza `--client-id`
* Questi flag si applicano solo ai trasporti HTTP e SSE. Non hanno effetto sui server stdio
* Utilizza `claude mcp get ` per verificare che le credenziali OAuth siano configurate per un server
Indirizza Claude Code a un URL di metadati OAuth specifico 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`:
```json theme={null}
{
"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://`. `authServerMetadataUrl` richiede Claude Code v2.1.64 o successiva. L'`scopes_supported` dell'URL dei metadati sovrascrive gli ambiti che il server upstream pubblicizza.
Limita gli ambiti OAuth
Imposta `oauth.scopes` per fissare gli ambiti 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ù ambiti di quelli che desideri concedere. Il valore è una singola stringa separata da spazi, corrispondente al formato del parametro `scope` in RFC 6749 §3.3.
```json theme={null}
{
"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 ambiti che il server scopre su `/.well-known`. Lascialo non impostato per consentire al server MCP di determinare l'insieme di ambiti richiesti.
A partire da v2.1.196, quando `oauth.scopes` non è impostato, Claude Code richiede l'ambito fornito dall'intestazione `WWW-Authenticate` del server o dai suoi metadati della risorsa protetta, e non invia alcun parametro `scope` quando nessuno dei due lo fornisce. Non richiede più il catalogo completo di `scopes_supported` dai metadati del server di autorizzazione scoperto automaticamente. La richiesta di quel catalogo ha fatto sì che i provider di identità che pubblicizzano ambiti solo amministratore o modello rifiutassero la richiesta di autorizzazione con un errore `invalid_scope`. I metadati recuperati da un `authServerMetadataUrl` configurato forniscono comunque il loro `scopes_supported` come ambiti richiesti.
Se il server di autorizzazione pubblicizza `offline_access` in `scopes_supported`, Claude Code lo aggiunge agli ambiti fissati in modo che il token di accesso possa essere aggiornato senza un nuovo accesso al browser.
Se il server successivamente restituisce un 403 `insufficient_scope` per una chiamata di strumento, Claude Code si autentica di nuovo con gli stessi ambiti fissati. Amplia `oauth.scopes` quando uno strumento di cui hai bisogno richiede un ambito al di fuori del pin.
Se il tuo server MCP utilizza uno schema di autenticazione diverso da OAuth, come Kerberos, token di breve durata o un SSO interno, utilizza `headersHelper` per generare intestazioni di richiesta al momento della connessione. Claude Code esegue il comando e unisce il suo output alle intestazioni di connessione.
```json theme={null}
{
"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:
```json theme={null}
{
"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
* Il comando viene eseguito in una shell con un timeout di 10 secondi
* Le intestazioni dinamiche sovrascrivono qualsiasi `headers` statico con lo stesso nome
L'helper viene eseguito di nuovo ad ogni connessione, all'avvio della sessione e alla riconnessione. Non c'è caching, quindi il tuo script è responsabile di qualsiasi riutilizzo di token.
A partire da v2.1.193, se una chiamata di strumento restituisce `401 Unauthorized` o `403 Forbidden`, Claude Code esegue automaticamente di nuovo l'helper, si riconnette con le intestazioni aggiornate e ritenta la chiamata una volta. Claude Code contrassegna il server come richiedente autenticazione in `/mcp` solo se anche quel tentativo non riesce.
Claude Code imposta queste variabili di ambiente quando esegue l'helper:
| Variabile | Valore |
| :---------------------------- | :---------------------------------------------------------------------------------------------------------------------- |
| `CLAUDE_CODE_MCP_SERVER_NAME` | il nome del server MCP |
| `CLAUDE_CODE_MCP_SERVER_URL` | l'URL del server MCP |
| `CLAUDE_PLUGIN_ROOT` | la directory radice del plugin. Impostato solo quando un [plugin](/it/plugins-reference#mcp-servers) fornisce il server |
Utilizza questi per scrivere un singolo script helper che serve più server MCP.
Per un server fornito da un plugin, l'helper viene eseguito anche con la sua directory di lavoro impostata sulla radice del plugin, quindi un percorso `headersHelper` relativo si risolve all'interno della directory del plugin piuttosto che rispetto alla directory di lavoro della sessione. Richiede Claude Code v2.1.195 o successiva.
`headersHelper` esegue comandi shell arbitrari. Quando definito a livello di progetto o locale, viene eseguito solo dopo che accetti la finestra di dialogo di fiducia dell'area di lavoro.
Aggiungi server MCP dalla configurazione JSON
Se hai una configurazione JSON per un server MCP, puoi aggiungerla direttamente:
```bash theme={null}
# Sintassi di base
claude mcp add-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
```
```bash theme={null}
claude mcp get weather-api
```
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:
```bash theme={null}
# Sintassi di base
claude mcp add-from-claude-desktop
```
Dopo aver eseguito il comando, vedrai una finestra di dialogo interattiva che ti consente di selezionare quali server desideri importare.
```bash theme={null}
claude mcp list
```
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 avranno gli stessi nomi di Claude Desktop
* Se server con gli stessi nomi esistono già, riceveranno un suffisso numerico (per esempio, `server_1`)
Utilizza server MCP da claude.ai
Se hai effettuato l'accesso a Claude Code con un account [claude.ai](https://claude.ai), i server MCP che hai aggiunto in claude.ai sono automaticamente disponibili in Claude Code:
Aggiungi server su [claude.ai/customize/connectors](https://claude.ai/customize/connectors). Nei piani Team ed Enterprise, solo gli amministratori possono aggiungere server.
Completa eventuali passaggi di autenticazione richiesti in claude.ai.
In Claude Code, utilizza il comando:
```text theme={null}
/mcp
```
I server da claude.ai appaiono nell'elenco con indicatori che mostrano che provengono da claude.ai.
A partire dalla v2.1.161, 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](/it/authentication#authentication-precedence) attivo è il tuo abbonamento claude.ai. Non vengono caricati quando `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `apiKeyHelper`, o un provider di terze parti come Bedrock o Vertex è attivo, anche se in precedenza hai eseguito `/login`.
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 o rimuovi l'impostazione `apiKeyHelper`, quindi esegui `/login` per selezionare il tuo account claude.ai.
Un server che hai aggiunto in Claude Code ha [precedenza](#scope-hierarchy-and-precedence) rispetto a 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 registrato da claude.ai. A partire dalla v2.1.162, l'autenticazione di uno di questi host in `/mcp` mostra un messaggio che ti indirizza a collegarlo in Impostazioni → Connettori su claude.ai. Una volta collegato lì, il connettore appare in Claude Code automaticamente.
Disabilita connettori claude.ai
Per disabilitare i server MCP di claude.ai in Claude Code, imposta [`disableClaudeAiConnectors`](/it/settings#available-settings) su `true` in qualsiasi ambito di impostazioni:
```json theme={null}
{
"disableClaudeAiConnectors": true
}
```
Questa impostazione utilizza la semantica any-source-true: `true` in qualsiasi fonte di impostazioni ha la precedenza. Un file `.claude/settings.json` del progetto archiviato può escludere un repository dai connettori cloud, ma un `false` a livello di progetto non può riabilitare i connettori che un `true` a livello di utente o di policy 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:
```bash theme={null}
ENABLE_CLAUDEAI_MCP_SERVERS=false claude
```
Per bloccare singoli connettori claude.ai invece di tutti, aggiungili a [`deniedMcpServers`](/it/managed-mcp) per nome o per modello di URL. Ad esempio, una voce `serverName` di `"claude.ai Slack"` blocca il connettore Slack. Per attivare o disattivare un connettore solo per il progetto corrente, utilizza il pannello `/mcp`.
Queste impostazioni lato client governano le sessioni locali di Claude Code. Nelle sessioni di [Claude Code sul web](/it/claude-code-on-the-web), i connettori claude.ai sono forniti dall'host remoto e arrivano come voci esplicite `--mcp-config`, quindi `disableClaudeAiConnectors` non si applica lì. Gli URL dei connettori vengono anche riscritti attraverso il proxy della sessione, quindi un modello `serverUrl` di `deniedMcpServers` che punta all'URL del fornitore non corrisponderà. Gestisci quali connettori una sessione cloud può utilizzare dalle impostazioni dell'organizzazione claude.ai.
Utilizza Claude Code come server MCP
Puoi utilizzare Claude Code stesso come server MCP a cui altre applicazioni possono connettersi:
```bash theme={null}
# Avvia Claude come server MCP stdio
claude mcp serve
```
Puoi utilizzarlo in Claude Desktop aggiungendo questa configurazione a claude\_desktop\_config.json:
```json theme={null}
{
"mcpServers": {
"claude-code": {
"type": "stdio",
"command": "claude",
"args": ["mcp", "serve"],
"env": {}
}
}
}
```
**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:
```bash theme={null}
which claude
```
Quindi utilizza il percorso completo nella tua configurazione:
```json theme={null}
{
"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`.
Suggerimenti:
* Il server fornisce accesso agli strumenti di Claude come View, Edit, LS, ecc.
* 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 di strumenti.
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 vostra conversazione:
* **Soglia di avviso di output**: Claude Code visualizza un avviso quando l'output di qualsiasi strumento MCP supera 10.000 token
* **Limite configurabile**: potete regolare il massimo di token di output MCP consentiti utilizzando la variabile di ambiente `MAX_MCP_OUTPUT_TOKENS`
* **Limite predefinito**: il massimo predefinito è 25.000 token
* **Ambito**: la variabile di ambiente si applica agli strumenti che non dichiarano il loro limite. Gli strumenti che impostano [`anthropic/maxResultSizeChars`](#raise-the-limit-for-a-specific-tool) utilizzano quel valore invece per il contenuto di testo, indipendentemente da ciò che `MAX_MCP_OUTPUT_TOKENS` è impostato. Gli strumenti che restituiscono dati di immagine sono ancora soggetti a `MAX_MCP_OUTPUT_TOKENS`
Per aumentare il limite per gli strumenti che producono output di grandi dimensioni:
```bash theme={null}
export MAX_MCP_OUTPUT_TOKENS=50000
claude
```
Questo è particolarmente utile quando si lavora con server MCP che:
* interrogano grandi set di dati o database
* generano report o documentazione dettagliati
* elaborano file di log estesi o informazioni di debug
Se state costruendo un server MCP, potete consentire ai singoli strumenti di restituire risultati più grandi della soglia predefinita impostando `_meta["anthropic/maxResultSizeChars"]` nella voce dello strumento nella risposta `tools/list`. Claude Code aumenta la soglia di quello strumento al valore annotato, fino a un limite massimo di 500.000 caratteri.
Questo è utile per strumenti che restituiscono output intrinsecamente grandi ma necessari, come schemi di database o alberi di file completi. Senza l'annotazione, i risultati che superano la soglia predefinita vengono persistiti su disco e sostituiti con un riferimento a file nella conversazione.
```json theme={null}
{
"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 di ambiente per gli strumenti che la dichiarano. Gli strumenti che restituiscono dati di immagine sono ancora soggetti al limite di token.
Se incontrate frequentemente avvisi di output con server MCP specifici che non controllate, considerate di aumentare il limite `MAX_MCP_OUTPUT_TOKENS`. Potete anche chiedere all'autore del server di aggiungere l'annotazione `anthropic/maxResultSizeChars` o di impaginare le loro risposte. L'annotazione non ha effetto sugli strumenti che restituiscono contenuto di immagine; per quelli, aumentare `MAX_MCP_OUTPUT_TOKENS` è l'unica opzione.
Rispondi alle richieste di elicitazione MCP
I server MCP possono richiedere input strutturato da te 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 e passa la tua risposta al server. Non è richiesta alcuna configurazione da parte tua: le finestre di dialogo di elicitazione appaiono 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 (per esempio, un prompt di nome utente e password). Compila i campi e invia.
* **Modalità URL**: Claude Code apre un URL del browser per l'autenticazione o l'approvazione. Completa il flusso nel browser, quindi conferma nella CLI.
Per rispondere automaticamente alle richieste di elicitazione senza mostrare una finestra di dialogo, utilizza l'[hook `Elicitation`](/it/hooks#elicitation).
Se stai costruendo un server MCP che utilizza l'elicitazione, vedi la [specifica di elicitazione MCP](https://modelcontextprotocol.io/docs/learn/client-concepts#elicitation) per i dettagli del protocollo e gli esempi di schema.
Utilizza risorse MCP
I server MCP possono esporre risorse che puoi referenziare utilizzando menzioni @, simile a come referenzi i file.
Referenzia risorse MCP
Digita `@` nel tuo prompt per vedere le risorse disponibili da tutti i server MCP connessi. Le risorse appaiono insieme ai file nel menu di completamento automatico.
Utilizza il formato `@server:protocol://resource/path` per referenziare una risorsa:
```text theme={null}
Puoi analizzare @github:issue://123 e suggerire una correzione?
```
```text theme={null}
Per favore rivedi la documentazione API su @docs:file://api/authentication
```
Puoi referenziare più risorse in un singolo prompt:
```text theme={null}
Confronta @postgres:schema://users con @docs:file://database/user-model
```
Suggerimenti:
* Le risorse vengono recuperate automaticamente e incluse come allegati quando referenziate
* I percorsi delle risorse sono ricercabili con fuzzy search nel completamento automatico della menzione @
* Claude Code fornisce automaticamente strumenti per elencare e leggere risorse MCP quando i server le supportano
* Le risorse possono contenere qualsiasi tipo di contenuto fornito dal server MCP (testo, JSON, dati strutturati, ecc.)
Tool search mantiene l'utilizzo del contesto MCP basso rimandando le definizioni degli strumenti fino a quando Claude ne ha bisogno. Solo i nomi degli strumenti e le istruzioni del server vengono caricati all'avvio della sessione, quindi aggiungere più server MCP ha un impatto minimo sulla tua finestra di contesto. Claude Code non impone un limite fisso di strumenti per server; il limite pratico è il tuo budget della finestra di contesto.
Come funziona
Tool search è abilitato per impostazione predefinita. Gli strumenti MCP vengono rimandati piuttosto che caricati nel contesto in anticipo, e Claude utilizza uno strumento di ricerca per scoprire quelli rilevanti quando un'attività ne ha bisogno. Solo gli strumenti che Claude effettivamente utilizza entrano nel contesto. Dal tuo punto di vista, gli strumenti MCP funzionano esattamente come prima.
Se preferisci il caricamento basato su soglia, imposta `ENABLE_TOOL_SEARCH=auto` per caricare gli schemi in anticipo quando si adattano entro il 10% della finestra di contesto e rimanda solo l'overflow. Vedi [Configura tool search](#configure-tool-search) per tutte le opzioni.
Per gli autori di server MCP
Se stai costruendo un server MCP, il campo delle istruzioni del server diventa più utile con tool search abilitato. Le istruzioni del server aiutano Claude a capire quando cercare i tuoi strumenti, simile a come funzionano le [skills](/it/skills).
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 le descrizioni degli strumenti e le istruzioni del server a 2KB ciascuna. Mantienile concise per evitare il troncamento e metti i dettagli critici all'inizio.
Tool search è abilitato per impostazione predefinita: gli strumenti MCP vengono rimandati e scoperti su richiesta. Claude Code lo disabilita per impostazione predefinita su Vertex AI. È anche disabilitato quando `ANTHROPIC_BASE_URL` punta a un host non di prima parte, poiché la maggior parte dei proxy non inoltrano blocchi `tool_reference`. Imposta `ENABLE_TOOL_SEARCH` esplicitamente per ignorare uno qualsiasi dei fallback.
Tool search richiede un modello che supporta blocchi `tool_reference`. I modelli Haiku non lo supportano. Su Vertex AI, tool search è supportato per Claude Sonnet 4.5 e successivi e Claude Opus 4.5 e successivi.
Controlla il comportamento di tool search con la variabile di ambiente `ENABLE_TOOL_SEARCH`:
| Valore | Comportamento |
| :-------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| (non impostato) | Tutti gli strumenti MCP rimandati e caricati su richiesta. Ricade al caricamento in anticipo su Vertex AI o quando `ANTHROPIC_BASE_URL` è un host non di prima parte |
| `true` | Tutti gli strumenti MCP rimandati. Claude Code invia l'intestazione beta anche su Vertex AI e attraverso i proxy. Le richieste non riescono su modelli Vertex AI precedenti a Sonnet 4.5 o Opus 4.5, o su proxy che non supportano blocchi `tool_reference` |
| `auto` | Modalità soglia: gli strumenti vengono caricati in anticipo se si adattano entro il 10% della finestra di contesto, rimandati altrimenti |
| `auto:N` | Modalità soglia con una percentuale personalizzata, dove `N` è 0-100. Ad esempio, `auto:5` per il 5% |
| `false` | Tutti gli strumenti MCP caricati in anticipo, nessun rinvio |
```bash theme={null}
# Utilizza una soglia personalizzata del 5%
ENABLE_TOOL_SEARCH=auto:5 claude
# Disabilita completamente tool search
ENABLE_TOOL_SEARCH=false claude
```
Oppure imposta il valore nel campo `env` del tuo [settings.json](/it/settings#available-settings).
Puoi anche disabilitare lo strumento `ToolSearch` specificamente:
```json theme={null}
{
"permissions": {
"deny": ["ToolSearch"]
}
}
```
Esentare un server dal rinvio
Se gli strumenti di un server dovrebbero essere sempre visibili a Claude senza un passaggio di ricerca, imposta `alwaysLoad` su `true` nella configurazione di quel server. Ogni strumento da quel server viene quindi caricato nel contesto all'avvio della sessione indipendentemente dall'impostazione `ENABLE_TOOL_SEARCH`. Utilizza questa opzione per un piccolo numero di strumenti che Claude necessita ad ogni turno, poiché ogni strumento in anticipo consuma contesto che altrimenti sarebbe disponibile per la tua conversazione.
La seguente voce `.mcp.json` esentare un server HTTP mentre lascia gli altri server rimandati:
```json theme={null}
{
"mcpServers": {
"core-tools": {
"type": "http",
"url": "https://mcp.example.com/mcp",
"alwaysLoad": true
}
}
}
```
Il campo `alwaysLoad` è disponibile su tutti i tipi di server e richiede Claude Code v2.1.121 o successivo. Un server MCP può anche contrassegnare singoli strumenti come sempre caricati includendo `"anthropic/alwaysLoad": true` nell'oggetto `_meta` dello strumento, che ha lo stesso effetto solo per quello strumento.
L'impostazione di `alwaysLoad: true` blocca anche l'avvio fino a quando il server non si connette, limitato al timeout di connessione standard di 5 secondi. Questo si applica anche se MCP startup è altrimenti [non-blocking per impostazione predefinita](/it/env-vars), poiché gli strumenti devono essere presenti quando viene costruito il primo prompt. Gli altri server continuano a connettersi in background.
Utilizza i prompt MCP come comandi
I server MCP possono esporre prompt che diventano disponibili come comandi in Claude Code.
Esegui i prompt MCP
Digita `/` per vedere tutti i comandi disponibili, inclusi quelli dai server MCP. I prompt MCP appaiono con il formato `/mcp__servername__promptname`.
```text theme={null}
/mcp__github__list_prs
```
Molti prompt accettano argomenti. Passali separati da spazi dopo il comando:
```text theme={null}
/mcp__github__pr_review 456
```
```text theme={null}
/mcp__jira__create_issue "Bug nel flusso di accesso" high
```
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
* I nomi del server e del prompt vengono normalizzati, con gli spazi convertiti in trattini bassi
Configurazione MCP gestita
Per le organizzazioni che necessitano di un controllo centralizzato su quali server MCP gli utenti possono connettere, consulta [Configurazione MCP gestita](/it/managed-mcp). Copre la distribuzione di un set fisso di server con `managed-mcp.json`, la restrizione dei server con `allowedMcpServers` e `deniedMcpServers`, e cosa vedono gli utenti quando un server è bloccato.