AI Abilities and Skills

Load YouTube videoThis video is hosted by YouTube. Loading it may share data with YouTube.

Bricks 2.4 introduces experimental AI abilities for Bricks. Abilities are actions registered with the WordPress Abilities API that an AI agent can run through an MCP-compatible client. Developers can also inspect and run the same registered abilities from WP-CLI when the wp ability command is available.

With abilities enabled, a connected agent can read and update parts of a Bricks site: design system, templates, elements, dynamic data, media, WooCommerce templates, and revisions.

Bricks skills are optional companion instructions for AI clients that support skills, rules, or reusable project guidance. They do not add new site permissions or new Bricks actions. They teach the agent how to work with Bricks more carefully, for example when to inspect the existing design system, avoid duplicate classes or variables, preview before saving, and choose the right ability for the task.

Use Bricks > AI to set up the MCP connection, choose which abilities are available on the site, create credentials, and install optional Bricks skills.

Experimental feature

AI abilities can write to your site. Test on a local or staging site first. Keep this feature off on production sites while it is experimental.

Where to find it

Visit the Bricks > AI screen in your WordPress dashboard.

The AI screen is split into three tabs:

Tab	What it does
Configuration	Installs or detects the WordPress MCP Adapter, enables Bricks abilities, creates an application password, and generates client-specific MCP config.
Abilities	Lets you choose which Bricks MCP abilities are available on this site.
Skills	Helps you install and verify the optional Bricks skills package in your AI client.

How the connection works

The connection has three parts:

Piece	Lives in	Purpose
WordPress MCP Adapter	WordPress plugin	Adds the MCP endpoint that exposes registered WordPress abilities.
Bricks abilities	Bricks	Registers Bricks actions with the WordPress Abilities API.
Bricks skills	AI client	Adds optional Bricks workflow guidance for clients that support skills, rules, or reusable instructions.

Bricks generates MCP config that runs npx -y @automattic/mcp-wordpress-remote@latest locally. That command connects the AI client to the WordPress MCP endpoint and authenticates with a WordPress application password.

Every request uses the WordPress user behind that application password. Bricks then checks that user’s WordPress capabilities, builder access, and builder permissions before abilities can read or write.

Setup

Use an administrator account for setup. Installing the adapter, activating it, saving settings, and creating credentials can require WordPress permissions such as manage_options, install_plugins, activate_plugins, and permission to edit the selected user account.

1. Install or activate the MCP Adapter

Go to Bricks > AI > Configuration.

In Abilities API, Bricks shows the MCP server status:

Status	Meaning	What to do
Not installed	The WordPress MCP Adapter plugin is not installed.	Click Install plugin if available, or use View on GitHub and install the latest stable release ZIP.
Inactive	The adapter is installed but not active.	Click Activate plugin, or activate it from Plugins.
Connected	The adapter is active and its REST route is registered.	Enable the Abilities API and continue.
Route missing	The adapter is loaded, but the MCP REST route did not register.	Check REST API routing, permalinks, plugin conflicts, and PHP error logs.
Disabled	BRICKS_DISABLE_MCP is set to a truthy value in wp-config.php.	Remove the constant or set it to false if this environment should allow MCP.

If the one-click installer is not available on your site, download mcp-adapter.zip from the latest stable WordPress MCP Adapter release and upload it under Plugins > Add New Plugin > Upload Plugin.

Bricks only registers abilities when the WordPress Abilities API is available. WordPress 6.9 includes the Abilities API. Earlier WordPress versions need the MCP Adapter or a related Abilities API package to provide it before Bricks abilities can register.

2. Enable Bricks abilities

When the adapter status is Connected, enable Abilities API in the same section.

Bricks shows the MCP endpoint URL. It usually looks like this:

https://example.com/wp-json/mcp/mcp-adapter-default-server

If pretty permalinks are not available, the same endpoint may need the REST route format:

https://example.com/?rest_route=/mcp/mcp-adapter-default-server

The toggle stays disabled if the adapter is not connected or if BRICKS_DISABLE_MCP forces MCP off.

3. Create a credential

In Credentials, select the WordPress user the AI client should act as, enter a credential name, and click Generate password.

Use a name that identifies the client or workflow, for example Codex staging, Claude local, or Cursor design review.

Copy the generated application password before leaving the page. WordPress only shows it once.

For shared local or staging environments, create a dedicated WordPress user for the AI client instead of using your personal admin account. Give that user only the builder access and WordPress capabilities it needs.

4. Connect your AI client

In Connect AI client, choose the client you use. Bricks shows a config block, a command, or a prompt depending on the client.

Use Paste config when the client supports config files. It keeps the setup explicit and keeps credentials out of the chat prompt.

