ai-machine-learning

Model Context Protocol: Crea il tuo primo server MCP oggi

Scritto da Mert Batur
Mar 17, 2026
21 lettura
Model Context Protocol: Crea il tuo primo server MCP oggi

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.

AttributoDettaglio
Nome completoModel Context Protocol (MCP)
Creato daAnthropic (nov 2024), ora governato da Linux Foundation / AAIF (dic 2025)
Cosa faStandard universale per connettere i modelli IA a strumenti, dati e servizi
Problema che risolveElimina le M x N integrazioni personalizzate -- come USB-C per l'IA
Primitive fondamentaliStrumenti, Risorse, Prompt e Campionamento
Trasportostdio (sviluppo locale), Streamable HTTP (produzione)
AutenticazioneOAuth 2.1 (richiesto per il trasporto HTTP)
SDKPython (FastMCP), TypeScript, Java, Kotlin, C#
Dimensione dell'ecosistema10.000+ server attivi (secondo Linux Foundation, dic 2025)
Principali adottantiClaude, ChatGPT, Gemini, Cursor, VS Code Copilot, Windsurf
Stato della specificaStandard aperto, in evoluzione attiva (roadmap 2026 in corso)
Ideale perAgenti 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?

ComponenteRuoloEsempiCosa fa
HostL'applicazione con cui interagisce l'utenteClaude Desktop, Cursor, VS CodeFornisce l'interfaccia utente, gestisce le istanze client
ClientGestore del protocollo all'interno dell'hostIntegrato nell'app hostMantiene una connessione 1:1 con un server MCP
ServerEspone strumenti e dati tramite MCPServer GitHub, server Postgres, server SlackRacchiude 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:

json
// 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:

  1. Inizializzazione -- il client invia le capacità, il server risponde con le sue
  2. Negoziazione delle capacità -- entrambe le parti concordano sulle funzionalità supportate (strumenti, risorse, prompt, campionamento)
  3. Pronto -- la connessione è attiva; le richieste fluiscono in entrambe le direzioni
  4. Richieste/risposte -- tools/call, resources/read, ecc.
  5. 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.

PrimitivaChi la controllaDirezioneEsempioCaso d'uso
StrumentiIl modello decide quando chiamareClient -> Servercreate_github_issueAzioni che l'IA esegue autonomamente
RisorseL'applicazione/utente selezionaClient -> Serverfile://project/README.mdDati allegati al contesto
PromptL'utente attivaClient -> ServerTemplate code_reviewSchemi di interazione riutilizzabili
CampionamentoIl server richiede il completamentoServer -> ClientIl server chiede al modello di riassumereCicli 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.

json
// 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.

bash
# Installa FastMCP
pip install fastmcp
python
# 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.

bash
# Installa l'SDK e Zod per la validazione degli schemi
npm install @modelcontextprotocol/sdk zod
typescript
// 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:

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:

bash
npx @modelcontextprotocol/inspector python weather_server.py

L'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.

TrasportoCaso d'usoVantaggiSvantaggiStato
stdioSviluppo locale, strumenti personaliZero configurazione, semplice, veloceSolo sulla stessa macchinaAttivo
Streamable HTTPProduzione, server remoti, multi-utenteFunziona sulla rete, supporta lo streaming via SSE, compatibile statelessRichiede server HTTP, necessita di authAttivo (spec 2025)
HTTP+SSE (vecchio)Trasporto remoto legacyEra l'opzione remota originaleSostituito da Streamable HTTPDeprecato

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.

typescript
// 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.

CaratteristicaMCPFunction CallingREST API
StandardizzazioneProtocollo aperto, agnostico al modelloPer provider (OpenAI, Anthropic hanno ognuno il loro)Universale
Scoperta degli strumentiIntegrata (tools/list)Nessuna -- invii schemi per richiestaNessuna -- richiede docs o spec OpenAPI
Accesso ai datiPrimitiva RisorseNon supportataEndpoint standard
Template di promptPrimitiva PromptNon supportataNon applicabile
AutenticazioneOAuth 2.1 (livello spec)Chiave API del providerVaria (chiavi API, OAuth, ecc.)
StreamingSSE tramite Streamable HTTPDipende dal providerVaria
Multi-modelloFunziona con qualsiasi modello compatibile MCPBloccato all'API di un providerAgnostico al modello (con codice colla)
Ecosistema di server10.000+ server pre-costruitiN/AMilioni di API
Complessità di setupEseguire un server MCPInviare JSON in una chiamata APIClient HTTP
Ideale perAmbienti di agenti multi-modello e multi-strumentoApp semplici a singolo modello con pochi strumentiComunicazione 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?

LLMSupporto MCPDa quandoNote
ClaudeNativo, supporto completoNov 2024Ha creato MCP; integrazione più profonda
ChatGPTSupporto ufficialeMar 2025Tramite l'integrazione MCP di OpenAI
GeminiSupporto ufficialeApr 2025Server MCP Google Cloud per i servizi Google
Llama / Open-SourceTramite adattatori2025LangChain, LlamaIndex e adattatori personalizzati
Copilot (VS Code)Nativo in modalità agente2025Microsoft include il supporto MCP in VS Code

Server MCP popolari che vale la pena conoscere

CategoriaServerCosa fa
CodiceGitHubPR, issue, repo, ricerca nel codice
CodiceGitLabMerge request, pipeline, gestione progetti
DatabasePostgreSQLIspezione degli schemi, esecuzione di query
DatabaseMySQLAccesso a query e schemi
SaaSSlackMessaggi di canale, ricerca, notifiche
SaaSGoogle DriveAccesso ai file, ricerca, lettura di documenti
SaaSNotionLettura di pagine, query di database
RicercaBrave SearchRisultati di ricerca web
DevOpsDockerGestione dei container
InfraAWSGestione 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

  1. Implementa OAuth 2.1 per qualsiasi server esposto tramite HTTP. Nessuna chiave API statica nei file di configurazione.
  2. 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.
  3. Isola le credenziali. Ogni server MCP deve avere i propri token con scope limitato. Non condividere un singolo "token dio" tra server.
  4. Imponi TLS ovunque. Streamable HTTP senza HTTPS è automaticamente non adatto alla produzione.
  5. 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.
  6. 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.
  7. 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.

bash
# 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.ts

L'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 che command si risolva in un vero binario e che cwd punti alla directory corretta. Su macOS, usa percorsi assoluti.
  • Errori di validazione dello schema degli strumenti -- Se il modello invia argomenti che non corrispondono all'inputSchema dello 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:

  1. 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.
  2. 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.
  3. 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

Tag

model context protocolmcpserver mcpagenti iatutorial mcparchitettura mcpfastmcpsviluppo ia

Condividi questo articolo

Il Tuo Prossimo Passo

Hai un progetto in mente? Parliamone.

Prenota una call di 30 minuti. Ti ascoltiamo, capiamo il problema e ti diciamo se possiamo aiutarti.