
Il Model Context Protocol (MCP) è uno standard aperto che dà ai modelli di IA un modo universale per connettersi a strumenti esterni, fonti di dati e servizi. Invece di scrivere codice di integrazione personalizzato per ogni combinazione modello-strumento, scrivi un singolo server MCP e ogni modello compatibile può usarlo. Anthropic ha creato MCP alla fine del 2024, la Linux Foundation lo governa ora, e OpenAI, Google e il resto dell'ecosistema IA agentivo lo hanno adottato. Ecco tutto ciò che devi capire, costruire e distribuire con MCP.
MCP in sintesi
Se vuoi la versione rapida prima di immergerti in 6.000 parole di dettagli, eccola.
| Attributo | Dettaglio |
|---|---|
| Nome completo | Model Context Protocol (MCP) |
| Creato da | Anthropic (nov 2024), ora governato da Linux Foundation / AAIF (dic 2025) |
| Cosa fa | Standard universale per connettere i modelli IA a strumenti, dati e servizi |
| Problema che risolve | Elimina le M x N integrazioni personalizzate -- come USB-C per l'IA |
| Primitive fondamentali | Strumenti, Risorse, Prompt e Campionamento |
| Trasporto | stdio (sviluppo locale), Streamable HTTP (produzione) |
| Autenticazione | OAuth 2.1 (richiesto per il trasporto HTTP) |
| SDK | Python (FastMCP), TypeScript, Java, Kotlin, C# |
| Dimensione dell'ecosistema | 10.000+ server attivi (secondo Linux Foundation, dic 2025) |
| Principali adottanti | Claude, ChatGPT, Gemini, Cursor, VS Code Copilot, Windsurf |
| Stato della specifica | Standard aperto, in evoluzione attiva (roadmap 2026 in corso) |
| Ideale per | Agenti IA che devono interagire con strumenti e dati del mondo reale |
Ora analizziamo ognuno di questi punti, partendo da cosa sia effettivamente MCP e il problema che l'ha reso necessario.
Che cos'è il Model Context Protocol?
Il Model Context Protocol è un protocollo aperto basato su JSON-RPC che standardizza come i modelli IA scoprono e interagiscono con strumenti e dati esterni. Pensaci come HTTP per le integrazioni IA -- un linguaggio comune che qualsiasi modello e qualsiasi strumento può parlare.
Hai probabilmente sentito l'analogia con USB-C, ed è utile fino a un certo punto: prima di USB-C, ogni dispositivo aveva bisogno del proprio cavo. MCP fa la stessa cosa per l'IA, ma l'analogia lo sottovaluta. USB-C trasporta solo dati ed energia. MCP trasporta definizioni di strumenti, schemi di accesso ai dati, template di prompt riutilizzabili e consente persino ai server di richiedere completamenti al modello. È un protocollo più ricco di quanto suggerirebbe una metafora di cavo.
Il problema M x N che MCP risolve
Senza MCP, connettere M modelli a N strumenti richiede M x N integrazioni personalizzate. Supponiamo che tu supporti 5 LLM (Claude, GPT-4, Gemini, Llama, Mistral) e debba farli accedere a 10 strumenti (GitHub, Postgres, Slack, Jira, e così via). Sono 50 livelli di integrazione su misura, ognuno con la propria autenticazione, gestione degli errori e formattazione dei dati.
Con MCP, ogni modello implementa il protocollo client MCP una volta, e ogni strumento implementa un server MCP una volta. Ora sono 5 + 10 = 15 implementazioni invece di 50. Aggiungere un nuovo modello? Funziona immediatamente con tutti i 10 strumenti. Aggiungere un nuovo strumento? Tutti e 5 i modelli possono usarlo.
Una breve storia di MCP
Anthropic ha reso MCP open source nel novembre 2024 con SDK per Python e TypeScript più connettori per Claude Desktop. L'adozione è andata veloce. OpenAI ha aggiunto il supporto MCP a ChatGPT a marzo 2025. Google ha seguito per Gemini ad aprile 2025. A dicembre 2025, Anthropic ha donato MCP alla nuova Agentic AI Foundation (AAIF) della Linux Foundation, co-fondata con Block e OpenAI, rendendo MCP uno standard neutro rispetto ai vendor con governance inter-settoriale.
Cosa MCP NON È:
- Non è un modello né un framework IA (è un protocollo, come HTTP)
- Non sostituisce LangChain o LlamaIndex (quelli sono livelli di orchestrazione; MCP si trova sotto di essi)
- Non è limitato ad Anthropic o Claude (è agnostico rispetto al modello per design)
- Non è la stessa cosa del function calling (maggiori dettagli nella sezione di confronto)
Come funziona MCP? Approfondimento sull'architettura
MCP ha tre ruoli, e confonderli è l'errore più comune per i principianti. Chiariamo la distinzione.
<!-- IMAGE: Diagramma dell'architettura MCP che mostra i ruoli host, client, server con esempi reali come Claude Desktop, GitHub MCP Server, Postgres MCP Server -->Host, Client e Server -- Qual è la differenza?
| Componente | Ruolo | Esempi | Cosa fa |
|---|---|---|---|
| Host | L'applicazione con cui interagisce l'utente | Claude Desktop, Cursor, VS Code | Fornisce l'interfaccia utente, gestisce le istanze client |
| Client | Gestore del protocollo all'interno dell'host | Integrato nell'app host | Mantiene una connessione 1:1 con un server MCP |
| Server | Espone strumenti e dati tramite MCP | Server GitHub, server Postgres, server Slack | Racchiude API/dati esterni in endpoint compatibili MCP |
Ecco un esempio concreto: chiedi a Claude Desktop di controllare le tue pull request aperte su GitHub. Claude Desktop è l'host. Il suo client MCP integrato apre una connessione al server MCP di GitHub. Il server chiama l'API di GitHub, recupera le tue PR e restituisce i risultati al client, che li passa al modello.
Un singolo host può eseguire più client, ognuno connesso a un server diverso. È così che Claude Desktop può accedere simultaneamente a GitHub, al tuo database Postgres e a Slack -- tre server MCP separati, tre connessioni client separate, un host.
Come fluiscono i messaggi (JSON-RPC 2.0)
Tutta la comunicazione MCP usa JSON-RPC 2.0 -- un protocollo richiesta/risposta leggero. Ecco come appare uno scambio tools/list sul filo:
// Richiesta client: "Quali strumenti hai?"
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}
// Risposta server: uno strumento disponibile
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"tools": [
{
"name": "get_weather",
"description": "Ottieni il meteo attuale per una città",
"inputSchema": {
"type": "object",
"properties": {
"city": { "type": "string" }
},
"required": ["city"]
}
}
]
}
}Il modello legge queste definizioni di strumenti, decide quando chiamarle in base alla richiesta dell'utente, e il client invia una richiesta tools/call al server con gli argomenti appropriati.
Ciclo di vita della connessione
Ogni sessione MCP segue lo stesso ciclo di vita:
- Inizializzazione -- il client invia le capacità, il server risponde con le sue
- Negoziazione delle capacità -- entrambe le parti concordano sulle funzionalità supportate (strumenti, risorse, prompt, campionamento)
- Pronto -- la connessione è attiva; le richieste fluiscono in entrambe le direzioni
- Richieste/risposte --
tools/call,resources/read, ecc. - Chiusura -- disconnessione pulita
Questo handshake garantisce la compatibilità futura. Se un server aggiunge una nuova primitiva, i client più vecchi la ignorano elegantemente invece di andare in crash.
Primitive MCP: Strumenti, Risorse, Prompt e Campionamento
MCP definisce quattro primitive, e capire chi controlla ognuna è la chiave per progettare buoni server MCP.
| Primitiva | Chi la controlla | Direzione | Esempio | Caso d'uso |
|---|---|---|---|---|
| Strumenti | Il modello decide quando chiamare | Client -> Server | create_github_issue | Azioni che l'IA esegue autonomamente |
| Risorse | L'applicazione/utente seleziona | Client -> Server | file://project/README.md | Dati allegati al contesto |
| Prompt | L'utente attiva | Client -> Server | Template code_review | Schemi di interazione riutilizzabili |
| Campionamento | Il server richiede il completamento | Server -> Client | Il server chiede al modello di riassumere | Cicli agentivi dove il server usa l'LLM |
Strumenti (controllati dal modello)
Gli strumenti sono funzioni che il modello può chiamare. Il server le dichiara con un nome, una descrizione e una definizione dello schema di input JSON. Il modello legge queste definizioni e, quando la richiesta di un utente lo richiede, decide di invocare lo strumento.
// Il client invia una richiesta tools/call
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": { "city": "Roma" }
}
}Se hai usato il function calling di OpenAI, gli strumenti ti sembreranno familiari -- ma sono standardizzati per ogni modello compatibile MCP.
Risorse (controllate dall'applicazione)
Le risorse sono endpoint di dati in sola lettura. A differenza degli strumenti, il modello non decide di recuperare una risorsa da solo -- l'applicazione host o l'utente allega esplicitamente le risorse al contesto della conversazione. Pensaci come endpoint GET: postgres://mydb/users/schema, file://docs/api-reference.md.
Le risorse supportano le sottoscrizioni tramite resources/subscribe, così il client può essere notificato quando i dati cambiano.
Prompt (controllati dall'utente)
I prompt sono template riutilizzabili che un server MCP espone. Un prompt code_review potrebbe accettare un percorso di file e generare una richiesta di revisione strutturata. L'utente (o l'interfaccia utente dell'host) attiva i prompt esplicitamente -- non vengono invocati automaticamente dal modello.
Campionamento (avviato dal server) -- Avanzato
Ecco la primitiva che la maggior parte delle guide omette. Il Campionamento consente al server di chiedere al client di generare un completamento usando l'LLM. Questo inverte il flusso usuale: invece che il modello chiami uno strumento, è lo strumento a chiamare il modello.
Perché? Cicli agentivi. Immagina un server MCP che elabora ticket di supporto. Legge il ticket (una risorsa), usa sampling/createMessage per chiedere al modello un riassunto, poi usa quel riassunto per instradare il ticket tramite uno strumento. Il server orchestra un flusso di lavoro a più fasi sfruttando l'intelligenza del modello.
Il campionamento è controllato dall'applicazione host -- l'utente deve approvarlo, e l'host controlla cosa può richiedere il server. Questo previene cicli incontrollati e mantiene la supervisione umana.
Costruire il tuo primo server MCP: Python e TypeScript a confronto
Abbastanza teoria. Costruiamo un server MCP funzionante che espone uno strumento get_weather. Mostrerò sia Python che TypeScript così puoi confrontare l'esperienza dello sviluppatore e scegliere lo stack che si adatta al tuo progetto.
Python con FastMCP
FastMCP è l'SDK Python ufficiale di alto livello. Gestisce tutta l'infrastruttura del protocollo così puoi concentrarti sulla logica dei tuoi strumenti.
# Installa FastMCP
pip install fastmcp# weather_server.py
from fastmcp import FastMCP
mcp = FastMCP("Server Meteo")
@mcp.tool()
def get_weather(city: str) -> str:
"""Ottieni il meteo attuale per una città."""
# In produzione, chiama qui una vera API meteo
weather_data = {
"Roma": "Soleggiato, 18°C",
"Tokyo": "Soleggiato, 22°C",
"New York": "Piovoso, 8°C",
}
return weather_data.get(city, f"Nessun dato per {city}")
if __name__ == "__main__":
mcp.run()Questo è tutto -- 15 righe. FastMCP deduce lo schema di input dello strumento dalle annotazioni di tipo Python e dalla docstring. Nessun boilerplate JSON Schema.
TypeScript con l'SDK ufficiale
L'SDK TypeScript (@modelcontextprotocol/sdk) è un po' più esplicito ma ti dà pieno controllo sulle definizioni degli schemi.
# Installa l'SDK e Zod per la validazione degli schemi
npm install @modelcontextprotocol/sdk zod// weather-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: "Server Meteo",
version: "1.0.0",
});
server.tool(
"get_weather",
"Ottieni il meteo attuale per una città",
{ city: z.string() },
async ({ city }) => {
const weatherData: Record<string, string> = {
Roma: "Soleggiato, 18°C",
Tokyo: "Soleggiato, 22°C",
"New York": "Piovoso, 8°C",
};
return {
content: [
{ type: "text", text: weatherData[city] ?? `Nessun dato per ${city}` },
],
};
}
);
const transport = new StdioServerTransport();
await server.connect(transport);La versione TypeScript usa schemi Zod invece di annotazioni di tipo, e restituisce blocchi di contenuto strutturati. Più verboso, ma la type safety è eccellente.
Connettersi a Claude Desktop
Per collegare uno dei due server a Claude Desktop, aggiungilo al tuo claude_desktop_config.json:
{
"mcpServers": {
"weather-python": {
"command": "python",
"args": ["weather_server.py"],
"cwd": "/percorso/al/tuo/progetto"
},
"weather-typescript": {
"command": "npx",
"args": ["tsx", "weather-server.ts"],
"cwd": "/percorso/al/tuo/progetto"
}
}
}Riavvia Claude Desktop e entrambi i server meteo appaiono nell'elenco degli strumenti. Chiedi "Com'è il tempo a Roma?" e il modello chiama automaticamente il tuo strumento get_weather.
Testare con MCP Inspector
Prima di collegare il tuo server a un host, testalo in isolamento con MCP Inspector:
npx @modelcontextprotocol/inspector python weather_server.pyL'Inspector apre un'interfaccia utente nel browser dove puoi vedere gli strumenti scoperti, invocarli manualmente e ispezionare i messaggi JSON-RPC che vanno avanti e indietro. È lo strumento di debug migliore nell'ecosistema MCP -- usalo presto e spesso.
Trasporti MCP: stdio per lo sviluppo, Streamable HTTP per la produzione
I messaggi MCP hanno bisogno di un modo per viaggiare tra client e server. Questo è il livello di trasporto, e scegliere quello giusto è importante.
| Trasporto | Caso d'uso | Vantaggi | Svantaggi | Stato |
|---|---|---|---|---|
| stdio | Sviluppo locale, strumenti personali | Zero configurazione, semplice, veloce | Solo sulla stessa macchina | Attivo |
| Streamable HTTP | Produzione, server remoti, multi-utente | Funziona sulla rete, supporta lo streaming via SSE, compatibile stateless | Richiede server HTTP, necessita di auth | Attivo (spec 2025) |
| HTTP+SSE (vecchio) | Trasporto remoto legacy | Era l'opzione remota originale | Sostituito da Streamable HTTP | Deprecato |
stdio funziona avviando il server MCP come sottoprocesso e comunicando tramite stdin/stdout. È quello che hai usato nel tutorial sopra -- nessuna porta, nessun TLS, nessuna autenticazione necessaria. Perfetto per lo sviluppo e gli strumenti locali a singolo utente.
Streamable HTTP è il trasporto di produzione, aggiunto nell'aggiornamento della spec 2025. I client inviano richieste HTTP POST standard al server. Il server può rispondere in modo sincrono o aprire uno stream SSE per operazioni più lunghe. È compatibile stateless, funziona dietro load balancer e supporta l'autenticazione HTTP standard.
Se vedi tutorial più vecchi che menzionano "HTTP+SSE" come due trasporti separati (uno per inviare, uno per ricevere), quello è l'approccio deprecato. Streamable HTTP consolida entrambi in un unico meccanismo più pulito.
La decisione è semplice: usa stdio durante lo sviluppo locale, passa a streamable-http quando distribuisci per altri.
// Passare da stdio a Streamable HTTP in TypeScript
import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
const transport = new StreamableHTTPServerTransport({ port: 3001 });
await server.connect(transport);MCP vs Function Calling vs REST API -- Quando usare cosa
Questa è la domanda che emerge in ogni discussione su MCP, quindi risolviamola con un confronto diretto.
| Caratteristica | MCP | Function Calling | REST API |
|---|---|---|---|
| Standardizzazione | Protocollo aperto, agnostico al modello | Per provider (OpenAI, Anthropic hanno ognuno il loro) | Universale |
| Scoperta degli strumenti | Integrata (tools/list) | Nessuna -- invii schemi per richiesta | Nessuna -- richiede docs o spec OpenAPI |
| Accesso ai dati | Primitiva Risorse | Non supportata | Endpoint standard |
| Template di prompt | Primitiva Prompt | Non supportata | Non applicabile |
| Autenticazione | OAuth 2.1 (livello spec) | Chiave API del provider | Varia (chiavi API, OAuth, ecc.) |
| Streaming | SSE tramite Streamable HTTP | Dipende dal provider | Varia |
| Multi-modello | Funziona con qualsiasi modello compatibile MCP | Bloccato all'API di un provider | Agnostico al modello (con codice colla) |
| Ecosistema di server | 10.000+ server pre-costruiti | N/A | Milioni di API |
| Complessità di setup | Eseguire un server MCP | Inviare JSON in una chiamata API | Client HTTP |
| Ideale per | Ambienti di agenti multi-modello e multi-strumento | App semplici a singolo modello con pochi strumenti | Comunicazione servizio-a-servizio |
Quando il function calling è sufficiente
Se hai meno di 5 strumenti e usi un modello, il function calling è più semplice. Definisci gli schemi dei tuoi strumenti inline con ogni chiamata API, il modello restituisce il nome della funzione e gli argomenti, e li esegui nel tuo codice applicativo. Nessun server da eseguire, nessun protocollo da imparare. Per un chatbot che controlla lo stato degli ordini e cerca nelle FAQ, il function calling va benissimo.
Quando MCP vale lo sforzo
MCP giustifica la sua complessità quando:
- Supporti più LLM e non vuoi riscrivere le definizioni degli strumenti per ogni provider
- Hai bisogno della scoperta degli strumenti -- il modello può interrogare cosa è disponibile invece di dover codificare gli schemi in modo rigido
- Vuoi risorse e prompt, non solo chiamate agli strumenti
- Stai costruendo agenti IA che coordinano in modo autonomo e hai bisogno di un livello di integrazione standardizzato
- Il tuo team sta crescendo e ingegneri diversi costruiscono strumenti diversi -- MCP li lascia lavorare in modo indipendente
Verdetto: MCP vince quando hai bisogno di accesso standardizzato agli strumenti con più modelli. Il function calling vince per casi d'uso semplici a singolo modello. Le REST API rimangono la scelta giusta per la comunicazione tradizionale servizio-a-servizio che non coinvolge un LLM.
L'ecosistema MCP nel 2026: Chi lo supporta e cosa è disponibile
MCP è passato da un progetto collaterale di Anthropic a uno standard industriale in meno di 18 mesi. Ecco dove stanno le cose.
Quali LLM supportano MCP?
| LLM | Supporto MCP | Da quando | Note |
|---|---|---|---|
| Claude | Nativo, supporto completo | Nov 2024 | Ha creato MCP; integrazione più profonda |
| ChatGPT | Supporto ufficiale | Mar 2025 | Tramite l'integrazione MCP di OpenAI |
| Gemini | Supporto ufficiale | Apr 2025 | Server MCP Google Cloud per i servizi Google |
| Llama / Open-Source | Tramite adattatori | 2025 | LangChain, LlamaIndex e adattatori personalizzati |
| Copilot (VS Code) | Nativo in modalità agente | 2025 | Microsoft include il supporto MCP in VS Code |
Server MCP popolari che vale la pena conoscere
| Categoria | Server | Cosa fa |
|---|---|---|
| Codice | GitHub | PR, issue, repo, ricerca nel codice |
| Codice | GitLab | Merge request, pipeline, gestione progetti |
| Database | PostgreSQL | Ispezione degli schemi, esecuzione di query |
| Database | MySQL | Accesso a query e schemi |
| SaaS | Slack | Messaggi di canale, ricerca, notifiche |
| SaaS | Google Drive | Accesso ai file, ricerca, lettura di documenti |
| SaaS | Notion | Lettura di pagine, query di database |
| Ricerca | Brave Search | Risultati di ricerca web |
| DevOps | Docker | Gestione dei container |
| Infra | AWS | Gestione delle risorse cloud |
L'annuncio dell'AAIF della Linux Foundation ha citato 10.000+ server attivi e 97 milioni di download mensili dell'SDK al momento della donazione di MCP nel dicembre 2025. L'ecosistema non è più sperimentale -- è pronto per la produzione.
MCP Apps è una nuova primitiva introdotta a gennaio 2026. Permette ai server di fornire componenti UI interattivi che si renderizzano all'interno dell'applicazione host. Ancora prematuro, ma segnala l'evoluzione di MCP da protocollo dati a framework completo per applicazioni agentive. Vale la pena tenerlo d'occhio.
Governance: Da Anthropic alla Linux Foundation
MCP è governato dalla Agentic AI Foundation (AAIF) sotto la Linux Foundation, co-fondata da Anthropic, Block e OpenAI. Questo conta per l'adozione aziendale: MCP non è legato alla roadmap di un singolo vendor. La roadmap 2026 si concentra sull'evoluzione del trasporto, la comunicazione agente-agente (una nuova primitiva "Task"), la maturazione della governance e la preparazione aziendale.
Per i team che costruiscono sistemi IA in produzione, framework come un framework di agenti IA autonomi come OpenClaw si integrano già con i server MCP per dare agli agenti capacità nel mondo reale.
Sicurezza MCP: OAuth 2.1, minacce e una checklist pratica
La sicurezza è dove l'ecosistema MCP ha più terreno da recuperare. E i numeri dipingono un quadro chiaro.
Il problema dell'88%: Perché la maggior parte dei server MCP non è sicura
Astrix Security ha analizzato oltre 5.200 implementazioni di server MCP open source e ha scoperto che l'88% richiede credenziali di qualche tipo -- ma il 53% si affida a segreti statici di lunga durata non sicuri come chiavi API e token di accesso personali codificati in modo rigido nei file di configurazione. Solo l'8,5% implementa OAuth.
Ciò significa che la stragrande maggioranza dei server MCP in circolazione usa l'equivalente di autenticazione di incollare la chiave di casa sulla porta d'ingresso.
OAuth 2.1 per i server MCP
La specifica MCP richiede OAuth 2.1 per tutti i server basati su HTTP dall'aggiornamento di giugno 2025. Il flusso funziona così: il client MCP avvia un flusso di autorizzazione OAuth 2.1 con il server, ottiene un token di accesso con scope limitato e lo include con ogni richiesta successiva. PKCE (Proof Key for Code Exchange) è richiesto per tutti i client -- senza eccezioni.
Se stai costruendo un server MCP che gira su Streamable HTTP, OAuth 2.1 non è opzionale. È mandato dalla specifica.
Modello di minacce: Cosa può andare storto
Quattro minacce meritano attenzione in qualsiasi deployment MCP:
- Prompt injection tramite strumenti -- Una fonte di dati malevola o compromessa restituisce contenuto progettato per manipolare il modello. Se uno strumento recupera una pagina web e quella pagina contiene istruzioni nascoste, il modello potrebbe eseguirle.
- Attacco del deputy confuso -- Il modello invoca uno strumento con permessi più ampi di quelli che l'utente intendeva. Se il server MCP ha accesso amministratore a un database, il modello potrebbe teoricamente eliminare una tabella.
- Rischio di concentrazione dei token -- Un server MCP che detiene chiavi API per GitHub, Slack e il tuo database di produzione è un singolo bersaglio di alto valore. Comprometti un server, comprometti tutto ciò a cui si connette.
- Trasporto non sicuro -- Eseguire un server MCP HTTP senza TLS espone ogni richiesta, inclusi i token OAuth e i dati sensibili, in testo in chiaro.
Checklist di sicurezza per MCP in produzione
- Implementa OAuth 2.1 per qualsiasi server esposto tramite HTTP. Nessuna chiave API statica nei file di configurazione.
- Applica lo scope del minimo privilegio. Se il tuo strumento legge solo dati, le credenziali del server devono essere in sola lettura. Non dare accesso in scrittura a uno strumento di reportistica.
- Isola le credenziali. Ogni server MCP deve avere i propri token con scope limitato. Non condividere un singolo "token dio" tra server.
- Imponi TLS ovunque. Streamable HTTP senza HTTPS è automaticamente non adatto alla produzione.
- Valida e sanifica i risultati degli strumenti. Tratta i dati restituiti dagli strumenti allo stesso modo in cui tratteresti l'input dell'utente -- non fidarti ciecamente.
- Limita la frequenza delle invocazioni degli strumenti. Un ciclo di agente incontrollato che chiama uno strumento migliaia di volte può esaurire le quote API o causare effetti collaterali indesiderati.
- Verifica e registra ogni chiamata agli strumenti. Includi ID richiesta, timestamp, il modello chiamante e gli argomenti dello strumento. Ne hai bisogno per il debug e per la risposta agli incidenti di sicurezza.
Debug MCP: Inspector, logging e errori comuni
Incontrerai errori. Ogni sviluppatore li incontra. Ecco come risolverli velocemente.
MCP Inspector è lo strumento di debug ufficiale e la tua prima linea di difesa. Si connette a qualsiasi server MCP, scopre i suoi strumenti/risorse/prompt e ti lascia invocarli manualmente mostrando il traffico JSON-RPC grezzo.
# Avvia Inspector contro il tuo server Python
npx @modelcontextprotocol/inspector python weather_server.py
# O contro un server TypeScript
npx @modelcontextprotocol/inspector npx tsx weather-server.tsL'Inspector apre un'interfaccia utente basata su browser con schede per Strumenti, Risorse, Prompt e un pannello notifiche. Puoi chiamare qualsiasi strumento con argomenti personalizzati e vedere esattamente quale JSON passa attraverso il filo. Usalo prima di connetterti a un'applicazione host -- è molto più facile fare il debug del server in isolamento.
Errori comuni e soluzioni
- "Server non trovato" in Claude Desktop -- Quasi sempre un problema di percorso in
claude_desktop_config.json. Verifica checommandsi risolva in un vero binario e checwdpunti alla directory corretta. Su macOS, usa percorsi assoluti. - Errori di validazione dello schema degli strumenti -- Se il modello invia argomenti che non corrispondono all'
inputSchemadello strumento, il server rifiuta la chiamata. Controlla che i tipi del tuo schema corrispondano a quello che il modello si aspetta. Zod (TypeScript) e le annotazioni di tipo (Python) catturano la maggior parte di questi al momento della definizione. - Cadute della connessione di trasporto -- Per
stdio, di solito significa che il processo del server è andato in crash. Controlla l'output di stderr. Per Streamable HTTP, verifica le impostazioni di timeout -- gli strumenti a lunga esecuzione possono superare i timeout HTTP predefiniti. - Errori "Permission denied" o 401 -- Scope OAuth troppo ristretto. Il server sta rifiutando il token perché non ha i permessi richiesti. Amplia lo scope, ma solo quanto lo strumento ha effettivamente bisogno.
Best practice di logging
Struttura i tuoi log con ID richiesta così puoi tracciare una singola richiesta utente attraverso il client MCP, il server e qualsiasi API downstream. Registra ogni invocazione tools/call con il nome dello strumento, gli argomenti, il tempo di risposta e lo stato del risultato. In produzione, invia questi log a una piattaforma di osservabilità -- quando qualcosa va storto alle 3 di mattina, sarai contento di averlo fatto.
Come Techsy costruisce con MCP
Stiamo integrando MCP in progetti client dall'inizio del 2025, e il pattern che vediamo più spesso è questo: un team ha una funzione IA che funziona con un modello e una manciata di strumenti, ma stanno pianificando di scalare -- più modelli, più fonti di dati, più capacità agentive. Questo è il punto di svolta dove MCP inizia a dare i suoi frutti.
Il nostro approccio segue tre passi:
- Valutare l'adeguatezza. Non ogni progetto ha bisogno di MCP. Se stai chiamando due strumenti da un singolo modello, il function calling è più semplice e te lo diremo. MCP ha senso quando connetti 3 o più fonti di dati, supporti più modelli, o costruisci workflow di agenti dove gli strumenti devono essere scopribili.
- Costruire e testare i server in isolamento. Sviluppiamo server MCP personalizzati per ogni fonte di dati -- database interni, API SaaS, servizi proprietari -- e li validiamo con MCP Inspector prima di connetterli a qualsiasi host.
- Distribuire con Streamable HTTP e OAuth 2.1. Per la produzione, eseguiamo i server MCP come servizi containerizzati dietro TLS, con token OAuth con scope limitato e logging strutturato dal primo giorno. Nessun segreto statico.
Le integrazioni più comuni che costruiamo: connettere assistenti IA a database Postgres interni, costruire server MCP personalizzati per le piattaforme SaaS dei clienti, e migrare i team da configurazioni di function calling sparse a un'architettura MCP standardizzata.
Stai costruendo strumenti alimentati dall'IA che devono connettersi alla tua infrastruttura? Aiutiamo i team a progettare e implementare integrazioni MCP. Ottieni una consulenza gratuita
Domande frequenti su MCP
Che cos'è il Model Context Protocol (MCP)?
MCP è uno standard aperto, creato originariamente da Anthropic e ora governato dalla Linux Foundation, che definisce come i modelli IA si connettono a strumenti esterni, fonti di dati e servizi. Standardizza il livello di integrazione così un server MCP funziona con qualsiasi modello compatibile -- come una spina universale per l'IA.
Come funziona MCP?
MCP usa un'architettura in tre parti: un'applicazione host (come Claude Desktop o Cursor), un client MCP all'interno dell'host che gestisce le connessioni, e server MCP che espongono strumenti e dati. Tutta la comunicazione usa messaggi JSON-RPC 2.0 su stdio (locale) o Streamable HTTP (remoto).
Per cosa si usa MCP?
I casi d'uso comuni includono la connessione di assistenti IA a database (Postgres, MySQL), l'integrazione con piattaforme di codice (GitHub, GitLab), l'accesso a strumenti SaaS (Slack, Notion, Google Drive) e la costruzione di agenti IA autonomi che devono interagire con servizi reali.
MCP è la stessa cosa del function calling?
No. Il function calling è specifico del modello (il formato di OpenAI differisce da quello di Anthropic) e per richiesta -- invii schemi degli strumenti con ogni chiamata API. MCP è un protocollo standardizzato che funziona su più modelli, supporta la scoperta degli strumenti e include risorse e prompt oltre alla semplice esecuzione di funzioni.
Cosa sono i server MCP?
I server MCP sono programmi che espongono strumenti, risorse e prompt ai modelli IA tramite il protocollo MCP. Racchiudono API esterne e fonti di dati in un'interfaccia standardizzata. Gli esempi includono il server MCP di GitHub (per la gestione di PR e issue) e il server MCP di Postgres (per le query di database).
Come si costruisce un server MCP?
Usa Python con FastMCP (pip install fastmcp) o TypeScript con l'SDK ufficiale (npm install @modelcontextprotocol/sdk). Definisci i tuoi strumenti come funzioni decorate (Python) o handler registrati (TypeScript), poi esegui il server. Vedi la sezione tutorial sopra per il codice funzionante completo.
MCP è sicuro?
Il protocollo stesso supporta OAuth 2.1 per l'autenticazione e permessi con scope limitato. Tuttavia, la ricerca di Astrix Security ha rilevato che l'88% delle implementazioni di server MCP esistenti si affida a segreti statici piuttosto che a OAuth. Il protocollo è sicuro per design, ma la maggior parte dei deployment reali non si è ancora adeguata.
Quali LLM supportano MCP?
Claude ha supporto MCP nativo dalla sua creazione nel novembre 2024. ChatGPT ha aggiunto il supporto a marzo 2025, e Gemini ha seguito ad aprile 2025. I modelli open source possono usare MCP tramite adattatori in LangChain e LlamaIndex.
Qual è la differenza tra MCP e una REST API?
Le REST API sono progettate per la comunicazione generale servizio-a-servizio. MCP è progettato specificamente per l'interazione con i modelli IA -- include scoperta degli strumenti, negoziazione degli schemi, accesso alle risorse e template di prompt che REST non ha. Non sostituiresti le tue REST API con MCP; servono livelli diversi.
Chi mantiene MCP ora?
L'Agentic AI Foundation (AAIF) della Linux Foundation, formata nel dicembre 2025, governa MCP. È stata co-fondata da Anthropic, Block e OpenAI. Questa governance neutrale rispetto ai vendor è un motivo chiave per cui le aziende stanno adottando MCP.
Che cos'è Streamable HTTP in MCP?
Streamable HTTP è il meccanismo di trasporto di produzione aggiunto nell'aggiornamento della spec MCP 2025. Sostituisce il vecchio trasporto HTTP+SSE con un design più pulito: i client inviano richieste HTTP POST e i server possono rispondere in modo sincrono o tramite streaming SSE. Funziona dietro load balancer e supporta l'autenticazione HTTP standard.
Quanti server MCP esistono?
La Linux Foundation ha citato 10.000+ server attivi e 97 milioni di download mensili dell'SDK quando MCP è stato donato all'AAIF nel dicembre 2025. L'ecosistema comprende database, strumenti di codice, integrazioni SaaS, motori di ricerca e provider di infrastruttura cloud.
Conclusione
MCP è passato dall'esperimento open source di Anthropic al protocollo standard dell'industria per connettere i modelli IA agli strumenti in poco più di un anno. Ecco cosa conta:
- MCP risolve il problema M x N -- un server funziona con ogni modello compatibile, un client funziona con ogni server
- Puoi costruire un server MCP funzionante in meno di 50 righe di Python (FastMCP) o TypeScript
- Usa stdio per lo sviluppo, Streamable HTTP per la produzione -- la scelta del trasporto è semplice
- Proteggi i tuoi server con OAuth 2.1 -- l'88% delle implementazioni attuali non lo fa, e questo è un rischio reale
- L'ecosistema è pronto per la produzione -- 10.000+ server, tutti i principali LLM, governance neutrale sotto la Linux Foundation
Guardando avanti, la roadmap 2026 si concentra sulla comunicazione agente-agente tramite una nuova primitiva Task, una sicurezza aziendale migliorata e MCP Apps per un'interfaccia utente interattiva guidata dal server. MCP non è più solo un protocollo per l'accesso agli strumenti -- sta diventando il livello infrastrutturale per l'IA agentiva.
Inizia con il codice del tutorial sopra, testalo in MCP Inspector e collegalo a Claude Desktop. Avrai un'integrazione MCP funzionante in meno di un'ora.
Fonti
- Specifica MCP (2025-11-25)
- Specifica di autorizzazione MCP
- Specifica dei trasporti MCP
- Documentazione MCP Inspector
- Introduzione al Model Context Protocol -- Anthropic
- Donazione di MCP alla Linux Foundation -- Anthropic
- Annuncio AAIF della Linux Foundation
- Supporto MCP Google Cloud
- FastMCP Python SDK
- MCP TypeScript SDK
- Astrix Security: Stato della sicurezza dei server MCP 2025
- Roadmap MCP 2026