MCP Adapter

https://github.com/wordpress/mcp-adapter
Admin
The official WordPress package for MCP integration that exposes WordPress abilities as Model Context...
Tokens:73,150
Snippets:591
Trust Score:9.1
License:GPL-2.0
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Install release build via WP-CLI

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/troubleshooting/common-issues.md

Alternative to a source checkout: install the latest release zip directly from GitHub, activating it and forcing overwrite.

```bash
wp plugin install https://github.com/WordPress/mcp-adapter/releases/latest/download/mcp-adapter.zip --activate --force
```

--------------------------------

### Start wp-env Test Environment

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/testing.md

Starts the wp-env test environment, which provides a containerized WordPress instance at http://localhost:8889 with all required dependencies.

```bash
npm run wp-env:test start
```

--------------------------------

### Initialize request event example

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/observability.md

Example of an initialize request that creates a new session. Note session_id is null and new_session_id is provided.

```php
// Initialize request (creates new session)
[
  'event' => 'mcp.request',
  'tags' => [
    'status' => 'success',
    'method' => 'initialize',
    'transport' => 'http',
    'server_id' => 'default',
    'request_id' => 1,
    'session_id' => null, // No session yet
    'params' => ['protocolVersion' => '2025-06-18', 'client_name' => 'Bruno'],
    'new_session_id' => 'a3f2c1d4-5e6f-7890-abcd-ef1234567890', // Newly created
  ],
  'duration_ms' => 12.34
]
```

--------------------------------

### wp mcp-adapter serve examples

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/cli-usage.md

Examples of the serve command: serving the default server as admin, serving a specific server as user ID 1, and serving without authentication (limited capabilities).

```bash
# Serve the default MCP server as admin user
wp mcp-adapter serve --user=admin

# Serve a specific server as user with ID 1
wp mcp-adapter serve --server=my-mcp-server --user=1

# Serve without authentication (limited capabilities)
wp mcp-adapter serve --server=public-server
```

--------------------------------

### Install development dependencies

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/CONTRIBUTING.md

Installs Node.js and Composer dependencies. Use NVM to select the correct Node.js version, then run npm install and optionally composer install.

```bash
## If you're using NVM, make sure to use the correct Node.js version:
nvm use

## Then install the NPM dependencies:
npm install

# If you are using Composer locally, also run:
composer install
```

--------------------------------

### Start local development environment

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/CONTRIBUTING.md

Starts the WordPress development environment using wp-env. The site will be available at http://localhost:8888.

```bash
npm run wp-env start
```

--------------------------------

### STDIO transport example with wp mcp-adapter serve

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/default-server.md

Example of using the STDIO transport via WP-CLI. No HTTP session is needed; each invocation runs as a single process.

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
  wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server
```

--------------------------------

### Install MCP Adapter via Composer

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/getting-started/installation.md

Installs MCP Adapter as a Composer library. This method is not recommended because it can lead to conflicts with the MCP Adapter plugin or other plugins bundling their own copy. If you currently bundle it, see the v0.7.0 migration guide.

```bash
composer require wordpress/mcp-adapter
```

--------------------------------

### Flattened Output Schema Examples

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/creating-abilities.md

Examples of primitive types for flattened output schemas.

```php
// Number output
'output_schema' => [
    'type' => 'integer',
    'description' => 'Total number of posts found'
]

// Boolean output
'output_schema' => [
    'type' => 'boolean',
    'description' => 'Whether the operation succeeded'
]

// Array output
'output_schema' => [
    'type' => 'array',
    'description' => 'List of post titles',
    'items' => ['type' => 'string']
]
```

--------------------------------

### Install Composer dependencies and verify autoloader

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/troubleshooting/common-issues.md

When the plugin is installed from a source checkout, run composer install in the plugin directory. Then verify the Jetpack autoloader file exists.

```bash
# Install dependencies in the plugin directory
cd wp-content/plugins/mcp-adapter
composer install

# Check the autoloader exists (Jetpack Autoloader, not autoload.php)
ls vendor/autoload_packages.php
```

--------------------------------

### Install MCP Adapter plugin with WP-CLI

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/getting-started/installation.md

Installs and activates the MCP Adapter plugin from the latest GitHub release using WP-CLI. After activation, the plugin creates a default MCP server at /wp-json/mcp/mcp-adapter-default-server.

```bash
wp plugin install https://github.com/WordPress/mcp-adapter/releases/latest/download/mcp-adapter.zip --activate
```

--------------------------------

### wp mcp-adapter list examples

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/cli-usage.md

Examples of the list command: default table format, JSON format, and counting components under MCP 2026-07-28. The --protocol option does not filter servers or change how they serve requests.

```bash
# List servers in table format
wp mcp-adapter list

