Protocolli MCP: stdio, HTTP e autenticazione in C# con .NET

🔌 Cosa sono i trasporti MCP (host, client, server)

In MCP ci sono tre ruoli: l'host (la tua applicazione), il client MCP che vive dentro l'host, e il server MCP che espone tool, risorse e prompt. Client e server dialogano con messaggi JSON-RPC 2.0.

Il trasporto è il canale su cui viaggiano quei messaggi. La specifica ne definisce due standard: stdio per i server locali e Streamable HTTP per quelli remoti. Il formato dei messaggi non cambia: cambia solo come arrivano da una parte all'altra.

• Host: l'app che coordina modello, client MCP e conversazione.
• Client: apre una connessione verso un server e ne elenca i tool.
• Server: espone capacità (tool/risorse/prompt) in modo standard.

// Richiesta: il client invoca un tool del server MCP
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": { "name": "read_file",
               "arguments": { "path": "README.md" } } }

// Risposta: stesso formato su qualsiasi trasporto
{ "jsonrpc": "2.0", "id": 1,
  "result": { "content": [ { "type": "text",
                              "text": "# Progetto..." } ] } }

🖥️ stdio: il trasporto locale

Con stdio il client lancia il server come processo figlio e ci parla scrivendo su stdin e leggendo da stdout. Niente rete, niente porte: due processi sulla stessa macchina che si scambiano righe JSON-RPC.

È il trasporto consigliato quando possibile: latenza minima, zero superficie di rete e un ciclo di vita semplice — quando l'host chiude, il processo del server termina con lui. Lo stderr resta per i log.

• Il server è un eseguibile (un binario, `npx`, `dotnet run`, `uvx`).
• Un client parla con un processo: relazione uno-a-uno.
• Nessun handshake di rete: parte e basta.

# Il server MCP e' un processo: il client lo avvia cosi'
npx -y @modelcontextprotocol/server-filesystem /Users/tu/progetti

# Da qui in poi client e server si parlano SOLO
# su stdin (richieste) e stdout (risposte). stderr = log.

🌐 Streamable HTTP: il trasporto remoto

Con Streamable HTTP il server è un processo indipendente che espone un solo endpoint HTTP. Il client invia i messaggi con una richiesta POST; il server può rispondere con un JSON singolo oppure aprire uno stream SSE (Server-Sent Events) quando deve mandare più messaggi.

È il trasporto per tutto ciò che è fuori dalla macchina: un server condiviso, un SaaS, un servizio dietro load balancer. Un solo server gestisce molti client insieme e, se serve, richiede autenticazione.

• POST per inviare, GET + SSE per lo streaming server→client.
• Multi-client e scalabile: sta dietro un reverse proxy come qualsiasi API.
• È il punto in cui entra in gioco l'autenticazione (vedi sotto).

# Streamable HTTP: una POST inizializza la sessione.
# Il client accetta sia JSON sia uno stream SSE.
curl -X POST https://api.example.com/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer $MCP_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize"}'

🕰️ HTTP+SSE: il vecchio trasporto (deprecato)

Prima di Streamable HTTP esisteva HTTP+SSE (specifica 2024-11-05): due endpoint separati, una connessione SSE sempre aperta e una POST a parte per le richieste. Funzionava, ma era scomodo da scalare e da mettere in sicurezza.

Dal 2025 è stato sostituito da Streamable HTTP e resta solo per retrocompatibilità. Se scrivi codice nuovo, usa Streamable HTTP: il vecchio schema è deprecato e va evitato per i server nuovi.

⚖️ stdio vs HTTP: quando usare quale

La regola è semplice: locale → stdio, remoto → Streamable HTTP. Se il server gira sulla stessa macchina dell'host (tool sui file, una CLI, uno strumento di sviluppo), stdio è più veloce e senza fronzoli.

Se il server è condiviso, esposto in rete o gestito da terzi, serve HTTP: multi-client, scalabile e con autenticazione. Molti host, del resto, parlano entrambi i trasporti e li mescolano nello stesso progetto.

stdio per il locale, Streamable HTTP per il remoto: caratteristiche opposte, stesso protocollo.

🔐 Autenticazione MCP: quando serve

