Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Configura un server MCP locale (STDIO)

Lezione 4 di 14 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Il tuo primo server MCP locale
  2. Scrittura del server
  3. Configurazione del client STDIO
  4. Test prima dell’integrazione
  5. Punti chiave

Aggiornato il 2 novembre 2026 — MCP Python SDK v2. Questo corso segue ora la versione 2 dell’SDK mcp (2.3.0 al 2 ottobre 2026): MCPServer sostituisce FastMCP, le impostazioni di trasporto si spostano in run() o streamable_http_app(), e un’applicazione esposta sotto un hostname reale deve dichiarare tale hostname (transport_security). Questa è anche la versione richiesta dall’SDK Mistral: l’extra mistralai[agents] richiede mcp>=2.2.0,<3.0. Fonti: Novità nella v2 · Guida alla migrazione · Distribuzione e scalabilità.

Il tuo primo server MCP locale

La modalità STDIO è il punto di partenza naturale per sviluppare e testare un server MCP: tutto gira sulla tua macchina, senza distribuzione, senza URL pubblico e senza certificati da gestire. Modifichi un file, riavvii e osservi. In questa lezione, scriverai un server MCP locale in Python per poi collegarlo a un client.

Come prerequisiti, ti servono Python 3.10 o superiore, una versione aggiornata di pip e, preferibilmente, un ambiente virtuale dedicato. Quest’ultimo punto non è estetico: i pacchetti MCP evolvono rapidamente e un venv separato per progetto ti impedisce di rompere un server funzionante quando installi una dipendenza per un altro.

# Crea un ambiente virtuale
python -m venv mcp-env
source mcp-env/bin/activate  # Linux/Mac
# mcp-env\Scripts\activate   # Windows

# SDK MCP ufficiale (v2) e SDK Mistral con il suo extra agents
pip install "mcp[cli]>=2.2,<3" "mistralai[agents]"

Scrittura del server

Con MCPServer, la classe di alto livello nell’SDK ufficiale (precedentemente FastMCP), un server locale richiede solo poche righe. Istanzii un’applicazione assegnandole un nome descrittivo, poi decori le tue funzioni Python con @app.tool() per esporle.

# serveur_local.py
from mcp.server.mcpserver import MCPServer

# Inizializza il server con un nome descrittivo
app = MCPServer("Local Demo Server")

@app.tool()
def greet(name: str) -> str:
    """Saluta una persona per nome.

    Args:
        name: Il nome della persona da salutare

    Returns:
        Un messaggio di saluto personalizzato
    """
    return f"Hello {name}! Welcome to the world of MCP."

@app.tool()
def calculate(operation: str, a: float, b: float) -> str:
    """Esegue un semplice calcolo matematico.

    Args:
        operation: L'operazione da eseguire (add, sub, mul, div)
        a: Primo numero
        b: Secondo numero

    Returns:
        Il risultato del calcolo
    """
    ops = {
        "add": a + b,
        "sub": a - b,
        "mul": a * b,
        "div": a / b if b != 0 else "Error: division by zero"
    }
    result = ops.get(operation, "Unknown operation")
    return f"{a} {operation} {b} = {result}"

Questo file espone due strumenti. Nota il ruolo delle docstring: non servono solo a documentare il tuo codice per un collega; diventano letteralmente la descrizione che il modello legge per decidere se chiamare calculate invece di greet. Una docstring approssimativa qui porta a chiamate erratiche in seguito.

Configurazione del client STDIO

Lato client, non ti connetti a un indirizzo; spieghi come avviare il server. È questo il ruolo di StdioServerParameters.

# client_stdio.py
from mcp import StdioServerParameters
from mistralai.extra.mcp.stdio import MCPClientSTDIO
from pathlib import Path

# Percorso del tuo server
path_to_server = Path("serveur_local.py")

# Configurazione del server STDIO
server_params = StdioServerParameters(
    command="python",           # Il comando per avviare il server
    args=[str(path_to_server)], # Gli argomenti (il file Python)
    env=None,                   # Variabili d'ambiente (opzionale)
)

# Crea il client MCP
mcp_client = MCPClientSTDIO(stdio_params=server_params)

Tre parametri meritano un approfondimento.

command

È il comando di sistema che avvia il processo server: "python" per un server Python, "node" per un server JavaScript, o il percorso diretto a un binario se il tuo server è compilato.

# Python
command="python"

# Node.js
command="node"

# Un eseguibile compilato
command="./mon_serveur_mcp"

args

È la lista di argomenti passati a quel comando. Per uno script Python, questo include come minimo il percorso del file, ma nulla ti impedisce di passare qui le opzioni del tuo server.

# Script semplice
args=["serveur_local.py"]

# Con argomenti aggiuntivi
args=["serveur_local.py", "--port", "8080", "--verbose"]

env

È il dizionario delle variabili d’ambiente passate al processo server: il canale attraverso cui gli fornisci una chiave API, un URL di database o un flag di debug.

import os

server_params = StdioServerParameters(
    command="python",
    args=["serveur_local.py"],
    env={
        **os.environ,  # Eredita dall'ambiente corrente
        "API_KEY": "your_api_key",
        "DATABASE_URL": "postgresql://...",
        "DEBUG": "true",
    },
)

Il comportamento di questo parametro sorprende spesso. Con env=None, il server ereda l’intero ambiente del processo genitore; con un dizionario, vede rigorosamente solo le variabili elencate. Se fornisci un dizionario senza riversarci os.environ, non stupirti se il tuo server non riesce più a trovare il suo PATH o la tua chiave API: il comportamento è perfettamente logico, semplicemente radicale.

Test prima dell’integrazione

Prima di collegare il tuo server a un agente, testalo in isolamento con l’MCP Inspector. Il ragionamento è semplice: se una chiamata fallisce una volta che il server è connesso a un modello, non saprai se il problema risiede nel tuo codice o nella decisione del modello. L’Inspector rimuove questa ambiguità.

npx @modelcontextprotocol/inspector python serveur_local.py

Il comando apre un’interfaccia web locale dove puoi elencare gli strumenti esposti, ispezionare la descrizione e i parametri che il modello riceverà, attivare una chiamata manuale con argomenti a tua scelta e verificare il formato esatto del valore di ritorno. Prendi l’abitudine di usarlo sistematicamente: sono cinque minuti che ti risparmiano un’ora.

Infine, ecco un’organizzazione dei file che invecchia bene, con il server, il client, le dipendenze, i segreti tenuti fuori dal repository e test unitari per i tuoi strumenti:

mon-projet-mcp/
├── serveur_local.py     # Il server MCP
├── client_stdio.py      # Lo script client
├── requirements.txt     # Dipendenze
├── .env                 # Variabili d'ambiente (mai committate)
└── tests/
    └── test_tools.py    # Test unitari per gli strumenti

Punti chiave

  • Un server STDIO si avvia come processo locale
  • StdioServerParameters configura il comando, gli argomenti e le variabili d’ambiente
  • Le docstring dei tuoi strumenti fungono da descrizione per il modello
  • L’MCP Inspector (npx @modelcontextprotocol/inspector) è essenziale per i test
  • env=None ereda l’intero ambiente; un dizionario esplicito limita le variabili