MCP: Deep Dive dell'architettura e del protocollo

Introduzione

Se state utilizzando Claude, ChatGPT, Cursor o qualsiasi altra AI moderna, è molto probabile che stiate già interagendo con il Model Context Protocol (MCP) senza rendervene conto. MCP è il protocollo che trasforma un Large Language Model da semplice chatbot a sistema realmente integrato con i vostri dati e strumenti.

Non si tratta di teoria astratta o di un concetto futuristico. MCP è già in produzione e permette alle AI di:

Leggere e scrivere file sul filesystem
Interrogare database relazionali e NoSQL
Chiamare API esterne
Accedere a knowledge base proprietarie
Eseguire operazioni complesse sui vostri sistemi

Questa guida vi accompagnerà attraverso l'architettura, il funzionamento e l'implementazione pratica di MCP, fornendo le conoscenze necessarie per integrare le AI moderne nel vostro stack tecnologico.

Il Problema: Integration Hell

La Frammentazione delle Integrazioni AI

Prima dell'introduzione di MCP, il panorama delle integrazioni AI era caratterizzato da una frammentazione estrema. Ogni provider aveva il proprio sistema proprietario:

Anthropic con le sue API specifiche per Claude
OpenAI con il proprio ecosistema per GPT
Google con le integrazioni proprietarie per Gemini

A prima vista, questo potrebbe sembrare semplicemente un problema di duplicazione del codice. Ma la realtà è molto più complessa e problematica.

I Tre Volti della Complessità

1. Adattatori Custom Hard-Coded

Senza uno standard comune, ogni integrazione richiede un adattatore scritto su misura. Questi adattatori non sono semplici wrapper: contengono logica di business complessa per:

Gestire il contesto: Come passare informazioni da una chiamata all'altra
Normalizzare i formati: Convertire tra schemi dati diversi
Gestire gli errori: Ogni API ha le sue convenzioni per gli errori
Controllare il rate limiting: Implementazioni diverse per ogni provider

Il risultato? Codice fragile, difficile da testare e quasi impossibile da mantenere.

2. Fragilità Sistemica

Ogni modifica al sistema diventa un potenziale punto di rottura:

Cambio ambiente (Test → Produzione):

- Endpoint diversi
- Credenziali diverse
- Configurazioni diverse
→ Pipeline di integrazione da riscrivere

Aggiornamento API del provider:

- Schema cambiato
- Nuovi campi obbligatori
- Deprecazione di endpoint
→ Metà della logica di integrazione obsoleta

Nuova fonte dati da integrare:

- Formato diverso
- Autenticazione diversa
- Semantica diversa
→ Nuovo adattatore custom da zero

3. Complessità Esponenziale

Il vero problema emerge quando si considera l'intera organizzazione:

Backend Engineers parlano in JSON strutturato e REST API
Data Scientists parlano in embedding, vettori e indici semantici
DevOps parlano in container, orchestrazione e deployment

Senza uno standard condiviso, questi team non condividono nemmeno un linguaggio comune per l'integrazione. Ogni team implementa le proprie integrazioni, duplicando sforzi e creando debito tecnico.

L'Analogia: Prima di USB-C

Per comprendere meglio il problema, pensate all'ecosistema di ricarica prima dello standard USB-C:

Apple aveva Lightning
MacBook aveva MagSafe
Android aveva Micro-USB
Altri dispositivi avevano mini-USB

Il risultato? Tre o quattro cavi diversi nella borsa, nessuna interoperabilità, e la continua frustrazione di non avere mai il cavo giusto al momento giusto.

MCP risolve lo stesso problema per le integrazioni AI: un solo protocollo standard per tutte le integrazioni.

La Soluzione: Model Context Protocol

Che Cos'è MCP?

Model Context Protocol (MCP) è uno standard aperto che definisce come i Large Language Model comunicano con sistemi esterni. È il layer di astrazione che si posiziona tra:

Le AI (Claude, GPT, altri LLM)
I vostri sistemi (database, filesystem, API, tool proprietari)

I Principi Fondamentali

MCP si basa su tre principi chiave:

1. Standardizzazione Completa

MCP non standardizza solo i messaggi o il formato dei dati. Standardizza l'intero modello di integrazione:

Come si stabilisce una connessione
Come si negoziano le capabilities
Come si scoprono i tools disponibili
Come si invocano le funzioni
Come si gestiscono gli errori

Questo significa che scrivendo un server MCP una volta sola, ottieni automaticamente compatibilità con tutti i client MCP.

2. Write Once, Run Everywhere

Un server MCP scritto per Claude Desktop funziona immediatamente con:

Cursor (IDE AI-powered)
Zed (editor di testo moderno)
Qualsiasi altro client compatibile MCP

Non servono modifiche. Non servono adattatori. Lo stesso codice, ovunque.

3. Nessun Vendor Lock-In

MCP è uno standard aperto. Non è proprietario di Anthropic, OpenAI o Google. È un protocollo aperto che chiunque può implementare.

Questo significa:

Libertà di cambiare provider AI senza riscrivere integrazioni
Possibilità di supportare multiple AI contemporaneamente
Controllo completo del vostro stack tecnologico

Il Risultato

Con MCP, state implementando uno standard, non integrando una singola AI. E questo cambia completamente il paradigma di integrazione.

Architettura MCP: I Tre Componenti

MCP definisce un'architettura chiara basata su tre componenti principali. Comprendere questa architettura è fondamentale per implementare integrazioni corrette e robuste.

1. Host

L'Host è l'applicazione che l'utente finale utilizza. È l'ambiente che contiene tutto:

Componenti dell'Host:

User Interface: L'interfaccia con cui l'utente interagisce
Model (LLM): Il Large Language Model che genera risposte
Client MCP: Il componente che implementa il protocollo MCP

Esempi di Host:

Claude Desktop
Cursor
IDE con supporto AI
Chat application custom

Ruolo: L'Host è il punto di orchestrazione. Gestisce l'interazione utente, coordina le chiamate al Model, e orchestra la comunicazione con i Server MCP tramite il Client.

2. Client

Il Client è il componente all'interno dell'Host che parla il protocollo MCP.

Responsabilità del Client:

Stabilire e mantenere connessioni con i Server MCP
Tradurre le decisioni del Model in messaggi MCP
Inviare richieste JSON-RPC ai Server
Ricevere e processare le risposte
Gestire errori e timeout

Importante: Il Client è un traduttore, non un decisore. Non contiene logica di business. Non decide quando invocare i tools. Traduce semplicemente le decisioni del Model in chiamate protocollari.

3. Server

Il Server è il componente che voi implementate. Questo è il vostro codice.

Responsabilità del Server:

Esporre Tools (funzioni eseguibili)
Esporre Resources (dati leggibili)
Esporre Prompts (template riutilizzabili)
Eseguire le operazioni richieste
Validare gli input
Gestire errori e edge cases

Il Server è dove vivono:

L'accesso ai vostri database
La logica di business
Le chiamate alle vostre API
L'indicizzazione delle vostre knowledge base

Il Model: Dov'è?

Punto fondamentale da comprendere: il Model non è parte del protocollo MCP.

