SpyBara
Go Premium

mcp-quickstart.md 2026-10-19 23:58 UTC to 2026-10-20 23:00 UTC

This page contains 215 additions and 249 deletions.

2026
Thu 1 23:59 Thu 15 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Wed 28 23:57 Fri 30 23:01

Connettere i server MCP

Aggiungere un server MCP a Claude Code, verificare la connessione e trovare la configurazione su disco.

Il Model Context Protocol (MCP) consente a Claude Code di utilizzare strumenti oltre il suo set integrato, come la ricerca in un tracker di problemi, l'interrogazione di un database o il controllo di un browser web. Questi strumenti provengono dai server MCP, che vengono eseguiti sulla vostra macchina o come servizi ospitati.

Questa guida vi guida attraverso la connessione di un server MCP end-to-end con la CLI di Claude Code. Alla fine, avrete un server connesso e rispondente, saprete dove vive la sua configurazione su disco e saprete come risolvere gli errori di connessione più comuni.

[!NOTE]

Potete anche aggiungere server MCP da altre superfici, inclusa l'app desktop, VS Code e il web. Vedere Connettere da altre superfici.

Per ogni modo di connettere e configurare i server MCP in Claude Code, consultare il riferimento MCP.

Prima di iniziare

Assicuratevi di avere:

  • Claude Code installato e autenticato
  • Un terminale aperto in una directory di progetto. Qualsiasi directory funziona, inclusa una vuota.

Aggiungere e verificare un server

L'esempio seguente si connette al server MCP della documentazione di Claude Code, un server ospitato con ricerca full-text sulla documentazione di Claude Code. Non richiede autenticazione o alcuna configurazione speciale, quindi funziona bene come primo server per testare il flusso di configurazione.

I passaggi sono gli stessi per qualsiasi server: aggiungerlo, controllare lo stato della connessione, quindi utilizzarlo in una sessione, con un passaggio di pulizia facoltativo alla fine. Alcuni server aggiungono un passaggio, come un accesso al browser, mostrato in Esempi di server MCP aggiuntivi. Per altri server a cui connettersi, consultare la Directory Anthropic.

1. Aggiungere il server MCP

Registrare il server con Claude Code. Eseguire questo nel vostro terminale, non all'interno di una sessione claude: state configurando il server prima di avviare una conversazione.

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

Le parti del comando:

  • claude mcp add: registra un server con Claude Code.
  • --transport http: il server è ospitato a un URL piuttosto che eseguito come processo locale.
  • claude-code-docs: un nome che voi scegliete. Chiamare lo stesso server docs funzionerebbe in modo identico. Claude Code utilizza qualsiasi nome voi scegliate per etichettare gli strumenti del server nell'output di Claude e per fare riferimento al server in comandi come claude mcp remove.
  • https://code.claude.com/docs/mcp: l'URL dove il server è ospitato.

Il comando stampa una conferma come Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config, seguita da una riga File modified: che mostra il file di configurazione che ha scritto. La parte local config significa che il server è registrato per voi, in questo progetto: se avviate Claude Code in un progetto diverso, questo server non è attivo lì. Per registrare un server una volta per tutti i vostri progetti, aggiungetelo a livello di utente, coperto in Cambiare l'ambito del server.

2. Controllare lo stato della connessione

Confermare che il server appaia nell'elenco dei server e controllare il suo stato:

claude mcp list

Il server appare con un indicatore di stato:

Stato Significato
✔ Connected Pronto all'uso. Questo è quello che dovreste vedere per claude-code-docs
! Connected · tools fetch failed Il server si è connesso ma non ha potuto elencare i suoi strumenti. Eseguire claude mcp get <name> per il dettaglio dell'errore
! Needs authentication Il server è raggiungibile ma necessita un accesso al browser, o un token passato con --header. Vedere Connettere un server che richiede l'accesso
✘ Failed to connect Il server non ha risposto. Vedere Risoluzione dei problemi
✘ Connection error Il tentativo di connessione ha generato un errore. Vedere Risoluzione dei problemi
⏸ Pending approval (run `claude` to approve) Un server con ambito di progetto che non avete ancora approvato. Vedere Modificare .mcp.json direttamente
⊘ Disabled for this project (re-enable via /mcp) Un server disattivato per questo progetto dall'elenco disabledMcpServers del progetto. Vedere Disattivare un server senza rimuoverlo

Alcune console Windows legacy, come la console predefinita su Windows 10, non supportano questi glifi Unicode e mostrano √ e × al posto di ✔ e ✘.