Qui i due trasporti divergono. Con stdio l'autenticazione MCP non si applica: il server è locale e fidato, quindi le credenziali (API key, token) arrivano dalle variabili d'ambiente che gli passi all'avvio. La specifica dice esplicitamente di non usare OAuth su stdio.

Con HTTP, invece, un server protetto segue OAuth 2.1. Il server pubblica un Protected Resource Metadata (PRM, RFC 9728) che dice al client quale authorization server usare; il client ottiene un access token con PKCE e Resource Indicators (RFC 8707), poi chiama il server con l'header `Authorization: Bearer`.

• stdio → nessun OAuth: credenziali dalle variabili d'ambiente.
• HTTP → OAuth 2.1: PRM per la discovery, PKCE obbligatorio per i client pubblici.
• Il token ha un audience legato alla risorsa: non è riutilizzabile altrove.

Il client scopre l'authorization server dal PRM, prende il token con PKCE e chiama il server.

🧩 Come si dichiara un trasporto (config reale)

Prima del codice C#, ecco come i due trasporti appaiono in una configurazione reale, quella con cui un host (qui Claude Code) registra i suoi server MCP. La differenza è tutta nei campi.

Un server stdio si descrive con `command` e `args` (cosa eseguire). Un server HTTP con `type: "http"` e una `url`; l'eventuale token va negli `headers` come `Authorization`, preso da una variabile e mai scritto in chiaro.

🧰 Preparare il progetto .NET

Passiamo alla pratica. Creiamo una console app e aggiungiamo quattro pacchetti: le astrazioni Microsoft.Extensions.AI, un provider per il modello, Microsoft Agent Framework per l'agente e l'MCP C# SDK ufficiale (`ModelContextProtocol`).

Le astrazioni di Extensions.AI (`IChatClient`) rendono il codice indipendente dal provider: oggi OpenAI, domani Azure OpenAI o Ollama, cambiando una riga. L'MCP SDK è in preview, quindi va aggiunto con `--prerelease`.

# nuova console app
dotnet new console -n McpAgentDemo && cd McpAgentDemo

# astrazioni AI + provider + agent framework + MCP
dotnet add package Microsoft.Extensions.AI
dotnet add package Microsoft.Extensions.AI.OpenAI --prerelease
dotnet add package Microsoft.Agents.AI --prerelease
dotnet add package ModelContextProtocol --prerelease

🗂️ Esempio 1 — stdio senza auth (Filesystem)

Primo esempio: un agente che usa il server Filesystem via stdio. Il client lo avvia con `npx`, elenca i tool e li passa all'agente. Nessuna autenticazione: è tutto locale, e l'eventuale scope (la cartella) è un semplice argomento da riga di comando.

Il cuore è `McpClient.CreateAsync(transport)`: crea il client e avvia il processo figlio. `ListToolsAsync()` restituisce dei `McpClientTool`, che sono `AIFunction` di Extensions.AI: si passano all'agente così come sono.

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using ModelContextProtocol.Client;
using OpenAI;

// 1) Il modello: un IChatClient di Microsoft.Extensions.AI.
var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;
IChatClient chatClient = new OpenAIClient(apiKey)
    .GetChatClient("gpt-4o-mini")
    .AsIChatClient();

// 2) Trasporto stdio: avvia il server come processo figlio.
//    Nessuna auth: e' locale e fidato.
var transport = new StdioClientTransport(new StdioClientTransportOptions
{
    Name = "Filesystem",
    Command = "npx",
    Arguments = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/tu/progetti"],
});

await using McpClient mcp = await McpClient.CreateAsync(transport);

// 3) I tool del server SONO AIFunction: si passano all'agente.
IList<McpClientTool> tools = await mcp.ListToolsAsync();

// 4) L'agente (Agent Framework) orchestra modello + tool.
AIAgent agent = new ChatClientAgent(chatClient, new ChatClientAgentOptions
{
    Name = "FilesystemAgent",
    Instructions = "Rispondi solo usando i file della cartella di lavoro.",
    ChatOptions = new ChatOptions { Tools = [.. tools] },
});

Console.WriteLine(await agent.RunAsync("Elenca i file .md e riassumi il README."));

▶️ Avviare l'esempio stdio e leggere l'output

Alla `dotnet run` il client avvia il server, completa l'handshake e scopre i tool disponibili (per il Filesystem: leggere file, elencare directory, scrivere). Poi l'agente decide quali chiamare per rispondere.