Il Model (l'LLM) vive dentro l'Host. Non comunica direttamente con il Server. La comunicazione avviene sempre attraverso il Client.

Il flusso è sempre:

Model → Client → Server

Mai:

Model → Server (diretto)

Il Principio Chiave: Separazione delle Responsabilità

Model decide   → "Ho bisogno di cercare nella KB"
Client comunica → Traduce in tools/call JSON-RPC
Server esegue   → Esegue la ricerca e ritorna risultati

Questa separazione garantisce:

Sicurezza: Il Model non ha accesso diretto ai vostri sistemi
Testabilità: Ogni componente può essere testato indipendentemente
Manutenibilità: Modifiche a un componente non impattano gli altri

Modello di Comunicazione

Il modello di comunicazione primario in MCP è il request-response:

✅ Il pattern fondamentale: Request-Response

Client → richiesta → Server
Server → risposta → Client

Questo è il flusso che userete nel 99% dei casi: il Client chiede, il Server risponde. Semplice, prevedibile, debuggabile.

✅ Supportato anche: Notifications

Oltre al request-response, MCP supporta le notifications: messaggi unidirezionali che non richiedono risposta. Sia il Client che il Server possono inviare notifications.

Esempi pratici:

Il Server notifica che la lista dei tools è cambiata (notifications/tools/list_changed)
Il Server notifica che una resource è stata aggiornata (notifications/resources/updated)
Il Client notifica che i root paths sono cambiati (notifications/roots/list_changed)

Le notifications sono un meccanismo di segnalazione leggero: dicono "è successo qualcosa", ma non richiedono una risposta. Se il Client riceve una notifica di cambio tools, potrà poi fare una nuova tools/list per ottenere la lista aggiornata — sempre con il pattern request-response.

❌ Non Supportato:

Il Server non può invocare tools sul Client
Nessuno streaming bidirezionale arbitrario
Nessun callback asincrono complesso

Perché questo modello?

1. Sicurezza: Il Server non può "attaccare" il Client. Non può inondarlo di richieste. Non può tentare di prendere controllo. Può rispondere a richieste e inviare segnalazioni leggere, nulla di più.

2. Semplicità: Request-response con notifications è un modello semplice da implementare, debuggare e monitorare. Non ci sono:

Race condition complesse
Sincronizzazione bidirezionale
Code di messaggi da gestire

Il risultato è un protocollo prevedibile e affidabile, che bilancia flessibilità e sicurezza.

I Quattro Pilastri di MCP

MCP espone quattro primitive fondamentali che definiscono come il Client può interagire con il Server. Comprendere a fondo questi quattro elementi è essenziale per progettare server MCP efficaci.

1. Resources

Definizione: Le Resources sono dati esposti dal Server che il Model può leggere.

Caratteristiche:

Passive: Non eseguono codice
Read-only: Il Model può leggerle ma non modificarle
Context: Forniscono informazioni di contesto al Model

Esempi concreti:

docs://api-reference.md

Un file di documentazione API che il Server rende disponibile. Quando il Model ha bisogno di rispondere a domande sulle API, il Client può richiedere questa Resource.

db://config/production

Record di configurazione del database di produzione esposti come Resource.

logs://system/errors/2024-02-15

Log di sistema per una data specifica.

Caso d'uso tipico:

Immaginate di avere una knowledge base di documentazione tecnica interna. Il vostro Server MCP espone ogni documento come Resource:

Resource: kb://architecture/microservices-design
Contenuto: Documento di 5000 parole sulla vostra architettura

Quando un utente chiede "Come è strutturata la nostra architettura a microservizi?", il Model:

Identifica che serve il documento
Il Client richiede la Resource
Il Server legge il file dal filesystem
Ritorna il contenuto
Il Model lo usa per generare una risposta accurata

Punto chiave: Le Resources non eseguono mai codice. Sono dati puri.

2. Tools

Definizione: I Tools sono azioni eseguibili che il Server espone.

Caratteristiche:

Active: Eseguono codice sul Server
Parametrizzabili: Accettano input strutturati
Side effects: Possono modificare stato

Differenza fondamentale con Resources:

Resources → Lettura passiva di dati
Tools     → Esecuzione attiva di operazioni

Esempi concreti:

Tool: search_kb

{
  name: "search_kb",
  description: "Cerca documenti nella knowledge base usando ricerca semantica",
  inputSchema: {
    type: "object",
    properties: {
      query: {
        type: "string",
        description: "Query di ricerca in linguaggio naturale"
      },
      maxResults: {
        type: "number",
        description: "Numero massimo di risultati (default: 5)"
      }
    },
    required: ["query"]
  }
}

Implementazione sul Server:

async function search_kb(query, maxResults = 5) {
  // 1. Tokenizza la query
  const tokens = tokenize(query);

  // 2. Genera embedding
  const embedding = await generateEmbedding(tokens);

  // 3. Cerca nell'indice vettoriale
  const results = await vectorIndex.search(embedding, maxResults);

  // 4. Rankizza per rilevanza
  const ranked = rankByRelevance(results);

  return ranked;
}

Tool: create_file

{
  name: "create_file",
  description: "Crea un nuovo file nel workspace",
  inputSchema: {
    type: "object",
    properties: {
      path: { type: "string" },
      content: { type: "string" },
      overwrite: { type: "boolean", default: false }
    },
    required: ["path", "content"]
  }
}

Tool: query_database

{
  name: "query_database",
  description: "Esegue query SQL safe sul database di produzione",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string" },
      params: { type: "array" }
    },
    required: ["query"]
  }
}

Punto critico: La quality delle description è fondamentale.

Il Model vede SOLO:

Il nome del tool
La description
L'input schema

Non vede il vostro codice. Non vede l'implementazione. Basa le sue decisioni esclusivamente su queste informazioni.

Description migliori → Decisioni migliori del Model.

Esempio di description debole vs forte:

❌ Debole:

"Cerca documenti"

✅ Forte:

"Cerca documenti nella knowledge base usando ricerca semantica.
Supporta query in linguaggio naturale. Ritorna i documenti più
rilevanti con score di similarità. Usa questo tool quando l'utente
chiede informazioni presenti nella documentazione aziendale."

3. Prompts

Definizione: I Prompts sono template riutilizzabili che il Server espone per guidare il Model in task specifici.

Caratteristiche:

Template-based: Strutture di prompt predefinite con placeholders
Parametrizzabili: Accettano variabili che vengono sostituite a runtime
Reusable: Possono essere invocati ripetutamente con input diversi
Server-side: Vivono sul Server, non nel Client

Il problema che risolvono: Senza Prompts, ogni volta che un utente chiede "fammi una code review" o "analizza questi log", il Model deve costruire da zero le istruzioni su come strutturare l'analisi. Il risultato è inconsistente: a volte l'analisi è approfondita, a volte superficiale, e il formato cambia ogni volta.

Con i Prompts, voi codificate il vostro know-how in un template. Il Model lo usa come guida strutturata, producendo output consistenti e di qualità prevedibile.

Come funzionano nel protocollo: Il Client chiede al Server quali Prompts sono disponibili (prompts/list), poi può richiedere un Prompt specifico con i suoi argomenti (prompts/get). Il Server restituisce una sequenza di messaggi già strutturati che il Client passa al Model.

Esempio 1: Analyze Error Logs

{
  name: "analyze_error_logs",
  description: "Analisi strutturata di log di errore con identificazione pattern, root cause analysis e azioni raccomandate. Usa questo prompt quando l'utente fornisce log di errore e vuole un'analisi sistematica.",
  arguments: [
    {
      name: "logs",
      description: "I log di errore da analizzare (testo grezzo o path al file)",
      required: true
    },
    {
      name: "timeframe",
      description: "Intervallo temporale di riferimento (es: 'ultime 24 ore', 'settimana scorsa')",
      required: false
    },
    {
      name: "severity_focus",
      description: "Livello di severità su cui concentrarsi: 'all', 'critical_only', 'high_and_above'",
      required: false
    }
  ]
}

Template del Prompt:

Analizza i seguenti log di errore in modo sistematico:

LOG DATA:
{logs}

TIMEFRAME: {timeframe}
FOCUS: {severity_focus}

Esegui la seguente analisi:

1. PATTERN IDENTIFICATION
   - Identifica errori ricorrenti
   - Raggruppa errori simili per tipo e origine
   - Calcola frequenza per categoria

2. ROOT CAUSE ANALYSIS
   - Per ogni pattern identificato, proponi cause probabili
   - Ordina per impatto sul sistema

3. SEVERITY ASSESSMENT
   - Critical: errori che bloccano il sistema o causano perdita dati
   - High: errori che impattano utenti attivi
   - Medium: errori che degradano performance
   - Low: errori informativi o warning

4. RECOMMENDED ACTIONS
   - Azioni immediate per errori critical (con stima del tempo)
   - Fix suggeriti per errori high/medium
   - Miglioramenti preventivi per ridurre errori futuri

Formato output: JSON strutturato con sezioni separate per ogni punto

Perché è utile: Senza questo template, se chiedete a un LLM "analizza questi log" ottenete risposte di qualità variabile. Con il template, ottenete sempre le quattro sezioni, sempre la classificazione per severity, sempre le azioni raccomandate. È il vostro standard di qualità, codificato.

Esempio 2: Code Review

{
  name: "code_review",
  description: "Code review strutturata con focus su bug, performance, sicurezza e manutenibilità. Usa questo prompt quando l'utente chiede una revisione del codice.",
  arguments: [
    {
      name: "code",
      description: "Il codice sorgente da revisionare",
      required: true
    },
    {
      name: "language",
      description: "Linguaggio di programmazione (es: 'typescript', 'python', 'go')",
      required: true
    },
    {
      name: "context",
      description: "Contesto del codice: cosa fa, dove viene usato, requisiti specifici",
      required: false
    }
  ]
}

Template del Prompt:

Esegui una code review professionale del seguente codice:

LINGUAGGIO: {language}
CONTESTO: {context}

CODICE:
{code}

Analizza il codice secondo questi criteri:

1. CORRETTEZZA
   - Bug potenziali o logica errata
   - Edge case non gestiti
   - Errori di tipo o null safety

2. SICUREZZA
   - Input non validati
   - Injection vulnerabilities (SQL, XSS, command injection)
   - Gestione credenziali e dati sensibili
   - Permessi e autorizzazioni

3. PERFORMANCE
   - Operazioni O(n²) o peggio evitabili
   - Memory leak potenziali
   - Query N+1 o chiamate ridondanti
   - Opportunità di caching

4. MANUTENIBILITÀ
   - Naming e leggibilità
   - Complessità ciclomatica elevata
   - Duplicazione di codice
   - Aderenza ai principi SOLID

5. TESTING
   - Testabilità del codice
   - Test case suggeriti
   - Mock necessari

Per ogni issue trovata, specifica:
- Riga o sezione del codice
- Severità: 🔴 Critico | 🟡 Importante | 🔵 Suggerimento
- Codice corretto suggerito

Concludi con un punteggio complessivo da 1 a 10 e un summary delle priorità.

