WordPress Abilities API and the MCP Adapter: A Practical Guide for Agencies

An ability is a named, self-describing action a site can perform. Each one is registered with:

• a name in the form namespace/ability-name, using lowercase letters, numbers and hyphens;
• a label, a description and a category;
• an input schema and an output schema, so a caller knows what to send and what comes back;
• an execute callback, which does the work, and a permission callback, which decides who may run it;
• optional meta, including annotations that mark an ability as read-only, destructive or idempotent.

The Abilities API is available from WordPress 6.9. It is useful on its own, as a single registry of what a site can do, but its headline use is giving AI agents a typed, permissioned way in.

The MCP Adapter, an official plugin from the WordPress project, turns abilities into MCP tools, resources and prompts. Abilities are private by default. To expose one, its developer sets meta.public to true, or meta.mcp.public to expose it to MCP only. Each ability becomes a tool unless meta.mcp.type says otherwise: a resource needs a uri, and a prompt needs arguments.

The adapter’s default server, mcp-adapter-default-server, gives clients three tools: mcp-adapter/discover-abilities, mcp-adapter/get-ability-info and mcp-adapter/execute-ability. A client discovers what the site offers, reads an ability’s schema and runs it, and the ability’s own permission callback is checked every time.

Here is a read-only ability an agency might ship to every client site: list published posts that have not been updated for a given number of days. Put it in a small plugin or a must-use plugin.

<?php
/**
 * Plugin Name: Agency Abilities
 * Description: Read-only abilities agents can call on client sites.
 */

add_action( 'wp_abilities_api_categories_init', function () {
	wp_register_ability_category( 'agency-audit', array(
		'label'       => __( 'Agency audit', 'agency' ),
		'description' => __( 'Read-only checks an agency runs across client sites.', 'agency' ),
	) );
} );

add_action( 'wp_abilities_api_init', function () {
	wp_register_ability( 'agency/list-stale-posts', array(
		'label'               => __( 'List stale posts', 'agency' ),
		'description'         => __( 'Lists published posts not updated in the given number of days.', 'agency' ),
		'category'            => 'agency-audit',
		'input_schema'        => array(
			'type'       => 'object',
			'properties' => array(
				'days' => array( 'type' => 'integer', 'minimum' => 30, 'default' => 365 ),
			),
		),
		'output_schema'       => array(
			'type'  => 'array',
			'items' => array(
				'type'       => 'object',
				'properties' => array(
					'id'       => array( 'type' => 'integer' ),
					'title'    => array( 'type' => 'string' ),
					'modified' => array( 'type' => 'string' ),
				),
			),
		),
		'execute_callback'    => function ( $input ) {
			$days  = absint( $input['days'] ?? 365 );
			$posts = get_posts( array(
				'post_status'    => 'publish',
				'posts_per_page' => 50,
				'date_query'     => array(
					array( 'column' => 'post_modified_gmt', 'before' => $days . ' days ago' ),
				),
			) );
			$items = array();
			foreach ( $posts as $post ) {
				$items[] = array(
					'id'       => $post->ID,
					'title'    => get_the_title( $post ),
					'modified' => $post->post_modified_gmt,
				);
			}
			return $items;
		},
		'permission_callback' => function () {
			return current_user_can( 'edit_posts' );
		},
		'meta'                => array(
			'public'      => true,
			'annotations' => array(
				'readonly'    => true,
				'destructive' => false,
				'idempotent'  => true,
			),
		),
	) );
} );

Three details matter. The permission callback checks a real capability rather than returning true. The annotations tell clients the ability only reads. And meta.public is set deliberately, because nothing is exposed until you say so. The Abilities API handbook lists every argument.

With the MCP Adapter active, the ability is available through the default server. For a local site, the adapter’s guide uses WP-CLI over STDIO. In Claude Desktop’s claude_desktop_config.json:

{
  "mcpServers": {
    "wordpress": {
      "command": "wp",
      "args": [
        "--path=/path/to/your/wordpress/site",
        "mcp-adapter",
        "serve",
        "--server=mcp-adapter-default-server",
        "--user=admin"
      ]
    }
  }
}

For a hosted site, use an application password and Automattic’s @automattic/mcp-wordpress-remote proxy; the exact configuration is in How to connect Claude to WordPress. Then ask Claude to discover the site’s abilities and run agency/list-stale-posts with days set to 365.

• One namespace per agency. Ship your abilities under a single prefix, such as agency/, in one plugin you version and deploy across the fleet.
• Read-only first. Start with abilities that report, such as stale content, plugin versions or broken links, before any that change things.
• Honest annotations. Mark destructive abilities as destructive, so clients and reviewers treat them accordingly.
• Real permission checks. Never use __return_true for anything that writes; check the capability the action needs.
• A dedicated agent user. Connect MCP clients as a user with only the capabilities your abilities need.
• Logging. Record who ran which ability and when, so a client question has an answer.

Write abilities when the action is yours: client-specific workflows, business rules, or reports no general plugin will ship. Use an MCP plugin when you want breadth today: hundreds of general tools for content, settings and stores. The two are not exclusive, and the official route is where WordPress itself is heading, as covered in what WordPress 7.0 means for agencies. Our comparison of WordPress MCP plugins covers the plugin side.

Abilities make a site agent-ready. Running a client fleet takes more. WPOS is an agent and workspace for agencies: it works inside wp-admin on each client site, builds natively in the site’s builder, follows your team’s skills and checks its own render before it reports done. It also speaks MCP, so your own Claude Code, Cursor or Codex can drive the same tools across your client sites without spending WPOS credits. Try it free for 30 days on a site you already manage.