3. Utilizzare il server

Avviare una sessione e chiedere a Claude di utilizzare il nuovo server per nome:

claude

Use the claude-code-docs server to look up what MCP_TIMEOUT does

[!NOTE]

Normalmente non è necessario nominare un server nel vostro prompt, poiché Claude sceglie gli strumenti rilevanti da solo. Nominarlo qui garantisce che la dimostrazione passi attraverso il nuovo server piuttosto che un altro strumento, come web fetch, che potrebbe rispondere alla stessa domanda.

Se Claude Code chiede il permesso la prima volta che Claude chiama il server, approvate. La chiamata dello strumento nell'output di Claude è etichettata con il nome del server, che è come confermate che la risposta proviene dal server MCP piuttosto che dalla conoscenza integrata di Claude.

4. Rimuovere il server

Questo passaggio è facoltativo. Quando avete finito di sperimentare, potete rimuovere il server:

claude mcp remove claude-code-docs

Il comando conferma con Removed MCP server "claude-code-docs" from local config e una riga File modified: che mostra il file che ha aggiornato.

[!NOTE]

Ogni server connesso occupa dello spazio nella finestra di contesto di Claude perché i nomi degli strumenti e le istruzioni del server si caricano in ogni sessione. Rimuovere i server che non utilizzate più mantiene quello spazio libero.

Dove vengono salvati i server

Il comando claude mcp add scrive i dettagli del server in un file di configurazione. Per impostazione predefinita registra il server a livello di ambito local: privato per voi, attivo solo nel progetto corrente. Passare --scope user per registrarlo una volta per tutti i vostri progetti, o --scope project per condividerlo con i vostri compagni di squadra. Cambiare l'ambito del server illustra entrambi.

[!NOTE]

claude mcp add funziona allo stesso modo in ogni shell, inclusi PowerShell e Command Prompt. All'interno di una sessione claude, utilizzare il comando /mcp per controllare e gestire i server che avete già aggiunto.

Ci sono altri modi per aggiungere un server, ognuno con la sua propria sezione:

Trovare la vostra configurazione su disco

Il comando claude mcp add scrive il server in uno di tre ambiti, archiviati in due file, a seconda del flag --scope. Non è necessario modificare questi file direttamente, ma sapere dove si trovano aiuta con il debug e il controllo della versione.

Ambito File Disponibile per
local ~/.claude.json, sotto l'entry per questo progetto Solo voi, solo questo progetto. L'impostazione predefinita
project .mcp.json nella radice del vostro progetto Chiunque cloni il progetto
user ~/.claude.json, sotto la chiave mcpServers di livello superiore Solo voi, tutti i progetti

Su Windows, ~/.claude.json si risolve in %USERPROFILE%\.claude.json, tipicamente C:\Users\YourName\.claude.json. Se avete impostato CLAUDE_CONFIG_DIR, Claude Code legge .claude.json da dentro quella directory invece.

Eseguire claude mcp get claude-code-docs per vedere quale ambito contiene la definizione di un server. Per come gli ambiti interagiscono quando lo stesso server è definito in più di uno, vedere Ambiti di installazione MCP.

Cambiare l'ambito del server

L'ambito di un server è fisso quando lo aggiungete, quindi cambiare l'ambito significa rimuovere l'entry e riaggiungerla a quello nuovo. Entrambi i casi seguenti iniziano rimuovendo l'entry locale dalla prima procedura dettagliata, in modo che il server abbia una sola definizione. Se l'avete già rimosso alla fine di quella procedura dettagliata, saltate questo comando:

claude mcp remove claude-code-docs --scope local

Utilizzare un server in tutti i vostri progetti

Riaggiunger il server a livello di ambito user per renderlo attivo in ogni progetto che aprite, ancora privato per voi:

claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

Condividere un server con il vostro team

Riaggiunger il server a livello di ambito project, che scrive in .mcp.json nella radice del progetto:

claude mcp add --scope project --transport http claude-code-docs https://code.claude.com/docs/mcp

Eseguire il commit di .mcp.json al controllo della versione. I compagni di squadra che clonano il repository e avviano Claude Code vedono un prompt per approvare il server, quindi si connette anche per loro.

Esempi di server MCP aggiuntivi

La prima procedura dettagliata ha utilizzato un server ospitato che si connette senza alcun accesso. Gli esempi seguenti coprono le altre due forme comuni, con lo stesso flusso di aggiunta, controllo, utilizzo.

Aggiungere un server locale

