WordPress · Jameswlepage · Aug 30, 2025 · Aug 31, 2025 · Aug 31, 2025 · Aug 31, 2025
diff --git a/.wp-env.json b/.wp-env.json
@@ -1,7 +1,7 @@
 {
 	"$schema": "https://schemas.wp.org/trunk/wp-env.json",
 	"core": null,
-	"plugins": ["WordPress/abilities-api", "./."],
+	"plugins": ["WordPress/abilities-api", "./.", "./demo"],
 	"env": {
 		"development": {
 			"config": {

diff --git a/README.md b/README.md
@@ -2,15 +2,18 @@
 
 [*Part of the **AI Building Blocks for WordPress** initiative*](https://make.wordpress.org/ai/2025/07/17/ai-building-blocks)
 
-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.
+A canonical plugin for WordPress that provides bidirectional integration with the Model Context Protocol (MCP). It enables WordPress abilities to be exposed as MCP tools, resources, and prompts, **and** allows WordPress to connect to external MCP servers and use their capabilities as local abilities. This adapter serves as the foundation for integrating WordPress capabilities with AI agents through the MCP specification.
+
+**Includes Demo Plugin**: A complete demonstration plugin showcasing real-world usage patterns, admin interface, and practical examples.
 
 ## 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.
+The MCP Adapter bridges the gap between WordPress's Abilities API and the Model Context Protocol (MCP), enabling bidirectional integration:
+
+**Server Mode**: Expose WordPress abilities to AI agents as MCP tools, resources, and prompts.
+**Client Mode**: Connect to external MCP servers and use their capabilities as local WordPress abilities.
+
+This provides a clean abstraction layer that seamlessly integrates WordPress with the broader MCP ecosystem.
 
 **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
@@ -21,8 +24,14 @@ systems.
 
 ### Core Functionality
 
+**MCP Server Features:**
 - **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
+
+**MCP Client Features:**
+- **Remote MCP Integration**: Connect to external MCP servers and consume their capabilities
+- **Ability Registration**: Remote MCP tools, resources, and prompts become local WordPress abilities
+- **Multi-Client Management**: Connect to multiple external MCP servers simultaneously
 - **Extensible Transport Layer**:
     - **Built-in Transports**: REST API (`RestTransport`) and Streaming (`StreamableTransport`) protocols included
     - **Custom Transport Support**: Implement `McpTransportInterface` to create custom communication protocols
@@ -379,6 +388,8 @@ if ( ! defined( 'WP_MCP_VERSION' ) || version_compare( WP_MCP_VERSION, '0.1.0',
 
 ## Basic Usage
 
+**Note**: For complete working examples, see the included [demo plugin](demo/) which provides practical implementations and an admin interface for testing MCP functionality.
+
 ### 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.
@@ -404,6 +415,76 @@ add_action('mcp_adapter_init', function($adapter) {
 });
 ```
 
+### Creating an MCP Client
+
+To connect to external MCP servers, register a callback function to the `mcp_client_init` action hook:
+
+```php
+add_action('mcp_client_init', function($adapter) {
+    $adapter->create_client(
+        'ai-service',                    // Unique client identifier
+        'https://api.example.com/mcp',   // External MCP server URL
+        [                                // Client configuration
+            'auth' => [
+                'type'  => 'bearer',
+                'token' => 'your-api-token',
+            ],
+            'timeout' => 30,
+        ]
+    );
+});
+```
+
+Once connected, remote MCP capabilities automatically become available as WordPress abilities:
+
+```php
+// Remote MCP tool becomes a WordPress ability
+$result = wp_execute_ability('mcp_ai-service/analyze-content', [
+    'content' => 'Text to analyze',
+    'type'    => 'sentiment'
+]);
+
+// Remote MCP resource becomes a WordPress ability  
+$data = wp_execute_ability('mcp_ai-service/resource/user-profile', []);
+
+// Remote MCP prompt becomes a WordPress ability
+$prompt = wp_execute_ability('mcp_ai-service/prompt/seo-analysis', [
+    'url' => 'https://example.com'
+]);
+```
+
+### Client Authentication
+
+The MCP client supports multiple authentication methods:
+
+```php
+// Bearer token authentication
+$config = [
+    'auth' => [
+        'type'  => 'bearer',
+        'token' => 'your-bearer-token'
+    ]
+];
+
+// API key authentication
+$config = [
+    'auth' => [
+        'type'   => 'api_key',
+        'key'    => 'your-api-key',
+        'header' => 'X-API-Key'  // Optional, defaults to X-API-Key
+    ]
+];
+
+// Basic authentication
+$config = [
+    'auth' => [
+        'type'     => 'basic',
+        'username' => 'your-username',
+        'password' => 'your-password'
+    ]
+];
+```
+
 ## Advanced Usage
 
 ### Custom Transport Implementation

diff --git a/composer.json b/composer.json
@@ -70,7 +70,8 @@
 		}
 	},
 	"require": {
-		"php": "^7.4 || ^8.0"
+		"php": "^7.4 || ^8.0",
+		"wordpress/abilities-api": "^0.1.0"
 	},
 	"require-dev": {
 		"automattic/vipwpcs": "^3.0",

diff --git a/composer.lock b/composer.lock
diff --git a/demo/README.md b/demo/README.md
@@ -0,0 +1,121 @@
+# MCP Adapter Demo Plugin
+
+A demonstration plugin showcasing the MCP Adapter functionality with practical examples and an admin interface for testing MCP server and client capabilities.
+
+## Overview
+
+This demo plugin provides:
+
+- **Admin Interface**: WordPress admin page for managing and testing MCP servers and clients
+- **Working Examples**: Practical implementation examples in the `examples/` directory
+- **Demo Abilities**: Sample WordPress abilities that demonstrate MCP integration patterns
+- **Real-world Usage**: Production-ready code patterns you can use in your own plugins
+
+## Features
+
+### Admin Interface
+
+The demo plugin adds an admin page under **Settings > MCP Settings** that provides:
+
+- **Server Management**: Create and configure MCP servers
+- **Client Management**: Connect to external MCP servers
+- **Testing Tools**: Interactive testing of MCP functionality
+- **Real-time Monitoring**: View server status and connection details
+
+### Dashboard Widget
+
+A clean dashboard widget that displays MCP status information:
+
+- **Server Status**: List of configured MCP servers with capability counts (tools, resources, prompts)
+- **Client Connections**: Connected MCP clients with connection status and server URLs  
+- **Quick Actions**: Direct access to MCP settings and manual refresh functionality
+- **Core WordPress Styling**: Matches WordPress dashboard widgets exactly using minimal custom CSS
+
+### Demo Abilities
+
+The plugin registers several example abilities that demonstrate different MCP integration patterns:
+
+- **Tool Examples**: Interactive abilities that perform actions
+- **Resource Examples**: Data-providing abilities for information access
+- **Prompt Examples**: Template abilities for generating recommendations
+
+### Examples Directory
+
+The `examples/` directory contains standalone PHP files demonstrating:
+
+- Server setup and configuration
+- Client connection and usage
+- Error handling and observability
+- Transport customization
+- Real-world integration patterns
+
+## Installation
+
+### Requirements
+
+- WordPress 6.8+
+- MCP Adapter plugin (installed and activated)
+- PHP 7.4+
+
+### Installation Steps
+
+1. **Install MCP Adapter**: Ensure the main MCP Adapter plugin is installed and activated first
+2. **Install Demo Plugin**: Install this demo plugin 
+3. **Activate Plugin**: Activate the MCP Adapter Demo plugin
+4. **Access Admin Interface**: Navigate to **Settings > MCP Settings** in your WordPress admin
+
+## Usage
+
+### Testing MCP Functionality
+
+1. Navigate to **Settings > MCP Settings** in WordPress admin
+2. Use the interface to create test servers and clients
+3. Monitor connections and test MCP operations
+4. Review the examples directory for code implementation details
+
+### Using as Reference
+
+The demo plugin serves as a reference implementation for:
+
+- **Plugin Structure**: How to structure an MCP-enabled plugin
+- **Ability Registration**: Proper patterns for registering WordPress abilities
+- **Server Configuration**: Best practices for MCP server setup
+- **Client Integration**: How to connect to external MCP servers
+- **Error Handling**: Robust error handling patterns
+- **Admin Integration**: Creating WordPress admin interfaces for MCP management
+
+## Examples Directory
+
+See the [examples README](examples/README.md) for detailed information about the included code examples and how to use them in your own projects.
+
+## Code Structure
+
+```
+demo/
+├── mcp-adapter-demo.php    # Main plugin file
+├── includes/
+│   ├── DemoPlugin.php          # Core plugin class
+│   ├── Autoloader.php          # PSR-4 autoloader
+│   └── Admin/
+│       ├── McpTestPage.php     # Admin interface implementation
+│       ├── DashboardWidget.php # Dashboard widget functionality
+│       └── assets/             # CSS and JavaScript files
+└── examples/               # Standalone usage examples
+```
+
+## Development
+
+This demo plugin follows WordPress coding standards and best practices:
+
+- **PSR-4 Autoloading**: Proper namespace and class loading
+- **WordPress Hooks**: Correct use of WordPress action and filter hooks
+- **Security**: Proper nonce handling and capability checks
+- **Error Handling**: Graceful error handling and user feedback
+
+## Contributing
+
+This demo plugin is part of the MCP Adapter project. For contributing guidelines, see the main [MCP Adapter repository](https://github.com/WordPress/mcp-adapter).
+
+## License
+
+GPL-2.0-or-later - same as WordPress and the main MCP Adapter plugin.