Server MCP

Approfondimento · AI

Server MCP

MCP è il modo standard con cui un’applicazione AI scopre e usa strumenti esterni. Non è un modello, non è un agente: è un contratto. Questa pagina spiega com’è fatto, quando conviene e come costruirne un server senza aprire buchi di sicurezza.

In breve. Un server MCP espone capacità a un host: tool che il modello può chiamare, risorse che l’applicazione può leggere, prompt che l’utente può scegliere. Il valore è il confine standard; il rischio è che quel confine venga attraversato con troppi permessi.

Che cos’è MCP

L’architettura ha tre ruoli. L’host è l’applicazione che l’utente usa: un editor, un assistente, una chat. Il client è il componente che parla con un server: ogni client è collegato a un solo server. Il server espone capacità. Un host può avere più client, quindi più server.

Il dialogo è JSON-RPC. Il server può essere locale, avviato come processo e collegato via stdio, oppure remoto, raggiunto via Streamable HTTP. Nel primo caso eredita i permessi del processo che lo avvia; nel secondo serve autenticazione e autorizzazione esplicite.

Le primitive sono tre, e la differenza sta in chi decide.

Primitiva Chi decide A cosa serve Esempio
Tool Il modello Eseguire un’azione o una query. Cercare un articolo, inviare un messaggio.
Resource L’applicazione Leggere dati identificati da un URI. catalogo://schema, un file, una pagina.
Prompt L’utente Scegliere un modello di richiesta preconfezionato. “Riassumi questo documento”.

JSON-RPC significa che ogni messaggio è un oggetto con un metodo, dei parametri e un identificativo. La risposta riporta lo stesso identificativo, così le due parti sanno a cosa corrisponde. Non è un protocollo di streaming di testo: è una sequenza di richieste e risposte, e questo lo rende facile da ispezionare e da proxare.

Lo stato, nella revisione 2026-07-28, non vive nella connessione: vive nelle richieste. È una scelta che semplifica il deployment — un server può essere replicato, riavviato, messo dietro un bilanciatore — ma sposta la responsabilità della sessione sull’applicazione. Se ti serve memoria tra una chiamata e l’altra, devi progettarla tu.

Vale la pena dire cosa MCP non è. Non è un formato per scrivere prompt: quelli restano testo. Non è un modello: non genera nulla. Non è un agente: non decide quando usare un tool, lo espone soltanto. Non è nemmeno un sostituto delle API: è un modo standard di presentarle a un’applicazione AI. Se confondi questi livelli, finisci per chiedere al protocollo cose che non può fare.

La revisione 2026-07-28 ha cambiato il protocollo in modo sostanziale: è diventato stateless. Non esiste più l’handshake initialize: ogni richiesta porta con sé versione e capability nei _meta. Esistono server/discover per conoscere le capacità e subscriptions/listen per le sottoscrizioni; le richieste avviate dal server usano un pattern multi round-trip invece di un canale permanente. Non è una semplificazione: è un modello diverso, più adatto a deployment distribuiti.

Attenzione. Molti client e server usano ancora la revisione 2025-11-25. Prima di scrivere codice, verifica quale generazione supporta l’host che hai davanti: un server moderno può non essere visto da un client vecchio, e viceversa.

Architettura MCP: un host con più client, ciascuno collegato a un server che espone tool, risorse e prompt.
Un host, più client, un server per client. Il tratteggio separa ciò che gira in locale da ciò che attraversa la rete. Illustrazione Adripedia.

Quando usarlo (e quando no)

MCP non è sempre la risposta. È un’infrastruttura, e come tutte le infrastrutture ha un costo di adozione. La domanda giusta è chi deve usare la stessa capacità e con quale grado di riuso.