Esempio 3: API Documentation Generator

{
  name: "generate_api_docs",
  description: "Genera documentazione API completa da codice sorgente. Produce output in formato Markdown con endpoint, parametri, esempi di richiesta/risposta e codici di errore.",
  arguments: [
    {
      name: "code",
      description: "Il codice sorgente contenente le definizioni degli endpoint",
      required: true
    },
    {
      name: "api_name",
      description: "Nome dell'API per il titolo della documentazione",
      required: true
    },
    {
      name: "base_url",
      description: "URL base dell'API (es: 'https://api.example.com/v1')",
      required: false
    }
  ]
}

Template del Prompt:

Genera documentazione API completa dal seguente codice:

API: {api_name}
BASE URL: {base_url}

CODICE:
{code}

Per ogni endpoint trovato nel codice, genera:

1. ENDPOINT OVERVIEW
   - Metodo HTTP e path
   - Descrizione breve (una riga)
   - Autenticazione richiesta (sì/no, tipo)

2. PARAMETRI
   - Path parameters (con tipo e descrizione)
   - Query parameters (con tipo, default, obbligatorio/opzionale)
   - Request body (schema JSON con tipi e descrizioni)

3. RESPONSE
   - Status code di successo con esempio di response body
   - Status code di errore con significato

4. ESEMPIO COMPLETO
   - Richiesta curl funzionante
   - Response JSON di esempio

Formato output: Markdown con heading per ogni endpoint.
Usa tabelle per i parametri e code block per gli esempi.

Esempio 4: Test Case Generation

{
  name: "generate_test_cases",
  description: "Genera test case completi da requisiti funzionali o codice. Produce test case strutturati con precondizioni, step e risultati attesi.",
  arguments: [
    {
      name: "source",
      description: "Requisiti funzionali o codice sorgente da cui generare i test",
      required: true
    },
    {
      name: "type",
      description: "Tipo di test: 'unit', 'integration', 'e2e', 'all'",
      required: false
    },
    {
      name: "framework",
      description: "Framework di test (es: 'vitest', 'jest', 'pytest')",
      required: false
    }
  ]
}

Template del Prompt:

Genera test case dal seguente input:

TIPO: {type}
FRAMEWORK: {framework}

SOURCE:
{source}

Per ogni funzionalità identificata, genera:

1. HAPPY PATH
   - Test con input validi e flusso normale
   - Verifica di tutti gli output attesi

2. EDGE CASES
   - Input ai limiti (stringhe vuote, numeri 0, array vuoti)
   - Input al massimo consentito
   - Valori null/undefined

3. ERROR CASES
   - Input invalidi (tipo sbagliato, fuori range)
   - Errori di rete/timeout (per integration test)
   - Stato inconsistente

4. SECURITY CASES (se applicabile)
   - Input malicious (injection attempts)
   - Accesso non autorizzato
   - Rate limiting

Per ogni test case specifica:
- Nome descrittivo (it('should...'))
- Arrange: setup e precondizioni
- Act: azione da eseguire
- Assert: risultato atteso

Se specificato un framework, genera codice eseguibile.
Altrimenti, genera test case in formato tabellare.

Quando usare i Prompts e quando no

I Prompts sono potenti ma non sempre necessari. Ecco una guida pratica:

Usate i Prompts quando:

Avete task ripetitivi che richiedono output strutturato e consistente
Il vostro team ha standard di qualità specifici (format di code review, checklist di analisi)
Volete codificare domain expertise che altrimenti andrebbe perso
Più persone fanno lo stesso tipo di richiesta e volete risultati uniformi

Non servono Prompts quando:

Le richieste sono sempre diverse e non standardizzabili
Il Model produce già risposte di qualità sufficiente senza guida
State costruendo un server semplice con uno o due tools (in quel caso, concentratevi su tools e resources)

Per la nostra knowledge base: Nella serie di video ci concentreremo su Tools e Resources, che sono i pilastri più immediati per un server di knowledge base. Ma se in futuro volete aggiungere, ad esempio, un prompt per "analizza tutti i documenti della KB e trova inconsistenze", sapete come farlo.

4. Transport

Definizione: Il Transport è il livello più basso. Definisce come i messaggi MCP vengono trasmessi tra Client e Server.

Punto chiave: Il protocollo MCP è indipendente dal Transport.

MCP definisce cosa comunicare (initialize, tools/list, tools/call), ma non come trasmetterlo. Questo permette flessibilità nell'implementazione.

Transport: stdio

Uso: Comunicazione locale tra processi sullo stesso sistema.

Funzionamento:

Il Server legge da standard input
Il Server scrive su standard output
Il Client e Server comunicano via pipe

Vantaggi:

Semplice da implementare
Veloce (nessun overhead di rete)
Perfetto per integrazioni locali

Casi d'uso:

Claude Desktop
Cursor
IDE plugins
Tool da command line

Esempio di setup:

// Server in Node.js
const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");

const server = new Server({
  name: "my-mcp-server",
  version: "1.0.0"
});

const transport = new StdioServerTransport();
await server.connect(transport);

Warning critico per stdio: stdout è il canale del protocollo. Mai usare console.log() in un server MCP su stdio. Usa console.error() per logging.

Transport: HTTP con Server-Sent Events

Uso: Comunicazione remota per deployment cloud.

Funzionamento:

Server espone endpoint HTTP
Client si connette via HTTP
Server può scalare orizzontalmente
Supporta migliaia di client concorrenti

Vantaggi:

Deployment in cloud
Scalabilità orizzontale
Load balancing
Monitoring e logging centralizzati

Casi d'uso:

Server MCP in produzione
Servizi multi-tenant
Integrazioni enterprise
API pubbliche

Esempio di setup:

const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
const { SSEServerTransport } = require("@modelcontextprotocol/sdk/server/sse.js");
const express = require("express");

const app = express();
const server = new Server({
  name: "my-mcp-server",
  version: "1.0.0"
});

app.post("/mcp", async (req, res) => {
  const transport = new SSEServerTransport("/mcp", res);
  await server.connect(transport);
});

app.listen(3000);

Punto fondamentale: Cambiare Transport non richiede modifiche al codice del Server. La logica dei Tools, Resources e Prompts resta identica.

JSON-RPC 2.0: Il Protocollo Sottostante

MCP non ha inventato un nuovo protocollo di comunicazione. Si basa su JSON-RPC 2.0, uno standard aperto definito nel 2010 e ampiamente utilizzato in sistemi distribuiti.

Perché JSON-RPC?

1. Standard collaudato: 15+ anni di uso in produzione

2. Semplice: Definizione chiara e concisa

3. Testato: Librerie disponibili in ogni linguaggio

4. Interoperabile: Supporto nativo in molti framework

Struttura di un Messaggio JSON-RPC

Ogni messaggio JSON-RPC ha quattro campi principali:

{
  "jsonrpc": "2.0",           // Versione del protocollo
  "id": 1,                    // ID per associare richiesta/risposta
  "method": "nome_metodo",    // Metodo da invocare
  "params": { }               // Parametri del metodo
}

Semplicità pura. Nessuna magia.

Nota: Le notifications usano lo stesso formato ma senza il campo id. L'assenza dell'id è ciò che le distingue da una richiesta: il mittente non si aspetta risposta.

{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed"
}

I Tre Messaggi Fondamentali di MCP

MCP definisce tre messaggi che costituiscono l'intero lifecycle di una connessione. Vediamoli in dettaglio con i JSON reali.

1. Initialize: Handshake & Capability Negotiation

Scopo: Stabilire la connessione e negoziare le capabilities.

Richiesta del Client

Quando il Client si connette al Server, invia questo messaggio:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "roots": {
        "listChanged": true
      },
      "sampling": {}
    },
    "clientInfo": {
      "name": "claude-desktop",
      "version": "1.2.0"
    }
  }
}

Analisi dei campi:

protocolVersion: La versione del protocollo MCP che il Client supporta. Questo permette evoluzione del protocollo mantenendo backward compatibility.

capabilities: Le capabilities che il Client supporta. In questo esempio:

roots: Il Client può gestire filesystem roots
sampling: Il Client supporta richieste di sampling (completamento dall'LLM)

clientInfo: Informazioni sul Client per debugging e telemetry.

Risposta del Server

Il Server risponde con le sue capabilities:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {},
      "resources": {
        "subscribe": true,
        "listChanged": true
      },
      "prompts": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "my-knowledge-base-server",
      "version": "1.0.0"
    }
  }
}

Analisi dei campi:

protocolVersion: Deve corrispondere a quella del Client. Se non corrisponde, la connessione viene terminata immediatamente.

capabilities: Le capabilities che il Server supporta:

tools: Espone tools eseguibili
resources: Espone resources leggibili (con supporto per subscription e notifiche di cambio)
prompts: Espone prompt template (con supporto per notifiche di cambio)

serverInfo: Informazioni sul Server per debugging.

Nota sui listChanged: Quando vedete "listChanged": true nelle capabilities, significa che quel componente supporta le notifications. Ad esempio, resources.listChanged: true indica che il Server invierà una notification notifications/resources/list_changed quando la lista delle resources cambia. Il Client potrà allora fare una nuova resources/list per aggiornarsi.

