Creating Abilities

This document explains how to create WordPress abilities that can be exposed as MCP tools, resources, and prompts. It covers the wp_register_ability function, configuration options, schema definitions, callbacks, and MCP metadata.

For schema transformation details (flattened vs object schemas), see Schema Transformation. For component-specific requirements (annotations, URI patterns, message formats), see Tools, Resources, and Prompts.

Purpose and Scope

Creating an ability involves:

1. Calling wp_register_ability with configuration parameters
2. Defining input/output schemas using JSON Schema
3. Implementing execute and permission callbacks
4. Configuring MCP metadata to control exposure and type

Abilities are registered during the wp_abilities_api_init action and automatically discovered by MCP servers that filter for meta.mcp.public = true.

---

Registration Overview

The wp_register_ability Function

Abilities are registered using the wp_register_ability function provided by the WordPress Abilities API. This function takes an ability ID (namespace/name) and a configuration array:

The ability ID follows the format namespace/ability-name, where the namespace is typically your plugin name. This creates a WP_Ability object that is stored in the WordPress Abilities API registry.

Sources: docs/guides/creating-abilities.md37-57

Registration Timing

Abilities must be registered during the wp_abilities_api_init action hook:

This ensures the Abilities API is fully initialized before registration occurs.

Sources: docs/getting-started/basic-examples.md12 docs/getting-started/basic-examples.md125 docs/getting-started/basic-examples.md178

Registration to Exposure Flow

Sources: Diagram 3 in high-level architecture, docs/guides/creating-abilities.md14-26

---

Ability Configuration Structure

Required Fields

Every ability must provide these fields:

Field	Type	Purpose
label	string	Human-readable name for the ability
description	string	Detailed explanation of what the ability does
execute_callback	callable	Function that implements the ability's logic
permission_callback	callable	Function that checks if execution is allowed

Sources: docs/guides/creating-abilities.md37-57

Optional Fields

Field	Type	Purpose
input_schema	array	JSON Schema defining accepted parameters (required for tools)
output_schema	array	JSON Schema defining return value structure
meta	array	Metadata including MCP configuration and annotations

Sources: docs/guides/creating-abilities.md37-57

Basic Structure Example

Sources: docs/guides/creating-abilities.md37-57

---

MCP Metadata Configuration

The meta.mcp Object

The meta.mcp object controls how an ability is exposed via MCP servers:

Sources: docs/guides/creating-abilities.md14-35

MCP Exposure Control

Abilities are NOT exposed by default. The meta.mcp.public flag must be explicitly set to true:

Sources: docs/guides/creating-abilities.md14-26

MCP Type Configuration

The meta.mcp.type field specifies how the ability is exposed:

Type	Discovery Endpoint	Requirements
tool (default)	tools/list	Standard ability with input_schema
resource	resources/list	Requires meta.uri
prompt	prompts/list	Returns messages array

If type is not specified, the ability defaults to 'tool'.

Sources: docs/guides/creating-abilities.md28-35

Type-Specific Meta Fields

Resources require a URI:

Prompts require arguments (or use input_schema which is auto-converted):

Sources: docs/guides/creating-abilities.md545-576 docs/guides/creating-abilities.md580-655

---

Input and Output Schemas

Schema Formats

The MCP Adapter supports two schema formats for input_schema and output_schema:

1. Object Schema (standard JSON Schema):

2. Flattened Schema (simplified for single values):

Sources: docs/guides/creating-abilities.md59-108

Schema Transformation

Flattened schemas are automatically transformed to MCP-compatible object schemas by the SchemaTransformer class:

The transformation wraps primitive types in an object with a single property:

• Input schemas use "input" as the wrapper property
• Output schemas use "result" as the wrapper property

For detailed transformation rules and examples, see Schema Transformation.

Sources: includes/Domain/Utils/SchemaTransformer.php20-92 docs/guides/creating-abilities.md84-108

Input Schema Usage

The input_schema defines parameters accepted by the ability. For tools, this is required and validated before execution:

Sources: docs/getting-started/basic-examples.md16-42

Output Schema Usage

The output_schema defines the structure of returned data:

Output schemas are optional but recommended for documentation and type safety.

Sources: docs/getting-started/basic-examples.md43-59

Schema Validation Behavior

Schema Type	Wrapper Property	Callback Input/Output Format
Object	None	Direct object: {'title': 'Hello'}
Flattened Input	"input"	Unwrapped value: 'post'
Flattened Output	"result"	Unwrapped value: 42

When using flattened schemas:

• The callback receives the unwrapped input value directly
• The callback should return the unwrapped output value
• The adapter automatically handles wrapping/unwrapping for MCP clients