Approccio Quando usarlo Limite
MCP Più host devono usare la stessa capacità, o serve un confine standard e riutilizzabile. Costo di implementazione e di sicurezza.
Function calling diretto Una sola applicazione, pochi tool, nessun riuso previsto. Ogni host reimplementa tutto.
CLI L’agente ha già accesso alla shell e i comandi sono già scritti. Permessi ampi, output non strutturato.
RAG Servono documenti in lettura, non azioni. Non esegue nulla e non sostituisce un’API.

MCP conviene quando la stessa capacità è utile a più strumenti o quando vuoi separare chi espone i dati da chi li consuma. Non conviene se stai costruendo una singola applicazione con tre funzioni: in quel caso il function calling diretto è più semplice e ha meno superficie d’attacco.

C’è un costo che spesso si sottovaluta: un server MCP va scritto, testato, distribuito, aggiornato e protetto. Se lo usano due persone, quel costo difficilmente si recupera. Se lo usano duecento, o se lo usano tre strumenti diversi, il calcolo cambia. La domanda non è “è moderno?”, ma “chi lo mantiene per i prossimi due anni?”.

Un’avvertenza che vale sempre: MCP non sostituisce una buona API. Se l’API è lenta, incoerente o insicura, incapsularla in un server MCP non la migliora: aggiunge un livello. Il server è un adattatore, non una cura.

Costruire un server minimo

La SDK ufficiale Python nella versione 2.x espone la classe MCPServer. Questo server espone due tool e una resource su un catalogo di articoli. È volutamente piccolo: un tool, un lavoro.

import json
import logging
from mcp.server import MCPServer

logging.basicConfig(level=logging.INFO)
log = logging.getLogger("catalogo")

mcp = MCPServer("catalogo")

ARTICOLI = {
    "A-101": {"titolo": "Router e cascate", "testo": "..."},
    "A-102": {"titolo": "Valutare un modello", "testo": "..."},
}

@mcp.tool()
def cerca_articoli(testo: str, limite: int = 5) -> list[dict]:
    """Cerca articoli per parola chiave. Restituisce al massimo `limite` risultati."""
    testo = testo.lower().strip()
    trovati = [
        {"id": k, "titolo": v["titolo"]}
        for k, v in ARTICOLI.items()
        if testo in v["titolo"].lower()
    ]
    log.info("ricerca %r: %d risultati", testo, len(trovati))
    return trovati[:limite]

@mcp.tool()
def leggi_articolo(id: str) -> dict:
    """Legge un articolo per ID. Se l'ID non esiste, restituisce un errore strutturato."""
    articolo = ARTICOLI.get(id)
    if articolo is None:
        return {
            "errore": "articolo_non_trovato",
            "id": id,
            "suggerimento": "usa cerca_articoli per trovare un ID valido",
        }
    return {"id": id, **articolo}

@mcp.resource("catalogo://schema")
def schema_catalogo() -> str:
    """Schema del catalogo, in JSON."""
    return json.dumps({
        "campi": ["id", "titolo", "testo"],
        "esempio_id": "A-101",
    })

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

Tre dettagli non sono decorativi. I docstring diventano la descrizione che il modello legge per scegliere il tool: vanno scritti come istruzioni, non come note per sviluppatori. I type hint diventano lo schema dei parametri. E i log vanno su stderr: su stdio, stdout è il canale del protocollo, e una riga di log scritta lì rompe la comunicazione.

Il server è piccolo abbastanza da essere letto in cinque minuti, ma mostra tutti i punti che contano: due tool con docstring e type hint, una resource con URI, un errore strutturato, i log su stderr. Se lo esegui in locale, la prima cosa da verificare è che l’avvio non scriva nulla su stdout. La seconda è che cerca_articoli con una parola inesistente restituisca una lista vuota, non un errore: una ricerca senza risultati è un risultato valido.

La configurazione lato client è un oggetto con comando, argomenti e variabili d’ambiente. I nomi dei campi variano tra client, ma la sostanza è questa:

