Transport System

Purpose and Scope

The Transport System is the communication layer that handles all incoming requests from MCP clients and routes them to appropriate handlers for processing. It abstracts the underlying protocol (HTTP, STDIO) and provides a unified interface for MCP request processing, session management, and response formatting.

This page covers the overall transport architecture and core components. For specific transport implementations, see HTTP Transport and STDIO Transport. For request routing details, see Request Router. For session handling, see Session Management. For authentication, see Transport Permissions.

Architecture Overview

The transport system consists of three main layers:

1. Transport Interface Layer: Defines contracts for transport implementations
2. Request Processing Layer: Handles JSON-RPC message parsing, routing, and response building
3. Context Management Layer: Encapsulates request state and dependencies

Sources: includes/Transport/HttpTransport.php includes/Transport/Infrastructure/RequestRouter.php includes/Transport/Infrastructure/HttpRequestHandler.php includes/Transport/Infrastructure/McpTransportContext.php

Transport Interfaces

McpTransportInterface

The base transport interface defines the contract that all transport implementations must fulfill:

Interface	Purpose	Key Methods
McpTransportInterface	Base contract for all transports	register()
McpRestTransportInterface	REST API specific transports	register_rest_route(), handle_request(), check_permission()

Sources: includes/Transport/Contracts/McpTransportInterface.php includes/Transport/Contracts/McpRestTransportInterface.php

Request Processing Flow

HTTP Request Lifecycle

Sources: includes/Transport/HttpTransport.php87-129 includes/Transport/Infrastructure/HttpRequestHandler.php46-67 includes/Transport/Infrastructure/RequestRouter.php51-130

Request Processing Stages

Stage	Component	Responsibilities
1. Permission Check	HttpTransport::check_permission()	Validates transport-level permissions
2. Request Parsing	HttpRequestHandler::handle_request()	Routes based on HTTP method (POST/GET/DELETE)
3. JSON-RPC Validation	JsonRpcResponseBuilder::validate_jsonrpc_message()	Validates JSON-RPC 2.0 format
4. Session Validation	HttpSessionValidator::validate_session()	Checks session for non-initialize requests
5. Request Routing	RequestRouter::route_request()	Dispatches to appropriate handler
6. Response Building	JsonRpcResponseBuilder::create_*_response()	Formats JSON-RPC response

Sources: includes/Transport/HttpTransport.php131-176 includes/Transport/Infrastructure/HttpRequestHandler.php77-203

Context Objects

The transport system uses two context objects to encapsulate state and dependencies:

McpTransportContext

Contains all dependencies needed for request processing:

The McpTransportContext is created during server initialization and passed to transport implementations. It provides access to:

• Handler instances: Pre-configured handlers for all MCP methods
• Router: Centralized request routing logic
• Observability: Metrics and event tracking
• Error handling: Logging and error reporting
• Permission callback: Custom transport-level authentication

Sources: includes/Transport/Infrastructure/McpTransportContext.php1-130

HttpRequestContext

Captures HTTP-specific request information:

The HttpRequestContext extracts and normalizes:

• HTTP method (GET/POST/DELETE)
• Request body (parsed JSON)
• Session ID from Mcp-Session-Id header
• Original WP_REST_Request for additional context

Sources: includes/Transport/Infrastructure/HttpRequestContext.php1-60

JSON-RPC Message Processing

JsonRpcResponseBuilder

Handles all JSON-RPC 2.0 message parsing and response formatting:

Key Methods:

Method	Purpose	Returns
validate_jsonrpc_message()	Validates JSON-RPC 2.0 structure	Error array or null
is_batch_request()	Detects batch vs single request	boolean
normalize_messages()	Converts single to array	array of messages
process_messages()	Processes all messages with callback	JSON-RPC response(s)
create_success_response()	Formats success response	{jsonrpc, id, result}
create_error_response()	Formats error response	{jsonrpc, id, error}

Sources: includes/Transport/Infrastructure/JsonRpcResponseBuilder.php1-262

Message Validation

The validate_jsonrpc_message() method enforces JSON-RPC 2.0 requirements:

1. jsonrpc field: Must be "2.0"
2. method field: Required for requests
3. id field: Required for requests (not notifications)
4. params field: Optional, must be object or array

Sources: includes/Transport/Infrastructure/JsonRpcResponseBuilder.php87-128

Transport Registration

Transports are registered during server creation and initialization:

Transport Configuration in Server:

Sources: includes/Core/McpServer.php1-400 includes/Transport/HttpTransport.php64-85

HTTP Methods Support

The HTTP transport implements the MCP 2025-06-18 specification for HTTP-based communication:

HTTP Method	Purpose	Handler	Status
POST	Send MCP requests to server	handle_mcp_request()	✅ Implemented
GET	Subscribe to SSE messages	handle_sse_request()	❌ Not implemented (returns 405)
DELETE	Terminate session	handle_session_termination()	✅ Implemented
OPTIONS	CORS preflight	N/A	❌ Not implemented (returns 405)

Sources: includes/Transport/Infrastructure/HttpRequestHandler.php46-67 tests/Integration/HttpTransportTest.php76-980

Error Handling in Transport Layer

The transport layer integrates with the error handling system at multiple levels:

Error Code to HTTP Status Mapping:

Error Code	HTTP Status	Scenario
-32700 (Parse Error)	400	Invalid JSON
-32600 (Invalid Request)	400	Missing session, malformed JSON-RPC
-32601 (Method Not Found)	404	Unknown MCP method
-32602 (Invalid Params)	400	Invalid session, missing parameters
401 (Unauthorized)	401	Permission denied, authentication required
-32603 (Internal Error)	500	Unexpected exceptions

Sources: includes/Infrastructure/ErrorHandling/McpErrorFactory.php1-400 includes/Transport/Infrastructure/HttpRequestHandler.php77-131

Performance Considerations

Request Processing Optimization

The transport layer uses several strategies to minimize overhead:

1. Early Validation: Permission and session checks happen before expensive operations
2. Batch Processing: Multiple JSON-RPC messages processed in single HTTP request
3. Context Reuse: Handler instances created once per server, not per request
4. Lazy Loading: Handlers only process when router dispatches to them

Observability Integration

Request timing is tracked automatically at the router level:

Metrics Captured:

• Request duration (ms)
• Method name
• Transport type
• Server ID
• Success/error status
• Error codes (on failure)

Sources: includes/Transport/Infrastructure/RequestRouter.php52-130

Transport Integration Points

WordPress REST API Integration

The HTTP transport registers as a WordPress REST API endpoint:

Resulting Endpoint Format:

/wp-json/{namespace}/{route}

For example, the default server endpoint:

/wp-json/mcp/mcp-adapter-default-server

Sources: includes/Transport/HttpTransport.php64-85

Permission Callback Integration

Transports support custom permission callbacks for authentication:

The permission callback receives the WP_REST_Request object and can:

• Return true to grant access
• Return false to deny access (falls back to default)
• Return WP_Error to deny with specific error (falls back to default)
• Throw exception to deny with logging (falls back to default)

Sources: includes/Transport/HttpTransport.php131-176 tests/Integration/HttpTransportTest.php710-802