Server Creation and Configuration

This reference guide documents the create_server method and its parameters for creating custom MCP servers. It covers server identity configuration, transport setup, error handling, observability, ability registration, and permission callbacks.

For transport implementation details, see HTTP Transport and STDIO Transport. For error handler implementation, see Error Handling. For observability handler implementation, see Observability System. For creating abilities to register with servers, see Creating Abilities.

The create_server Method

The McpAdapter::create_server() method creates and registers a new MCP server instance with the adapter. Each server has a unique identifier, REST API endpoint, and independent configuration for transports, error handling, observability, and permissions.

Method Signature

Sources: includes/Core/McpAdapter.php89-107

Parameters Reference

Parameter	Type	Required	Description
$server_id	string	Yes	Unique identifier for the server. Used for server lookup and CLI commands.
$server_route_namespace	string	Yes	REST API namespace (e.g., 'my-plugin' for /wp-json/my-plugin/...).
$server_route	string	Yes	REST API route segment (e.g., 'mcp' for /.../mcp).
$server_name	string	Yes	Human-readable server name displayed to clients.
$server_description	string	Yes	Server description shown during initialization.
$server_version	string	Yes	Server version following semver format (e.g., '1.0.0').
$mcp_transports	array	Yes	Array of transport class names implementing McpTransportInterface.
$error_handler	?string	Yes	Class name implementing McpErrorHandlerInterface. null defaults to NullMcpErrorHandler.
$observability_handler	?string	No	Class name implementing McpObservabilityHandlerInterface. null defaults to NullMcpObservabilityHandler.
$tools	array	No	Array of ability names to register as tools (e.g., ['my-plugin/my-ability']).
$resources	array	No	Array of ability names to register as resources.
$prompts	array	No	Array of ability names to register as prompts.
$transport_permission_callback	?callable	No	Custom authentication callback for transport-level access. null defaults to is_user_logged_in().

Return Value

Returns McpAdapter instance on success for method chaining, or WP_Error on failure with error codes:

• invalid_error_handler - Error handler class doesn't exist or doesn't implement required interface
• invalid_observability_handler - Observability handler class doesn't exist or doesn't implement required interface
• invalid_timing - Method called outside mcp_adapter_init action
• duplicate_server_id - Server with this ID already exists

Sources: includes/Core/McpAdapter.php105-227

Server Configuration Process

Timing Requirements

Server creation must occur during the mcp_adapter_init action hook. The adapter validates this timing and returns a WP_Error if called at the wrong time.

Initialization Lifecycle: Server Creation Hook

Sources: includes/Core/McpAdapter.php76-86 includes/Core/McpAdapter.php164-174

Correct Hook Usage

Sources: README.md454-472

Parameter Details

Server Identity Configuration

The first six parameters define the server's identity and REST API endpoint.

Server Identity to Endpoint Mapping

Component	Purpose	Validation
server_id	Unique identifier for get_server() and CLI commands	Must be unique across all servers
server_route_namespace	REST API namespace segment	WordPress REST API validation
server_route	REST API route segment	WordPress REST API validation
server_name	Display name for MCP clients	Shown in initialize response
server_description	Server description	Shown in initialize response
server_version	Semantic version	Shown in initialize response

Duplicate ID Prevention:

The adapter validates server ID uniqueness and triggers _doing_it_wrong() if a duplicate is detected.

Sources: includes/Core/McpAdapter.php176-191 includes/Core/McpAdapter.php194-208

Transport Configuration

The $mcp_transports parameter is an array of transport class names. Multiple transports can be configured simultaneously.

Transport Configuration Pattern

Built-in Transports:

Transport Class	Protocol	Use Case
\WP\MCP\Transport\HttpTransport	HTTP + JSON-RPC 2.0	AI clients, remote connections (MCP 2025-06-18 compliant)

Example: Single Transport

Example: Custom Transport

For custom transport implementation, see Custom Transports.

Sources: README.md462-464 includes/Core/McpServer.php70-77

Error Handler Configuration

The $error_handler parameter specifies the class name for error handling. If null, defaults to NullMcpErrorHandler.

Error Handler Validation and Defaults

Validation Rules:

1. Class must exist (includes/Core/McpAdapter.php114-123)
2. Class must implement McpErrorHandlerInterface (includes/Core/McpAdapter.php125-134)

Built-in Error Handlers:

