Collegare un agente AI

01Prima di iniziare

Serve WordPress 6.9 o successivo, PHP 8.2 o successivo, i permalink attivi e un utente amministratore per aggiungere l'agente.

Il sito deve rispondere in HTTPS. Una richiesta OAuth in chiaro riceve l'errore https_required, salvo negli ambienti di sviluppo (tipo local o development). Dietro un proxy o un bilanciatore, il proxy deve inoltrare l'intestazione X-Forwarded-Proto: https.

02Come funziona

03URL del server

Lo trovi in Nucleo AI → Agenti AI, già pronto da copiare. Ha sempre questa forma:

https://tuo-sito.it/wp-json/nucleo/v1/mcp

04Configurazione per client

Scegli il tuo client. Sui server di sviluppo puoi collegarti anche da terminale con wp nucleo mcp --user=login.

# aggiunge il server MCP di Nucleo a Claude Code
claude mcp add --transport http nucleo https://tuo-sito.it/wp-json/nucleo/v1/mcp

# server MCP su STDIO con i permessi dell'utente indicato
wp nucleo mcp --user=admin

Agente aggiunto a mano

Nella pagina Nucleo AI → Agenti AI, "Add agent" registra un client con un nome e un URL di ritorno (redirect). L'URL deve usare https, oppure http solo su localhost o 127.0.0.1. Il client_id compare una sola volta: copialo subito.

"Add confidential agent" registra un client con client secret. Inserisci un URL di ritorno per riga. Il plugin genera il secret e lo mostra una sola volta, alla pagina successiva, insieme al client_id. Nel database resta solo l'hash.

Registrazione dinamica

Se la attivi, i client si registrano da soli senza che tu li aggiunga a mano. È spenta di default.

Con la lista dei domini ammessi non vuota, anche un client registrato da solo deve avere l'URL di ritorno su un dominio della lista (vedi sotto).

Domini ammessi

Nella pagina Agenti AI puoi indicare i domini ammessi, uno per riga, senza protocollo. Lista vuota: nessun vincolo.

Con domini in lista:

• un client che usa un documento di metadati (client_id https) è accettato solo se il suo host è nella lista;
• un client registrato da solo è accettato solo se ogni URL di ritorno è su un host della lista.

Un host è ammesso se è uguale a un dominio della lista o è un suo sottodominio. Gli agenti aggiunti a mano non sono soggetti alla lista.

Intestazione Authorization

Se il server rimuove l'intestazione Authorization, gli agenti non riescono ad autenticarsi. La pagina Agenti AI lo segnala e propone di scrivere nel .htaccess della radice la regola che passa l'intestazione a PHP (Apache). Se il file non è scrivibile, aggiungi la regola a mano.

05Permessi

Ogni richiesta dell'agente appartiene a un ambito. Gli ambiti che il tuo ruolo non può concedere appaiono disattivati nella pagina di autorizzazione.