Come Costruire il Tuo Primo Server MCP: Guida Pratica

Indice

Aggiornato giugno 2026.

TL;DR: MCP (Model Context Protocol) è come dare a Claude accesso strutturato a strumenti e dati esterni — database, file, API — senza sovraccaricare la finestra di contesto. Il server è più semplice di quanto sembri: installa l’SDK, definisci i tuoi strumenti come JSON schema, implementa i handler, connetti via stdio. In meno di 30 minuti Claude può chiamare i tuoi strumenti personalizzati.

[Prospettiva dell’operatore] Collego regolarmente nuovi strumenti ai miei agenti, e MCP è ora la via standard per farlo in modo pulito. Una volta costruito il server, ogni client compatibile — Claude Desktop, Claude Code, qualsiasi app che usa l’SDK Anthropic — può usarlo senza modifiche al codice chiamante. Questo è il valore: costruire una volta, riutilizzare ovunque.

Cos’è davvero MCP

Il Model Context Protocol è un protocollo aperto che standardizza come i modelli AI si connettono al contesto esterno e agli strumenti. Pensalo come uno standard USB-C per le integrazioni AI: prima di esso, ogni app che voleva che Claude leggesse un database o chiamasse un’API doveva inventare la propria soluzione. Dopo di esso, costruisci un server MCP e qualsiasi host conforme può usarlo.

MCP definisce tre cose che un server può offrire:

• Strumenti — funzioni che Claude può chiamare (leggere un file, interrogare un DB, inviare un messaggio Slack)
• Risorse — dati che Claude può leggere (documenti, righe di database, alberi di file)
• Prompt — template di prompt riutilizzabili che l’host può iniettare

Per la maggior parte dei casi d’uso degli operatori, si costruiscono server di strumenti. Risorse e prompt vengono dopo, una volta che le basi funzionano.

L’architettura è client-server, con il client (Claude Desktop, Claude Code, la tua app personalizzata) che controlla tutto. Il server è passivo — ascolta semplicemente le richieste di chiamata strumenti e restituisce risultati.

I tre componenti di ogni server MCP

Ogni server MCP che costruisci ha la stessa struttura:

1. L’oggetto server — dichiara il nome, la versione e le capacità del tuo server (strumenti, risorse, prompt)
2. Definizioni degli strumenti — un elenco di strumenti con nomi, descrizioni e JSON schema per i loro input
3. Handler delle richieste — le funzioni che vengono eseguite quando Claude chiama uno strumento

Tutto qui. Nessun database, nessuno stack HTTP, nessun layer di autenticazione richiesto per iniziare. Il server minimale ha meno di 30 righe di TypeScript.

Prerequisiti (2 minuti)

• Node.js 18+ — verifica con node --version
• TypeScript 5+ (incluso come dipendenza di sviluppo)
• Un client MCP per testare — Claude Desktop è gratuito ed è il modo più semplice per vedere il tuo server funzionare

Non è necessaria una chiave API Anthropic per eseguire un server MCP. La chiave API vive nel client (Claude Desktop), non nel tuo server.

Passo 1: Configurare il progetto (3 minuti)

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk
npm install -D typescript tsx @types/node

Aggiungi a package.json:

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "dev": "tsx src/index.ts"
  }
}

Crea tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./build",
    "strict": true
  },
  "include": ["src/**/*"]
}

Passo 2: Scrivere il server minimale (5 minuti)

Crea src/index.ts:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import {
  CallToolRequestSchema,
  ListToolsRequestSchema,
} from "@modelcontextprotocol/sdk/types.js";

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

// Dichiara quali strumenti offre questo server
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: "get_word_count",
      description: "Conta le parole in un blocco di testo.",
      inputSchema: {
        type: "object",
        properties: {
          text: {
            type: "string",
            description: "Il testo in cui contare le parole",
          },
        },
        required: ["text"],
      },
    },
  ],
}));

// Gestisce le chiamate agli strumenti dal client
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name, arguments: args } = request.params;

  if (name === "get_word_count") {
    const { text } = args as { text: string };
    const count = text.trim().split(/\s+/).filter(Boolean).length;
    return {
      content: [{ type: "text", text: `Conteggio parole: ${count}` }],
    };
  }

  throw new Error(`Strumento sconosciuto: ${name}`);
});

// Connetti via stdio — così Claude Desktop parla con il server
const transport = new StdioServerTransport();
await server.connect(transport);

