01 - Introduzione al Model Context Protocol (MCP)

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.

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.

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:

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

Streamable HTTP

Per server remoti o quando servono connessioni multiple. Il client invia richieste HTTP POST, il server risponde con un oggetto JSON oppure, per lo streaming, con uno stream Server-Sent Events limitato a quella richiesta. Fino alla revisione 2025-11-25 supportava anche i session ID; dalla 2026-07-28 le sessioni non esistono più (vedi il riquadro in cima). Non va confuso con il vecchio transport HTTP+SSE del 2024-11-05, deprecato.

• 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

1. Discovery: all'avvio, il Client chiede al Server l'elenco dei tool disponibili (tools/list)
2. Schema: ogni tool dichiara i propri parametri con uno schema JSON/Zod validabile
3. Invocazione: l'AI decide autonomamente quando e quale tool chiamare in base al contesto della conversazione
4. Esecuzione: il Server esegue la logica di business e ritorna il risultato
5. 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:

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:

1. Interoperabilità: un server MCP funziona con Claude Desktop, Cursor, VS Code e qualsiasi altro client compatibile senza modifiche. Scrivi una volta, funziona ovunque.
2. 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.
3. Sicurezza: il protocollo definisce chiaramente cosa un server può fare. L'utente mantiene sempre il controllo sull'approvazione delle azioni sensibili.
4. Ecosistema aperto: chiunque può creare un server MCP. Non serve il permesso di nessun vendor, non ci sono marketplace da cui dipendere.
5. 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:

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:

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:

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.