Cos’è un server MCP — un’introduzione per sviluppatori

Il Model Context Protocol (MCP) è lo standard di Anthropic per collegare assistenti IA a strumenti e dati locali. Un server MCP espone un insieme ristretto di operazioni — tool, resource o prompt — che un client IA può invocare durante una conversazione. Questa introduzione pratica risponde alle domande che ci siamo fatti costruendo il server MCP di Rockxy.

Il problema che MCP risolve

Prima di MCP, se volevi far leggere al tuo assistente IA qualcosa della tua macchina — file, database, log, traffico di rete — avevi due opzioni. Primo, copia-incolla: stressante e parziale. Secondo, plugin custom per il tuo specifico assistente, lock-in garantito: il plugin funziona con Claude Desktop e non con Cursor, o viceversa.

MCP standardizza il ponte. Un server MCP scritto una volta parla con qualsiasi client compatibile MCP. Claude Desktop, Cursor, Windsurf, Zed, Mistral Le Chat — tutti consumano lo stesso server, con lo stesso protocollo JSON-RPC 2.0.

Come è fatto un server MCP

Un server MCP è un programma che parla JSON-RPC 2.0 su un trasporto. Non serve niente di più. Ricevuta una chiamata tools/list, torna il manifest dei tool. Ricevuta una tools/call, esegue il tool e torna il risultato.

Il server MCP di Rockxy, per esempio, espone quattro tool:

• list_flows — elenca le flow HTTP catturate con filtri opzionali.
• get_flow_detail — riporta una singola flow con richiesta, risposta e tempi.
• replay_request — rigioca una flow esistente con eventuali override.
• diff_flows — torna un diff strutturale tra due flow.

Quando Claude Desktop o un altro client chiede il manifest, il server risponde con quelle definizioni. Quando l’IA decide che «elencare le richieste» è la mossa giusta, manda una tools/call con name: "list_flows" e i parametri che ha dedotto dal contesto.

stdio vs HTTP: quale trasporto

MCP supporta due trasporti. stdio: il client fa lo spawn del server come processo figlio e parla su stdin/stdout. HTTP con server-sent events: il server espone una porta e il client si collega come un qualsiasi HTTP client.

stdio è il trasporto standard per i client desktop. Claude Desktop lo usa. Il motivo: con stdio non devi gestire port binding, firewall, rinnovo certificati o segreti di autenticazione. Il sistema operativo isola il processo figlio e il client ne conosce già la discendenza.

HTTP ha senso per server remoti o per integrazioni dove il server gira altrove (un’IDE remota, un assistente browser). Per strumenti locali come un proxy, stdio è la scelta giusta. Rockxy espone anche una porta HTTP in loopback per i client che non parlano stdio, ma il default è stdio.

Tool, resource, prompt

MCP ha tre primitive. I tool sono le azioni: il modello decide di invocarli per rispondere alla domanda dell’utente. Le resource sono dati read-only indirizzabili tramite URI: file, voci di log, qualsiasi cosa il server vuole esporre come contenuto. I prompt sono template che il server offre al client come scorciatoie per l’utente («apri un nuovo prompt con questo template già pre-compilato»).

La maggior parte dei server MCP utili espone solo tool. Le resource sono utili quando hai file di grandi dimensioni di cui il modello deve leggere porzioni pigramente. I prompt sono utili quando offri flussi guidati all’utente. Se stai scrivendo il tuo primo server, inizia con i tool.

Come si autentica un server MCP

Con il trasporto stdio, l’autenticazione è implicita: se puoi spawnare il processo, hai l’accesso. Lo spazio di fiducia è il sistema operativo stesso.

Con il trasporto HTTP le opzioni sono più tradizionali: bearer token, mTLS, OAuth. MCP non impone un meccanismo specifico, ma le implementazioni reali convergono su bearer token per il caso locale e OAuth per il caso server remoti.

