Key Concepts

This page defines the fundamental concepts and terminology used throughout the MCP Adapter system. Understanding these concepts is essential for working with MCP Adapter effectively.

For an introduction to what MCP Adapter is and how it fits into WordPress, see What is MCP Adapter. For practical examples of using these concepts, see Basic Examples.

---

MCP Servers

An MCP Server is an isolated instance that exposes a specific set of abilities as MCP components through dedicated endpoints. Each server has its own configuration for authentication, error handling, observability, and transport methods.

McpAdapter Singleton

The McpAdapter class (includes/Core/McpAdapter.php25) serves as the central registry for all MCP servers in a WordPress installation. It follows the singleton pattern to ensure consistent server management across the application.

MCP Adapter Singleton Registry Pattern

Sources: includes/Core/McpAdapter.php25-69 README.md150-157

McpServer Instance

Each McpServer instance (includes/Core/McpServer.php) represents an independent MCP server with:

Property	Description	Example
server_id	Unique identifier	"mcp-adapter-default-server"
namespace	REST API namespace	"mcp"
route	REST API route	"mcp-adapter-default-server"
name	Human-readable name	"Default MCP Server"
description	Server description	"Default server exposing all abilities"
version	Server version	"1.0.0"
transports	Communication methods	[HttpTransport::class]
error_handler	Error handling strategy	ErrorLogMcpErrorHandler::class
observability_handler	Metrics tracking	NullMcpObservabilityHandler::class
transport_permission_callback	Authentication logic	is_user_logged_in()

Sources: includes/Core/McpAdapter.php89-227 README.md159-167

Multi-Server Architecture

Multiple servers can coexist on a single WordPress site, each with isolated configuration. This enables:

• Different authentication schemes per server (API keys, user roles, etc.)
• Separate ability sets exposed to different clients
• Custom error handling and observability per use case
• Multiple transport methods for different client types

Sources: Diagram 5 from system architecture, README.md449-471

---

Abilities

Abilities are WordPress's standardized way to define executable functionality with inputs, outputs, permissions, and metadata. They are registered using the WordPress Abilities API and form the foundation of all MCP components.

Ability Structure

Each ability registered via wp_register_ability() includes:

Component	Purpose
label	Human-readable name
description	Detailed explanation of functionality
input_schema	JSON Schema defining accepted inputs
output_schema	JSON Schema defining expected outputs
execute_callback	Function that performs the ability's action
permission_callback	Function that checks if execution is allowed
meta.mcp	MCP-specific metadata (type, public flag, etc.)

Ability Registration Components

Sources: README.md296-344 Diagram 3 from system architecture

MCP Metadata

The meta.mcp field controls how abilities are exposed as MCP components:

Sources: README.md296-344

---

MCP Components

MCP defines three types of components that AI agents can interact with: Tools, Resources, and Prompts. WordPress abilities are automatically converted to these components based on their metadata.

Tools

Tools are executable functions that AI agents can call to perform actions. They correspond to abilities with meta.mcp.type = 'tool'.

Tool Component Flow

MCP tools support:

• List operation (tools/list) - Discover available tools
• Call operation (tools/call) - Execute a specific tool
• Schema transformation - Input/output wrapped in MCP-compatible objects

Sources: README.md38 README.md82-86 includes/Handlers/Tools/ Diagram 4 from system architecture

Resources

Resources are read-only data sources that provide contextual information. They correspond to abilities with meta.mcp.type = 'resource'.

Resource Component Flow

MCP resources support:

• List operation (resources/list) - Discover available resources
• Read operation (resources/read) - Retrieve resource content
• URI-based identification - Each resource has a unique URI

Sources: README.md39 README.md88-91 includes/Handlers/Resources/ Diagram 4 from system architecture

Prompts

Prompts are structured templates that guide AI agent interactions. They correspond to abilities with meta.mcp.type = 'prompt'.

Prompt Component Flow

MCP prompts support:

• List operation (prompts/list) - Discover available prompts
• Get operation (prompts/get) - Retrieve prompt template with arguments
• Message generation - Prompts return structured message arrays

Sources: README.md40 README.md93-99 includes/Handlers/Prompts/ Diagram 4 from system architecture

---

Transport Layer

The transport layer handles communication between AI clients and MCP servers. MCP Adapter supports multiple transport protocols that can be used simultaneously.

Transport Types

Transport	Protocol	Use Case	Implementation
HTTP	JSON-RPC 2.0 over HTTP	AI clients, remote access	HttpTransport
STDIO	JSON-RPC 2.0 over stdin/stdout	Local CLI, development	StdioServerBridge

Transport Layer Architecture

Sources: README.md19-23 includes/Transport/HttpTransport.php includes/Cli/StdioServerBridge.php Diagram 1 from system architecture

JSON-RPC 2.0 Protocol

All transport methods use JSON-RPC 2.0 for message formatting:

Sources: README.md360-371 includes/Transport/Infrastructure/JsonRpcResponseBuilder.php

