STDIO Transport

The STDIO Transport provides process-based communication between MCP clients and WordPress MCP servers through standard input/output streams. This transport method enables local development, command-line testing, and integration with MCP clients that support STDIO connections.

For HTTP-based communication with remote MCP servers, see HTTP Transport. For information about request routing and handler dispatch, see Request Router.

Purpose and Use Cases

STDIO Transport is designed for:

Local Development and Testing

• Direct interaction with MCP servers via command-line
• Rapid testing of tools, resources, and prompts during development
• Debugging MCP server behavior without HTTP overhead

MCP Client Integration

• Claude Desktop and other MCP clients that support STDIO transport
• Process-based server connections for local WordPress sites
• Development environments where HTTP transport is not feasible

Limitations

• Testing Only for Direct CLI: Direct command-line piping is intended for testing purposes only
• Production Use: For production environments, use HTTP Transport with proper authentication
• Local Sites: STDIO transport requires direct file system access to WordPress installation

Sources: README.md19-22 README.md358-372

Architecture Overview

The STDIO transport implementation consists of two primary components that bridge WP-CLI with the MCP server infrastructure:

Sources: README.md75-78 includes/Core/McpAdapter.php295-318

Core Components

McpCommand

The McpCommand class implements WP-CLI commands for managing and serving MCP servers through STDIO transport.

Registration

WP-CLI commands are registered during adapter initialization:

includes/Core/McpAdapter.php295-318

The registration occurs in the register_wp_cli_commands() method, which:

1. Checks if WP-CLI is available via the WP_CLI constant
2. Verifies the WP_CLI class exists
3. Registers the mcp-adapter command namespace with the McpCommand class

Available Commands

The command namespace provides two primary operations:

Command	Purpose	Usage
list	Display all registered MCP servers	wp mcp-adapter list
serve	Start STDIO server for specific server ID	wp mcp-adapter serve --server=<id> --user=<username>

Initialization Context

The adapter initialization differs based on execution context:

includes/Core/McpAdapter.php59-66

• WP-CLI Context: Initializes on the init action at priority 20 to ensure servers are available for commands
• REST API Context: Initializes on rest_api_init at priority 15

Sources: includes/Core/McpAdapter.php295-318 includes/Core/McpAdapter.php59-66 README.md75-78

StdioServerBridge

The StdioServerBridge class provides the actual STDIO transport implementation by:

Input Processing

• Reading JSON-RPC 2.0 requests from standard input (stdin)
• Parsing and validating JSON-RPC message structure
• Extracting method and parameters for routing

Request Routing

• Retrieving the appropriate McpServer instance from the adapter registry
• Routing requests through the server's transport infrastructure
• Delegating to the RequestRouter for handler dispatch

Output Formatting

• Formatting responses as JSON-RPC 2.0 messages
• Writing responses to standard output (stdout)
• Handling error responses with proper JSON-RPC error codes

Session Management

• Creating and validating sessions for STDIO connections
• Managing session state across multiple requests
• Cleaning up sessions on connection termination

Sources: README.md75-78

Request Processing Flow

The following diagram illustrates the complete lifecycle of a STDIO request:

Sources: README.md75-78 includes/Core/McpAdapter.php59-66

Command-Line Testing

STDIO transport enables direct testing of MCP functionality through command-line pipes.

Basic Testing Pattern

Testing Tool Execution

Testing Resources

Command Options

Option	Description	Required
--server=<id>	Server ID to serve	Yes
--user=<username>	WordPress user for authentication	Yes
--path=<path>	WordPress installation path	No (auto-detected)

Sources: README.md358-372

MCP Client Configuration

MCP clients connect to WordPress MCP servers through STDIO by launching the WP-CLI process and communicating through standard streams.

Configuration for Local Sites

The following configuration demonstrates STDIO transport setup for MCP clients like Claude Desktop:

Configuration Parameters

Command Path