Capability Negotiation: Fail Fast

Se le capabilities non sono compatibili, la connessione fallisce immediatamente.

Esempio di failure:

Client richiede: { "mandatory_capability": "advanced_features" }
Server supporta: { "tools": {}, "resources": {} }

→ Connection failed: unsupported capability

Questo è fail fast: meglio un errore chiaro all'inizio che comportamenti indefiniti dopo.

2. tools/list: Discovery

Scopo: Il Client scopre quali tools il Server espone.

Richiesta del Client

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

Semplice richiesta senza parametri: "Quali tools hai?"

Risposta del Server

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "search_kb",
        "description": "Cerca documenti nella knowledge base usando ricerca semantica. Supporta query in linguaggio naturale e ritorna i documenti più rilevanti con score di similarità. Usa questo tool quando l'utente chiede informazioni presenti nella documentazione aziendale.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "query": {
              "type": "string",
              "description": "Query di ricerca in linguaggio naturale"
            },
            "maxResults": {
              "type": "number",
              "description": "Numero massimo di risultati da ritornare",
              "default": 5,
              "minimum": 1,
              "maximum": 20
            },
            "filters": {
              "type": "object",
              "properties": {
                "category": {
                  "type": "string",
                  "enum": ["technical", "business", "process"]
                },
                "dateRange": {
                  "type": "object",
                  "properties": {
                    "start": { "type": "string", "format": "date" },
                    "end": { "type": "string", "format": "date" }
                  }
                }
              }
            }
          },
          "required": ["query"]
        }
      },
      {
        "name": "get_document",
        "description": "Recupera il contenuto completo di un documento specifico dato il suo ID. Usa questo tool quando hai già l'ID del documento da una ricerca precedente.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "documentId": {
              "type": "string",
              "description": "ID univoco del documento"
            }
          },
          "required": ["documentId"]
        }
      }
    ]
  }
}

Punti Critici della Discovery

1. Il Model vede SOLO questo

Il Model non ha accesso al vostro codice. Non vede l'implementazione. Prende decisioni basandosi esclusivamente su:

Nome del tool
Description
Input schema

2. Quality della Description

Una description ben scritta include:

Cosa fa il tool: Descrizione chiara della funzionalità
Quando usarlo: Trigger condition per il Model
Cosa ritorna: Tipo e struttura del risultato
Limitazioni: Cosa NON può fare

3. Input Schema Dettagliato

Più dettagli fornite nello schema, meglio il Model può costruire richieste valide:

{
  "maxResults": {
    "type": "number",
    "description": "Numero massimo di risultati",
    "default": 5,
    "minimum": 1,
    "maximum": 20
  }
}

Con questi vincoli, il Model sa che:

Il valore deve essere numerico
Ha un default se non specificato
Deve essere tra 1 e 20

3. tools/call: Execution

Scopo: Il Model ha deciso di usare un tool. Il Client lo invoca.

Richiesta del Client

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "search_kb",
    "arguments": {
      "query": "come configurare il database di produzione",
      "maxResults": 5,
      "filters": {
        "category": "technical"
      }
    }
  }
}

Flusso che ha portato a questo messaggio:

Utente: "Come configuro il database di produzione?"
Model analizza la richiesta
Model decide: "Ho bisogno di cercare nella KB"
Model guarda i tools disponibili
Model identifica: search_kb è appropriato
Model costruisce gli arguments
Client traduce in JSON-RPC
Client invia il messaggio al Server

Elaborazione sul Server

Quando il Server riceve questo messaggio:

async function handleToolCall(name, arguments) {
  // 1. Validazione
  if (name !== "search_kb") {
    throw new Error("Unknown tool");
  }

  // 2. Validazione schema
  validateSchema(arguments, searchKbSchema);

  // 3. Esecuzione
  const { query, maxResults, filters } = arguments;

  // 3.1 Tokenizza query
  const tokens = tokenize(query);

  // 3.2 Genera embedding
  const embedding = await generateEmbedding(tokens);

  // 3.3 Applica filtri
  let searchParams = { embedding, maxResults };
  if (filters?.category) {
    searchParams.category = filters.category;
  }

  // 3.4 Cerca nell'indice
  const results = await vectorIndex.search(searchParams);

  // 3.5 Formatta risultati
  return formatResults(results);
}

Risposta del Server

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Trovati 3 documenti rilevanti:\n\n1. **Configurazione Database Produzione** (score: 0.95)\n   - PostgreSQL 14.5\n   - Host: db.prod.internal\n   - Port: 5432\n   - Max connections: 100\n   - Connection timeout: 30s\n   - SSL: required\n   \n2. **Best Practices Database** (score: 0.87)\n   - Connection pooling: PgBouncer\n   - Backup schedule: 3am daily\n   - Replication: streaming async\n   \n3. **Troubleshooting Database Issues** (score: 0.82)\n   - Common errors and solutions\n   - Performance tuning\n   - Monitoring dashboards"
      }
    ],
    "isError": false
  }
}

Flusso Completo di Ritorno

Server formatta e ritorna il result
Client riceve la risposta
Client passa il result al Model
Model integra l'informazione nel suo contesto
Model genera la risposta finale all'utente

"Ho trovato la configurazione del tuo database di produzione:

Il database è PostgreSQL 14.5 hostato su db.prod.internal
sulla porta 5432. La configurazione prevede:
- Massimo 100 connessioni contemporanee
- Timeout di 30 secondi per le connessioni
- SSL obbligatorio per tutte le connessioni

Per il connection pooling viene utilizzato PgBouncer,
e i backup sono schedulati alle 3am ogni giorno con
replicazione streaming asincrona.

Vuoi che approfondisca qualche aspetto specifico?"

Gestione Errori

Se qualcosa va storto, il Server ritorna un errore JSON-RPC:

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "param": "maxResults",
      "reason": "Must be between 1 and 20",
      "received": 50
    }
  }
}

Errori standard JSON-RPC:

-32700: Parse error
-32600: Invalid request
-32601: Method not found
-32602: Invalid params
-32603: Internal error

Esempio End-to-End Completo

Vediamo ora l'intero flusso dall'inizio alla fine, con tutti i messaggi e tutte le decisioni.

Scenario

Utente: "Cerca nella KB la configurazione del database di produzione"

Step 1: Il Model Analizza

Il Model riceve la richiesta e inizia l'analisi:

Input: "Cerca nella KB la configurazione del database di produzione"

Analisi:
- Intent: ricerca di informazioni
- Source: knowledge base (KB)
- Target: configurazione database
- Environment: produzione

Decisione: Usare il tool search_kb

Il Model consulta i tools disponibili (dalla precedente tools/list):

{
  "name": "search_kb",
  "description": "Cerca documenti nella knowledge base...",
  "inputSchema": {
    "properties": {
      "query": { "type": "string" },
      "maxResults": { "type": "number" }
    }
  }
}

Match perfetto! Il Model decide di usare questo tool.

Step 2: Il Client Costruisce la Richiesta

Il Model comunica la sua decisione al Client:

Tool: search_kb
Arguments:
  - query: "database production configuration"
  - maxResults: 5

Il Client traduce in JSON-RPC:

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "search_kb",
    "arguments": {
      "query": "database production configuration",
      "maxResults": 5
    }
  }
}

E invia il messaggio al Server via transport (stdio o HTTP).

Step 3: Il Server Riceve e Valida

Il Server riceve il messaggio:

// Server riceve via transport
const message = await transport.receive();

// Parse JSON-RPC
const { method, params } = message;

// Verifica metodo
if (method !== "tools/call") {
  return errorResponse("Invalid method");
}

// Estrae parametri
const { name, arguments } = params;

// Verifica tool exists
if (name !== "search_kb") {
  return errorResponse("Unknown tool");
}

// Valida schema
const validation = validateSchema(arguments, searchKbSchema);
if (!validation.valid) {
  return errorResponse("Invalid params", validation.errors);
}

Validazione passata ✅

Step 4: Il Server Esegue la Ricerca

async function executeSearch(query, maxResults) {
  console.error(`[LOG] Starting search: query="${query}", max=${maxResults}`);

  // 1. Tokenizzazione
  const tokens = tokenize(query);
  console.error(`[LOG] Tokenized into ${tokens.length} tokens`);

  // 2. Generazione embedding
  const embedding = await embeddingModel.encode(tokens);
  console.error(`[LOG] Generated embedding vector of size ${embedding.length}`);

  // 3. Ricerca nell'indice vettoriale
  const vectorResults = await vectorIndex.search({
    vector: embedding,
    topK: maxResults * 2  // Recupera il doppio per il re-ranking
  });
  console.error(`[LOG] Vector search returned ${vectorResults.length} results`);

  // 4. Re-ranking con modello cross-encoder
  const reranked = await reranker.rank(query, vectorResults);

  // 5. Prendi top maxResults
  const topResults = reranked.slice(0, maxResults);

  // 6. Recupera contenuti completi
  const documents = await Promise.all(
    topResults.map(async (result) => {
      const doc = await database.getDocument(result.id);
      return {
        id: doc.id,
        title: doc.title,
        excerpt: doc.excerpt,
        relevanceScore: result.score,
        metadata: {
          category: doc.category,
          lastUpdated: doc.updatedAt,
          author: doc.author
        }
      };
    })
  );

  console.error(`[LOG] Search completed, returning ${documents.length} documents`);
  return documents;
}

