MCP Adapter

Part of the AI Building Blocks for WordPress initiative

A canonical plugin for WordPress that provides the adapter for the WordPress Abilities API, enabling WordPress abilities to be exposed as MCP (Model Context Protocol) tools, resources, and prompts. This adapter serves as the foundation for integrating WordPress capabilities with AI agents through the MCP specification.

Overview

The MCP Adapter bridges the gap between WordPress's Abilities API and the Model Context Protocol (MCP), allowing WordPress applications to expose their functionality to AI agents in a standardized, secure, and extensible way. It provides a clean abstraction layer that converts WordPress abilities into MCP-compatible interfaces.

Built for Extensibility: The adapter ships with production-ready REST API and streaming transport protocols, plus a default error handling system. However, it's designed to be easily extended - create custom transport protocols for specialized communication needs or implement custom error handlers for advanced logging, monitoring, and notification systems.

Features

Core Functionality

• Ability-to-MCP Conversion: Automatically converts WordPress abilities into MCP tools, resources, and prompts
• Multi-Server Management: Create and manage multiple MCP servers with unique configurations
• Extensible Transport Layer:
  • Built-in Transports: REST API (RestTransport) and Streaming (StreamableTransport) protocols included
  • Custom Transport Support: Implement McpTransportInterface to create custom communication protocols
  • Multiple Transport per Server: Configure servers with multiple transport methods simultaneously
• Flexible Error Handling:
  • Built-in Error Handler: Default WordPress-compatible error logging included
  • Custom Error Handlers: Implement McpErrorHandlerInterface for custom logging, monitoring, or notification systems
  • Server-specific Handlers: Different error handling strategies per MCP server
• Observability:
  • Built-in Observability: Default zero-overhead metrics tracking with configurable handlers
  • Custom Observability Handlers: Implement McpObservabilityHandlerInterface for integration with monitoring systems
• Validation: Built-in validation for tools, resources, and prompts with extensible validation rules
• Permission Control: Granular permission checking for all exposed functionality with configurable transport permissions

MCP Component Support

• Tools: Convert abilities into executable MCP tools
• Resources: Expose abilities as MCP resources for data access
• Prompts: Transform abilities into structured MCP prompts
• Server Discovery: Automatic registration and discovery of MCP servers

Understanding Abilities as MCP Components

The MCP Adapter's core strength lies in its ability to transform WordPress abilities into different MCP component types, each serving distinct interaction patterns with AI agents.

Abilities as Tools

Purpose: Interactive, action-oriented functionality that AI agents can execute with specific parameters.

When to Use:

• Operations that modify data or state (creating posts, updating settings)
• Search and query operations that require dynamic parameters
• Actions that return computed results based on input parameters
• Functions that perform business logic or data processing

Characteristics:

• Accept input parameters defined by the ability's input schema
• Execute the ability's callback function with provided arguments
• Return structured results based on the ability's output schema
• Respect permission callbacks for access control
• Can have side effects (create, update, delete operations)

Abilities as Resources

Purpose: Static or semi-static data access that provides information without requiring complex input parameters.

When to Use:

• Providing current user information or site metadata
• Exposing configuration data or system status
• Offering read-only access to data collections
• Sharing contextual information that doesn't change frequently

Characteristics:

• Primarily data retrieval operations with minimal or no input parameters
• Focus on providing information rather than performing actions
• Results are typically cacheable and may not change frequently
• Often used for context gathering by AI agents
• Generally read-only operations without side effects

Abilities as Prompts

Purpose: Structured templates that guide AI agents in generating contextually appropriate responses or suggestions.

When to Use:

• Providing advisory content (SEO recommendations, content strategy)
• Generating analysis reports (performance assessments, security audits)
• Offering structured prompts for content generation or optimization

Characteristics:

• Focus on generating human-readable guidance and recommendations
• May incorporate data from other abilities or WordPress APIs
• Designed to provide actionable insights and suggestions
• Often combine multiple data sources to create comprehensive advice
• Results are typically formatted for direct presentation to users

