---
title: "WordPress Abilities API: Register and Expose One Ability"
url: https://hostmy.blog/wordpress-abilities-api/
date: 2026-10-30
modified: 2026-10-30
lang: en
author: "Aditya Sharma"
description: "A build tutorial for the WordPress Abilities API: register a category and a read-only ability, test it with WP-CLI, add an input, and expose it over REST and MCP."
categories:
  - "RankReady"
image: https://hostmy.blog/wp-content/uploads/2026/10/hmb-card-2684-1024x538.jpg
word_count: 1708
---

# WordPress Abilities API: Register and Expose One Ability

This WordPress Abilities API tutorial is for developers: register one ability, test it, and expose it so that other code, and an MCP client, can call it. It assumes you know what the API is for, which [WordPress MCP: what the Abilities API lets an AI do](/wordpress-mcp/) explains. It also leaves the question of whether you should expose an ability to [WordPress MCP security](/wordpress-mcp-security/). Here the job is to get a small, correct, read-only ability working.

The examples follow the registration pattern in WordPress's own developer documentation, with one addition that takes an input. The Abilities API shipped in WordPress 6.9, so you need that version or later. Test on a development site, not on production.

## What you will build

Two abilities in one small plugin. The first returns basic site information and needs no input. The second counts published posts of a given type, which gives you an input schema to work with. Both are read-only, and both are registered in the order WordPress requires: a category first, then the abilities.