Sources: docs/guides/creating-abilities.md219-228 docs/guides/creating-abilities.md539-543

---

Callbacks

Execute Callback

The execute_callback implements the ability's logic. It receives validated input parameters and returns the result:

Sources: docs/getting-started/basic-examples.md60-91

Execute Callback Signature

For object schemas:

For flattened input schemas:

The input is pre-validated by the WordPress Abilities API before the callback is invoked.

Sources: docs/guides/creating-abilities.md472-498

Permission Callback

The permission_callback determines if execution is allowed. It receives the input parameters and returns a boolean or WP_Error:

More complex permission checks can access the input:

Sources: docs/guides/creating-abilities.md746-763

Two-Layer Security Model

Permission callbacks provide fine-grained, ability-level security. However, transport-level permissions act as a server-wide gatekeeper. For complete security architecture, see Security and Permissions.

Sources: docs/guides/creating-abilities.md744-763 Diagram 4 in high-level architecture

---

Complete Examples

Tool Example

Tools execute actions and return results. This example creates a post:

Tools default to type: 'tool' if not specified. For tool-specific annotations and behavior, see Tools.

Sources: docs/guides/creating-abilities.md437-499 docs/getting-started/basic-examples.md5-106

Resource Example

Resources provide read-only access to data and require a meta.uri:

Resources don't typically need input_schema since they're accessed by URI. For resource URI patterns and requirements, see Resources.

Sources: docs/guides/creating-abilities.md545-577 docs/getting-started/basic-examples.md119-157

Prompt Example

Prompts generate structured messages for language models and return a messages array:

Prompts use input_schema (not meta.arguments) which is automatically converted to MCP arguments format. For prompt message structure and annotations, see Prompts.

Sources: docs/guides/creating-abilities.md605-655 docs/getting-started/basic-examples.md172-229

---

Registration and Conversion Pipeline

From Registration to MCP Component

Sources: Diagram 3 in high-level architecture, docs/guides/creating-abilities.md1-88

Key Conversion Classes

Class	Purpose	File Reference
SchemaTransformer	Converts flattened schemas to object schemas	includes/Domain/Utils/SchemaTransformer.php20-92
RegisterAbilityAsMcpTool	Converts abilities to MCP tools	Referenced in Diagram 3
RegisterAbilityAsMcpResource	Converts abilities to MCP resources	Referenced in Diagram 3
RegisterAbilityAsMcpPrompt	Converts abilities to MCP prompts	Referenced in Diagram 3
McpAnnotationMapper	Maps WordPress annotations to MCP format	Referenced in Diagram 3

Sources: Diagram 3 in high-level architecture, includes/Domain/Utils/SchemaTransformer.php1-92

Discovery Flow

Once registered and converted, MCP components are discoverable via the MCP server's list endpoints:

Sources: docs/getting-started/basic-examples.md246-271

---

Best Practices

Schema Design

• Use clear, descriptive field names
• Provide detailed descriptions for all properties
• Define appropriate data types and constraints (min/max length, enums, ranges)
• Mark required fields explicitly in the required array
• Use object schemas for multiple parameters, flattened schemas for single values

Sources: docs/guides/creating-abilities.md766-772

Error Handling

• Return meaningful error messages from callbacks
• Throw exceptions for unexpected errors (they're converted to MCP errors)
• Use WP_Error objects when appropriate
• Include context information for debugging

For error handling patterns and the McpErrorFactory, see Error Handling.

Sources: docs/guides/creating-abilities.md774-777

Performance

• Keep execute callbacks lightweight
• Cache expensive operations (database queries, API calls)
• Use appropriate WordPress query functions
• Consider pagination for large datasets

Sources: docs/guides/creating-abilities.md779-783

Security

• Always implement proper permission callbacks
• Validate and sanitize input within execute callbacks
• Remember transport permissions provide server-wide gatekeeper functionality
• Use WordPress capability checks (current_user_can)

Sources: docs/guides/creating-abilities.md744-763

---

Testing Abilities

Abilities can be tested via WP-CLI using the default MCP server:

Sources: docs/getting-started/basic-examples.md113-116 docs/getting-started/basic-examples.md162-169 docs/getting-started/basic-examples.md233-240

---

Next Steps

• Schema Transformation - Detailed guide to flattened vs object schemas and SchemaTransformer
• Tools - Tool-specific annotations, behavior hints, and ToolsHandler processing
• Resources - Resource URI patterns, read-only semantics, and ResourcesHandler
• Prompts - Prompt arguments, message structure, and PromptsHandler
• ExecuteAbilityAbility - The meta-ability that enables dynamic execution
• Security and Permissions - Two-layer security model details