Introduzione: perchè il Model Context Protocol
Il Model Context Protocol (MCP) e uno standard aperto sviluppato da Anthropic che definisce come le applicazioni AI comunicano con strumenti esterni. MCP risolve un problema fondamentale: dare ai modelli linguistici la capacità di agire nel mondo reale, non solo di generare testo.
Prima di MCP, ogni integrazione tra un'AI e un tool esterno richiedeva un'implementazione custom, con protocolli proprietari e integrazioni fragili. MCP standardizza questa comunicazione, creando un ecosistema dove qualsiasi tool può essere reso accessibile a qualsiasi AI compatibile, esattamente come USB-C ha unificato i connettori hardware.
In questa serie di 14 articoli, esploreremo MCP dalle fondamenta fino all'implementazione avanzata, analizzando nel dettaglio il progetto open source Tech-MCP, un monorepo TypeScript con 31 server MCP, 85+ tools e 6 pacchetti condivisi.
Cosa Imparerai in Questa Serie
- I fondamenti del protocollo MCP e la sua architettura Host/Client/Server
- Le tre primitive: Tools, Resources e Prompts con validazione Zod
- Come creare server e client MCP in TypeScript da zero
- Pattern architetturali: monorepo, EventBus, pacchetti condivisi
- 31 server MCP reali per produttività, DevOps, database, project management
- Collaborazione inter-server con eventi tipizzati e invocazione cross-server
- Testing, best practice e deploy in produzione
Il Problema che MCP Risolve
I Large Language Model (LLM) sono potenti nel ragionamento e nella generazione di testo, ma presentano limitazioni fondamentali che ne restringono l'utilita pratica:
- Non possono accedere a dati in tempo reale: il training ha una data di cutoff, quindi l'AI non conosce eventi recenti o dati aggiornati
- Non possono eseguire azioni: creare file, chiamare API, interagire con database, gestire deploy sono operazioni impossibili senza integrazioni esterne
- Non hanno contesto locale: l'AI non conosce il tuo progetto, i tuoi task, la struttura del tuo codebase o il tuo ambiente di sviluppo
MCP colma questo gap fornendo un protocollo di comunicazione bidirezionale tra l'AI e il mondo esterno, permettendo ai modelli linguistici di diventare veri assistenti operativi.
Il Problema N x M delle Integrazioni
Senza uno standard, connettere N applicazioni AI a M strumenti esterni richiede N x M integrazioni custom. Ogni combinazione ha il suo protocollo, la sua autenticazione, il suo formato dati. Questo approccio non scala.
MCP riduce la complessità a N + M: ogni applicazione AI implementa un client MCP, ogni tool implementa un server MCP, e tutti comunicano attraverso lo stesso protocollo standard.
Analogia: MCP come USB-C per l'AI
Prima di USB-C, ogni dispositivo aveva il suo connettore proprietario. Oggi USB-C unifica tutto: ricarica, dati, video. MCP fa lo stesso per l'AI: un unico protocollo standard che collega qualsiasi modello linguistico a qualsiasi strumento esterno, eliminando le integrazioni custom.
Architettura MCP: Host, Client e Server
L'architettura MCP si basa su tre componenti fondamentali che collaborano per abilitare l'interazione tra AI e strumenti esterni:
1. Host
L'Host e l'applicazione AI che l'utente utilizza direttamente. Gestisce la sessione utente, connette i server MCP e orchestra le chiamate ai tool. Esempi di Host includono:
- Claude Desktop: l'applicazione desktop di Anthropic
- Cursor IDE: l'IDE con AI integrata
- VS Code con estensioni MCP
- Applicazioni custom che usano l'SDK MCP
2. Client
Il Client e il componente software nell'Host che implementa il lato client del protocollo MCP. Mantiene una connessione 1:1 con un server MCP e gestisce:
- La negoziazione delle capacità durante l'inizializzazione
- Il routing dei messaggi JSON-RPC tra Host e Server
- La gestione del ciclo di vita della connessione
3. Server
Il Server e il componente che espone funzionalità all'AI. Un server MCP può offrire tre tipi di primitive:
Le Tre Primitive MCP
| Primitiva | Descrizione | Controllo | Esempio |
|---|---|---|---|
| Tools | Funzioni che l'AI può invocare | L'AI decide quando chiamarli | create-sprint, analyze-diff |
| Resources | Dati che l'applicazione può leggere | L'applicazione controlla l'accesso | File, database, API response |
| Prompts | Template predefiniti riutilizzabili | L'utente seleziona quale usare | "Analizza questo codice per bug" |
Transport: Come Comunicano Client e Server
Il Transport e il meccanismo fisico di comunicazione tra Client e Server. MCP supporta due modalità principali:
STDIO (Standard Input/Output)
Il transport più comune per server locali. Client e Server comunicano tramite stdin e
stdout del processo. Ogni messaggio e un oggetto JSON-RPC separato da newline.
Il canale stderr rimane disponibile per il logging.
- Pro: setup semplice, nessuna configurazione di rete, sicuro (locale)
- Contro: solo locale, un processo per connessione
HTTP + SSE (Streamable HTTP)
Per server remoti o quando servono connessioni multiple. Il client invia richieste HTTP POST, il server risponde via Server-Sent Events per lo streaming. Supporta session ID per mantenere lo stato tra le richieste.
- Pro: supporto remoto, connessioni multiple, scalabile
- Contro: più complesso da configurare, richiede un server HTTP
Come Funziona una Chiamata Tool
Per capire concretamente come MCP opera, seguiamo il flusso di una chiamata tool passo dopo passo:
Utente: "Crea uno sprint chiamato Sprint-15"
|
v
[1] L'AI ragiona e decide di chiamare il tool "create-sprint"
|
v
[2] Il Client MCP serializza la richiesta in JSON-RPC:
{ "method": "tools/call",
"params": { "name": "create-sprint",
"arguments": { "name": "Sprint-15" } } }
|
v
[3] Il Server MCP riceve, esegue la logica, ritorna il risultato:
{ "content": [{ "type": "text", "text": "Sprint creato con id 42" }] }
|
v
[4] L'AI riceve il risultato e lo presenta all'utente:
"Ho creato lo sprint Sprint-15 (ID: 42)"
Flusso Dettagliato del Protocollo
- Discovery: all'avvio, il Client chiede al Server l'elenco dei tool disponibili (
tools/list) - Schema: ogni tool dichiara i propri parametri con uno schema JSON/Zod validabile
- Invocazione: l'AI decide autonomamente quando e quale tool chiamare in base al contesto della conversazione
- Esecuzione: il Server esegue la logica di business e ritorna il risultato
- Composizione: l'AI può combinare più chiamate tool per completare task complessi
MCP vs REST API vs Plugin AI
MCP non e l'unico modo per integrare strumenti con l'AI, ma offre vantaggi significativi rispetto alle alternative tradizionali:
Confronto tra Approcci di Integrazione
| Caratteristica | REST API | Plugin AI | MCP |
|---|---|---|---|
| Standardizzato | Si (HTTP) | No (vendor-specific) | Si (protocollo aperto) |
| Discovery automatico | No | Parziale | Si |
| Tipizzazione parametri | OpenAPI | Varia | Zod / JSON Schema |
| Bidirezionale | No | No | Si |
| Streaming nativo | No | Varia | Si (SSE) |
| Vendor lock-in | No | Si | No |
| Composabilità | Manuale | Limitata | Nativa |
perchè MCP e Importante per gli Sviluppatori
MCP rappresenta un cambio di paradigma nell'interazione tra sviluppatori e AI. Ecco i vantaggi principali che lo rendono fondamentale:
- Interoperabilità: un server MCP funziona con Claude Desktop, Cursor, VS Code e qualsiasi altro client compatibile senza modifiche. Scrivi una volta, funziona ovunque.
-
Composabilità: l'AI può combinare tool di server diversi in un unico flusso di lavoro.
Ad esempio: analizza il codice (
code-review), genera i test (test-generator), e logga il tempo (time-tracking) - tutto in una singola conversazione. - Sicurezza: il protocollo definisce chiaramente cosa un server può fare. L'utente mantiene sempre il controllo sull'approvazione delle azioni sensibili.
- Ecosistema aperto: chiunque può creare un server MCP. Non serve il permesso di nessun vendor, non ci sono marketplace da cui dipendere.
- Contesto persistente: a differenza delle API stateless, MCP supporta sessioni con stato, permettendo al server di mantenere contesto tra le chiamate successive.
Il Progetto Tech-MCP: Una Suite Completa
Per dimostrare la potenza e la flessibilità di MCP, ho sviluppato Tech-MCP, un progetto open source che implementa 31 server MCP organizzati in un monorepo TypeScript. Questi server coprono l'intero ciclo di vita dello sviluppo software:
Tech-MCP in Numeri
| Metrica | Valore |
|---|---|
| Server MCP | 31 |
| Tools disponibili | 85+ |
| Pacchetti condivisi | 6 |
| Eventi tipizzati | 29 |
| Linguaggio | TypeScript 5.7 |
| Runtime | Node.js 20+ |
| Build system | Turborepo + pnpm |
Categorie di Server
I 31 server sono organizzati in categorie funzionali che coprono ogni aspetto dello sviluppo:
- Produttività (3): code-review, dependency-manager, project-scaffolding
- DevOps (3): docker-compose, log-analyzer, cicd-monitor
- Database (2): db-schema-explorer, data-mock-generator
- Documentazione (2): api-documentation, codebase-knowledge
- Testing (2): test-generator, performance-profiler
- Utility (3): regex-builder, http-client, snippet-manager
- Project Management (5): scrum-board, agile-metrics, time-tracking, project-economics, retrospective-manager
- Comunicazione (2): standup-notes, environment-manager
- Avanzati (9): incident-manager, decision-log, access-policy, quality-gate, workflow-orchestrator, insight-engine, mcp-registry, dashboard-api
Setup dell'Ambiente di Sviluppo
Per seguire questa serie e iniziare a sviluppare server MCP, assicurati di avere installato:
Prerequisiti
- Node.js 20+: runtime JavaScript/TypeScript (
node --version) - pnpm 9+: package manager per monorepo (
npm install -g pnpm) - TypeScript 5.7+: linguaggio tipizzato (
npx tsc --version) - Claude Desktop: per testare i server MCP (download da
claude.ai) - Git: per clonare il repository Tech-MCP
Clonare e Avviare Tech-MCP
Per esplorare il progetto completo, clona il repository e installa le dipendenze:
# Clona il repository
git clone https://github.com/fedcal/Tech-MCP.git
cd Tech-MCP
# Installa le dipendenze con pnpm
pnpm install
# Compila tutti i pacchetti e server
pnpm build
# Verifica che tutto funzioni
pnpm test
Configurare Claude Desktop
Per testare un server MCP con Claude Desktop, modifica il file di configurazione:
// macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
// Windows: %APPDATA%\Claude\claude_desktop_config.json
// Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"scrum-board": {
"command": "node",
"args": ["path/to/Tech-MCP/servers/scrum-board/dist/index.js"],
"env": {}
}
}
}
Struttura della Serie
Questa serie di 14 articoli segue un percorso progressivo, dalle fondamenta teoriche fino all'implementazione avanzata:
Roadmap degli Articoli
| # | Argomento | Livello |
|---|---|---|
| 01 | Introduzione al Model Context Protocol | Beginner |
| 02 | Primitive MCP: Tools, Resources e Prompts | Beginner |
| 03 | Architettura Monorepo e Pattern di Progetto | Intermediate |
| 04 | Creare il Primo Server MCP in TypeScript | Intermediate |
| 05 | Creare un Client MCP e Transport HTTP | Intermediate |
| 06 | Pacchetti Condivisi: Core, EventBus e Database | Intermediate |
| 07-11 | Server per Categoria (Produttività, DevOps, DB, PM, Avanzati) | Intermediate/Advanced |
| 12 | Collaborazione Inter-Server e EventBus | Advanced |
| 13 | Testing, Best Practice e Produzione | Advanced |
| 14 | Tech-MCP: Panoramica Completa del Progetto Open Source | Advanced |
Conclusioni
Il Model Context Protocol rappresenta un salto qualitativo nell'integrazione tra AI e strumenti di sviluppo. Non si tratta di un semplice wrapper attorno a chiamate API, ma di un protocollo strutturato che abilita discovery automatico, tipizzazione forte, comunicazione bidirezionale e composabilità nativa.
Nel prossimo articolo approfondiremo le tre primitive MCP (Tools, Resources e Prompts), analizzando nel dettaglio come definirle, validarle con Zod e gestirne il ciclo di vita. Inizieremo a scrivere codice, esplorando la struttura di un tool handler e il formato delle risposte.
Il codice completo di tutti gli esempi e disponibile nel repository Tech-MCP su GitHub.