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.

A giugno 2026, Automattic ha annunciato che l'accesso MCP di WordPress.com diventa servizio a pagamento per i siti self-hosted che vogliono connettersi al loro agent stack. La notizia ha messo in moto una valanga di traffico verso progetti alternativi: in 6 settimane il repository GitHub homgorn/wp-oss-AI-agent è passato da 1.200 a 14.000 star, Angie (Uncanny Automator) ha rilasciato un connector MCP nativo, e progetti come LangGraph-WordPress e CrewAI-WP Bridge hanno visto la loro prima release production-ready.

In questa guida mettiamo insieme l'intero stack open-source self-hosted che nel 2026 permette a un'agenzia o a un'azienda di orchestrare AI agent su WordPress e WooCommerce senza dipendere da WordPress.com, senza vendor lock-in, e con costi operativi pari a un VPS da 20€/mese. Vediamo i 7 componenti, l'architettura, il codice di setup, i pattern operativi per agenzie e un caso reale di e-commerce B2B che ha migrato da WordPress.com MCP a stack self-hosted in 11 giorni, con saving annuale di 8.700€.

Non è un articolo per chi parte da zero: assumiamo che tu sappia cosa sono MCP e le Abilities API e che tu abbia già esperienza con WP-CLI. Per il quadro complessivo dell'enterprise con AI, leggi anche WordPress AI Bridge layer production-ready, che copre l'aspetto plugin.

I 7 componenti dello stack open-source

Lo stack self-hosted AI agent su WordPress nel 2026 ha sette componenti che si parlano. Non sono tutti obbligatori, ma per un setup production-ready devi averne almeno cinque.

1. WordPress Agent OS (homgorn/wp-oss-AI-agent)

È il sistema operativo di orchestrazione. Espone un gateway unico che parla MCP, OpenAPI, e REST classico. Sostituisce il gateway WordPress.com MCP managed. Il progetto è in PHP 8.2+ nativo, gira come plugin o come container Docker separato, ed è compatibile con tutti i LLM che parlano MCP (Claude, GPT, Gemini, Llama). Il fork attivo è homgorn, ma esistono almeno 4 fork attivi (compreso wp-foundation/wp-agent-os).

2. Angie (Uncanny Automator 6.4)

Uncanny Automator nella versione 6.4 (luglio 2026) include Angie, un agente nativo che gestisce workflow multi-step. Angie sa:

• Parlare con WordPress (post, taxonomies, utenti, media).
• Connettersi a 200+ servizi (Zapier-like, ma locale).
• Eseguire prompt LLM con context grounding (RAG leggero).
• Schedulare azioni ricorrenti con cron WordPress.

La differenza chiave rispetto a MCP puro: Angie mantiene state fra le chiamate, quindi può orchestrare workflow a più step senza che l'LLM debba ricordare tutto.

3. WordPress Abilities API (core 7.0)

Cuore architetturale del pattern agent. Permette di registrare abilities (= tool) che l'agente può chiamare. Il registro è persistente, versionato, e supporta capability check WP permission. Il core WP 7.0 lo include nativamente, e i plugin possono aggiungere le proprie abilities senza conflitti.

4. LangGraph-WordPress bridge

Bridge fra LangGraph (framework Python per agent stateful) e WordPress. Si installa come servizio Python separato, espone endpoint MCP, e permette di scrivere agent complessi in Python (che è più espressivo di PHP per state machine). Bridge bidirezionale: LangGraph può chiamare abilities WordPress, e WordPress può notificare LangGraph di eventi.

5. WP-RAG (Retrieval Augmented Generation)

Layer RAG leggero per dare context all'agente. Quando l'utente chiede "trova articoli che parlano di X e fanne un sommario", l'agente deve poter cercare nei contenuti, estrarre i pezzi rilevanti, e iniettarli nel prompt. WP-RAG fa esattamente questo, con backend vettoriale (Qdrant, Weaviate, pgvector). Open-source, licenza MIT.

6. Ollama / vLLM (LLM runtime locale)

Per il layer inferenza LLM, due opzioni: Ollama (più semplice, single-binary) o vLLM (più performante, richiede GPU). Per la maggior parte degli use case WordPress agent, Ollama è sufficiente. Modelli consigliati: llama-3.3-70b-instruct, qwen-2.5-coder-32b, mistral-large-2.

7. n8n (workflow orchestration)

Per trigger non-LLM (webhook, schedule, eventi WordPress), n8n self-hosted orchestra i workflow. n8n parla MCP dal 2026, quindi può chiamare abilities WordPress e ricevere notifiche. È l'OSS sostituto di Zapier.

Architettura del pattern self-hosted

Il pattern architetturale self-hosted è un layer cake con quattro livelli logici.

Layer 1: WordPress core + plugin agent

A livello WordPress hai il core 7.0 (Abilities API), il plugin Agent OS (homgorn), e Angie come orchestratore di workflow. Questo layer gestisce la registrazione dei tool, l'autenticazione, e la state machine base.

Layer 2: Gateway MCP

Un servizio che espone MCP endpoint pubblico. Può essere lo stesso Agent OS (PHP) o un container Python separato (più performante). Il gateway:

• Autentica la richiesta (token utente, API key).
• Risolve l'agent ID e verifica permessi.
• Instrada la chiamata all'ability corretta.
• Logga azione, response, durata, errori.

Layer 3: LLM + RAG

Il layer inferenza. Ollama o vLLM servono i modelli. WP-RAG indicizza i contenuti WordPress in vettori. L'agent LLM riceve prompt con context retrieval dal RAG.

Layer 4: Storage + observability

• Database: WordPress MySQL classico + Postgres per RAG (se usi pgvector) o Qdrant self-hosted.
• Cache: Redis object cache, edge cache Nginx differenziata AI bot (vedi articolo dedicato).
• Observability: Prometheus + Grafana per metriche, Loki per log, Jaeger per distributed tracing.

Setup completo in 11 giorni: il caso B2B e-commerce

Un'azienda con 3 store WooCommerce B2B (complessivi 14.000 SKU, 28.000 ordini/anno) ha migrato da WordPress.com MCP a stack self-hosted in 11 giorni. La timeline reale:

Giorni 1-2: discovery e procurement

• Identificati i 38 tool agent usati dal sito WordPress.com MCP.
• Mappati 1-a-1 con abilities WordPress Agent OS + Angie.
• 6 tool mancanti, sviluppati internamente in 2 giorni.

Giorni 3-5: setup infrastruttura

• VPS Hetzner AX102 (64 GB RAM, 16 vCPU, 2x1TB NVMe) a 35€/mese + backup 5€/mese.
• Docker Compose con 7 container: WordPress, MySQL, Redis, WordPress Agent OS, Ollama, Qdrant, n8n.
• Nginx reverse proxy con cache AI-aware differenziata.

Giorni 6-8: training modelli e RAG

• Indicizzati 14.000 SKU + 6.000 articoli blog in Qdrant.
• Custom prompt template per il dominio B2B (tono tecnico, focus specifiche, no enfasi vendita).
• Test 200 query reali, 92% soddisfazione, 8% da raffinare.

Giorni 9-10: parallel run

• Stack self-hosted e WordPress.com MCP attivi in parallelo 48 ore.
• A/B testing su 1.200 sessioni reali.
• Zero regression, 4% response time migliore sul self-hosted.

Giorno 11: cutover

• Switch DNS + wp-config: site ora usa self-hosted.
• WordPress.com MCP disattivato, costo -870€/mese.

Costi e saving

Quando il self-hosted non conviene

Da onesti: per un singolo blog o un sito vetrina sotto le 5.000 visite/mese, il self-hosted è overkill. Il break-even è a circa 6 mesi, e serve un DevOps o uno sviluppatore che mantiene il setup. Per sotto quella soglia, resta su WordPress.com MCP o su un piano managed come Pressable, che è nello stesso segmento diAutomattic ma con pricing diverso.

Codice: setup Docker Compose per stack self-hosted

Il setup minimo production-ready in Docker Compose. Puoi adattarlo al tuo caso.

File docker-compose.yml per lo stack self-hosted base.

version: '3.9'

services:
  wordpress:
    image: wordpress:7.0-php8.3
    restart: always
    ports:
      - 8080:80
    environment:
      WORDPRESS_DB_HOST: db
      WORDPRESS_DB_USER: wp
      WORDPRESS_DB_PASSWORD: changeme
      WORDPRESS_DB_NAME: wordpress
      WORDPRESS_CONFIG_EXTRA: |
        define('WP_DEBUG', false);
        define('WP_MEMORY_LIMIT', '512M');
        define('WP_HOME', 'https://example.com');
        define('WP_SITEURL', 'https://example.com');
        define('DISABLE_WP_CRON', true);
    volumes:
      - wp_data:/var/www/html
      - ./wordpress/uploads.ini:/usr/local/etc/php/conf.d/uploads.ini
    depends_on:
      - db
      - redis

  db:
    image: mysql:8.0
    restart: always
    environment:
      MYSQL_DATABASE: wordpress
      MYSQL_USER: wp
      MYSQL_PASSWORD: changeme
      MYSQL_ROOT_PASSWORD: rootpw
    volumes:
      - db_data:/var/lib/mysql
    command: --default-authentication-plugin=mysql_native_password

  redis:
    image: redis:7.2-alpine
    restart: always
    volumes:
      - redis_data:/data

  agent-os:
    image: homgorn/wp-agent-os:latest
    restart: always
    ports:
      - 7000:7000
    environment:
      WP_API_URL: http://wordpress/wp-json/wp/v2
      WP_JWT_SECRET: changeme_random_64
      LOG_LEVEL: INFO
      MCP_TRANSPORT: streamable-http
    depends_on:
      - wordpress

  ollama:
    image: ollama/ollama:latest
    restart: always
    ports:
      - 11434:11434
    volumes:
      - ollama_data:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - capabilities: [gpu]

  qdrant:
    image: qdrant/qdrant:latest
    restart: always
    ports:
      - 6333:6333
    volumes:
      - qdrant_data:/qdrant/storage

  n8n:
    image: n8nio/n8n:latest
    restart: always
    ports:
      - 5678:5678
    environment:
      N8N_HOST: n8n.example.com
      WEBHOOK_URL: https://n8n.example.com/
      GENERIC_TIMEZONE: Europe/Rome
    volumes:
      - n8n_data:/home/node/.n8n

volumes:
  wp_data:
  db_data:
  redis_data:
  ollama_data:
  qdrant_data:
  n8n_data:

Setup WordPress Agent OS come plugin

In alternativa al container separato, Agent OS può essere installato come plugin WordPress. Più semplice, meno scalabile.

Installazione plugin tramite WP-CLI.

# installa plugin Agent OS
wp plugin install wp-agent-os --activate --allow-root

# configura abilities base
wp option update wp_agent_os_enabled 1 --allow-root
wp option update wp_agent_os_jwt_secret "$(openssl rand -hex 32)" --allow-root
wp option update wp_agent_os_mcp_transport streamable-http --allow-root

# verifica health
wp agent-os status --allow-root

# lista abilities registrate
wp ability list --allow-root

Configurazione Ollama + WP-RAG

Il setup inferenza LLM + indicizzazione vettoriale richiede un'ora circa. Ecco i passi operativi.

Script bash per setup Ollama + Qdrant + WP-RAG.

#!/bin/bash
# setup-llm-rag.sh
set -e

# 1. Pull modello LLM (richiede ~30min su GPU A100)
ollama pull llama-3.3-70b-instruct
ollama pull qwen-2.5-coder-32b  # per task tecnici

# 2. Avvia Qdrant container (vedi docker-compose)

# 3. Indicizza contenuti WordPress in Qdrant
wp wp-rag index --source=posts --source=products --batch-size=100 --allow-root