Copy a prompt asks the AI client to help install the MCP server using the same connection details. Use it only in a local or staging workflow, and only with a client you trust with the credential.

Bricks generates client-specific config for many tools. The examples below show the shape of that config, but use the values generated on your site. The generated config includes:

• WP_API_URL: the MCP endpoint URL.
• WP_API_USERNAME: the selected WordPress username.
• WP_API_PASSWORD: the generated application password.
• NODE_TLS_REJECT_UNAUTHORIZED=0, only when Bricks detects a local development HTTPS domain that likely uses a self-signed certificate.
• npx -y @automattic/mcp-wordpress-remote@latest as the local command that connects your AI client to WordPress.

Do not put the application password in the endpoint URL, command arguments, or global shell config. Keep it in the MCP server environment for that client.

Codex

Paste the generated block into ~/.codex/config.toml, or merge it with your existing MCP server config:

[mcp_servers.example-com]
command = "npx"
args = ["-y", "@automattic/mcp-wordpress-remote@latest"]

[mcp_servers.example-com.env]
WP_API_URL = "https://example.com/wp-json/mcp/mcp-adapter-default-server"
WP_API_USERNAME = "mcp-service-user"
WP_API_PASSWORD = "xxxx xxxx xxxx xxxx"

Start a new Codex chat after saving the config so Codex reloads the MCP server.

Claude Code

Run the generated command in your terminal:

claude mcp add example-com \
  --env WP_API_URL='https://example.com/wp-json/mcp/mcp-adapter-default-server' \
  --env WP_API_USERNAME='mcp-service-user' \
  --env WP_API_PASSWORD='xxxx xxxx xxxx xxxx' \
  -- npx -y @automattic/mcp-wordpress-remote@latest

Start a new Claude Code chat after adding the server.

Generic JSON

Many clients use a JSON config shape like this:

{
  "mcpServers": {
    "example-com": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote@latest"],
      "env": {
        "WP_API_URL": "https://example.com/wp-json/mcp/mcp-adapter-default-server",
        "WP_API_USERNAME": "mcp-service-user",
        "WP_API_PASSWORD": "xxxx xxxx xxxx xxxx"
      }
    }
  }
}

Use the exact file path and wrapper key shown in Bricks > AI, because each client names its MCP config differently.

Local HTTPS

For local domains such as .local, .test, .localhost, .ddev.site, localhost, or 127.0.0.1, Bricks may add NODE_TLS_REJECT_UNAUTHORIZED=0 to the generated MCP server environment. Keep that setting scoped to this MCP server only. Do not set it globally.

5. Test the connection

Start a new chat in your AI client and ask:

Call bricks-start-here, then bricks-get-mcp-version, then bricks-list-ability-status.
Tell me whether Bricks abilities are available, which Bricks version is connected, and whether any abilities are disabled.

If bricks-start-here is not visible as a direct tool, ask the client to call the MCP Adapter dispatcher:

{
  "ability_name": "bricks/start-here",
  "parameters": {}
}

If the client cannot list Bricks abilities, fix the MCP connection before installing skills or trying a build task.

Managing abilities

Open Bricks > AI > Abilities to control which Bricks abilities AI clients can use on this site.

User permissions still apply

The Abilities tab controls site-level availability. It does not grant permissions to the WordPress user behind the MCP connection. An ability can be enabled here and still not be callable for that user if they do not have the required WordPress capability, builder access, or Bricks builder permission.

You can:

• Search abilities by name or description.
• Filter by category, enabled state, disabled state, and default-off state.
• Enable all, disable all, or reset to defaults.
• Review badges such as Default off and Destructive.

Some diagnostic abilities are always available so clients and admins can understand the connection state:

• bricks/start-here
• bricks/get-mcp-version
• bricks/list-ability-status

Most abilities are enabled by default once the Abilities API is enabled. Sensitive categories, such as builder permission management, are default-off until an admin enables them. Abilities marked destructive can remove data or make changes that are not easy to reverse, so treat them as actions that need clear user approval.

Fast-path tools and dispatcher tools

Bricks registers many abilities, but only common abilities appear directly in an MCP client’s tool list.

Direct MCP tool names use hyphens:

bricks-get-design-context
bricks-get-page-elements
bricks-set-page-elements

Ability names use slashes:

bricks/get-design-context
bricks/get-page-elements
bricks/set-page-elements

If a Bricks ability is not visible as a direct tool, call it through the MCP Adapter dispatcher:

{
  "ability_name": "bricks/get-mcp-version",
  "parameters": {}
}

Use bricks-list-ability-status to see which abilities are enabled, which are disabled, and which are default-off.

Installing Bricks skills

