Come funziona il server MCP di Guida

20 gennaio 2025 · 8 min di lettura ·

technical

Guida include un server Model Context Protocol (MCP) integrato. È ciò che permette a un’IA esterna, come Claude Code, Cursor o qualsiasi client compatibile con MCP, di controllare il browser. È il ponte tra “voglio estrarre dati da questa pagina” detto a un’IA e le query DOM, i clic e il salvataggio dati che lo rendono concreto.

Questo post è un approfondimento tecnico su come funziona. Vedremo il protocollo, il livello di trasporto, come vengono registrati gli strumenti e il modello di sicurezza a tre livelli che garantisce che l’IA non possa fare nulla senza la tua conoscenza e il tuo consenso.

Cos’è MCP, in breve

MCP è un protocollo JSON-RPC per collegare modelli IA a strumenti esterni. L’IA invia una richiesta come “chiama lo strumento Navigate con url: https://example.com”, il server la esegue e restituisce il risultato. Il modello non tocca mai direttamente il browser: vede solo il contratto input/output dello strumento.

Il protocollo definisce tre primitive:

Strumenti (Tools) — funzioni che l’IA può chiamare (navigare, fare clic, estrarre, ecc.)
Risorse (Resources) — dati che l’IA può leggere (schede aperte, contenuto pagina)
Prompt (Prompts) — modelli riutilizzabili per operazioni comuni

Guida implementa le primitive strumenti e risorse (tools e resources). Espone oltre 100 strumenti che coprono automazione del browser, archiviazione dati, ricerca e altro.

Trasporto: HTTP locale

MCP supporta più trasporti. Guida usa un trasporto HTTP locale: il server esegue un’istanza Kestrel integrata su http://127.0.0.1:9315.

La scelta di HTTP invece di stdio ha ragioni pratiche: Guida è un’app desktop WPF, non uno strumento CLI. Non ci sono stdin/stdout a cui collegarsi. HTTP permette anche a client MCP esterni di connettersi mentre interfaccia browser, stato delle autorizzazioni, cronologia attività e pannelli dello spazio di lavoro restano visibili.

Per i client HTTP streamable, l’endpoint utile è il root (/) del server:

http://127.0.0.1:9315/

La negoziazione iniziale è standard MCP: il client inizializza, il server restituisce le capacità disponibili, poi il client scopre gli strumenti e inizia a chiamarli.

Client → initialize
         {"jsonrpc": "2.0", "method": "initialize", ...}

Server → capabilities
         {"jsonrpc": "2.0", "id": 1, "result": {...}}

Client → tools/list
Client → tools/call

Registrazione degli strumenti

Gli strumenti vengono registrati in McpServerService.cs usando l’SDK MCP per .NET. Ogni strumento ha nome, descrizione, JSON Schema per i parametri e un gestore asincrono.

Ecco alcuni strumenti rappresentativi tra gli oltre 100 disponibili:

Strumento	Descrizione
`Navigate`	Naviga la scheda attiva verso un URL
`Click`	Fa clic su un elemento tramite selettore CSS
`GetElements`	Interroga elementi DOM ed estrae attributi
`Screenshot`	Cattura il viewport visibile come PNG
`ExecuteScript`	Esegue uno script `g.*` nel motore di scripting dell’app
`StoreGet` / `StorePut`	Legge/scrive nell’archiviazione dello spazio di lavoro
`QueueEnqueue` / `QueueDequeue`	Gestisce code di lavoro
`SearchQuery`	Ricerca testuale su documenti indicizzati

Sotto il cofano, la maggior parte degli strumenti delega agli stessi servizi che alimentano l’API di scripting g.*. Navigate chiama lo stesso BrowserAutomationService.NavigateAsync() usato da g.nav.navigateToUrl(). Il livello MCP è un adattatore sottile che mappa richieste JSON-RPC a chiamate di servizio e formatta i risultati.

Questo significa che script e strumenti IA hanno le stesse capacità, con una eccezione critica che vedremo nella sezione sicurezza.

Sicurezza a tre livelli

Qui Guida diverge dalla maggior parte dei server MCP. L’IA è potente, ma non è fidata. Ogni azione passa attraverso tre livelli di sicurezza prima di raggiungere il browser.

Livello 1: elenco dei domini autorizzati

Prima che l’IA possa navigare verso qualsiasi URL, il dominio deve essere nell’elenco dei domini autorizzati. Guida supporta tre livelli:

Per sessione — domini autorizzati che scadono quando chiudi l’app
Per spazio di lavoro — domini elencati in domains.json nella cartella dello spazio di lavoro
Globale — domini sempre consentiti (configurati nelle impostazioni)

Se l’IA prova a navigare verso un dominio non autorizzato, la chiamata allo strumento fallisce con un messaggio di errore chiaro. L’IA vede il rifiuto e può spiegare cosa è successo.

I caratteri jolly funzionano: *.example.com consente tutti i sottodomini. L’elenco dei domini autorizzati si applica solo alla navigazione scriptata; manualmente puoi navigare ovunque.

Livello 2: autorizzazione degli strumenti

Anche su un dominio consentito, le chiamate monitorate agli strumenti richiedono la tua autorizzazione esplicita. Quando l’IA vuole fare clic su un pulsante o eseguire uno script, Guida ti mostra:

Il nome esatto dello strumento chiamato
I parametri esatti (URL, selettore, codice script, ecc.)
Opzioni per autorizzare una volta, autorizzare per questa sessione o rifiutare