Handler Class	Behavior	Use Case
NullMcpErrorHandler	Silent (no logging)	Production, high-traffic sites
ErrorLogMcpErrorHandler	Logs to error_log()	Development, debugging

Example Configuration:

Sources: includes/Core/McpAdapter.php108-134

Observability Handler Configuration

The $observability_handler parameter specifies the class name for metrics and event tracking. If null, defaults to NullMcpObservabilityHandler.

Observability Handler Validation and Defaults

Validation Rules:

1. Class must exist (includes/Core/McpAdapter.php142-151)
2. Class must implement McpObservabilityHandlerInterface (includes/Core/McpAdapter.php153-162)

Built-in Observability Handlers:

Handler Class	Behavior	Overhead	Use Case
NullMcpObservabilityHandler	No-op	Zero	Production default
ErrorLogMcpObservabilityHandler	Logs events	Minimal	Development debugging

Example Configuration:

Sources: includes/Core/McpAdapter.php136-162 README.md466-467

Component Registration

The $tools, $resources, and $prompts parameters specify which WordPress abilities to expose through the server.

Ability Registration Flow

Registration Rules:

1. Abilities must be registered via wp_register_ability() before server creation
2. Each ability name is a string in format 'namespace/ability-name'
3. Empty arrays are valid (server with no tools/resources/prompts)
4. Abilities are validated during server initialization

Example: Mixed Component Types

Sources: includes/Core/McpAdapter.php100-102 includes/Core/McpAdapter.php194-208 README.md468

Transport Permission Callback

The $transport_permission_callback parameter provides custom authentication at the transport layer, before any MCP request processing.

Transport Permission Flow

Permission Layers:

Layer	Timing	Default Behavior	Custom Configuration
Transport	Before request routing	is_user_logged_in()	$transport_permission_callback parameter
Ability	During handler execution	Defined in wp_register_ability()	N/A (set per ability)

Example: API Key Authentication

Example: IP Whitelist

For detailed transport permission patterns, see Transport Permissions.

Sources: includes/Core/McpAdapter.php103 includes/Core/McpAdapter.php207 README.md34

Validation and Error Handling

The create_server method performs comprehensive validation and returns WP_Error objects for invalid configurations.

Validation Sequence

Server Creation Validation Flow

Error Code Reference

Error Code	Trigger Condition	Resolution
invalid_error_handler	Error handler class doesn't exist or doesn't implement McpErrorHandlerInterface	Verify class name and interface implementation
invalid_observability_handler	Observability handler class doesn't exist or doesn't implement McpObservabilityHandlerInterface	Verify class name and interface implementation
invalid_timing	create_server() called outside mcp_adapter_init action	Move call inside add_action('mcp_adapter_init', ...)
duplicate_server_id	Server with same $server_id already registered	Use unique server ID or retrieve existing server with get_server()

Sources: includes/Core/McpAdapter.php108-191

Error Handling Example

Sources: includes/Core/McpAdapter.php105-227

Default Server Creation

The adapter automatically creates a default server unless disabled via filter. This server exposes all registered WordPress abilities.

Default Server Creation Flow

Default Server Configuration

Parameter	Value
Server ID	mcp-adapter-default-server
Namespace	mcp
Route	mcp-adapter-default-server
Endpoint	/wp-json/mcp/mcp-adapter-default-server
Transports	HttpTransport
Error Handler	ErrorLogMcpErrorHandler
Observability	NullMcpObservabilityHandler
Built-in Tools	mcp-adapter-discover-abilities, mcp-adapter-get-ability-info, mcp-adapter-execute-ability
Permission	is_user_logged_in()

Disabling Default Server

Default Abilities

The default server includes three core abilities:

Ability	Purpose	Tool Name
DiscoverAbilitiesAbility	List all registered WordPress abilities	mcp-adapter-discover-abilities
GetAbilityInfoAbility	Get detailed information about an ability	mcp-adapter-get-ability-info
ExecuteAbilityAbility	Execute any registered ability	mcp-adapter-execute-ability

Sources: includes/Core/McpAdapter.php254-265 includes/Core/McpAdapter.php272-292 includes/Servers/DefaultServerFactory.php1-60

Complete Configuration Examples

Minimal Server

Production Server

Development Server

Multi-Transport Server

Sources: README.md449-472 includes/Core/McpAdapter.php89-227