• "command": "wp" - The WP-CLI binary must be in the system PATH
• Alternatively, use absolute path: "/usr/local/bin/wp"

Arguments Array

1. --path=<path> - Absolute path to WordPress installation root
2. mcp-adapter - The command namespace
3. serve - The serve subcommand
4. --server=<server-id> - Target MCP server identifier
5. --user=<username> - WordPress user for authentication context

Server Identification

• Default server: mcp-adapter-default-server
• Custom servers: Use the server_id parameter from create_server()

Sources: README.md377-407

STDIO vs HTTP Transport Comparison

The following table summarizes key differences between STDIO and HTTP transports:

Aspect	STDIO Transport	HTTP Transport
Communication	Process stdin/stdout	REST API endpoints
Network	Local process only	Network-capable
Authentication	--user parameter	WordPress authentication
Session Management	Process-scoped	Header-based (Mcp-Session-Id)
Use Case	Local development, testing	Production, remote access
Client Types	MCP clients with STDIO support	Any HTTP client, AI services
Configuration	Command-line arguments	REST API routes
Performance	Lower overhead	HTTP protocol overhead
Scalability	Single process	Multiple concurrent requests
Production Ready	No (testing only)	Yes

Sources: README.md19-22 README.md358-372

Implementation Details

Server Retrieval

The bridge retrieves the target server from the adapter registry:

The server lookup uses the server_id parameter passed to the serve command:

includes/Core/McpAdapter.php236-238

Sources: includes/Core/McpAdapter.php236-238

User Context

The --user parameter establishes the WordPress user context for the entire STDIO session:

Purpose

• Sets the current user for permission checks
• Determines capability-based access control
• Provides user context for ability execution

Authentication Flow

• WP-CLI authenticates the user before processing requests
• User context persists throughout the process lifetime
• All requests in the session execute with this user's capabilities

Permission Validation

• Transport-level permissions check the user context
• Ability-level permissions use the user's capabilities
• Failed permission checks return appropriate JSON-RPC errors

Sources: README.md367-371

Error Handling

STDIO transport uses the same error handling infrastructure as HTTP transport:

Error Sources

• JSON-RPC parsing errors (invalid JSON, malformed requests)
• Server not found errors (invalid --server parameter)
• User authentication errors (invalid --user parameter)
• Method routing errors (unknown MCP methods)
• Handler execution errors (ability failures, permission denials)

Error Response Format

All errors return JSON-RPC 2.0 error responses to stdout:

Error Logging

Errors are logged through the server's configured error handler, just as with HTTP transport. See Error Handling for details on error handler configuration.

Sources: README.md24-29

Integration with WP-Env

For development environments using wp-env, the STDIO transport requires the MCP Adapter plugin to be installed:

Accessing WP-CLI in WP-Env

Path Considerations

When using wp-env, the WordPress installation path is typically /var/www/html inside the container. MCP client configurations should account for this when specifying paths.

Sources: README.md247-261

Limitations and Best Practices

Known Limitations

Process Lifecycle

• Each STDIO connection creates a new PHP process
• Process startup overhead may impact performance
• Not suitable for high-throughput scenarios

Concurrency

• Single request processing per process
• No concurrent request handling
• Multiple clients require multiple processes

Production Use

• STDIO transport is designed for development and testing
• Production deployments should use HTTP transport
• Direct command-line piping is for testing only

Best Practices

Development Workflow

1. Use STDIO transport for rapid tool/resource/prompt testing
2. Validate JSON-RPC requests before testing with AI clients
3. Switch to HTTP transport for integration testing
4. Use HTTP transport with proxy for production deployments

Security Considerations

• The --user parameter determines all permission checks
• Choose appropriate user roles for testing scenarios
• Never expose STDIO processes to untrusted inputs
• Use HTTP transport with proper authentication for production

Performance Optimization

• Minimize process restarts during development
• Use persistent HTTP connections for performance-critical operations
• Cache ability lookups to reduce repeated database queries

Sources: README.md358-372 README.md19-22