Architecture

This page explains the high-level architecture of the MCP Adapter, including its core components, layered design, request processing flow, and security model. For implementation details of specific subsystems, see Core System Components, Request Processing Pipeline, and Security and Permissions.

Three-Tier Architecture

The MCP Adapter follows a three-tier architecture that separates concerns between communication, routing, and business logic:

Sources: includes/Core/McpAdapter.php1-319 includes/Core/McpServer.php includes/Transport/HttpTransport.php includes/Transport/Infrastructure/RequestRouter.php README.md56-146

The three tiers operate as follows:

Tier	Responsibility	Key Classes
Transport	Accept connections, parse JSON-RPC, authenticate, manage sessions	HttpTransport, StdioServerBridge, HttpSessionValidator
Routing	Dispatch methods to handlers, extract metadata, coordinate observability	RequestRouter, HttpRequestHandler, HttpRequestContext
Handler	Execute business logic, validate parameters, interact with abilities	ToolsHandler, ResourcesHandler, PromptsHandler, SystemHandler

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

Core Components

McpAdapter Singleton Registry

The McpAdapter class serves as the central registry for all MCP servers in a WordPress installation. It implements the singleton pattern to ensure a single point of coordination.

Sources: includes/Core/McpAdapter.php25-319

Key responsibilities of McpAdapter:

Method	Purpose	Hook
instance()	Returns singleton instance, sets up initialization hooks	rest_api_init (priority 15) or init (priority 20 for CLI)
init()	Creates default server, fires mcp_adapter_init action	Called by WordPress action hooks
create_server()	Validates and registers new McpServer instances	Must be called during mcp_adapter_init action
get_server()	Retrieves server by ID	N/A
get_servers()	Returns all registered servers	N/A

Sources: includes/Core/McpAdapter.php55-227 mcp-adapter.php55-56

McpServer Instances

Each McpServer represents an independent MCP server with its own configuration, components, and endpoints:

Sources: includes/Core/McpServer.php includes/Core/McpComponentRegistry.php

Each server maintains isolated configuration:

Configuration	Description	Default
Endpoint	REST API route for HTTP transport	/wp-json/{namespace}/{route}
Transport permissions	Callback for server-wide authentication	is_user_logged_in()
Error handler	Custom error logging/monitoring	NullMcpErrorHandler
Observability handler	Custom metrics/event tracking	NullMcpObservabilityHandler
Components	Registered tools, resources, prompts	Empty arrays

Sources: includes/Core/McpServer.php includes/Core/McpAdapter.php107-227

Component Registry Pattern

The McpComponentRegistry manages component lookup and validation:

Sources: includes/Core/McpComponentRegistry.php

Multi-Server Architecture

The adapter supports multiple independent MCP servers running simultaneously, each with isolated configuration:

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

Default Server Creation: The default server (mcp-adapter-default-server) is automatically created during mcp_adapter_init unless filtered out via apply_filters('mcp_adapter_create_default_server', true).

Sources: includes/Core/McpAdapter.php254-265 includes/Servers/DefaultServerFactory.php

Request Processing Flow

The complete lifecycle from client request to handler response follows this sequence:

HTTP Transport Flow

Sources: includes/Transport/HttpTransport.php includes/Transport/Infrastructure/HttpRequestHandler.php includes/Transport/Infrastructure/HttpSessionValidator.php includes/Transport/Infrastructure/SessionManager.php includes/Transport/Infrastructure/RequestRouter.php includes/Handlers/Tools/ToolsHandler.php

Key Request Processing Classes

Class	File	Responsibility
HttpTransport	includes/Transport/HttpTransport.php	REST API endpoint registration, request parsing
HttpRequestHandler	includes/Transport/Infrastructure/HttpRequestHandler.php	Coordinates request processing, permission checks
HttpSessionValidator	includes/Transport/Infrastructure/HttpSessionValidator.php	Session creation and validation
SessionManager	includes/Transport/Infrastructure/SessionManager.php	Session state management
RequestRouter	includes/Transport/Infrastructure/RequestRouter.php	Method-to-handler dispatch, metadata extraction
JsonRpcResponseBuilder	includes/Transport/Infrastructure/JsonRpcResponseBuilder.php	Standardized response formatting