# List servers in JSON format
wp mcp-adapter list --format=json

# Count components available under MCP 2026-07-28
wp mcp-adapter list --protocol=2026-07-28
```

--------------------------------

### Flattened Input Schema Examples

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/creating-abilities.md

Examples of various primitive types supported in flattened input schemas.

```php
// Number with constraints
'input_schema' => [
    'type' => 'number',
    'description' => 'Maximum number of posts',
    'minimum' => 1,
    'maximum' => 100,
    'default' => 10
]

// Boolean flag
'input_schema' => [
    'type' => 'boolean',
    'description' => 'Include draft posts'
]

// Array of strings
'input_schema' => [
    'type' => 'array',
    'description' => 'List of post IDs',
    'items' => ['type' => 'integer'],
    'minItems' => 1
]
```

--------------------------------

### Discover abilities output format

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/default-server.md

Example output format for the discover-abilities tool. Returns an array of abilities with name, label, and description for each public ability.

```json
{
  "abilities": [
    {
      "name": "my-plugin/create-post",
      "label": "Create Post", 
      "description": "Creates a new WordPress post"
    }
  ]
}
```

--------------------------------

### Create custom server with error and observability handlers

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/observability.md

For a custom server, pass both handler classes to create_server(). This example creates an HTTP server with empty tool, resource, and prompt lists; supply your components in those arrays.

```php
use WP\MCP\Core\McpAdapter;
use WP\MCP\Infrastructure\ErrorHandling\ErrorLogMcpErrorHandler;
use WP\MCP\Infrastructure\Observability\ErrorLogMcpObservabilityHandler;
use WP\MCP\Transport\HttpTransport;

add_action( 'mcp_adapter_init', static function ( McpAdapter $adapter ): void {
    $adapter->create_server(
        'my-custom-server',
        'my-namespace',
        'my-route',
        'My Custom Server',
        'A custom MCP server with diagnostics and request events',
        '1.0.0',
        array( HttpTransport::class ),
        ErrorLogMcpErrorHandler::class,
        ErrorLogMcpObservabilityHandler::class,
        array(), // Tools.
        array(), // Resources.
        array()  // Prompts.
    );
} );
```

--------------------------------

### Custom authentication with permission callback

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/migration/v0.3.0.md

Demonstrates custom authentication by passing a permission callback to create_server. The callback checks the X-API-Key header and validates it. This example includes additional parameters for resources and prompts.

```php
add_action('mcp_adapter_init', function($adapter) {
    $adapter->create_server(
        'secure-server',
        'secure',
        'mcp',
        'Secure Server',
        'Custom auth example',
        '1.0.0',
        [ HttpTransport::class ],
        ErrorLogMcpErrorHandler::class,
        NullMcpObservabilityHandler::class,
        ['my-plugin/ability'],
        [],  // resources
        [],  // prompts
        function() {
            // Custom permission logic
            $api_key = $_SERVER['HTTP_X_API_KEY'] ?? '';
            return validate_api_key($api_key);
        }
    );
});
```

--------------------------------

### Successful tool execution event example

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/observability.md

Example of a successful tool execution event with status 'success' and method 'tools/call'. Includes tags for component_type, tool_name, and ability_name.

```php
// Successful tool execution
[
  'event' => 'mcp.request',
  'tags' => [
    'status' => 'success',
    'method' => 'tools/call',
    'transport' => 'http',
    'server_id' => 'default',
    'request_id' => 82,
    'session_id' => 'a3f2c1d4-5e6f-7890-abcd-ef1234567890',
    'params' => ['name' => 'create-post', 'arguments_count' => 2],
    'component_type' => 'tool',
    'tool_name' => 'create-post',
    'ability_name' => 'create_post',
  ],
  'duration_ms' => 45.23
]
```

--------------------------------

### Resource and Prompt Annotations Schema

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/creating-abilities.md

Example of the shared annotation schema used by Resources and Prompts.

```php
'meta' => [
    'annotations' => [
        'audience' => ['user', 'assistant'],      // Intended audience
        'lastModified' => '2024-01-15T10:30:00Z', // ISO 8601 timestamp
        'priority' => 0.8                         // 0.0 (lowest) to 1.0 (highest)
    ]
]
```

--------------------------------

### Build plugin for distribution

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/CONTRIBUTING.md

Builds the plugin zip for distribution. First install Composer dependencies without dev packages, then run the plugin-zip script.

```bash
# IMPORTANT!: Make sure you've cleaned up any dev-dependencies from Composer first:
composer install --no-dev