Un server stdio locale è un programma che Claude Code avvia come sottoprocesso sulla vostra macchina, piuttosto che un servizio che raggiunge tramite un URL. Utilizzatene uno per strumenti che necessitano accesso a risorse locali come un browser, il vostro filesystem o un socket di database.

Il server MCP Playwright è un buono da provare: dà a Claude un browser che può navigare, fare clic e leggere, e non necessita alcun account. Viene eseguito tramite npx, quindi richiede Node.js 18 o successivo.

1. Aggiungere il server Playwright

Registrare il server con il comando che Claude Code dovrebbe eseguire per avviarlo:

claude mcp add playwright -- npx -y @playwright/mcp@latest

Questo comando differisce dall'esempio ospitato in tre modi:

  • Non c'è il flag --transport, perché i server locali utilizzano il trasporto predefinito stdio.
  • Tutto dopo il separatore -- è il comando che Claude Code esegue per avviare il server.
  • -y dice a npx di installare il pacchetto senza chiedere.

Il comando stampa una conferma come Added stdio MCP server playwright with command: npx -y @playwright/mcp@latest to local config, seguita da una riga File modified: che mostra il file di configurazione che ha scritto.

Playwright guida qualsiasi Chrome già installato sulla vostra macchina. Per utilizzare un browser diverso, aggiungere --browser con il nome del browser, ad esempio --browser firefox, dopo @playwright/mcp@latest.

2. Controllare la connessione

La conferma Added significa che l'entry è stata salvata, non che il comando viene eseguito. Controllare la connessione:

claude mcp list

Il primo controllo può mostrare ✘ Failed to connect mentre npx scarica il pacchetto, quindi attendere un momento ed eseguirlo di nuovo. Una volta che il download finisce, lo stato cambia a ✔ Connected. Se mostra ancora ✘ Failed to connect dopo un paio di tentativi, vedere Risoluzione dei problemi.

3. Utilizzare il browser

Dare a Claude un compito che necessita il browser:

Use playwright to open https://example.com and tell me the page title

Una finestra del browser si apre in modo che possiate vederla funzionare, e le chiamate dello strumento nell'output di Claude sono etichettate con il nome del server playwright e l'azione, come browser_navigate.

Provate a puntarlo al vostro server di sviluppo locale per controllare che una pagina ancora si renderizzi dopo una modifica, o fatelo camminare attraverso un rapporto di bug passo dopo passo.

Connettere un server che richiede l'accesso

Servizi ospitati come Sentry, Linear e Notion eseguono i loro server MCP dietro OAuth: aggiungete l'URL del server, quindi accedete tramite il vostro browser.

I passaggi seguenti utilizzano Sentry come esempio. Per connettere un servizio diverso, sostituire il suo URL, che potete trovare nella Directory Anthropic o nella documentazione del servizio.

1. Aggiungere il server

Il comando add è lo stesso che per il server docs, con l'URL di Sentry:

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

Dopo l'aggiunta, claude mcp list mostra il server con ! Needs authentication. È previsto: il passaggio successivo completa l'accesso.

2. Autenticarsi nel vostro browser

Avviare una sessione di Claude Code e aprire il pannello MCP:

/mcp

Selezionare sentry dall'elenco, premere Invio e scegliere Authenticate. Il vostro browser si apre alla pagina di accesso di Sentry. Approvare la connessione lì.

Di nuovo in Claude Code, lo stato del server cambia a connesso. Se l'accesso fallisce o il browser non si apre, vedere Risoluzione dei problemi.

3. Utilizzare il server

Chiedere a Claude qualcosa che necessita il servizio, come What Sentry projects do I have access to?, e cercare le chiamate dello strumento etichettate con il nome del server sentry nel suo output.

I server che si autenticano con un token statico invece di OAuth prendono il token al momento dell'aggiunta con --header "Authorization: Bearer <token>". Vedere l'esempio GitHub per una versione elaborata.

Modificare .mcp.json direttamente

Ogni file nella tabella degli ambiti utilizza lo stesso formato JSON per le entry dei server. Questa sezione modifica .mcp.json, il file con ambito di progetto. È quello che vale più la pena scrivere a mano perché è controllato nel repository, dove funge anche da configurazione come codice per il vostro team.

Creare .mcp.json nella radice del vostro progetto. L'esempio seguente definisce entrambi i server da questa guida, il server docs ospitato raggiunto tramite HTTP e il server Playwright come processo stdio locale:

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

I campi differiscono per tipo di server:

  • Per i server HTTP, url è l'endpoint a cui Claude Code si connette.
  • Per i server stdio, command e args sono il programma che esegue.