Component Selection Strategy

The choice between tools, resources, and prompts depends on the intended interaction pattern:

• Choose Tools for operations requiring user input and dynamic execution
• Choose Resources for providing contextual data and system information
• Choose Prompts for generating guidance, analysis, and recommendations

The same WordPress ability can potentially be exposed through multiple component types, allowing different interaction patterns for various use cases.

Architecture

Component Overview

./src
│   # Core system components
├── Core/
│   ├── McpAdapter.php # Main registry and server management
│   └── McpServer.php  # Individual server configuration
│
│   # Business logic and MCP components
├── Domain/
│   │   # MCP Tools implementation
│   ├── Tools/
│   │   ├── McpTool.php                   # Base tool class
│   │   ├── RegisterAbilityAsMcpTool.php  # Ability-to-tool conversion
│   │   └── McpToolValidator.php          # Tool validation
│   │   # MCP Resources implementation
│   ├── Resources/
│   │   ├── McpResource.php                   # Base resource class
│   │   ├── RegisterAbilityAsMcpResource.php  # Ability-to-resource conversion
│   │   └── McpResourceValidator.php          # Resource validation
│   │   # MCP Prompts implementation
│   └── Prompts/
│       ├── Contracts/                         # Prompt interfaces
│       │   └── McpPromptBuilderInterface.php  # Prompt builder interface
│       ├── McpPrompt.php                      # Base prompt class
│       ├── McpPromptBuilder.php               # Prompt builder implementation
│       ├── McpPromptValidator.php             # Prompt validation
│       └── RegisterAbilityAsMcpPrompt.php     # Ability-to-prompt conversion
│
│   # Request processing handlers
├── Handlers/
│   ├── Initialize/  # Initialization handlers
│   ├── Tools/       # Tool request handlers
│   ├── Resources/   # Resource request handlers
│   ├── Prompts/     # Prompt request handlers
│   └── System/      # System request handlers
│
│   # Infrastructure concerns
├── Infrastructure/
│   │   # Error handling system
│   ├── ErrorHandling/
│   │   ├── Contracts/                        # Error handling interfaces
│   │   │   └── McpErrorHandlerInterface.php  # Error handler interface
│   │   ├── ErrorLogMcpErrorHandler.php       # Default error handler
│   │   ├── NullMcpErrorHandler.php           # Null object pattern
│   │   └── McpErrorFactory.php               # Error response factory
│   │   # Monitoring and observability
│   └── Observability/
│       ├── Contracts/                                # Observability interfaces
│       │   └── McpObservabilityHandlerInterface.php  # Observability interface
│       ├── ErrorLogMcpObservabilityHandler.php       # Default handler
│       ├── NullMcpObservabilityHandler.php           # Null object pattern
│       └── McpObservabilityHelperTrait.php           # Helper trait
│
│   # Transport layer implementations
├─── Transport/
│   ├── Contracts/
│   │   └── McpTransportInterface.php  # Transport interface
│   │   # HTTP-based transports
│   │   # Transport interfaces
│   ├── Http/
│   │   ├── RestTransport.php        # REST API transport
│   │   └── StreamableTransport.php  # Streaming transport
│   │   # Transport infrastructure
│   └── Infrastructure/
│       ├── McpRequestRouter.php         # Request routing
│       ├── McpTransportContext.php      # Transport context
│       └── McpTransportHelperTrait.php  # Helper trait
│
│   # Plugin Wrapper - these won't be needed if/when merged into core.
├── Autoloader.php  # PSR-4 autoloader.
└── Plugin.php      # Plugin entrypoint.

Key Classes

McpAdapter

The main registry class that manages multiple MCP servers:

• Singleton Pattern: Ensures single instance across the application
• Server Management: Create, configure, and retrieve MCP servers
• Initialization: Handles WordPress integration and action hooks
• REST API Integration: Automatically integrates with WordPress REST API