npm run plugin-zip
```

--------------------------------

### Default server creation with is_user_logged_in()

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/transport-permissions.md

Creates an MCP server without a permission callback, so the default is_user_logged_in() is used. This is the basic setup for logged-in users.

```php
$adapter->create_server(
    'my-server',
    'my-plugin',
    'mcp',
    'My MCP Server',
    'Server description',
    '1.0.0',
    [\WP\MCP\Transport\HttpTransport::class],
    \WP\MCP\Infrastructure\ErrorHandling\ErrorLogMcpErrorHandler::class,
    \WP\MCP\Infrastructure\Observability\NullMcpObservabilityHandler::class,
    ['my-plugin/tool'], // tools
    [], // resources
    [], // prompts
    // No permission callback = uses is_user_logged_in()
);
```

--------------------------------

### Create MCP server with HttpTransport

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/migration/v0.3.0.md

Shows the default setup for an MCP server using HttpTransport. The create_server call includes the transport class and error handler. Use this as a baseline for standard MCP servers.

```php
use WP\MCP\Core\McpAdapter;
use WP\MCP\Transport\HttpTransport;

add_action('mcp_adapter_init', function($adapter) {
    $adapter->create_server(
        'my-server-id',
        'my-namespace',
        'mcp',
        'My MCP Server',
        'Server description',
        '1.0.0',
        [ HttpTransport::class ],  // Use HttpTransport
        ErrorLogMcpErrorHandler::class,
        ['my-plugin/my-ability']
    );
});
```

--------------------------------

### wp mcp-adapter serve syntax

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/cli-usage.md

Syntax for the serve command. Starts an MCP server over STDIO. Use --server to select a specific server (defaults to the first available) and --user to run as a specific WordPress user for permission checks; without --user, runs unauthenticated with limited capabilities.

```bash
wp mcp-adapter serve [--server=<server-id>] [--user=<id|login|email>]
```

--------------------------------

### Component registration event payloads

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/observability.md

Example event payloads for successful and failed component registration. The successful example uses status 'success' and component_type 'tool'; the failed example uses status 'failed' and includes error_type 'InvalidArgumentException'.

```php
// Successful tool registration
[
  'event' => 'mcp.component.registration',
  'tags' => [
    'status' => 'success',
    'component_type' => 'tool',
    'component_name' => 'create_post',
    'server_id' => 'default',
  ]
]

// Failed resource registration
[
  'event' => 'mcp.component.registration',
  'tags' => [
    'status' => 'failed',
    'component_type' => 'resource',
    'component_name' => 'invalid_ability',
    'error_type' => 'InvalidArgumentException',
    'server_id' => 'default',
  ]
]
```

--------------------------------

### List and serve specific server

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/cli-usage.md

List available servers and then serve a specific server using the --server option when multiple servers are available.

```bash
# List available servers
wp mcp-adapter list

# Serve specific server
wp mcp-adapter serve --server=content-management --user=admin
```

--------------------------------

### Failed request - tool not found event example

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/observability.md

Example of a failed request when the tool is not found. Includes error_code -32002 and failure_reason 'not_found'.

```php
// Failed request - tool not found
[
  'event' => 'mcp.request',
  'tags' => [
    'status' => 'error',
    'method' => 'tools/call',
    'transport' => 'http',
    'server_id' => 'default',
    'request_id' => 83,
    'session_id' => 'a3f2c1d4-5e6f-7890-abcd-ef1234567890',
    'params' => ['name' => 'invalid-tool'],
    'component_type' => 'tool',
    'tool_name' => 'invalid-tool',
    'failure_reason' => 'not_found',
    'error_code' => -32002,
  ],
  'duration_ms' => 2.15
]
```

--------------------------------

### Debug Server Creation with mcp_adapter_init

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/troubleshooting/common-issues.md

Use this PHP snippet to debug why a server is not created. It hooks into 'mcp_adapter_init', attempts to create a server with the 'test-server' ID, and logs success or failure to the error log.

```php
// Debug server creation
add_action( 'mcp_adapter_init', function( $adapter ) {
    error_log( 'MCP Adapter init fired' );
    
    try {
        $adapter->create_server(
            'test-server',
            'test',
            'mcp',
            'Test Server',
            'Testing server creation',
            '1.0.0',
            [ \WP\MCP\Transport\HttpTransport::class ],
            \WP\MCP\Infrastructure\ErrorHandling\ErrorLogMcpErrorHandler::class,
            []
        );
        error_log( 'Server created successfully' );
    } catch ( Exception $e ) {
        error_log( 'Server creation failed: ' . $e->getMessage() );
    }
});
```

--------------------------------

### After v0.5.0: Get observability context

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/migration/v0.5.0.md

Shows the v0.5.0 way of getting observability context via get_observability_context(). Failure reasons now use FailureReason constants with the same string values.

```php
// After (v0.5.0)
$tags = $mcp_tool->get_observability_context();
// Returns: ['component_type' => 'tool', 'tool_name' => '...', 'source' => 'ability']
```

--------------------------------

### Test MCP Server with WP-CLI

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/getting-started/README.md

Uses WP-CLI to list available tools and execute the site info tool via STDIO transport. Requires admin user and the default server.

```bash
# List available tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server

