Il Model Context Protocol (MCP) è uno standard aperto che consente a modelli come Claude di Anthropic e a strumenti per sviluppatori come Claude Code di chiamare strumenti esterni, fonti di dati e prompt in modo sicuro e standardizzato.
Questa guida ti accompagnerà nella creazione da zero di un tuo server MCP, consentendo a Claude Code di accedere a funzionalità personalizzate e quindi ampliare notevolmente le sue capacità ben oltre quelle integrate.
Che cos’è il Model Context Protocol (MCP)?
MCP (Model Context Protocol) è una specifica aperta progettata per standardizzare il modo in cui i client dei modelli linguistici (come Claude, Claude Code o altri frontend per LLM) si connettono a server di strumenti e a fonti di dati. Pensa a MCP come a una “porta USB‑C per gli LLM”: definisce un trasporto/schema JSON‑RPC e un modo comune per i server di pubblicare tre tipi di capacità:
- Risorse — dati simili a file o documenti che un client può leggere (ad es. una riga di database, un file di testo, un payload JSON).
- Strumenti — funzioni invocabili che il modello può chiedere all’host di eseguire (con approvazione dell’utente).
- Prompt — template di prompt riutilizzabili o flussi di lavoro che il modello/cliente può invocare.
MCP supporta diversi trasporti (stdio, HTTP, SSE) e fornisce schema, SDK ed esempi di server, così non devi inventare tu il wire format. Il protocollo è mantenuto pubblicamente (spec + SDK) e dispone di tutorial e di una galleria di server di esempio per accelerarne l’adozione.
Com’è architetturato MCP?
L’architettura di MCP è intenzionalmente semplice e modulare: i componenti principali sono i server MCP, i client MCP e i trasporti che veicolano messaggi incapsulati JSON‑RPC tra di loro. Di seguito trovi i componenti principali con cui interagirai quando costruisci un server per Claude Code (o altri client MCP).
Server, client e protocollo
- Server MCP — Un servizio che pubblica strumenti, risorse e prompt. Gli strumenti possono produrre effetti collaterali o recuperare dati; le risorse espongono contenuti in sola lettura; i prompt sono template riutilizzabili da cui il client può chiedere al modello di campionare.
- Client MCP (host) — Tipicamente parte dell’host dell’LLM (ad es. Claude Code, plugin per VS Code, un client browser). Scopre i server disponibili, presenta al modello le descrizioni degli strumenti e instrada ai server le chiamate avviate dal modello.
- Protocollo — I messaggi sono codificati come JSON‑RPC; la specifica definisce gli eventi di ciclo di vita, la discovery degli strumenti, l’invocazione, le completion/sampling e come i risultati strutturati vengono riportati al client e al modello.
Pattern di comunicazione (cosa succede quando si usa uno strumento)
- Il client invia il messaggio dell’utente al modello.
- Il modello analizza il contesto e decide di chiamare uno strumento esposto da MCP (o più strumenti).
- Il client inoltra la chiamata allo strumento al server MCP tramite il trasporto scelto.
- Il server esegue lo strumento e restituisce i risultati.
- Il modello riceve l’output dello strumento e compone la risposta finale per l’utente.
Primitivi di implementazione
- I messaggi JSON‑RPC seguono lo schema MCP.
- Le definizioni degli strumenti sono pubblicate nelle risposte di discovery del server, così i client possono presentarle nell’interfaccia.
- Le risorse sono referenziate dai client con la sintassi
@source:path(ad es.@postgres:...), permettendo ai modelli di riferirsi a contenuti esterni senza incorporare grandi quantità di dati nel prompt.
Perché integrare Claude Code con server MCP?
Claude Code è l’offerta di Anthropic focalizzata su flussi di lavoro orientati al codice e agli sviluppatori (integrazione con editor/IDE, comprensione del codice, ecc.). Esporre i tuoi strumenti interni (ricerca nel sorgente, esecuzione del CI, sistema di ticketing, registry privati) tramite server MCP consente a Claude Code di utilizzarli come strumenti di prima classe all’interno delle conversazioni di coding e dei flussi agent.
Integrare Claude Code con server MCP sblocca capacità pratiche e rilevanti per la produzione per un agente di coding:
1. Permettere al modello di agire su sistemi reali
Claude Code può chiedere a un server MCP di interrogare issue tracker, eseguire query sul database, leggere documentazione ampia o creare PR su GitHub — abilita automazioni end‑to‑end direttamente dalla sessione di coding. Questo è esplicitamente supportato dalla documentazione di Claude Code (esempi: query su Postgres, Sentry o creazione di PR).
2. Delegare grandi quantità di dati e logica specializzata
Invece di incorporare ogni sorgente dati nel prompt (consumando token), pubblichi dati e strumenti tramite MCP. Il modello chiama lo strumento, riceve una risposta strutturata e ci ragiona sopra — riduce l’uso di token e consente ai server di gestire lavori pesanti (query DB, letture di file lunghi, autenticazione).
3. Sicurezza e governance
MCP centralizza il controllo degli accessi e l’auditing a livello di server, permettendo alle organizzazioni di inserire nella allowlist i server approvati, controllare quali strumenti sono disponibili e limitare gli output. Claude Code supporta anche la configurazione MCP per aziende e il consenso per ambito.
4. Riutilizzabilità ed ecosistema
I server MCP sono riutilizzabili tra client e team. Costruisci una volta e molti client Claude/LLM possono usare gli stessi servizi (o sostituire le implementazioni).
Cosa ti serve prima di iniziare?
Requisiti minimi
- Una macchina di sviluppo con Python 3.10+ (useremo Python nell’esempio). In alternativa, Node / altri linguaggi sono supportati dagli SDK MCP.
uv(strumento di Astral) o un runner equivalente per eseguire server MCP via stdio (il tutorial MCP usauv). I passaggi di installazione sono mostrati sotto.- Claude Code installato o accesso a un client Claude (desktop o CLI) per registrare e testare il tuo server; oppure qualsiasi client compatibile MCP. Claude Code supporta server HTTP, SSE e stdio locali.
- Nota di sicurezza: Aggiungi a Claude Code solo server MCP di cui ti fidi in contesti di team o enterprise — MCP fornisce ai server accesso a dati sensibili e esistono rischi di prompt injection se un server restituisce contenuti malevoli.
Come installare e verificare la CLI di Claude Code
Questa è la Guida all’installazione e all’uso di Claude Code.
1) Riepilogo rapido — metodi di installazione consigliati
Usa l’installer nativo (consigliato) o Homebrew su macOS/Linux. È disponibile NPM se ti serve un’installazione basata su Node. Per Windows sono disponibili installer PowerShell / CMD. Fonte: documentazione ufficiale di Claude Code e GitHub.
2) Prerequisiti
- macOS 10.15+, Ubuntu 20.04+/Debian 10+ o Windows 10+ (su Windows è consigliato WSL).
- Node.js 18+ richiesto solo per il metodo di installazione via NPM.
3) Comandi di installazione (scegline uno)
Nativo (consigliato — senza dipendenza da Node), macOS / Linux / WSL:
curl -fsSL https://claude.ai/install.sh | bash
# optional: install latest explicitly
curl -fsSL https://claude.ai/install.sh | bash -s latest
# or install a specific version
curl -fsSL https://claude.ai/install.sh | bash -s 1.0.58
Windows PowerShell:
irm https://claude.ai/install.ps1 | iex
# or for latest: & (::Create((irm https://claude.ai/install.ps1))) latest
(Questi sono gli script di installazione nativi ufficiali).
NPM (se vuoi un’installazione globale basata su Node):
# requires Node.js 18+
npm install -g @anthropic-ai/claude-code
Non usare sudo npm install -g — sconsigliato per le installazioni globali con sudo (problemi di permessi/sicurezza). Se incontri errori di permesso, usa nvm o correggi il prefisso globale di npm invece di usare sudo.
4) Verifica che il binario sia installato (controlli di base)
Esegui subito questi comandi in locale dopo l’installazione:
# is the command on PATH?
which claude
# version (or -v)
claude --version
# or
claude -v
# help (sanity check)
claude --help
Atteso: which mostra un percorso (ad es. /usr/local/bin/claude o ~/.nvm/.../bin/claude) e claude --version stampa una stringa in formato semver. La documentazione e il README indicano claude come entrypoint CLI principale.
5) Verifica dello stato dell’installazione e della configurazione (controlli consigliati)
a) claude doctor, esegui:
claude doctor
Questa diagnostica integrata verifica il tipo di installazione, problemi comuni (come permessi npm), dipendenze come ripgrep e suggerisce correzioni. La documentazione raccomanda esplicitamente di eseguire claude doctor dopo l’installazione.
b) Esegui uno smoke test (non interattivo)
Dalla directory del tuo progetto:
cd /path/to/your/project
claude -p "Explain this project in 3 sentences"
Questo usa la modalità print (-p) per inviare un singolo prompt e poi uscire; utile per CI o rapidi check funzionali.
c) Verifica dell’autenticazione (assicurati che la CLI riesca a raggiungere Anthropic)
Claude Code supporta diversi flussi di autenticazione (Console OAuth, API key, integrazioni con provider). Verifiche comuni:
- Se usi una API key (CI / headless / variabile d’ambiente locale):
export ANTHROPIC_API_KEY="sk-..."
# then
claude auth status
claude auth whoami # or `claude auth whoami` / `claude whoami` depending on version
Puoi utilizzare l’API key di CometAPI per usare Claude Code; usare l’API di Claude tramite CometAPI ti offre uno sconto del 20%.
- Se hai usato OAuth tramite la console — esegui:
claude auth status
claude auth whoami
Dovresti vedere le informazioni su account/piano o una conferma dell’avvenuta autenticazione.
Preparazione dell’ambiente passo dopo passo
Di seguito sono riportati passaggi concreti per preparare due stack comuni per sviluppatori (TypeScript e Python), seguiti da rapide verifiche per assicurarsi che tutto funzioni.
H3 — A. Configurazione TypeScript / Node (percorso più rapido)
- Crea il progetto e installa l’SDK:
mkdir mcp-demo && cd mcp-demo
npm init -y
npm install @modelcontextprotocol/sdk express zod
npm install --save-dev typescript tsx @types/node @types/express
- Crea
server.ts. (Forniamo un esempio completo nella sezione “Come creare rapidamente…”.) - Esegui:
npx -y tsx server.ts
- Testa in locale con MCP Inspector o aggiungi a Claude Code:
npx @modelcontextprotocol/inspector
# or (for Claude Code)
claude mcp add --transport http my-server http://localhost:3000/mcp
(I comandi di Inspector e di Claude ti permettono di validare la discovery e invocare gli strumenti.)
Come creare rapidamente un server MCP per Claude Code?
checklist rapida
-
Avvia il tuo server (consigliato Streamable HTTP):
node server.tsoppureuvicorn server:app. -
Dalla tua macchina di sviluppo, puoi:
- Usare MCP Inspector per validare (
npx @modelcontextprotocol/inspector) e confermaretools/listeresources/list; oppure - Aggiungere il server a Claude Code:
claude mcp add --transport http <name> http://<host>:<port>/mcp(o seguire i flussi dell’interfaccia web se il tuo client supporta MCP remoto).
Se prevedi di usare il connettore Messages API di Anthropic per MCP remoto (nessun client separato), leggi la documentazione di Claude — potrebbe essere necessario un header in beta (controlla la documentazione per l’header esatto e lo stato di supporto attuale).
Qui sotto trovi due esempi di server completi ma compatti che puoi copiare, eseguire e collegare a Claude Code (o a MCP Inspector). L’esempio TypeScript usa Express + l’SDK TypeScript; l’esempio Python mostra un mounting con FastAPI.
Nota: il codice seguente segue gli esempi pubblici degli SDK ed è intenzionalmente minimale per chiarezza. In produzione, aggiungi autenticazione, logging, rate limiting e validazione degli input oltre ai default dell’SDK.
Esempio 1: TypeScript + Express (Streamable HTTP)
Crea server.ts (completo):
// server.ts
import express from "express";
import * as z from "zod/v4";
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
const server = new McpServer({ name: "claude-code-demo", version: "0.1.0" });
// Register a simple tool: add two numbers
server.registerTool(
"add",
{
title: "Add",
description: "Add two numbers a and b",
inputSchema: { a: z.number(), b: z.number() },
outputSchema: { result: z.number() }
},
async ({ a, b }) => {
const output = { result: a + b };
return {
content: ,
structuredContent: output
};
}
);
// Register a resource: greet user (dynamic)
server.registerResource(
"greeting",
new ResourceTemplate("greeting://{name}", { list: undefined }),
{ title: "Greeting", description: "Return a greeting for the name" },
async (uri, params) => {
return {
contents:
};
}
);
// Express + Streamable HTTP transport
const app = express();
app.use(express.json());
app.post("/mcp", async (req, res) => {
const transport = new StreamableHTTPServerTransport({ enableJsonResponse: true });
// Close transport when connection closes
res.on("close", () => transport.close());
await server.connect(transport);
await transport.handleRequest(req, res, req.body);
});
const port = parseInt(process.env.PORT || "3000", 10);
app.listen(port, () => console.log(`MCP server listening: http://localhost:${port}/mcp`));
Esegui:
npm install
npx -y tsx server.ts
Poi connetti in Claude Code (esempio):
# Add the remote server to your Claude Code MCP list (local dev)
claude mcp add --transport http my-demo http://localhost:3000/mcp
Esempio adattato dal Quick Start dell’SDK TypeScript ufficiale e mostra come registrare strumenti e risorse, quindi esporli tramite Streamable HTTP.
Esempio 2: Python + FastAPI (FastMCP + Streamable HTTP)
Crea server.py (completo):
# server.py
from fastapi import FastAPI
from mcp.server.fastmcp import FastMCP
app = FastAPI()
mcp = FastMCP("claude-python-demo", stateless_http=True)
# tool: simple sum
@mcp.tool()
def add(a: int, b: int) -> dict:
"""Add two integers"""
return {"result": a + b}
# resource: simple greeting resource template
@mcp.resource("greeting://{name}")
def greeting(name: str):
return {"contents": }
# mount the streamable-http MCP endpoint (FastMCP exposes an ASGI app)
app.mount("/mcp", mcp.streamable_http_app())
# optional endpoint to demonstrate other API routes
@app.get("/")
async def root():
return {"status": "OK"}
Esegui:
uvicorn server:app --reload --port 8000
Connettiti con l’Inspector:
npx @modelcontextprotocol/inspector
# In Inspector select Streamable HTTP and enter http://localhost:8000/mcp
Gli esempi dell’SDK Python e le utility FastMCP rendono semplice registrare @mcp.tool() e @mcp.resource() che l’LLM può scoprire e chiamare.
Come fa concretamente Claude Code a chiamare i tuoi strumenti?
Quando un LLM decide di usare uno strumento, il client invia un’invocazione JSON‑RPC al server MCP. Il server esegue lo strumento richiesto (per esempio, interroga un DB, esegue test o chiama un’API esterna) e restituisce contenuti strutturati e contenuti presentabili. Il client (Claude Code) può quindi includere l’output strutturato nel contesto del modello, così il modello può continuare a ragionarci sopra basandosi su dati affidabili — non solo sull’output testuale del server. L’SDK TypeScript supporta la registrazione di inputSchema e outputSchema (zod) in modo che argomenti e output siano convalidati e tipizzati per le macchine.
Quali strumenti di test e debug dovresti usare?
MCP Inspector
Il MCP Inspector è lo strumento visivo ufficiale per sviluppatori per testare i server MCP. Ti permette di connetterti a un server (stdio, SSE o streamable‑HTTP), elencare gli strumenti, invocarli manualmente e ispezionare il ciclo di vita dei messaggi JSON‑RPC — è prezioso durante lo sviluppo. Avvialo con npx @modelcontextprotocol/inspector.
Test locale vs remoto
- Locale (stdio) — ciclo di iterazione rapido per app desktop e debug offline.
- Streamable HTTP — testa con l’Inspector o connetti a Claude Code usando la
claude mcp addCLI o il connettore MCP nelle Messages API per test remoti. Assicurati di fornire eventuali header di autenticazione richiesti dal tuo server.
Conclusione
MCP è il ponte pratico tra i moderni LLM e i sistemi che detengono davvero i dati ed eseguono le azioni. Per i flussi di lavoro legati al codice, integrare Claude Code con un server MCP offre al modello accesso strutturato e verificabile a repository, CI, issue tracker e strumenti personalizzati — con il risultato di un’automazione più precisa e effetti collaterali più sicuri. Con gli SDK ufficiali in TypeScript e Python, Streamable HTTP per l’hosting remoto e strumenti come MCP Inspector, puoi creare un server minimale in pochi minuti e iterare verso un deployment di produzione.
Gli sviluppatori possono accedere alla Claude Sonnet 4.5 API e alla Claude Opus 4.1 API, ecc. tramite CometAPI; la versione del modello più recente è sempre allineata al sito ufficiale. Per iniziare, esplora le capacità del modello nel Playground e consulta la guida alle API per istruzioni dettagliate. Prima di accedere, assicurati di aver effettuato l’accesso a CometAPI e di aver ottenuto la chiave API. CometAPI offre un prezzo molto inferiore rispetto al prezzo ufficiale per aiutarti nell’integrazione.
Pronti a partire?→ Registrati a CometAPI oggi stesso!
Se vuoi altri consigli, guide e novità sull’AI, seguici su VK, X e Discord!