Architettura di un server MCP personalizzato
In questa pagina
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):MCPServersostituisceFastMCP, le impostazioni di trasporto si spostano inrun()ostreamable_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’extramistralai[agents]richiedemcp>=2.2.0,<3.0. Fonti: Novità nella v2 · Guida alla migrazione · Distribuzione e scalabilità.
Progettare un server MCP per la produzione
Un prototipo MCP sta in un file di quaranta righe, e spesso basta questo per convincere un team. Passare all’uso reale cambia tutto: più persone chiamano il server, gli strumenti si moltiplicano, la configurazione varia tra gli ambienti e il file singolo diventa impossibile da mantenere. Questa lezione copre le decisioni architetturali che ti impediscono di sbattere contro quel muro: scegliere un framework, strutturare il progetto, gestire configurazione ed errori, e decidere tra server con stato (stateful) e senza stato (stateless).
Scegliere il tuo framework
In Python, la classe MCPServer dell’SDK ufficiale (precedentemente FastMCP) è lo strumento standard. Espone un’API basata su decoratori e gestisce il protocollo MCP per te, così un server prende vita in tre righe:
from mcp.server.mcpserver import MCPServer
app = MCPServer(
"My Server",
instructions="MCP Server for project management",
)
I team JavaScript e TypeScript hanno l’SDK MCP ufficiale pubblicato da Anthropic. La logica è comparabile anche se la sintassi differisce:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({
name: "My Server",
version: "1.0.0",
});
La scelta dipende meno dalle capacità e più dall’ecosistema da cui il server recupererà i dati. Un server che interroga un database via SQLAlchemy o riutilizza script di elaborazione esistenti sarà naturalmente in Python; un server supportato da un’applicazione Express esistente rimarrà in TypeScript. La tabella seguente riassume le differenze pratiche.
| Criterio | MCPServer (SDK Python) | SDK MCP (TypeScript) |
|---|---|---|
| Maturità | Molto matura | Matura |
| Decoratori | @app.tool() | Metodo server.tool() |
| Trasporto HTTP | Integrato (FastAPI) | Integrato (Express) |
| Community | Ampia | Ampia |
Una struttura di progetto duratura
La struttura di directory raccomandata separa quattro responsabilità: ciò che il modello vede (tools/), ciò che accede ai dati (services/), ciò che controlla l’accesso (auth/) e ciò che descrive l’ambiente (config.py, .env).
my-mcp-server/
├── server.py # Punto di ingresso FastAPI + montaggio MCP
├── tools/
│ ├── __init__.py
│ ├── project_tools.py # Strumenti di gestione progetti
│ ├── file_tools.py # Strumenti di gestione file
│ └── search_tools.py # Strumenti di ricerca
├── services/
│ ├── __init__.py
│ ├── database.py # Accesso al database
│ └── external_api.py # Chiamate API esterne
├── auth/
│ ├── __init__.py
│ └── middleware.py # Middleware di autenticazione
├── config.py # Configurazione (variabili d'ambiente)
├── Dockerfile # Containerizzazione
├── requirements.txt # Dipendenze Python
├── .env # Variabili d'ambiente (non committate)
└── tests/
├── test_tools.py
└── test_integration.py
Questa separazione ha una conseguenza diretta e concreta: i tuoi strumenti non contengono più SQL o chiamate HTTP, solo validazione e delega a un servizio. Puoi quindi testare la logica di business senza passare per MCP e cambiare database senza toccare una singola docstring che il modello vede.
Il punto di ingresso: server.py
Il file principale non fa altro che assemblare i componenti: crea l’applicazione FastAPI, impila i middleware e monta ogni server MCP sul proprio route.
# server.py
"""Punto di ingresso del server MCP."""
from contextlib import asynccontextmanager
import os
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from mcp.server.transport_security import TransportSecuritySettings
from tools.project_tools import project_mcp
from tools.search_tools import search_mcp
from auth.middleware import AuthMiddleware
# Ogni server MCP deve avviare il proprio session manager
@asynccontextmanager
async def lifespan(app: FastAPI):
async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
yield
# Applicazione FastAPI
api = FastAPI(
title="My MCP Server",
version="1.0.0",
lifespan=lifespan,
)
# CORS per client web
api.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["*"],
allow_headers=["*"],
)
# Middleware di autenticazione
api.add_middleware(AuthMiddleware)
# Hostname pubblico sotto cui i server sono serviti (altrimenti: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])
# Monta i server MCP su route distinte
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))
# Home page (opzionale ma utile)
@api.get("/")
async def root():
return {
"service": "My MCP Server",
"version": "1.0.0",
"endpoints": {
"projects": "/projects/mcp",
"search": "/search/mcp",
},
}
if __name__ == "__main__":
import uvicorn
uvicorn.run(api, host="0.0.0.0", port=8000)
Montare su route distinte permette agli utenti di abilitare solo il dominio di cui hanno bisogno: chi cerca documentazione si connette a /search/mcp senza che gli vengano offerti strumenti di gestione progetti. Quanto alla home page, sembra banale finché un collega non chiede l’URL esatto dell’endpoint; risponde per te e funge da controllo di salute.
Un modulo strumenti per dominio
Ogni file nella cartella tools/ dichiara il proprio oggetto MCPServer e raggruppa strumenti dello stesso dominio funzionale. Ecco come appare il modulo di gestione progetti, importato in precedenza da server.py:
# tools/project_tools.py
"""Strumenti MCP per la gestione progetti."""
from mcp.server.mcpserver import MCPServer
from services.database import db
project_mcp = MCPServer(
"Project Manager",
instructions="Tools for project and task management",
)
@project_mcp.tool()
async def create_project(name: str, description: str = "") -> str:
"""Crea un nuovo progetto.
Args:
name: Nome del progetto (2-100 caratteri)
description: Descrizione del progetto (opzionale)
Returns:
JSON con i dettagli del progetto creato
"""
project = await db.projects.create(name=name, description=description)
return project.to_json()
@project_mcp.tool()
async def list_projects(status: str = "active") -> str:
"""Elenca i progetti per stato.
Args:
status: Filtra per stato: active, archived, all (default: active)
Returns:
JSON con l'elenco dei progetti
"""
projects = await db.projects.list(status=status)
return projects.to_json()
Nota quanto sono brevi i corpi delle funzioni: solo due righe ciascuno, perché l’accesso ai dati vive in services/database.py. Lo strumento descrive semplicemente il suo contratto al modello e delega.
Configurazione centralizzata
Qualsiasi valore che cambia tra la tua macchina e il server di produzione deve provenire dall’ambiente, mai dal codice. Un unico file config.py raccoglie queste variabili con i loro valori predefiniti:
# config.py
"""Configurazione del server MCP."""
import os
from dataclasses import dataclass
@dataclass
class Config:
api_token: str = os.getenv("MCP_API_TOKEN", "")
database_url: str = os.getenv("DATABASE_URL", "sqlite:///data.db")
debug: bool = os.getenv("DEBUG", "false").lower() == "true"
port: int = int(os.getenv("PORT", "8000"))
max_results: int = int(os.getenv("MAX_RESULTS", "50"))
config = Config()
Il parametro max_results illustra il beneficio di questo approccio: il giorno in cui uno strumento restituisce troppi risultati e satura il contesto del modello, regoli una variabile d’ambiente e riavvii, senza ridistribuire il codice.
Errori leggibili dal modello
Un’eccezione Python che risale improvvisamente non dice nulla al modello: vede un fallimento senza capire il perché, e spesso ritenta identicamente. Invece, standardizza un formato di risposta di errore esplicito con un codice e un messaggio.
import json
def error_response(message: str, code: str = "error") -> str:
"""Formatta un messaggio di errore standardizzato."""
return json.dumps({
"success": False,
"error": {"code": code, "message": message}
}, ensure_ascii=False)
@project_mcp.tool()
async def get_project(project_id: str) -> str:
"""Recupera i dettagli del progetto per ID."""
try:
project = await db.projects.get(project_id)
if not project:
return error_response(f"Project {project_id} not found", "not_found")
return project.to_json()
except Exception as e:
return error_response(f"Server error: {str(e)}", "server_error")
La differenza è decisiva nella conversazione. Di fronte a not_found, il modello capisce che deve prima elencare i progetti per trovare l’ID giusto; di fronte a un’eccezione silenziosa, si arrende o va in loop.
Con stato o senza stato
Un server con stato (stateful) mantiene le informazioni tra le chiamate: database in memoria, sessioni utente, contesto di lavoro. Questo è comune per i server di gestione, come il task manager della lezione precedente. Un server senza stato (stateless) gestisce ogni richiesta indipendentemente, senza ricordare nulla: consigliato per calcolo puro o trasformazione, e permette la scalabilità orizzontale poiché qualsiasi istanza può gestire qualsiasi richiesta. L’SDK v2 abilita questo con un parametro dell’applicazione HTTP (non più passato al costruttore). Nota che con la specifica del 28-07-2026, il protocollo stesso non conosce più le sessioni: questa impostazione riguarda solo i client che negoziano una versione precedente del protocollo.
app = MCPServer("Stateless Server")
# L'impostazione viene passata durante la costruzione dell'applicazione HTTP
mcp_app = app.streamable_http_app(stateless_http=True)
Decidi questa questione prima di scrivere i tuoi strumenti, non dopo: passare da un server con stato a uno senza stato significa spostare tutto lo stato in un database esterno, il che riscrive una buona parte del codice.
Punti chiave
- Separa i tuoi strumenti in moduli tematici in una cartella
tools/ - Usa FastAPI come base HTTP, monta i server MCP su route dedicate e passa il loro lifespan
- Centralizza la configurazione tramite variabili d’ambiente
- Standardizza i formati di risposta agli errori affinché il modello possa usarli
- Scegli tra con stato (gestione dati) e senza stato (calcolo puro)
- Aggiungi una home page
/per documentare i tuoi endpoint MCP