McpServer

Individual server management with comprehensive configuration:

• Server Identity: Unique ID, namespace, route, name, and description
• Component Registration: Tools, resources, and prompts management
• Transport Configuration: Multiple transport method support
• Error Handling: Server-specific error handling and logging
• Validation: Built-in validation for all registered components

Dependencies

Required Dependencies

• PHP: >= 7.4
• WordPress Abilities API: For ability registration and management

WordPress Abilities API Integration

This adapter requires the WordPress Abilities API, which provides:

• Standardized ability registration (wp_register_ability())
• Ability retrieval and management (wp_get_ability())
• Schema definition for inputs and outputs
• Permission callback system
• Execute callback system

Installation

As a plugin

The best and easiest way to try and use the MCP Adapter is to install it as a plugin by downloading the latest release from the GitHub Releases page.

With WP-CLI

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

With WP-Env

// .wp-env.json
{
  "$schema": "https://schemas.wp.org/trunk/wp-env.json",
  // ... other config ...
  "plugins": [
    "WordPress/abilities-api",
    "WordPress/mcp-adapter",
    // ... other plugins ...
  ],
  // ... more config ...
}

With Composer

Until the plugin is available on Packagist, you will need to add the repository to your composer.json file.

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/WordPress/abilities-api.git"
    },
    {
      "type": "vcs",
      "url": "https://github.com/WordPress/mcp-adapter.git"
    }
    // ... other repositories.
  ],
  "extra": {
    "installer-paths": {
      // This should match your WordPress+Composer setup.
      "wp-content/plugins/{$name}/": [
          "type:wordpress-plugin"
      ]
      // .. other paths.
    }
  }
  // ... rest of your composer.json.
}

Then, require the package in your project:

composer require wordpress/abilities-api wordpress/mcp-adapter

As a dependency

Plugin authors and developers may wish to rely on the MCP Adapter as a dependency in their own projects, before it is merged into core. You can do that in one of the following ways.

As a Plugin Dependency (Recommended)

The best way to ensure the MCP Adapter is available for your plugins is to include it as one of your Requires Plugins in your Plugin header. For example:

# my-plugin.php
/*
 *
 * Plugin Name:       My Plugin
 * Plugin URI:        https://example.com/plugins/the-basics/
 * Description:       Handle the basics with this plugin.
 * {all the other plugin header fields...}
 * Requires Plugins:  mcp-adapter
 */

While this is enough to ensure the MCP Adapter is loaded before your plugin, if you need to ensure specific version requirements or provide users guidance on installing the plugin, you can use the methods described later on

As a Composer dependency

Until the plugin is available on WordPress, you will need to add the repository to your composer.json file.

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/WordPress/mcp-adapter.git"
    }
    // ... other repositories.
  ],
  // ... rest of your composer.json.
}

Then, require the package in your project:

composer require wordpress/mcp-adapter

Checking availability with code

To ensure the MCP Adapter is loaded in your plugin:

if ( ! class_exists( 'WP\MCP\Plugin' ) ) {
  // E.g. add an admin notice about the missing dependency.
  add_action( 'admin_notices', static function() {
    wp_admin_notice(
      esc_html__( 'This plugin requires the MCP Adapter to use. Please install and activate it.', 'my-plugin' ),
      'error'
    );
  } );
  return;
}

You can also check for specific versions of the MCP Adapter using the WP_MCP_VERSION constant:

if ( ! defined( 'WP_MCP_VERSION' ) || version_compare( WP_MCP_VERSION, '0.1.0', '<' ) ) {
  // E.g. add an admin notice about the required version.
  add_action( 'admin_notices', static function() {
    wp_admin_notice(
      esc_html__( 'This plugin requires MCP Adapter version 0.1.0 or higher. Please update the plugin dependency.', 'my-plugin' ),
      'error'
    );
  } );
  return;
}

Basic Usage

Creating an MCP Server

