Skip to main content Skip to navigation
MacBook with lines of code on a busy desk, representing creating custom MCP tools for WordPress

How to Create Custom MCP Tools for WordPress

5 min read

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

ApproachHow it worksBest for
Abilities API plus MCP AdapterRegister a WordPress ability and let the adapter expose it as an MCP toolTools that live inside a WordPress plugin
Standalone MCP serverA separate program that calls your site’s REST APIPrototypes and tools that combine several systems
Extending an existing MCP pluginAdd tools using that plugin’s own extension points, if it has themSites 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:

  1. Confirm your environment. You need a WordPress version with the Abilities API, and the MCP Adapter installed.
  2. Register an ability in your plugin using wp_register_ability() on the wp_abilities_api_init action.
  3. Define the input schema so clients know what to send.
  4. Write the execute callback that does the work and returns a result.
  5. Write a permission callback that checks the current user’s capabilities.
  6. Mark it public if you want the adapter’s default server to expose it, or list it explicitly on a custom server.
  7. 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

  1. Call it with valid input and check the result.
  2. Call it with invalid input and check the error.
  3. Call it as a user who should not have access.
  4. Connect a real client and try natural-language prompts.
  5. 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.

Leave a Reply