Skills are optional. Get the MCP connection working first.

Open Bricks > AI > Skills and copy the install prompt. Paste it into the AI client you want to use. The prompt points the client to the Bricks skills repository, asks it to install the matching skills or rules format, and asks it to report which Bricks skills were installed.

Then copy the verification prompt from the same tab. Start a new chat and ask the client to list loaded Bricks skills.

If no Bricks skills are loaded, the MCP connection can still work. The client can call bricks-start-here at the beginning of a session to get the core Bricks workflow rules, fast-path tool names, and dispatcher example.

Skills help with workflows such as:

• Designing or auditing a design system.
• Creating pages and templates.
• Working with query loops and dynamic data.
• Writing element conditions and interactions.
• Converting HTML and CSS into Bricks element data.
• Verifying frontend output with screenshots or browser automation.

WP-CLI access

Bricks abilities are registered with the WordPress Abilities API, so they are not limited to MCP clients.

For developer checks, WP-CLI can access the same registered abilities from the command line. The WordPress Developer Resources page for wp ability describes it as the command for abilities registered through the WordPress Abilities API.

Useful checks:

wp ability list --namespace=bricks --user=admin
wp ability get bricks/get-mcp-version --user=admin
wp ability run bricks/get-mcp-version --user=admin
wp ability run bricks/list-ability-status --user=admin --format=json

Use --user so permission checks run in the same WordPress user context your MCP connection would use.

This is separate from the Bricks-specific wp bricks ... commands, and it is not required for the MCP setup above. It is a WordPress Abilities API surface for any registered ability, including abilities from Bricks and other plugins.

Security model

Treat an MCP-connected AI client like a real WordPress user.

• Each call runs as the authenticated WordPress user, for example the application-password user or the --user passed to WP-CLI.
• Bricks checks WordPress capabilities, builder access, and Bricks builder permissions before abilities can read or write.
• The Abilities tab controls which Bricks abilities are available on the site.
• BRICKS_DISABLE_MCP in wp-config.php is a hard off switch for the entire MCP surface.
• Application passwords can be revoked from the selected user’s WordPress profile.
• Post and template element writes create Bricks revisions where supported. Global data writes, such as classes, variables, theme styles, and components, are not covered by post revisions.

Recommended defaults:

• Use local or staging for first tests.
• Use a dedicated WordPress user for the AI client in shared testing environments.
• Disable abilities that are not needed for the workflow.
• Review destructive actions before approving them in the AI client.
• Revoke old application passwords.

Troubleshooting

Symptom	Likely cause	What to do
The Abilities API toggle is disabled	MCP Adapter is not connected, or BRICKS_DISABLE_MCP is forcing MCP off	Install and activate the adapter, confirm the status is Connected, or update wp-config.php.
MCP server enabled but endpoint did not register	The adapter loaded, but the REST route is missing	Check /wp-json/, permalink settings, plugin conflicts, and PHP error logs.
The client cannot connect	Wrong endpoint, wrong credential, or the client did not reload config	Confirm the endpoint in Bricks > AI, regenerate or re-copy the application password, then start a new chat.
Application passwords are unavailable	WordPress application passwords are disabled for the site or selected user	Check the selected user, security plugins, HTTPS settings, and WordPress application password availability.
The client only shows mcp-adapter-* tools	Bricks direct tools are not loaded or the ability is outside the fast path	Use mcp-adapter-discover-abilities, call long-tail abilities through mcp-adapter-execute-ability, and check bricks-list-ability-status.
A Bricks ability returns disabled	The ability is off in Bricks > AI > Abilities	Enable the ability or reset abilities to defaults.
Local HTTPS fails	The local certificate is not trusted by the local npx process	Use the scoped NODE_TLS_REJECT_UNAUTHORIZED=0 generated by Bricks for local development, or trust the local certificate.
The AI client keeps asking for approval on every tool call	The client has per-tool approval settings	Approve the Bricks MCP server or adjust that client’s MCP approval settings if you trust the workflow.

Example prompts

Start with explicit instructions. Ask the client to inspect the site before writing.

You are connected to a Bricks site through MCP.
Call bricks-start-here, then inspect the design system and the current page before making changes.
Do not create duplicate global classes or variables.
Preview or read back your changes before reporting that the task is done.

Build a first pass of a page:

Create an About page for this Bricks site. Use the existing design system, keep the style consistent with the homepage, and show me the plan before saving.

Replace static content with dynamic data:

Find the static listing cards on the homepage and replace them with a query loop that pulls the Listing post type. Use the existing card styling.

Audit before changing:

Audit the site's global classes, variables, and templates for naming drift or duplicated patterns. Show me the report first. Do not change anything yet.