Connetti Claude Code ai tuoi strumenti tramite MCP

​

Cosa puoi fare con MCP

• 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

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

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

​

Installare i server MCP

​

Opzione 1: aggiungere un server HTTP remoto

# 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"

​

Opzione 2: aggiungere un server SSE remoto

# 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

# 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

​

Come Claude Code arresta un server stdio

• Su macOS e Linux: Claude Code invia SIGINT, poi SIGTERM se il processo è ancora in esecuzione 100 millisecondi dopo, poi SIGKILL dopo ulteriori 400 millisecondi.
• 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.

​

Opzione 4: aggiungere un server WebSocket remoto

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

​

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

• 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 delle impostazioni di un altro client.

​

Aggiungere un server da un URL

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

​

Aggiungere un server da un comando npx, uvx o binario

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

​

Aggiungere un server da un blocco JSON mcpServers

• Un url senza type: aggiungi "type": "http", "type": "sse" o "type": "ws" in base all’endpoint. Claude Code legge una voce senza type come un server stdio, quindi una voce url senza type fallisce.
• 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.

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

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

​

Gestire i tuoi server

# 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

​

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

​

Approvazioni dei server di progetto e attendibilità del workspace

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

​

Dettagli sullo stato del server

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

​

Avvisi di configurazione

• Spazi nascosti: Claude Code avvisa quando un valore di configurazione MCP contiene spazi iniziali o finali nascosti, che spesso derivano dall’incollare un token con un a capo finale. Claude Code controlla command, url, ogni voce di args e i valori e i nomi delle chiavi sotto env e headers. Claude Code mostra l’avviso nell’output di claude mcp list e in /mcp, indicando i campi interessati senza mostrarne i valori, ad esempio Leading or trailing whitespace in: headers.Authorization. Claude Code non rimuove gli spazi e usa i valori esattamente come scritti, quindi modifica la configurazione per rimuoverli.
• Stesso nome in più ambiti: se definisci lo stesso nome di server in più di un ambito con endpoint diversi, Claude Code avvisa del conflitto nell’output di claude mcp list e in /mcp. Claude Code memorizza gli accessi OAuth per endpoint, quindi quando ti autentichi con la definizione che viene caricata in un progetto, devi comunque accedere separatamente in un progetto in cui viene caricata una definizione diversa. Mantieni l’endpoint che desideri e rimuovi gli altri con claude mcp remove <name> --scope <scope>. Nell’avviso, Claude Code riporta l’endpoint di ciascun ambito come scritto nella tua configurazione, con i riferimenti ${VAR} 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 priva di :-default, Claude Code avvisa nell’output di claude mcp list e in /mcp, indicando la variabile, e carica comunque il server con il testo ${VAR} non espanso. Imposta la variabile o aggiungi un fallback ${VAR:-default}. Nell’url e negli headers di un server remoto, alcune variabili di credenziali vengono invece lette come vuote, senza avviso.

​

Disponibilità degli strumenti

• Con la ricerca degli strumenti, il comportamento predefinito: 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 di Microsoft Foundry ospitato su Azure: Claude parte dal percorso della ricerca degli strumenti anziché con WaitForMcpServers, poiché Claude Code scopre il rifiuto lato server del deploy solo dall’API. Dopo che Claude Code ha spostato quel deploy al caricamento anticipato, gli strumenti di un server che completa la connessione diventano disponibili alla successiva richiesta di Claude.

​

Disattivare un server senza rimuoverlo

• disabledMcpServers: un elenco di esclusione per i server configurati dall’utente, i server dei plugin, i server che la tua organizzazione fornisce tramite le impostazioni gestite, 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 disattivi un connettore claude.ai con l’interruttore per progetto di /mcp descritto in Disattivare 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.

​

Runtime del client MCP

• 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

• Chiede ai server HTTP, stdio e connettori claude.ai se supportano la revisione più recente, e la usa con quelli che la supportano. 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 OAuth MCP la cui risposta di autorizzazione indica un emittente inatteso.
• Invia le credenziali OAuth MCP solo a un endpoint dei token servito tramite HTTPS o su localhost, 127.0.0.1 o ::1. L’accesso fallisce per un server il cui endpoint dei token è http:// semplice in qualsiasi altra posizione, come un dispositivo sulla tua rete locale. Consulta Refusing to send credentials to non-https token endpoint.

​

Aggiornamenti dinamici degli strumenti

• In una sessione interattiva del terminale, 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 in risposta a queste notifiche.

​

Stream di notifiche sul runtime v2

• 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 con gli stream verso host serverless: dopo cinque riaperture in un’ora, Claude Code attende circa sei ore prima della successiva.

​

Riconnessione automatica

​

Disconnessioni di un server remoto a metà sessione

• In una sessione interattiva: /mcp mostra il server come in attesa mentre Claude Code si riconnette. Dopo cinque tentativi falliti, Claude Code contrassegna il server come in errore, o come bisognoso di autenticazione quando il server deve essere nuovamente autorizzato. Quando contrassegna il server come in errore, vedi una notifica MCP server "<name>" disconnected · open /mcp to reconnect. Puoi riprovare manualmente da /mcp.
• Nelle esecuzioni claude -p e nelle sessioni dell’Agent SDK: Claude Code effettua gli stessi cinque tentativi, senza alcun pannello /mcp per mostrarli. Quando i tentativi di un server HTTP o SSE falliscono con un errore temporaneo, continua a riprovare in background per circa mezz’ora al massimo, e il server e i suoi strumenti tornano disponibili quando un nuovo tentativo riesce a connettersi.

​

Prime connessioni fallite

