Integrazione Claude Code MCP: Connetti Strumenti all'Agente

Ultimo aggiornamento: June 28, 2026

Di base, Claude Code legge ed edita i file ed esegue comandi shell. Non può leggere i tuoi problemi di GitHub, interrogare il tuo database o pilotare un browser. Il Model Context Protocol (MCP) colma questo divario: è lo standard plug che permette all'agente di comunicare con strumenti e dati esterni. Questa guida mostra i comandi esatti claude mcp add, quando scegliere un server locale rispetto a uno remoto, come funzionano gli scope, quali server vale la pena collegare e le verifiche di sicurezza da eseguire prima di fidarsi di uno.

Risposta rapida: come aggiungere un server MCP a Claude Code?

Si registra un server con il comando claude mcp add, dopodiché Claude Code può richiamarne gli strumenti durante una sessione.

Per un server locale che viene eseguito come processo sulla tua macchina:

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

Per un server remoto raggiunto tramite HTTPS:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

Dopo aver aggiunto un server, esegui /mcp all'interno di Claude Code per vedere il suo stato di connessione e completare qualsiasi accesso OAuth. Usa claude mcp list per confermare l'iscrizione. La documentazione ufficiale dei comandi si trova in Claude Code MCP docs.

Cos'è MCP e perché collegarlo a Claude Code?