Il server MCP di Rockxy, quando espone la porta HTTP, la vincola a 127.0.0.1 e richiede un token che Rockxy genera al setup. Il token è persistito localmente, non lascia il Mac.

Progettare bene un server MCP

Alcune regole che abbiamo imparato costruendo il server MCP di Rockxy.

Superficie piccola. Il modello ragiona meglio su quattro tool ben definiti che su quaranta parzialmente sovrapposti. Ogni tool ha un nome chiaro, una descrizione concisa, parametri tipizzati.

Operazioni idempotenti dove possibile. Il modello potrebbe chiamare un tool più volte in sequenza, specialmente se non è sicuro del risultato. Le operazioni idempotenti sopravvivono a questo comportamento senza bruciare nulla.

Errori con causa chiara. Quando un tool fallisce, l’output dovrebbe dire perché in termini che il modello possa reimpostare in italiano: non un numero esadecimale, non uno stack trace crudo, ma «parametro limit deve essere ≥ 1».

Output deterministico. Se il tool torna strutture diverse a seconda dell’input, documentalo. Meglio ancora: rendile invarianti. Il modello tollera campi opzionali ma odia schema che mutano.

Redaction di default. Se il server espone dati sensibili — token, body di pagamento, header di autenticazione — redazionali per default. Il server MCP di Rockxy redaziona header e query parameter sensibili, campi di body (JSON, form, XML, bearer in plaintext) automaticamente, con un toggle live se l’utente vuole vedere tutto.

Cosa distingue i server che durano

Abbiamo visto molti server MCP demo che hanno vita breve. I server che durano condividono qualche pattern.

Primo, fanno una cosa sola e la fanno bene. I server «coltellino svizzero» che espongono 50 tool di 10 sistemi diversi confondono il modello e si rompono a ogni refactor. Un server per repository Git, un server per il proxy HTTP, un server per il database. Separazione netta.

Secondo, sono versionati. Se cambi lo schema di un tool, incrementi la versione. I client più maturi negoziano versioni di protocollo; i server che non le dichiarano rompono le release dei client.

Terzo, sono osservabili. Log delle chiamate, metriche sugli errori, un modo per rispondere alla domanda «cosa ha chiesto l’IA al server alle 14:23?». Rockxy mostra le chiamate MCP direttamente nella timeline del proxy, così le vedi come qualsiasi altra richiesta HTTP.

Quarto, il codice è aperto. La fiducia in uno strumento che ha accesso ai tuoi dati cresce quando il codice è leggibile. Rockxy è AGPL-3.0. La directory MCPServer/ nel repository mostra esattamente cosa il server espone a Claude.

Quando scrivere un server MCP

Valuta di scrivere un server MCP quando:

• Hai uno strumento locale con dati che vorresti che un assistente IA leggesse (log, database di sviluppo, repository, traffico di rete, snapshot di test).
• La copia-incolla di questi dati nella chat è il collo di bottiglia del tuo flusso di debug.
• Vuoi che più client IA accedano allo stesso strumento senza riscrivere integrazioni custom per ognuno.
• Puoi esporre una manciata di operazioni ben definite (di solito 3-8 tool).

Non scrivere un server MCP se: la funzionalità sta meglio come CLI che già usi, o come libreria importata nel tuo codice, o come integrazione IDE nativa. MCP è uno strumento di contesto per l’IA, non un framework applicativo generale.

Risorse

La specifica MCP di Anthropic è il posto da cui partire. SDK in TypeScript, Python e Swift coprono le tre lingue più comuni. Il server MCP di Rockxy è scritto in Swift; il codice è su GitHub se vuoi vedere un esempio reale con redaction e gestione sessioni.

Se ti interessa collegare subito Claude Desktop a un server MCP esistente, leggi la guida passo-passo. Se vuoi solo provare l’esperienza dalla parte utente, scarica Rockxy e attiva il server MCP dalle Impostazioni.