Fino a poco tempo fa, un assistente come ChatGPT o Claude era una scatola chiusa: sapeva conversare, ma non poteva leggere i tuoi file, interrogare un database o creare una issue su GitHub senza integrazioni costruite a mano, diverse per ogni strumento. Il Model Context Protocol (MCP) nasce per risolvere esattamente questo: e' uno standard aperto, introdotto da Anthropic e oggi adottato praticamente da tutti (OpenAI, Google e persino il nuovo Muse Spark di Meta lo supportano), che funziona come una "presa universale" tra i modelli di IA e il mondo esterno. In questa guida imparerai cos'e', come installarlo e come collegare un assistente ai tuoi file e a GitHub, passo dopo passo.

A chi serve questa guida e cosa otterrai

Questo tutorial e' pensato per chi ha una minima dimestichezza con il terminale e vuole andare oltre la semplice chat: sviluppatori, professionisti tecnici, smanettoni curiosi. Al termine avrai un assistente (useremo Claude Desktop come esempio) capace di leggere e scrivere file in una cartella che decidi tu e di interagire con i tuoi repository GitHub, il tutto tramite MCP. I concetti valgono anche per altri client che supportano il protocollo, come Cursor o l'ecosistema di OpenAI.

Prerequisiti reali

  • Un computer con Windows, macOS o Linux.
  • Node.js installato (versione 18 o superiore): molti server MCP di riferimento girano tramite npx, che fa parte di Node. Puoi verificarlo con node --version.
  • L'app Claude Desktop installata (disponibile per Windows e macOS), oppure un altro client compatibile con MCP.
  • Per la parte GitHub, un token di accesso personale di GitHub.

Come funziona MCP in due minuti

MCP separa due ruoli. Da una parte c'e' il client (l'app di IA, per esempio Claude Desktop) che "parla" il protocollo. Dall'altra ci sono i server MCP: piccoli programmi che espongono capacita' specifiche, come l'accesso al file system, a GitHub, a un database o a un servizio web. Quando fai una richiesta, il modello puo' decidere di invocare uno strumento offerto da un server, riceverne il risultato e usarlo nella risposta. Il vantaggio dello standard e' che un server scritto una volta funziona con qualsiasi client compatibile: niente piu' integrazioni su misura per ogni combinazione.

I server MCP sono piccoli programmi che collegano l'assistente a file, GitHub e altri strumenti.

Passo 1: verifica che Node.js sia installato

Apri il terminale (Prompt dei comandi o PowerShell su Windows, Terminale su macOS/Linux) e digita:

node --version
npx --version

Se vedi due numeri di versione (ad esempio v20.11.0), sei a posto. Se ricevi un errore "comando non trovato", installa Node.js dal sito ufficiale nodejs.org scegliendo la versione LTS, poi riapri il terminale e riprova.

Passo 2: trova e apri il file di configurazione di Claude Desktop

Claude Desktop legge i server MCP da un file chiamato claude_desktop_config.json. Il modo piu' semplice per aprirlo e' dall'app: menu Impostazioni → Sviluppatore → Modifica configurazione. In alternativa lo trovi qui:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Se il file non esiste, crealo. Al primo avvio potrebbe essere vuoto o contenere solo {}.

Passo 3: collega l'assistente a una cartella dei tuoi file

Ora aggiungiamo il server MCP per il file system, limitandolo a una cartella specifica per sicurezza (il modello potra' leggere e scrivere solo li'). Incolla questa configurazione, sostituendo il percorso con una tua cartella reale:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/tuonome/Documenti/progetto-ia"
      ]
    }
  }
}

Su Windows il percorso avra' la forma C:\\Users\\tuonome\\Documenti\\progetto-ia (con le doppie barre rovesciate). Salva il file e riavvia completamente Claude Desktop. Al riavvio dovresti vedere comparire, nella barra degli strumenti della chat, l'icona che indica gli strumenti MCP disponibili.

Passo 4: prova il collegamento con un prompt

Adesso metti alla prova la connessione. In una nuova conversazione scrivi qualcosa come:

Elenca i file presenti nella cartella del progetto, poi crea un file chiamato note.md con un breve riepilogo di cosa contiene la cartella.

Il risultato atteso: Claude ti chiede il permesso di usare lo strumento, elenca i file reali della tua cartella e crea davvero note.md sul disco. La prima volta che un modello agisce sui tuoi file e' un piccolo momento rivelatore: non sta piu' solo parlando, sta facendo. Concedi i permessi solo quando capisci cosa sta per fare.

Passo 5: aggiungi GitHub

Per collegare anche GitHub, aggiungi un secondo server nella stessa sezione mcpServers. Ti servira' un token personale creato dalle impostazioni del tuo account GitHub (Settings → Developer settings → Personal access tokens), con i permessi minimi necessari:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/tuonome/Documenti/progetto-ia"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "il_tuo_token_qui"
      }
    }
  }
}

Riavvia di nuovo l'app. Ora potrai chiedere, per esempio: "Mostrami le ultime tre issue aperte sul repository X e riassumile", e l'assistente le recuperera' davvero da GitHub.

Errori comuni e come risolverli

  • Gli strumenti MCP non compaiono dopo il riavvio. Nove volte su dieci il JSON contiene un errore di sintassi: una virgola di troppo, una parentesi non chiusa. Incolla il contenuto in un validatore JSON online e correggi. Ricorda che l'ultimo elemento di un oggetto non deve avere la virgola finale.
  • "spawn npx ENOENT" o server che non parte. Significa che il sistema non trova npx: Node.js non e' installato o non e' nel PATH. Reinstalla Node.js e riavvia il computer.
  • Su Windows i percorsi danno errore. Usa le doppie barre rovesciate (\\) nei percorsi dentro il JSON, oppure barre normali (/).
  • Il modello dice di non avere accesso ai file. Verifica che il percorso indicato esista davvero e che tu abbia riavviato completamente l'app, non solo chiuso la finestra.

Buone pratiche di sicurezza

MCP e' potente proprio perche' da' al modello la capacita' di agire, e questo richiede prudenza. Limita sempre il server del file system a una cartella dedicata, mai all'intero disco o alla home. Non incollare mai token o password in conversazioni: vanno solo nel campo env del file di configurazione, che resta sul tuo computer. Concedi i permessi di esecuzione degli strumenti caso per caso, leggendo cosa il modello sta per fare, soprattutto quando l'azione modifica file o dati. E installa solo server MCP di cui ti fidi: come per qualsiasi software di terze parti, un server malevolo potrebbe abusare dei permessi.

Varianti, casi avanzati e come proseguire

Una volta capito il meccanismo, le possibilita' si moltiplicano. Esistono server MCP ufficiali e di comunita' per database (PostgreSQL, SQLite), per la ricerca web, per strumenti di produttivita', per il controllo del browser. Puoi anche scrivere il tuo server MCP con gli SDK ufficiali disponibili in Python e TypeScript, per esporre all'IA le API interne della tua azienda o uno strumento su misura: e' il modo in cui MCP passa da curiosita' a infrastruttura seria.

Se non usi Claude Desktop, il protocollo funziona allo stesso modo con altri client compatibili: cambia solo dove si trova il file di configurazione. La documentazione ufficiale su modelcontextprotocol.io elenca i server disponibili e le guide per costruirne di nuovi. Il consiglio pratico e' partire piccoli, con file system e un solo servizio, prendere confidenza con il flusso dei permessi e solo dopo aggiungere strumenti piu' potenti. In pochi passaggi avrai trasformato un assistente conversazionale in un collaboratore capace di agire davvero sui tuoi dati.