Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Distribuire un server MCP in produzione

Lezione 12 di 14 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. Dal prototipo al server di produzione
  2. Opzione 1: Hugging Face Spaces
  3. Opzione 2: Docker
  4. Opzioni 3 e 4: Distribuzioni gestite
  5. Mettere in sicurezza la distribuzione
  6. Vedere cosa sta succedendo
  7. Punti chiave

Aggiornamento 2 novembre 2026 — Le Chat è ora Vibe. Dal 28 maggio 2026, Le Chat è stato rinominato Vibe (sempre all’indirizzo chat.mistral.ai): un unico agente per lavoro e codice, che mantiene le tue conversazioni, impostazioni e abbonamenti. L’esperienza legacy di Le Chat rimane accessibile nella modalità Chat; nella modalità Work, gli agenti sono ora competenze (invocate con @), le memorie costituiscono la base di conoscenza e la ricerca approfondita è la competenza Deep Research. I piani si chiamano ora Mistral Free, Pro, Team ed Enterprise. Questa lezione utilizza il nome Vibe; alcuni menu qui descritti potrebbero aver cambiato nome o posizione.

Aggiornamento 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’app 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à.

Dal prototipo al server di produzione

Il tuo server gira in locale e ngrok lo espone al mondo solo per una demo. Il problema sorge quando qualcun altro deve usarlo: chiudi il terminale, l’URL muore e ogni connettore configurato dai tuoi colleghi si rompe. Passare in produzione significa essenzialmente ottenere un indirizzo stabile, disponibile 24/7, servito via HTTPS. Quattro opzioni ti portano a questo risultato, dalla più rapida alla più controllata. La tua scelta dipende principalmente da quanto sono sensibili i tuoi dati e da quanto controllo vuoi avere sull’infrastruttura.

Opzione 1: Hugging Face Spaces

Hugging Face Spaces fornisce macchine virtuali gratuite senza GPU, più che sufficienti per un server MCP che inoltra chiamate API. Questo è il percorso più veloce per una distribuzione reale: tre file e un git push.

mon-mcp-space/
├── app.py              # FastAPI + server MCP
├── requirements.txt    # Dipendenze
└── README.md           # Metadati dello Space

Il file app.py segue la struttura esatta che hai visto finora, tranne per il fatto che i valori sensibili vengono letti dall’ambiente: gli HF Secrets li iniettano lì:

# app.py
"""Server MCP distribuito su Hugging Face Spaces."""

import os
from contextlib import asynccontextmanager

from fastapi import FastAPI
from mcp.server.mcpserver import MCPServer
from mcp.server.transport_security import TransportSecuritySettings

mcp = MCPServer("My Production Server")

@mcp.tool()
def hello(name: str) -> str:
    """Saluta una persona.

    Args:
        name: Il nome della persona

    Returns:
        Messaggio di saluto
    """
    return f"Hello {name} from Hugging Face Spaces!"

@asynccontextmanager
async def lifespan(app: FastAPI):
    async with mcp.session_manager.run():
        yield

# Hostname dello Space, nella forma <user>-<space>.hf.space
SPACE_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[SPACE_HOST, f"{SPACE_HOST}:*"])

api = FastAPI(lifespan=lifespan)
api.mount("/mcp-endpoint", mcp.streamable_http_app(transport_security=security))

# Per le variabili sensibili, usa gli HF Secrets
API_KEY = os.environ.get("MY_API_KEY", "")

La particolarità della piattaforma risiede nel README, il cui header YAML guida la build dello Space. Il campo app_port deve corrispondere alla porta su cui il tuo server ascolta effettivamente; altrimenti, la distribuzione ha successo ma rimane inaccessibile:

---
title: My MCP Server
emoji: 🔧
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
---
# Crea uno Space su huggingface.co
# Push del codice
git push
# Lo Space viene distribuito automaticamente

Il tuo endpoint diventa quindi https://your-username-mon-mcp-space.hf.space/mcp-endpoint/mcp, servito via HTTPS. Rimane un passo di configurazione: dichiara questo hostname, your-username-mon-mcp-space.hf.space, nella variabile MCP_PUBLIC_HOST nelle impostazioni dello Space. Senza di esso, l’SDK rifiuta ogni richiesta con un errore 421 Invalid Host header.

Opzione 2: Docker

Non appena il server tocca dati interni, l’hosting sulla propria infrastruttura diventa la regola, e Docker è il formato standard. Il Dockerfile richiede solo poche istruzioni, con l’installazione delle dipendenze posizionata prima della copia del codice per sfruttare la cache dei layer durante le ricostruzioni:

FROM python:3.12-slim

WORKDIR /app

# Installa le dipendenze
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copia il codice
COPY . .

# Espone la porta
EXPOSE 8000

# Avvia il server
CMD ["uvicorn", "server:api", "--host", "0.0.0.0", "--port", "8000"]
fastapi>=0.115.0
uvicorn>=0.30.0
mcp>=2.2,<3
httpx>=0.27.0   # solo se i tuoi tool lo usano: l'SDK v2 non lo installa più

All’avvio, l’opzione --restart unless-stopped è ciò che distingue una distribuzione di produzione da un semplice test: senza di essa, il primo crash mette offline il tuo server finché qualcuno non se ne accorge.

# Costruisci l'immagine
docker build -t mon-mcp-server .

# Esegui il container
docker run -d \
  --name mcp-server \
  -p 8000:8000 \
  -e MY_API_KEY="secret" \
  -e DATABASE_URL="postgresql://..." \
  --restart unless-stopped \
  mon-mcp-server

