Come aggiungere un server MCP a Claude Code

Aggiungere un server remoto via HTTP

Un server remoto è un URL. Claude Code gli parla in streamable HTTP, quindi l'intera registrazione sta in una riga:

claude mcp add --transport http hosttracker https://mcp.host-tracker.com/mcp

Il primo argomento dopo il transport è il nome che vedrai in /mcp e nei nomi degli strumenti; il secondo è l'endpoint. I server che si autenticano con OAuth non richiedono altro sulla riga di comando: la prima volta che apri /mcp, selezioni il server e Claude Code apre il browser per il passaggio di accesso e consenso, poi memorizza il token risultante e lo rinnova da solo. Da Claude Code 2.1.186 puoi anche eseguire l'accesso senza la sessione interattiva, con claude mcp login hosttracker, e aggiungere --no-browser su una macchina senza browser per ottenere un URL da incollare altrove.

I server che si aspettano un token statico lo ricevono invece come intestazione:

claude mcp add --transport http secure-api https://api.example.com/mcp --header "Authorization: Bearer YOUR_TOKEN"

Alcuni server più vecchi parlano ancora il transport SSE. È deprecato a favore di HTTP, e da Claude Code 2.1.265 --transport http prova prima HTTP e ripiega su SSE se il server lo rifiuta, quindi raramente serve ancora --transport sse.

Aggiungere un server locale

Un server locale è un programma che Claude Code avvia per te e con cui comunica tramite standard input e output. Metti il suo comando e i suoi argomenti dopo un doppio trattino, così i flag di Claude Code non vengono confusi con quelli del server:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/projects

Le variabili d'ambiente di cui il server ha bisogno passano tramite --env (forma breve -e), ripetuto una volta per variabile. Un'insidia documentata: l'analizzatore di opzioni legge tutto ciò che segue --env CHIAVE=valore come un'altra coppia, quindi non mettere il nome del server subito dopo; inserisci un'altra opzione in mezzo oppure metti --env prima di --transport:

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server

Se hai già la configurazione del server come JSON, per esempio dal suo README, claude mcp add-json <nome> '<json>' la prende così com'è, incluso type, command, args e env.

Scegliere un ambito: questo progetto, il team o ovunque

Per impostazione predefinita un server viene aggiunto nell'ambito locale, il che significa solo questo progetto, memorizzato nel tuo ~/.claude.json. Esistono altri due ambiti:

• --scope project scrive la voce in un file .mcp.json nella radice del repository. Fallo il commit e ogni collaboratore ottiene lo stesso server; Claude Code chiede a ciascuna persona di approvarlo la prima volta.
• --scope user rende il server disponibile in ogni progetto sulla tua macchina, restando comunque privato per te.

Quando lo stesso nome esiste in più di un ambito, il locale prevale sul progetto, e il progetto prevale sull'utente. L'intera voce viene presa dall'ambito vincente; i campi non vengono mai uniti tra ambiti diversi. Una suddivisione sensata è --scope user per i servizi legati al tuo account personale, come un server di monitoraggio o di ticketing, e --scope project per gli strumenti che l'intero team dovrebbe condividere.

Verificare che funzioni

Esegui claude mcp list fuori da una sessione. Ogni server stampa uno di alcuni possibili stati: connesso, richiede autenticazione, connessione fallita (con lo stato HTTP o l'errore aggiunto dalla 2.1.219), in attesa di approvazione per un server di progetto non ancora approvato, oppure disabilitato per questo progetto. Dentro una sessione, /mcp mostra gli stessi server con il conteggio dei loro strumenti, ti permette di avviare l'accesso per uno che ne ha bisogno, di cancellarne l'autenticazione, o di disabilitarlo per il progetto corrente senza rimuoverlo.

Un test funzionale rapido è una richiesta a cui può rispondere solo il server. Con il server HostTracker connesso, chiedi "quali dei miei monitor sono giù in questo momento?" oppure "esegui un controllo HTTP su example.com da tre ubicazioni"; l'assistente dovrebbe chiamare uno strumento con il nome del server e citare un risultato che non poteva conoscere da solo. Se non succede nulla, di solito la causa è l'elenco degli strumenti: /mcp mostra zero strumenti per un server che si è connesso ma ha fallito l'autorizzazione.

Rimuovere, ispezionare e importare

claude mcp get <nome> stampa la configurazione completa e l'ambito di un server. claude mcp remove <nome> lo elimina insieme a qualsiasi token OAuth memorizzato. Se hai configurato i server prima in Claude Desktop, claude mcp add-from-claude-desktop li importa in modo interattivo; funziona su macOS e su Windows Subsystem for Linux, non su Windows nativo o Linux nativo, e salta un server di Desktop il cui nome contiene caratteri che Claude Code non ammette (solo lettere, cifre, trattini e trattini bassi).

Un server di monitoraggio come primo test

Un servizio di monitoraggio è un buon primo server da collegare perché il risultato di una chiamata a uno strumento è verificabile subito: l'assistente dice che un sito è raggiungibile, e tu puoi aprirlo. Il server di HostTracker non richiede alcuna installazione locale, si autentica con OAuth nel browser, ed espone controlli istantanei da 300 o più ubicazioni oltre ai monitor, agli incidenti, alle finestre di manutenzione e alle pagine di stato del tuo account, quindi "la produzione è online?" viene risposto da controlli reali invece che dai dati di addestramento. La guida correlata su configurazione e risoluzione dei problemi di .mcp.json copre il formato del file, le variabili d'ambiente e i guasti che si incontrano nella pratica.