Nota l'uso di console.error() per logging. Mai console.log() su stdio!

Step 5: Il Server Risponde

const results = await executeSearch(
  arguments.query,
  arguments.maxResults
);

// Formatta risposta
const response = {
  jsonrpc: "2.0",
  id: message.id,
  result: {
    content: [
      {
        type: "text",
        text: formatSearchResults(results)
      }
    ]
  }
};

// Invia via transport
await transport.send(response);

Response JSON inviata:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Trovati 3 documenti rilevanti:\n\n1. **Configurazione Database Produzione** (score: 0.95)\n   PostgreSQL 14.5, host: db.prod.internal, port: 5432\n   Max connections: 100, timeout: 30s, SSL required\n   \n2. **Database Best Practices** (score: 0.87)\n   Connection pooling con PgBouncer\n   Backup giornalieri alle 3am\n   Replicazione streaming asincrona\n   \n3. **Troubleshooting Database** (score: 0.82)\n   Errori comuni e soluzioni\n   Performance tuning guide"
      }
    ]
  }
}

Step 6: Il Client Passa il Result al Model

Il Client riceve la risposta e la passa al Model:

const response = await transport.receive();

// Verifica corrispondenza ID
if (response.id !== request.id) {
  throw new Error("ID mismatch");
}

// Verifica presenza result
if (response.error) {
  throw new MCPError(response.error);
}

// Estrae contenuto
const content = response.result.content;

// Passa al Model
model.addToolResult({
  toolName: "search_kb",
  result: content
});

Step 7: Il Model Genera la Risposta Finale

Il Model ora ha:

La richiesta originale dell'utente
Il risultato del tool search_kb

Genera la risposta finale:

Input context:
- User query: "Cerca nella KB la configurazione del database di produzione"
- Tool result: [3 documents about database configuration]

Model output:
"Ho trovato la configurazione del database di produzione nella nostra
knowledge base. Il database è PostgreSQL 14.5 hostato su db.prod.internal
sulla porta 5432.

Configurazione principale:
- Connessioni massime: 100
- Timeout connessione: 30 secondi
- SSL: obbligatorio

Per le connessioni viene utilizzato PgBouncer come connection pooler,
i backup sono schedulati giornalmente alle 3am, e c'è una replica
configurata con streaming asincrono.

Ho anche trovato una guida per il troubleshooting di problemi comuni e
best practices per il tuning delle performance. Vuoi che approfondisca
qualcuno di questi aspetti?"

Flusso Completo Riassunto

[User]
  ↓ "Cerca nella KB..."
[Model]
  ↓ Analizza → Decide: search_kb
[Client]
  ↓ Costruisce tools/call JSON-RPC
[Transport]
  ↓ Invia messaggio
[Server]
  ↓ Riceve, valida, esegue
[Server]
  ↓ Genera embedding, cerca, rankizza
[Server]
  ↓ Formatta e ritorna result
[Transport]
  ↓ Invia response
[Client]
  ↓ Riceve, passa al Model
[Model]
  ↓ Integra result, genera risposta
[User]
  ↓ Legge risposta completa

Tempo totale: ~2-3 secondi (dipende dalla complessità della ricerca)

Separazione dei ruoli mantenuta:

Model: Ha deciso COSA fare
Client: Ha gestito COME comunicare
Server: Ha eseguito COSA richiesto

Nessun componente ha invaso le responsabilità degli altri.

Lifecycle del Server MCP

Un server MCP attraversa diversi stati durante il suo lifecycle. Comprendere questi stati è fondamentale per gestire correttamente le connessioni e debuggare problemi.

Stati del Lifecycle

1. Startup

Cosa succede:

Caricamento configurazione
Lettura variabili d'ambiente
Inizializzazione connessioni (database, cache, ecc.)
Caricamento risorse (indici, modelli, ecc.)
Setup logging

Esempio:

async function startup() {
  console.error("[STARTUP] Loading configuration...");
  const config = loadConfig();

  console.error("[STARTUP] Connecting to database...");
  const db = await connectDatabase(config.db);

  console.error("[STARTUP] Loading vector index...");
  const vectorIndex = await loadVectorIndex(config.indexPath);

  console.error("[STARTUP] Initializing embedding model...");
  const embeddingModel = await loadEmbeddingModel();

  console.error("[STARTUP] Server ready");

  return {
    db,
    vectorIndex,
    embeddingModel
  };
}

Failure handling: Se lo startup fallisce, il processo deve terminare con exit code non-zero. Non tentate di continuare con risorse parzialmente inizializzate.

2. Listening

Cosa succede:

Il Server entra in ascolto sul transport
Per stdio: legge da standard input
Per HTTP: ascolta su porta configurata

3. Initialize (Handshake)

Cosa succede:

Arriva il messaggio initialize dal Client
Server valida protocol version
Server valida capabilities
Se OK: connessione stabilita
Se KO: connessione rifiutata

Fail fast: Se la validazione fallisce, terminare la connessione immediatamente. Non proseguire con una connessione in stato inconsistente.

4. Ready (Idle)

Cosa succede:

Server ha completato handshake
Attende richieste dal Client
Può ricevere: tools/list, tools/call, resources/list, ecc.

5. Processing

Cosa succede:

Server riceve una richiesta (es: tools/call)
Parse del JSON
Validazione dello schema
Esecuzione della funzione
Generazione della risposta
Invio della risposta

Dopo il processing, il Server torna in stato Ready.

6. Shutdown

Cosa succede:

Client si disconnette, oppure
Errore fatale, oppure
Signal di terminazione (SIGTERM, SIGINT)

Cleanup necessario:

Chiusura connessioni database
Flush di log pendenti
Chiusura di file aperti
Rilascio di risorse

Senza shutdown corretto, potreste avere connessioni database lasciate aperte, log persi, file corrotti, o stato inconsistente. Vedremo l'implementazione concreta del graceful shutdown nei prossimi video della serie.

Critical Warnings

1. STDOUT è il Canale del Protocollo (stdio transport)

IL WARNING PIÙ IMPORTANTE: Su transport stdio, mai usare console.log().

Perché?

Su stdio:

stdout = canale del protocollo JSON-RPC
Il Client legge da stdout aspettandosi SOLO JSON valido

Se fate:

console.log("Server started!");  // ❌ MALE!

Il Client riceve:

Server started!
{"jsonrpc":"2.0","id":1,"result":{...}}

Il parser JSON riceve testo misto e crasha:

Error: Unexpected token 'S' at position 0

Dal vostro punto di vista: "Il server è partito!"

Dal punto di vista del Client: "Protocollo corrotto, impossibile comunicare"

E il peggio: L'errore che vedete è sempre generico come:

JSON parse error
Unexpected token
Invalid protocol message

Niente che vi dica "hai usato console.log".

Dovete saperlo già.

Debugging Pratico

99% delle volte che vedete "JSON parse error":

✓ Primo posto dove guardare: console.log nel codice
✓ Secondo posto: console.log in dependencies
✓ Terzo posto: stdout da processi child

Come fare logging corretto:

// ❌ MALE - va su stdout
console.log("Processing request...");

// ✅ BENE - va su stderr
console.error("Processing request...");

// ✅ ANCORA MEGLIO - logger su file
logger.info("Processing request...");

2. Never Trust Input (Even from AI)

Regola d'oro: Validare SEMPRE gli input, anche quelli provenienti dal Model.

Perché?

Il Model può sbagliare i parametri
Il Client può avere bug
L'utente può manipolare i messaggi (in teoria)

Esempio di input invalido dal Model:

{
  "name": "search_kb",
  "arguments": {
    "query": "test",
    "maxResults": 1000  // Limite è 20!
  }
}

Senza validazione:

// ❌ Trust input
const results = await search(arguments.query, arguments.maxResults);
// → Cerca 1000 risultati, sovraccarica il sistema

Con validazione:

// ✅ Validate first
if (arguments.maxResults > 20) {
  throw new InvalidParamsError(
    `maxResults must be <= 20, got ${arguments.maxResults}`
  );
}

const results = await search(arguments.query, arguments.maxResults);

Nella serie vedremo come usare Zod per rendere la validazione dichiarativa e automatica. Per ora il concetto chiave è: mai fidarsi dell'input, nemmeno se viene dall'AI.

Conclusione

Model Context Protocol rappresenta un cambio di paradigma nel modo in cui integriamo le AI con i nostri sistemi. Non è solo un protocollo tecnico: è uno standard aperto che permette di costruire integrazioni robuste, portabili e manutenibili.

Cosa Abbiamo Visto

Il Problema: Integration hell causato dalla frammentazione delle integrazioni AI proprietarie.

La Soluzione: MCP come standard unificato per tutte le integrazioni.

L'Architettura: Separazione chiara tra Host, Client e Server con comunicazione basata su request-response e notifications.