MCP è un protocollo aperto, pubblicato per la prima volta da Anthropic, che definisce come un client AI e un server di strumenti scambiano capacità. Un server pubblicizza strumenti (azioni che l'agente può eseguire), risorse (dati che può leggere) e prompt. Qualsiasi client consapevole di MCP può usare qualsiasi server MCP, quindi un server GitHub funziona in Claude Code, in un IDE o in un altro agente senza colla personalizzata. La specifica e il registro dei server sono disponibili su modelcontextprotocol.io.

Il vantaggio pratico: invece di incollare il corpo di un problema nella chat, si collega il server GitHub una volta e si chiede all'agente di leggere, etichettare e rispondere ai problemi direttamente. Per approfondire il funzionamento del protocollo stesso, consulta MCP explainer, e per la guida completa sugli strumenti in contesto, Claude Code ultimate guide.

Un server può essere un piccolo script stdio che hai scritto, un'immagine Docker o un endpoint SaaS ospitato da un vendor. Claude Code li tratta tutti allo stesso modo una volta che parlano MCP.

Quale trasporto dovresti usare: locale o remoto?

Il trasporto è come Claude Code raggiunge il server. I server locali vengono eseguiti sulla tua macchina tramite stdio; i server remoti vengono eseguiti altrove e rispondono tramite HTTP o SSE. La scelta segue solitamente dove risiedono i dati.

Usa un server stdio locale quando lo strumento ha bisogno di file o servizi sul tuo laptop, come una cartella di asset del progetto o un'istanza Postgres su localhost. Usa un server HTTP o SSE remoto quando un vendor lo ospita già, perché salti l'installazione e ricevi aggiornamenti senza toccare la tua configurazione. I server remoti quasi sempre ti autenticano tramite OAuth, che tu attivi dal menu /mcp.

Scegliere uno scope: locale, progetto o utente

Lo Scope decide chi vede il server e dove viene salvata la configurazione. Claude Code supporta tre tipi, e sceglierne il giusto mantiene i segreti fuori dal tuo repo pur condividendo server sicuri con il team.

Imposta lo scope con il flag --scope, ad esempio claude mcp add --scope project .... Lo scope project scrive un .mcp.json sottoposto a controllo versione, quindi non inserire mai un token grezzo; fai riferimento a una variabile d'ambiente invece. Lo scope local è quello predefinito e il più sicuro per testare un nuovo server prima di impegnarsi a condividerlo. Se costruisci anche Claude Code skills, mantieni lo scope del server e lo scope delle skill coerenti in modo che un collega che tira il repo ottenga una configurazione funzionante.

Come si aggiunge un server con claude mcp add?

Lo schema è lo stesso per ogni server: un nome, un flag di trasporto opzionale e il comando o l'URL. Il separatore -- segna l'inizio del comando locale e dei suoi argomenti.

Aggiungi un server filesystem locale limitato a una cartella in modo che l'agente possa toccare solo ciò che autorizzi:

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

Passa i segreti come variabili d'ambiente invece di codificarli in modo permanente:

claude mcp add my-api --env API_KEY=your_key_here -- node ./my-mcp-server.js

Aggiungi un server remoto con il suo trasporto e l'URL:

claude mcp add --transport sse linear https://mcp.linear.app/sse

Poi gestisci quello che hai:

• claude mcp list mostra ogni server registrato e il suo stato.
• claude mcp get <name> stampa la configurazione di un server.
• claude mcp remove <name> lo disiscrive.
• /mcp (digitato in una sessione) mostra lo stato di connessione live ed esegue l'OAuth.

Tieni l'uso dei flag vicino alla documentazione ufficiale; i vendor cambiano occasionalmente il nome del pacchetto o l'URL di un server, quindi copia il valore corrente dal README del server stesso piuttosto che indovinare.

Server MCP comuni da collegare

Inizia con un server che elimina un vero fastidio, provalo e poi aggiungine altri. Questi sono quelli che gli sviluppatori cercano per primi e ciò che ognuno sblocca.

Il Playwright MCP server è il più efficace per il lavoro front-end: l'agente apre la tua pagina, fa clic attraverso un flusso e segnala cosa è andato storto con uno screenshot. Un server database è utile per domande sullo schema solo lettura, ma limitarlo a una replica di sola lettura in modo che una query errata non possa mai scrivere. Quando inizi a concatenare diversi server insieme, reindirizza il lavoro pesante a un worker dedicato usando Claude Code subagents in modo che la sessione principale rimanga reattiva.

Scenario: collegare un server MCP di GitHub per aprire PR

Supponiamo che tu voglia che l'agente triagi i problemi e apra le pull request in un repository. GitHub ospita un server MCP remoto ufficiale, quindi non devi installare nulla localmente.

1. Registrare il server ospitato:

   claude mcp add --transport http github https://api.githubcopilot.com/mcp/
   

2. Digitare /mcp in Claude Code, selezionare github e completare l'accesso OAuth nel tuo browser. Il token rimane con GitHub; non devi mai incollarlo in un file.

3. Confermare gli strumenti caricati con claude mcp list.

4. Ora chiedere in linguaggio semplice:

   • "Elenca i problemi aperti etichettati come bug e riassumi i tre principali."
   • "Apri una PR di bozza da fix/login-redirect a main con una breve descrizione."
   • "Leggi la PR #214 e segnala qualsiasi cosa tocchi l'autenticazione."

L'agente legge i thread dei problemi, prepara il corpo della PR e collega il problema giusto, tutto senza che tu lasci il terminale. Concedi prima all'app GitHub l'accesso a un singolo repository, rivedi ciò che propone l'agente e ampliare l'accesso solo quando ti fidi del flusso. L'elenco completo degli strumenti del server e l'opzione di auto-hosting sono documentati nel GitHub MCP server repo.

È sicuro collegare un server MCP?

Un server MCP può eseguire codice sulla tua macchina o agire sui tuoi account, quindi trattalo come installare una dipendenza: collega solo i server di cui ti fidi. Il rischio è reale perché un server dannoso o difettoso potrebbe esfiltrare file o compiere azioni distruttive con le tue credenziali.

Esegui questa checklist prima di aggiungere un server:

• Conferma la fonte. Preferisci i server ufficiali del vendor (GitHub, Sentry) o i server di riferimento pubblicati rispetto a un pacchetto sconosciuto.
• Leggi quali strumenti espone. Un server "leggimi i problemi" non dovrebbe richiedere l'accesso in scrittura all'intero disco.
• Scope strettamente. Indica i server filesystem su una cartella progetto e i server database su una replica di sola lettura.
• Tieni i segreti fuori da .mcp.json. Usa variabili d'ambiente e non committare mai un token reale.
• Concedi il minimo privilegio sull'OAuth. Dai a un'app GitHub un repo, non l'intera org, finché non ti fidi.
• Rivedi le azioni prima di approvare. Leggi la PR o la query che propone l'agente; non approvare automaticamente scritture da un nuovo server.

Anthropic segnala il rischio di prompt-injection per i server che recuperano contenuti web non fidati, quindi fai molta attenzione con qualsiasi server che estrae pagine arbitrarie. L'attuale guida sulla sicurezza si trova in Claude Code MCP docs.

Risoluzione dei problemi delle connessioni MCP

La maggior parte dei malfunzionamenti è di configurazione o autenticazione, non del protocollo. Procedi in questo ordine:

• Server non elencato: riesegui claude mcp list. Se manca, il comando add probabilmente ha fallito; controlla se c'è un errore di battitura nel separatore -- o nel nome del pacchetto.

• Stato mostra fallimento in /mcp: il processo non è riuscito ad avviarsi. Per i server stdio, esegui il comando grezzo (ad esempio la riga npx) nel tuo terminale per vedere l'errore reale.

• Autenticazione fallita: apri /mcp, seleziona il server e ripeti il flusso OAuth. Per i server basati su token, conferma che la variabile d'ambiente sia impostata nella shell che ha avviato Claude Code.

• Strumenti non visibili: riavvia la sessione di Claude Code in modo che ricarichi le capacità del server, quindi verifica che lo scope sia quello visibile dal progetto corrente.

• Scope sbagliato: un server aggiunto con --scope local non sarà visibile per i colleghi; aggiungilo nuovamente con --scope project se dovrebbe essere condiviso.

Quando un server remoto cambia il suo URL o un pacchetto viene rinominato, la tua configurazione salvata diventa obsoleta. Recupera il valore corrente dal README del server e riaggiungilo piuttosto che modificarlo a caso.

Punto chiave

MCP trasforma Claude Code da un agente file-and-shell in uno che parla con i tuoi strumenti reali. Aggiungi i server con claude mcp add, scegli stdio per i dati locali e HTTP/SSE per i servizi ospitati, e imposta lo scope su chi dovrebbe vedere il server. Collega prima un server utile, il server GitHub è un ottimo inizio, e verifica la fonte e i permessi di ogni server prima di fidarti. Mantieni i token nelle variabili d'ambiente, limita strettamente l'accesso a filesystem e database, e rivedi le azioni dell'agente finché un nuovo server non se lo guadagna.