in Architettura Software, Informatica |

Testing per Server MCP: VS Code Dev Tunnels e Online Inspectors

L’adozione del Model Context Protocol (MCP) sta ridefinendo gli standard di interoperabilità tra modelli linguistici di grandi dimensioni (LLM) e risorse dati esterne. Tuttavia, la fase di debugging di un server MCP locale presenta spesso sfide legate alla simulazione di ambienti di rete reali.

Una delle metodologie più efficienti per validare un’implementazione MCP consiste nell’utilizzare i Dev Tunnels di Visual Studio Code in combinazione con strumenti di ispezione remoti (Online Inspectors). Questa sinergia permette di esporre un endpoint locale in modo sicuro e monitorare il traffico JSON-RPC in tempo reale.

Architettura del Workflow di Testing

Il processo si articola in quattro fasi distinte che garantiscono la raggiungibilità del server e la conformità al protocollo.

1. Configurazione del Trasporto di Rete

Per consentire l’accesso esterno, il server MCP non deve operare tramite lo standard input/output (stdio), bensì deve implementare un trasporto basato su rete, come SSE (Server-Sent Events) o Streamable HTTP. È essenziale che il server sia in esecuzione su una porta locale specifica (es. localhost:3000).

2. Esposizione tramite VS Code Dev Tunnels

VS Code integra una funzionalità nativa di port forwarding che genera URL pubblici stabili su dominio devtunnels.ms.

  • Procedura: All’interno del pannello “Ports”, aggiungere la porta locale desiderata.
  • Visibilità: È imperativo impostare la visibilità della porta su “Public”. I tunnel privati richiedono infatti un’autenticazione tramite account Microsoft o GitHub che impedirebbe la connessione automatizzata da parte degli inspector esterni.

3. Gestione della Sicurezza e Interstitial Anti-Phishing

I Dev Tunnels di Microsoft includono una pagina di protezione anti-phishing che funge da intercettore per le richieste GET. Per garantire che le chiamate API dirette non vengano bloccate, è necessario configurare lo strumento di test per includere l’header HTTP specifico:

X-Tunnel-Skip-AntiPhishing-Page: true.

Questo header permette di bypassare l’interstitial di sicurezza, consentendo al traffico del protocollo MCP di raggiungere direttamente l’applicazione.

4. Requisiti CORS (Cross-Origin Resource Sharing)

Poiché gli online inspector (come inspector.mcp-use.com o mcp.ziziyi.com) operano direttamente dal browser, il server MCP deve essere configurato per gestire le richieste cross-origin.

  • Best Practice: Configurare il server per restituire gli header Access-Control-Allow-Origin specifici per l’URL dell’inspector utilizzato. In ambienti di puro sviluppo, è possibile utilizzare il wildcard *, sebbene sia sconsigliato in contesti di produzione.

Strumenti di Ispezione Consigliati

Una volta ottenuto l’URL pubblico (es. https://random-id-3000.euw.devtunnels.ms/mcp), è possibile utilizzare piattaforme di testing professionali che offrono:

  • Validazione dello Schema: Verifica automatica della conformità dei Tools, Resources e Prompts esposti.
  • Interactive Playground: Esecuzione di chiamate ai tool con input strutturati.
  • Logging JSON-RPC: Monitoraggio dettagliato dei messaggi di richiesta e risposta.

Ecco una versione estesa e tecnicamente dettagliata del post, con un focus specifico sulle procedure di configurazione necessarie per integrare con successo un server MCP (Model Context Protocol) locale con gli strumenti di ispezione online tramite VS Code Dev Tunnels.

Configurazione

L’integrazione di capacità IA all’interno di flussi operativi complessi richiede una validazione rigorosa dei server Model Context Protocol (MCP). Per gli sviluppatori che operano in ambienti locali, il testing della comunicazione SSE (Server-Sent Events) o Streamable HTTP può risultare oneroso.

L’utilizzo combinato dei Dev Tunnels di Visual Studio Code e degli Online MCP Inspectors (come mcp-use o Ziziyi) offre un ambiente di staging immediato e senza attriti. Di seguito viene illustrata la procedura di configurazione completa.

1. Configurazione del Server MCP (Lato Backend)

Affinché il server sia raggiungibile tramite tunnel, non deve limitarsi al trasporto stdio. È necessario implementare un endpoint di rete.

  • Trasporto: Configurare il server per utilizzare SSE o Streamable HTTP.
  • CORS (Cross-Origin Resource Sharing): Poiché l’inspector opera da un dominio differente, il server deve autorizzare esplicitamente l’origine.
    • Esempio FastMCP (Python): mcp = FastMCP("nome-server", cors_allowed_origins=["*"]).
    • Best Practice: In produzione, sostituire * con l’URL specifico dell’inspector (es. https://inspector.mcp-use.com).

2. Attivazione ed Esposizione del Dev Tunnel

VS Code permette di esporre la porta locale (es. 3000) attraverso l’infrastruttura Microsoft Azure.

  1. Aprire il pannello Ports in VS Code.
  2. Selezionare Forward a Port e inserire la porta su cui è in ascolto il server MCP.
  3. Cambio Visibilità: Per impostazione predefinita, il tunnel è “Private” (richiede login Microsoft/GitHub). Fare clic destro sulla colonna Visibility e selezionare Public. Questo passaggio è fondamentale per permettere agli strumenti di ispezione esterni di negoziare la connessione senza gestire flussi di autenticazione proprietari di Azure.

3. Gestione dell’Header Anti-Phishing

I tunnel pubblici di Microsoft includono una pagina di avviso (“interstitial”) che blocca le richieste programmatiche GET non interattive.

  • Il problema: L’Online Inspector fallirà la connessione poiché riceverà l’HTML della pagina di avviso invece dell’endpoint SSE.
  • La soluzione: È necessario istruire l’inspector a inviare l’header X-Tunnel-Skip-AntiPhishing-Page: true. La maggior parte degli inspector online avanzati dispone di una sezione “Custom Headers” nella configurazione della connessione.

4. Parametri di Connessione nell’Inspector Online

Accedendo a un servizio come inspector.mcp-use.com, la configurazione dovrà riflettere i seguenti parametri:

  • Transport Type: Selezionare Streamable HTTP (o SSE per implementazioni legacy).
  • URL: Inserire l’URL pubblico fornito da VS Code (es. https://xyz-3000.euw.devtunnels.ms/mcp).
  • Headers:
    • X-Tunnel-Skip-AntiPhishing-Page: true
    • Authorization: Bearer <token> (se il server implementa protezione).

5. Persistenza della Configurazione in VS Code (mcp.json)

Una volta validato il corretto funzionamento tramite l’inspector, è possibile aggiungere il server alla configurazione permanente di VS Code per l’utilizzo con GitHub Copilot o altri agenti locali.

Modificare il file .vscode/mcp.json nel workspace aggiungendo l’entry per il server remoto/tunnel:

{
  "servers": {
    "mcp-debug-server": {
      "type": "http",
      "url": "https://vostro-id-3000.euw.devtunnels.ms/mcp",
      "headers": {
        "X-Tunnel-Skip-AntiPhishing-Page": "true"
      }
    }
  }
}