{
  "mcpServers": {
    "catalogo": {
      "command": "python",
      "args": ["catalogo.py"],
      "env": {
        "CATALOGO_DB": "dati/catalogo.json"
      }
    }
  }
}

Un errore strutturato è più utile di un’eccezione generica, perché il modello può leggerlo e correggere la chiamata. Ma non deve contenere dettagli interni, stack trace o credenziali: è contenuto che finisce nel contesto.

Progettare i tool

La descrizione di un tool è parte del prompt. Se è vaga, il modello sceglie il tool sbagliato o inventa parametri. La regola è semplice: un tool, un lavoro.

Tool Cosa fare Cosa evitare
Nome Verbo e oggetto: cerca_articoli. Nomi generici come gestisci.
Descrizione Dire cosa fa, quando usarlo e cosa restituisce. Ripetere il nome o lasciare il docstring vuoto.
Schema Tipi espliciti, valori ammessi, campi obbligatori. Stringhe libere dove serve un enum.
Output Limitato, paginato, con un campo per il totale. Restituire migliaia di righe in una volta.
Scritture Idempotenti, con una chiave di richiesta. Creare duplicati a ogni retry.
Errori Codice, messaggio, suggerimento. Stack trace o dettagli interni.
Azioni distruttive Richiedono approvazione umana. Eliminare o inviare senza conferma.

Paginare non è un dettaglio da fare dopo. Un tool che restituisce tutto il catalogo occupa il contesto, costa token e nasconde l’informazione utile. Restituisci i primi N risultati, un identificatore per continuare e il totale. Il modello può sempre chiedere la pagina successiva.

Prendi una descrizione reale e peggiorala, per vedere l’effetto. “Cerca articoli” non dice se la ricerca è per titolo, per testo, per autore, né cosa restituisce. “Cerca articoli per parola chiave nel titolo; restituisce id e titolo, al massimo cinque, ordinati per rilevanza” dice tutto ciò che serve al modello per decidere. La differenza tra le due frasi è la differenza tra un tool usato bene e un tool usato a caso.

La stessa logica vale per i nomi dei parametri. id, limite, formato sono chiari; param1, opzioni, dati no. Se il modello deve indovinare, hai già perso.

Sicurezza

Due attacchi ricorrenti hanno un nome. Il confused deputy è un server che ha più permessi di chi lo chiama e li usa per conto di un altro: l’utente chiede una cosa innocua, il server la esegue con i propri privilegi e ne combina una più grande. Il token passthrough è un server che inoltra il token ricevuto a un servizio a valle senza verificarlo: il token finisce dove non doveva.

Rischio Mitigazione
Confused deputy Permessi per chiamante, non per server; consenso esplicito; scope minimi.
Token passthrough Non inoltrare token; usare credenziali proprie con audience corretta.
Accesso non autorizzato OAuth 2.0, verifica dell’audience, scadenza breve.
Injection via output Trattare l’output come non fidato; separarlo dalle istruzioni.
Tool troppo potenti Un tool, un’azione; niente shell generica se basta una query.
Dati in eccesso Filtrare, paginare, non restituire segreti.
Abuso e picchi Rate limit, quote, timeout, audit log.

La differenza tra server locale e remoto è sostanziale. Un server stdio gira con i permessi del processo che lo avvia: se quel processo può leggere un file, anche il server può. Un server HTTP remoto è raggiungibile da altri: senza autenticazione, chiunque può chiamarlo. Non è una differenza di configurazione, è una differenza di modello di fiducia.

Per un server remoto, OAuth 2.0 è il punto di partenza, non un dettaglio da aggiungere dopo. L’utente autorizza il client, il client ottiene un token con un’audience precisa, il server verifica il token e i suoi scope a ogni chiamata. Il consenso deve dire cosa l’utente sta autorizzando, non “accedi”. E il token non va mai inoltrato a un servizio a valle come se fosse una credenziale generica.

