SpyBara
Go Premium

mcp.md 2026-06-16 21:57 UTC to 2026-06-17 17:02 UTC

167 added, 81 removed.

2026
Fri 26 07:02 Thu 25 23:58 Wed 24 22:02 Tue 23 22:00 Mon 22 23:59 Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

Connetti Claude Code ai tuoi strumenti tramite MCP

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

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

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

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

Cosa puoi fare con MCP

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

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

Trovare e costruire server MCP

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

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

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

1

Installa il plugin

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.

2

Esegui lo skill di compilazione

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

# Sintassi di base
claude mcp add --transport http <name> <url>

# 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 

# Sintassi di base
claude mcp add --transport sse <name> <url>

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

# Sintassi di base
claude mcp add [options] <name> -- <command> [args...]

# Esempio reale: Aggiungi server Airtable
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

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:

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

# 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 <name> mostra i server in sospeso come ⏸ Pending approval e i server rifiutati come ✗ Rejected.

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

Aggiornamenti dinamici degli strumenti

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.

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 per utilizzare un canale ufficialmente supportato, oppure Riferimento canali per costruire il vostro.

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.

Server MCP forniti da plugin

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

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

{
  "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 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 (il supporto del trasporto può variare a seconda del server)

Visualizzazione dei server MCP del plugin:

# 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_<plugin-name>_<server-name>__<tool-name>, dove qualsiasi carattere al di fuori di A-Z, a-z, 0-9, _, e - viene sostituito con _. Per il server database-tools raggruppato in un plugin denominato my-plugin, uno strumento query è richiamabile come:

mcp__plugin_my-plugin_database-tools__query

Utilizza questo nome completo quando fai riferimento allo strumento nelle regole di autorizzazione, nell'elenco allowed-tools di una skill, o nel campo tools di un subagent.

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

Ambito Carica in Condiviso con il team Archiviato in
Locale Solo il progetto corrente No ~/.claude.json
Progetto Solo il progetto corrente Sì, tramite controllo della versione .mcp.json nella radice del progetto
Utente 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.

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

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

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

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

Ambito del progetto

I server con ambito del progetto abilitano la collaborazione del team archiviando le configurazioni in un file .mcp.json nella directory radice del tuo progetto. 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.

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

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

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

Gerarchia e precedenza dell'ambito

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

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

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:

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

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

Autenticati con il tuo account Sentry:

/mcp

Quindi esegui il debug dei problemi di produzione:

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

Mostrami la stack trace per l'errore ID abc123

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, genera un nuovo token con granularità fine con accesso ai repository con cui desideri che Claude lavori, quindi aggiungi il server:

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

Quindi lavora con GitHub:

Rivedi la PR #456 e suggerisci miglioramenti

Crea un nuovo issue per il bug che abbiamo appena trovato

Mostrami tutte le PR aperte assegnate a me

Esempio: Interroga il tuo database PostgreSQL 

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:

Qual è il nostro ricavo totale questo mese?

Mostrami lo schema per la tabella orders

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

Autenticazione con server MCP remoti

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

Claude Code contrassegna un server remoto come richiedente autenticazione quando il server risponde con 401 Unauthorized o 403 Forbidden. Uno di questi codici di stato contrassegna il server in /mcp in modo che tu possa completare il flusso OAuth. 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.

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.

1

Aggiungi il server che richiede l'autenticazione

Per esempio:

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

Utilizza il comando /mcp all'interno di Claude Code

In Claude Code, utilizza il comando:

/mcp

Quindi segui i passaggi nel tuo browser per accedere.

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

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

Utilizza credenziali OAuth pre-configurate

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

1

Registra un'app OAuth con il server

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

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.

2

Aggiungi il server con le tue credenziali

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:

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

Autenticati in Claude Code

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

Sovrascrivi la scoperta dei metadati OAuth

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:

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

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

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.

Utilizza intestazioni dinamiche per l'autenticazione personalizzata

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.

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

Il comando può anche essere inline:

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

Requisiti:

  • Il comando deve scrivere un oggetto JSON di coppie chiave-valore stringa su stdout
  • 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.

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

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

Aggiungi server MCP dalla configurazione JSON

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

1

Aggiungi un server MCP da JSON

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

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

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

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

Verifica che il server sia stato aggiunto

claude mcp get weather-api

Importa server MCP da Claude Desktop

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

1

Importa server da Claude Desktop

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

Seleziona quali server importare

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

3

Verifica che i server siano stati importati

claude mcp list

Utilizza server MCP da Claude.ai

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

1

Configura server MCP in Claude.ai

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

2

Autentica il server MCP

Completa eventuali passaggi di autenticazione richiesti in Claude.ai.

3

Visualizza e gestisci i server in Claude Code

In Claude Code, utilizza il comando:

/mcp

I server 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 Claude.ai vengono recuperati solo quando il tuo metodo di autenticazione 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 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.

Per disabilitare i server MCP di claude.ai in Claude Code, imposta la variabile di ambiente ENABLE_CLAUDEAI_MCP_SERVERS su false:

ENABLE_CLAUDEAI_MCP_SERVERS=false claude

Utilizza Claude Code come server MCP

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

# Avvia Claude come server MCP stdio
claude mcp serve

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

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

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

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

Aumenta il limite per uno strumento specifico

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.

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

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.

Se stai costruendo un server MCP che utilizza l'elicitazione, vedi la specifica di elicitazione MCP 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

1

Elenca le risorse disponibili

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.

2

Referenzia una risorsa specifica

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

Puoi analizzare @github:issue://123 e suggerire una correzione?

Per favore rivedi la documentazione API su @docs:file://api/authentication
3

Referenze di risorse multiple

Puoi referenziare più risorse in un singolo prompt:

Confronta @postgres:schema://users con @docs:file://database/user-model

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

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

Puoi anche disabilitare lo strumento ToolSearch specificamente:

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

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

1

Scopri i prompt disponibili

Digita / per vedere tutti i comandi disponibili, inclusi quelli dai server MCP. I prompt MCP appaiono con il formato /mcp__servername__promptname.

2

Esegui un prompt senza argomenti

/mcp__github__list_prs
3

Esegui un prompt con argomenti

Molti prompt accettano argomenti. Passali separati da spazi dopo il comando:

/mcp__github__pr_review 456

/mcp__jira__create_issue "Bug nel flusso di accesso" high

Configurazione MCP gestita

Per le organizzazioni che necessitano di un controllo centralizzato su quali server MCP gli utenti possono connettere, consulta Configurazione MCP gestita. 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.