WordPress headless AI 2026: guida pratica decoupled con MCP

Perché headless + AI non è la stessa cosa del 2023

Headless WordPress non è una novità del 2026. Lo si faceva già nel 2018 con React e GraphQL, e nel 2022 era pane quotidiano per le agenzie che dovevano pubblicare su web, app e kiosk con lo stesso backend editoriale. Quello che è cambiato nel 2026 è la combinazione di tre cose: il Bridge AI introdotto con WordPress 7.0, il pattern MCP per i plugin WordPress che permette a un front-end esterno di chiamare le Abilities del core, e il fatto che Astro, Next.js 15 e Nuxt 4 sono ormai maturi abbastanza da poter essere deployati fianco a fianco a un'installazione WordPress senza dover reinventare la routing layer ogni volta.

Il risultato pratico è che oggi ha senso un sito dove WordPress fa solo da CMS + AI orchestration, e il front-end è una SPA o un sito statico con islands. Ma attenzione: questo non è gratis. In un progetto reale su cui ho lavorato a maggio, il cliente voleva "tutto headless con AI", poi dopo 6 settimane abbiamo capito che il 70% del budget era andato in plumbing (auth, preview, cache invalidation) e solo il 30% in feature utente. Questa guida serve a evitare quella trappola.

Si completa con la guida pratica al Bridge AI di WordPress 7.0, l'articolo sullo stack self-hosted per agent AI e il pattern MCP per plugin AI. L'obiettivo qui è operativo: come costruire un sito headless con AI senza pagare il prezzo del 2023.

Quando headless + AI ha senso (e quando no)

Casi dove conviene

Il primo caso è contenuto pubblicato su 3+ superfici: web, app mobile, email digest, newsletter RSS personalizzata. Il secondo è latenza editoriale sotto i 200ms su mobile 4G, che con un WordPress monolitico + cache Litespeed è borderline ma con Astro islands è naturale. Il terzo è team editoriale e team sviluppo separati, dove il team editoriale continua a usare l'admin WordPress e il team sviluppo lavora sul front-end senza dover toccare il tema. Il quarto è AI-assisted content generation massiva, dove il volume di articoli da generare (100-500 al mese) giustifica un front-end che può fare streaming della generazione invece di aspettare il rendering PHP di WordPress.

Casi dove NON conviene

Quando il sito è un blog personale, un sito corporate da 20 pagine, o un WooCommerce con catalogo sotto i 1000 prodotti: il monolite WP + cache + AI plugin è più veloce da consegnare, più economico da mantenere, e nessuno noterà la differenza di performance. Quando il team non ha competenze Next.js o Astro: pagare uno sviluppatore WordPress per imparare React/SSR è un investimento che si ripaga solo su 5+ progetti. Quando il budget è sotto i 15.000€: il break-even di headless + AI parte da lì.

Architettura: i 5 componenti di un setup reale

Un setup headless + AI funzionante ha 5 componenti. Ognuno ha una responsabilità precisa e tutti comunicano via API.

1. WordPress core + Bridge AI

WordPress fa solo due cose: custodisce i contenuti (custom post type, tassonomie, media) e orchestra le chiamate AI tramite il Bridge. Il Bridge è la Abilities API più il sistema di connettori che permette di autenticarsi con OpenAI, Anthropic o un provider self-hosted. Sul core non ci sono temi: il tema attivo è un tema minimale (Twenty Twenty-Five va bene) che serve solo a non rompere il wp-admin.

2. MCP server per WordPress

Il server MCP gira come plugin o come servizio separato e traduce le richieste del front-end in chiamate alla Abilities API. È il pezzo che permette al front-end di dire "generami 5 titoli per questo articolo" o "riscrivi questo paragrafo in italiano" senza dover scrivere un'integrazione custom per ogni use case. Il pattern MCP è descritto in dettaglio nel plugin ufficiale del WordPress Plugin Team.

3. Front-end: Next.js o Astro