Attenzione. Confused deputy e token passthrough non si risolvono con una frase nel prompt. Servono controlli nel server: autorizzazione per chiamante, scope limitati, nessun inoltro di token, approvazione umana per le azioni distruttive. Il modello non è un confine di sicurezza.

Un’ultima regola: l’output di un tool è contenuto non fidato. Se un tool legge una pagina web, quella pagina può contenere istruzioni. Trattala come dati, non come comandi. Le difese lato prompt aiutano, ma il controllo vero sta nel server e nei permessi.

Testare e debuggare

MCP Inspector è lo strumento di riferimento per guardare un server dall’esterno: elenca tool, risorse e prompt, permette di chiamarli e mostra il traffico. Serve anche a verificare la compatibilità tra generazioni del protocollo:

mcp-inspector --protocol-era modern
mcp-inspector --protocol-era legacy

I due comandi aprono lo stesso server con due aspettative diverse. Se funziona solo con uno, hai un problema di compatibilità da dichiarare, non da nascondere.

Oltre all’Inspector, servono test veri:

Quando un client rifiuta una chiamata, la domanda è sempre la stessa: il server non risponde, risponde con un errore, o risponde con qualcosa che il client non capisce? L’Inspector separa i tre casi. Senza di lui si finisce a modificare il codice a caso, che è il modo più costoso di fare debugging.

Il caso “tool che restituisce troppo” è quello che sfugge più spesso. Un test che misura i byte o i token dell’output lo intercetta prima che il problema arrivi in produzione.

Distribuire

La scelta del trasporto decide il modello operativo. stdio è la scelta giusta per uno strumento locale: semplice, veloce, nessuna rete. Streamable HTTP è la scelta giusta per un servizio condiviso: serve autenticazione, deployment, osservabilità.

Una checklist di rilascio, in ordine di importanza:

  1. autenticazione e autorizzazione verificate, con scope minimi;
  2. nessun segreto nei log, negli errori o nelle risposte;
  3. rate limit e timeout configurati;
  4. output paginato e limitato per dimensione;
  5. versionamento del server e delle sue primitive;
  6. compatibilità dichiarata con le revisioni supportate;
  7. log e metriche per chiamata, senza dati personali;
  8. procedura di revoca e rotazione delle credenziali.

La checklist non è un documento da firmare una volta. Va riletta a ogni modifica che tocchi permessi, trasporto o forma dell’output, perché sono le tre cose che cambiano il rischio senza cambiare il codice applicativo. Se un rilascio non tocca nessuna delle tre, può bastare un controllo più leggero; se le tocca tutte, serve una revisione vera.

L’osservabilità non è un lusso: senza sapere quali tool vengono chiamati, con quale esito e in quanto tempo, non puoi né difendere né migliorare il server. Registra l’identificativo della richiesta, il tool, la durata e l’esito; non registrare il contenuto se non serve.

Un server remoto ha anche un problema di versione del deployment: se aggiorni il codice ma non la documentazione delle capacità, i client continuano a chiamare tool che non esistono. Dichiara la versione del server in una resource o in una risposta di scoperta, e cambiala quando cambia il contratto. Un numero di versione visibile vale più di un changelog che nessuno legge.

Infine, ricorda che un server MCP è un’interfaccia pubblica anche quando è interno. Cambiare il nome di un tool o il tipo di un parametro rompe i client. Tratta il contratto come tale.

Lessico minimo

Host
L’applicazione che l’utente usa e che ospita uno o più client MCP.
Client
Il componente dell’host che mantiene la connessione con un singolo server.
Server
Il processo o servizio che espone tool, risorse e prompt.
Tool
Una funzione che il modello può decidere di chiamare.
Resource
Un dato identificato da un URI, che l’applicazione può leggere.
Confused deputy
Un server con più permessi di chi lo chiama, che li usa per conto di un altro.

Fonti

Fonti consultate l’11 novembre 2026. La specifica evolve: verifica la revisione supportata dal client che usi.