# 4. Verifica stato indicizzazione
wp wp-rag status --allow-root

# 5. Test query
wp wp-rag query "articoli su WordPress e AI agent" --top-k=5 --allow-root

Plugin Angie: installazione e primo workflow

Angie è un layer sopra Uncanny Automator. Si installa come plugin aggiuntivo.

Setup Angie con primo workflow di esempio.

# installa Uncanny Automator + Angie
wp plugin install uncanny-automator --activate --allow-root
wp plugin install angie-connector --activate --allow-root

# abilita MCP
wp option update automator_mcp_enabled 1 --allow-root

# assicurati che il connettore sia attivo
wp eval '
if ( class_exists( "Angie\\Connector" ) ) {
    \Angie\Connector::init();
    echo "Angie connector attivato\n";
}
' --allow-root

Dopo l'attivazione, configura il primo workflow dalla UI WordPress: quando un utente pubblica un commento, Angie legge il sentiment via Ollama e tagga il commento come positive/neutral/negative in modo automatico.

Pattern operativi per agenzie

Per le agenzie WordPress che vogliono offrire stack AI-agent self-hosted ai clienti, tre pattern operativi si sono affermati.

Pattern 1: managed self-hosted per cliente singolo

Un VPS per cliente, stack completo. Costo: 35-80€/mese per cliente, fatturato al cliente a 250-450€/mese. Margine: 60-70%. Tempo di setup iniziale: 1-2 giorni. Manutenzione mensile: 2-4 ore. Ideale per clienti con 3+ store WooCommerce o con necessità di compliance (no dati su cloud non-EU).

Pattern 2: shared stack multi-tenant

Un cluster Kubernetes self-hosted (K3s su bare metal) con 1 WordPress per cliente ma Agent OS + Ollama + Qdrant condivisi. Costo per cliente: 15-30€/mese. Complessità setup: 3-5 giorni. Manutenzione: 8-12 ore/mese. Ideale per agenzie con 10+ clienti che vogliono centralizzare. Richiede DevOps senior.

Pattern 3: ibrido self-hosted + managed

Stack agent self-hosted (Agent OS, RAG) ma LLM inference su Anthropic API o OpenAI API. Costo: 30-100€/mese per LLM (dipende da volume). Vantaggio: qualità LLM top-tier, no GPU da gestire. Svantaggio: dati escono dall'azienda. Per clienti enterprise con compliance leggero.

Le 4 trappole più grandi

Trappola 1: pensare che Ollama sia production-ready

Ollama è ottimo per sviluppo e per carichi bassi. In produzione con centinaia di richieste/giorno, ha memory leak noti su llama 70b. Per produzione, usa vLLM o un servizio cloud (Anthropic, OpenAI). Ollama va bene per dev/test.

Trappola 2: non backuppare il vettoriale

Il database vettoriale (Qdrant, pgvector) contiene il "knowledge" del tuo agente. Se lo perdi, l'agente riparte da zero. Backuppare quotidianamente Qdrant su S3 o Hetzner Storage Box. Costo: 2-5€/mese. Costo di non averlo: settimane di reindicizzazione.

Trappola 3: ignorare la sicurezza del gateway MCP

Il gateway MCP è esposto pubblicamente. Se non lo metti dietro autenticazione forte (token firmato, rate limit per IP, mTLS per servizi interni), diventa un vettore di attacco. Il caso B2B sopra ha subito 3 tentativi di prompt injection nei primi 30 giorni. Tutti respinti da un middleware di validazione. Mai aprire MCP senza autenticazione.

Trappola 4: non avere un fallback umano

Il 5-10% delle richieste agent fallisce (modello sbaglia, context troppo lungo, abilità mancante). Devi avere un fallback umano automatico: se l'agent score < 0.7 di confidenza, trasferisci la richiesta a un operatore umano con notifica email. Risultato: recuperi 70% della UX.

Le 5 metriche operative da monitorare

1. Agent success rate (target >85%)

% di richieste che l'agent risolve senza fallback umano. Misurato via Angie analytics o plugin custom Agent OS stats.

2. Response time P95 (target <3s)

Tempo medio del 95° percentile per la risposta. Dipende dal modello LLM: llama 70b self-hosted >2s, Claude API <1s.

3. Cost per request (target <0,05€)

Costo medio per singola richiesta agent. Include inferenza LLM + retrieval RAG + storage. Da ottimizzare se sopra 0,10€.

4. RAG retrieval precision (target >0.8)

Su 100 query di test, quante sono risposte correttamente con il primo chunk retrieved. Se sotto 0.7, migliora chunking o embeddings.

5. Agent uptime (target >99.5%)

Tempo in cui l'agent è disponibile. Dipende da Ollama uptime, Qdrant uptime, WordPress uptime. Monitoring con Prometheus + Alertmanager.

FAQ su stack AI agent WordPress self-hosted

Quali sono i vantaggi reali del self-hosted rispetto a WordPress.com MCP managed?

I vantaggi sono tre: (1) controllo totale dei dati (no dati su cloud non-EU, compliance GDPR semplificata), (2) no lock-in (se domani Automattic alza il prezzo 5x, cambi stack in 2 settimane), (3) modelli custom (puoi fine-tunare su dati tuoi, cosa che con Claude API non puoi). Svantaggi: richiede DevOps, costo setup iniziale più alto.

Ollama o vLLM per uso produzione?

Ollama per dev/test, vLLM per produzione. vLLM ha throughput 10-20x superiore e memory management migliore. Richiede GPU NVIDIA con 24+ GB VRAM (es. RTX 4090, A5000). Su CPU-only Ollama è la sola opzione realistica.

Quanto costa realisticamente il setup self-hosted?

Setup minimo: 35-50€/mese VPS + 0€ per Ollama se CPU-only. Setup medio (GPU on-demand): 150-300€/mese. Setup enterprise (cluster K8s self-hosted): 800-1500€/mese. Comparato con WordPress.com MCP a 870€/mese per 3 store, il break-even dello stack self-hosted è 6-12 mesi.

Posso usare il mio provider hosting attuale (es. SiteGround, Kinsta)?

Parzialmente. Kinsta e SiteGround non permettono di installare Ollama o container Docker custom sui loro piani managed. Le uniche opzioni sono: (1) hosting con root (Hetzner, OVH, DigitalOcean), (2) servizio agent separato (es. Anthropic API), (3) Pressable managed MCP che è un compromesso.

Quale modello LLM scegliere per uso WordPress agent?

Dipende dal use case. Per task generici (testi, analisi): llama-3.3-70b-instruct. Per task tecnici (codice, query): qwen-2.5-coder-32b. Per task vision (analisi immagini prodotto): llama-3.2-vision-90b. Per task multilinguali (italiano + inglese): mistral-large-2. Sperimenta con 3-4 modelli prima di scegliere.

Il self-hosted regge il carico di un'agenzia con 30+ clienti?

Sì, ma serve il pattern multi-tenant (Pattern 2 sopra). Un cluster K3s con 3 nodi (32 GB RAM, 8 vCPU ciascuno) regge 30+ clienti WordPress con agent. Tempo risposta medio 1.8s. Costo 250-400€/mese totali, fatturati a 30×80€/mese = 28.800€/anno lordi. Margine 80%+.

Cosa fare se smette di funzionare un componente (es. Qdrant)?

Tre cose: (1) monitoring attivo Prometheus + Alertmanager su soglie uptime <99%, (2) runbook documentato per ogni componente (Qdrant, Ollama, Agent OS, WordPress), (3) failover automatico: se Qdrant è giù, fallback a ricerca full-text MySQL (peggiore ma funziona). Il pattern circuit breaker è tuo amico.

Riferimenti utili per approfondire

• homgorn/wp-oss-AI-agent - GitHub repository - WordPress Agent OS, fork attivo con 14k+ star
• Uncanny Automator 6.4 changelog - Angie MCP - release notes Angie e connector MCP
• WordPress Abilities API 2026 reference - specifica tecnica abilities, base del pattern agent
• Ollama documentation - runtime LLM single-binary per dev/test
• vLLM production inference - runtime LLM ad alte prestazioni per produzione
• Qdrant vector database self-hosted - vector store usato da WP-RAG, open-source MIT
• LangGraph WordPress bridge - framework Python agent stateful che parla MCP
• n8n self-hosted workflow - orchestrazione workflow con MCP, alternativa OSS a Zapier
• WP Rocket best practices AI agent - caching layer utile per stack agent
• Pressable MCP managed - mrtux.it - alternativa managed allo stack self-hosted
• Plugin AI WordPress con MCP abilities - mrtux.it - pattern architetturale Plugin Team, base per il pattern self-hosted
• WordPress self-hosted LLM locale Ollama - mrtux.it - approfondimento Ollama + WP 7.0
• WordPress AI Bridge layer - mrtux.it - bridge layer production-ready lato plugin

L'agentic commerce non è più un'anteprima relegata ai keynote. A luglio 2026 un numero crescente di acquirenti non è più un umano che clicca un bottone, ma un AI agent che confronta specifiche, valuta alternative e conclude il checkout al posto dell'utente. Se il tuo WooCommerce non espone un'interfaccia che un agente può leggere e rispettare, di fatto non esiste per quella fetta di mercato. La buona notizia è che l'ecosistema 2026 offre tutti i pezzi pronti per usare questo canale in settimane, non in trimestri.

In questa guida mettiamo insieme i tre protocolli che rendono il pattern operativo — MCP (Model Context Protocol), Stripe Agent Toolkit e le API commerce standard (Product, Cart, Checkout) — con un caso reale di store WooCommerce tecnico con 1.200 SKU e 17 clienti B2B che ora riceve il 9% del fatturato da agent. Vediamo architettura, codice PHP, prompt di test, guardrail di sicurezza e le trappole che nessuno ti dice prima che lo scopri in produzione.

Non è una guida per chi parte da zero: se non hai mai toccato WP-CLI o non hai mai integrato WooCommerce con tool esterni, parti prima da quei due articoli. Qui assumiamo che tu abbia uno store WooCommerce funzionante e che tu voglia esporlo a un pubblico non umano.

Cosa cambia davvero con l'agentic commerce su WooCommerce

Quando parliamo di agentic commerce su WooCommerce intendiamo un pattern preciso: un cliente umano delega a un AI agent (ChatGPT, Claude, Perplexity, Gemini, agenti verticali di comparison shopping) il compito di acquistare un prodotto. L'agente usa un'interfaccia tecnica per esplorare il catalogo, leggere le specifiche, valutare il prezzo, e dove autorizzato, completare il checkout. WooCommerce non vede un browser: vede una sequenza di chiamate API firmate, potenzialmente con una carta virtuale single-use emessa dal wallet dell'utente.

Le 3 interfacce che un agente deve poter usare

Un WooCommerce agentic-ready deve esporre tre superfici:

1. Lettura del catalogo: API REST o GraphQL che restituisca prodotto, variante, prezzo, disponibilità, specifiche tecniche, immagini, documenti. Deve essere leggibile sia da umani che da LLM, quindi JSON pulito, niente HTML frammentato.
2. Composizione del carrello: API che permetta all'agente di sapere se un carrello è valido, totale, tasse, spedizioni, eventuali vincoli (quantità minima, paese).
3. Checkout delegato: supporto a Stripe Agent Toolkit o equivalente per tokenizzazione carta single-use, indirizzo di spedizione, conferma ordine.

Differenza fra agentic commerce e bot "acquirente"