Next.js 15 con App Router è la scelta predefinita se si vuole SSR + ISR + edge functions. Astro 4 con islands è la scelta predefinita se si vuole massima performance con minima JavaScript. La scelta tra i due è spesso filosofica: Next.js ha più developer tools, Astro ha output più snello. In entrambi i casi il front-end consuma i contenuti via REST API o GraphQL e chiama il server MCP via HTTPS.

4. Caching e invalidation

Il caching è il pezzo che fa la differenza tra un sito che regge 1000 RPS e uno che crolla a 200. Il pattern corretto è: cache HTML sul CDN (Cloudflare o Fastly), cache JSON su Redis per le risposte GraphQL/REST, invalidation on publish via webhook dal Bridge AI. Il "on publish" è critico: se pubblichi un articolo e il CDN continua a servire la versione vecchia per 5 minuti, hai un bug.

5. Monitoring e observability

Servono almeno 4 metriche: TTFB per le pagine renderizzate, hit ratio del CDN, latenza del server MCP, e tasso di errore delle chiamate AI. Strumenti come Sentry + Better Stack + una dashboard Grafana coprono il caso medio. Sui progetti grossi conviene anche un log delle Abilities invocate per capire quale use case AI sta crescendo.

Setup pratico: Next.js 15 + WordPress 7.0 + MCP

Vediamo il setup minimo funzionante. Non è un Hello World: è la versione che ho messo in produzione a marzo 2026 per un cliente editoriale con 80.000 articoli.

Installazione e auth

# 1. Crea progetto Next.js con App Router
npx create-next-app@latest headless-wp \
  --typescript --app --src-dir --import-alias "@/*" --no-tailwind

# 2. Installa dipendenze
cd headless-wp
npm install graphql-request @anthropic-ai/sdk

# 3. Setup variabili ambiente
cat > .env.local <<EOF
WORDPRESS_API_URL=https://cms.example.com/wp-json
WORDPRESS_PREVIEW_TOKEN=...
MCP_SERVER_URL=https://cms.example.com/wp-json/mcp/v1
ANTHROPIC_API_KEY=sk-ant-...
EOF

# 4. Test connessione MCP
curl -sS -X POST "$MCP_SERVER_URL" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}' | jq

Lettura contenuti da WordPress

// src/lib/wordpress.ts
import { GraphQLClient, gql } from 'graphql-request';

const client = new GraphQLClient(
  `${process.env.WORDPRESS_API_URL}/graphql`,
  { headers: { Authorization: `Bearer ${process.env.WORDPRESS_PREVIEW_TOKEN}` } }
);

export async function getPostBySlug(slug: string) {
  const query = gql`
    query GetPost($slug: ID!) {
      post(id: $slug, idType: SLUG) {
        title
        content
        excerpt
        date
        author { node { name } }
        featuredImage { node { sourceUrl altText } }
      }
    }
  `;
  const data = await client.request(query, { slug });
  return data.post;
}

export async function listPosts(first = 20) {
  const query = gql`
    query ListPosts($first: Int!) {
      posts(first: $first) {
        nodes { id slug title excerpt date }
      }
    }
  `;
  const data = await client.request(query, { first });
  return data.posts.nodes;
}

Chiamata MCP per generazione AI

// src/lib/mcp-client.ts
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

export async function generatePostOutline(topic: string, audience: string) {
  const response = await client.messages.create({
    model: 'claude-sonnet-4-5',
    max_tokens: 2000,
    system: 'Se un editor senior italiano. Rispondi in italiano. Output JSON valido.',
    messages: [{
      role: 'user',
      content: `Genera outline per articolo su: ${topic}. Target: ${audience}. Restituisci JSON con title, slug, sections (array di {h2, paragraphs}), tags (array), excerpt (max 160 caratteri).`
    }]
  });
  const text = response.content[0].type === 'text' ? response.content[0].text : '';
  return JSON.parse(text);
}