# Execute the site info tool
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"my-plugin-get-site-info","arguments":{"include_stats":true}}}' | wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server
```

--------------------------------

### Register ability with and without category

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/troubleshooting/common-issues.md

The first example shows a missing category causing wp_register_ability() to return null. The second example uses the core 'site' category. Both are shown for comparison.

```php
// Wrong: no category → returns null, ability never registers.
wp_register_ability( 'my-plugin/my-ability', [
    'label'       => 'My Ability',
    'description' => 'Test ability',
    // ...
] );

// Right: use a core category. Core provides 'site' and 'user'.
wp_register_ability( 'my-plugin/my-ability', [
    'label'       => 'My Ability',
    'description' => 'Test ability',
    'category'    => 'site',
    // ...
] );
```

--------------------------------

### Test Resource with MCP Adapter Commands (resources/read and resources/list)

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/getting-started/basic-examples.md

These bash commands test the resource by reading the site configuration and listing all available resources via the MCP adapter. They use the 'wp mcp-adapter serve' command with the '--user=admin' and '--server=mcp-adapter-default-server' flags, sending JSON-RPC requests.

```bash
# Read the site configuration resource
echo '{"jsonrpc":"2.0","id":1,"method":"resources/read","params":{"uri":"wordpress://site/config"}}' | wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server

# List all available resources
echo '{"jsonrpc":"2.0","id":1,"method":"resources/list","params":{}}' | wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server
```

--------------------------------

### Registering Tools, Resources, and Prompts with wp_register_ability

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/creating-abilities.md

Examples of registering different types of abilities using the WordPress Abilities API format. Each example includes specific meta annotations for MCP integration.

```php
// Tool with WordPress Abilities API format (RECOMMENDED)
wp_register_ability('my-plugin/analyze-data', [
    'label' => 'Data Analyzer',
    'description' => 'Analyze data with various algorithms',
    'category' => 'site',
    'input_schema' => [...],
    'execute_callback' => 'analyze_data_callback',
    'permission_callback' => function() { return current_user_can('read'); },
    'meta' => [
        'public' => true,
        'annotations' => [
            'readonly' => true,              // WordPress format → readOnlyHint
            'destructive' => false,          // WordPress format → destructiveHint
            'idempotent' => true,            // WordPress format → idempotentHint
            'openWorldHint' => false,        // No WordPress equivalent
            'title' => 'Data Analysis Tool'  // No WordPress equivalent
        ],
        'mcp' => [
            'type' => 'tool'
        ]
    ]
]);

// Resource with Resource-specific annotations
wp_register_ability('my-plugin/user-data', [
    'label' => 'User Data Resource',
    'description' => 'Access to user profile data',
    'category' => 'user',
    'execute_callback' => 'get_user_data',
    'permission_callback' => function() { return current_user_can('read'); },
    'meta' => [
        'public' => true,
        'uri' => 'wordpress://users/profile',
        'annotations' => [
            'audience' => ['assistant'],     // For AI use only
            'priority' => 0.9,              // High importance
            'lastModified' => date('c')      // ISO 8601 timestamp
        ],
        'mcp' => [
            'type' => 'resource'
        ]
    ]
]);