I Quattro Pilastri: Resources (dati), Tools (azioni), Prompts (template), Transport (canale).

Il Protocollo: JSON-RPC 2.0 con tre messaggi fondamentali (initialize, tools/list, tools/call) più notifications per segnalazioni.

Il Lifecycle: Stati ben definiti da startup a shutdown.

Prossimi Passi

Questa guida vi ha fornito le fondamenta teoriche di MCP. I prossimi passi sono:

Setup del Progetto: Inizializzare un progetto TypeScript con MCP SDK
Primo Server: Implementare un server funzionante con un tool reale
Testing: Testare l'integrazione con Claude Desktop
Production: Deploy e monitoring in ambiente production

Questo articolo è parte di una serie completa su Model Context Protocol. Per video tutorial, esempi di codice e deployment guide, visita il canale.

Trascrizione della Lezione Video

Introduzione

Ciao a tutti e benvenuti in questa serie su come creare un server MCP da zero. Sono Manuel di WebTea Learning; in questa serie vi porterò dalla teoria completa fino al deployment in produzione di un server MCP professionale per una knowledge base intelligente.

Se non sapete cos'è MCP, non preoccupatevi: è esattamente quello che scopriremo oggi. E se invece già lo conoscete, preparatevi, perché andremo molto in profondità.

Vi ricordo che, oltre al video, su learning.webtea.it trovate gli appunti scritti con qualche approfondimento extra. E, ultima raccomandazione: non dimenticate di seguirmi e attivate le notifiche per non perdervi i prossimi video.

Quindi, bando alle ciance, iniziamo.

Agenda

In questa prima lezione della serie, vedremo il problema che MCP risolve e la soluzione che offre la sua architettura. I quattro pilastri fondamentali, il protocollo JSON-RPC (e lo vedremo bene in dettaglio), e il lifecycle completo di un server.

Alla fine, vi mostrerò esattamente cosa succede quando un utente fa una domanda a Claude, e Claude usa il vostro tool per rispondere: tutto il flusso completo, dall'inizio alla fine.

Ma partiamo dal problema.

Il Problema: Integration Hell

Prima di MCP, ogni AI aveva il suo sistema proprietario di integrazione: Claude aveva le API Anthropic, GPT aveva quello di OpenAI e Gemini aveva quelle di Google. Fin qui sembra solo un problema di duplicazione, ma il vero problema è più profondo: senza uno standard comune, ogni integrazione diventa un adattatore custom. La gestione del contesto è hard coded. I formati dei dati cambiano, ogni endpoint ha il suo schema e appena qualcosa si modifica, si rompe tutto.

Cambiate ambiente da test a produzione? Le pipeline vanno riviste. Aggiornano un endpoint API? Dovete riscrivere metà della logica. Aggiungete una nuova sorgente dati? Altro adattatore custom.

Questo è quello che chiamo "integration hell". Tre codebase. Tre protocolli. Tre logiche di contesto: backend parla JSON strutturato, data scientist parla in embedding e vettori, DevOps parla di deployment container, e nessuno parla lo stesso linguaggio. L'integrazione non è solo duplicazione, è complessità esponenziale. E la complessità, come ben sappiamo, non scala.

Quindi, senza uno standard, ogni integrazione AI è un progetto custom.

L'analogia: il Type-C dell'AI

Ma, per capire al meglio, facciamo un'analogia.

Il Model Context Protocol è definito anche in documentazione come il Type-C dell'AI. Proviamo a pensare com'era prima dell'arrivo del Type-C: ogni dispositivo aveva il suo caricatore, che sia Lightning, MagSafe, Micro USB. Avevamo sicuramente tre cavi diversi in borsa per poter caricare tre dispositivi diversi. Poi, fortunatamente, è arrivato il Type-C: un solo standard, un solo protocollo, e non avevamo più bisogno di portare tre caricatori.

MCP fa esattamente questo, ma per le integrazioni AI.

La Soluzione: Model Context Protocol

E MCP esattamente cos'è? Cosa fa?

MCP è un solo protocollo standardizzato. Il suo mantra è "write once, run everywhere": scrivere una volta per farlo eseguire ovunque. Tutti i client sono compatibili e non abbiamo (questo è importante) nessun vendor lock-in, quindi non siamo per forza di cose legati ad Anthropic, piuttosto che a OpenAI, piuttosto che a Google.

Architettura MCP

Per quanto riguarda la parte architetturale, MCP definisce tre componenti principali: host, client e server. Vediamoli uno per uno.

Host

Partiamo dall'host. L'host è l'applicazione che l'utente utilizza: Claude Desktop, Cursor, un IDE, una chat AI. L'host è l'ambiente che contiene tutto: contiene l'interfaccia utente, contiene il model (quindi LLM) e contiene il client MCP; è il punto di orchestrazione.

Client

All'interno dell'host troviamo il client. Il client è il componente che parla il protocollo MCP. È responsabile della comunicazione con i server MCP: invia richieste, riceve risposte e gestisce la connessione. Il client non contiene logiche di business, è solo un traduttore. Traduce le richieste dell'host in messaggi MCP.

Server

Dall'altra parte, invece, troviamo il server. Il server è il componente che voi implementate. Questo è il nostro codice. Il server espone tre cose: tools, resources e prompt. Qui definite cosa l'AI può fare: accesso ai file, accesso ai database, accesso ad API.

Dove sta il Model?