Docker Compose rende questa configurazione riproducibile e aggiunge un health check, che l’orchestratore usa per rilevare un server bloccato: un processo attivo che non risponde più è uno scenario che i semplici riavvii automatici non coprono:

# docker-compose.yml
version: "3.8"
services:
  mcp-server:
    build: .
    ports:
      - "8000:8000"
    environment:
      - MY_API_KEY=${MY_API_KEY}
      - DATABASE_URL=${DATABASE_URL}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/"]
      interval: 30s
      retries: 3

Opzioni 3 e 4: Distribuzioni gestite

Prefect Horizon (precedentemente FastMCP Cloud), la piattaforma del team dietro al framework indipendente FastMCP, rimuove il passo dell’infrastruttura: ti logghi su horizon.prefect.io con il tuo account GitHub, scegli il repository e il file del server, e la piattaforma costruisce e pubblica un URL con autenticazione integrata. È rivolto a server scritti con quel framework (pip install fastmcp, from fastmcp import FastMCP), che è distinto dall’SDK ufficiale usato in questo corso; esiste un piano gratuito per progetti personali.

Cloudflare Workers punta a un profilo d’uso diverso: serverless, con esecuzione il più vicino possibile all’utente e quindi latenza ridotta. Un template dedicato avvia il progetto:

# Usa il template MCP di Cloudflare
npm create cloudflare@latest -- remote-mcp-server-authless --template=cloudflare/ai/demos/remote-mcp-authless

Entrambe le opzioni ti risparmiano la gestione di certificati e riavvii, al costo di una dipendenza dalla piattaforma e di vincoli di esecuzione: un Worker serverless, ad esempio, non si sposa bene con un server con stato (stateful).

Mettere in sicurezza la distribuzione

HTTPS è non negoziabile: Vibe rifiuta endpoint in chiaro e un token che viaggia su HTTP è un token compromesso. Tre percorsi portano a questo risultato a seconda del tuo hosting. Un reverse proxy come Nginx o Caddy posizionato davanti al tuo server, con un certificato Let’s Encrypt, copre il caso del server dedicato. Le piattaforme cloud-native (Hugging Face, Cloudflare e la maggior parte dei provider PaaS) forniscono HTTPS automaticamente. Un tunnel, come Cloudflare Tunnel, espone un server che rimane sulla tua rete interna senza aprire porte.

Nessun segreto dovrebbe apparire nel codice. Nota la distinzione tra le due sintassi qui sotto: os.environ["MCP_API_TOKEN"] causa il fallimento dell’avvio se la variabile manca, il che è esattamente il comportamento desiderato per un segreto obbligatorio, mentre os.environ.get() tollera l’assenza per valori opzionali.

import os

# Configurazione tramite variabili d'ambiente
API_TOKEN = os.environ["MCP_API_TOKEN"]       # Obbligatorio
DATABASE_URL = os.environ.get("DATABASE_URL")  # Opzionale
DEBUG = os.environ.get("DEBUG", "false") == "true"

Un server pubblico senza rate limiting prima o poi viene saturato, volontariamente o meno. Un limitatore basato sull’IP è sufficiente nella maggior parte dei casi:

from fastapi import FastAPI, Request
from slowapi import Limiter, _rate_limit_exceeded_handler

limiter = Limiter(key_func=lambda request: request.client.host)
api = FastAPI()
api.state.limiter = limiter

@api.middleware("http")
async def rate_limit(request: Request, call_next):
    # 100 richieste al minuto per IP
    ...

Vedere cosa sta succedendo

In produzione non hai più il tuo terminale davanti a te, e un tool che fallisce una volta su dieci può essere diagnosticato solo con le tracce. Come minimo, strumentalizza input, output e durata di ogni chiamata:

import logging
import time

logger = logging.getLogger("mcp-server")

@mcp.tool()
async def my_tool(param: str) -> str:
    """Il mio tool con logging."""
    start = time.time()
    logger.info(f"Tool chiamato con param={param}")

    try:
        result = await process(param)
        duration = time.time() - start
        logger.info(f"Tool terminato in {duration:.2f}s")
        return result
    except Exception as e:
        logger.error(f"Errore nel tool: {e}")
        raise

Misurare la durata non è un lusso: un tool che impiega dodici secondi a rispondere triggera timeout lato client e dà l’impressione di un server rotto quando in realtà sta funzionando. Prima di annunciare il tuo server, rivedi i seguenti sei punti di configurazione.

  • HTTPS attivo e certificato valido
  • Variabili d’ambiente per tutti i segreti
  • Logging strutturato abilitato
  • Endpoint di health check (/ o /health)
  • Riavvio automatico in caso di crash
  • Rate limiting configurato

Restano due verifiche, quelle che le persone saltano più spesso ma che rivelano i veri problemi: un test con MCP Inspector lanciato dall’esterno, poi un test da Mistral Vibe. Un server che risponde perfettamente dalla tua macchina può essere bloccato da un firewall o da una configurazione CORS non appena viene chiamato da altrove.

Punti chiave

  • Hugging Face Spaces: il più veloce, gratuito, ideale per iniziare
  • Docker: controllo totale, adatto per server dedicati e cloud
  • Prefect Horizon (ex-FastMCP Cloud): distribuzione da GitHub, per server scritti con il framework FastMCP
  • Cloudflare Workers: serverless, bassa latenza, scalabile
  • Sicurezza con HTTPS, variabili d’ambiente e rate limiting
  • Aggiungi monitoraggio e log per il debug in produzione