Come Creare un Server MCP: Dalla Teoria alla Pratica con un Caso Reale

Hai mai desiderato che un'intelligenza artificiale potesse interrogare direttamente i dati della tua azienda? Con MCP (Model Context Protocol) questo è possibile. In questa guida ti racconto come abbiamo costruito un server MCP reale, collegandolo a un CRM con oltre 1.800 clienti e 5.400 ordini.

Cos'è MCP e perché dovresti conoscerlo

MCP è un protocollo aperto creato da Anthropic che standardizza il modo in cui le applicazioni AI comunicano con fonti di dati esterne. Pensalo come una "USB-C per l'AI": un'interfaccia universale che permette a qualsiasi modello linguistico di connettersi a qualsiasi servizio.

Prima di MCP, collegare un LLM a 5 servizi diversi significava scrivere 5 integrazioni custom. Con 3 modelli AI, il lavoro si moltiplicava per 3. Un problema M×N. MCP lo trasforma in M+N: scrivi un server MCP una volta, funziona con qualsiasi client compatibile.

I tre concetti fondamentali

MCP si basa su tre primitivi:

Come funziona: il flusso completo

Quando un utente scrive una domanda nella chat AI, ecco cosa succede dietro le quinte:

La cosa fondamentale: OpenAI non parla direttamente col server MCP. È il backend che fa da intermediario — riceve le richieste di tool call da OpenAI, le esegue sul server MCP e rimanda i risultati.

L'architettura del nostro progetto

Abbiamo collegato un CRM reale (Snapzoid) a un assistente AI. Ecco lo stack:

Il problema PHP + MCP (e come lo abbiamo risolto)

Il protocollo MCP via SSE (Server-Sent Events) è asincrono: il client mantiene una connessione long-lived e scambia messaggi in parallelo. PHP è sincrono — ogni richiesta segue un flusso lineare request → response. Non può gestire SSE.

La soluzione? Un proxy Python che traduce semplici chiamate REST (che Laravel sa fare perfettamente) in sessioni MCP asincrone:

Il Server MCP in Python

Il server espone 4 tool al modello AI. Ecco la struttura di un tool:

from mcp.server.fastmcp import FastMCP
from pydantic import Field

mcp = FastMCP("Snapzoid CRM", host="0.0.0.0", port=8005)

@mcp.tool()
def cerca_clienti(
    snztoken: str = Field(description="Token autenticazione"),
    query: str = Field(description="Testo da cercare"),
    limit: int = Field(default=10, description="Max risultati")
) -> str:
    """Cerca clienti nel CRM per nome, email, telefono o CF.
    Usa questo tool quando l'utente chiede di trovare un contatto."""
    user_id = get_user_id(snztoken)
    risultati = query_db(
        "SELECT * FROM customer WHERE user_id = %s AND name LIKE %s",
        (user_id, f"%{query}%")
    )
    return json.dumps({"risultati": risultati})

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

Punti chiave da notare:

• La docstring non è solo documentazione — è l'istruzione che l'AI legge per capire quando usare il tool
• I Field(description=...) descrivono ogni parametro all'AI
• Il parametro snztoken garantisce l'isolamento multi-tenant (ogni utente vede solo i suoi dati)
• Il server usa un connection pool MySQL (5 connessioni) per le performance

I 4 tool esposti

Il Proxy: il ponte tra PHP e MCP

Il proxy ha due compiti fondamentali:

L'integrazione Laravel + OpenAI

Il backend Laravel orchestra tutto con un loop tool-call:

// Pseudocodice del loop
$tools = POST proxy/tools/list;          // Recupera tool MCP
$tools = convertiPerOpenAI($tools);       // Adatta il formato

$response = OpenAI($messaggio, $tools);   // Prima chiamata

while ($response ha tool_calls) {
    foreach ($response->tool_calls as $call) {
        $result = POST proxy/tools/call   // Esegui via MCP
        $messages[] = tool_result($result);
    }
    $response = OpenAI($messages, $tools); // OpenAI elabora
}

return $response->content;  // Risposta finale in italiano

Infrastruttura e deployment

Tutto gira su un singolo VPS Contabo con Ubuntu, dietro Nginx reverse proxy e certificati Let's Encrypt:

• mcp.snapzoid.com (porta 8005) — Server MCP con configurazione speciale per SSE: buffering disabilitato, timeout 24h
• proxy-mcp.snapzoid.com (porta 8006) — Proxy REST, timeout standard 60s
• Entrambi gestiti da systemd con auto-restart (max 5 tentativi in 60 secondi)
• Python 3.11 compilato da sorgente (Ubuntu 20.04 ha solo Python 3.8)

Come testare un server MCP

Prima di collegare tutto, è fondamentale testare il server MCP isolatamente:

1. MCP Inspector (GUI)

npx @modelcontextprotocol/inspector
# Inserisci: https://mcp.snapzoid.com/sse?snz-token=TOKEN

Tool visuale di Anthropic: mostra i tool disponibili, permette di chiamarli e ispezionare le risposte.

2. Curl (terminale)

curl -X POST https://proxy-mcp.snapzoid.com/tools/call \
  -H "Content-Type: application/json" \
  -H "X-Snz-Token: IL_TUO_TOKEN" \
  -d '{"name":"statistiche_generali","arguments":{}}'

3. Test full stack

curl "https://app.snapzoid.com/api/TOKEN/ai/ask?q=quanti+clienti+ho"

Le lezioni imparate

Ogni progetto reale ha i suoi ostacoli. Ecco quelli che abbiamo incontrato e risolto:

I risultati

Conclusione

MCP non è solo un protocollo — è un cambio di paradigma nel modo in cui colleghiamo AI e dati aziendali. Con un investimento relativamente contenuto (un server Python, un proxy e qualche riga di Laravel) puoi dare ai tuoi utenti un assistente AI che interroga dati reali in linguaggio naturale.

I punti chiave da ricordare:

• MCP è language-agnostic — il server può essere in Python, il backend in PHP, il frontend in qualsiasi cosa
• Le docstring sono fondamentali — sono le istruzioni che l'AI legge per decidere quando usare un tool
• Il proxy è necessario con PHP — ma aggiunge anche vantaggi come l'iniezione automatica del token
• Testa sempre in isolamento — MCP Inspector e curl prima di collegare tutto
• L'isolamento multi-tenant è critico — mai usare stato globale, sempre parametri espliciti

Il protocollo è giovane e in evoluzione (il nuovo Streamable HTTP semplifica ulteriormente il deployment), ma è già pronto per la produzione. Se lavori con PMI e vuoi differenziarti, un assistente AI collegato ai dati reali del cliente è un valore aggiunto enorme.