1~
2Il **Model Context Protocol (MCP)** è uno standard aperto creato da Anthropic che definisce come i modelli AI comunicano con strumenti esterni, fonti di dati e servizi. Pensalo come l'"USB-C dell'AI"  -  un connettore universale che consente a qualsiasi agente AI di comunicare con qualsiasi strumento attraverso un'interfaccia standardizzata.
3~
4Dal suo lancio, MCP ha superato i **97 milioni di download mensili dell'SDK** ed è stato adottato da tutti i principali fornitori di AI: Anthropic, OpenAI, Google, Microsoft e Amazon. In questa guida, esploreremo tutto ciò che devi sapere per costruire con MCP.
5~
6## Perché MCP Esiste
7~
8Prima di MCP, ogni applicazione AI doveva costruire integrazioni personalizzate per ogni strumento che voleva utilizzare. Vuoi che la tua AI legga file? Scrivi codice personalizzato. Interrogare un database? Altro codice personalizzato. Pubblicare su Slack? Ancora un'altra integrazione.
9~
10Questo creava un **problema N×M**: N applicazioni AI, ciascuna con M integrazioni personalizzate necessarie, portando a sforzi duplicati ed ecosistemi frammentati.
11~
12```mermaid
13graph TD
14    subgraph "Before MCP (N×M)"
15        A1[AI App 1] --> T1[GitHub Integration]
16        A1 --> T2[Slack Integration]
17        A1 --> T3[DB Integration]
18        A2[AI App 2] --> T4[GitHub Integration]
19        A2 --> T5[Slack Integration]
20        A2 --> T6[DB Integration]
21    end
22```
23~
24MCP risolve questo con un **singolo protocollo** che qualsiasi client AI può utilizzare per comunicare con qualsiasi server MCP:
25~
26```mermaid
27graph TD
28    subgraph "With MCP (N+M)"
29        A1[AI App 1] --> MCP[MCP Protocol]
30        A2[AI App 2] --> MCP
31        MCP --> S1[GitHub Server]
32        MCP --> S2[Slack Server]
33        MCP --> S3[DB Server]
34    end
35```
36~
37## Concetti Fondamentali
38~
39MCP ha tre primitive fondamentali:
40~
41### 1. Strumenti (Tools)
42Gli strumenti sono funzioni che l'AI può chiamare. Rappresentano azioni come "crea un file", "interroga un database" o "invia un messaggio". Ogni strumento ha un nome, una descrizione e un JSON Schema per i suoi parametri.
43~
44```typescript
45{
46  name: "create_issue",
47  description: "Create a new GitHub issue",
48  inputSchema: {
49    type: "object",
50    properties: {
51      title: { type: "string", description: "Issue title" },
52      body: { type: "string", description: "Issue body" },
53      repo: { type: "string", description: "Repository name" }
54    },
55    required: ["title", "repo"]
56  }
57}
58```
59~
60### 2. Risorse (Resources)
61Le risorse sono dati che l'AI può leggere. Rappresentano file, record di database, risposte API o qualsiasi altra fonte di dati. Le risorse sono identificate tramite URI.
62~
63```typescript
64{
65  uri: "file:///Users/dev/project/README.md",
66  name: "Project README",
67  mimeType: "text/markdown"
68}
69```
70~
71### 3. Prompt (Prompts)
72I prompt sono template riutilizzabili che aiutano a strutturare le interazioni. Possono includere parametri dinamici e sono utili per standardizzare i flussi di lavoro comuni.
73~
74```typescript
75{
76  name: "code_review",
77  description: "Review code changes for quality and security",
78  arguments: [
79    { name: "diff", description: "The code diff to review", required: true }
80  ]
81}
82```
83~
84## Architettura
85~
86MCP segue un'architettura client-server:
87~
88```mermaid
89graph LR
90    subgraph "Host Application"
91        Client[MCP Client]
92    end
93~
94    subgraph "MCP Server"
95        Server[Server Process]
96        Server --> Tools[Tools]
97        Server --> Resources[Resources]
98        Server --> Prompts[Prompts]
99    end
100~
101    Client -- "JSON-RPC 2.0\n(stdio or SSE)" --> Server
102```
103~
104- **Host**: L'applicazione AI (Claude Desktop, Cursor, la tua app personalizzata)
105- **Client**: Mantiene una connessione 1:1 con un server MCP
106- **Server**: Espone strumenti, risorse e prompt al client
107- **Transport**: La comunicazione avviene tramite JSON-RPC 2.0 su stdio (locale) o Server-Sent Events (remoto)
108~
109## Costruire un Server MCP
110~
111Costruiamo un server MCP pratico che interagisce con una lista di attività memorizzata in un file JSON.
112~
113### Configurazione Iniziale
114~
115```bash
116mkdir mcp-todo-server && cd mcp-todo-server
117npm init -y
118npm install @modelcontextprotocol/sdk zod
119```
120~
121### Implementazione del Server
122~
123```typescript
124// src/index.ts
125import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
126import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
127import { z } from "zod";
128import fs from "fs";
129~
130const TODO_FILE = "./todos.json";
131~
132function readTodos(): { id: number; text: string; done: boolean }[] {
133  if (!fs.existsSync(TODO_FILE)) return [];
134  return JSON.parse(fs.readFileSync(TODO_FILE, "utf-8"));
135}
136~
137function writeTodos(todos: { id: number; text: string; done: boolean }[]) {
138  fs.writeFileSync(TODO_FILE, JSON.stringify(todos, null, 2));
139}
140~
141const server = new McpServer({
142  name: "todo-server",
143  version: "1.0.0",
144});
145~
146// Tool: Add a todo
147server.tool(
148  "add_todo",
149  "Add a new todo item",
150  { text: z.string().describe("The todo text") },
151  async ({ text }) => {
152    const todos = readTodos();
153    const newTodo = { id: Date.now(), text, done: false };
154    todos.push(newTodo);
155    writeTodos(todos);
156    return { content: [{ type: "text", text: `Added: "${text}"` }] };
157  }
158);
159~
160// Tool: List todos
161server.tool(
162  "list_todos",
163  "List all todo items",
164  {},
165  async () => {
166    const todos = readTodos();
167    const list = todos
168      .map((t) => `${t.done ? "✅" : "⬜"} [${t.id}] ${t.text}`)
169      .join("\n");
170    return { content: [{ type: "text", text: list || "No todos yet." }] };
171  }
172);
173~
174// Tool: Complete a todo
175server.tool(
176  "complete_todo",
177  "Mark a todo as completed",
178  { id: z.number().describe("The todo ID to complete") },
179  async ({ id }) => {
180    const todos = readTodos();
181    const todo = todos.find((t) => t.id === id);
182    if (!todo) return { content: [{ type: "text", text: "Todo not found." }] };
183    todo.done = true;
184    writeTodos(todos);
185    return { content: [{ type: "text", text: `Completed: "${todo.text}"` }] };
186  }
187);
188~
189// Resource: Current todos as a readable resource
190server.resource(
191  "todos://list",
192  "Current todo list",
193  async () => ({
194    contents: [{
195      uri: "todos://list",
196      mimeType: "application/json",
197      text: JSON.stringify(readTodos(), null, 2),
198    }],
199  })
200);
201~
202// Start the server
203const transport = new StdioServerTransport();
204await server.connect(transport);
205```
206~
207### Configurazione
208~
209Per utilizzare questo server con Claude Desktop, aggiungilo alla tua configurazione:
210~
211```json
212{
213  "mcpServers": {
214    "todo": {
215      "command": "npx",
216      "args": ["tsx", "/path/to/mcp-todo-server/src/index.ts"]
217    }
218  }
219}
220```
221~
222## Costruire un Client MCP
223~
224Puoi anche costruire un client personalizzato che si connette a qualsiasi server MCP:
225~
226```typescript
227import { Client } from "@modelcontextprotocol/sdk/client/index.js";
228import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
229~
230const transport = new StdioClientTransport({
231  command: "npx",
232  args: ["tsx", "./src/index.ts"],
233});
234~
235const client = new Client({ name: "my-client", version: "1.0.0" });
236await client.connect(transport);
237~
238// List available tools
239const { tools } = await client.listTools();
240console.log("Available tools:", tools.map((t) => t.name));
241~
242// Call a tool
243const result = await client.callTool({
244  name: "add_todo",
245  arguments: { text: "Write MCP blog post" },
246});
247console.log(result);
248```
249~
250## Server MCP Popolari
251~
252L'ecosistema MCP è cresciuto rapidamente. Ecco alcuni dei server più popolari:
253~
254| Server | Descrizione | Caso d'Uso |
255|--------|-------------|------------|
256| **GitHub** | Crea issue, PR, gestisci repository | Flussi di lavoro di sviluppo |
257| **Slack** | Invia messaggi, gestisci canali | Comunicazione del team |
258| **PostgreSQL** | Interroga e gestisci database | Accesso ai dati |
259| **Filesystem** | Leggi, scrivi e cerca file | Sviluppo locale |
260| **Puppeteer** | Automazione browser e scraping | Test web |
261| **Sentry** | Monitoraggio errori e debug | Supporto in produzione |
262| **Supabase** | Database, autenticazione, storage | Operazioni backend |
263~
264## MCP vs A2A (Agent-to-Agent)
265~
266Mentre MCP gestisce la comunicazione **agente-strumento**, il protocollo **A2A (Agent-to-Agent)** di Google gestisce la comunicazione **agente-agente**. Sono complementari:
267~
268```mermaid
269graph TD
270    Agent1[Agent 1] -- "A2A Protocol" --> Agent2[Agent 2]
271    Agent1 -- "MCP Protocol" --> Tool1[GitHub MCP Server]
272    Agent2 -- "MCP Protocol" --> Tool2[Database MCP Server]
273```
274~
275- **MCP**: Come un agente AI utilizza gli strumenti (integrazione verticale)
276- **A2A**: Come gli agenti AI collaborano tra loro (integrazione orizzontale)
277~
278## Buone Pratiche
279~
2801. **Mantieni i server focalizzati**: Un server per dominio (server GitHub, server Slack, ecc.). Non costruire server monolitici.
2812. **Valida gli input con Zod**: Valida sempre gli input degli strumenti con schemi appropriati.
2823. **Gestisci gli errori con grazia**: Restituisci messaggi di errore significativi, non stack trace.
2834. **Usa le risorse per dati in sola lettura**: Se l'AI ha solo bisogno di leggere dati, esponili come risorsa piuttosto che come strumento.
2845. **Aggiungi descrizioni appropriate**: Buone descrizioni degli strumenti e dei parametri aiutano l'AI a capire quando e come usare ogni strumento.
2856. **Testa con l'MCP Inspector**: Usa `npx @modelcontextprotocol/inspector` per testare il tuo server in modo interattivo.
286~
287## Per Iniziare
288~
289```bash
290# Create a new MCP server from template
291npx @modelcontextprotocol/create-server my-server
292~
293# Test with the MCP Inspector
294npx @modelcontextprotocol/inspector npx tsx ./src/index.ts
295```
296~
297## Conclusione
298~
299MCP è diventato lo standard de facto per l'uso degli strumenti AI nel 2026. Che tu stia costruendo agenti AI personalizzati, estendendo Claude Code o creando integrazioni per piattaforme esistenti, comprendere MCP è essenziale. Il protocollo è abbastanza semplice da imparare in un pomeriggio ma abbastanza potente per costruire flussi di lavoro AI di livello produttivo.
300~
301**Prossimi passi:**
302- Esplora la [Specifica MCP](https://spec.modelcontextprotocol.io/)
303- Sfoglia i [server MCP esistenti](https://github.com/modelcontextprotocol/servers) per ispirazione
304- Costruisci il tuo primo server con l'SDK TypeScript o Python
305- Testalo con Claude Desktop o l'MCP Inspector
306~