export async function callWordPressAbility(abilityName: string, args: unknown) {
  // Chiama il server MCP che internamente parla con la Abilities API
  const response = await fetch(`${process.env.MCP_SERVER_URL}/abilities/${abilityName}`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${process.env.WORDPRESS_PREVIEW_TOKEN}`
    },
    body: JSON.stringify(args)
  });
  if (!response.ok) throw new Error(`Ability ${abilityName} failed: ${response.status}`);
  return response.json();
}

Pagina con rendering ibrido

// src/app/posts/[slug]/page.tsx
import { getPostBySlug, listPosts } from '@/lib/wordpress';
import { generatePostOutline } from '@/lib/mcp-client';

export const revalidate = 300; // ISR: rigenera ogni 5 minuti

export async function generateStaticParams() {
  const posts = await listPosts(100);
  return posts.map(p => ({ slug: p.slug }));
}

export default async function PostPage({ params }: { params: { slug: string } }) {
  const post = await getPostBySlug(params.slug);
  return (
    <article>
      <h1>{post.title}</h1>
      <div dangerouslySetInnerHTML={{ __html: post.content }} />
    </article>
  );
}

Cache invalidation: il pezzo che salva il progetto

La parte più noiosa ma più importante è la cache invalidation. Il pattern che funziona è duplice: webhook da WordPress al front-end quando un post viene pubblicato, e ISR/On-demand revalidation su Next.js.

// src/app/api/revalidate/route.ts
import { revalidateTag, revalidatePath } from 'next/cache';

export async function POST(request: Request) {
  const { slug, type } = await request.json();
  const secret = request.headers.get('x-webhook-secret');
  if (secret !== process.env.WORDPRESS_WEBHOOK_SECRET) {
    return Response.json({ error: 'unauthorized' }, { status: 401 });
  }
  if (type === 'post.updated' || type === 'post.created') {
    revalidatePath(`/posts/${slug}`);
    revalidateTag('posts-list');
  }
  return Response.json({ revalidated: true });
}

Sul lato WordPress serve un mu-plugin che invia il webhook.

<?php
/**
 * Plugin: Headless cache invalidation webhook
 * Invia webhook al front-end Next.js quando un post cambia
 */

add_action('save_post', function ($post_id) {
    if (wp_is_post_revision($post_id)) return;
    if (defined('DOING_AUTOSAVE') && DOING_AUTOSAVE) return;

    $post = get_post($post_id);
    if ($post->post_status !== 'publish') return;

    $webhook_url = WP_HEADLESS_FRONTEND . '/api/revalidate';
    wp_remote_post($webhook_url, [
        'headers' => [
            'Content-Type' => 'application/json',
            'X-Webhook-Secret' => WP_HEADLESS_SECRET,
        ],
        'body' => wp_json_encode([
            'slug' => $post->post_name,
            'type' => $post->post_modified_gmt !== $post->post_date_gmt
                ? 'post.updated' : 'post.created',
        ]),
        'timeout' => 5,
        'blocking' => false,
    ]);
});

Quattro errori che ho già fatto (e che puoi evitare)

Errore 1: pensare che headless = più veloce

Non è automaticamente vero. Il primo progetto headless + AI che ho consegnato aveva un TTFB peggiore del monolite perché il front-end non cachava niente e WordPress rifaceva la query GraphQL ogni volta. La cache va progettata dal giorno uno, non aggiunta dopo.

Errore 2: usare GraphQL per tutto

GraphQL è elegante ma ha un costo di complessità non trascurabile. REST API con ?_fields= per ridurre il payload è spesso più che sufficiente e debuggabile con curl. GraphQL lo consiglio solo se ci sono davvero query eterogenee (es. mobile + web che chiedono cose diverse).

Errore 3: non gestire la preview

La preview è il pezzo che rompe tutti i progetti headless. Un editor clicca "Preview" in WordPress, si aspetta di vedere l'articolo come apparirà sul sito, e invece vede un 404 o un 500 perché il front-end non sa come renderizzare un draft. Soluzione: autenticare la preview con un token condiviso, rigenerare la pagina on-demand, e non cachare le preview.

Errore 4: credere che l'AI sostituisca il ruolo editoriale

L'AI genera outline e bozze in 10 secondi. L'editor le riscrive in 30 minuti, le critica, le integra con la linea editoriale, le testa sui social. Il guadagno di tempo reale è del 40-60%, non del 90%. Su un articolo di 2500 parole il saving è di 30 minuti, non di 2 ore.

Quando NON serve MCP

Per un sito corporate da 30 pagine senza generazione AI massiva, MCP è overkill. Bastano i plugin AI classici (Jetpack AI, AI Engine, Content AI di RankMath) installati sul WordPress monolitico. MCP diventa utile quando:

• Il volume di contenuti generati supera i 50/mese
• Il team editoriale vuole workflow AI-assisted strutturati (revision, brand voice check, fact-checking)
• Ci sono 3+ front-end che consumano contenuti
• Il budget del progetto è sopra i 30.000€

Costi reali di un progetto headless + AI nel 2026

I numeri che seguono sono da un progetto reale, cliente editoriale italiano, 80.000 articoli, team di 4 persone (1 dev WordPress, 1 dev Next.js, 1 editor, 1 AI specialist), 5 mesi di lavoro. Sono indicativi.

La manutenzione del primo anno aggiunge circa il 20-25% (hosting + piccoli fix + aggiornamenti).

Confronto rapido: headless vs monolitico per siti AI 2026

Un confronto sintetico per decidere al volo. Non sostituisce l'analisi del caso specifico, ma dà un'idea.

Domande frequenti

WordPress 7.0 è obbligatorio per headless + AI? Sì, nella mia esperienza. Il Bridge AI introdotto con 7.0 è il pezzo che rende MCP naturale invece di forzato. Su WordPress 6.x si può fare, ma serve scrivere plugin custom per orchestrare i connettori AI e il setup è molto più verboso.

Posso usare Astro invece di Next.js? Sì, Astro è ottimo per siti dove la maggior parte delle pagine è statica e solo l'admin WordPress è dinamico. Astro + WordPress è una combo meno diffusa ma ben supportata. La scelta tra Next.js e Astro è più su SSR vs statico che su WordPress-specifico.

Quanto è stabile MCP nel 2026? Il protocollo è stabile da inizio 2025, e il plugin ufficiale del Plugin Team è production-ready. Ci sono ancora edge case nelle Abilities custom registrate da plugin di terze parti, ma il path principale (Bridge AI + MCP server + front-end che consuma) è solido.

Posso migrare un sito monolitico esistente a headless + AI senza riscriverlo? Sì, ma è un progetto di 2-4 settimane solo per la migrazione. Il primo passo è mettere il front-end dietro a WordPress senza toccare il tema WP, poi spostare i template gradualmente. Non è un weekend project.

L'AI può scrivere articoli completi in autonomia? Sì, tecnicamente può. Il problema è qualità, fact-checking, e allineamento con la linea editoriale. Nella mia esperienza serve sempre un editor umano che fa review di 15-30 minuti per articolo.

Riferimenti utili per approfondire

• Bridge AI WordPress 7.0 plugin production-ready 2026 - architettura del Bridge su cui si basa MCP.
• Plugin AI WordPress con MCP e abilities pattern ufficiale - il pattern Plugin Team per connettori MCP.
• Stack AI agent WordPress self-hosted 2026 - alternativa self-hosted al front-end cloud.
• WordPress 7.1 guida pratica aggiornamento 2026 - requisiti core per il setup.
• WooCommerce agentic commerce 2026 - caso d'uso headless + agent su WooCommerce.
• AI tools sviluppatore WordPress workflow 2026 - toolchain AI per chi sviluppa headless.
• Kinsta Blog - What Is Headless WordPress - introduzione canonica a headless WP.
• Anthropic MCP documentation - reference ufficiale del protocollo MCP.
• Next.js 15 App Router docs - documentazione ufficiale per il front-end.
• Astro WordPress integration - alternativa statica a Next.js.
• Vercel ISR on-demand revalidation - come gestire cache invalidation.
• WP GraphQL plugin - il plugin GraphQL per WordPress usato nell'esempio.