Dopo aver salvato il file, avviare una nuova sessione di Claude Code nel progetto. Claude Code legge .mcp.json all'avvio.

La prima volta che Claude Code vede un server con ambito di progetto, vi chiede di approvarlo. Il prompt esiste in modo che un repository che clonate non possa lanciare processi sulla vostra macchina senza il vostro consenso. Approvate il prompt, o eseguite /mcp per approvare più tardi se l'avete perso.

Una volta approvato, eseguire /mcp e controllare che i server mostrino come connessi. Se uno mostra un errore invece, vedere Risoluzione dei problemi.

Connettere da altre superfici

Questa guida utilizza i comandi CLI claude mcp, ma ogni superficie di Claude Code può connettersi ai server MCP:

Risoluzione dei problemi

Se un server non si connette, controllare il suo stato con /mcp all'interno di una sessione o claude mcp list dal vostro shell, quindi abbinare il sintomo seguente. Il pannello /mcp vi consente anche di riconnettervi o autenticarvi senza lasciare la sessione.

/mcp shows No MCP servers configured

Claude Code non ha trovato alcun server per la directory corrente. Le cause più comuni:

  • Avete eseguito claude mcp add da un progetto diverso. I server con ambito locale sono legati al progetto dove li avete aggiunti: la radice del repository, o la directory esatta se non eravate in un repository git. Riaggiunger il server dal progetto in cui siete ora, o aggiungetelo con --scope user in modo che non sia legato a un progetto.
  • Avete modificato un file di configurazione al percorso sbagliato. I file corretti sono ~/.claude.json e <project>/.mcp.json. Claude Code non legge percorsi come ~/.claude/.mcp.json, ~/.claude/config/mcp.json, ~/.claude/mcp.json, o %APPDATA%\Claude\mcp.json. Per i server con ambito utente, eseguire claude mcp add --scope user, che scrive nella chiave mcpServers in ~/.claude.json; per i server con ambito progetto, modificare .mcp.json nella radice del progetto.
  • Avete scritto una voce malformata in .mcp.json. Claude Code salta quella voce e carica comunque le altre. Eseguire claude mcp list dal vostro shell e cercare l'avviso di analisi, che nomina il campo offensivo.

Status shows Failed to connect or Connection error

Entrambi gli stati significano che il server non è stato avviato o l'URL non ha risposto. Possono anche apparire per i server HTTP che rifiutano il token configurato in headers.Authorization; un server che vuole un token che non avete configurato mostra ! Needs authentication invece, coperto in Connettere un server che richiede l'accesso.

Il vostro primo passo dipende da quale stato vedete:

  • Failed to connect: iniziare con il dettaglio dell'errore sullo stato stesso. claude mcp list e claude mcp get <name> mostrano lo stato HTTP o il codice di errore e qualsiasi testo di errore che il server ha restituito, che spesso nomina il problema direttamente, come un'intestazione mancante o un token rifiutato. Prima della v2.1.219, Failed to connect mostrava solo lo stato nudo, e avevate bisogno dei controlli curl e comando più avanti in questa sezione per trovare la causa.
  • Connection error: Claude Code non aggiunge alcun dettaglio a questo stato su nessuna versione, quindi andate direttamente ai controlli curl e comando più avanti in questa sezione.

Se il dettaglio punta a una credenziale o un URL, controllate anche gli avvisi nell'output di claude mcp list. Claude Code contrassegna i valori di configurazione con spazi bianchi nascosti all'inizio o alla fine, una causa comune di errori di autenticazione dopo aver incollato un token.

Se un server HTTP restituisce 404 Not Found, Claude Code mostra MCP endpoint not found at <origin>. Check the URL in your MCP config. quando selezionate il server in /mcp. Il messaggio nomina l'origine dell'URL, come https://mcp.example.com, senza il suo percorso, quindi eseguire claude mcp get <name> per vedere l'URL completo che avete configurato. Confrontate il suo percorso con il percorso dell'endpoint MCP documentato del server, quindi eseguire claude mcp remove <name> e riaggiunger con l'URL corretto. Prima della v2.1.219, il messaggio includeva anche il percorso dell'URL, e prima della v2.1.191, un 404 mostrava un messaggio generico Error POSTing to endpoint senza l'URL.

Per i server HTTP, confermare che l'URL sia raggiungibile dalla vostra macchina:

curl -I https://mcp.sentry.dev/mcp

In PowerShell, utilizzare curl.exe invece di curl in modo che la richiesta vada al binario curl reale piuttosto che all'alias Invoke-WebRequest.