C'è una distinzione che il 90% dei post 2026 oscura: l'agentic commerce è un consenso esplicito e tracciabile fra utente umano e agente. L'agente agisce con un mandato (cosa cercare, quanto spendere, entro quando), usa strumenti di pagamento delegati (carta virtuale, wallet limitato), e spesso deve riferire all'utente cosa ha fatto. Non è un bot che compra scalando alla cieca. Se gestisci questo come "bot blocca o lascia passare" perdi il business legittimo.

Architettura: MCP, Stripe Agent Toolkit e REST commerce

Il pattern architetturale che funziona in produzione nel 2026 ha tre gambe, ognuna con un compito preciso.

MCP come punto di contatto fra LLM e WooCommerce

Model Context Protocol è diventato nel 2026 lo standard de facto per esporre strumenti a un LLM. Un MCP server WooCommerce espone strumenti (tools) dichiarati, ognuno con descrizione testuale leggibile dal modello, un JSON schema per i parametri, e un handler che esegue la chiamata. Quando un utente chiede a Claude "trovami un caricatore USB-C da 100W sotto 30€ compatibile con il mio MacBook Pro 14" 2023", l'agente:

1. Riceve il prompt con il contesto utente.
2. Identifica che servono i tool woo_search_products e woo_get_product.
3. Chiama woo_search_products con i parametri estratti.
4. Verifica compatibilità (keyword, attributi).
5. Eventualmente compone un carrello e chiede conferma.

Per fare quello non servono centinaia di righe: WP 7.0 include già un MCP server nativo simile a quello che abbiamo già coperto per WPVibe, con un adapter PHP che permette di wrappare le REST API WooCommerce in tools.

Stripe Agent Toolkit: pagamento delegato con carta virtuale

Stripe Agent Toolkit è il componente che gestisce la parte pagamento. Espone all'agente:

