Come creare un server MCP: tutorial passo passo in Python e TypeScript (2026)

Puoi creare un server MCP che Claude chiama davvero in circa 15 minuti. L'abbiamo cronometrato su Node 20 e Python 3.11: uno strumento add funzionante, in esecuzione su stdio e rilevato da Claude Desktop, ha richiesto 14 minuti la prima volta e meno di 5 una volta nota la struttura. Questo tutorial costruisce lo stesso server due volte, una in Python con FastMCP 2.x e una in TypeScript con @modelcontextprotocol/sdk 1.x, così puoi scegliere il tuo stack e copiare codice reale. Se vuoi prima l'architettura e la teoria del protocollo, la nostra guida al Model Context Protocol la copre; qui costruiamo e basta.

Server MCP, avvio rapido: cosa costruirai

Un server MCP è un piccolo programma che espone strumenti, dati e modelli di prompt a client IA come Claude, Cursor o VS Code tramite il Model Context Protocol. Scrivi il server una volta e qualsiasi client compatibile con MCP può chiamarlo. In questo tutorial costruisci un server con due strumenti (un calcolatore add e un helper fetch_url), lo esegui localmente su stdio, lo testi e lo colleghi a un client reale.

Ecco tutto ciò che ti serve prima di iniziare.

Entrambe le vie producono un server dal comportamento identico. Scegli il linguaggio con cui il tuo team già lavora. Se non hai preferenze, inizia con Python, perché FastMCP rende il primo server più breve.

Cosa espone davvero un server MCP?

Prima di scrivere codice, aiuta sapere quali tre cose un server può offrire. Un server MCP espone strumenti (funzioni che il modello può chiamare, come "interroga il database"), risorse (dati in sola lettura che il modello può caricare, come un file o un record) e prompt (modelli di prompt riutilizzabili). La maggior parte dei server che costruirai sarà incentrata sugli strumenti; risorse e prompt sono opzionali.

Server MCP, definito: un processo che parla il Model Context Protocol e annuncia un elenco di strumenti, risorse e prompt che un client IA può scoprire e invocare a runtime.

Il client (Claude Desktop, ad esempio) agisce come host. Avvia il tuo server o vi si connette, chiede "quali strumenti hai?" e poi li chiama quando il modello decide che uno strumento è utile. Non chiami mai il modello da dentro il server. Il flusso va nell'altra direzione.

Quella direzione conta. Il tuo server è un fornitore passivo. Aspetta che il client si connetta, risponde alla richiesta di scoperta ed esegue lo strumento chiamato. Tieni a mente questo modello mentale e il resto del tutorial torna da solo.

Come creare un server MCP in Python (passo passo)

Python è la via più rapida a un server funzionante, perché FastMCP gestisce l'impianto del protocollo e trasforma semplici funzioni in strumenti con un decoratore. Tutto ciò che segue usa l'SDK Python ufficiale. Ecco i quattro passaggi.

Passo 1: configurare il progetto. Usa uv, ormai lo standard per i progetti MCP in Python:

uv init mcp-demo
cd mcp-demo
uv add "mcp[cli]"

Se preferisci pip: python -m venv .venv && source .venv/bin/activate && pip install "mcp[cli]".

Passo 2: scrivere il server. Crea server.py:

from mcp.server.fastmcp import FastMCP
import httpx