To create an MCP server, register a callback function to the mcp_adapter_init action hook. This callback function can accept one parameter, $adapter, which is an instance of the McpAdapter class that is used to create the MCP server.

add_action('mcp_adapter_init', function($adapter) {
    $adapter->create_server(
        'my-server-id',                    // Unique server identifier
        'my-namespace',                    // REST API namespace
        'mcp',                            // REST API route
        'My MCP Server',                  // Server name
        'Description of my server',       // Server description
        'v1.0.0',                        // Server version
        [                                 // Transport methods
            \WP\MCP\Transport\Http\RestTransport::class,
        ],
        \WP\MCP\Infrastructure\ErrorHandling\ErrorLogMcpErrorHandler::class, // Error handler
        \WP\MCP\Infrastructure\Observability\NullMcpObservabilityHandler::class, // Observability handler
        ['my-plugin/my-ability'],         // Abilities to expose as tools
        [],                              // Resources (optional)
        []                               // Prompts (optional)
    );
});

Advanced Usage

Custom Transport Implementation

While the MCP Adapter includes production-ready REST API and streaming transports, you may need to create custom transport protocols to meet specific infrastructure requirements or integration needs.

Why Create Custom Transports:

• Product-Specific Requirements: Different products may need unique authentication, routing, or response formats that don't fit the standard REST transport
• Integration with Existing Systems: Connect with your product's existing APIs, message queues, or internal communication protocols
• Performance Needs: Optimize for high-traffic scenarios or specific latency requirements your product demands
• Security & Compliance: Implement custom authentication, request signing, or meet specific security standards your product requires
• Environment-Specific Behavior: Handle different configurations for development, staging, and production environments
• Custom Monitoring: Integrate with your product's existing logging and analytics infrastructure

use WP\MCP\Transport\Contracts\McpTransportInterface;
use WP\MCP\Transport\Infrastructure\McpTransportContext;
use WP\MCP\Transport\Infrastructure\McpTransportHelperTrait;

class MyCustomTransport implements McpTransportInterface {
    use McpTransportHelperTrait;
    
    private McpTransportContext $context;
    
    public function __construct(McpTransportContext $context) {
        $this->context = $context;
        add_action('rest_api_init', [$this, 'register_routes']);
    }
    
    public function register_routes(): void {
        // Register custom REST API routes
        register_rest_route(
            $this->context->mcp_server->get_server_route_namespace(), 
            $this->context->mcp_server->get_server_route() . '/custom', 
            [
                'methods' => 'POST',
                'callback' => [$this, 'handle_request'],
                'permission_callback' => [$this, 'check_permission']
            ]
        );
    }
    
    public function check_permission() {
        return is_user_logged_in();
    }
    
    public function handle_request($request) {
        // Custom request handling logic
        return rest_ensure_response(['status' => 'success']);
    }
}

Custom Error Handler

While the MCP Adapter includes a default WordPress-compatible error handler, your product may need custom error handling to integrate with existing systems or meet specific requirements.

Why Create Custom Error Handlers:

• Integration with Existing Logging: Connect with your product's current logging systems (Logstash, Sentry, DataDog, etc.)
• Product-Specific Context: Add custom fields like user IDs, product versions, or feature flags to error logs
• Alert Integration: Trigger notifications, Slack alerts, or incident management workflows when errors occur
• Error Routing: Send different types of errors to different systems (critical errors to on-call, debug info to development logs)
• Compliance Requirements: Meet specific logging standards or data retention policies your product requires
• Performance Monitoring: Track error rates and patterns in your product's analytics dashboard

use WP\MCP\Infrastructure\ErrorHandling\Contracts\McpErrorHandlerInterface;

class MyErrorHandler implements McpErrorHandlerInterface {
    public function log(string $message, array $context = [], string $type = 'error'): void {
        // Custom error logging implementation
        error_log(sprintf(
            '[MCP Error] %s - Context: %s',
            $message,
            json_encode($context)
        ));
    }
}

License

GPL-2.0-or-later