Come implementare un server MCP remoto su Vercel: Guida completa passo-passo 2025
Il Model Context Protocol (MCP) sta rivoluzionando il modo in cui le applicazioni di intelligenza artificiale interagiscono con strumenti e fonti di dati esterni.
In questa guida completa, ti mostreremo come distribuire il tuo server MCP remoto sulla piattaforma serverless di Vercel, utilizzando il nostro server di produzione my-mcp-server come esempio pratico.
Cos'è il Model Context Protocol (MCP)?
MCP è uno standard aperto sviluppato da Anthropic che consente ai Large Language Model (LLM) di comunicare senza problemi con sistemi esterni.
Pensalo come un adattatore universale che permette agli assistenti IA come Claude, ChatGPT e altri di accedere ai tuoi strumenti, database e API personalizzati in modo standardizzato.
Vantaggi principali di MCP
- Comunicazione standardizzata: Un protocollo per tutto – niente più integrazioni personalizzate per ogni piattaforma IA
- Scoperta degli strumenti: I client IA possono scoprire automaticamente quali strumenti fornisce il tuo server
- Sicurezza dei tipi: Gli schemi integrati garantiscono la validazione dei dati
- Estensibilità: Facile aggiunta di nuovi strumenti senza modificare l'architettura di base
Perché distribuire MCP su Vercel?
Vercel ha annunciato ufficialmente il supporto per i server MCP a maggio 2025, rendendola la piattaforma principale per l'hosting di server MCP remoti.
Ecco perché:
- Architettura serverless: Paga solo ciò che usi, con scalabilità automatica
- Rete Edge globale: Bassa latenza da qualsiasi parte del mondo
- Supporto nativo: Supporto integrato per il trasporto Streamable HTTP
- Deploy facile: Push su Git e deploy automatico
- Fluid Compute: Utilizzo efficiente delle risorse per carichi di lavoro IA
Panoramica dell'architettura
Prima di immergerci nel codice, comprendiamo l'architettura:
┌──────────────────┐ HTTPS ┌──────────────────────┐
│ │ ◄────────────► │ │
│ Client MCP │ Streamable │ Funzione Vercel │
│ (Claude Code, │ HTTP │ (Server MCP) │
│ Cursor, ecc.) │ │ │
│ │ │ ┌────────────────┐ │
└──────────────────┘ │ │ Handler Tool │ │
│ └────────────────┘ │
│ │
└──────────────────────┘
Passo 1: Configurazione del progetto
Crea un nuovo progetto:
# Creare nuovo progetto
mkdir mio-server-mcp
cd mio-server-mcp
npm init -y
# Installare dipendenze
npm install @modelcontextprotocol/sdk zod
npm install -D @vercel/node typescript @types/node
Passo 2: Creare l'handler del server MCP
Crea l'handler API principale in api/index.ts:
import type { VercelRequest, VercelResponse } from "@vercel/node";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
import { z } from "zod";
function createMcpServer(): McpServer {
const server = new McpServer({
name: "mio-server-mcp",
version: "1.0.0",
});
// Registrare il primo strumento
server.registerTool("ciao_mondo", {
title: "Ciao Mondo",
description: "Un semplice strumento di saluto",
inputSchema: {
nome: z.string().describe("Nome da salutare"),
},
}, async ({ nome }) => {
return {
content: [{
type: "text",
text: JSON.stringify({
messaggio: `Ciao, ${nome}! Benvenuto in MCP.`,
timestamp: new Date().toISOString(),
}, null, 2),
}],
};
});
return server;
}
export default async function handler(
req: VercelRequest,
res: VercelResponse
) {
res.setHeader("Access-Control-Allow-Origin", "*");
res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
if (req.method === "OPTIONS") {
return res.status(200).end();
}
try {
const server = createMcpServer();
const transport = new StreamableHTTPServerTransport({
sessionIdGenerator: undefined,
});
await server.connect(transport);
await transport.handleRequest(req, res, req.body);
} catch (error) {
if (!res.headersSent) {
return res.status(500).json({
jsonrpc: "2.0",
error: {
code: -32603,
message: `Errore interno del server: ${error}`,
},
});
}
}
}
Componenti chiave dell'handler
L'handler implementa tre funzionalità principali:
- Gestione CORS: Permette richieste cross-origin dai client MCP
- Creazione server: Inizializza il server MCP con nome e versione
- Trasporto HTTP: Utilizza StreamableHTTPServerTransport per la comunicazione
Passo 3: Configurare il deployment su Vercel
Crea vercel.json:
{
"$schema": "https://openapi.vercel.sh/vercel.json",
"version": 2,
"buildCommand": "npm run build",
"functions": {
"api/index.ts": {
"maxDuration": 60
}
}
}
Configurazione timeout
Importante: Il parametro
maxDurationimposta il timeout massimo a 60 secondi, ideale per operazioni IA che potrebbero richiedere più tempo.
Passo 4: Aggiungere strumenti reali – L'esempio my-mcp-server
Vediamo come il nostro server di produzione my-mcp-server implementa strumenti reali. Questo server fornisce ricerca web, pubblicazione sui social media, generazione di immagini e altro.
Strumento di ricerca web
// Strumento di ricerca web
server.registerTool("search_web", {
title: "Search Web",
description: "Cerca sul web informazioni attuali usando Tavily AI",
inputSchema: {
query: z.string().describe("Query di ricerca"),
maxResults: z.number().optional().describe("Risultati massimi (default: 5)"),
topic: z.enum(["general", "news"]).optional().describe("Tipo di ricerca"),
},
}, async ({ query, maxResults, topic }) => {
const result = await tavilySearch(query, { maxResults, topic });
return {
content: [{
type: "text",
text: JSON.stringify({
query: result.query,
answer: result.answer,
results: result.results,
}, null, 2),
}],
};
});
Strumento di generazione immagini
// Strumento di generazione immagini
server.registerTool("generate_hero_image", {
title: "Generate Hero Image",
description: "Genera un'immagine hero usando Gemini AI",
inputSchema: {
topic: z.string().describe("Argomento/descrizione dell'immagine"),
style: z.enum([
"modern-professional",
"tech-gradient",
"minimal-abstract"
]).describe("Stile visivo"),
},
}, async ({ topic, style }) => {
const image = await generateImageWithGemini(topic, style);
return {
content: [{
type: "text",
text: JSON.stringify({
status: "success",
topic,
style,
mimeType: image.mimeType,
base64Data: image.base64Data,
}, null, 2),
}],
};
});
Passo 5: Variabili d'ambiente
Configura le tue variabili d'ambiente in Vercel:
# Richieste per varie integrazioni
TAVILY_API_KEY=la_tua_chiave_tavily
GOOGLE_API_KEY=la_tua_chiave_google
TYPEFULLY_API_KEY=la_tua_chiave_typefully
Passo 6: Distribuire su Vercel
npm install -g vercel
vercel --prod
Dopo il deployment, Vercel ti fornirà un URL pubblico per il tuo server MCP.
Passo 7: Connettere i client al tuo server MCP
Connessione con Claude Code / Claude Desktop
Aggiungi alla tua configurazione Claude (tipicamente in ~/.claude.json o settings.json):
{
"mcpServers": {
"my-mcp-server": {
"command": "npx",
"args": [
"-y",
"mcp-remote",
"https://tuo-progetto.vercel.app/api"
]
}
}
}
Connessione con l'AI SDK (Vercel)
import { experimental_createMCPClient } from "ai";
const mcpClient = await experimental_createMCPClient({
transport: {
type: "sse",
url: "https://tuo-progetto.vercel.app/api",
},
});
// Ottenere gli strumenti disponibili
const tools = await mcpClient.tools();
console.log("Strumenti disponibili:", tools);
Passo 8: Testare il server
Testa se il tuo server funziona:
# Health Check
curl https://il-tuo-progetto.vercel.app/api?action=health
# Elencare gli strumenti
npx mcp-remote https://il-tuo-progetto.vercel.app/api --list-tools
Best Practices
Design e architettura
- Design stateless: Le funzioni Vercel sono stateless – non memorizzare stato tra le richieste
- Gestione errori: Restituisci sempre risposte di errore JSON-RPC appropriate
- Gestione timeout: Imposta timeout appropriati per operazioni lunghe
- Validazione input: Usa sempre gli schemi Zod per validare gli input degli strumenti
Sicurezza e performance
- Implementa rate limiting per prevenire abusi
- Usa variabili d'ambiente per chiavi API sensibili
- Monitora l'utilizzo delle risorse tramite Vercel Analytics
- Implementa caching quando possibile per ridurre i costi
Prossimi passi
Ora che sai come distribuire un server MCP su Vercel, ecco alcune idee per strumenti che potresti costruire:
- Strumenti di ricerca: Ricerca web, aggregazione notizie, ricerca tematica
- Strumenti di contenuto: Generazione di outline per blog, ottimizzazione SEO
- Strumenti immagine: Generazione di immagini AI con vari stili
- Strumenti database: Interrogare e gestire i tuoi database
- Integrazioni API: Connessione a servizi di terze parti
Conclusione
Distribuire un server MCP su Vercel combina la potenza del calcolo serverless con la flessibilità del Model Context Protocol.
L'ecosistema MCP sta crescendo rapidamente, con grandi aziende come Booking.com, Expedia e Microsoft che adottano il protocollo.
Il futuro è MCP: Con il supporto ufficiale di Vercel e l'adozione crescente da parte delle aziende, MCP sta diventando lo standard de facto per l'integrazione degli strumenti IA.
Risorse
Pronto a distribuire il tuo server MCP? Inizia subito!