Connect an AI agent

01Before you start

You need WordPress 6.9 or later, PHP 8.2 or later, pretty permalinks and an administrator account to add the agent.

The site must answer over HTTPS. A plain HTTP OAuth request receives the error https_required, except in development environments (type local or development). Behind a proxy or a load balancer, the proxy must forward the header X-Forwarded-Proto: https.

02How it works

03Server URL

You find it in Nucleo AI → AI agents, ready to copy. It always has this form:

https://your-site.com/wp-json/nucleo/v1/mcp

04Client setup

Pick your client. On development servers you can also connect from the terminal with wp nucleo mcp --user=login.

# adds the Nucleo MCP server to Claude Code
claude mcp add --transport http nucleo https://your-site.com/wp-json/nucleo/v1/mcp

# MCP server over STDIO with the given user's permissions
wp nucleo mcp --user=admin

Agent added by hand

On the Nucleo AI → AI agents page, "Add agent" registers a client with a name and a return URL (redirect). The URL must use https, or http only on localhost or 127.0.0.1. The client_id appears only once: copy it right away.

"Add confidential agent" registers a client with a client secret. Enter one return URL per line. The plugin generates the secret and shows it only once, on the next page, together with the client_id. The database keeps only the hash.

Dynamic registration

When you turn it on, clients register themselves without you adding them by hand. It is off by default.

With the allowed domains list not empty, a client that registers itself must also have its return URL on a domain in the list (see below).

Allowed domains

On the AI agents page you can enter the allowed domains, one per line, without a protocol. An empty list means no limit.

With domains in the list:

• a client that uses a metadata document (client_id over https) is accepted only if its host is in the list;
• a client that registers itself is accepted only if every return URL is on a host in the list.

A host is allowed if it equals a domain in the list or is a subdomain of one. Agents added by hand are not subject to the list.

Authorization header

If the server removes the Authorization header, agents cannot sign in. The AI agents page reports it and offers to write, in the .htaccess file of the root, the rule that passes the header to PHP (Apache). If the file is not writable, add the rule by hand.

05Permissions

Every agent request belongs to a scope. Scopes your role cannot grant appear disabled on the authorization page.