Un assistente IA, da solo, non sa nulla dei tuoi file, dei tuoi database o dei tuoi strumenti aziendali. Il Model Context Protocol (MCP) nasce per risolvere proprio questo: e' uno standard aperto, introdotto da Anthropic e oggi adottato da molti, che permette ai modelli di collegarsi in modo uniforme a dati e funzioni esterne. In questa guida costruirai un server MCP in Python e lo userai dentro Claude Desktop, in modo che l'assistente possa chiamare i tuoi strumenti personalizzati.

A chi serve e cosa otterrai

E' la guida giusta per sviluppatori e smanettoni che vogliono dare a Claude (o ad altri host compatibili) la capacita' di leggere dati e compiere azioni specifiche: interrogare un file, chiamare un'API interna, calcolare qualcosa. Alla fine avrai un server funzionante che espone due strumenti, collegato a Claude Desktop e richiamabile in linguaggio naturale.

Prerequisiti reali: Python 3.10+, un minimo di dimestichezza con il terminale e con Python, e l'applicazione Claude Desktop installata (Windows o Mac). Useremo uv, il gestore di progetti Python veloce diventato lo standard per questi setup, e l'SDK ufficiale mcp con il framework FastMCP, che riduce drasticamente il codice necessario.

I tre mattoni dell'MCP

Prima di scrivere codice, conviene capire le tre primitive del protocollo:

  • Tools (strumenti): funzioni che il modello puo' invocare per calcolare o agire e ottenere un risultato.
  • Resources (risorse): dati esposti a un indirizzo (URI), che il modello puo' leggere come contesto.
  • Prompts: modelli di conversazione pronti all'uso, richiamabili dall'utente.

L'architettura prevede un server (quello che costruiamo, offre tools e resources), un client e un host che li mette in comunicazione: nel nostro caso l'host e' Claude Desktop.

Il server MCP espone strumenti che Claude puo' richiamare in linguaggio naturale.

Passo 1: preparare il progetto

Installa uv se non lo hai (su Mac/Linux con lo script ufficiale, su Windows con il pacchetto consigliato dalla documentazione). Poi crea il progetto:

uv init server-mcp
cd server-mcp
uv add "mcp[cli]"

Questo crea l'ambiente e installa l'SDK MCP con gli strumenti da riga di comando.

Passo 2: scrivere il server

Crea un file server.py con questo contenuto. Esponiamo due strumenti: uno che calcola quanti giorni mancano a una data, e uno che conta le parole di un testo. Sono esempi semplici, ma il meccanismo e' identico per chiamate ad API o database.

from datetime import date
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("strumenti-utili")

@mcp.tool()
def giorni_mancanti(data_obiettivo: str) -> str:
    """Calcola quanti giorni mancano a una data in formato AAAA-MM-GG."""
    anno, mese, giorno = map(int, data_obiettivo.split("-"))
    delta = date(anno, mese, giorno) - date.today()
    return f"Mancano {delta.days} giorni a {data_obiettivo}."

@mcp.tool()
def conta_parole(testo: str) -> str:
    """Conta le parole e i caratteri di un testo."""
    parole = len(testo.split())
    caratteri = len(testo)
    return f"{parole} parole, {caratteri} caratteri."

if __name__ == "__main__":
    mcp.run(transport="stdio")

La docstring di ogni funzione e' importante: Claude la legge per capire quando e come usare lo strumento. I tipi degli argomenti (qui str) servono al modello per passare i valori corretti.

Passo 3: collegarlo a Claude Desktop

Ora bisogna dire a Claude Desktop come avviare il server. Apri il file di configurazione:

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

Aggiungi (o integra) la chiave mcpServers, indicando il percorso assoluto del tuo progetto:

{
  "mcpServers": {
    "strumenti-utili": {
      "command": "uv",
      "args": ["--directory", "/PERCORSO/ASSOLUTO/server-mcp", "run", "server.py"]
    }
  }
}

Sostituisci /PERCORSO/ASSOLUTO/server-mcp con il percorso reale della cartella. Salva e riavvia completamente Claude Desktop.

La configurazione JSON indica a Claude Desktop come avviare il server.

Passo 4: provarlo

Riaperto Claude Desktop, dovresti vedere l'icona degli strumenti (lo slider/martello) che segnala i tool MCP disponibili. Prova a scrivere:

"Quanti giorni mancano al 2026-12-31?"

Claude riconoscera' lo strumento giorni_mancanti, chiedera' (la prima volta) il permesso di eseguirlo e restituira' il conteggio. Allo stesso modo:

"Conta le parole di questo paragrafo: [incolla un testo]"

Il modello chiamera' conta_parole e ti dara' parole e caratteri. Hai appena esteso le capacita' dell'assistente con codice tuo.

Un esempio piu' utile: leggere i tuoi appunti

Gli strumenti di prova servono a capire il meccanismo, ma il valore vero arriva quando colleghi Claude ai tuoi dati. Ecco uno strumento che cerca una parola dentro un file di appunti locale e restituisce le righe che la contengono — un mini motore di ricerca personale. Aggiungilo a server.py:

from pathlib import Path

@mcp.tool()
def cerca_appunti(parola: str) -> str:
    """Cerca una parola nel file appunti.txt e restituisce le righe trovate."""
    percorso = Path.home() / "appunti.txt"
    if not percorso.exists():
        return "File appunti.txt non trovato nella cartella home."
    righe = [r.strip() for r in percorso.read_text(encoding="utf-8").splitlines()
             if parola.lower() in r.lower()]
    if not righe:
        return f"Nessuna riga contiene '{parola}'."
    return "\n".join(righe[:20])

Dopo aver riavviato Claude Desktop, potrai chiedere: "Cerca nei miei appunti cosa ho scritto su 'fattura'". Claude chiamera' lo strumento, leggera' il file in locale e ti riportera' le righe pertinenti. Lo stesso schema si estende a qualsiasi fonte: una chiamata a un'API meteo, una query a un database SQLite, la lettura di un foglio di calcolo. Il modello non vede mai i tuoi dati grezzi se non quando chiama esplicitamente lo strumento che glieli fornisce.

Permessi e sicurezza: la regola d'oro

Dare a un assistente la capacita' di eseguire codice e leggere file e' potente, ma va trattato con disciplina. Tre principi da tenere a mente. Primo: gli strumenti che scrivono o cancellano dati, inviano email o spendono denaro vanno progettati con cautela, e Claude chiede conferma prima di eseguire un tool, ma sei tu a doverla concedere consapevolmente. Secondo: limita cosa puo' fare un tool — meglio una funzione che legge solo un file specifico che una che esegue comandi arbitrari di sistema. Terzo: non esporre segreti (chiavi API, password) nel codice del server; usa variabili d'ambiente. Un server MCP scritto male e' una porta aperta tanto quanto e' utile uno scritto bene.

Errori comuni e soluzioni

  • Gli strumenti non compaiono in Claude: quasi sempre e' il percorso nel JSON sbagliato o un riavvio mancato. Usa il percorso assoluto e chiudi del tutto l'app prima di riaprirla.
  • "command not found: uv": Claude non trova uv nel PATH. Indica il percorso completo dell'eseguibile uv nella chiave command, oppure usa python con il percorso completo dello script.
  • JSON non valido: una virgola di troppo o le virgolette sbagliate bloccano tutto. Verifica il file con un validatore JSON.
  • Il server si avvia ma va in errore: prova a eseguirlo a mano con uv run server.py per leggere il messaggio d'errore nel terminale.

Varianti, livelli avanzati e quando non serve

Da qui puoi crescere molto: aggiungere resources per esporre file o record di un database, definire prompts riutilizzabili, oppure pubblicare un server MCP remoto raggiungibile via rete e non solo in locale. Lo stesso server, essendo basato su uno standard aperto, funziona con altri host compatibili oltre a Claude Desktop, incluse alcune IDE e altri assistenti.

Quando non vale la pena? Se ti serve una singola integrazione banale, una chiamata diretta all'API del modello e' piu' rapida. MCP brilla quando vuoi che l'assistente acceda in modo strutturato e riutilizzabile a piu' strumenti e dati, con il controllo dei permessi. Per approfondire, la guida ufficiale e' su modelcontextprotocol.io e il corso introduttivo di Anthropic.