Questo è il server completo. Registra uno strumento (get_word_count) e lo implementa. La struttura è ciò che conta.

Passo 3: Compilare e registrare in Claude Desktop (5 minuti)

Compila TypeScript:

npm run build

Ora registralo nel file di configurazione di Claude Desktop.

Su macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Su Windows: %APPDATA%\Claude\claude_desktop_config.json

Se il file non esiste, crealo:

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "node",
      "args": ["/percorso/assoluto/a/my-mcp-server/build/index.js"]
    }
  }
}

Usa il percorso assoluto. Riavvia Claude Desktop dopo il salvataggio. Vedrai un’icona a martello (🔨) nell’input del messaggio — significa che Claude ha scoperto i tuoi strumenti.

Passo 4: Costruire uno strumento utile

Il conteggio delle parole è illustrativo. Ecco uno strumento più utile: leggere file da una directory di progetto, che uso per agenti di iniezione di contesto che riassumono codebase, changelog o file di configurazione.

import { readFileSync, readdirSync } from "fs";
import { join, extname } from "path";

const ALLOWED_EXTENSIONS = [".md", ".txt", ".ts", ".json", ".yaml"];
const PROJECT_DIR = process.env.PROJECT_DIR ?? process.cwd();

La logica è la stessa: definisci gli strumenti con JSON schema precisi, implementa gli handler, valida gli input per prevenire il path traversal e restituisci testo al client.

Gli errori che ho fatto (perché tu non li faccia)

Il percorso deve essere assoluto. I percorsi relativi nella config di Claude Desktop non si risolvono come ci si aspetta. Usa sempre il percorso completo /home/utente/....

Stdio significa nessun console.log nel tuo server. Claude Desktop comunica con il tuo server via stdin/stdout. Un console.log di debug corrompe lo stream JSON-RPC. Logga su stderr:

process.stderr.write(`Debug: ${message}\n`);

Riavvia Claude Desktop dopo ogni modifica alla config. I server MCP vengono caricati all’avvio. Un file di config modificato non fa nulla finché non chiudi e riapri l’app.

Le descrizioni degli strumenti sono il prodotto. Claude decide se chiamare il tuo strumento in base al campo description. Una descrizione vaga significa che Claude non saprà quando usarlo. Una precisa significa che Claude la usa al momento giusto. Investi più tempo nelle descrizioni che nell’implementazione.

Come uso i server MCP in produzione

Il pattern stdio funziona benissimo per Claude Desktop e Claude Code (locale). Per gli agenti in produzione — i 30+ che eseguo su Cloudflare Workers — uso direttamente l’API tool-use dell’SDK Anthropic, perché ho bisogno della flessibilità di instradare verso Haiku vs Sonnet per ogni passo.

I pattern che uso davvero in produzione:

1. Tooling di sviluppo locale — server MCP per Claude Code che espongono strumenti specifici del progetto
2. Iniezione di contesto — server MCP che precaricano doc rilevanti senza copiare manualmente
3. Bridge prototipo-to-API — costruisco prima MCP (più veloce da iterare), poi migro la logica all’SDK tool-use per la produzione

Cosa costruire dopo

Una volta compresa la struttura del server, gli strumenti utili sono quelli che accedono al contesto esterno di Claude:

• Lettore di database — esegue una query SQL in sola lettura e restituisce risultati come JSON
• Lettore Slack — recupera gli ultimi N messaggi da un canale
• Lettore GitHub — elenca le PR aperte, legge un file a un commit specifico
• Wrapper API interna — chiama la tua API REST con gli header di autenticazione integrati

FAQ

Ho bisogno di una chiave API Anthropic per costruire un server MCP?

No. Il tuo server MCP non chiama l’API Anthropic. Risponde semplicemente alle richieste di chiamata degli strumenti dal client. La chiave API vive nel client, non nel server.

Il mio server MCP può chiamare API esterne?

Sì — l’handler è solo codice TypeScript asincrono. Recupera un’API meteo, interroga un database, scrivi su un file. Al server non importa cosa fa l’handler internamente.

Qual è la differenza tra i trasporti stdio e HTTP?

Stdio è per server locali — stessa macchina di Claude Desktop o Claude Code. HTTP con SSE è per server remoti che puoi distribuire come servizio web. Inizia con stdio; è più semplice da debuggare.

Come fa Claude a sapere quando chiamare il mio strumento?

Claude decide in base al campo description dello strumento e al contesto della conversazione. Se Claude continua a ignorare il tuo strumento, raffina la descrizione.