# Next.js e WebMCP: la Skill che fa parlare al tuo sito parla la lingua degli agenti AI

13 ottobre 2026 — Alessandro Caprai

---

Ho passato gli ultimi mesi a sporcarmi le mani con WebMCP su caprai.dev, e devo ammettere che l'esperienza è stata illuminante. Non nel senso romantico del termine, ma in quello pratico: ho fatto errori, li ho corretti, e ora so esattamente cosa serve per rendere un sito Next.js davvero pronto per gli agenti AI che vivono nel browser.

Quando dico "agenti AI nel browser" mi riferisco a quegli assistenti che oggi cominciano a popolare Chrome, Edge e altri browser. Gemini che ti guarda mentre navighi, ChatGPT Desktop che cerca di capire cosa hai davanti. Il problema è che questi agenti, fino a ieri, erano come turisti senza mappa: dovevano indovinare come funziona un sito guardandone l'HTML, cercando di interpretare pulsanti, form e link senza alcuna guida.

## Ho creato una Skill

Da tutta questa esperienza ho creato una Skill attraverso la quale potrai facilmente guidare il tuo Coding Agent nello strutturare un WebMCP per un progetto Next.js e la puoi trovare qui <https://github.com/capraidev/nextjs-webmcp>

## WebMCP: il protocollo che mancava

WebMCP è lo standard che il W3C sta definendo per risolvere questo problema. L'idea è semplice ma potente: invece di lasciare che l'agente indovini, è il sito stesso a dichiarare cosa può fare. Posso cercare contenuti? Sì, ecco come. Voglio leggere un articolo? Usa questo strumento. Devo compilare un modulo? Ecco le regole.

Non è fantascienza, è pragmatismo. E implementarlo su Next.js, con tutti i suoi meccanismos di rendering e ottimizzazione, richiede un approccio chirurgico.

## Un registro unico: la lezione più importante

L'errore che ho commesso nella prima iterazione è stato quello che commettono tutti: descrivere gli strumenti in posti diversi. Una versione per il browser, una per il server, una per llms.txt, magari una quarta per documentazione futura. Il risultato? Divergenza garantita nel giro di una settimana.

La soluzione che ho adottato è un registro unico. Gli strumenti vengono descritti una volta sola, con schema completo, regole di validazione e limiti di utilizzo. Da quel registro centrale:

- Si generano gli strumenti disponibili nel browser
- Si alimenta la rotta API che li esegue lato server
- Si compila llms.txt per chi preferisce leggere testo
- Si prepara il terreno per futuri endpoint MCP remoti

Zero duplicazione, zero logica sparsa. Quando modifichi uno strumento, la modifica si propaga ovunque. È il tipo di architettura che ti fa dormire sonni tranquilli.

## Letture e scritture: una distinzione fondamentale

Una cosa che ho imparato osservando il comportamento degli agenti è che c'è una differenza sostanziale tra leggere e scrivere. Le operazioni di lettura, cercare articoli, consultare un catalogo, sono relativamente sicure. Rispettano le regole di accesso già presenti, non modificano nulla, non hanno conseguenze.

Le azioni con conseguenze reali, invece, restano dove devono stare: nei moduli visibili. L'agente può aiutarti a compilarli, può suggerirti cosa scrivere, ma il pulsante "invia" lo premi tu. Persona fisica, responsabilità fisica.

Iscrizione alla newsletter? L'agente compila i campi, tu confermi. Messaggio di contatto? Stesso meccanismo. Pagamenti, registrazioni, consensi al trattamento dati: tutto fuori, di proposito. Non perché non si possa fare tecnicamente, ma perché non si deve fare eticamente.

## Sicurezza e privacy: non sono optional

La prima volta che ho lanciato WebMCP su caprai.dev, PageSpeed mi ha subito fatto notare problemi con la Content Security Policy. I nonce, i Trusted Types, la Cross-Origin-Opener-Policy: tutti aspetti che in un'implementazione frettolosa si tende a ignorare o aggirare.

