MCP Server Python: agente AI in 12 passi in 75 minuti (2026)

Introduzione al nuovo Model Context Protocol

Il 28 luglio 2026 il Model Context Protocol (MCP) ha subito una revisione strutturale che ha eliminato l’handshake initialize e le sessioni, rendendo ogni server MCP un semplice servizio HTTP stateless, capace di operare dietro un load‑balancer tradizionale. Chi ha seguito i tutorial del 2025 troverà ancora esempi basati su un modello stateful, ormai deprecato.

Questa trasformazione è cruciale per gli sviluppatori che desiderano costruire agenti AI modulari: il protocollo rimane il modo standard per dichiarare strumenti (tool), risorse (resource) e prompt riutilizzabili, consentendo a qualunque applicazione compatibile – IDE, assistente da terminale o script Python – di accedervi in modo uniforme.

Contesto di mercato

Secondo la Developer Survey 2025 di Stack Overflow, il 31 % degli sviluppatori utilizza già agenti AI, mentre un ulteriore 17 % prevede di adottarli. Tuttavia, la potenza di un agente dipende dalla qualità e dalla sicurezza degli strumenti che può invocare; MCP fornisce il “linguaggio comune” per descriverli una sola volta.

Il progetto Notedesk

Notedesk è un esempio pratico: un server MCP che espone una cartella di note in Markdown (elenco, ricerca, lettura, salvataggio) e un agente che interagisce con il server usando un modello LLM locale con supporto al tool‑calling. Qualsiasi modello locale – ad esempio Qwen 3.8‑27B su Ollama – è idoneo, purché sia già scaricato.

Il vantaggio principale è la completa privacy: nessun dato lascia la macchina, un requisito fondamentale per chi gestisce informazioni personali o soggette a GDPR. L’intera configurazione richiede circa 75 minuti, un terminale e una connessione per scaricare le dipendenze.

Che cos’è un MCP server?

Un MCP server dichiara le proprie capacità in modo standardizzato. Il protocollo distingue tre attori:

• Host: l’applicazione con cui l’utente interagisce (es. assistente di programmazione).
• Client: vive dentro l’host e comunica con il server tramite MCP.
• Server: implementato dallo sviluppatore, fornisce tool, risorse e prompt, ma non dialoga direttamente con il modello.

L’SDK Python include la classe Client, che verrà usata sia dall’agente sia dai test.

Tipi di primitive MCP

Primitiva	Chi la controlla	Cos’è	Esempio in Notedesk
Tool	Modello	Funzione chiamata dal modello per agire	cercanote, salvanota
Resource	Applicazione	Dati caricati nel contesto del modello	nota://checklist-sicurezza
Prompt	Utente	Messaggio richiamabile per nome	riassumi

Una resource equivale a una GET HTTP (solo lettura), un tool a una POST (può avere effetti collaterali), mentre il prompt non ha un diretto equivalente HTTP ed è più simile a una query salvata.

Novità della revisione 2026‑07‑28

Le modifiche più impattanti sono:

• Protocollo stateless per default.
• Framework di estensioni formale: MCP Apps per interfacce renderizzate dal server e Tasks per lavori lunghi.
• Autorizzazione rafforzata, allineata a OAuth e OpenID Connect.

Le principali differenze operative sono sintetizzate nella tabella seguente:

Prima (pre‑2026‑07‑28)	Dopo (post‑2026‑07‑28)
Handshake initialize e sessioni	Nessun handshake, nessuna sessione
Negoziazione iniziale	Scoperta tramite server/discover
Richieste avviate dal client	Richieste avviate dal server
Multi Round‑Trip Requests (MRTR)	Notifiche di cambiamento unificate sotto subscriptions/listen
Tasks non standard	Tasks diventa un’estensione core

Con queste modifiche il codice del server non deve più gestire sessioni, consentendo il deployment dietro bilanciatori round‑robin senza “sticky sessions”. Inoltre, la maggior parte dei tutorial online che mostrano initialize o SSE descrive il vecchio modello.

Governance e adozione

Anthropic ha donato MCP alla Agentic AI Foundation, un fondo sotto la Linux Foundation, garantendo indipendenza da un singolo vendor. Gli SDK Python e TypeScript superano i 97 milioni di download mensili. La prossima revisione maggiore è prevista per marzo 2027, perciò gli esempi di questa guida resteranno validi per diversi mesi.

Struttura del progetto Notedesk

Notedesk è diviso in due componenti indipendenti che comunicano esclusivamente via MCP:

• server.py: gestisce le note (tool, resource, prompt).
• agent.py: carica il modello locale e orchestra le chiamate ai tool.

Questa separazione permette di sostituire il modello senza modificare il server, o di collegare lo stesso server a host diversi.

File generati