// Prompt with Prompt-specific annotations
wp_register_ability('my-plugin/review-prompt', [
    'label' => 'Code Review Prompt',
    'description' => 'Generate structured code review prompts',
    'category' => 'site',
    'input_schema' => [
        'type' => 'object',
        'properties' => [
            'code' => ['type' => 'string', 'description' => 'Code to review']
        ],
        'required' => ['code']
    ],
    'execute_callback' => 'generate_review_prompt',
    'permission_callback' => function() { return current_user_can('edit_posts'); },
    'meta' => [
        'public' => true,
        'annotations' => [
            'audience' => ['user', 'assistant'], // For both user and AI
            'priority' => 0.8,                  // High priority
            'lastModified' => date('c')          // Current timestamp
        ],
        'mcp' => [
            'type' => 'prompt'
        ]
    ]
]);
```

--------------------------------

### List all available resources using WP-CLI

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/getting-started/basic-examples.md

Use this command to list all available resources from the default MCP server. It sends a JSON-RPC request to the 'resources/list' method via WP-CLI, specifying the admin user and the default server.

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"resources/list","params":{}}' | wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server
```

--------------------------------

### List all available tools using WP-CLI

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/getting-started/basic-examples.md

Use this command to list all available tools from the default MCP server. It sends a JSON-RPC request to the 'tools/list' method via WP-CLI, specifying the admin user and the default server.

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server
```

--------------------------------

### Error response format example

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/default-server.md

Example error response format returned by the default server. It includes a JSON-RPC error object with a numeric code and a message describing the failure, such as a permission denied error.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32008,
    "message": "Permission denied: User lacks required capability: read"
  }
}
```

--------------------------------

### Test MCP adapter with WP-CLI commands

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/default-server.md

Use these WP-CLI commands to test the MCP adapter server. Each command pipes a JSON-RPC request to `wp mcp-adapter serve` with `--user=admin` and `--server=mcp-adapter-default-server`. The first lists available tools, the second gets info about a specific ability, and the third executes an ability with parameters.

```bash
# List all available tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | \
  wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server

# Get info about a specific ability
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"mcp-adapter-get-ability-info","arguments":{"ability_name":"my-plugin/create-post"}}}' | \
  wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server

# Execute an ability
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"mcp-adapter-execute-ability","arguments":{"ability_name":"my-plugin/create-post","parameters":{"title":"Test Post","content":"Hello World"}}}}' | \
  wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server
```

--------------------------------

### Permission denied with WP_Error event example

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/observability.md

Example of a permission denied error with a detailed WP_Error. The WP_Error code is used as failure_reason, e.g., 'ability_invalid_input'. If boolean false is returned, the generic 'permission_denied' reason is used.

```php
// Permission denied with detailed WP_Error
[
  'event' => 'mcp.request',
  'tags' => [
    'status' => 'error',
    'method' => 'tools/call',
    'transport' => 'http',
    'server_id' => 'default',
    'request_id' => 84,
    'session_id' => 'a3f2c1d4-5e6f-7890-abcd-ef1234567890',
    'params' => ['name' => 'user-notifications', 'arguments_count' => 1],
    'component_type' => 'tool',
    'tool_name' => 'user-notifications',
    'ability_name' => 'wpcom-mcp/user-notifications',
    'failure_reason' => 'ability_invalid_input', // WP_Error code used directly
    'error_code' => -32004,
  ],
  'duration_ms' => 8.51
]
```

--------------------------------

### Create a custom MCP server with mcp_adapter_init

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/default-server.md

Registers a custom MCP server via the mcp_adapter_init hook, exposing the listed abilities as standalone MCP tools. The AI agent sees my-plugin-create-post and my-plugin-update-post as individual tools with full schemas, no discovery step required.

```php
add_action( 'mcp_adapter_init', function ( $adapter ) {
    $adapter->create_server(
        'content-server',
        'mcp',
        'content-server',
        'Content Server',
        'Focused content management tools',
        '1.0.0',
        array( \WP\MCP\Transport\HttpTransport::class ),
        \WP\MCP\Infrastructure\ErrorHandling\ErrorLogMcpErrorHandler::class,
        null, // observability handler
        array( 'my-plugin/create-post', 'my-plugin/update-post' ), // tools
        array(), // resources
        array()  // prompts
    );
} );
```

--------------------------------

### Replace failure reason string literals with FailureReason constants

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/migration/v0.5.0.md

Shows the migration from raw string literals to the FailureReason constant for failure reason observability events. The before example uses the literal 'permission_denied', while the after example uses the typed constant FailureReason::PERMISSION_DENIED.

```php
// Before: string literals scattered across the codebase
'failure_reason' => 'permission_denied'

// After: centralized constants
'failure_reason' => FailureReason::PERMISSION_DENIED
```

--------------------------------

### Environment-specific configurations

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/cli-usage.md