Sources: includes/Transport/HttpTransport.php includes/Transport/Infrastructure/

Component Registration Lifecycle

WordPress abilities are automatically converted to MCP components through a hook-based lifecycle:

Sources: includes/Core/McpAdapter.php76-86 includes/Core/McpServer.php includes/Domain/Tools/RegisterAbilityAsMcpTool.php includes/Domain/Resources/RegisterAbilityAsMcpResource.php includes/Domain/Prompts/RegisterAbilityAsMcpPrompt.php

Registration Timing

Hook	Priority	Purpose
wp_abilities_api_init	Default (10)	Plugins register abilities
mcp_adapter_init	After REST initialization	Developers create custom servers
rest_api_init	15	McpAdapter::init() runs, creates default server

Sources: includes/Core/McpAdapter.php55-86

Schema Transformation

The SchemaTransformer automatically converts between WordPress Abilities API schemas and MCP-compatible schemas:

Sources: includes/Domain/SchemaTransformer.php

The transformation occurs in two scenarios:

1. Tool Registration: Flattened ability input_schema is wrapped into object format for MCP compatibility
2. Tool Execution: Object-formatted parameters are unwrapped before passing to ability execute_callback

Sources: includes/Domain/Tools/RegisterAbilityAsMcpTool.php includes/Handlers/Tools/ToolsHandler.php

Error Handling Architecture

The error handling system provides centralized error creation and pluggable error handlers:

Sources: includes/Infrastructure/ErrorHandling/McpErrorFactory.php includes/Infrastructure/ErrorHandling/Contracts/McpErrorHandlerInterface.php includes/Infrastructure/ErrorHandling/ErrorLogMcpErrorHandler.php includes/Infrastructure/ErrorHandling/NullMcpErrorHandler.php

Each McpServer can specify its own error handler via the $error_handler parameter in create_server(). If none is provided, NullMcpErrorHandler is used.

Sources: includes/Core/McpAdapter.php107-134

Observability System

The metadata-driven observability architecture enables tracking without coupling handlers to specific monitoring tools:

Sources: includes/Infrastructure/Observability/Contracts/McpObservabilityHandlerInterface.php includes/Infrastructure/Observability/NullMcpObservabilityHandler.php includes/Infrastructure/Observability/ErrorLogMcpObservabilityHandler.php includes/Transport/Infrastructure/RequestRouter.php

Metadata Flow

Handlers attach _metadata to responses containing:

Metadata Field	Description	Source
component_type	"tool", "resource", or "prompt"	Handler logic
component_name	Name of executed component	Handler parameter
execution_time_ms	Duration of execution	Handler timing
failure_reason	Error category on failure	Error context

Sources: includes/Handlers/Tools/ToolsHandler.php includes/Handlers/Resources/ResourcesHandler.php includes/Handlers/Prompts/PromptsHandler.php

The RequestRouter extracts this metadata and records events via the server's McpObservabilityHandlerInterface:

Sources: includes/Transport/Infrastructure/RequestRouter.php

Two-Layer Security Model

The MCP Adapter implements security at two distinct layers:

Sources: includes/Transport/Infrastructure/HttpRequestHandler.php includes/Handlers/Tools/ToolsHandler.php includes/Handlers/Resources/ResourcesHandler.php includes/Handlers/Prompts/PromptsHandler.php

Layer 1: Transport Permissions

Server-wide authentication configured via $transport_permission_callback parameter:

Sources: includes/Core/McpAdapter.php107 includes/Transport/Infrastructure/HttpRequestHandler.php

Layer 2: Ability Permissions

Granular permission checks defined in each ability's permission_callback:

Sources: WordPress Abilities API, includes/Handlers/Tools/ToolsHandler.php

Both layers must pass for execution to proceed. See Transport Permissions for implementation patterns and Security and Permissions for detailed security architecture.

Sources: includes/Transport/Infrastructure/HttpRequestHandler.php includes/Handlers/Tools/ToolsHandler.php includes/Handlers/Resources/ResourcesHandler.php includes/Handlers/Prompts/PromptsHandler.php README.md34