E ora il punto fondamentale: il model (quindi l'LLM) non è parte del protocollo MCP. Il model vive dentro l'host. Il model non comunica direttamente con il server, comunica attraverso il client. Il model prende decisioni. Il client traduce queste decisioni in chiamate MCP. Il server esegue.

E il principio chiave diventa quindi questo: il model decide, il client comunica e il server esegue. E in tutto questo l'host orchestra tutto.

Quindi ricordate: MCP standardizza la comunicazione tra client e server, non tra model e server.

Direzione della Comunicazione

Ora, un dettaglio fondamentale sulla direzione della comunicazione.

È importante sottolineare che il server non può mai chiamare il client. È sempre una questione di request-response, mai push. Il server risponde solo quando riceve una richiesta. Non può iniziare una conversazione, non può inviare notifiche, non può fare callback.

Questo è fondamentale, sostanzialmente per due motivi.

Primo: la sicurezza. Il server non può attaccare il client, non può inondarlo di messaggi, non può tentare di prenderne il controllo.

Secondo: la semplicità. Request-response è il modello più semplice da implementare, debuggare e monitorare. Niente race condition, niente sincronizzazione complessa, niente code di messaggi. Solo: richiesta arriva, risposta parte. Questo è il modello di controllo di MCP: sempre esplicito, sempre prevedibile.

Precisazione sulle Notifications

Piccola precisazione. Intanto ciao, sono Manuel dal futuro.
Una piccola precisazione importante su questa slide: quando dico "nessuna notifica push", intendo che il server non può fare richieste attive al client, però MCP supporta le notifications (messaggi unidirezionali leggeri). Il server può segnalare: "La lista dei tool è cambiata", e il client poi farà una nuova richiesta per aggiornarsi. È un meccanismo di segnalazione, non di comunicazione bidirezionale vera e propria.
Nella lezione testuale (trovate il link in descrizione) trovate tutti i dettagli.

I Quattro Pilastri

E se l'architettura è chiara, vediamo ora cosa espone concretamente un server MCP, perché il protocollo definisce quattro primitive fondamentali: Resources, Tools, Prompt e Transport. Queste primitive definiscono come il client può interagire con il server. Vediamole una per una.

1. Resources

Partiamo da resources. Le risorse sono dati esposti dal server. Sono informazioni che il model può leggere, ma non eseguire e non modificare.

Pensatele come documenti accessibili tramite il protocollo (ad esempio file di configurazione, documentazioni, log di sistema, record di database): il server rende queste informazioni disponibili. Il client può richiederle, il model può usarle come contesto, ma non esegue alcuna azione. Le risorse sono passive, forniscono contesto. E il contesto nell'AI sappiamo che è importantissimo, quindi forniscono contesto, non comportamento.

Immaginiamo quindi quello che dobbiamo costruire per comprendere meglio queste risorse. Noi dobbiamo costruire una knowledge base di documentazione. Il nostro server espone una resource che può essere api-reference.md. Quando il model ha bisogno di rispondere a una domanda sulle API, il client può richiedere quella resource: il server la legge dal file system e la restituisce come contesto. A quel punto, il model la usa per generare una risposta accurata, ma non ha mai eseguito codice: ha solo letto dati.

Questo è il pattern Resource. Quindi è un po' come se voi prendete un file che avete sul vostro computer e lo caricate come allegato in una conversazione con ChatGPT o Gemini. Voi state fornendo del contesto. Ecco, allo stesso modo le risorse funzionano in maniera simile.

2. Tools

I tools, invece, sono il secondo elemento e sono decisamente più importanti. I tool sono azioni eseguibili, quindi funzioni che il server espone, funzioni che il model può decidere di invocare tramite il client (ad esempio: search_kb per cercare nella knowledge base, oppure create_file per creare un file, o query_db per interrogare un database, call_api per interagire con sistemi esterni).

Questa è la differenza sostanziale: le resources forniscono informazioni, i tool eseguono operazioni. Qui l'AI smette di essere passiva e diventa operativa. Non sta più solo leggendo, sta agendo sul nostro sistema. Sempre tramite il server, sempre sotto il nostro controllo.

3. Prompts

Il terzo elemento sono i prompt. I prompt sono template riutilizzabili definiti dal server ed esposti al client. Servono per standardizzare task comuni.

Immaginiamo, ad esempio, di voler analizzare dei log di errore. Invece di lasciare che il model inventi ogni volta come analizzare i log, il nostro server può esporre un prompt tipo "Analyze Error Logs" con istruzioni già ottimizzate (quindi: analizza questi log, identifica pattern comuni, raggruppa errori simili, suggerisci cause probabili, ordina per frequenza, eccetera). Il client può usare questo template, riempirlo con i log specifici e ottenere analisi consistenti di qualità.

Questo migliora chiaramente la coerenza, riduce la latenza e sfrutta la nostra expertise di dominio. I prompt non eseguono codice, non forniscono dati: forniscono semplicemente istruzioni strutturate.

4. Transport

L'ultimo elemento, quindi il quarto pilastro, sono i transport. Il Transport è il livello più basso. Definisce come i messaggi MCP vengono trasmessi tra client e server. Il protocollo MCP è indipendente dal Transport. Può funzionare su diversi canali. I più comuni sono stdio per comunicazioni locale fra processi, e HTTP con Server-Sent Events per comunicazione remota.

Vediamo la differenza.

stdio è perfetto per integrazioni locali: Claude Desktop usa stdio, ad esempio; Cursor usa stdio. Il server legge da standard input e scrive su standard output. Tutto locale, niente network, veloce e semplice.

HTTP con Server-Sent Events è perfetto per i deployment remoti: il server diventa un servizio HTTP, il client si connette via web. Il server può essere in cloud, può scalare orizzontalmente e può servire migliaia di client.

In questa serie useremo stdio perché è semplice ed è veloce. È perfetto per quelle integrazioni locali con Claude Desktop, ma il protocollo è lo stesso. Se domani facciamo il deploy (alla fine di questa serie faremo il deploy in produzione su HTTP), ci basterà cambiare solamente il transport e il resto del codice resta identico. È estremamente semplice da fare.

Recap dei Pilastri

Quindi, facciamo un piccolo recap. Il server espone: resources per fornire i dati, tools per eseguire azioni, prompts per fornire template. Il client usa il transport per comunicare con il server, e il model, tramite il client, decide quando usare queste capacità.

Il Protocollo JSON-RPC

E adesso che sappiamo cosa espone un server MCP, vediamo come queste primitive vengono effettivamente utilizzate, e per farlo dobbiamo guardare al protocollo reale, e quindi i messaggi in JSON-RPC.

Ora qui siamo arrivati al cuore tecnico di MCP. Il protocollo utilizza JSON-RPC 2.0. Non è un protocollo proprietario, non è qualcosa inventato appositamente per MCP. È uno standard aperto definito all'incirca nel 2010, quindi è in giro da un bel po', ed è utilizzato in moltissimi sistemi distribuiti. Questo è importante perché significa che MCP non reinventa. La comunicazione si basa su uno standard semplice, solido e già testato.

JSON-RPC è estremamente semplice. Definisce un modo standard per chiamare metodi remoti usando JSON. Ogni messaggio ha quattro campi principali: la versione del protocollo; method, il metodo da chiamare; params, che sono i parametri; e l'ID, per poter associare la richiesta alla risposta.

È tutto. Nessuna magia, nessuna stregoneria, niente fumo. Solo JSON strutturato. Ma questo JSON è ciò che permette al client MCP di comunicare con il server MCP e quindi indirettamente permette al model di usare i nostri tool.

I Tre Messaggi Fondamentali

Ora vedremo i tre messaggi fondamentali che dipingono l'intero lifecycle di una connessione MCP. Il primo è l'initialization (o initialize) con l'handshake. Poi abbiamo una tools list di Discovery e una tools call di execution. Questi tre messaggi sono sufficienti per abilitare un'integrazione completa e li vediamo uno per uno.

1. Initialize (Handshake)

Partiamo con initialize. Questo è il primo messaggio inviato dal client al server quando la connessione viene stabilita. Pensatelo come una sorta di stretta di mano (anche perché handshake significa proprio quello). Il client dice: "Questo è il protocollo che supporto e queste sono le mie capacità". E il server risponde: "Questa è la versione che supporto, queste sono le mie capacità".

Questo processo si chiama Capability Negotiation. Entrambe le parti, quindi, verificano di essere compatibili.

Ma qual è l'oggetto del negoziato esattamente? Le capabilities sono funzionalità opzionali del protocollo. Per esempio, il client può dichiarare supporto al sampling ("Posso gestire richieste di completamento dal LLM") o supporto roots ("Posso fornire file system root"), e il server può dichiarare supporto ai tools ("Espongo tools eseguibili"), supporto resources ("Espongo dati leggibili") e supporto prompt ("Espongo template").

Se le capabilities non sono compatibili, la connessione fallisce immediatamente.

Facciamo un piccolo esempio per capire meglio. Il client dice: "Supporto sampling roots". Il server dice: "Supporto solo tools". Connessione ok, perché non c'è conflitto. Ma se il client richiede una capability che il server non supporta, la connessione termina.

Questo garantisce che client e server parlino sempre lo stesso dialetto del protocollo. Niente comportamenti indefiniti, niente bug silenziosi, niente fail test.

2. Tools List (Discovery)

Il messaggio successivo è Tools List, o Discovery. Una volta stabilita la connessione, il client deve capire cosa può fare il server e, per farlo, invia la richiesta Tools list. Il significato è semplice: "Mi hai detto che hai dei tools, ma quali sono questi tools?" Il server risponde con una lista strutturata.

Ogni tool include: il nome (il nome del tool), la description (cosa fa), e l'input schema (quali parametri accetta).

Questo è un punto fondamentale. Il model non vede il nostro codice, non vede la nostra implementazione: vede solo questa definizione strutturata. Il model prende decisioni basandosi sul nome del tool. Ancor più importante la description (quindi non deve essere una roba tipo "questo è un tool che ho implementato", deve essere una roba bella, descrittiva) e lo schema degli input.

E non stresserò mai a sufficienza il fatto che la description è critica. La description migliore porta a decisioni migliori da parte del modello.

3. Tools Call (Execution)

Infine il terzo messaggio, che è quello più importante, o meglio, è il momento più importante. Questo è il tools call, quindi l'execution. Questo è il momento in cui il model decide di usare un tool. Il model non esegue codice, il model prende una decisione. Il client traduce questa decisione in una richiesta JSON-RPC e la invia al server.

Il messaggio contiene il nome del tool e gli argomenti. Quindi chiamo il search_kb e l'argomento è la query "Database Production configuration". Il server riceve il messaggio, valida gli input, esegue la funzione e restituisce il risultato. Il risultato torna al client, il client lo passa al model e il model lo usa per generare la risposta finale.

Il Ciclo Completo

Mettiamo tutto insieme per comprendere meglio. Partiamo con initialize: quando il client e il server stabiliscono la connessione, si stringono la mano e vedono se sono compatibili. Tools List: il client scopre le capacità del server. Tools call: il client invoca un tool. Il server esegue.

Questo è l'intero ciclo MCP: handshake, discovery ed execution, tutto basato su JSON-RPC. Tutto esplicito, tutto controllato.

E notate una cosa importante: questi tre messaggi bastano per tutto. Non c'è tools update, non c'è tool subscribe, non c'è tools stream; il protocollo è volutamente minimale. Initialize, list, call. Questo è tutto, perché la semplicità è una feature. Meno messaggi, meno stati, meno bug: più facile da implementare, più facile da debuggare, più facile da mantenere.

Quindi, ricordate sempre questo: il model non esegue codice, il model prende decisioni, il client comunica, il server esegue. Questo è il modello di sicurezza e controllo che MCP ci mette a disposizione.

Esempio End-to-End

Ok, ci sono un po' di concetti che sono stati condivisi fino ad adesso. Spero tra l'altro che siano chiari. E però penso che sia giunto il momento di fare un piccolo esempio end-to-end per ripercorrere tutto quanto il percorso che avviene quando noi mettiamo a disposizione un MCP ad un modello.

Facciamo un percorso dall'inizio alla fine e seguiamo il flusso completo.

Lo Scenario

Lo scenario è questo: l'utente apre Claude Desktop e scrive "Cerca nella knowledge base la configurazione del database di produzione". Cosa succede?

Step 1: Il Model Analizza

Si parte dallo step uno. Il model analizza la richiesta, guarda i tool disponibili e trova search_kb. La description di search_kb è "cerca documenti nella knowledge base usando query semantica". L'input schema è query string, max results number (quindi una stringa come query e un numero come risultati massimi da ricevere). Il model decide: "Uso questo tool".

Step 2: Il Client Costruisce il JSON-RPC

Lo step due: il client costruisce il JSON-RPC, quindi la tools call con la query. Manderà un JSON-RPC con metodo tools call e i parametri sono il nome del tool che vuole utilizzare (quindi search_kb) e gli argomenti che questo tool si aspetta (la query e il numero massimo di risultati) e lo invia al server via standard input.

Step 3: Il Server Riceve e Valida

Il server riceve il messaggio, valida lo schema (query è una stringa? Check. Max results è un numero? Check), esegue la funzione a quel punto.

Step 4: Il Server Esegue

Esegue search_kb, la funzione che cosa fa? Tokenizza la query, cerca nell'indice vettoriale, mette in ordine i risultati per rilevanza e restituisce la top cinque. Poi, se ce ne sono di meno, restituisce quelli che comunque ha trovato. A questo punto il server cerca nell'indice vettoriale, trova cinque documenti.

Step 5: Il Server Risponde

A questo punto il server risponde con il risultato, quindi con il JSON result. In questo result ci sono i documenti. C'è quindi questa lista di documenti con titolo, riassunto, e la rilevanza è un numero che va da 0 a 1.

Step 6: Il Client Passa il Risultato al Model

Il client riceve la risposta e passa il risultato al Model. Claude ora ha tutte le informazioni: sa che esistono due documenti rilevanti, ad esempio, e sa cosa contengono e può generare la risposta finale.

Step 7: Il Model Genera la Risposta

Il model genera la risposta finale all'utente, dicendogli: "Ho trovato la configurazione del database di produzione PostgreSQL 14..." e così via. "Vuoi che approfondisca qualche aspetto?"

Questo è tutto. È un flusso di sette step: User → Model → Client → Server → Execution → Result → Client → Model → Response → User. Questo è tutto quanto il percorso che viene fatto, il ciclo completo dall'inizio alla fine.

La Separation of Concerns

E ora capite perché la separation of concerns è così importante. Il model non sa dove sono i dati, non sa come cercarli, non sa nemmeno che state usando Postgres. Il model sa solo che c'è un tool che si chiama search_kb: "Posso passargli una query. Mi restituisce dei risultati". Tutto il resto è responsabilità del server. Il nostro codice, quindi, è quello che è sotto il nostro controllo.

Lifecycle del Server MCP

Ora che abbiamo visto i messaggi e il flusso end-to-end, ci manca ancora una cosa: il lifecycle completo di un server MCP. Perché non si tratta semplicemente di un "avvio server, ciao, tutto a posto?". No, è una macchina a stati e se capite questi stati capirete anche come debuggare qualunque problema MCP in 5 minuti.

Gli Stati del Server

Startup. Il server parte in startup. Qui caricate configurazioni, variabili d'ambiente, inizializzazione delle connessioni, database, file system, indicizzazione. Quello che vi serve, insomma.

Listening. Successivamente allo startup entra in uno stato di listening: sta in ascolto sul Transport (nel nostro caso stdio, quindi legge da standard input e scrive su standard output).

Initialize (Handshake). A quel punto arriva initialize, quindi quel famoso handshake che abbiamo visto prima, il client apre la connessione e manda la stretta di mano. Qui il server valida due cose critiche: protocol version e capabilities. Se qualcosa non torna dovete fallire subito, fail fast. Meglio un errore chiaro all'inizio che un comportamento instabile dopo. Meglio veramente troncare subito la connessione.

Ready. Se l'handshake va bene, il server entra in stato ready. Ready significa "sono compatibile, sono vivo e posso ricevere richieste".

Idle ↔ Processing. Da qui in poi il server passa continuamente tra due stati: Idle (Ready aspetta richieste) e Processing (gestisce una richiesta MCP). Ogni volta che arriva un tool call, fa il parse del JSON, valida lo schema, esegue la funzione e restituisce result oppure error, e poi torna in ready.

Shutdown. Infine c'è shutdown, che può succedere perché il client si disconnette (ovviamente non ha senso che rimanga attivo) o per errore fatale (il processo viene terminato). Qui bisogna fare il cleanup di tutto: chiudete connessioni, flush dei log, rilasciate le risorse. Se il vostro server in produzione non gestisce bene lo shutdown, avrete dei bug fantasma che girano e infestano la vostra codebase.

Critical Warnings

Mai usare console.log

Importante da sottolineare: il warning più importante per chi usa stdio è mai usare console.log in un server MCP. Mai e poi mai. So che è abitudine usare console.log per tutto, ma qui no. Il motivo è semplice: lo standard output è il canale del protocollo. Il client legge da standard output aspettandosi solo JSON-RPC. Se voi stampate "server start", il client riceve testo non JSON e il parser si rompe.

Risultato? Crash immediato, e soprattutto non capirete mai perché. Perché dal vostro punto di vista il server è partito. Dal punto di vista del client, invece, il protocollo è corrotto, e il bello è che l'errore che vedrete sarà "JSON Parser Expect token S invalid protocol message". Niente che vi dica "hai usato console.log", quindi solo errori di parsing.

Regola pratica da stamparsi ovunque: se vedete JSON parse error nel client, il 99% delle volte avete usato un console.log che inquina lo standard output. Primo posto dove guardare: fate una ricerca console.log ed eradicatelo.

Come fare logging

Abbiamo due opzioni sicure:

console.error, che va sullo stderr e non interferisce con il protocollo principale
Log su file, ancora meglio in produzione

Ricordatevi: lo standard output è per il protocollo, lo standard error è per il log. Questo vi risparmia ore e ore di debugging. Considerate che mettere il console.log è memoria muscolare per chi sviluppa in JavaScript/TypeScript, quindi a volte può capitare che sovrappensiero sfugga quel console.log.

Mai fidarsi dell'input

Ultimo punto fondamentale: non vi fidate mai dell'input, anche se questo arriva dall'AI.

Il model può sbagliare parametri, il client può avere bug, e voi non potete permettervi che un tool crashi il server. Quindi: validazione sempre, è tutto schema driven. Prima validate, poi eseguite. Se l'input è invalido, rispondete con un errore JSON-RPC "invalid param", così il server resta stabile. Il client riceve un errore utile, voi potete debuggare subito.

Noi lo vedremo anche negli esempi pratici delle prossime lezioni. Utilizzeremo Zod per validare lo schema, quindi validare poi gli input, anche quando questi arrivano dall'AI, perché dobbiamo essere in ascolto di tutte e due le parti.

Regola fondamentale: mai fidarsi dell'AI.

Recap

Ora avete il modello mentale completo. Capite cos'è MCP. Capite come funziona. Capite la separazione tra model, client, server e capite cosa costruiremo nei prossimi video.

A inizio di questo video abbiamo visto il problema: senza uno standard, ogni integrazione è fragile. Adattatori custom, pipeline che si rompono, nessuna portabilità.

Poi abbiamo visto la soluzione: Model Context Protocol, uno standard aperto che permette di esporre tool, dati e capacità alle AI in modo strutturato, dove il mantra è "write once, run everywhere".

Abbiamo visto l'architettura ufficiale MCP: Host, client, server. Il Model prende decisioni. Il client comunica tramite il protocollo e il server esegue. Separazione chiara delle responsabilità. Controllo totale e comunicazione sempre unidirezionale: request-response, mai push.

Abbiamo visto cosa espone un server MCP: Resources per fornire i dati, Tools per eseguire azioni, Prompt per fornire template e il Transport che permette la comunicazione, con esempi concreti per ognuno.

Poi siamo andati ancora più in profondità. Abbiamo visto il protocollo reale, JSON-RPC 2.0: il messaggio di initialize per stabilire la connessione e negoziare le capabilities, la tools list per scoprire le capacità, tools call per eseguire azioni. E abbiamo visto che questi tre messaggi sono sufficienti, volutamente minimali, perché la semplicità è una feature.

E poi abbiamo visto il flusso end-to-end completo, dalla domanda dell'utente ("Cerca nella knowledge base la configurazione del database") fino alla risposta finale di Claude. Sette step: Model decide, il client costruisce JSON-RPC, Server Esegue, Result Ritorna, Model genera risposta. Ora sapete esattamente cosa succede sotto il cofano quando Claude usa un vostro tool. Niente magia, solo protocollo.

Infine abbiamo visto il lifecycle completo: startup, initialize, ready, processing e shutdown. E due regole fondamentali per la produzione: mai usare stdout per il logging (e se vedete JSON parse il 99% delle volte è un console.log che è sfuggito) e validate sempre gli input.

Prossimi Passi

Passeremo dalla teoria alla pratica. Inizializzeremo il progetto, configureremo TypeScript correttamente e costruiremo il nostro primo server MCP funzionante.

Nel frattempo pensate a questo: che capacità vorreste dare alla vostra AI? Accesso alla vostra knowledge base? Ricerca nel vostro codebase? Accesso ai vostri strumenti interni, come potrebbe essere un Notion di turno? Questo è il vero potenziale di MCP.

Scrivetelo nei commenti, perché sono curioso di vedere cosa vorrete costruire.

Grazie per aver seguito questo primo video. Ora avete le fondamenta, nel prossimo iniziamo a costruire. Ci vediamo nel prossimo video.