---

Sessions

Sessions track communication state between clients and servers. They are required for all MCP interactions following the initialize → request → request pattern.

Session Lifecycle

Session Management Flow

Session Implementation

Sessions are managed by:

• SessionManager (includes/Transport/Infrastructure/SessionManager.php) - Creates and tracks sessions
• HttpSessionValidator (includes/Transport/Infrastructure/HttpSessionValidator.php) - Validates session headers
• Mcp-Session-Id header - Contains unique session identifier

Sources: includes/Transport/Infrastructure/SessionManager.php includes/Transport/Infrastructure/HttpSessionValidator.php Diagram 2 from system architecture

---

Two-Layer Security Model

MCP Adapter implements two distinct security layers that work together to control access:

Layer 1: Transport Permissions

Transport permissions control access to the entire MCP server endpoint. They are checked before any request processing occurs.

Two-Layer Security Flow

Default transport permission: is_user_logged_in()

Custom transport permission example:

Sources: includes/Core/McpAdapter.php103 README.md34 README.md482-485

Layer 2: Ability Permissions

Ability permissions are granular checks for individual abilities. They are evaluated when an ability is accessed.

Each ability defines its own permission callback:

This allows fine-grained control where:

• Transport layer grants access to the server
• Ability layer grants access to specific functionality

Sources: README.md340-342 Diagram 2 from system architecture

---

Request Processing

Request processing follows a consistent pipeline from client request to response:

Request Processing Pipeline

Sources: includes/Transport/Infrastructure/RequestRouter.php includes/Transport/Infrastructure/HttpRequestHandler.php Diagram 2 from system architecture

---

Handlers

Handlers are domain-specific classes that process MCP method requests. Each handler corresponds to a specific MCP component type.

Handler Mapping

MCP Method	Handler Class	File Path
initialize	InitializeHandler	includes/Handlers/Initialize/
tools/list	ToolsHandler::list_tools()	includes/Handlers/Tools/ToolsHandler.php
tools/call	ToolsHandler::call_tool()	includes/Handlers/Tools/ToolsHandler.php
resources/list	ResourcesHandler::list_resources()	includes/Handlers/Resources/ResourcesHandler.php
resources/read	ResourcesHandler::read_resource()	includes/Handlers/Resources/ResourcesHandler.php
prompts/list	PromptsHandler::list_prompts()	includes/Handlers/Prompts/PromptsHandler.php
prompts/get	PromptsHandler::get_prompt()	includes/Handlers/Prompts/PromptsHandler.php
ping	SystemHandler::ping()	includes/Handlers/System/SystemHandler.php

Handler Pattern

All handlers follow a consistent pattern:

1. Extract parameters from request using HandlerHelperTrait
2. Retrieve component from McpComponentRegistry
3. Validate permissions through ability callbacks
4. Execute operation (list, call, read, get, etc.)
5. Attach metadata for observability
6. Return response or error

Sources: includes/Handlers/ includes/Handlers/HandlerHelperTrait.php Diagram 4 from system architecture

---

Error Handling and Observability

Error Handling

Error handling standardizes error responses across the entire system using the McpErrorFactory (includes/Infrastructure/ErrorHandling/McpErrorFactory.php).

Error Handling System

Standard error codes:

• -32600 - Invalid request
• -32601 - Method not found / Tool not found
• -32602 - Invalid params / Missing parameter
• -32603 - Internal error
• 401/403 - Permission denied

Sources: includes/Infrastructure/ErrorHandling/McpErrorFactory.php README.md24-28 Diagram 6 from system architecture

Observability

Observability tracks system metrics and events through the McpObservabilityHandlerInterface (includes/Infrastructure/Observability/Contracts/McpObservabilityHandlerInterface.php).

Each request generates events with metadata:

• method - MCP method called
• transport - Transport type used
• status - success/failure
• duration_ms - Request duration
• component_type - tool/resource/prompt
• server_id - Which server handled request

Handlers attach metadata using _metadata field, which the router extracts and records.

Sources: includes/Infrastructure/Observability/ README.md29-32 Diagram 6 from system architecture

---

Schemas

Schemas define the structure of inputs and outputs using JSON Schema format. MCP Adapter performs automatic schema transformation to ensure compatibility.

Schema Transformation

WordPress abilities may use flattened schemas (primitive types directly):

MCP requires object schemas, so SchemaTransformer (includes/Domain/Tools/SchemaTransformer.php) automatically wraps them:

Schema Unwrapping

When executing tools, the handler unwraps the schema:

1. Client sends: {"input": "Hello World"}
2. Handler unwraps to: "Hello World"
3. Ability receives the unwrapped value
4. Response is wrapped back for client

Sources: includes/Domain/Tools/SchemaTransformer.php Diagram 3 from system architecture, includes/Handlers/Tools/ToolsHandler.php

---

This page has defined the core concepts used throughout MCP Adapter. For practical application of these concepts, proceed to Getting Started and Basic Examples.