Overview

This document provides a high-level introduction to the MCP Adapter system architecture, its core components, and how requests flow through the system. For detailed installation instructions, see Installation. For fundamental concepts and terminology, see Key Concepts. For in-depth architectural details, see Architecture.

System Purpose

MCP Adapter is a WordPress package that bridges the WordPress Abilities API with the Model Context Protocol (MCP) specification. It enables AI agents to interact with WordPress functionality by automatically converting WordPress abilities into MCP tools, resources, and prompts.

The system operates through a three-tier architecture:

1. Transport Layer: HTTP and STDIO communication protocols
2. Routing Layer: JSON-RPC request routing and session management
3. Handler Layer: Business logic for tools, resources, prompts, and system operations

Sources: README.md1-11

Architecture Overview

The MCP Adapter follows a modular, layered architecture with clear separation of concerns:

Key architectural patterns:

Layer	Purpose	Key Components
Core	Server management and component registry	McpAdapter, McpServer, McpComponentRegistry
Transport	Protocol implementation and request routing	HttpTransport, StdioServerBridge, RequestRouter
Handler	MCP method implementation	ToolsHandler, ResourcesHandler, PromptsHandler, InitializeHandler, SystemHandler
Domain	Ability-to-MCP conversion	RegisterAbilityAsMcpTool, RegisterAbilityAsMcpResource, RegisterAbilityAsMcpPrompt
Infrastructure	Error handling, observability, sessions	McpErrorFactory, McpObservabilityHandlerInterface, SessionManager

Sources: README.md56-146 includes/Core/McpAdapter.php includes/Core/McpServer.php includes/Core/McpComponentRegistry.php includes/Transport/HttpTransport.php includes/Transport/Infrastructure/RequestRouter.php includes/Cli/StdioServerBridge.php

Request Processing Flow

Every MCP request follows a consistent lifecycle from client to response:

Request lifecycle stages:

1. Transport Processing: JSON-RPC parsing, session validation, transport permission checks
2. Request Routing: Method dispatch, observability start tracking
3. Handler Execution: Parameter validation, component retrieval, permission checks
4. Ability Execution: WordPress ability callback invocation
5. Response Building: Metadata attachment, observability recording, JSON-RPC formatting

Sources: includes/Transport/HttpTransport.php includes/Transport/Infrastructure/RequestRouter.php includes/Transport/Infrastructure/SessionManager.php includes/Transport/Infrastructure/HttpSessionValidator.php includes/Handlers/Tools/ToolsHandler.php includes/Handlers/Resources/ResourcesHandler.php includes/Handlers/Prompts/PromptsHandler.php

Component Transformation Pipeline

WordPress abilities are automatically transformed into MCP components through a registration and conversion pipeline:

Transformation rules:

Ability Metadata	Resulting MCP Component	Registration Class
meta.mcp.type = 'tool'	McpTool	RegisterAbilityAsMcpTool
meta.mcp.type = 'resource'	McpResource	RegisterAbilityAsMcpResource
meta.mcp.type = 'prompt'	McpPrompt	RegisterAbilityAsMcpPrompt
meta.mcp.public = true	Exposed via REST API	N/A
meta.mcp.public = false	Internal only	N/A

For detailed information on creating abilities, see Creating Abilities. For schema transformation details, see Schema Transformation.

Sources: includes/Domain/Tools/RegisterAbilityAsMcpTool.php includes/Domain/Resources/RegisterAbilityAsMcpResource.php includes/Domain/Prompts/RegisterAbilityAsMcpPrompt.php includes/Infrastructure/SchemaTransformer.php includes/Core/McpComponentRegistry.php

Multi-Server Architecture

The McpAdapter singleton manages multiple independent McpServer instances, each with isolated configuration:

Server isolation guarantees:

Configuration	Per-Server	Shared
REST endpoint	✓
Component registry	✓
Error handler	✓
Observability handler	✓
Transport permissions	✓
Session management	✓
WordPress abilities	✓

The default server (mcp-adapter-default-server) is automatically created by DefaultServerFactory::create() during the mcp_adapter_init action. Custom servers are created via McpAdapter::create_server() during the same action hook.

For server creation details, see Server Creation and Configuration.

Sources: includes/Core/McpAdapter.php includes/Core/McpServer.php includes/Servers/DefaultServerFactory.php README.md449-471

Key Components and Their Roles

The following table summarizes the primary classes and their responsibilities:

Component	File Path	Purpose
McpAdapter	includes/Core/McpAdapter.php	Singleton registry managing all McpServer instances
McpServer	includes/Core/McpServer.php	Individual server configuration with component registry, transports, and handlers
McpComponentRegistry	includes/Core/McpComponentRegistry.php	Storage and retrieval of tools, resources, and prompts
HttpTransport	includes/Transport/HttpTransport.php	HTTP transport implementing MCP 2025-06-18 specification
StdioServerBridge	includes/Cli/StdioServerBridge.php	STDIO transport for WP-CLI integration
RequestRouter	includes/Transport/Infrastructure/RequestRouter.php	Routes JSON-RPC methods to appropriate handlers
SessionManager	includes/Transport/Infrastructure/SessionManager.php	Creates and validates session identifiers
ToolsHandler	includes/Handlers/Tools/ToolsHandler.php	Handles tools/list and tools/call methods
ResourcesHandler	includes/Handlers/Resources/ResourcesHandler.php	Handles resources/list and resources/read methods
PromptsHandler	includes/Handlers/Prompts/PromptsHandler.php	Handles prompts/list and prompts/get methods
InitializeHandler	includes/Handlers/Initialize/InitializeHandler.php	Handles initialize method for session creation
SystemHandler	includes/Handlers/System/SystemHandler.php	Handles system methods like ping and logging/setLevel
RegisterAbilityAsMcpTool	includes/Domain/Tools/RegisterAbilityAsMcpTool.php	Converts WordPress ability to McpTool
RegisterAbilityAsMcpResource	includes/Domain/Resources/RegisterAbilityAsMcpResource.php	Converts WordPress ability to McpResource
RegisterAbilityAsMcpPrompt	includes/Domain/Prompts/RegisterAbilityAsMcpPrompt.php	Converts WordPress ability to McpPrompt
SchemaTransformer	includes/Infrastructure/SchemaTransformer.php	Transforms flattened schemas to MCP-compatible object schemas
McpErrorFactory	includes/Infrastructure/ErrorHandling/McpErrorFactory.php	Creates standardized JSON-RPC error responses
McpErrorHandlerInterface	includes/Infrastructure/ErrorHandling/Contracts/McpErrorHandlerInterface.php	Interface for error handling implementations
McpObservabilityHandlerInterface	includes/Infrastructure/Observability/Contracts/McpObservabilityHandlerInterface.php	Interface for observability implementations
ExecuteAbilityAbility	includes/Abilities/ExecuteAbilityAbility.php	Built-in ability for executing any registered WordPress ability
DiscoverAbilitiesAbility	includes/Abilities/DiscoverAbilitiesAbility.php	Built-in ability for discovering available abilities

For detailed information on handlers, see Request Processing Pipeline. For transport details, see Transport System. For infrastructure concerns, see Infrastructure.

Sources: README.md56-146 includes/Core/ includes/Transport/ includes/Handlers/ includes/Domain/ includes/Infrastructure/ includes/Abilities/