La risposta vi dice quale tipo di problema avete:

  • Un 404 o 405: il server è attivo. Molti endpoint MCP rispondono solo alle richieste POST, quindi questo comunque conferma che l'URL è raggiungibile dalla vostra macchina.
  • Un 401 o 403: il server è attivo e dovete autenticarvi. Utilizzare l'accesso al browser in Connettere un server che richiede l'accesso, o per i server che prendono un token invece, come quello di GitHub, passarlo con --header "Authorization: Bearer <token>" sul comando claude mcp add.
  • Nessuna risposta: controllare l'URL e la vostra rete.

Per i server stdio, eseguire il comando configurato direttamente nel vostro terminale per vedere l'errore sottostante. Per il server Playwright da questa guida, eseguire:

npx -y @playwright/mcp@latest

Quello che succede dopo vi dice dove è il problema:

  • Il comando si avvia e attende l'input: il server stesso funziona.

    Eseguire claude mcp get <name> e confermare che il comando mostrato lì corrisponda a quello che avete appena eseguito. Se il comando mostrato differisce da quello che avete digitato, probabilmente avete omesso il separatore -- prima del comando del server. Rimuovere il server e riaggiungerlo con -- al suo posto. Se avete scritto .mcp.json a mano, controllare la sua sintassi e posizione. Prima della v2.1.285, claude mcp get non stampava alcuna riga Command per una voce stdio salvata senza un campo type, come una voce .mcp.json scritta a mano. Su quelle versioni, eseguire claude mcp list invece, che stampa la riga di comando in entrambi i casi.

  • Il comando genera un errore: il messaggio nomina cosa manca, come Node.js o un browser.

Connection timed out at startup

Il server ha impiegato più del timeout di avvio predefinito di 30 secondi. La prima esecuzione di un server stdio può essere lenta mentre npx scarica il pacchetto. Aumentare il limite con la variabile di ambiente MCP_TIMEOUT, in millisecondi:

MCP_TIMEOUT=60000 claude

In PowerShell, impostare la variabile prima del comando sulla stessa riga:

$env:MCP_TIMEOUT = "60000"; claude

Prima della v2.1.299, alcune connessioni a server HTTP attivi andavano in timeout all'avvio indipendentemente da MCP_TIMEOUT. Se usi una di quelle versioni e un server HTTP attivo va ancora in timeout dopo che hai aumentato il limite, aggiorna Claude Code.

Server already exists

Avete già aggiunto un server con quel nome allo stesso ambito. O rimuovete l'entry esistente per primo o scegliete un nome diverso:

claude mcp remove claude-code-docs

Se il nome esiste in più di un ambito, remove segnala exists in multiple scopes. Passare --scope per scegliere quale copia eliminare, ad esempio claude mcp remove claude-code-docs --scope local.

Server connects but no tools appear

Eseguire /mcp all'interno di una sessione e selezionare il server per vedere il suo elenco di strumenti. Se l'elenco è vuoto, il server è stato avviato ma non ha registrato alcuno strumento, il che di solito significa che manca una variabile di ambiente richiesta come una chiave API.

Passa la variabile con --env KEY=value in claude mcp add, oppure nel campo env della voce del server in .mcp.json. La documentazione del server elenca le variabili di cui ha bisogno.

Prima della v2.1.302, /mcp mostrava lo stato tools fetch failed per un server che usava la revisione del protocollo 2026-07-28 e ometteva resultType, ttlMs o cacheScope dalle sue risposte. Se usi una di quelle versioni e un server mostra quello stato, aggiorna Claude Code.

Changes to .mcp.json don't take effect

Claude Code legge .mcp.json all'avvio della sessione. Uscire e riavviare la sessione dopo aver modificato il file.

Se i vostri server ancora non appaiono, eseguire claude mcp list e cercare un avviso di analisi. Claude Code salta le entry malformate e mostra il campo offensivo lì.

Se in precedenza avete rifiutato il server quando richiesto, reimpostare le approvazioni del progetto:

claude mcp reset-project-choices

OAuth sign-in fails or browser doesn't open

Eseguire /mcp, selezionare il server e scegliere Authenticate di nuovo. Se il browser non si apre automaticamente, copiare l'URL mostrato nel terminale e aprirlo manualmente. Vedere Autenticarsi con server MCP remoti per porte di callback fisse e credenziali preconfigurate.

Passaggi successivi

Con un server connesso, esplorare il resto di ciò che MCP abilita: