Nel 2026 il Model Context Protocol (MCP) è diventato lo standard de facto per collegare i modelli di intelligenza artificiale ai dati e agli strumenti del mondo reale. L'idea, lanciata da Anthropic e adottata trasversalmente dal settore, è semplice: invece di scrivere un'integrazione diversa per ogni modello, esponi le tue funzioni tramite un «server MCP», e qualsiasi client compatibile — Claude Desktop, vari editor di codice e altri assistenti — può usarle.

In questa guida costruiremo da zero un server MCP in Python che espone due strumenti utili, e lo collegheremo a Claude Desktop per vederlo all'opera. È un tutorial avanzato ma alla portata di chi sa programmare un minimo in Python: al termine avrai un'integrazione funzionante e lo schema mentale per costruirne altre.

A chi serve e cosa otterrai

Questo tutorial è per sviluppatori, smanettoni e team tecnici che vogliono dare ai propri assistenti IA la capacità di compiere azioni concrete: leggere un database interno, interrogare un'API aziendale, manipolare file, eseguire calcoli specifici. Otterrai un server MCP che espone strumenti personalizzati e impara a registrarli in Claude Desktop.

Prerequisiti reali:

  • Python 3.10 o superiore installato.
  • Dimestichezza con il terminale e con le funzioni Python.
  • Claude Desktop installato (l'app per Windows o macOS) per il test finale. In alternativa puoi testare il server con gli strumenti di sviluppo MCP.
  • Consigliato il gestore di pacchetti uv, veloce e ormai standard, ma vanno benissimo anche pip e un ambiente virtuale.

Concetti chiave: Tools, Resources e Prompts

Un server MCP può esporre tre tipi di capacità, spiegate nella documentazione ufficiale:

  • Tools (strumenti): funzioni che il modello può eseguire, simili a endpoint POST. Servono a compiere azioni o produrre effetti (es. inviare una richiesta, fare un calcolo).
  • Resources (risorse): dati che il modello può leggere, simili a endpoint GET, per caricare informazioni nel contesto.
  • Prompts: modelli di interazione riutilizzabili.

In questa guida ci concentriamo sui Tools, che sono il punto di partenza più utile.

Un server MCP espone strumenti che qualsiasi client compatibile può chiamare.

Passo 1: creare il progetto e installare l'SDK

Apri il terminale e crea il progetto. Con uv:

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

In alternativa, con pip e un ambiente virtuale:

python -m venv .venv
source .venv/bin/activate        # su Windows: .venv\Scripts\activate
pip install "mcp[cli]"

Il pacchetto mcp, pubblicato su PyPI, include l'API di alto livello FastMCP, che gestisce i dettagli del protocollo e ti lascia concentrare sulla logica.

Passo 2: scrivere il server

Crea un file server.py. Definiamo due strumenti: uno che converte valute con un tasso fisso (esempio didattico) e uno che conta le parole di un testo. Il decoratore @mcp.tool() trasforma una normale funzione Python in uno strumento MCP; le annotazioni di tipo e la docstring diventano la descrizione che il modello legge per capire quando e come usarlo.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("strumenti-demo")

@mcp.tool()
def converti_eur_usd(importo: float, tasso: float = 1.08) -> str:
    """Converte un importo da euro a dollari usando un tasso di cambio.

    Args:
        importo: la cifra in euro da convertire.
        tasso: euro/dollaro (default 1.08).
    """
    usd = importo * tasso
    return f"{importo:.2f} EUR = {usd:.2f} USD (tasso {tasso})"

@mcp.tool()
def conta_parole(testo: str) -> int:
    """Conta quante parole contiene un testo."""
    return len(testo.split())

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

Punti importanti: le docstring non sono decorative, sono ciò che permette al modello di scegliere lo strumento giusto; le annotazioni di tipo (importo: float) definiscono lo schema dei parametri. Scrivile con cura.

Passo 3: provare il server in locale

Prima di collegarlo a Claude, verifica che parta senza errori. Con l'SDK puoi usare l'ispettore di sviluppo:

uv run mcp dev server.py

Si aprirà un'interfaccia che elenca gli strumenti esposti (converti_eur_usd e conta_parole) e ti permette di invocarli a mano, controllando input e output. Se gli strumenti compaiono e rispondono, il server è pronto.

L'ispettore di sviluppo MCP permette di testare gli strumenti prima di collegarli al client.

Passo 4: collegare il server a Claude Desktop

Il modo più rapido è lasciare che l'SDK registri il server nella configurazione di Claude:

uv run mcp install server.py --name "Strumenti Demo"

In alternativa, modifica a mano il file di configurazione di Claude Desktop. Su macOS si trova in:

~/Library/Application Support/Claude/claude_desktop_config.json

Su Windows: %APPDATA%\Claude\claude_desktop_config.json. Aggiungi il tuo server alla sezione mcpServers (adatta i percorsi):

{
  "mcpServers": {
    "strumenti-demo": {
      "command": "uv",
      "args": ["--directory", "/percorso/assoluto/mio-server-mcp", "run", "server.py"]
    }
  }
}

Salva il file e riavvia completamente Claude Desktop. Se tutto è corretto, comparirà l'icona degli strumenti: ora puoi chiedere a Claude qualcosa come «Converti 250 euro in dollari» oppure «Quante parole ci sono in questo paragrafo?», e il modello userà i tuoi strumenti, chiedendoti conferma prima di eseguirli.

Errori comuni e soluzioni

  • Il server non compare in Claude: quasi sempre è un percorso sbagliato in claude_desktop_config.json. Usa percorsi assoluti e verifica che uv (o python) sia raggiungibile. Riavvia l'app del tutto, non solo la finestra.
  • «spawn uv ENOENT»: il comando uv non è nel PATH visto da Claude. Indica il percorso completo dell'eseguibile, oppure usa python con l'ambiente virtuale.
  • Lo strumento c'è ma il modello non lo usa: migliora la docstring e i nomi dei parametri perché descrivano chiaramente cosa fa lo strumento e quando serve.
  • Errori di JSON nella config: una virgola di troppo basta a rompere tutto. Valida il file con un controllore JSON.

Varianti e prossimi passi

Da qui puoi crescere in più direzioni. Aggiungi Resources per esporre dati in sola lettura (per esempio il contenuto di file o righe di un database). Trasforma uno strumento in una vera chiamata a un'API esterna usando httpx. Per esporre il server fuori dal computer locale, l'SDK supporta trasporti come HTTP «streamable» al posto della comunicazione su standard input/output.

Una raccomandazione di sicurezza, infine: un server MCP esegue codice e può compiere azioni reali. Esponi solo strumenti di cui ti fidi, valida sempre gli input e fai attenzione a non dare a un assistente IA il potere di operazioni distruttive senza una conferma esplicita. Il codice completo dell'SDK e altri esempi sono disponibili sul repository ufficiale. Con queste basi puoi collegare i tuoi sistemi a Claude e agli altri client MCP, costruendo agenti che fanno cose davvero utili sul tuo perimetro.