# Akurai & AI

With Akurai 4.7.0 you can manage your reviews and bonuses from an AI chat. Ask Claude or
ChatGPT something like "which reviews have no bonus terms?" or "add these pros
and cons to *review name*", and it does the work on your website for you.

This page explains how to set that up. If you are a developer using a coding
tool such as Claude Code, skip to
[Coding agents and developer tools](https://docs.affkraft.com/akurai/ai#coding-agents-and-developer-tools).

***

## Manage your website from a chat with an AI agent

### How it works

An AI assistant doesn't log in to your dashboard and click around like you do.
Instead, your website gives it a list of specific tasks it is allowed to do,
such as "list reviews", "update a bonus" or "set the payments". WordPress calls
these tasks **abilities**.

To make this work you need three things:

1. **Akurai** provides the abilities for your reviews, standalone bonuses, categories,
   tags, Akurai blocks and shortcodes, settings and license. You choose which
   ones to offer on the **Akurai → AI & Abilities** page.
2. **"[MCP Adapter](https://wordpress.org/plugins/mcp-adapter/)"**, a free
   plugin, lets AI apps connect to your website and use those abilities.
3. **"[Enable Abilities for MCP](https://wordpress.org/plugins/enable-abilities-for-mcp/)"**,
   a free plugin, adds the sign-in. When you connect a chat app, you log in to
   your WordPress website and approve the connection, much like "Sign in with
   Google" on other websites.

The assistant then works as the WordPress user you signed in with. If that user
isn't allowed to do something, the assistant can't do it either.

> **Warning**
>
> AI abilities need WordPress 6.9 or newer. On older versions the
> **AI & Abilities** page shows a notice; upgrade to recent versions of WordPress
> to be able to use Akurai's AI abilities.
>
> Your website must also be online and use HTTPS, because the chat app connects
> to it over the internet. A local website, or a staging website behind a
> password, won't work.

### Set it up

1. **Install the plugins.** Go to **Akurai → AI & Abilities**.
   The **Status** box at the top has buttons to install and activate both
   plugins.
2. **Choose what the assistant can do.** On the same page, tick **Enable
   abilities**, then tick the groups you want and click **Save Changes**. The
   default groups let the assistant read and edit reviews and bonuses, manage categories
   and tags, and work with Akurai blocks and shortcodes, but not move posts
   to the trash or change your settings or license.
3. **Turn on sign-in.** Go to **Settings → WP Abilities**, open the
   **Connection** tab and turn on the OAuth connector.
4. **Connect your chat app.** In your chat app, add a *custom connector* and
   paste your website address. You'll be sent to your WordPress login page:
   sign in and approve.
5. **Try it.** Start a new chat, make sure the connector is switched on for it,
   and ask "list my five most recent reviews".

Where to add a custom connector depends on the app. Menu names change often, so
treat these as a guide:

| App | Where |
| --- | --- |
| Claude | **Settings → Connectors → Add custom connector** |
| ChatGPT | Turn on Developer Mode in **Settings → Apps & Connectors → Advanced settings**, then create a connector with your website address and OAuth sign-in. Paid plans only, at the time of writing. |
| Gemini | **Settings → Connected Apps → Add a custom app**. Available to personal accounts in the US only, at the time of writing. |

> **Tip**
>
> "Enable Abilities for MCP" also comes with its own abilities for posts, pages,
> media and more. Akurai doesn't need them, so turn on only the ones you want on
> its **Abilities** tab.

### The AI & Abilities page

**Status** tells you whether everything is ready. A green tick means that part
is fine; a warning icon tells you what's missing, usually with a button to fix
it.

* **MCP Adapter** and **Chat app sign-in (OAuth)** show whether the two plugins
  are active. When MCP Adapter is active, its endpoint address is shown too.
* **Akurai abilities** shows how many tasks the assistant can currently use,
  and from how many groups.
* **Hidden elsewhere** only appears if "Enable Abilities for MCP" has switched
  off some of Akurai's abilities on its own screen. Turn them back on there if
  you want to use them.

**Ability Groups** starts with the main switch, **Enable abilities**. It is off
by default, and while it's off, assistants can't do anything with your Akurai
data. Below it, related tasks are grouped together, for example everything
needed to create and update reviews.

**Individual abilities (advanced)** lets you switch off a single task inside a
group you turned on. For example, you can let the assistant update reviews but
not change their geo affiliate links.

### Ability groups

"Who can use it" means which WordPress users the assistant can sign in as to
use that group.

| Group | What it can do | Abilities | Who can use it | Default |
| --- | --- | --- | --- | --- |
| Reviews: read | List, view and audit reviews, list valid field choices and check country support | `akurai/list-reviews`, `akurai/get-review`, `akurai/audit-reviews`, `akurai/list-field-choices`, `akurai/check-geo-support` | Users who can edit reviews (`edit_posts` on review CPT) | On |
| Reviews: edit | Create review drafts and update review fields, status, categories, tags, bonus, pros & cons, ratings, payments, info table, offers, countries and geo affiliate links | `akurai/create-review`, `akurai/update-review`, `akurai/set-bonus`, `akurai/set-pros-cons`, `akurai/set-ratings`, `akurai/set-payments`, `akurai/set-info-table`, `akurai/set-offers`, `akurai/set-geo`, `akurai/set-geo-links` | Users who can edit that review; publishing requires `publish_posts` on review CPT | On |
| Bonuses: read | List and inspect standalone bonus posts | `akurai/list-bonuses`, `akurai/get-bonus` | Users who can edit bonuses (`edit_posts` on bonus CPT) | On |
| Bonuses: edit | Create bonus drafts and update bonus fields, status, categories and review links | `akurai/create-bonus`, `akurai/update-bonus` | Users who can edit that bonus; publishing requires `publish_posts` on bonus CPT | On |
| Categories & tags | List, create, rename and delete terms in review categories, review tags and bonus categories | `akurai/list-terms`, `akurai/create-term`, `akurai/update-term`, `akurai/delete-term` | Users with taxonomy edit/delete capabilities | On |
| Blocks & shortcodes | Find Akurai blocks and shortcodes in posts, pages, reviews and bonuses, change their settings and insert new ones | `akurai/list-element-types`, `akurai/find-elements`, `akurai/get-elements`, `akurai/update-block`, `akurai/update-shortcode`, `akurai/insert-block`, `akurai/insert-shortcode` | Users who can edit that post or page | On |
| Settings | Read and update allowlisted Customizer theme settings, configure geo targeting and change CPT rewrite base slugs | `akurai/get-settings`, `akurai/update-settings`, `akurai/set-geo-settings`, `akurai/set-review-slug` | Administrators (`manage_options`; `get-settings` and `update-settings` also need `edit_theme_options`) | Off |
| Trash & restore | Move reviews or bonuses to the trash and restore them as drafts | `akurai/trash-review`, `akurai/restore-review`, `akurai/trash-bonus`, `akurai/restore-bonus` | Users who can delete that post | Off |
| License | Check theme registration state, version and cached expiration | `akurai/get-license-status` | Administrators (`manage_options`) | Off |

### The 39 abilities

Read abilities only look at your data; write abilities change it. Every ability
runs as the WordPress user you signed in with.

| Ability | Group | Type | What it does | Who can use it |
| --- | --- | --- | --- | --- |
| `akurai/list-reviews` | Reviews: read | Read | Lists reviews with search, status, category and tag filters, sorting and paging, and shows each review's issue codes. | Users who can edit reviews |
| `akurai/get-review` | Reviews: read | Read | Returns one full review: fields, bonus, ratings, pros and cons, payments, info table, offers, geo settings, terms and issue codes. | Users who can edit that review |
| `akurai/audit-reviews` | Reviews: read | Read | Scans up to 1000 reviews and returns only those with problems, plus a count per issue code. | Users who can edit reviews |
| `akurai/list-field-choices` | Reviews: read | Read | Lists valid values for countries, bonus types, offer types and geo target countries. | Users who can edit reviews |
| `akurai/check-geo-support` | Reviews: read | Read | Checks whether a review (or, without a review, which reviews you can edit) supports a country, with the geo message and affiliate link. | Users who can edit reviews |
| `akurai/create-review` | Reviews: edit | Write | Creates a review as a draft. Refuses duplicate titles unless you allow them. | Users who can edit reviews |
| `akurai/update-review` | Reviews: edit | Write | Updates title, slug, status, content, featured image, categories, tags and main fields. Publishing needs name, logo, small logo and affiliate link. | Users who can edit that review; publishing needs publish rights |
| `akurai/set-bonus` | Reviews: edit | Write | Sets a review's bonus text, bonus codes and terms. | Users who can edit that review |
| `akurai/set-pros-cons` | Reviews: edit | Write | Replaces the pros and cons headings and lists (up to 20 items each). | Users who can edit that review |
| `akurai/set-ratings` | Reviews: edit | Write | Sets the overall rating and the rating rows (0 to 10 in steps of 0.5, up to 10 rows). | Users who can edit that review |
| `akurai/set-payments` | Reviews: edit | Write | Sets deposit and withdrawal headings and method lists (up to 30 each). | Users who can edit that review |
| `akurai/set-info-table` | Reviews: edit | Write | Sets the info table values (website, established, country, minimum and maximum deposit) and custom row labels. | Users who can edit that review |
| `akurai/set-offers` | Reviews: edit | Write | Sets the sportsbook, casino, live casino, poker, bingo and lottery offers and their display options. | Users who can edit that review |
| `akurai/set-geo` | Reviews: edit | Write | Replaces a review's supported countries and custom geo texts. | Users who can edit that review |
| `akurai/set-geo-links` | Reviews: edit | Write | Sets or removes per-country affiliate links on a review. | Users who can edit that review |
| `akurai/list-bonuses` | Bonuses: read | Read | Lists bonus posts with search, status, category, bonus type and linked review filters. | Users who can edit bonuses |
| `akurai/get-bonus` | Bonuses: read | Read | Returns the full record of one bonus. | Users who can edit that bonus |
| `akurai/create-bonus` | Bonuses: edit | Write | Creates a bonus as a draft. | Users who can edit bonuses |
| `akurai/update-bonus` | Bonuses: edit | Write | Updates a bonus's post fields, categories and fields. | Users who can edit that bonus; publishing needs publish rights |
| `akurai/list-terms` | Categories & tags | Read | Lists terms in review categories, review tags or bonus categories. | Users who can edit reviews |
| `akurai/create-term` | Categories & tags | Write | Creates a term in one of those taxonomies. | Users who can manage those terms |
| `akurai/update-term` | Categories & tags | Write | Changes a term's name, slug, description or parent. | Users who can manage those terms |
| `akurai/delete-term` | Categories & tags | Write | Permanently deletes a term. The reviews and bonuses stay and are only detached from it. | Users who can delete those terms |
| `akurai/list-element-types` | Blocks & shortcodes | Read | Lists Akurai block types and shortcode types with their settings. | Users who can edit reviews |
| `akurai/find-elements` | Blocks & shortcodes | Read | Finds posts, pages, reviews and bonuses you can edit that contain Akurai blocks or shortcodes. Looks at the first 500 matches and tells you if there were more. | Users who can edit reviews |
| `akurai/get-elements` | Blocks & shortcodes | Read | Returns every Akurai block and shortcode in one post with its settings. | Users who can edit that post |
| `akurai/update-block` | Blocks & shortcodes | Write | Changes settings of one Akurai block; the rest of the post is left exactly as it was. | Users who can edit that post |
| `akurai/update-shortcode` | Blocks & shortcodes | Write | Changes attributes of one Akurai shortcode. Refuses shortcodes that wrap content or use unnamed attributes, and values containing a double quote or `]`. | Users who can edit that post |
| `akurai/insert-block` | Blocks & shortcodes | Write | Inserts a new Akurai block at the start, the end or after an existing block. | Users who can edit that post |
| `akurai/insert-shortcode` | Blocks & shortcodes | Write | Inserts a new Akurai shortcode at the start, the end or after an existing shortcode. | Users who can edit that post |
| `akurai/trash-review` | Trash & restore | Write | Moves a review to the Trash. Refuses if Trash is turned off on the website. | Users who can delete that review |
| `akurai/restore-review` | Trash & restore | Write | Restores a trashed review as a draft. A review that isn't in the Trash is left as it is. | Users who can delete that review |
| `akurai/trash-bonus` | Trash & restore | Write | Moves a bonus to the Trash. Refuses if Trash is turned off on the website. | Users who can delete that bonus |
| `akurai/restore-bonus` | Trash & restore | Write | Restores a trashed bonus as a draft. | Users who can delete that bonus |
| `akurai/get-settings` | Settings | Read | Reads the allowed theme settings, the review and bonus URL slugs and the geo options. | Administrators |
| `akurai/update-settings` | Settings | Write | Changes allowed theme settings, or resets them to default. All values are checked before anything is saved. | Administrators |
| `akurai/set-geo-settings` | Settings | Write | Sets the geo target countries and the default supported and not-supported texts. | Administrators |
| `akurai/set-review-slug` | Settings | Write | Changes the URL slug of reviews or bonuses. | Administrators |
| `akurai/get-license-status` | License | Read | Shows whether the theme is registered, its version and the cached expiry, never the license key. | Administrators |

Two limits to know about. Linking a review to a bonus isn't kept in sync: the
review's linked bonuses and the bonus's linked review are separate fields, so
set each side yourself. And the assistant can't change custom fonts, the footer
copyright text or header and footer scripts.

### Keeping it safe

* **Use a separate WordPress user** for the assistant, with the Editor role (Authors
  and Contributors can't use any Akurai ability), instead of your own Administrator account.
* **Start with the default groups** and turn on more only when you need them.
* **Nothing goes live by accident.** New reviews and bonuses are always saved as drafts. A
  review can only be published once it has the required fields: name, logo,
  small logo and affiliate link. A post with a future date can't be published
  by the assistant (that would schedule it); change the date first.
* **Posts are never deleted for good.** Trash abilities only move posts to
  the Trash, where you can restore them. If Trash is turned off on your website
  (`EMPTY_TRASH_DAYS` set to 0), they refuse and change nothing. Deleting a category or tag,
  however, cannot be undone (the reviews and bonuses themselves are kept).
* **Your keys stay private.** The assistant can never read your Akurai license key,
  only whether one is registered. Header and footer script options (`aic_scripts_*`)
  cannot be read or modified through the abilities API.
* **Some things can't be changed by the assistant.** Custom fonts, the footer
  copyright text and the header and footer scripts are not available to it. Make those changes in the Customizer
  yourself.
* **Slug changes have wide effects.** Changing the review or bonus URL slug changes the
  address of every item, so old links stop working unless you add redirects.
* **Ask to see changes first**, especially for bulk edits: "show me the changes
  before saving".

### Things you can ask

* "Which reviews have no bonus terms?"
* "Audit my reviews for missing data and list what's missing."
* "Add these pros and cons to *review name*: ..."
* "Set the geo link for Canada on *review name* to *affiliate URL*."
* "Is *review name* available to visitors from Germany?"
* "Add a Reviews Table with the top 5 reviews to the homepage."
* "Create a draft review for *brand name* with a 100% welcome bonus up to $200.
  Show me the change before saving."
* "Create a standalone welcome bonus linked to *review name* with code *BONUS100*."

The audit checks each review for these problems (issue codes in brackets):
no name (`no_name`), no logo (`no_logo`), no small logo (`no_small_logo`), no
affiliate link (`no_affiliate_link`), no bonus (`no_bonus`), no overall rating
(`no_rating`), fewer than two rating rows (`few_ratings`), no pros (`no_pros`),
no cons (`no_cons`), no bonus terms (`no_terms`), no supported countries
(`no_countries`), no category (`no_categories`) and published reviews not
modified for six months, or the number of months you ask for (`stale`).

***

## Coding agents and developer tools

Tools such as Claude Code, Codex or Cursor don't need the chat-app sign-in, so
"Enable Abilities for MCP" isn't required. You still turn on the abilities in
**Akurai → AI & Abilities**.

### MCP over HTTP

Needs the "MCP Adapter" plugin and a WordPress
[Application Password](https://wordpress.org/documentation/article/application-passwords/)
(**Users → Profile**). The `@automattic/mcp-wordpress-remote` proxy connects
to the endpoint. For Claude Code:

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

### MCP over WP-CLI

On a local site, or over SSH, you can skip HTTP and run the MCP server through
WP-CLI (STDIO):

```bash
wp mcp-adapter list
wp mcp-adapter serve --server=mcp-adapter-default-server --user=admin
```

### WordPress REST API

Abilities with REST enabled are also listed by WordPress itself at
`/wp-json/wp-abilities/v1/abilities`. Akurai's abilities are in the `akurai`
category.

***

## AI writing helpers in the editor

The official WordPress AI plugin adds writing helpers inside the Block Editor,
such as titles, excerpts and alt text. It works alongside Akurai and is a
different thing from managing your website from a chat assistant.