![Diagram of the Abilities API order: the category registers on wp_abilities_api_categories_init, the abilities register on wp_abilities_api_init, then code calls wp_get_ability and execute.](https://hostmy.blog/wp-content/uploads/2026/10/hmb-diagram-2684.png)Registration order for the two abilities in this tutorial.

## Step one: a plugin file

Create a folder in wp-content/plugins and a PHP file in it. A plugin header is all you need to make WordPress load it.

`<?php
/**
* Plugin Name: Demo Abilities
* Description: Registers two read-only abilities as a tutorial.
* Version: 0.1.0
*/

if ( ! defined( 'ABSPATH' ) ) {
exit;
}`

Keep the plugin separate from your theme. An ability is part of the site's capabilities, so it should survive a theme change.

## Step two: register a category

Every ability must belong to a category, and the category has to exist before the ability that uses it. [WordPress's announcement of the API](https://make.wordpress.org/core/2025/11/10/abilities-api-in-wordpress-6-9/) says categories are registered on the wp_abilities_api_categories_init hook. If you register an ability in a category that does not exist, the registration fails.

`add_action( 'wp_abilities_api_categories_init', 'demo_register_categories' );
function demo_register_categories() {
wp_register_ability_category(
'data-retrieval',
array(
'label' => __( 'Data Retrieval', 'demo-abilities' ),
'description' => __( 'Abilities that read data from the site.', 'demo-abilities' ),
)
);
}`

The name data-retrieval is the one chosen for this tutorial, and you can choose another. Use a short, lowercase name.

## Step three: register the first ability

Abilities are registered on the wp_abilities_api_init hook. Registering them anywhere else triggers a notice from WordPress, and the registration fails. The ability needs a name in the form namespace/ability-name: one namespace and one name, separated by a single slash, each made of lowercase letters, numbers and dashes. Core rejects anything else.

`add_action( 'wp_abilities_api_init', 'demo_register_abilities' );
function demo_register_abilities() {
wp_register_ability(
'demo/get-site-info',
array(
'label' => __( 'Get Site Information', 'demo-abilities' ),
'description' => __( 'Returns the site name, tagline and URL.', 'demo-abilities' ),
'category' => 'data-retrieval',
'output_schema' => array(
'type' => 'object',
'properties' => array(
'name' => array( 'type' => 'string' ),
'description' => array( 'type' => 'string' ),
'url' => array( 'type' => 'string', 'format' => 'uri' ),
),
),
'execute_callback' => function () {
return array(
'name' => get_bloginfo( 'name' ),
'description' => get_bloginfo( 'description' ),
'url' => home_url(),
);
},
'permission_callback' => '__return_true',
'meta' => array(
'annotations' => array(
'readonly' => true,
'destructive' => false,
),
),
)
);
}`

That is the shape of WordPress's own example. The label and description are for people and for AI clients, so write them in plain words. The output schema says what comes back. The execute callback does the work. The permission callback decides who may run it, and returning true for everyone is only appropriate here because the ability reads information that is already public. The annotations mark it as read-only and not destructive, which tells a client what to expect.

## Step four: test it

Activate the plugin, then run the ability from WP-CLI. Retrieve it by name and execute it, and check for an error.

`wp eval '$a = wp_get_ability( "demo/get-site-info" ); var_dump( $a ? $a->execute() : "not registered" );'`

You should see an array with the name, description and URL. If you see not registered, the ability did not register, and the usual causes are in the section below. The same pattern works in PHP: call wp_get_ability, check that it returned something, call execute, and check whether the result is a WP_Error.

## Step five: an ability with an input

The second ability takes a post type and returns how many published posts it has. It adds an input schema, which describes what the caller must supply, and uses it to restrict the value.

`wp_register_ability(
'demo/count-posts',
array(
'label' => __( 'Count Published Posts', 'demo-abilities' ),
'description' => __( 'Returns how many published items a post type has.', 'demo-abilities' ),
'category' => 'data-retrieval',
'input_schema' => array(
'type' => 'object',
'properties' => array(
'post_type' => array( 'type' => 'string', 'default' => 'post' ),
),
),
'output_schema' => array(
'type' => 'object',
'properties' => array( 'count' => array( 'type' => 'integer' ) ),
),
'execute_callback' => function ( $input = array() ) {
$type = isset( $input['post_type'] ) ? sanitize_key( $input['post_type'] ) : 'post';
$counts = wp_count_posts( $type );
return array( 'count' => isset( $counts->publish ) ? (int) $counts->publish : 0 );
},
'permission_callback' => function () {
return current_user_can( 'edit_posts' );
},
'meta' => array( 'annotations' => array( 'readonly' => true, 'destructive' => false ) ),
)
);`

Place this call inside the same registration function, after the first one. Two things differ. The callback sanitises the input before using it, because input from outside is never trusted. And the permission callback requires a capability, so a caller who cannot edit posts is refused. The first ability defines no input schema and takes no arguments. The second defines an object schema, and in my test a call with no input at all was rejected, so always pass an array, even an empty one. The table in the next section shows the results.

## What I got when I ran it

I installed a clean WordPress 7.1.4 site (PHP 8.5.12, SQLite database), activated the plugin built from the code blocks above, and ran the calls from a PHP script that loads WordPress, because the test machine had no WP-CLI. The calls are the ones in the wp eval line. The results:

| Call | User | Result |
| ---- | ---- | ------ |
| demo/get-site-info, execute() | Administrator | Array with name, description and url |
| demo/get-site-info, execute() | Subscriber | Same array, because the permission callback returns true |
| demo/count-posts, execute( array( "post_type" => "post" ) ) | Administrator | array( "count" => 1 ) on the fresh site |
| demo/count-posts, execute() with no input | Administrator | WP_Error ability_invalid_input: input is not of type object |
| demo/count-posts, execute( array( "post_type" => "post" ) ) | Subscriber | WP_Error ability_invalid_permissions: does not have necessary permission |
| wp_get_ability( "demo/nope" ) | Any | null, plus a notice: Ability "demo/nope" not found |
| wp_register_ability() called outside the hook | Any | null, plus a notice: Abilities must be registered on the wp_abilities_api_init action |

The low-privilege row is the one that matters: the subscriber could read public site information but was refused the count. That is the permission callback doing its job, not a sign that something is broken.

## Step six: expose it

An ability is private to PHP until you expose it. There are two routes, and they are separate decisions.

| Route | What you set | What it does |
| ----- | ------------ | ------------ |
| REST API | meta show_in_rest set to true | Makes the ability available under the wp-abilities/v1 namespace, to authenticated users |
| MCP adapter | meta public or meta mcp public set to true | Makes the ability visible to an MCP client through the adapter |

The REST route is described in [the announcement](https://make.wordpress.org/core/2025/11/10/abilities-api-in-wordpress-6-9/), which says you enable it by setting meta.show_in_rest to true and that "Access to all Abilities REST API endpoints requires an authenticated user." The MCP route is described in [the MCP adapter README](https://github.com/WordPress/mcp-adapter), which says "WordPress abilities are private by default" and that you set meta.public (or meta.mcp.public) to true to expose one. To expose the first ability both ways, add the flags to its meta array.

`'meta' => array(
'show_in_rest' => true,
'mcp' => array( 'public' => true ),
'annotations' => array( 'readonly' => true, 'destructive' => false ),
),`

In the WP_Ability class in WordPress 7.1.4, show_in_rest is taken from an explicit show_in_rest value first, then from the public flag, and falls back to false. Setting public may therefore expose the ability over REST as well, so set one flag deliberately and test the result. Expose only what you need. Each flag widens who can reach the ability, and whether you should is a security decision, not a build step.

## When it does not register

| Symptom | Likely cause | Fix |
| ------- | ------------ | --- |
| A notice about the wrong hook, and nothing registered | The call is outside wp_abilities_api_init | Move it into the hook |
| Registration fails | The category does not exist yet | Register the category on its own hook first |
| The name is rejected | It breaks the naming rule | Use namespace/name with lowercase letters, numbers and dashes |
| wp_get_ability returns nothing | The plugin is inactive, or the code did not run | Activate it, and check for errors |
| Execute returns an error | Input fails the schema | Check the input against input_schema |
| A client cannot see the ability | It is not exposed | Set the public flag, and check the adapter is installed |

## A checklist before you ship

`1. The category is registered on its own hook, before the ability.
2. The name follows namespace/ability-name.
3. The label and description are plain and accurate.
4. Input is validated by a schema and sanitised in the callback.
5. The permission callback checks a real capability.
6. Read-only abilities are annotated as read-only.
7. Exposure flags are set only where needed.
8. The ability was tested as a low-privilege user.`

The last line is the one people skip. Test as the user who will actually call it, not as an administrator, or you will not find out what a lower role can do.

Last checked on 29 October 2026 by running the plugin above on WordPress 7.1.4 (api.wordpress.org lists 7.1.4 as current), with PHP 8.5.12 and a SQLite test database, and against the Abilities API announcement linked above. The API is young and changing, so check the reference for the version you run.

## Where RankReady fits

RankReady does not need your ability. Its own [WebMCP manifest](https://hostmy.blog/plugins/rankready/webmcp-wordpress/) is a separate, read-only file that works without the Abilities API, and the page that describes it says plainly that RankReady's registration with core's Abilities API is not working yet. If you are building for the API, you are building for the pieces above. The free [AI Readiness Checker](https://hostmy.blog/plugins/rankready/ai-readiness-checker/) shows what your public site exposes today.

If you exposed one ability this week, which user would you test it with?