Strumenti, Risorse e Prompt in MCP
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 · Deploy e scalabilità.
Tre capacità, tre intenti
Un server MCP può esporre tre tipi di capacità ai suoi client. Non sono intercambiabili: ciascuna risponde a un bisogno distinto e confonderle porta a server difficili da usare per il modello. Questa lezione le esamina una per una, prima di affrontare la domanda che determina la qualità del server: quanti strumenti e con quale granularità.
Strumenti: funzioni eseguibili
Gli Strumenti sono la capacità più utilizzata del protocollo. Uno strumento è una funzione che il modello può decidere di chiamare per eseguire un’azione o recuperare informazioni. La sua definizione si basa su quattro elementi: un nome unico e descrittivo (create_issue, get_weather), una descrizione testuale che indica al modello quando chiamarlo, uno schema JSON per i parametri di input con i relativi tipi e vincoli, e un formato di ritorno, spesso testo o JSON.
from mcp.server.mcpserver import MCPServer
app = MCPServer("My Server")
@app.tool()
def get_weather(latitude: float, longitude: float) -> str:
"""Recupera le condizioni meteorologiche attuali per le coordinate fornite.
Args:
latitude: Latitudine in gradi decimali (-90 a 90)
longitude: Longitudine in gradi decimali (-180 a 180)
Returns:
Descrizione testuale delle condizioni meteorologiche attuali
"""
# Logica di chiamata alle API meteo
return f"Soleggiato, 22°C a ({latitude}, {longitude})"
Non sottovalutare la descrizione e la tipizzazione: il modello non vede nient’altro. Non ha accesso al tuo codice, non può intuire le tue intenzioni e non può testare una chiamata per vedere cosa succede. Descrizioni vaghe o parametri mal tipizzati producono meccanicamente chiamate errate.
Alcune abitudini rendono i tuoi strumenti significativamente più affidabili. Nominali in base a ciò che fanno: book_restaurant dice tutto, process_request non dice nulla. Descrivi sia l’azione sia il contenuto restituito, poiché il modello deve anticipare cosa recupererà. Annota sempre i parametri in Python e scrivi docstring strutturate con Args e Returns: questi alimentano lo schema che il modello vede. Infine, restituisci valori leggibili piuttosto che identificatori opachi; uno strumento che restituisce "John Smith" permette al modello di comporre una frase, mentre uno che restituisce un UUID lo costringe a indovinare.
Risorse: dati leggibili
Le Risorse espongono dati che il client può leggere senza effetti collaterali. La sfumatura rispetto agli strumenti si riduce a un verbo: uno strumento fa qualcosa, una risorsa contiene qualcosa. Il contenuto di un file di configurazione, una base di conoscenza, la documentazione delle API o lo stato attuale di un sistema sono tutte risorse naturali.
@app.resource("config://database")
def get_db_config() -> str:
"""Configurazione attuale del database."""
return json.dumps({
"host": "localhost",
"port": 5432,
"database": "production"
})
Ogni risorsa è identificata da un URI — config://database, file:///path/to/doc — che il client può elencare e poi leggere su richiesta. In pratica, sono usate meno spesso degli strumenti, poiché un semplice strumento che restituisce dati copre la maggior parte delle esigenze. Rimangono utili quando vuoi pubblicare dati statici o semi-statici senza logica di esecuzione sottostante.
Prompt: modelli riutilizzabili
I Prompt MCP sono modelli parametrizzabili che il server mette a disposizione. Servono a condividere istruzioni collaudate per un dato compito, invece di lasciare che ognuno reinventi la propria formulazione.
@app.prompt()
def code_review(language: str, code: str) -> str:
"""Genera un prompt per la revisione del codice per il linguaggio specificato."""
return f"""Sei un esperto in {language}.
Analizza il seguente codice e identifica:
1. Potenziali bug
2. Problemi di prestazioni
3. Miglioramenti della leggibilità
Codice da analizzare:
```{language}
{code}
```"""
Questo utilizzo ha massimo senso in un contesto di team. Uno sviluppatore senior codifica i propri prompt per code review, debug o analisi architetturale in un server MCP, e l’intero team vi accede dal proprio client con la stessa qualità di istruzioni.
Negoziazione delle capacità
Quando un client si connette a un server, una fase di negoziazione precede qualsiasi utilizzo:
- Il client richiede le capacità del server
- Il server risponde con il suo elenco di strumenti, risorse e prompt
- Il client presenta queste capacità al modello linguistico
- Il modello usa le descrizioni per decidere cosa chiamare
Questa negoziazione è dinamica, ed è una proprietà sfruttabile: lo stesso server può annunciare capacità diverse a seconda dell’utente connesso o del contesto di chiamata: un account amministratore vede strumenti che un account in sola lettura non vedrà mai.
Quanti strumenti per server?
La domanda sembra banale, eppure condiziona il tasso di errore del tuo agente. Mantieni i tuoi server focalizzati: da tre a dieci strumenti ben definiti funzionano meglio di cinquanta generici. Oltre un certo volume, il modello disperde le sue scelte e finisce per chiamare lo strumento sbagliato o accumulare chiamate non necessarie.
Se il tuo ambito funzionale è ampio, suddividilo in diversi server specializzati: uno per le operazioni Git, uno per la gestione progetti, uno per il monitoraggio. Il client sa connettersi a più server simultaneamente e attivare solo quelli richiesti dal compito corrente, il che equivale a caricare il contesto utile piuttosto che l’intero catalogo.
Un ultimo compromesso merita la tua attenzione: la granularità. Esporre tre strumenti per elencare i ristoranti, verificare la disponibilità e poi prenotare costringe il modello a orchestrare una sequenza, con un rischio di errore a ogni passo. Un singolo strumento di flusso di lavoro — book_restaurant — incapsula l’intera sequenza, riduce il numero di round trip e sposta la logica di business dove è testabile: nel tuo codice.
Punti chiave
- Strumenti = azioni eseguibili (90% dei casi d’uso), richiedono descrizione e tipizzazione precise
- Risorse = dati leggibili tramite URI, nessun effetto collaterale
- Prompt = modelli riutilizzabili, utili per i team
- Mantieni i tuoi server focalizzati (massimo 3–10 strumenti)
- Preferisci strumenti di flusso di lavoro rispetto a strumenti eccessivamente granulari
- La qualità della descrizione determina l’efficienza del modello