MCP (Model Context Protocol): La Guida Completa per Sviluppatori

Il 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.

Dal 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.

Perché MCP Esiste

Prima 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.

Questo creava un problema N×M: N applicazioni AI, ciascuna con M integrazioni personalizzate necessarie, portando a sforzi duplicati ed ecosistemi frammentati.

MCP risolve questo con un singolo protocollo che qualsiasi client AI può utilizzare per comunicare con qualsiasi server MCP:

Concetti Fondamentali

MCP ha tre primitive fondamentali:

1. Strumenti (Tools)

Gli 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.

{
  name: "create_issue",
  description: "Create a new GitHub issue",
  inputSchema: {
    type: "object",
    properties: {
      title: { type: "string", description: "Issue title" },
      body: { type: "string", description: "Issue body" },
      repo: { type: "string", description: "Repository name" }
    },
    required: ["title", "repo"]
  }
}

2. Risorse (Resources)

Le 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.

{
  uri: "file:///Users/dev/project/README.md",
  name: "Project README",
  mimeType: "text/markdown"
}

3. Prompt (Prompts)

I prompt sono template riutilizzabili che aiutano a strutturare le interazioni. Possono includere parametri dinamici e sono utili per standardizzare i flussi di lavoro comuni.

{
  name: "code_review",
  description: "Review code changes for quality and security",
  arguments: [
    { name: "diff", description: "The code diff to review", required: true }
  ]
}

Architettura

MCP segue un'architettura client-server:

• Host: L'applicazione AI (Claude Desktop, Cursor, la tua app personalizzata)
• Client: Mantiene una connessione 1:1 con un server MCP
• Server: Espone strumenti, risorse e prompt al client
• Transport: La comunicazione avviene tramite JSON-RPC 2.0 su stdio (locale) o Server-Sent Events (remoto)

Costruire un Server MCP

Costruiamo un server MCP pratico che interagisce con una lista di attività memorizzata in un file JSON.

Configurazione Iniziale

mkdir mcp-todo-server && cd mcp-todo-server
npm init -y
npm install @modelcontextprotocol/sdk zod

Implementazione del Server

// src/index.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import fs from "fs";

const TODO_FILE = "./todos.json";

function readTodos(): { id: number; text: string; done: boolean }[] {
  if (!fs.existsSync(TODO_FILE)) return [];
  return JSON.parse(fs.readFileSync(TODO_FILE, "utf-8"));
}

function writeTodos(todos: { id: number; text: string; done: boolean }[]) {
  fs.writeFileSync(TODO_FILE, JSON.stringify(todos, null, 2));
}

const server = new McpServer({
  name: "todo-server",
  version: "1.0.0",
});

// Tool: Add a todo
server.tool(
  "add_todo",
  "Add a new todo item",
  { text: z.string().describe("The todo text") },
  async ({ text }) => {
    const todos = readTodos();
    const newTodo = { id: Date.now(), text, done: false };
    todos.push(newTodo);
    writeTodos(todos);
    return { content: [{ type: "text", text: `Added: "${text}"` }] };
  }
);

// Tool: List todos
server.tool(
  "list_todos",
  "List all todo items",
  {},
  async () => {
    const todos = readTodos();
    const list = todos
      .map((t) => `${t.done ? "✅" : "⬜"} [${t.id}] ${t.text}`)
      .join("\n");
    return { content: [{ type: "text", text: list || "No todos yet." }] };
  }
);

// Tool: Complete a todo
server.tool(
  "complete_todo",
  "Mark a todo as completed",
  { id: z.number().describe("The todo ID to complete") },
  async ({ id }) => {
    const todos = readTodos();
    const todo = todos.find((t) => t.id === id);
    if (!todo) return { content: [{ type: "text", text: "Todo not found." }] };
    todo.done = true;
    writeTodos(todos);
    return { content: [{ type: "text", text: `Completed: "${todo.text}"` }] };
  }
);

// Resource: Current todos as a readable resource
server.resource(
  "todos://list",
  "Current todo list",
  async () => ({
    contents: [{
      uri: "todos://list",
      mimeType: "application/json",
      text: JSON.stringify(readTodos(), null, 2),
    }],
  })
);

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

Configurazione

Per utilizzare questo server con Claude Desktop, aggiungilo alla tua configurazione:

{
  "mcpServers": {
    "todo": {
      "command": "npx",
      "args": ["tsx", "/path/to/mcp-todo-server/src/index.ts"]
    }
  }
}

Costruire un Client MCP

Puoi anche costruire un client personalizzato che si connette a qualsiasi server MCP:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["tsx", "./src/index.ts"],
});

const client = new Client({ name: "my-client", version: "1.0.0" });
await client.connect(transport);

// List available tools
const { tools } = await client.listTools();
console.log("Available tools:", tools.map((t) => t.name));

// Call a tool
const result = await client.callTool({
  name: "add_todo",
  arguments: { text: "Write MCP blog post" },
});
console.log(result);

Server MCP Popolari

L'ecosistema MCP è cresciuto rapidamente. Ecco alcuni dei server più popolari:

MCP vs A2A (Agent-to-Agent)

Mentre MCP gestisce la comunicazione agente-strumento, il protocollo A2A (Agent-to-Agent) di Google gestisce la comunicazione agente-agente. Sono complementari:

• MCP: Come un agente AI utilizza gli strumenti (integrazione verticale)
• A2A: Come gli agenti AI collaborano tra loro (integrazione orizzontale)

Buone Pratiche

1. Mantieni i server focalizzati: Un server per dominio (server GitHub, server Slack, ecc.). Non costruire server monolitici.
2. Valida gli input con Zod: Valida sempre gli input degli strumenti con schemi appropriati.
3. Gestisci gli errori con grazia: Restituisci messaggi di errore significativi, non stack trace.
4. Usa le risorse per dati in sola lettura: Se l'AI ha solo bisogno di leggere dati, esponili come risorsa piuttosto che come strumento.
5. Aggiungi descrizioni appropriate: Buone descrizioni degli strumenti e dei parametri aiutano l'AI a capire quando e come usare ogni strumento.
6. Testa con l'MCP Inspector: Usa npx @modelcontextprotocol/inspector per testare il tuo server in modo interattivo.

Per Iniziare

# Create a new MCP server from template
npx @modelcontextprotocol/create-server my-server

# Test with the MCP Inspector
npx @modelcontextprotocol/inspector npx tsx ./src/index.ts

Conclusione

MCP è 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.

Prossimi passi:

• Esplora la Specifica MCP
• Sfoglia i server MCP esistenti per ispirazione
• Costruisci il tuo primo server con l'SDK TypeScript o Python
• Testalo con Claude Desktop o l'MCP Inspector