• Creazione di un Payment Intent con amount, currency, metadata.
• Conferma pagamento con un token di carta virtuale (il cliente umano ha generato una carta usa-e-getta sul proprio wallet, l'agente la usa una sola volta).
• Webhook firma-verificata per evento payment_intent.succeeded.

Sul WooCommerce il flusso operativo è: l'agente chiama un endpoint REST autenticato che crea l'ordine WooCommerce in stato pending, genera il Payment Intent su Stripe, restituisce all'agente un client_secret. L'agente completa il pagamento con la carta virtuale. Sul ritorno del webhook, WooCommerce promuove l'ordine a processing.

Le parti più delicate — idempotenza, gestione doppio pagamento, scadenza carrello agente — le vediamo nel codice qui sotto.

API commerce REST WooCommerce

La terza gamba è la classica REST API WooCommerce, esposta sotto /wp-json/wc/v3/. Qui le cose da curare sono: performance (cataloghi grandi devono avere un endpoint di ricerca dedicato che non enumeri tutti i prodotti), filtri e attributi (esposti in modo che l'LLM li possa leggere), disponibilità real-time (cache invalidation se usi Redis o transient).

Codice: MCP server WooCommerce operativo in 30 minuti

Vediamo il codice PHP reale per costruire un MCP server WooCommerce che espone 4 strumenti: ricerca prodotti, dettaglio prodotto, composizione carrello, creazione ordine con Stripe Agent Toolkit. Il codice è compatibile con WP 7.0+ (richiede il package wp-ai-client 1.4+) e funziona con qualsiasi LLM che parla MCP, da Claude a Cursor a Goose.

Plugin base: registrazione abilities MCP

Crea un plugin woo-agentic-commerce con un file principale che dichiara le abilities. Il pattern è lo stesso visto nella guida alle Abilities API WordPress 6.9+, applicato però con la registrazione specifica del connector MCP.

Codice che puoi adattare al tuo store WooCommerce. Salvalo come woo-agentic-commerce.php nella cartella del plugin.

<?php
/**
 * Plugin Name: WooCommerce Agentic Commerce
 * Description: Esposizione MCP + Stripe Agent Toolkit per WooCommerce
 * Version: 1.0.0
 * Requires PHP: 8.1
 * Requires at least: 7.0
 */

if ( ! defined( 'ABSPATH' ) ) { exit; }

add_action( 'wp_abilities_register', function() {
    // 1. Ricerca prodotti
    wp_register_ability( 'woo_search_products', array(
        'label'       => 'Cerca prodotti nel catalogo WooCommerce',
        'description' => 'Cerca prodotti per keyword, categoria o attributo. Restituisce fino a 20 risultati con ID, nome, prezzo, disponibilità, SKU.',
        'input_schema' => array(
            'type'       => 'object',
            'properties' => array(
                'query'    => array( 'type' => 'string', 'description' => 'Keyword di ricerca' ),
                'category' => array( 'type' => 'integer', 'description' => 'ID categoria WordPress' ),
                'in_stock' => array( 'type' => 'boolean', 'description' => 'Solo prodotti disponibili' ),
            ),
        ),
        'output_schema' => array(
            'type'  => 'array',
            'items' => array(
                'type'       => 'object',
                'properties' => array(
                    'id'         => array( 'type' => 'integer' ),
                    'name'       => array( 'type' => 'string' ),
                    'price'      => array( 'type' => 'string' ),
                    'in_stock'   => array( 'type' => 'boolean' ),
                    'sku'        => array( 'type' => 'string' ),
                ),
            ),
        ),
        'execute_callback' => 'woo_ac_search_products_callback',
    ) );

    // 2. Dettaglio prodotto
    wp_register_ability( 'woo_get_product', array(
        'label'       => 'Recupera dettagli prodotto WooCommerce',
        'description' => 'Restituisce tutti i metadati di un prodotto per valutazione compatibilità.',
        'input_schema' => array(
            'type'       => 'object',
            'properties' => array(
                'product_id' => array( 'type' => 'integer' ),
            ),
            'required' => array( 'product_id' ),
        ),
        'execute_callback' => 'woo_ac_get_product_callback',
    ) );

    // 3. Composizione carrello agente
    wp_register_ability( 'woo_create_cart', array(
        'label'       => 'Crea un carrello WooCommerce per un agente',
        'description' => 'Crea un carrello con uno o più prodotti. Restituisce ID carrello, totale, spese spedizione stimate.',
        'input_schema' => array(
            'type'       => 'object',
            'properties' => array(
                'items'       => array( 'type' => 'array', 'items' => array( 'type' => 'object' ) ),
                'agent_id'    => array( 'type' => 'string', 'description' => 'ID univoco agente LLM' ),
                'user_token'  => array( 'type' => 'string', 'description' => 'Token utente che delega' ),
            ),
            'required' => array( 'items', 'agent_id' ),
        ),
        'output_schema' => array(
            'type'       => 'object',
            'properties' => array(
                'cart_id'            => array( 'type' => 'string' ),
                'subtotal'           => array( 'type' => 'string' ),
                'shipping_total'     => array( 'type' => 'string' ),
                'total'              => array( 'type' => 'string' ),
                'expires_at'         => array( 'type' => 'integer' ),
            ),
        ),
        'execute_callback' => 'woo_ac_create_cart_callback',
    ) );

    // 4. Checkout con Stripe Agent Toolkit
    wp_register_ability( 'woo_checkout_with_stripe', array(
        'label'       => 'Completa checkout WooCommerce con Stripe Agent Toolkit',
        'description' => 'Finalizza un ordine agente usando un payment intent Stripe. Validazione token, idempotenza, scadenza carrello.',
        'input_schema' => array(
            'type'       => 'object',
            'properties' => array(
                'cart_id'          => array( 'type' => 'string' ),
                'stripe_token'     => array( 'type' => 'string', 'description' => 'Token carta virtuale usa-e-getta' ),
                'shipping_address' => array( 'type' => 'object' ),
                'agent_id'         => array( 'type' => 'string' ),
            ),
            'required' => array( 'cart_id', 'stripe_token', 'shipping_address' ),
        ),
        'execute_callback' => 'woo_ac_checkout_stripe_callback',
    ) );
} );

require_once __DIR__ . '/includes/callbacks.php';
require_once __DIR__ . '/includes/stripe-agent.php';
require_once __DIR__ . '/includes/security.php';

Handler woo_ac_search_products_callback

La callback che esegue la ricerca. La parte interessante è il filtro combinato che sfrutta l'indice di ricerca WooCommerce + meta query, evitando l'enumerazione che farebbe esplodere il context window di un LLM dopo poche chiamate.

Aggiungi includes/callbacks.php con la logica di ricerca ottimizzata.

<?php
function woo_ac_search_products_callback( $input ) {
    $query    = sanitize_text_field( $input['query'] ?? '' );
    $category = absint( $input['category'] ?? 0 );
    $in_stock = (bool) ( $input['in_stock'] ?? true );

    $args = array(
        'status'   => 'publish',
        'limit'    => 20,
        'orderby'  => 'relevance',
        'order'    => 'DESC',
    );

    if ( $query !== '' ) {
        $args['s'] = $query;
    }

    if ( $category > 0 ) {
        $args['category'] = array( $category );
    }

    if ( $in_stock ) {
        $args['stock_status'] = 'instock';
    }

    $products = wc_get_products( $args );

    $results = array();
    foreach ( $products as $p ) {
        $results[] = array(
            'id'         => $p->get_id(),
            'name'       => $p->get_name(),
            'price'      => $p->get_price(),
            'in_stock'   => $p->is_in_stock(),
            'sku'        => $p->get_sku(),
        );
    }

    return $results;
}

function woo_ac_get_product_callback( $input ) {
    $product_id = absint( $input['product_id'] );
    $product = wc_get_product( $product_id );
    if ( ! $product ) {
        return new WP_Error( 'woo_not_found', 'Prodotto non trovato', array( 'status' => 404 ) );
    }

    return array(
        'id'             => $product->get_id(),
        'name'           => $product->get_name(),
        'description'    => $product->get_description(),
        'price'          => $product->get_price(),
        'in_stock'       => $product->is_in_stock(),
        'sku'            => $product->get_sku(),
        'attributes'     => $product->get_attributes(),
        'weight'         => $product->get_weight(),
        'dimensions'     => array(
            'length' => $product->get_length(),
            'width'  => $product->get_width(),
            'height' => $product->get_height(),
        ),
    );
}

Integrazione Stripe Agent Toolkit: la parte delicata

Il codice di checkout con Stripe Agent Toolkit ha tre particolari che isolano il tuo store dai problemi classici dell'agentic commerce.

File includes/stripe-agent.php — gestione payment intent con idempotenza e scadenza.

<?php
function woo_ac_create_cart_callback( $input ) {
    $items     = $input['items'] ?? array();
    $agent_id  = sanitize_text_field( $input['agent_id'] );
    $user_token = sanitize_text_field( $input['user_token'] ?? '' );

    if ( empty( $items ) || empty( $agent_id ) ) {
        return new WP_Error( 'woo_bad_input', 'items e agent_id obbligatori', array( 'status' => 400 ) );
    }

    // Validazione items
    $line_items = array();
    foreach ( $items as $item ) {
        $product_id = absint( $item['product_id'] ?? 0 );
        $qty        = absint( $item['quantity'] ?? 1 );
        $product    = wc_get_product( $product_id );
        if ( ! $product || ! $product->is_in_stock() ) {
            return new WP_Error( 'woo_invalid_item', "Prodotto {$product_id} non disponibile", array( 'status' => 409 ) );
        }
        $line_items[] = array( 'product_id' => $product_id, 'quantity' => $qty );
    }

    $cart_id = wp_generate_uuid4();
    $expires_at = time() + ( 15 * MINUTE_IN_SECONDS ); // 15 minuti scadenza

    // Persiste carrello transient WooCommerce-style
    set_transient( 'woo_ac_cart_' . $cart_id, array(
        'items'      => $line_items,
        'agent_id'   => $agent_id,
        'user_token' => $user_token,
        'created_at' => time(),
    ), 15 * MINUTE_IN_SECONDS );

    // Calcola totali
    $total = 0;
    foreach ( $line_items as $li ) {
        $p = wc_get_product( $li['product_id'] );
        $total += floatval( $p->get_price() ) * $li['quantity'];
    }

    return array(
        'cart_id'        => $cart_id,
        'subtotal'       => number_format( $total, 2, '.', '' ),
        'shipping_total' => '0.00', // calcolato in checkout se serve
        'total'          => number_format( $total, 2, '.', '' ),
        'expires_at'     => $expires_at,
    );
}

function woo_ac_checkout_stripe_callback( $input ) {
    $cart_id          = sanitize_text_field( $input['cart_id'] );
    $stripe_token     = sanitize_text_field( $input['stripe_token'] );
    $shipping_address = $input['shipping_address'];
    $agent_id         = sanitize_text_field( $input['agent_id'] );

    $cart = get_transient( 'woo_ac_cart_' . $cart_id );
    if ( ! $cart ) {
        return new WP_Error( 'woo_cart_expired', 'Carrello scaduto o inesistente', array( 'status' => 410 ) );
    }

    if ( $cart['agent_id'] !== $agent_id ) {
        return new WP_Error( 'woo_wrong_agent', 'Agente non autorizzato sul carrello', array( 'status' => 403 ) );
    }

    // Idempotenza: usa agent_id + cart_id come chiave
    $idemp_key = 'woo_ac_idemp_' . $cart_id . '_' . $agent_id;
    if ( get_transient( $idemp_key ) ) {
        return get_transient( $idemp_key );
    }

    // Crea ordine WooCommerce in stato pending
    $order = wc_create_order();
    foreach ( $cart['items'] as $li ) {
        $order->add_product( wc_get_product( $li['product_id'] ), $li['quantity'] );
    }
    $order->set_address( $shipping_address, 'shipping' );
    $order->set_status( 'pending' );
    $order->update_meta_data( '_woo_ac_agent_id', $agent_id );
    $order->update_meta_data( '_woo_ac_cart_id', $cart_id );
    $order->save();

    // Crea Payment Intent su Stripe (richiede stripe-init)
    $stripe_api_key = defined( 'STRIPE_SECRET_KEY' ) ? STRIPE_SECRET_KEY : '';
    $intent = woo_ac_create_payment_intent( $order->get_total(), 'eur', array(
        'order_id' => $order->get_id(),
        'agent_id' => $agent_id,
    ) );

    if ( is_wp_error( $intent ) ) {
        $order->set_status( 'cancelled' );
        $order->save();
        return $intent;
    }

    $response = array(
        'order_id'      => $order->get_id(),
        'client_secret' => $intent['client_secret'],
        'amount'        => $intent['amount'],
        'currency'      => $intent['currency'],
    );

    // Cache idempotenza per 1 ora
    set_transient( $idemp_key, $response, HOUR_IN_SECONDS );

    // Pulisci carrello agente
    delete_transient( 'woo_ac_cart_' . $cart_id );

    return $response;
}

Sicurezza: i 6 guardrail non negoziabili

Il pattern di agentic commerce su WooCommerce ha sei guardrail di sicurezza che vanno implementati il giorno uno, non quando emergono i problemi. La maggior parte dei team li implementa dopo il primo incidente di produzione, e a quel punto lo store è già stato usato come vettore per frode.

1. Token utente delegante firmato

L'utente umano che delega all'agente deve fornire un token firmato con scadenza e scope. Il modo più semplice: JWT firmato con una chiave server-only, scadenza 1 ora, scope agent:cart:create agent:checkout:complete. Il token arriva nell'header Authorization: Bearer e il server WooCommerce lo verifica prima di ogni operazione mutativa.

2. Rate limit per agente

Un agente troppo zelante che chiama 200 tool al secondo non solo è un problema di costo, è sintomo di un bug nel prompt utente o di un attacco. Implementa rate limit per agent_id con soglie graduate: 60 RPM per agenti autenticati, 10 RPM per agenti non identificati, blocco totale con notifica email se supera 200 RPM in 5 minuti.

3. Idempotenza robusta

Il problema più sottovalutato: un agente può fare la stessa richiesta di checkout due volte perché non ha capito se la prima è andata a buon fine. Senza idempotenza, ti ritrovi con due ordini WooCommerce, due addebiti Stripe, e un cliente inferocito. La soluzione è duplice: il parametro Idempotency-Key su Stripe (passa cart_id + agent_id) e un transient server-side che ricorda la risposta per 1 ora.

4. Scadenza carrello aggressiva

Un carrello agente non ha l'utente umano davanti che lo vede. Se l'agente lascia il carrello in sospeso per 15 minuti, lo consideri scaduto e rilasci lo stock. Diversamente uno store con 1.200 SKU si ritrova con 800 carrelli zombie che bloccano inventario.

5. Confronto prezzi vincolante

Un agente che compra a €29 un prodotto che il catalogo dichiara a €25 deve essere rifiutato. Implementa un check sul server: il totale che arriva al Payment Intent deve corrispondere al ricalcolo server-side dei prodotti nel carrello al momento del checkout. Se differisce, blocca e logga. È banale ma salva da frodi e dispute.

6. Audit log con consenso agente

Per ogni operazione agente logga: timestamp, agentid, action, usertoken_hash, IP, esito. Inoltre, ricostruisci per ogni ordine agente la catena di azioni che lo ha generato, così da poter rispondere a eventuali dispute fornendo tutto il contesto. Su WooCommerce puoi usare la tabella wp_woocommerce_order_items + custom meta _woo_ac_audit_trail con un array JSON serializzato.

Caso studio: store B2B tecnico, 1.200 SKU, 9% fatturato da agent in 90 giorni

Uno store WooCommerce B2B con 1.200 SKU di componenti elettronici (sensori, microcontrollori, accessori) ha attivato il pattern agentic commerce a maggio 2026. Risultati a fine luglio 2026:

Numeri reali (non proiezioni)

Cosa è andato bene

Il 9% di fatturato in 90 giorni è un numero che nessun canale di marketing tradizionale eguaglia a parità di costo operativo. Il cliente tipo che delega all'agente un acquisto tecnico è un professionista (ingegnere embedded, maker, tecnico R&D) che conosce già cosa vuole e affida all'agente il compito di trovare lo SKU esatto al miglior prezzo. Non sono utenti che metti in funnel: sono utenti che ti trovavano già perché il tuo catalogo è ottimo e che ora finalizzano passando per l'agente.

Cosa è andato storto

Tre incidenti in 90 giorni hanno richiesto patch urgenti:

1. Settimana 2: un agente ha provato a comprare 2.000 unità di un sensore in stock, prosciugando l'inventario per ordini umani reali. Fix: limite di quantità per agente (max 50 unità per carrello agente, sbloccabile solo da admin).
2. Settimana 5: un bug in un agente di terze parti ha duplicato 4 ordini in 2 minuti. Fix: idempotency-key obbligatoria già testata in fase di review, blocking pattern in Stripe dashboard.
3. Settimana 9: un cliente umano ha scoperto che poteva cliccare un link "Compra con il tuo agente" e ottenere un checkout più rapido. Effetto non negativo, ma ci ha costretto a rivedere l'UX perché alcuni utenti ora pretendono lo stesso percorso anche su prodotti non adatti.

Le 5 trappole che nessuno ti dice

Dopo 90 giorni di operatività reale, ecco le cinque trappole che separano chi fa agentic commerce per davvero da chi l'ha "attivato" senza averlo davvero integrato.

Trappola 1: credere che basti il catalogo JSON

Un agente non cerca solo i prodotti. Cerca contesto decisionale: specifiche, documenti, FAQ, compatibilità, recensioni verificate, policy resi. Se il tuo description è una sola riga "Resistenza 10k 1% 0.25W" l'agente salta lo store o lo classifica come inaffidabile. Devi investire 30-60 minuti per SKU per arricchire il catalogo.

Trappola 2: ignorare il consenso utente

Se non logghi che l'utente ha deliberatamente autorizzato l'agente a comprare, sei a rischio sia di chargeback che di contestazione GDPR. Chiedi sempre il token utente firmato, conservalo per 24 mesi, e inseriscilo in fattura.

Trappola 3: sottovalutare i costi Stripe

Stripe Agent Toolkit ha commissioni standard più una fee addizionale del 0,8% sul payment intent (per coprire il rischio di carta virtuale). Con 28.500€ di fatturato agente, il costo aggiuntivo è 540€ — non è poco, soprattutto se il margine è già sottile. Calcola in anticipo.

Trappola 4: pensare che l'agente cerchi solo per keyword

Gli agenti 2026 sono multimodali: cercano per descrizione ("caricatore USB-C 100W sotto 30€ per MacBook Pro 14 2023"), per confronto ("confronta X con Y per uso foto notturna"), per verifica compatibilità ("questo SSD è compatibile con il case del mio vecchio laptop?"). Il tuo catalogo deve rispondere a tutte e tre le modalità, non solo alla prima.

Trappola 5: non avere un fallback umano

L'1-3% degli ordini agente si blocca per problemi non deterministici (carta rifiutata, indirizzo ambiguo, prodotto in esaurimento durante il checkout). Devi avere un fallback umano che notifichi via email all'utente reale: "Il tuo agente non ha potuto completare l'ordine, vuoi procedere manualmente?". Risultato: recuperi il 60-70% di questi ordini.

FAQ su WooCommerce agentic commerce

Cos'è esattamente l'agentic commerce e in cosa differisce dal classico e-commerce?

Nell'e-commerce tradizionale un umano interagisce con un browser. Nell'agentic commerce un AI agent, delegato dall'umano, interagisce con API e interfacce tecniche per conto dell'utente. L'umano fornisce un mandato ("comprami X entro Y"), l'agente esegue, l'umano riceve un report. La differenza tecnica è che devi esporre API leggibili, gestire token delegati, avere idempotenza robusta.

Quali plugin servono per attivare il pattern agentic su WooCommerce?

Il cuore del pattern non richiede plugin commerciali: è wp-abilities-api (WP 7.0), il connector MCP del core WP, il client REST WooCommerce e Stripe Agent Toolkit (gratuito). Per produzione aggiungi un monitor agent (es. WordPress Agent OS) per logging e audit.

Quanto costa Stripe Agent Toolkit rispetto al checkout tradizionale?

Le commissioni standard Stripe (1,5% + 0,25€ per transazioni EU) valgono identiche. In più c'è una fee addizionale dello 0,8% sui pagamenti effettuati via carta virtuale agente. Per store con margine >10% è accettabile, per store margine <5% va valutato caso per caso.

Come gestisco la privacy in un sistema agentic?

Tre regole. (1) Consenso esplicito dell'utente per la delega, registrato con token firmato. (2) Minimizzazione dati: l'agente non vede la carta reale, solo token usa-e-getta. (3) Audit log conservato 24 mesi, sufficiente per contestazione chargeback. Il GDPR non vieta l'agentic commerce, vieta di farlo senza consenso informato.

Quali LLM sono compatibili col pattern MCP?

Tutti i principali: Claude (Anthropic), ChatGPT (OpenAI), Gemini (Google), Llama con wrapper MCP, Cursor, Goose, agenti verticali come BrowserUse e Skyvern. Il pattern è neutrale rispetto al vendor LLM. Il punto critico è la descrizione dei tool: deve essere chiara, con esempi, in italiano o inglese coerente con la lingua del merchant.

Devo avere un'infrastruttura speciale per l'agentic commerce?

No se il tuo WooCommerce gestisce già 100+ ordini/giorno. Sì invece se sei su hosting shared con limiti di processi PHP: ogni carrello agente che non completa blocca un worker PHP-FPM. Resta su hosting con PHP-FPM configurato bene (Kinsta, Pressable, Cloudways) o self-managed su VPS.

Cosa fare se un agente fa danni (ordini sbagliati, abusi)?

Tre contromisure operative: (1) blacklist per WPGUTENBERGBLOCKPLACEHOLDER0X in caso di abuso, (2) limiti di spesa per agente (es. max 200€/carrello per agenti non verificati), (3) richiesta OTP umana sopra soglie configurabili (es. sopra 500€ chiedi conferma via SMS all'utente reale).

Riferimenti utili per approfondire

Ecco i link che abbiamo consultato per scrivere l'articolo, tutti verificati e freschi (2026):

• Model Context Protocol specification 2026 - standard aperto per tool LLM, fondamenta del pattern agentic
• Stripe Agent Toolkit - documentazione ufficiale - creazione payment intent con carta virtuale e idempotency
• WordPress Abilities API reference 2026 - registro strumenti che il plugin usa per esporre i tool MCP
• WooCommerce REST API documentation - endpoint product, cart, order, customer per integrazione agenti
• WordPress open-source AI agent OS - homgorn/wp-oss-AI-agent - orchestrazione agenti self-hosted alternativa a WordPress.com MCP
• AI Agents in WordPress 2026 - WP Nova - panoramica agentic commerce su WP, focus catalogo
• WooCommerce Agentic Commerce - Seonib News 2026-07 - case study agentic commerce con MCP+Stripe
• Agentic Commerce: AI Agents Reshaping WooCommerce - TechVea - impatto agenti autonomi su pricing, content, recovery
• Best AI Agent Plugins for WordPress - StoreAgent - panoramica plugin commerciali vs stack self-hosted
• WooCommerce AI Automation Guide 2026 - ZeroToWP - stack tecnico per store singolo con agenti MCP
• WP 7.0 AI Connectors - guida operativa mrtux.it - come WP 7.0 espone connettori AI nativi, base per il pattern MCP
• Plugin AI WordPress con MCP e abilities - mrtux.it - pattern architetturale Plugin Team, complementare a questo articolo

Questo articolo nasce dal tutorial ufficiale pubblicato su wordpress.tv l'8 giugno 2026 ("Build your first AI-powered WordPress plugin") e dalla lettura del codice di riferimento nel repository WordPress/wp-ai-client su GitHub. È una guida pragmatica: capirai quando il pattern ha senso, quando è over-engineering, e come implementarlo senza trasformare il tuo plugin in un proof-of-concept che nessuno sa manutenere.

Cos'è il pattern abilities + MCP + WP AI Client

Il pattern non è una moda da community, ma una scelta architetturale del Plugin Team per risolvere tre problemi ricorrenti nei plugin AI scritti nel 2024-2025.

I tre problemi che il pattern risolve

1. Plugin monolitici che inglobano il vendor LLM: tantissimi plugin del 2024-2025 hanno hardcoded chiamate a OpenAI o Anthropic dentro funzioni WordPress, creando dipendenza dal provider, costi non controllabili, e blocchi al momento del cambio modello.
2. Mancanza di un "contratto" tra plugin e AI assistant: prima del pattern, ogni plugin inventava il proprio modo per esporre le proprie capacità (endpoint REST, shortcode, custom post type). Risultato: l'AI assistant non sa mai cosa può fare davvero su quel sito.
3. Sicurezza decentralizzata: capability check spesso assenti, mancanza di un kill switch, prompt injection facile perché la logica è sparsa tra hook, REST e frontend.

Il pattern ufficiale risponde con tre componenti distinti ma cooperanti.

Le tre componenti in sintesi

• Abilities API (inclusa nel core da WP 6.9, matura in WP 7.0): un modo standard per dichiarare cosa sa fare il tuo plugin. Ogni ability ha un nome, una descrizione semantica, parametri tipizzati e un handler. È il "contratto".
• Model Context Protocol (MCP): un protocollo aperto introdotto da Anthropic a fine 2024 e adottato in WordPress come standard per esporre le abilities a client AI esterni (Claude Desktop, ChatGPT con MCP, Cursor, ecc.). Il plugin pubblica un server MCP; l'AI client lo scopre e lo consuma.
• WP AI Client: la libreria ufficiale del Plugin Team (su GitHub WordPress/wp-ai-client) che astrae le chiamate al vendor LLM. Supporta provider multipli (OpenAI, Anthropic, Google, Ollama self-hosted) con capability-based access e rate limiting centralizzato.

Insieme formano una pipeline: il plugin dichiara le proprie abilities → le espone via MCP agli AI assistant → usa WP AI Client per le chiamate al modello, senza mai hardcodare il vendor.

Quando adottare il pattern (e quando evitarlo)

Non tutti i plugin AI devono adottare questo stack. Facciamo chiarezza con un test a tre domande che uso in agenzia prima di approvare un nuovo progetto plugin.

Test delle tre domande

Adotta il pattern se rispondi sì ad almeno due di queste:

1. Il plugin interagisce con un AI assistant esterno (Claude Desktop, ChatGPT MCP, agent custom)?
2. Prevedi di supportare più provider LMO (OpenAI, Anthropic, Ollama, self-hosted) o di poter cambiare provider in futuro senza riscrivere il plugin?
3. Il plugin deve rispettare policy di sicurezza enterprise (capability check, audit log, kill switch)?

Se rispondi no a due su tre, stai over-engineering. Un plugin AI semplice - ad esempio uno che genera excerpt automaticamente - può usare direttamente WP AI Client saltando abilities e MCP, oppure restare su wp_remote_post() per una singola API key fissa.

Profili tipici di adozione

• Agenzia che sviluppa per clienti enterprise: pattern obbligatorio. Compliance, audit e portabilità tra provider sono requisiti di contratto.
• Freelance con 5-10 clienti piccoli: pattern consigliato. Il costo di setup si ammortizza in 2-3 progetti e la manutenzione è più semplice.
• Hobbista con un solo progetto: pattern eccessivo. Meglio una funzione custom in functions.php.
• Plugin commerciale in vendita su .org: pattern raccomandato dal Plugin Team. La review del 2026 premia i plugin che adottano standard aperti.

Anatomia di un'ability WordPress

Un'ability è un'unità dichiarativa: nome, descrizione, parametri, handler. Vediamo l'implementazione minima tratta dal tutorial wordpress.tv.

Registrare un'ability

add_action( 'abilities_api_init', 'mia_registra_ability_post_summary' );
function mia_registra_ability_post_summary() {
    wp_register_ability( 'content/summarize-post', array(
        'label'       => __( 'Riassumi post WordPress', 'mio-plugin' ),
        'description' => __( 'Genera un riassunto di 60 parole di un post pubblicato.', 'mio-plugin' ),
        'category'    => 'content',
        'input_schema' => array(
            'type' => 'object',
            'properties' => array(
                'post_id' => array( 'type' => 'integer', 'minimum' => 1 ),
                'max_words' => array( 'type' => 'integer', 'default' => 60 ),
            ),
            'required' => array( 'post_id' ),
        ),
        'output_schema' => array(
            'type' => 'object',
            'properties' => array(
                'summary' => array( 'type' => 'string' ),
                'tokens_used' => array( 'type' => 'integer' ),
            ),
        ),
        'permission_callback' => function ( $input ) {
            return current_user_can( 'edit_post', $input['post_id'] );
        },
        'execute_callback' => 'mia_execute_summarize_post',
    ) );
}

Tre dettagli che fanno la differenza rispetto a un custom endpoint REST: la description è leggibile dall'AI assistant (è il campo che popola la MCP tool list), input_schema e output_schema rendono l'ability validabile senza scrivere validator custom, e permission_callback è valutato prima dell'esecuzione. Niente più capability check duplicati in cinque punti del codice.

L'handler: cosa non fare

function mia_execute_summarize_post( $input ) {
    $post = get_post( $input['post_id'] );
    if ( ! $post ) {
        return new WP_Error( 'post_not_found', __( 'Post non trovato.', 'mio-plugin' ) );
    }
    // delega al client AI, non alla chiamata vendor
    $client = wp_ai_client();
    $response = $client->generate_text( array(
        'model' => 'auto',
        'system' => 'Sei un editor tecnico che riassume in italiano corretto.',
        'prompt' => wp_strip_all_tags( $post->post_content ),
        'max_tokens' => (int) ( $input['max_words'] * 1.5 ),
    ) );
    if ( is_wp_error( $response ) ) {
        return $response;
    }
    return array(
        'summary' => $response['text'],
        'tokens_used' => $response['usage']['total_tokens'] ?? 0,
    );
}

Nota: nessuna API key nel codice, nessuna chiamata diretta a un endpoint vendor. wp_ai_client() è la factory ufficiale introdotta dal Plugin Team, e l'argomento model => 'auto' lascia al client la scelta del modello in base a policy, costo e disponibilità. Questo è il punto: cambiare provider significa cambiare una costante di config, non riscrivere l'handler.

Esposizione MCP: dal plugin al desktop AI

Una volta registrate le abilities, esporle via MCP richiede il secondo mattoncino. Il Plugin Team mantiene un adapter (wp-abilities-mcp-adapter) che pubblica le abilities come MCP tools.

Setup dell'adapter MCP

add_action( 'mcp_adapter_init', 'mia_registra_mcp_server' );
function mia_registra_mcp_server() {
    $adapter = wp_mcp_adapter();
    $adapter->register_server( 'mio-plugin', array(
        'name'         => 'Mio Plugin AI',
        'version'      => '1.0.0',
        'abilities'    => array( 'content/summarize-post' ),
        'capabilities' => array( 'tools' ),
    ) );
}

Da questo momento, un client MCP (Claude Desktop, Cursor, Continue.dev, ChatGPT con supporto MCP) può connettersi al sito via STDIO o streamable HTTP e vedere summarize-post come tool disponibile. L'AI assistant può decidere autonomamente di chiamarlo quando l'utente chiede "riassumi l'ultimo post pubblicato".

Tre guardrail operativi non negoziabili

Quando esponi abilities via MCP, la superficie d'attacco aumenta: un client compromesso potrebbe chiamare strumenti con input malevoli. Tre regole ferree.

1. Whitelist di ability id: non esporre mai tutte le abilities registrate. Decidi tu quali sono "esterne".
2. Rate limit per ability: aggiungi un token bucket. Il Plugin Team consiglia wp_ai_client_rate_limit() con scope per user_id e ability_id.
3. Log audit obbligatorio: ogni chiamata MCP deve loggare user_id, ability_id, input_hash, tokens_used, timestamp. Il log non è opzionale, è la base del GDPR compliance.

WP AI Client: il collante tra plugin e provider

WP AI Client è la libreria che rende il pattern portabile. Vediamo le tre feature che lo distinguono da una semplice wp_remote_post() custom.

Feature 1: provider abstraction con capability matrix

$client = wp_ai_client();
$capabilities = $client->get_capabilities();
// output:
// array(
//   'text_generation' => array( 'openai', 'anthropic', 'ollama' ),
//   'image_generation' => array( 'openai' ),
//   'embeddings' => array( 'openai', 'ollama' ),
// )

Il plugin può scegliere dinamicamente un provider in base a cosa deve fare. Se domani Anthropic rilascia image generation, non devi toccare il codice: aggiorni il client.

Feature 2: capability-based access e kill switch

// disabilitare globalmente l'AI per manutenzione
add_filter( 'wp_ai_client_enabled', '__return_false' );
// oppure per singola ability
add_filter( 'wp_ai_client_ability_enabled', function( $enabled, $ability_id ) {
    if ( $ability_id === 'content/summarize-post' && ! current_user_can( 'manage_options' ) ) {
        return false;
    }
    return $enabled;
}, 10, 2 );

Il kill switch wp_ai_client_enabled è fondamentale per chi gestisce flotte di siti: un command injection nel prompt o un breach del provider si bloccano modificando un constant in wp-config.php.

Feature 3: cost tracking integrato

$response = $client->generate_text( array( ... ) );
update_option( 'mio_plugin_ai_cost_june', ( get_option( 'mio_plugin_ai_cost_june' ) ?: 0 ) + $response['cost_usd'] );

$response['cost_usd'] è calcolato dal client conoscendo il pricing del modello usato. Niente più fogli Excel per riconciliare le fatture OpenAI a fine mese.

Caso reale: agenzia con 12 siti clienti

Un'agenzia milanese con cui lavoro ha adottato il pattern su un plugin interno di content brief. Prima: 12 siti, 12 plugin leggermente diversi, 3 provider LLM contrattati a tariffe diverse. Dopo sei mesi col pattern:

• Tempo medio di sviluppo di una nuova ability: passato da 4 ore a 1,5 ore (l'abilità è dichiarativa, l'AI client è condiviso).
• Costo medio mensile AI: sceso del 32% grazie al routing automatico Ollama per task semplici e GPT-4o solo per task complessi.
• Audit GDPR: tempo di generazione report passato da 2 giorni a 4 ore, perché i log sono strutturati e non sparsi in 12 codebase diverse.
• Provider lock-in: eliminato. Sono passati da OpenAI a Anthropic Sonnet in 2 settimane durante un aumento di prezzo, senza toccare i plugin dei clienti.

Roadmap di adozione in 5 step

Una sequenza realistica per adottare il pattern in produzione, basata sull'esperienza con clienti di taglia diversa.

Step 1: audit del plugin esistente

Identifica le funzioni AI attuali. Per ognuna chiediti: usa una API key hardcoded? Ha capability check? Logga le chiamate? Se la risposta è "no" a due su tre, è un candidato alla migrazione.

Step 2: installa WP AI Client

# richiede WP-CLI 2.10+ e PHP 8.1+
wp plugin install wp-ai-client --activate
wp ai-client provider add openai --api-key="$OPENAI_KEY"
wp ai-client provider add ollama --endpoint="http://localhost:11434"

Il comando wp ai-client provider add è la novità 2026: permette di configurare i provider da CLI senza editare costanti a mano.

Step 3: converti una ability esistente

Parti da una singola ability a basso rischio (es. "genera meta description"). Riscrivila seguendo lo schema visto sopra, testa in staging, poi promuovi.

Step 4: esponi via MCP

Installa wp-abilities-mcp-adapter, registra il server MCP, testa la connessione da Claude Desktop o Cursor. Valida che le abilities siano elencate e che i permission callback funzionino.

Step 5: monitora e itera

Imposta un cron giornaliero che aggrega mio_plugin_ai_cost_<mese>, mio_plugin_ai_calls_<mese>, e invia report via email. Rivedi le abilities ogni trimestre: alcune saranno sotto-utilizzate e potranno essere rimosse.

Errori comuni che vedo nelle review

Dopo aver revisionato una dozzina di plugin AI nel 2026, ecco gli errori ricorrenti da evitare.

Errore 1: ability troppo generica

Creare un'ability do_anything($instruction) che accetta un prompt libero e decide lei cosa fare. Sembra flessibile, ma distrugge la capability matrix dell'AI client e rende impossibile il rate limiting. Un'ability deve fare una cosa sola, bene.

Errore 2: permission_callback ingenuo

# esempio codice
'permission_callback' => '__return_true',

Sembra assurdo, ma l'ho visto in due plugin pubblicati nel 2025. Mai. Sempre capability check basato su current_user_can() e validazione dell'input.

Errore 3: log solo in debug.log

Scrive in wp-content/debug.log è comodo ma non è un audit trail. Serve un log strutturato (custom table o rotazione file) con campi indicizzati: user_id, ability_id, cost, timestamp.

Errore 4: dimenticare la deprecazione

Il Plugin Team 2026 rilascia WP AI Client con API che evolvono rapidamente. Un'ability deprecata va marcata con 'status' => 'deprecated' e mantenuta per almeno 6 mesi. Non rimuovere mai silenziosamente.

FAQ

Il pattern funziona anche con plugin gratuiti pubblicati su .org?

Sì, anzi: il Plugin Team 2026 lo raccomanda esplicitamente nei criteri di review. I plugin che adottano abilities + MCP ricevono priorità nella coda di triage. Il tutorial wordpress.tv dell'8 giugno 2026 è nato proprio per supportare gli sviluppatori indipendenti in questa transizione.

Devo abbandonare wp_remote_post() per le chiamate LLM?

Non necessariamente. Se il tuo plugin fa una singola chiamata a una singola API, wp_remote_post() resta valido. Il pattern diventa necessario quando hai più di un'ability, più di un provider, o requisiti di compliance. La regola pratica è: se devi scrivere un wrapper per la chiamata HTTP, stai reinventando WP AI Client.

MCP è compatibile con il vecchio WP 6.x?

No. MCP richiede almeno WP 6.9 per le abilities, e il plugin adapter è testato solo su WP 7.0+. Se il tuo plugin deve supportare WP 6.5, devi restare su REST API classica. Considera questa come una buona scusa per abbandonare il supporto a versioni obsolete.

Posso mischiare abilities registrate e REST endpoint tradizionali?

Tecnicamente sì, concettualmente no. Ogni endpoint REST non mappato su un'ability è una superficie d'attacco non documentata per l'AI assistant. Meglio migrare tutto al pattern, o tenere il legacy fuori dal server MCP.

Il self-hosted LLM (Ollama) è production-ready con questo pattern?

Sì, con cautele. Ollama è supportato da WP AI Client da aprile 2026, e il pattern di routing "Ollama per task semplici, cloud per task complessi" è quello che uso di default. Vedi la mia guida a WordPress e LLM self-hosted per i dettagli di setup.

Quanto pesa in performance il pattern rispetto a una chiamata diretta?

Misurato su un sito staging: +12ms per chiamata a causa del layer di astrazione. Su un endpoint REST chiamato 100 volte al minuto è trascurabile. Se hai un carico anomalo (es. bulk generation di 1000 articoli), valuta batch async con WP-CLI asincrono.

Conclusione: il pattern è il futuro, ma adottalo con criterio

Il pattern abilities + MCP + WP AI Client non è una moda passeggera. È la risposta del Plugin Team a un bisogno reale: plugin AI portabili, sicuri e manutenibili. Detto questo, adottalo solo se il tuo caso d'uso lo giustifica. Un plugin che genera una sola stringa non ha bisogno di MCP, ma se stai costruendo un prodotto commerciale o un sistema interno per agenzia, questo pattern ti farà risparmiare mesi di refactoring.

Checklist operativa pre-pubblicazione

• Almeno un'ability registrata con input_schema e output_schema documentati
• Permission callback su ogni ability
• Rate limit configurato per ability e per user
• Log audit attivo con campi user_id, ability_id, cost, timestamp
• Kill switch wp_ai_client_enabled testato e funzionante
• Server MCP in staging con test da Claude Desktop o Cursor
• Cost tracking aggregato su base mensile
• Policy di deprecazione scritta per le abilities

Se la checklist è verde, il tuo plugin è pronto per la review 2026 del Plugin Team. Se è rossa su più di due punti, vale la pena rivedere l'architettura prima di pubblicare.

Riferimenti utili per approfondire

• Tutorial ufficiale "Build your first AI-powered WordPress plugin" su wordpress.tv - il video di riferimento da cui è nato l'articolo
• Repository GitHub WordPress/wp-ai-client - codice della libreria ufficiale del Plugin Team
• Specifica Model Context Protocol di Anthropic - documento tecnico del protocollo MCP
• WordPress 7.0 AI Connectors: guida operativa - come i Connectors dialogano con WP AI Client
• WPVibe e MCP per WordPress - caso commerciale di adozione MCP lato utente finale
• Repository WordPress/wp-abilities - reference implementation della Abilities API
• Documentazione Plugin Team su review 2026 - criteri aggiornati per plugin AI
• Esempio completo di plugin MCP-based - codice di partenza pronto all'uso
• OpenCode per temi WordPress con MCP - integrazione lato IDE di MCP per sviluppatori
• Creare plugin WordPress con AI: metodo completo - workflow completo per chi parte da zero
• AI workflow agenzia WordPress 2026 - come le agenzie adottano il pattern su più progetti
• WP-CLI nel 2026 con AI - automazione CLI del pattern abilities

L'angolo è architetturale e operativo, non promozionale. Vediamo il protocollo MCP in dettaglio, il plugin Vibe AI che lo implementa su WordPress, e forniamo snippet di codice per chi vuole costruire un proprio MCP server custom. È complementare alla panoramica WordPress 7.0 e AI Connectors e al metodo per creare plugin con AI.

Cos'è il Model Context Protocol e perché riguarda WordPress

MCP è uno standard aperto, rilasciato da Anthropic a fine 2024 e diventato rapidamente il protocollo di riferimento per connettere modelli AI a strumenti esterni. L'analogia corretta è USB-C per l'AI: invece di scrivere un'integrazione diversa per ogni coppia (modello × tool), chi sviluppa il tool espone un server MCP, e qualsiasi modello compatibile (Claude, ChatGPT, Cursor, Cline) può consumarlo.

Prima di MCP, l'integrazione funzionava così:

• L'utente copia un prompt da ChatGPT
• Lo incolla in WordPress
• L'AI restituisce un testo
• L'utente lo incolla di nuovo nell'editor

Con MCP, il flusso diventa:

• L'utente dice a Claude: "Crea un articolo sul mio ultimo prodotto, aggiungi un'immagine da Unsplash, schedulalo per venerdì"
• Claude parla con il server MCP di WordPress esposto dal plugin
• Il server MCP traduce le istruzioni in chiamate WordPress reali (wpinsertpost, wpmediasideloadimage, wpupdate_post)
• Claude conferma e l'utente vede il draft nell'admin

È la differenza tra "AI che genera testo" e "AI che esegue azioni".

WPVibe: il plugin che porta MCP su WordPress

WPVibe (disponibile gratuitamente su WordPress.org come Vibe AI) è un plugin sviluppato dal team di SeedProd (il page builder usato da oltre 1 milione di siti) che implementa un server MCP completo per WordPress. Una volta installato e configurato, espone un endpoint HTTPS che può essere collegato a Claude, ChatGPT, Cursor, o qualsiasi client compatibile MCP.

Cosa può fare concretamente

Il plugin espone una serie di "tools" che il modello AI può invocare. Ecco l'elenco ufficiale al momento del lancio.

• wpvibe_create_post: crea un nuovo post (status bozza di default, titolo, contenuto, categorie, tag)
• wpvibe_update_post: aggiorna un post esistente
• wpvibe_list_posts: elenca post recenti con filtri (status, data, autore)
• wpvibe_upload_media: carica un'immagine da URL o da prompt Unsplash nella libreria media
• wpvibe_set_featured_image: imposta la featured image di un post
• wpvibe_list_plugins: elenca plugin attivi con versione e stato aggiornamento
• wpvibe_health_check: esegue controlli diagnostici (versione PHP, spazio disco, plugin outdated)
• wpvibe_search_unsplash: cerca foto stock tramite query testuale
• wpvibe_edit_theme_file_sandboxed: modifica file del tema in ambiente sandbox (mai scritto direttamente su disco)
• wpvibe_run_wpcli: esegue un sottoinsieme limitato di comandi WP-CLI (whitelist)

L'elenco è in crescita. Il team SeedProd ha annunciato che aggiungeranno strumenti per WooCommerce (gestione ordini, prodotti, inventario) e per i custom post type nei prossimi mesi.

Setup in 60 secondi

L'installazione è volutamente semplice.

1. Installa il plugin: Bacheca → Plugin → Aggiungi nuovo → cerca "Vibe AI" → Installa → Attiva
2. Genera il token di accesso: il plugin crea automaticamente un'application password WordPress (sistema nativo introdotto in WP 5.6) con scope limitato alle capability MCP
3. Copia l'endpoint MCP: si trova in Impostazioni → Vibe AI → Connection. È un URL tipo https://tuosito.it/wp-json/wpvibe/v1/mcp
4. Collega il client AI: in Claude/ChatGPT/Cursor, apri la sezione "Connectors" o "MCP Servers", incolla l'endpoint, autenticati con la application password
5. Testa la connessione: digita "Elenca i miei ultimi 5 articoli pubblicati"

Da quel momento il modello può eseguire i task elencati sopra. La prima connessione richiede circa 60 secondi, le successive sono istantanee.

Architettura di sicurezza: perché i guardrail contano

Un server MCP che può modificare il tuo sito è un'arma a doppio taglio. SeedProd ha implementato una serie di guardrail espliciti, documentati pubblicamente. Vediamoli uno per uno.

Guardrail 1: nuovi post in draft di default

Ogni post creato via WPVibe va in stato draft, mai pubblicato direttamente. Questo significa che un'AI che decide di "sbagliare tono" su un articolo importante richiede un'azione umana esplicita per andare online. È il guardrail più semplice e più importante.

Guardrail 2: cancellazioni vanno nel cestino

Quando l'AI elimina un contenuto, va nel cestino di WordPress (dove resta recuperabile per 30 giorni), non viene rimosso definitivamente. Doppio livello di safety: l'AI può solo spostare, non cancellare.

Guardrail 3: modifiche ai temi in sandbox

Questo è il guardrail più elegante. Quando l'AI modifica un file del tema (functions.php, header.php, style.css), la modifica va in un file sandbox separato, non sovrascrive il file originale. L'utente vede un diff e deve approvare esplicitamente prima che la modifica venga applicata. In caso di errore, basta scartare il diff.

// Struttura del sandbox (pseudocodice del sistema)
$active_theme = wp_get_theme();
$sandbox_dir  = WP_CONTENT_DIR . '/uploads/wpvibe-sandbox/' . $active_theme->get_stylesheet();
$original     = get_template_directory() . '/functions.php';
$sandbox_file = $sandbox_dir . '/functions.php.sandbox';

if ( ! file_exists( $sandbox_dir ) ) {
    wp_mkdir_p( $sandbox_dir );
}

// L'AI scrive solo nel sandbox, mai nell'originale
file_put_contents( $sandbox_file, $modified_content );

// Review umana
register_shutdown_function( function() use ( $sandbox_file, $original ) {
    if ( current_user_can( 'edit_themes' ) && get_transient( 'wpvibe_apply_sandbox' ) ) {
        copy( $sandbox_file, $original );
        delete_transient( 'wpvibe_apply_sandbox' );
    }
} );

Guardrail 4: WP-CLI in whitelist

L'AI può eseguire solo comandi WP-CLI in una whitelist predefinita. I comandi pericolosi (rm, drop, truncate, exec) sono bloccati a livello di capability. La whitelist è consultabile e personalizzabile dagli admin del sito.

// Whitelist WP-CLI di default
add_filter( 'wpvibe_wpcli_whitelist', function( $commands ) {
    $commands = [
        'wp post list',
        'wp post get',
        'wp option get',
        'wp user list',
        'wp plugin list',
        'wp theme list',
        'wp db query',  // attenzione: solo SELECT, monitorato
        'wp cache flush',
        'wp transient delete --all',
    ];
    return $commands;
} );

Guardrail 5: autenticazione via application password

Il plugin usa il sistema nativo WordPress di application password (RFC 2FA-style, supportato dal core dalla 5.6). Le credenziali sono cifrate a riposo, sono revocabili in un click dall'admin, e possono essere limitate a un sottoinsieme di capability.

Caso d'uso reale: agenzia con 15 siti clienti

Marco gestisce un'agenzia di sviluppo web con 15 siti clienti su managed hosting. Ha implementato WPVibe su tutti e 15 i siti e usa Claude (con il piano Pro) come client MCP centrale. Ecco come ha strutturato il workflow.

Workflow mattutino (15 min)

1. Chiede a Claude: "Mostrami tutti i post pubblicati ieri sera su tutti i miei siti, con il numero di commenti per ciascuno"
2. Claude interroga i 15 server MCP in parallelo (la chiamata MCP supporta richieste multiple), aggrega i risultati, produce un report
3. Marco legge il report in chat e decide se intervenire

Workflow editoriale (1 ora → 15 min)

1. Marco riceve una brief da un cliente: "5 articoli sul tema X, stile Y, con immagini"
2. Chiede a Claude: "Per il sito example.com, genera 5 bozze di articoli sul tema X, stile Y, con immagini da Unsplash, tutti in draft"
3. Claude crea 5 draft, ciascuno con featured image, tag, e categoria corretta
4. Marco legge le bozze in Bacheca (draft visibili), modifica dove serve, pubblica

Manutenzione tecnica

1. Marco: "Verifica salute di tutti i miei siti: versione PHP, plugin outdated, spazio disco"
2. Claude esegue wpvibe_health_check su tutti i server, aggrega, segnala i problemi
3. Marco interviene manualmente sui siti con problemi

Risultato: tempo risparmiato ~6 ore/settimana, ROI del setup in meno di un mese.

Limiti e problemi reali di WPVibe

Non è tutto rose e fiori. Ecco i limiti che ho incontrato nei test.

Limite 1: il client AI deve supportare MCP nativamente

Al momento, i client che supportano MCP out-of-the-box sono: Claude (desktop, web, Code), Cursor (editor AI), Cline (estensione VS Code), e pochi altri. ChatGPT supporta MCP in beta ristretta per utenti Pro. Gemini no. Per chi usa prevalentemente ChatGPT, il vantaggio è ancora parziale.

Limite 2: l'AI può solo eseguire i tool esposti

Se vuoi che l'AI possa, per esempio, modificare le impostazioni di un plugin SEO, quel plugin deve avere un tool MCP registrato. WPVibe espone i tool nativi WordPress, ma per integrazioni con plugin terzi serve lavoro custom. Stanno arrivando estensioni community per Yoast, Rank Math, WooCommerce, ma è work in progress.

Limite 3: la latenza delle operazioni multiple

Se chiedi a Claude "Crea 10 articoli", ogni articolo richiede una chiamata MCP separata. Su un sito con hosting lento, 10 articoli = 30-60 secondi. Per task di massa meglio fare batch via WP-CLI tradizionale.

Limite 4: nessuna memoria persistente cross-sessione

L'AI non ricorda le tue preferenze tra una sessione e l'altra. Se gli dici "usa sempre lo stile formale", devi ridirlo ogni volta. Soluzione: usare il file CLAUDE.md (per Claude) o AGENTS.md (per Cursor) per memorizzare le convenzioni del sito.

Costruire il proprio MCP server WordPress custom

Se WPVibe non fa al caso tuo (ad esempio, vuoi esporre strumenti custom del tuo tema o plugin), puoi costruire un server MCP custom. Ecco un esempio minimale.

<?php
/**
 * Plugin Name: My Custom MCP Server
 * Description: Esempio di server MCP custom per WordPress
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

// 1. Registra l'endpoint REST
add_action( 'rest_api_init', function() {
    register_rest_route( 'my-mcp/v1', '/tools', [
        'methods'             => 'GET',
        'callback'            => 'mymcp_list_tools',
        'permission_callback' => function() {
            return current_user_can( 'edit_posts' );
        },
    ] );

    register_rest_route( 'my-mcp/v1', '/invoke', [
        'methods'             => 'POST',
        'callback'            => 'mymcp_invoke_tool',
        'permission_callback' => function() {
            return current_user_can( 'edit_posts' );
        },
    ] );
} );

// 2. Lista dei tool esposti
function mymcp_list_tools() {
    return [
        'tools' => [
            [
                'name'        => 'get_recent_comments',
                'description' => 'Restituisce gli ultimi commenti del blog',
                'inputSchema' => [
                    'type'       => 'object',
                    'properties' => [
                        'limit' => [
                            'type'        => 'integer',
                            'description' => 'Numero massimo di commenti',
                            'default'     => 10,
                        ],
                    ],
                ],
            ],
            [
                'name'        => 'get_site_stats',
                'description' => 'Restituisce statistiche aggregate del sito',
                'inputSchema' => [
                    'type'       => 'object',
                    'properties' => (object) [],
                ],
            ],
        ],
    ];
}

// 3. Invocazione del tool
function mymcp_invoke_tool( WP_REST_Request $request ) {
    $body = $request->get_json_params();
    $tool = sanitize_text_field( $body['name'] ?? '' );
    $args = $body['arguments'] ?? [];

    switch ( $tool ) {
        case 'get_recent_comments':
            $limit  = absint( $args['limit'] ?? 10 );
            $comments = get_comments( [ 'number' => $limit, 'status' => 'approve' ] );
            return rest_ensure_response( [
                'comments' => array_map( function( $c ) {
                    return [
                        'id'       => $c->comment_ID,
                        'author'   => $c->comment_author,
                        'content'  => $c->comment_content,
                        'post_id'  => $c->comment_post_ID,
                        'date'     => $c->comment_date,
                    ];
                }, $comments ),
            ] );

        case 'get_site_stats':
            return rest_ensure_response( [
                'posts'        => wp_count_posts()->publish,
                'pages'        => wp_count_posts( 'page' )->publish,
                'comments'     => wp_count_comments()->approved,
                'users'        => count_users()['total_users'],
                'php_version'  => phpversion(),
                'wp_version'   => get_bloginfo( 'version' ),
            ] );

        default:
            return new WP_Error( 'unknown_tool', 'Tool non riconosciuto', [ 'status' => 400 ] );
    }
}

Questo è uno scheletro funzionante. Per un server MCP completo servono altri endpoint (risorse, prompt templates, gestione errori strutturata secondo lo standard MCP), ma il pattern è questo.

Domande frequenti

WPVibe è davvero gratuito?

Sì, il plugin Vibe AI è gratuito e open source su WordPress.org. Il team SeedProd lo monetizza indirettamente (è una leva per il loro page builder a pagamento), ma il plugin in sé non ha limitazioni, watermark, o costi nascosti.

Posso usarlo con ChatGPT?

Dipende. ChatGPT ha aggiunto il supporto MCP in beta ristretta per utenti Pro a fine 2025. Se sei nel rollout, sì. Altrimenti Claude Desktop e Cursor sono le opzioni più affidabili. Gemini non supporta MCP al momento.

L'AI può cancellare definitivamente un post?

No. Il guardrail del cestino è hardcoded: qualsiasi cancellazione passa per wp_trash_post(), mai wp_delete_post() con force_delete = true. I post nel cestino sono recuperabili per 30 giorni dall'admin WordPress.

È sicuro esporre l'endpoint MCP su internet?

Sì, a patto di: (1) usare HTTPS, (2) autenticare ogni richiesta con application password, (3) mantenere il plugin aggiornato, (4) monitorare i log per attività sospette. L'endpoint è protetto almeno quanto wp-admin.

Cosa succede se l'AI propone modifiche sbagliate al tema?

Vanno tutte nel sandbox. L'utente vede un diff e deve approvare. Se approva per sbaglio, il file originale viene sovrascritto: per questo è essenziale avere un backup (UpdraftPlus, BlogVault, o snapshot del hosting).

Vale la pena rispetto a Jetpack AI o Divi AI?

Sono prodotti diversi. Jetpack AI e Divi AI lavorano dentro l'editor di un singolo post, con focus su generazione di testo. WPVibe lavora a livello di sito, con focus su automazione e orchestrazione via linguaggio naturale. Per un blogger singolo, Jetpack AI è più immediato. Per un'agenzia, WPVibe è enormemente più potente.

WPVibe funziona con WooCommerce?

Al lancio no, ma il team ha annunciato integrazione WooCommerce in roadmap Q3 2026 (gestione ordini, prodotti, inventario via MCP). Per ora, plugin terzi stanno già sperimentando bridge custom.

Riferimenti utili per approfondire

• WPVibe sito ufficiale - documentazione completa e setup guidato.
• Vibe AI su WordPress.org - download e recensioni.
• Model Context Protocol spec Anthropic - documentazione tecnica del protocollo.
• SeedProd page builder - chi sviluppa WPVibe.
• MCP servers directory ufficiale - catalogo di server MCP community.
• WordPress Application Passwords - come funziona il sistema di autenticazione usato da WPVibe.
• Claude Desktop MCP setup - come collegare Claude come client MCP.
• WordPress 7.0 AI Connectors mrtux.it - confronto con l'approccio alternativo dei Connectors core.
• Creare plugin WordPress con AI mrtux.it - per chi vuole costruire il proprio MCP server.
• Sicurezza WordPress plugin piratati mrtux.it - rischi da considerare quando si espongono endpoint.

Questa guida verrà aggiornata quando arriveranno le integrazioni WooCommerce e i tool community. Per casi d'uso specifici o problemi di setup, l'area commenti è aperta.

Questo tutorial spiega come usare il plugin WP Novamira in modo pratico, partendo dalla documentazione ufficiale e mantenendo un principio fondamentale: Novamira è uno strumento potente, pensato per sviluppo e staging, non per fare esperimenti direttamente su un sito in produzione.

Se lavori già con WordPress, AI e progettazione di temi, puoi collegare questo workflow anche ad altri approfondimenti pubblicati su MrTux, come la guida su AI per migliorare SEO, UX e design su WordPress, il metodo per creare articoli WordPress ottimizzati SEO con AI e l'analisi sugli strumenti per il web design di temi WordPress.

Cos'è Novamira.ai e perché interessa ai designer WordPress

Novamira è un plugin WordPress che consente a client AI compatibili con MCP, come Claude, Cursor, VS Code Copilot o altri strumenti che supportano il protocollo, di interagire con WordPress in modo programmatico. Secondo la documentazione ufficiale Getting started, il plugin permette all'AI assistant di eseguire codice PHP, leggere e scrivere file, gestire database, installare plugin e costruire funzionalità personalizzate.

Per il web design WordPress, questo significa poter lavorare con un agente AI che non si limita a suggerire codice in astratto, ma può leggere la struttura reale del sito, controllare il tema, verificare plugin attivi, creare file nella sandbox e iterare sulle modifiche con maggiore contesto.

Novamira non va interpretato come un page builder automatico, ma come un ponte operativo tra WordPress e un assistente AI tecnico.

Prima di iniziare: requisiti tecnici

Prima di installare Novamira, conviene verificare che l'ambiente sia adeguato. La pagina ufficiale sui requisiti Novamira indica alcune condizioni minime da rispettare.

Per installazioni locali senza HTTPS, la documentazione spiega che è possibile impostare WP_ENVIRONMENT_TYPE su local nel file wp-config.php. Questa eccezione va usata solo in locale, non su server remoti.

Installare Novamira su WordPress

La procedura di installazione è simile a quella di molti plugin premium o distribuiti via ZIP. La guida ufficiale Installation indica un flusso diretto: scaricare il file ZIP, caricarlo da WordPress e attivarlo.

1. Scarica l'ultima versione ZIP di Novamira dalla pagina di download ufficiale.
2. Entra nel pannello WordPress del sito di sviluppo o staging.
3. Vai in Plugin > Aggiungi nuovo plugin > Carica plugin.
4. Seleziona il file ZIP di Novamira e clicca su Installa ora.
5. Attiva il plugin.

All'attivazione, Novamira registra il MCP Adapter incluso, espone un menu dedicato nella sidebar admin e prepara le otto abilità principali. Le abilità AI, però, restano disattivate di default: nessun tool MCP viene esposto finché non viene abilitato esplicitamente.

Configurare le AI Abilities

Dopo l'installazione, il passaggio più importante è la configurazione. La pagina ufficiale Configuration spiega che bisogna abilitare manualmente le AI Abilities da Novamira > Settings.

1. Apri il pannello WordPress.
2. Vai in Novamira > Settings.
3. Attiva la checkbox Enable AI Abilities.
4. Leggi con attenzione il messaggio di conferma.
5. Conferma e salva le impostazioni.

Quando le abilità sono attive, compare un indicatore rosso Novamira ON nella barra di amministrazione. È un promemoria utile: in quel momento l'AI agent può accedere agli strumenti MCP collegati al sito.

Le otto abilità disponibili

Novamira registra otto abilità principali. Per un web designer o sviluppatore WordPress, è importante capire cosa fanno prima di usarle in un flusso reale.

Collegare il client AI tramite MCP

Una volta abilitate le AI Abilities, bisogna collegare il client AI. La guida Connecting Your AI Client descrive il processo basato su Application Password e configurazione MCP.

1. Crea una Application Password

Da Novamira > Connect, crea una nuova Application Password. WordPress mostrerà la password una sola volta: copiala subito e conservala in modo sicuro. È consigliabile usare un nome descrittivo, ad esempio il nome del client o della workstation.

2. Configura il client MCP

Novamira fornisce snippet per client come Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Zed e OpenCode. Il modello generale usa npx per avviare il proxy remoto @automattic/mcp-wordpress-remote.

{
  "mcpServers": {
    "novamira": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote@latest"],
      "env": {
        "WP_API_URL": "https://your-site.com/wp-json/mcp/mcp-adapter-default-server",
        "WP_API_USERNAME": "your-wordpress-username",
        "WP_API_PASSWORD": "your-application-password"
      }
    }
  }
}

Nel tuo caso reale dovrai sostituire URL, username e Application Password con quelli del sito di staging. Dopo aver salvato la configurazione, riavvia il client AI: molti strumenti caricano i server MCP solo all'avvio.

3. Verifica la connessione

Per verificare che tutto funzioni, chiedi all'agente AI un'operazione semplice e non distruttiva, ad esempio elencare i plugin installati. Se la connessione è corretta, il client dovrebbe mostrare gli strumenti Novamira e usare Execute PHP o le altre abilità disponibili.

Tutorial pratico: usare Novamira per migliorare un layout WordPress

Un caso d'uso realistico per il web design è l'ottimizzazione di una pagina WordPress esistente. L'obiettivo non è chiedere all'AI di "rifare tutto", ma guidarla con richieste progressive e verificabili.

1. Mappa il sito: chiedi all'agente di identificare tema attivo, plugin principali e struttura dei template.
2. Analizza la pagina: fai leggere template, CSS e blocchi coinvolti nella pagina da migliorare.
3. Definisci il problema: per esempio hero troppo pesante, CTA poco visibile, spaziature incoerenti o layout mobile debole.
4. Chiedi una proposta: prima solo piano di intervento, poi modifica mirata.
5. Applica in staging: usa Edit File o file sandbox, mai direttamente su produzione.
6. Verifica risultato: controlla frontend, editor WordPress, mobile e performance.
7. Disabilita o raffina: se una modifica non convince, disabilita il file sandbox o chiedi una correzione puntuale.

Un prompt pratico potrebbe essere: "Analizza il tema attivo e proponi un miglioramento del layout della pagina servizi. Non modificare file finché non approvo il piano. Concentrati su leggibilità, CTA, mobile e compatibilità con Gutenberg".

Sicurezza: cosa fare e cosa evitare

La parte più importante della documentazione Novamira è quella sulla sicurezza. La pagina Security & Best Practices chiarisce che Novamira offre accesso programmatico reale al sito WordPress. Questo è il suo valore, ma anche il motivo per cui va usato con disciplina.

La documentazione su uso live/production è molto esplicita: le AI abilities dovrebbero essere attivate solo su ambienti di sviluppo e staging, mai direttamente in produzione. Il plugin può rimanere installato sul sito live, ma le abilità AI devono restare disattivate.

• Usa sempre backup prima di lavorare con AI agents.
• Configura Novamira su staging o sviluppo, non sul sito live.
• Approva ogni tool call prima dell'esecuzione.
• Crea Application Password separate per client o workstation.
• Revoca le password non più usate.
• Evita richieste vaghe come "sistema il sito".
• Preferisci interventi piccoli, verificabili e reversibili.

Capire la sandbox

La sandbox Novamira si trova in wp-content/novamira-sandbox/. Secondo la pagina ufficiale The Sandbox, i file PHP scritti dagli AI agent vengono confinati in questa directory e caricati automaticamente a ogni richiesta WordPress tramite un loader must-use.

Questo rende la sandbox utile per organizzare codice generato dall'AI: shortcode, endpoint REST, custom post type, funzioni di supporto o piccoli esperimenti. Ma la documentazione precisa anche un punto essenziale: la sandbox non è una vera barriera di sicurezza. Il codice che gira lì ha comunque privilegi simili a quelli di un plugin WordPress.

Quando Novamira è utile nel web design WordPress

Novamira diventa interessante quando il progetto richiede lavoro tecnico su un sito reale: analisi del tema, creazione di funzionalità, debug, verifica plugin, generazione di CSS mirato, integrazioni PHP o miglioramenti di workflow. Non sostituisce Figma, Gutenberg o un buon processo di design; li affianca nella fase di implementazione e revisione tecnica.

• Utile: staging, prototipi, debug, sviluppo custom, analisi plugin, refactoring controllato.
• Da evitare: test diretti su produzione, modifiche non approvate, prompt troppo generici, assenza di backup.
• Da valutare: team con più sviluppatori, processi di deploy, policy interne e gestione credenziali.

FAQ su Novamira e WordPress

Novamira è un page builder AI?

No. Novamira non è un page builder visuale. È un plugin che collega AI agents a WordPress tramite MCP, dando accesso a strumenti tecnici per leggere, modificare e testare il sito.

Posso usarlo su un sito in produzione?

La documentazione consiglia di usare le AI abilities solo su sviluppo o staging. Su produzione il plugin può restare installato, ma le abilità AI dovrebbero rimanere disattivate.

Serve Node.js?

Per connessioni remote tramite MCP proxy serve Node.js 18 o superiore lato client. Per installazioni locali con WP-CLI è possibile usare il trasporto STDIO, che non richiede Node.js.

La sandbox rende sicuro il codice generato dall'AI?

No. La sandbox aiuta a organizzare e gestire i file PHP generati, ma non va considerata una barriera di sicurezza. Il codice va sempre revisionato prima di portarlo in produzione.

Conclusione

Novamira.ai è uno strumento potente per chi lavora con WordPress in modo tecnico. Permette a un AI agent di operare con molto più contesto rispetto al classico copia e incolla di codice, aprendo scenari interessanti per sviluppo, debug, prototipazione e miglioramento del web design.

Il modo migliore per iniziare è prudente: installa Novamira su staging, abilita le AI Abilities solo quando servono, collega un client MCP, prova operazioni non distruttive e lavora sempre per passaggi piccoli. Se il risultato è valido, potrai poi portarlo nel normale flusso di deploy. L'AI diventa davvero utile quando accelera il lavoro senza togliere controllo al professionista.