Off-the-shelf WordPress MCP plugins cover common tasks, but sooner or later you want a tool that does one specific thing: generate a report, check a custom post type, or run a workflow unique to your business. This guide shows the main ways to create custom MCP tools for WordPress and how to design them well.
Details depend on the approach and on current versions of WordPress and the MCP libraries. Treat code here as illustration and verify against the official documentation.
What Is a Custom MCP Tool?
An MCP tool is a named action an AI client can call. It has a description, an input schema, and code that runs when called. A custom tool is one you define yourself rather than one that ships with a plugin.
Three Ways to Build One
| Approach | How it works | Best for |
|---|---|---|
| Abilities API plus MCP Adapter | Register a WordPress ability and let the adapter expose it as an MCP tool | Tools that live inside a WordPress plugin |
| Standalone MCP server | A separate program that calls your site’s REST API | Prototypes and tools that combine several systems |
| Extending an existing MCP plugin | Add tools using that plugin’s own extension points, if it has them | Sites already using that plugin |
This guide focuses on the first two.
Approach 1: Abilities API and the MCP Adapter
WordPress core includes the Abilities API, and the official MCP Adapter can expose registered abilities to MCP clients. The general path:
- Confirm your environment. You need a WordPress version with the Abilities API, and the MCP Adapter installed.
- Register an ability in your plugin using
wp_register_ability()on thewp_abilities_api_initaction. - Define the input schema so clients know what to send.
- Write the execute callback that does the work and returns a result.
- Write a permission callback that checks the current user’s capabilities.
- Mark it public if you want the adapter’s default server to expose it, or list it explicitly on a custom server.
- Connect an MCP client and test.
Example
This mirrors the structure in the MCP Adapter’s documentation. Check the current docs for required fields.
add_action( 'wp_abilities_api_init', function () {
wp_register_ability( 'my-plugin/count-drafts', [
'label' => 'Count Drafts',
'description' => 'Returns the number of draft posts on the site',
'category' => 'site',
'input_schema' => [
'type' => 'object',
'properties' => [],
],
'execute_callback' => function ( $input ) {
$counts = wp_count_posts();
return [ 'drafts' => (int) $counts->draft ];
},
'permission_callback' => function () {
return current_user_can( 'edit_posts' );
},
'meta' => [
'public' => true,
'annotations' => [ 'readonly' => true ],
],
] );
} );
Read-only annotations tell clients that the tool does not change data. The adapter converts WordPress annotation names to MCP format.
How Clients Reach It
According to the adapter’s documentation, the default server is available over HTTP at a path under /wp-json/ and over STDIO through a WP-CLI command. Public abilities are found through the adapter’s discovery tools. Confirm the current endpoint and commands in the official documentation for your version.
Approach 2: A Standalone MCP Server
If you prefer to keep logic outside WordPress, write an MCP server with an official SDK and have it call the WordPress REST API. Each tool becomes a function that sends a request and returns the result. This suits quick prototypes, but you manage authentication, hosting, and updates yourself.
For a working example, see our guide on connecting Claude to WordPress, and follow the SDK’s own documentation for tool definitions.
Design Principles for Good Tools
- One tool, one job. Small tools are easier for a model to use correctly.
- Write clear descriptions. The model chooses tools based on them.
- Use precise schemas. Type and describe every input.
- Validate everything. Never trust model-supplied arguments blindly.
- Return useful, structured results. Include IDs and status.
- Prefer safe defaults. Drafts over publishing, read over write.
- Fail with readable errors. Help the model correct itself.
Security and Permissions
- Always write a real permission check. Never return true for sensitive actions.
- Sanitize and validate inputs, and escape outputs.
- Mark destructive tools clearly, and require confirmation where possible.
- Do not expose secrets or private data in results.
- Test with a limited user on staging.
- Require authentication on the MCP endpoint and use HTTPS.
Test Your Tool
- Call it with valid input and check the result.
- Call it with invalid input and check the error.
- Call it as a user who should not have access.
- Connect a real client and try natural-language prompts.
- Read any logs and check for unexpected side effects.
Troubleshooting
The Tool Does Not Appear
Check that the ability is registered on the right hook, marked public or explicitly listed, and that the adapter is active.
The Model Calls It Wrongly
Improve the description and schema, and simplify the tool.
Permission Errors
The connected user must satisfy your permission callback.
Frequently Asked Questions
Do I need PHP to create custom MCP tools?
For tools inside WordPress, yes. A standalone server can use another language.
What is the easiest route?
Registering an ability and letting the MCP Adapter expose it is a natural fit for plugin developers.
How many tools should I expose?
As few as your workflow needs.
Can one tool work with several AI clients?
Potentially, since MCP is a standard. Client support varies.
Conclusion
To create custom MCP tools for WordPress, register abilities and let the MCP Adapter expose them, or write a standalone server. Keep tools small, permissions strict, and defaults safe.
Related reading: our free MCP server for WordPress and the MCP Manager feature breakdown.
Explore ByteCore Stack Plugins
- MCP Manager β connect your WordPress site to AI assistants through MCP.
- SMTP Manager β reliable WordPress email delivery.
- Lightsail Manager β manage your AWS Lightsail CDN from WordPress.