Se qualcosa non parte, il primo posto da guardare è il log del server: un errore tipico è `spawn npx ENOENT`, cioè Node/npx non è nel PATH. Con stdio i problemi sono quasi sempre di ambiente o di comando.

Connection state: Running e poi i tool scoperti: la prova che l'handshake stdio è andato a buon fine.

🔑 Esempio 2 — HTTP con auth (GitHub MCP)

Secondo esempio: lo stesso agente, ma verso il server MCP remoto di GitHub via Streamable HTTP e con autenticazione. Cambia solo il trasporto: `SseClientTransport` con `TransportMode = StreamableHttp` e l'header `Authorization: Bearer`.

Il token non si scrive nel codice: arriva da una variabile d'ambiente. È la stessa regola dello stdio (credenziali da env) applicata all'header HTTP: mai segreti in chiaro nel sorgente.

using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using ModelContextProtocol.Client;
using ModelContextProtocol.Protocol;
using OpenAI;

var apiKey = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;

// Il token arriva da una variabile d'ambiente, mai dal codice.
var githubToken = Environment.GetEnvironmentVariable("GITHUB_MCP_TOKEN")
    ?? throw new InvalidOperationException("GITHUB_MCP_TOKEN non impostata.");

IChatClient chatClient = new OpenAIClient(apiKey)
    .GetChatClient("gpt-4o-mini")
    .AsIChatClient();

// Trasporto Streamable HTTP verso un server remoto, con header Bearer.
var transport = new SseClientTransport(new SseClientTransportOptions
{
    Name = "GitHub MCP",
    Endpoint = new Uri("https://api.githubcopilot.com/mcp/"),
    TransportMode = HttpTransportMode.StreamableHttp,
    AdditionalHeaders = new Dictionary<string, string>
    {
        ["Authorization"] = $"Bearer {githubToken}",
    },
});

await using McpClient mcp = await McpClient.CreateAsync(transport);
IList<McpClientTool> tools = await mcp.ListToolsAsync();

AIAgent agent = new ChatClientAgent(chatClient, new ChatClientAgentOptions
{
    Name = "GitHubAgent",
    Instructions = "Rispondi solo su repository GitHub, usando i tool MCP.",
    ChatOptions = new ChatOptions { Tools = [.. tools] },
});

Console.WriteLine(await agent.RunAsync(
    "Riassumi gli ultimi 5 commit di modelcontextprotocol/csharp-sdk."));

🪪 Oltre il token: OAuth 2.1 con l'SDK

Un token statico va bene per un personal access token. Ma quando il server impone OAuth 2.1, non passiamo un token a mano: l'MCP C# SDK ha il flusso integrato. Basta impostare `OAuth` sulle opzioni del trasporto con un `ClientOAuthOptions`.

Sotto al cofano l'SDK fa tutto: legge il PRM del server, scopre l'authorization server, esegue l'Authorization Code con PKCE e gestisce il token. Al tuo codice resta solo aprire il browser sull'URL di autorizzazione.

using ModelContextProtocol.Client;

// Server che impone OAuth 2.1: niente token statico.
// L'SDK gestisce PRM discovery (RFC 9728), PKCE e scambio del token.
var transport = new SseClientTransport(new SseClientTransportOptions
{
    Name = "Secure MCP",
    Endpoint = new Uri("https://mcp.example.com/"),
    OAuth = new ClientOAuthOptions
    {
        ClientName = "MioClientMcp",
        RedirectUri = new Uri("http://localhost:1179/callback"),
        // Delegato che apre il browser sull'URL di autorizzazione.
        AuthorizationRedirectDelegate = OpenBrowserAsync,
    },
});

await using McpClient mcp = await McpClient.CreateAsync(transport);

✅ Riepilogo e checklist

Ricapitoliamo. Il trasporto è la prima scelta di ogni integrazione MCP: stdio per il locale, Streamable HTTP per il remoto, e HTTP+SSE solo se devi parlare con un vecchio server. Il codice dell'agente, però, resta identico.

L'autenticazione segue il trasporto: variabili d'ambiente per stdio, OAuth 2.1 (o un Bearer da env) per HTTP. Grazie a Extensions.AI e Agent Framework, cambiare provider o trasporto è questione di poche righe.

Altri articoli del blog