File	Ruolo	Passi
pyproject.toml	Dipendenze e versione Python	1
dati/*.md	Tre note di esempio	2
server.py	MCP server con 4 tool, 1 resource, 1 prompt	3,5,6,7
test_server.py	Cinque test in memoria con pytest	8
client_prova.py	Client stdio per ispezionare il server	9
agent.py	Agente con modello locale e ciclo di tool	10,11

Prerequisiti tecnici

Prima di iniziare, verifica di avere:

• Python 3.15.1 (minimo 3.11, 3.14.9 e 3.13.17 sono accettabili).
• SDK mcp serie 2.x, con extra cli per i comandi mcp dev e mcp run.
• Gestore ambienti uv (oppure venv + pip).
• Ollama installato e configurato, con endpoint localhost:11434/v1.
• Modello locale con supporto tool‑calling (es. Qwen 3.8‑27B). Verifica con ollama show NOME.
• Node.js LTS (solo per MCP Inspector).

Python 3.15.0 è stato rilasciato il 9 ottobre 2026; la 3.15.1 è disponibile dal 21 ottobre con patch di sicurezza. Aggiorna eventuali versioni obsolete (es. 3.10) perché lo SDK richiede almeno 3.11 e non riceve più aggiornamenti.

Requisiti hardware

Un modello di pochi miliardi di parametri gira tranquillamente su un portatile con RAM sufficiente (≥ 16 GB). Modelli più grandi dipendono dalla GPU o dalla memoria unificata; il codice rimane invariato, ma la velocità varia.

Sicurezza e mitigazione dei rischi

Un agente con tool è vulnerabile da tre angolazioni:

• Il modello può generare argomenti errati per imprecisione.
• Le note possono contenere istruzioni nascoste (prompt injection indiretta).
• Componenti di terze parti possono avere vulnerabilità.

Notedesk affronta ciascuna minaccia con:

• Validazione rigorosa degli input (tipo, lunghezza, pattern).
• Strumenti di scrittura limitati e confermati dall’utente.
• Superficie d’attacco ridotta al minimo indispensabile.

Il risultato è che, in caso di errore del modello, il danno massimo è la creazione di una nuova nota – mai la sovrascrittura di una esistente – nella cartella dati/.

Passi pratici: da zero al server funzionante

Passo 1 – Preparare l’ambiente con uv

Esegui i seguenti comandi:

uv init notedesk
cd notedesk
rm -f main.py
uv add "mcp[cli]" openai
uv add --dev pytest
uv run python --version

Assicurati che la versione di Python stampata sia ≥ 3.11. Se uv ha selezionato un interprete più vecchio, specifica la versione desiderata in pyproject.toml con requires-python e rilancia uv sync.

Passo 2 – Creare le note di esempio

Crea la cartella dati/ e inserisci tre file Markdown, ad esempio:

dati/meeting.md
dati/checklist-sicurezza.md
dati/ideas.md

Passo 3 – Implementare il server MCP

Nel file server.py definisci:

• Quattro tool: cercanote, salvanota, elencanote, rimuovinota.
• Una resource: nota://checklist-sicurezza.
• Un prompt: riassumi.

Utilizza la classe mcp.Server e registra le primitive con i decorator forniti dallo SDK.

Passo 4 – Testare il server

Scrivi test_server.py con cinque test pytest che verificano:

• Scoperta delle primitive via /discover.
• Risposta corretta dei tool di ricerca e salvataggio.
• Gestione delle risorse in modalità read‑only.
• Validazione degli argomenti (tipo e lunghezza).
• Comportamento delle subscription.

Passo 5 – Client di ispezione

Il file client_prova.py avvia un client stdio che permette di inviare richieste manuali al server, utile per il debug interattivo.

Passo 6 – Configurare Ollama

Installa Ollama, scarica il modello desiderato (es. ollama pull qwen3.8-27b) e verifica la presenza dei tool con ollama show qwen3.8-27b.

Passo 7 – Implementare l’agente

In agent.py:

• Inizializza il client MCP.
• Carica il modello locale tramite l’API OpenAI compatibile di Ollama.
• Definisci un ciclo di ragionamento: il modello invoca un tool, il client chiama il server, il risultato è restituito al modello.
• Gestisci le Tasks per operazioni lunghe (es. generazione di riassunti estesi).

Passo 8 – Eseguire un caso d’uso

Esempio pratico: chiedi all’agente di “riassumere le note sulla sicurezza”. L’agente:

• Chiama il tool cerca_note con la keyword “sicurezza”.
• Riceve la resource nota://checklist-sicurezza.
• Passa il contenuto al modello, che genera il riassunto.
• Restituisce il risultato all’utente.

Passo 9 – Deploy

Grazie al nuovo modello stateless, il server può essere containerizzato con Docker e scalato dietro un load‑balancer senza configurare sticky sessions. Un semplice docker build -t notedesk . seguito da docker run -p 8000:8000 notedesk è sufficiente.

Passo 10 – Manutenzione e aggiornamenti

Monitora le versioni dello SDK (uv list), aggiorna Ollama regolarmente e verifica la compatibilità dei modelli con le nuove capacità di tool‑calling introdotte dalla revisione 2026‑07‑28.

Conclusioni

Seguendo questi 12 passi, in meno di 75 minuti è possibile avere un MCP server Python completamente funzionante e un agente AI locale che sfrutta il nuovo protocollo stateless. La separazione netta tra server (strumenti) e agente (modello) garantisce flessibilità, scalabilità e, soprattutto, sicurezza dei dati, rendendo Notedesk un modello ideale per applicazioni aziendali sensibili o per progetti personali che richiedono il massimo controllo sulla privacy.