Workbranch › Guide

Come collegare server MCP a Claude Code

I server MCP danno a Claude Code accesso a strumenti esterni al tuo codice, come un issue tracker, un database o uno strumento di design. Questa guida mostra i comandi per aggiungerne uno, dove viene salvata l'impostazione, come accedere e come capire se funziona.

Aggiornato 30 ottobre 2026

I comandi qui sotto seguono la documentazione di Claude Code di Anthropic a ottobre 2026. I comandi claude mcp si eseguono nel normale terminale, non dentro una sessione di Claude Code.

Aggiungere un server remoto (il caso più comune)

Un servizio ospitato ti fornisce un indirizzo web per il suo server MCP, che trovi nelle sue istruzioni di configurazione. Per questi server Anthropic consiglia il trasporto HTTP.

1. Nel terminale, entra con cd nel progetto in cui lo userai.
2. Esegui claude mcp add --transport http notion https://mcp.notion.com/mcp, sostituendo nome e indirizzo con i tuoi. Il nome è quello che vedrai negli elenchi e in /mcp.
3. Se il servizio usa una chiave API invece di un accesso con account, passala come header: --header "Authorization: Bearer your-token".

I server più vecchi potrebbero offrire solo SSE, che è deprecato. Le versioni recenti di Claude Code provano prima HTTP e passano da sole a SSE se serve; nelle versioni più vecchie usa --transport sse.

Aggiungere un server locale

Un server locale (stdio) è un programma che gira sul tuo computer, spesso avviato con npx.

1. Scrivi prima le opzioni di Claude, poi --, poi il comando del server: claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server.
2. Claude Code passa tutto ciò che segue -- direttamente al programma del server. Senza il separatore, i flag destinati al server (come -y) vengono letti come opzioni di Claude Code.
3. Quando usi --env, metti un'altra opzione tra questa e il nome del server, come nell'esempio, altrimenti il nome viene letto come un'altra variabile.

Scegliere un ambito

Scegli user per gli strumenti che vuoi ovunque, come la tua app di note, e project per gli strumenti che servono a tutto il team in un repository. Se lo stesso server è definito in più posti, Claude Code si connette una sola volta, con questo ordine di priorità: local, project, user, poi i server dei plugin, poi i connettori di claude.ai. I tre ambiti vengono confrontati per nome; i server dei plugin e i connettori contano come duplicati quando puntano allo stesso indirizzo o comando. La voce che prevale viene usata per intero; i campi non vengono combinati.

Non mettere segreti direttamente in un .mcp.json condiviso. Il file accetta variabili come ${API_KEY} o ${API_BASE_URL:-https://api.example.com}, che ognuno imposta nel proprio ambiente.

Accedere a un server che richiede un account

1. Avvia Claude Code con claude.
2. Digita /mcp. Il pannello elenca i server a cui devi ancora accedere.
3. Seleziona il server e segui l'accesso nel browser. Il token viene salvato sul tuo computer e rinnovato automaticamente.
4. In alternativa, dalla shell esegui claude mcp login name. Esci con claude mcp logout name.

Alcuni servizi richiedono di registrare prima un'app presso di loro. In quel caso aggiungi il server con --client-id, --client-secret (ti verrà chiesto di digitarlo) e, se la loro configurazione richiede un redirect fisso, --callback-port.

Verificare che funzioni

• claude mcp list mostra ogni server con il suo stato: Connected (connesso), Needs authentication (richiede autenticazione), Failed to connect (connessione non riuscita), Pending approval (in attesa di approvazione) o Disabled for this project (disattivato per questo progetto).
• claude mcp get name mostra i dettagli di un server, compreso l'errore HTTP quando fallisce.
• Dentro una sessione, /mcp mostra lo stesso stato e ti permette di riconnetterti.
• Infine, chiedi a Claude di fare qualcosa che solo quel server può fare, per esempio "elenca le mie issue aperte su Linear".

Rimuovi un server con claude mcp remove name.

Da sapere

• I server di progetto chiedono prima: la prima volta che una sessione trova server nel .mcp.json di un repository, Claude Code ti chiede di approvarli. Annulla le tue scelte con claude mcp reset-project-choices. Approva solo server di repository di cui ti fidi.
• I permessi valgono comunque: ogni chiamata a uno strumento MCP può chiederti conferma come qualsiasi altro strumento; vedi come gestire i permessi in Claude Code.
• Risultati grandi: Claude Code avvisa quando uno strumento restituisce più di 10.000 token e per impostazione predefinita limita l'output a 25.000. Puoi alzare il limite con la variabile d'ambiente MAX_MCP_OUTPUT_TOKENS.
• Plugin: alcuni plugin portano con sé i propri server MCP, quindi installare un plugin può essere la strada più semplice; vedi come installare i plugin in Claude Code.

Se non funziona

• Failed to connect: esegui claude mcp get name per vedere l'errore, controlla l'URL, poi esegui /mcp reconnect all in una sessione (versioni recenti) per riprovare.
• Un server locale lento va in timeout all'avvio: avvia Claude Code con un limite più lungo, per esempio MCP_TIMEOUT=10000 claude (in millisecondi).
• "has a url but no type": a una voce JSON per un server remoto manca "type": "http".
• La chiave API viene rifiutata: Claude Code avvisa se ci sono spazi o a capo all'inizio o alla fine di un header. Aggiungi di nuovo il server incollando il token in modo pulito.

Fonti

• Claude Code user FAQ (Claude Help Center, verificato il 30 ottobre 2026)
• Connect Claude Code to tools via MCP (Claude Code Docs, verificato il 30 ottobre 2026)

Domande frequenti