Invece vanno affrontati di petto. La skill che ho sviluppato include indicazioni precise su come far convivere WebMCP con una CSP rigorosa, come gestire i nonce dinamici in Next.js, come configurare i Trusted Types senza aprire buchi.

E poi ci sono le protezioni basilari ma essenziali: nessun dato personale nelle risposte degli strumenti, rate limiting per IP per evitare abusi, validazione severa degli input per prevenire prompt injection. Sono precauzioni che sembrano ovvie sulla carta, ma nella pratica richiedono attenzione costante.

## Dal codice alla produzione: il percorso completo

Una delle parti più delicate è stata la gestione dell'origin trial di Chrome ed Edge. Per chi non lo sapesse, WebMCP è ancora in fase sperimentale, e per attivarlo serve un token specifico per il proprio dominio. Su Vercel, questo token va configurato come variabile d'ambiente, con tanto di promemoria della scadenza.

Ho incluso nella skill:

- Template TypeScript pronti da adattare al proprio dominio
- Test automatici che verificano ogni strumento prima del deploy
- Controlli che impediscono regressioni silenziose
- Script per verificare quali strumenti espone ogni pagina
- Audit Lighthouse specifici per l'"Agentic browsing"

Quest'ultimo punto è stato una rivelazione. Lighthouse ha introdotto audit dedicati per verificare quanto un sito sia friendly verso gli agenti. Passarli tutti richiede cura, ma il feedback è immediato e prezioso.

## Gli errori che mi sono costati tempo

Vale la pena parlare anche di cosa non ha funzionato al primo tentativo. Ho provato a generare dinamicamente gli strumenti WebMCP in base al contesto della pagina. Idea interessante, implementazione disastrosa. Gli agenti si confondevano, gli strumenti cambiavano tra un rendering e l'altro, il caching diventava un incubo.

Soluzione: strumenti statici, sempre gli stessi, documentati chiaramente. Il contesto lo gestisci nei parametri, non nella disponibilità.

Altro errore: fidarsi ciecamente della validazione lato client. Gli agenti, per definizione, bypassano l'interfaccia visiva. Se la tua unica validazione è un form React, sei nei guai. Serve validazione severa lato server, con schema esplicito e messaggi d'errore chiari.

## Perché farlo, e perché farlo bene

Potresti chiederti se vale la pena investire tempo su uno standard ancora in definizione. La mia risposta, dopo averlo fatto, è sì. Non perché WebMCP diventerà sicuramente lo standard dominante, ma perché l'approccio che impone, dichiarare esplicitamente le capacità del tuo sito, è intrinsecamente sano.

Anche se WebMCP venisse sostituito da qualcos'altro domani, avere un registro centralizzato degli strumenti disponibili, validazione rigorosa, separazione netta tra lettura e scrittura, tutto questo resta valore. È architettura solida travestita da implementazione di uno standard.

E poi c'è il fatto che gli agenti AI nel browser sono qui per restare. Chiamiamoli WebMCP, chiamiamoli con un altro nome, ma l'esigenza di interfacciarsi in modo strutturato con i siti web non scomparirà. Meglio essere pronti ora, con un'implementazione pulita e verificata, che rincorrere dopo.

## Il futuro è conversazionale, ma deve essere sicuro

L'idea di un web dove gli agenti possono cercare, leggere, aiutarti a compilare form, è affascinante. Ma solo se fatto con criterio. Solo se la sicurezza e la privacy sono integrate dal giorno zero, non aggiunte come cerotto dopo.

La skill che ho messo a punto su caprai.dev rappresenta esattamente questo: un percorso completo, dagli errori alla soluzione, per rendere un sito Next.js pronto per questo futuro. Con codice di produzione, test, verifiche, e soprattutto con la consapevolezza di dove tracciare i confini.

Perché sì, vogliamo che gli agenti ci aiutino. Ma devono farlo rispettando le regole che noi, come creatori di esperienze web, decidiamo di imporre. WebMCP è lo strumento. Usarlo bene è responsabilità nostra.