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