È lo stesso modello di permessi che ti aspetteresti da un’app mobile che chiede accesso alla fotocamera, ma per singola azione, non per installazione. Puoi considerare attendibile uno strumento per la sessione se sei stanco di cliccare approva, oppure rivedere ogni chiamata individualmente.

Il centro di autorizzazione mostra i parametri reali, non un riepilogo. Se l’IA vuole chiamare Click con selettore button.delete-account, vedrai quel selettore esatto prima dell’esecuzione.

Livello 3: registro di tracciabilità

Ogni chiamata agli strumenti viene registrata in mcp-audit.db: un database LiteDB separato a cui l’IA non può accedere. Il registro cattura:

Nome strumento e parametri (primi 4000 caratteri)
Risultato o errore (primi 2000 caratteri)
Durata di esecuzione
Timestamp e ID sessione

Il pannello Cronologia MCP (MCP History) nell’app mostra il registro di tracciabilità in tempo reale. Puoi cercare, filtrare per errori ed entrare nelle singole chiamate per vedere JSON completo di parametri e risultati.

La proprietà di sicurezza chiave: l’IA non può leggere o cancellare il proprio registro di tracciabilità. Non esistono strumenti MCP che espongano il database del registro. Questo significa che anche un’IA manipolata tramite prompt injection non può coprire le proprie tracce.

Protezione delle credenziali di accesso

Un altra misura di sicurezza merita attenzione. Guida ha un pannello Credenziali di accesso (Secrets) dove salvi chiavi API, password e token, cifrati con Windows DPAPI. Gli script possono leggere credenziali di accesso tramite g.secrets.getSecret(name), ma gli script di origine MCP non possono.

Quando uno script viene avviato tramite uno strumento MCP (come ExecuteScript), Guida lo marca con origine Mcp. Qualsiasi chiamata a g.secrets.getSecret() da uno script di origine MCP restituisce un errore. Questo spezza la catena di esfiltrazione:

IA chiama ExecuteScript → lo script chiama g.secrets.getSecret("api-key")
                        → BLOCCATO (origine MCP rilevata)

Senza questo controllo, un’IA manipolata tramite prompt injection potrebbe eseguire uno script che legge la tua chiave API, scriverla in g.store e poi leggere lo spazio di archiviazione tramite MCP. Il controllo dell’origine impedisce il primo passaggio.

Altre operazioni sulle credenziali di accesso (elencare nomi, impostare valori) sono consentite: è bloccata solo la lettura dei valori decrittati. Questo permette all’IA di aiutarti a gestire le credenziali di accesso senza mai vedere i valori effettivi.

Strumenti personalizzati

Oltre agli oltre 100 strumenti integrati, puoi definire strumenti HTTP personalizzati nel tools.json di uno spazio di lavoro:

{
  "tools": [
    {
      "name": "GetWeather",
      "description": "Ottieni il meteo attuale per una città",
      "endpoint": "https://api.weather.example/v1/current",
      "method": "GET",
      "parameters": {
        "city": { "type": "string", "description": "Nome della città", "required": true }
      },
      "headers": {
        "Authorization": "Bearer {{secrets.WEATHER_API_KEY}}"
      }
    }
  ]
}

Nota il segnaposto {{secrets.WEATHER_API_KEY}}. Il valore reale della credenziale di accesso viene iniettato dal server al momento della chiamata: l’IA non lo vede mai. Questo permette di dare all’IA accesso ad API autenticate senza esporre credenziali.

Gli strumenti personalizzati passano attraverso lo stesso flusso di autorizzazione degli strumenti integrati. L’IA vede lo schema dello strumento, propone una chiamata e tu approvi o rifiuti.

Riepilogo architetturale

Ecco come si incastrano i pezzi:

┌──────────────────────┐
│   Client IA          │  Claude Code, Cursor, ecc.
│   (Client MCP)       │
└──────────┬───────────┘
           │ MCP su HTTP locale
           │
┌──────────▼───────────┐
│   Server MCP Guida   │  Kestrel integrato su 127.0.0.1:9315
│                      │
│  ┌─ Filtro domini ─┐ │  Livello 1: controllo domini autorizzati
│  ├─ Centro autoriz.┤ │  Livello 2: utente approva/rifiuta
│  ├─ Logger registro┤ │  Livello 3: registra in mcp-audit.db
│  └─ Gestore strum. ┘ │  Esegue tramite servizi condivisi
│                      │
└──────────┬───────────┘
           │ Chiamate di servizio
           │
┌──────────▼───────────┐
│   Servizi condivisi  │  BrowserAutomation, archiviazione,
│                      │  code, ricerca, rete, cronologia, ecc.
└──────────┬───────────┘
           │
┌──────────▼───────────┐
│   Browser / WebView2 │  Motore browser basato su Chromium
└──────────────────────┘

Il server MCP è un livello adattatore sottile. Non duplica logica applicativa: mappa JSON-RPC sugli stessi servizi usati dagli script. I livelli di sicurezza (filtro domini, autorizzazione, registro) vengono inseriti come componenti intermedi nel flusso MCP.

Collegare un client

Per collegare Claude Code o un altro client MCP a Guida, aggiungi questo alla configurazione del client MCP:

{
  "mcpServers": {
    "guida": {
      "url": "http://127.0.0.1:9315/"
    }
  }
}

Fatto. Il client scopre gli strumenti disponibili tramite il metodo tools/list e inizia a chiamarli. Il centro di autorizzazione di Guida gestisce le richieste monitorate.

Per altri dettagli sugli strumenti disponibili e sulla configurazione dello spazio di lavoro, consulta la documentazione Integrazione MCP e la guida Strumenti personalizzati.