# Name shows up in the client's tool list
mcp = FastMCP("demo-server")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers and return the sum."""
    return a + b

@mcp.tool()
async def fetch_url(url: str) -> str:
    """Fetch a URL and return the first 2000 characters of the body."""
    async with httpx.AsyncClient(timeout=10) as client:
        resp = await client.get(url)
        return resp.text[:2000]

if __name__ == "__main__":
    mcp.run()  # defaults to stdio transport

Due cose da notare. La docstring diventa la descrizione dello strumento che il modello legge, quindi scrivila come un'istruzione. E i type hint (a: int) diventano automaticamente lo schema di input, così FastMCP genera lo schema JSON al posto tuo.

Passo 3: eseguirlo. mcp.run() avvia il server su stdio, il trasporto che i client lanciano localmente. Non lo esegui direttamente durante lo sviluppo; lo lancia il client. Per un test rapido usa il runner di sviluppo:

uv run mcp dev server.py

Passo 4: restituire un output pulito. Un tranello che vale la pena segnalare già ora: restituisci una stringa o un valore tipizzato, non un dict annidato sperando che venga reso. Ci torneremo nella sezione produzione, ma in breve i tipi di ritorno ambigui possono essere troncati silenziosamente in alcuni client.

Questo è un server MCP Python completo. Due strumenti, chiamate di rete reali, schema automatico. Poi la stessa cosa in TypeScript.

Come creare un server MCP in TypeScript (passo passo)

La via TypeScript usa direttamente l'SDK TypeScript ufficiale e zod per la validazione dell'input. È un po' più verbosa di FastMCP, ma i tipi sono eccellenti e si distribuisce in modo pulito su host Node.

Passo 1: configurare il progetto.

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

Passo 2: scrivere il server. Crea server.ts:

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

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

server.tool(
  "add",
  "Add two numbers and return the sum.",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  }),
);

server.tool(
  "fetch_url",
  "Fetch a URL and return the first 2000 characters.",
  { url: z.string().url() },
  async ({ url }) => {
    const resp = await fetch(url);
    const body = await resp.text();
    return { content: [{ type: "text", text: body.slice(0, 2000) }] };
  },
);

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

Passo 3: eseguirlo. Durante lo sviluppo: npx tsx server.ts. Per la produzione, compila con tsc ed esegui il .js generato con Node. Nota la forma di ritorno: ogni strumento restituisce { content: [{ type: "text", text: ... }] }. Questo array content esplicito è l'equivalente TypeScript della regola "restituisci una stringa pulita" di Python. L'SDK vuole blocchi di contenuto tipizzati, non oggetti grezzi.

Passo 4: validare l'input con zod. Lo schema z.string().url() rifiuta input non validi prima che il tuo handler venga eseguito, che è esattamente ciò che vuoi quando un modello genera gli argomenti.

Gli stessi due strumenti, lo stesso comportamento, TypeScript idiomatico. Decidiamo ora come i client devono raggiungere il tuo server.

stdio vs Streamable HTTP: quale trasporto usare?

I server MCP comunicano tramite uno di due trasporti. stdio esegue il server come sottoprocesso locale che il client avvia e con cui comunica tramite input/output standard. Streamable HTTP esegue il server come servizio di rete a cui i client si connettono via HTTP. Scegli in base a dove deve vivere il server.

La regola pratica: costruisci e testa su stdio, passa a Streamable HTTP solo quando più di una persona o macchina ha bisogno del server. La maggior parte dei server non deve mai lasciare stdio. Le chiamate mcp.run() e StdioServerTransport() qui sopra sono già stdio, quindi sei pronto per lo sviluppo.

Come testare il tuo server MCP con l'Inspector

Prima di integrare il tuo server in Claude, testalo in isolamento con il MCP Inspector. È un'interfaccia browser che si connette al tuo server, ne elenca gli strumenti e ti permette di chiamarli a mano. Eseguilo contro il tuo server:

# Python
npx @modelcontextprotocol/inspector uv run server.py
# TypeScript
npx @modelcontextprotocol/inspector npx tsx server.ts

L'Inspector apre una pagina locale dove vedi i tuoi strumenti add e fetch_url, lanci una chiamata di test e leggi la risposta grezza. È l'abitudine migliore per lo sviluppo MCP. Se lo schema di uno strumento è malformato o un valore di ritorno è sbagliato, lo vedi qui in pochi secondi invece di fissare un fallimento silenzioso dentro Claude. Così abbiamo intercettato uno schema di input errato che altrimenti ci sarebbe costato un giro completo di debug attraverso il client. Testa prima nell'Inspector, sempre.

Come collegare il tuo server MCP a Claude Desktop, Claude Code e Cursor

Una volta che l'Inspector è soddisfatto, punta un client reale al tuo server. Ogni client legge un file di configurazione che gli dice come avviare il tuo server su stdio.

Claude Desktop. Modifica claude_desktop_config.json (su macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "demo-server": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/mcp-demo", "run", "server.py"]
    }
  }
}

Riavvia Claude Desktop e i tuoi strumenti appaiono sotto l'icona dei connettori.

Claude Code. Aggiungi il server con un comando dal tuo progetto: claude mcp add demo-server -- uv run server.py. Claude Code lo memorizza nella configurazione del progetto e lo carica all'avvio. Se usi anche gli hook per programmare Claude Code, la nostra guida agli hook di Claude Code si sposa bene con strumenti MCP personalizzati.

Cursor. Aggiungi lo stesso blocco mcpServers a .cursor/mcp.json nella radice del progetto. La forma corrisponde a quella di Claude Desktop. Per un esempio reale di server MCP in esecuzione dentro Claude Code, guarda come abbiamo collegato Higgsfield in Claude Code.

Usa percorsi assoluti in ogni configurazione. I percorsi relativi sono il motivo più comune per cui un server non si avvia.

Distribuire un server MCP in produzione (auth e hosting)

Quando il tuo server deve essere condiviso, spostalo da stdio a Streamable HTTP e aggiungi tre cose: autenticazione, gestione degli errori e un host.

• Autenticazione. I server MCP remoti devono usare OAuth 2.1 secondo la specifica di autorizzazione MCP. Per strumenti interni, un controllo del token bearer sull'endpoint HTTP è il minimo pragmatico. Non distribuire mai un server di strumenti pubblico e non autenticato, perché uno strumento che esegue SQL o colpisce API interne è una superficie d'attacco attiva.
• Gestione degli errori. Avvolgi i corpi degli strumenti con try/except (o try/catch) e restituisci un messaggio di errore tipizzato invece di sollevare un'eccezione. Il modello gestisce "la query è fallita, ecco perché" molto meglio di una connessione interrotta.
• Hosting. Qualsiasi piattaforma che esegue un processo Node o Python di lunga durata va bene: un piccolo VPS, Fly.io, Railway o un container sulla tua infrastruttura. Mantieni il processo caldo, perché gli avvii a freddo aggiungono latenza alla prima chiamata di strumento.
• Concorrenza e costo. Se i tuoi strumenti chiamano un LLM o un'API a pagamento a valle, metti un gateway davanti. La nostra panoramica degli strumenti gateway LLM copre rate-limiting e fallback, e gli strumenti di context engineering aiutano a evitare che l'output degli strumenti gonfi la finestra di contesto del modello.

Per Python, cambia la chiamata run in mcp.run(transport="streamable-http"); per TypeScript, sostituisci StdioServerTransport con lo StreamableHTTPServerTransport dell'SDK. Le definizioni degli strumenti non cambiano affatto. È questo il senso dell'astrazione del trasporto.

Cosa abbiamo imparato distribuendo server MCP in produzione

In Techsy abbiamo costruito server MCP per uso interno, e alcune lezioni emergono solo quando del traffico reale li colpisce. Ecco cosa abbiamo misurato e dove ci siamo scottati.

Il primo server che abbiamo distribuito era uno strumento di query Postgres in sola lettura, costruito con FastMCP 2.x sull'SDK Python mcp 1.x, poi riscritto in @modelcontextprotocol/sdk 1.x per confronto. Su uno stack del 2026 (Node 20, Python 3.11), le chiamate di strumento locali su stdio aggiungevano circa 8-12 ms di overhead di trasporto per chiamata. Spostando lo stesso server su Streamable HTTP su un VPS, il costo per chiamata è salito a 40-70 ms, quasi interamente andata e ritorno di rete invece che costo di protocollo. L'avvio a freddo di FastMCP era di circa 300 ms per il processo, motivo per cui teniamo caldo il processo di produzione.

Il tranello che ci è costato circa due ore: uno strumento che restituiva un dict Python grezzo veniva reso bene nell'Inspector ma tornava troncato dentro Claude Desktop. Avvolgere il valore di ritorno come stringa di testo tipizzata lo ha risolto all'istante. Per questo il tutorial restituisce ovunque stringhe e blocchi di testo content invece di oggetti annidati. L'altra abitudine che ha pagato subito è stata far passare ogni server da npx @modelcontextprotocol/inspector prima di toccare una configurazione del client, cosa che ha fatto emergere uno schema di input malformato nella riscrittura TypeScript che altrimenti sarebbe fallito silenziosamente in Cursor.

Se stai scegliendo quali strumenti integrare nei server in primo luogo, il nostro elenco dei migliori server MCP del 2026 è una buona banca di idee.

Come Techsy affronta lo sviluppo MCP

In Techsy costruiamo server MCP come parte dei sistemi di agenti IA che consegniamo ai clienti, collegando gli agenti a database interni, CRM e API tramite uno strato di strumenti tipizzato. Il nostro approccio è iniziare in piccolo (uno strumento ben testato su stdio), validarlo nell'Inspector e poi promuoverlo a servizio HTTP autenticato solo quando più di un agente ne ha bisogno. Abbiniamo server personalizzati al Claude Agent SDK quando la logica dell'agente si fa complessa.

Ecco la versione onesta: la maggior parte dei team sovradimensiona il primo server. Raramente servono HTTP, OAuth e una dozzina di strumenti il primo giorno. Se vuoi un secondo paio di occhi su un'integrazione MCP, richiedi una consulenza gratuita e ti diremo se è un lavoro stdio a singolo strumento o qualcosa che ha davvero bisogno di infrastruttura.

Domande frequenti

Devo creare il mio server MCP in Python o TypeScript?

Usa il linguaggio con cui il tuo team già lavora. Python con FastMCP è la via più breve a un primo server funzionante, perché un decoratore trasforma una funzione in uno strumento. TypeScript con l'SDK ufficiale è un po' più verboso ma ti dà tipi eccellenti e si distribuisce in modo pulito su host Node. Entrambi producono server dal comportamento identico per il client.

Mi serve un framework come FastMCP per creare un server MCP?

No, ma aiuta. FastMCP è incluso nell'SDK Python mcp ufficiale e rimuove la maggior parte del boilerplate di protocollo. Puoi usare l'API Server di più basso livello per un controllo fine, ma per quasi ogni server FastMCP (Python) o McpServer (TypeScript) è lo strumento giusto e molto meno codice.

Come faccio il debug di un server MCP che non funziona?

Fallo passare prima dal MCP Inspector: npx @modelcontextprotocol/inspector seguito dal tuo comando di esecuzione. L'Inspector elenca i tuoi strumenti e ti permette di chiamarli direttamente, così puoi confermare che il server funziona prima di incolpare il client. Se l'Inspector va bene ma il client no, controlla che la configurazione usi percorsi assoluti e di aver riavviato il client.

FastMCP è parte ufficiale di MCP?

Sì. FastMCP è incluso nell'SDK Python ufficiale del Model Context Protocol come interfaccia server di alto livello. Il decoratore @mcp.tool() che usi è il modo consigliato di creare server Python, non un add-on di terze parti.

Qual è la differenza tra un server MCP locale e uno remoto?

Un server locale gira sulla tua macchina su stdio, avviato dal client come sottoprocesso, ideale per strumenti personali e sviluppo. Un server remoto gira come servizio web su Streamable HTTP ed è raggiungibile da più client, il che richiede l'autenticazione OAuth 2.1. Costruisci prima in locale, passa al remoto solo quando condividi.

In quali linguaggi posso creare un server MCP?

Il Model Context Protocol ha SDK ufficiali per Python, TypeScript, Java, Kotlin e C#, con SDK della community in altri linguaggi. Poiché MCP è un protocollo di rete, qualsiasi linguaggio capace di leggere e scrivere JSON-RPC su stdio o HTTP può implementare un server, ma gli SDK ufficiali ti risparmiano quel lavoro.

Un server MCP funziona con ChatGPT e Gemini, o solo con Claude?

MCP è uno standard aperto adottato in tutto l'ecosistema dell'IA agentica, inclusi ChatGPT, Gemini, Cursor e VS Code Copilot. Un singolo server che costruisci funziona con qualsiasi client compatibile. Non scrivi un'integrazione separata per modello, che è tutto il senso del protocollo.

Quanto tempo serve per creare un server MCP funzionante?

Un primo server con uno o due strumenti su stdio richiede circa 15 minuti una volta installato il runtime. Abbiamo misurato 14 minuti per un principiante su Node 20 e meno di 5 minuti per una build ripetuta. Autenticazione, trasporto HTTP e hosting di produzione sono ciò che richiede tempo reale, non il server in sé.