• La prima connessione di un server WebSocket
• Un errore di autenticazione o di risorsa non trovata, perché per risolverlo è necessaria una modifica alla configurazione. Quando un headersHelper è l’unica fonte dell’header Authorization del server, Claude Code riprova comunque un errore di autenticazione, perché riesegue l’helper a ogni tentativo e può ottenere una credenziale nuova

​

Richieste di rilevamento fallite

​

Riprovare tu stesso i server in errore

​

Come Claude viene a sapere che un server è in errore

• Con la ricerca degli strumenti, Claude Code comunica a Claude quale server è in errore e il relativo errore di connessione, così Claude segnala l’errore di connessione nella sua risposta. Claude Code include le stesse informazioni nei risultati di ToolSearch che non trovano alcuno strumento corrispondente.
• In qualsiasi configurazione senza ricerca degli strumenti, Claude Code non segnala a Claude le connessioni ai server fallite.

​

Inviare messaggi con i canali

​

Spostamento automatico in background delle chiamate lunghe agli strumenti

• Le chiamate dai 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 che arrivi il risultato

​

Server MCP forniti dai plugin

• I plugin definiscono i server MCP in .mcp.json nella radice del plugin o 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 un server di un plugin installato in /mcp, il che impedisce a Claude Code di connettersi a esso senza rimuovere il plugin

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

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

• 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 di plugin remoto (HTTP o SSE) che hai già usato può invece mostrare lo stato cached; Claude Code lo connette quando Claude chiama per la prima volta uno dei suoi strumenti
  • 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 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 indicarli
  • Quando sposti la sessione con /cd su v2.1.246 o successiva, Claude Code connette i server dei plugin abilitati dalle impostazioni della nuova directory e disconnette i server dei plugin che non sono più abilitati, quindi non devi eseguire /reload-plugins dopo lo spostamento
  • Nelle sessioni cloud, una chiamata MCP a un server di plugin non ancora connesso, ad esempio subito dopo il risveglio di una sessione inattiva, avvia il server su richiesta e attende che si connetta
• Segnaposto di percorso: ${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 radice 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 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 in base al server

• 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

mcp__plugin_my-plugin_database-tools__query

​

Ambiti di installazione MCP

​

Ambito locale

# 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

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

​

Ambito del progetto

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

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

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

​

Ambito utente

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

​

Gerarchia e precedenza dell’ambito

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

​

Espansione delle variabili di ambiente in .mcp.json

​

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

• 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

{
  "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

​

Variabili di credenziali che leggono come vuote

• 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

​

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

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

​

Esempi pratici

​

Esempio: Connettiti a GitHub per le revisioni del codice

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

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

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

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

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

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

/mcp

​

Autenticazione dalla riga di comando

claude mcp login sentry

claude mcp login sentry --no-browser

​

Utilizza una porta di callback OAuth fissa

# 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

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

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

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

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

​

Sovrascrivi la scoperta dei metadati OAuth

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

​

Limita gli scope OAuth

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

​

Utilizza intestazioni dinamiche per l’autenticazione personalizzata

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

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

• 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

​

Dove l’helper viene eseguito

​

Quali variabili un helper può leggere

• 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

​

Affida una cartella prima che il suo headersHelper venga eseguito

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

​

Aggiungi server MCP dalla configurazione 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

claude mcp get weather-api

​

Importa server MCP da Claude Desktop

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

claude mcp list 

​

Utilizzare i server MCP da claude.ai

/mcp

• 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

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

​

Come i connettori raggiungono Claude Code

• 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

• Strumento impostato su ask: Claude Code richiede su ogni chiamata con il motivo Your organization requires approval for this tool. Il prompt appare anche in modalità permission acceptEdits, auto, e bypassPermissions, e non offre mai un’opzione per ricordare la tua scelta. Le regole Allow che corrispondono allo strumento non saltano il prompt neanche. In modalità dontAsk, che non richiede mai, Claude Code nega 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.

​

Disabilitare i connettori claude.ai

{
  "disableClaudeAiConnectors": true
}

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

​

Usa Claude Code come server MCP

# Avvia Claude come server MCP stdio
claude mcp serve

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

which claude

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

​

Limiti di output MCP e avvisi

• 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

• 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

export MAX_MCP_OUTPUT_TOKENS=50000
claude

​

Aumentare il limite per uno strumento specifico

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

​

Immagini nei risultati degli strumenti

​

Tool input schemas con un combinatore a livello radice

• 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

​

Strumenti con schemi di input non validi

• 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

​

Strumenti con nomi più lunghi di 128 caratteri

​

Richiedere l’approvazione per uno strumento specifico

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

​

Rispondere alle richieste di elicitazione MCP

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

​

Utilizzare le risorse MCP

​

Referenziare le risorse MCP

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

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

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

​

Scalare con la ricerca di strumenti MCP

​

Ricerca di strumenti per gli autori di server MCP

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

• 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

​

Contrassegnare uno strumento da caricare in anticipo o da mantenere rimandato

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

​

Configurare la ricerca di strumenti

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

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

# Disabilita completamente la ricerca di strumenti
ENABLE_TOOL_SEARCH=false claude

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

​

Ricerca di strumenti tramite un gateway LLM

​

Strumenti che restano rimandati sotto la soglia ENABLE_TOOL_SEARCH=auto

​

Esentare un server dal rinvio

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

​

Rimandare gli strumenti di un server

​

Usa i prompt MCP come comandi

​

Esegui i prompt MCP

/mcp__github__list_prs

/mcp__github__pr_review 456

/mcp__jira__create_issue login-bug high

​

Configurazione MCP gestita