Guida WebMCP
Guida WebMCP
WebMCP è lo standard proposto da ingegneri di Microsoft e Google per far dichiarare ai siti web le proprie funzioni agli agenti AI del browser, con due API: una dichiarativa (HTML) e una imperativa (JavaScript). In questa guida trovi origine, funzionamento, vantaggi e limiti, più due sezioni pratiche: il test con i flag sperimentali di Chrome e il codice per il tuo sito vetrina. Contenuti verificati sulla documentazione alla data dell’articolo.
Indice dei contenuti – Guida WebMCP
1. Cos’è WebMCP e perché interessa ora
2. Quando nasce WebMCP: la cronologia
3. A cosa serve WebMCP (e quando non usarlo)
4. Le caratteristiche fondamentali
5. Le modalità principali: API dichiarativa e API imperativa
6. Pratica 1: testare WebMCP con i flag sperimentali di Chrome
7. Pratica 2: preparare il codice HTML/JS del sito aziendale vetrina
8. Vantaggi e svantaggi attuali
10. Conclusioni: formazione continua e Corsi IT di Innovaformazione
1. Cos’è WebMCP e perché interessa ora
Lunedì mattina Giulia, sviluppatrice in una PMI, trova in chat lo screenshot del titolare. Aveva chiesto all’assistente AI del browser di compilare il modulo “Richiedi preventivo” del loro sito. L’agente ha spezzato “nome e cognome” nei campi sbagliati, ha scelto il servizio errato dal menu a tendina e ha inviato tutto con un clic. Il sito funziona e i test passano. Ma è stato disegnato per occhi umani, non per agenti.
Pensa a un turista in una città senza cartelli stradali: legge le insegne, deduce, tira a indovinare. Oggi gli agenti fanno lo stesso con le pagine web: analizzano DOM e screenshot e simulano clic e digitazione. La documentazione di Chrome lo definisce un processo con molti passaggi, ciascuno lasciato all’interpretazione dell’agente. WebMCP mette i cartelli: è il sito a dichiarare lo scopo di ogni funzione.
WebMCP (Web Model Context Protocol) è uno standard web proposto per creare ed esporre strumenti strutturati agli agenti AI. Il sito registra dei tool come cerca_servizi o richiedi_preventivo, ciascuno con nome, descrizione e schema JSON dei parametri. L’agente li scopre e li chiama come funzioni, invece di indovinare dove cliccare. Gli strumenti si eseguono in modo visibile nella pagina: l’utente vede cosa succede e il design resta quello che hai progettato.
Per chi sviluppa il vantaggio è doppio. L’agente diventa più preciso e più veloce, perché non deve dedurre il significato di un pulsante: lo legge da una definizione. E tu mantieni il controllo, perché decidi quali azioni esporre, con quali parametri e con quali conferme. Non cambia il modo in cui il sito si presenta agli utenti: WebMCP si può aggiungere come potenziamento progressivo, uno strumento alla volta, partendo dalle funzioni più usate.
Una precisazione di stato: WebMCP è oggi in origin trial e la documentazione ufficiale avverte che potrebbe cambiare. È il momento giusto per sperimentare, non per mettere in produzione senza rete.
2. Quando nasce WebMCP: la cronologia
Il progetto ha meno di un anno e un ritmo di evoluzione elevato. Le tappe, ricostruite dalle fonti ufficiali:
- 13 agosto 2025: prima pubblicazione dell’explainer su GitHub, a firma di ingegneri di Microsoft e Google. La specifica vive nel repository webmachinelearning/webmcp, quello della community Web Machine Learning del W3C.
- 10 febbraio 2026: il team Chrome annuncia l’anteprima tramite early preview program e presenta le due API, dichiarativa e imperativa.
- 18 maggio 2026: la documentazione debutta su Chrome for Developers.
- 9 giugno 2026: parte l’origin trial in Chrome 149. Anche Edge ha un origin trial, dalla versione 150.
- Ottobre 2026: la documentazione è ancora in aggiornamento (pagina principale il 7 ottobre, API imperativa il 16 ottobre).
Un dettaglio da annotare: le prime versioni della documentazione usavano navigator.modelContext, oggi gli esempi ufficiali usano document.modelContext. È la prova concreta che lavoriamo su un’API in movimento.
3. A cosa serve WebMCP (e quando non usarlo)
WebMCP trasforma le funzioni di una pagina in azioni affidabili per l’agente, mentre l’utente è presente e supervisiona. Gli esempi della documentazione ufficiale:
- Assistenza clienti: l’agente raggiunge il modulo giusto e compila i campi con i dati forniti dall’utente.
- Prenotazioni complesse: viaggi con più città e più passeggeri in meno passaggi.
- Moduli strutturati: uno strumento submit_application distingue, ad esempio, un campo “nome completo” da due campi separati.
- Interfacce per umani: uno strumento date_pick gestisce selezioni di data e ora complesse.
- Debug: uno strumento run_diagnostics attiva correzioni nascoste in menu annidati.
L’explainer aggiunge e-commerce con filtri, editor grafici e perfino code review: nell’esempio su Gerrit, gli strumenti leggono gli stati dei trybot e i log di errore.
Per un sito vetrina aziendale gli scenari sono concreti: cercare un servizio nel catalogo, prenotare una consulenza, aprire una richiesta di assistenza, scaricare una scheda tecnica. Sono azioni che un visitatore già compie a mano e che un agente, con strumenti ben descritti, esegue senza errori di interpretazione.
WebMCP non sostituisce MCP. La documentazione usa un’analogia efficace: MCP è il call center, raggiungibile ovunque e sempre; WebMCP è l’esperto in negozio, disponibile solo quando il cliente è nel punto vendita. MCP serve il backend: è persistente, headless e universale. WebMCP serve il frontend: vive nella scheda aperta, accede a sessione, cookie e DOM, e scompare alla chiusura della scheda. Le applicazioni più efficaci li combinano: logica di business su MCP, esperienza contestuale su WebMCP.
Quando non usarlo: nei flussi headless o completamente autonomi (l’API è pensata per workflow locali con un umano), nei servizi che devono essere sempre disponibili anche a scheda chiusa (lì serve MCP) e, senza refactoring, nei siti molto complessi, dove devi gestire lo stato dell’interfaccia.
4. Le caratteristiche fondamentali – Guida WebMCP
Cinque pilastri tecnici e tre meccanismi di controllo, secondo la documentazione ufficiale:
- Rilevamento: un modo standard per registrare gli strumenti della pagina, ad esempio checkout o filter_results.
- Schemi JSON: input e output espliciti, per ridurre allucinazioni e malintesi.
- Stato: una comprensione condivisa del contesto corrente della pagina.
- Human-in-the-loop: gli strumenti si eseguono in modo visibile; per le azioni sensibili puoi chiedere una conferma all’utente.
- Potenziamento progressivo: se uno strumento non basta, l’agente può ripiegare sull’automazione tradizionale. Il sito non cambia per gli utenti umani.
- Annotazioni: readOnlyHint (nessuna modifica di stato), untrustedContentHint (output con contenuti non attendibili), consequentialHint (azioni irreversibili) e debugging (strumenti per sviluppatori, da Chrome 156).
- Controllo dell’origine: la permissions policy tools vale self per impostazione predefinita; negli iframe cross-origin serve allow=”tools”. Le opzioni exposedTo e fromOrigins regolano chi vede cosa.
- Budget di caratteri consigliati: 500 per la descrizione dello strumento, 150 per quella dei parametri, 30 per i nomi, 1.500 per l’output.
Il rischio principale è la indirect prompt injection: gli LLM trattano istruzioni e dati come un’unica sequenza di token, e la documentazione ammette che dentro un LLM la sicurezza non si può garantire. Per questo contano le annotazioni, la sobrietà nelle descrizioni e l’esposizione di pochi strumenti, solo a origini fidate.
5. Le modalità principali: API dichiarativa e API imperativa
API dichiarativa: la presa standard. In casa non serve un elettricista per usare una presa. Qui basta annotare un normale <form>: toolname e tooldescription ne definiscono nome e scopo, toolparamdescription descrive i singoli campi. Il browser traduce il form in uno schema JSON; quando l’agente chiama lo strumento, mette a fuoco il form e compila i campi, che restano visibili. L’invio può restare manuale oppure partire in automatico con toolautosubmit. Nell’evento submit, agentInvoked ti dice se l’invio arriva da un agente e respondWith() restituisce l’esito. Hai inoltre gli eventi toolactivated e toolcancel e le pseudo-classi CSS :tool-form-active e :tool-submit-active per il feedback visivo.
API imperativa: l’impianto su misura. Quando serve JavaScript (ricerche, navigazione, gestione dello stato), usi document.modelContext.registerTool() con nome, descrizione, inputSchema ed execute. Un AbortSignal consente di deregistrare lo strumento e di annullare esecuzioni in corso. Con getTools() e executeTool() scopri ed esegui gli strumenti, mentre l’evento toolchange segnala le variazioni dell’elenco. Per TypeScript esiste il pacchetto webmcp-types; React, Vue e Angular hanno supporti sperimentali.
Le due modalità non sono alternative: un sito reale usa spesso il dichiarativo per i form e l’imperativo per tutto il resto.
6. Pratica 1: testare WebMCP con i flag sperimentali di Chrome
Iniziamo con una parte pratica della nostra Guida WebMCP.
Giulia vuole vedere WebMCP in azione prima di toccare il sito. Ecco il suo percorso, valido su Windows, macOS e Linux. Usa un profilo Chrome dedicato ai test: le estensioni possono eseguire strumenti WebMCP tramite content script.
- Aggiorna Chrome. L’origin trial parte da Chrome 149; per lo sviluppo locale basta il flag. Meglio una versione recente, perché alcune funzioni arrivano solo in release successive (ad esempio debugging da Chrome 156).
- Attiva il flag. Apri chrome://flags/#enable-webmcp-testing, imposta Enabled e riavvia Chrome.
- Verifica in Console. Apri DevTools su una pagina https o localhost e incolla lo snippet qui sotto: registra uno strumento, lo elenca e lo esegue.
// Incolla nella Console di DevTools (flag attivo, pagina https o localhost)
if (!("modelContext" in document)) {
console.warn("WebMCP non disponibile: controlla il flag e riavvia Chrome");
} else {
const controller = new AbortController();
// Registra uno strumento di prova
await document.modelContext.registerTool({
name: "saluta",
description: "Restituisce un saluto per il nome indicato.",
inputSchema: {
type: "object",
properties: { nome: { type: "string", description: "Nome della persona" } },
required: ["nome"],
},
annotations: { readOnlyHint: true },
execute: async ({ nome }) => `Ciao ${nome}, WebMCP funziona!`,
}, { signal: controller.signal });
// Elenca gli strumenti visibili e lancia quello appena creato
const tools = await document.modelContext.getTools();
console.table(tools.map((t) => ({ nome: t.name, origine: t.origin })));
const tool = tools.find((t) => t.name === "saluta");
console.log(await document.modelContext.executeTool(tool, { nome: "Dario" }));
// controller.abort(); // decommenta per deregistrare lo strumento
}
- Apri il pannello WebMCP. In DevTools vai su Application > WebMCP. Vedi gli “Strumenti disponibili” con contatore di chiamate, il registro degli “Strumenti chiamati” con input e output, e puoi testare uno strumento a mano senza passare dall’agente. Il filtro distingue strumenti dichiarativi e imperativi.
- Prova le demo ufficiali. Nel repository GoogleChromeLabs/webmcp-tools trovi WebMCPza Maker (API imperativa), una demo di viaggi in React e Le Petit Bistro (API dichiarativa). La demo di prenotazione appuntamenti confronta lo scraping del DOM con la chiamata di uno strumento.
- Simula un agente. Hai tre strade: l’estensione Model Context Tool Inspector (richiede una chiave API Gemini), l’estensione agentica di esempio (un piccolo server Node con le chiavi nel file .env) oppure un modello locale con la Prompt API, attivando chrome://flags/#prompt-api-tool-use: nessuna chiave e dati sul dispositivo.
- Facoltativo: origin trial. Per provare WebMCP sul tuo dominio, registra l’origine dalla pagina Origin trials di Chrome e inserisci il token come in ogni origin trial. Ricorda che è un programma a tempo, con possibili limiti di utilizzo.
7. Pratica 2: preparare il codice HTML/JS del sito aziendale vetrina
Proseguiamo la nostra Guida WebMCP nel pratico. Torniamo al modulo di Giulia. Obiettivo: far compilare correttamente la richiesta di preventivo e far cercare i servizi a un agente, senza peggiorare nulla per chi non usa agenti. Il metodo ha cinque mosse:
- Scegli poche azioni utili: due o tre strumenti bastano per un sito vetrina.
- Annota i form esistenti con toolname e tooldescription.
- Registra gli strumenti JavaScript dopo un controllo di compatibilità (“modelContext” in document).
- Rispetta i budget di caratteri e usa le annotazioni: readOnlyHint per le letture, consequentialHint per azioni irreversibili.
- Verifica nel pannello WebMCP e con un agente di prova.
Il codice completo, da salvare in una pagina HTML (i dati dei servizi sono d’esempio):
<!-- 1) API DICHIARATIVA: il form diventa lo strumento "richiedi_preventivo" -->
<form id="form-preventivo" action="/api/preventivo" method="post"
toolname="richiedi_preventivo"
tooldescription="Invia una richiesta di preventivo all'azienda. Servono nome, email e servizio di interesse.">
<label for="nome">Nome e cognome</label>
<input id="nome" name="nome" type="text" required>
<label for="email">Email</label>
<input id="email" name="email" type="email" required>
<label for="servizio">Servizio</label>
<select id="servizio" name="servizio" required
toolparamdescription="Servizio per cui si richiede il preventivo.">
<option value="sviluppo-web">Sviluppo sito web</option>
<option value="consulenza">Consulenza</option>
<option value="formazione">Formazione</option>
</select>
<label for="messaggio">Messaggio</label>
<textarea id="messaggio" name="messaggio" maxlength="500"
toolparamdescription="Dettagli della richiesta, massimo 500 caratteri."></textarea>
<!-- Niente toolautosubmit: l'invio resta una scelta dell'utente -->
<button type="submit">Invia richiesta</button>
<p id="esito" role="status"></p>
</form>
<script>
// Invio del form: vale sia per utenti sia per agenti
const form = document.getElementById("form-preventivo");
form.addEventListener("submit", (e) => {
e.preventDefault(); // necessario per usare respondWith()
const invio = fetch(form.action, { method: "POST", body: new FormData(form) })
.then((r) => (r.ok ? "Richiesta inviata. Ti risponderemo via email." : "Errore: richiesta non inviata."))
.catch(() => "Errore di rete: riprova più tardi.");
invio.then((msg) => { document.getElementById("esito").textContent = msg; });
if (e.agentInvoked) e.respondWith(invio); // restituisce l'esito all'agente
});
</script>
<script>
// 2) API IMPERATIVA: strumenti JavaScript (potenziamento progressivo)
const SERVIZI = [ // dati d'esempio: sostituiscili con una fetch al tuo endpoint
{ id: "web", titolo: "Sviluppo sito web aziendale", tag: "sito vetrina cms" },
{ id: "cons", titolo: "Consulenza tecnica e architetture", tag: "consulenza cloud" },
{ id: "form", titolo: "Formazione per team IT", tag: "formazione corsi" },
];
async function registraStrumenti() {
// Browser senza WebMCP: il sito funziona come sempre
if (!("modelContext" in document)) return;
try {
await document.modelContext.registerTool({
name: "cerca_servizi",
description: "Cerca nel catalogo servizi dell'azienda per parola chiave. Massimo 5 risultati.",
inputSchema: {
type: "object",
properties: { query: { type: "string", description: "Parola chiave, es. formazione" } },
required: ["query"],
},
annotations: { readOnlyHint: true }, // non modifica lo stato
execute: async ({ query }) => {
const q = query.toLowerCase();
const risultati = SERVIZI
.filter((s) => (s.titolo + " " + s.tag).toLowerCase().includes(q))
.slice(0, 5);
return JSON.stringify(risultati); // output breve (consigliati max 1.500 caratteri)
},
});
await document.modelContext.registerTool({
name: "vai_a_preventivo",
description: "Porta l'utente al modulo di richiesta preventivo e lo mette a fuoco.",
execute: async () => {
form.scrollIntoView({ behavior: "smooth" });
document.getElementById("nome").focus();
return "Modulo di preventivo in vista.";
},
});
} catch (err) {
console.warn("WebMCP: registrazione non riuscita", err);
}
}
registraStrumenti();
</script>
Due scelte meritano una nota. Il form non usa toolautosubmit, perché una richiesta commerciale deve restare una decisione dell’utente. Gli strumenti di sola lettura dichiarano readOnlyHint, così l’agente li chiama senza chiedere conferme. Se un domani aggiungi uno strumento che invia dati o cancella qualcosa, imposta consequentialHint: true.
8. Vantaggi e svantaggi attuali – Guida WebMCP
Il bilancio di oggi, in sintesi:
| Vantaggi | Svantaggi |
| Affidabilità: chiamate a funzioni esplicite al posto di clic simulati. | Instabilità: origin trial, API soggetta a modifiche e deprecazioni. |
| Schemi JSON espliciti: meno ambiguità e allucinazioni. | Supporto: Chrome ed Edge in origin trial; Firefox e Safari non risultano ancora implementati. |
| Riuso del codice front-end, senza backend dedicato. | Refactoring: i siti complessi richiedono gestione dello stato e JavaScript aggiuntivo. |
| Resistenza ai redesign: gli strumenti seguono la logica, non il layout. | Ambito: pensato per flussi locali con un umano; headless e agenti autonomi non sono l’obiettivo. |
| Controllo e trasparenza: esecuzione visibile, annotazioni, permissions policy. | Sicurezza: esposto alla prompt injection indiretta; servono disciplina su descrizioni, output e origini. |
| Debug dedicato: pannello DevTools e test manuale degli strumenti. | Rilevabilità: gli strumenti si scoprono solo visitando il sito; il ciclo di vita è legato alla scheda. |
La lettura corretta per un team tecnico: i vantaggi sono reali e verificabili in laboratorio, gli svantaggi riguardano soprattutto maturità e diffusione. Significa investire poco ma subito, con prototipi isolati, per farsi trovare pronti quando l’API si stabilizzerà.
9. Scenari futuri per il web – Guida WebMCP
Entriamo nel finale della Guida WebMCP. Dove può portare il web? Le direzioni arrivano dai temi aperti nell’explainer ufficiale:
- Standard davvero cross-browser: l’obiettivo dichiarato è un’API implementabile da qualsiasi browser con capacità agentiche. Edge ha già un origin trial; Mozilla e WebKit hanno aperto discussioni sulla posizione di standard.
- Contratti più ricchi: outputSchema, validazione nativa degli schemi, streaming e input/output multimodali.
- Consenso e coordinamento: richiesta di input all’utente durante l’esecuzione (requestUserInteraction() è nella bozza) e “skill” di alto livello per orchestrare più strumenti.
- Service worker: scoperta degli strumenti anche su siti non aperti, un cambio di passo rispetto al limite attuale della scheda attiva.
- Siti a doppia interfaccia: la stessa pagina servirà persone e agenti, con strumenti testati nel ciclo di sviluppo come oggi si testano le API.
Nessuna di queste direzioni è garantita: sono proposte in discussione pubblica e possono cambiare. Chi segue GitHub, Chrome Status e la documentazione ufficiale ha però un vantaggio chiaro: vede arrivare i cambiamenti mesi prima di doverli subire.
10. Conclusioni: formazione continua e Corsi IT di Innovaformazione
Il lunedì dopo, Giulia ha aggiunto quattro attributi al modulo e due strumenti JavaScript. L’agente del titolare ha compilato il preventivo al primo tentativo. La tecnologia non era complicata: serviva sapere che esisteva.
Questo è il punto. In cinque mesi, WebMCP è passato dall’anteprima all’origin trial, ha cambiato la superficie dell’API da navigator a document e ha già deprecato alcune funzioni, come gli argomenti di input in stringa JSON (da Chrome 155) e window.ontoolactivated (non supportato da Chrome 156). Un team che non si aggiorna accumula debito tecnico in settimane. Solo la formazione continua garantisce un alto standard di aggiornamento. Inoltre l’AI è ormai entrata nel lavoro quotidiano degli sviluppatori, dalla scrittura del codice al test, e usarla bene è una competenza da costruire.
La formazione continua non significa inseguire ogni novità, ma costruire un metodo: sapere dove leggere le fonti ufficiali, saper prototipare in poche ore, valutare rischi di sicurezza e decidere cosa portare in produzione. È un lavoro di squadra e funziona meglio quando è guidato, con esempi sul codice reale dell’azienda.
Innovaformazione propone Corsi IT rivolti alle aziende, per team che vogliono restare al passo con strumenti e standard emergenti:
Un corso WebMCP per aziende è attivabile su richiesta. Per un preventivo o per maggiori informazioni scrivi a info@innovaformazione.net oppure chiama il 347 1012275 (Dario Carrassi).
Ci auguriamo abbiate apprezzato la nostra Guida WebMCP.
Per altri articoli tecnici di settore consigliamo di navigare sul nostro blog QUI.
Articoli correlati
Claude Code con Arduino
Novità .Net 11
Backdoor nei modelli AI open-weight
Opportunità di lavoro Bari
Spieghiamo il Weight space programming
