By Fahad Murtaza · Published
WordPress MCP adapter: how to register an ability and call it as a tool
The WordPress MCP adapter is the official library that publishes WordPress abilities to AI clients over the Model Context Protocol. This is the hands-on guide: you will register an ability, expose it, and call it through the adapter. For the concept-level overview of the Abilities API itself, see the WordPress Abilities API overview.
This guide covers the names and hooks that matter, a registration example, the adapter’s three meta-tools, and how WP MCP uses both. It does not walk through building an MCP server from scratch. For that, see how to build an MCP server. The explanation of MCP itself is in what is an MCP server.
What the Abilities API is
According to the official Abilities API documentation on developer.wordpress.org, the API is available in WordPress 6.9 and above. It is a PHP registry. A plugin registers an ability once, and anything that wants to use abilities can list them, read their schemas and run them.
Each ability is described by:
- a unique name in a
namespace/ability-nameform, such asmy-plugin/site-info - a label and a description, which is the text an AI model reads to decide when to call it
- a category
- an input schema and an output schema, written as JSON Schema
- an
execute_callback, the PHP that does the work - a
permission_callback, the check that decides whether the current user may run it - a
metaarray, which includesshow_in_restto expose the ability over the REST API
The WordPress developer blog post Introducing the WordPress Abilities API adds the rest of the surface. Abilities are served under the wp-json/wp-abilities/v1 REST namespace, with routes to list them, fetch one and run one. You can also work with the registry in PHP:
wp_register_ability()adds an abilitywp_register_ability_category()adds a categorywp_get_ability()fetches one by name, and you callexecute()on itwp_get_abilities()lists them allwp_has_ability()checks whether one exists
Two hooks drive registration. Categories are registered on wp_abilities_api_categories_init, and abilities on wp_abilities_api_init. An ability must name a category that already exists, so the category hook comes first.
This is the key idea for AI use. Before the Abilities API, every plugin invented its own way to say “this function exists and here is what it takes”. Now there is one place to ask, with a schema attached and a permission check that runs before execution.
What the MCP adapter adds
The Abilities API on its own does not speak MCP. The WordPress/mcp-adapter repository is the official bridge. Its README says WordPress abilities automatically become MCP tools, resources and prompts, and that it supports HTTP and STDIO transports.
Three details are worth knowing:
- Abilities are private by default. You opt an ability in by setting
publicin its meta (the adapter documentation namesmeta.publicandmeta.mcp.public). An ability you forgot to flag stays out of the MCP surface. - There is a default server. Exposed abilities are reachable at
/wp-json/mcp/mcp-adapter-default-server. It publishes three meta-tools,mcp-adapter/discover-abilities,mcp-adapter/get-ability-infoandmcp-adapter/execute-ability, which let a client find and run abilities through a fixed set of tool definitions. - Abilities can be other MCP primitives. An ability can be marked as a resource or a prompt instead of a tool. For what those are, see MCP resources and prompts.
A caveat from the adapter docs: on WordPress 6.9 and 7.0 the adapter honors the public flag for MCP, but access over the REST API still needs show_in_rest set to true. Set both while you target those versions.
You can also register your own server through the adapter instead of using the default one. WP MCP does exactly that, which is covered below.
Register an ability: a worked example
This example is a read-only ability that returns basic facts about the site. It follows the pattern in the official documentation: register a category, then register the ability, both guarded for older WordPress.
<?php
/**
* Plugin Name: Site Facts Ability
*/
add_action( 'wp_abilities_api_categories_init', function () {
if ( ! function_exists( 'wp_register_ability_category' ) ) {
return;
}
wp_register_ability_category( 'site-facts', array(
'label' => __( 'Site facts', 'site-facts' ),
'description' => __( 'Read-only facts about this site.', 'site-facts' ),
) );
} );
add_action( 'wp_abilities_api_init', function () {
if ( ! function_exists( 'wp_register_ability' ) ) {
return;
}
wp_register_ability( 'site-facts/get-basics', array(
'label' => __( 'Get site basics', 'site-facts' ),
'description' => __( 'Returns the site name, URL, WordPress version and PHP version.', 'site-facts' ),
'category' => 'site-facts',
'input_schema' => array(
'type' => 'object',
'properties' => new stdClass(),
),
'output_schema' => array(
'type' => 'object',
'properties' => array(
'name' => array( 'type' => 'string' ),
'url' => array( 'type' => 'string' ),
'wp' => array( 'type' => 'string' ),
'php' => array( 'type' => 'string' ),
),
),
'execute_callback' => function ( $input = null ) {
return array(
'name' => get_bloginfo( 'name' ),
'url' => home_url(),
'wp' => get_bloginfo( 'version' ),
'php' => PHP_VERSION,
);
},
'permission_callback' => function () {
return current_user_can( 'manage_options' );
},
'meta' => array(
'show_in_rest' => true,
'public' => true, // lets the MCP adapter expose it
),
) );
} );
A few choices in that code are deliberate:
- The
function_exists()guards mean the plugin does nothing on WordPress older than 6.9 instead of causing a fatal error. - The permission callback is real.
manage_optionsis an administrator capability. An ability that returns site internals should never use__return_true. The callback runs before the ability executes, so it is the control that matters, not the description. - The description is written for a model. “Returns the site name, URL, WordPress version and PHP version” tells an agent when to pick this tool.
- It is read-only. A write ability should also say so in its description and be narrow, because an AI client may call it without a human reading the arguments first.
Check the ability exists from PHP before involving MCP:
$ability = wp_get_ability( 'site-facts/get-basics' );
$result = $ability->execute( array() );
Or from the REST API, which requires an authenticated user. Abilities live under /wp-json/wp-abilities/v1, and the ability name goes in the path.
See it as an MCP tool
With the adapter active, a client connects to the server and asks for the tool list. Over HTTP that is a JSON-RPC request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/list"
}
On the adapter’s default server you see three meta-tools. In the Abilities API they are named mcp-adapter/discover-abilities, mcp-adapter/get-ability-info and mcp-adapter/execute-ability, and on the wire the slash becomes a hyphen, so a client sees mcp-adapter-discover-abilities, mcp-adapter-get-ability-info and mcp-adapter-execute-ability. Your ability is reached through them. execute-ability takes two required arguments, ability_name (the full ability name) and parameters (an object, which may be empty):
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "mcp-adapter-execute-ability",
"arguments": {
"ability_name": "site-facts/get-basics",
"parameters": {}
}
}
}
mcp-adapter-get-ability-info takes only ability_name and returns the ability’s input schema, and mcp-adapter-discover-abilities takes no arguments and lists every exposed ability. All three require a signed-in user with the read capability by default. The adapter documents a WP-CLI route for local testing: wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server, which runs the server over STDIO as the user you name. To inspect any of this without a chat client in the way, use MCP Inspector.
How WP MCP uses both
WP MCP is built directly on this stack. Its 407 tools are registered as abilities, 274 in the free plugin and 133 in Pro, and the plugin needs WordPress 6.9 or newer because that is the version that bundles the Abilities API. Which tools a site actually has depends on which optional plugins are active, and list-tool-catalog shows the real list.
From the plugin source in src/MCP/Registrar.php, each tool is registered inside the wp_abilities_api_init action through wp_register_ability(), with the category wpmcp and meta containing show_in_rest set to true. The category itself is registered in src/Plugin.php through wp_register_ability_category() on wp_abilities_api_categories_init, which matches the order described above. Tool names carry a wpmcp/ prefix as abilities, for example wpmcp/list-posts.
Two design decisions are worth copying if you build your own:
- One gate for every ability. The permission callback passed to
wp_register_ability()sends every call through a single check that combines the user’s WordPress capability, the site’s governance settings and the license tier. Because the Abilities API runs the permission callback before each execution, a rule added later covers every tool without each tool remembering to check it. - Registration is not exposure. The source notes that an ability defaults to
show_in_restfalse, and core gates both listing and running on it. Forgetting that flag makes a tool invisible and impossible to run, which is a common first-day surprise.
WP MCP does not rely on the adapter’s default server. It turns the default server off and creates its own through the adapter’s mcp_adapter_init hook, calling create_server() with the abilities whose names start with wpmcp/, plus its own resources and prompts. The result is the endpoint https://your-site.com/wp-json/mcp/wpmcp-server. The reason is control: a custom server lets the plugin shape what tools/list returns, including an optional compact mode that advertises five tools (list-tools, get-tool-schema, call-tool, get-connection-info, get-site-context) and reaches the rest through call-tool.
The sign-in is an application password sent as a Basic header, or optional OAuth 2.1, which ships off. For the credential steps, see the application password guide. For the safety side, every supported write is snapshotted first and can be undone with rollback-operation, which is covered in the revisions guide.
Abilities registered by other plugins can also be reached. WP MCP has an abilities bridge, execute-site-ability, for running another plugin’s ability. It is a tool WP MCP ships in the free plugin and it is the route for abilities WP MCP does not wrap itself.
Should you build on the Abilities API or use a plugin
If you maintain a plugin and want your own features to be AI-callable, register abilities. It is a small amount of code, it keeps the permission check inside WordPress, and it works with the adapter and with any other abilities consumer. The cost is that you own the schemas, the descriptions and the safety of every write.
If you run a site and want an AI client to manage content, media, settings and page builders today, you do not need to write abilities. A plugin such as WP MCP already registers a large set and adds snapshots and undo around writes. See pricing for the free and Pro split, and best WordPress MCP plugins for how the options compare.
Either way, the model of work is the same: a named ability, a schema, a permission check and a callback. Once you see that, the MCP side of WordPress is much less mysterious.
Common questions
What is the WordPress Abilities API?
It is a core registry, added in WordPress 6.9, where plugins and themes declare what they can do. Each ability has a name, a description, input and output schemas, a permission callback and an execute callback, so other code, including AI agents, can discover and run it in a standard way.
Which WordPress version has the Abilities API?
WordPress 6.9. The developer documentation states the API is only available for WordPress 6.9 and above. On older versions the functions such as wp_register_ability() do not exist, so plugins should check function_exists() first.
What is the WordPress MCP adapter?
It is the official WordPress/mcp-adapter project. It reads abilities from the Abilities API and serves them to MCP clients as tools, resources and prompts over HTTP or STDIO. An ability must be marked public to be exposed.
How do I make my ability show up as an MCP tool?
Register it on wp_abilities_api_init with wp_register_ability(), put it in a registered category, and set its public meta flag so the adapter exposes it. Then connect an MCP client to the adapter's server and call tools/list to see it.
Is the Abilities API the same as the MCP adapter?
No. The Abilities API is the registry inside WordPress core. The MCP adapter is a separate library that publishes that registry over the Model Context Protocol. You can use abilities without MCP, for example through the REST API or in PHP.
Does WP MCP use the Abilities API?
Yes. Every WP MCP tool is registered as an ability and published through the official MCP adapter at /wp-json/mcp/wpmcp-server. WP MCP needs WordPress 6.9 or newer because it relies on the Abilities API.
All WP MCP guides, or see every plugin integration. Topic: Connect an AI client.