Use different configurations for different environments: development, staging, and production with limited access.

```bash
# Development
wp mcp-adapter serve --server=dev-server --user=admin

# Staging
wp mcp-adapter serve --server=staging-server --user=staging-user

# Production (limited access)
wp mcp-adapter serve --server=prod-server --user=api-user
```

--------------------------------

### ToolAnnotations Specification

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/creating-abilities.md

Example of the supported MCP specification annotations for Tools.

```php
'meta' => [
    'annotations' => [
        'readOnlyHint' => true,       // Tool doesn't modify data
        'destructiveHint' => false,   // Tool doesn't delete/destroy data
        'idempotentHint' => true,     // Same input → same output
        'openWorldHint' => false,     // Works with predefined data only
        'title' => 'Custom Title'     // Display title (optional)
    ]
]
```

--------------------------------

### Test with admin user and check capabilities

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/troubleshooting/common-issues.md

Test the MCP adapter with an admin user and list user capabilities to diagnose permission denied errors.

```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | wp mcp-adapter serve --user=admin --server=mcp-adapter-default-server
```

```bash
wp user list --fields=ID,user_login,roles
```

--------------------------------

### Create a confirmation-wrapped post creation tool

Source: https://github.com/wordpress/mcp-adapter/blob/trunk/docs/guides/mrtr.md

Registers a tool that validates input, checks the Ability's permissions, verifies the authenticated client, and asks for confirmation before creating a draft. The tool returns errors for invalid input, missing Ability, or unauthenticated requests. It uses a fixed key order for input hashing and saves state before returning.

```php
use WP\MCP\Domain\Tools\McpInputRequired;
use WP\MCP\Domain\Tools\McpTool;
use WP\MCP\Domain\Tools\McpToolCallContext;

$make_create_post_tool = static function ( callable $authenticated_client_id ) {
    return McpTool::fromArray(
        array(
            'name'        => 'create-post-with-confirmation',
            'description' => 'Create a draft post after confirmation of its title and content.',
            'inputSchema' => array(
                'type'                 => 'object',
                'properties'           => array(
                    'title'   => array( 'type' => 'string', 'minLength' => 1, 'maxLength' => 200 ),
                    'content' => array( 'type' => 'string', 'maxLength' => 10000 ),
                ),
                'required'             => array( 'title', 'content' ),
                'additionalProperties' => false,
            ),
            'permission' => static function ( array $args ) {
                $ability = wp_get_ability( 'my-plugin/create-post' );
                if ( null === $ability ) {
                    return new WP_Error( 'missing_ability', 'The post creation Ability is unavailable.' );
                }
                // Ability permission callbacks expect validated domain input.
                $valid = $ability->validate_input( $args );
                if ( is_wp_error( $valid ) ) {
                    return $valid;
                }
                return $ability->check_permissions( $args );
            },
            'handler' => static function ( array $args, McpToolCallContext $context ) use ( $authenticated_client_id ) {
                // Direct tools validate their own arguments before using them.
                if ( ! isset( $args['title'], $args['content'] )
                    || ! is_string( $args['title'] ) || ! is_string( $args['content'] )
                    || '' === trim( $args['title'] )
                    || mb_strlen( $args['title'], 'UTF-8' ) > 200 || mb_strlen( $args['content'], 'UTF-8' ) > 10000
                    || array_diff( array_keys( $args ), array( 'title', 'content' ) ) ) {
                    return new WP_Error( 'invalid_post_input', 'Supply a title and content within the size limits.' );
                }

                $ability = wp_get_ability( 'my-plugin/create-post' );
                if ( null === $ability ) {
                    return new WP_Error( 'missing_ability', 'The post creation Ability is unavailable.' );
                }
                $client_id = $authenticated_client_id();
                if ( ! is_string( $client_id ) || '' === $client_id || 0 === get_current_user_id() ) {
                    return new WP_Error( 'missing_identity', 'An authenticated client and user are required.' );
                }

                // Fixed key order makes the digest independent of argument order.
                $input = array( 'title' => $args['title'], 'content' => $args['content'] );
                $binding = array(
                    'user'   => get_current_user_id(),
                    'blog'   => get_current_blog_id(),
                    'client' => $client_id,
                    'tool'   => 'create-post-with-confirmation',
                    'input'  => hash( 'sha256', wp_json_encode( $input, JSON_THROW_ON_ERROR ) ),
                );
                $state = $context->request_state();
                $answers = $context->input_responses();

```
Tokens:
Raw