PHP MCP Expert Guru

Your specialized agent for building production-ready Model Context Protocol (MCP) servers in PHP 8.2+ using the official PHP SDK, covering server design, tool implementation, and deployment.

When to Use This Agent

Choose PHP MCP Expert Guru when:

• Building MCP servers in PHP using the official PHP SDK
• Implementing MCP tools, resources, and prompts with PHP type safety
• Configuring PHP MCP server transport and middleware
• Integrating PHP MCP servers with existing Laravel or Symfony applications
• Deploying PHP MCP servers for Claude Code or other MCP clients

Consider alternatives when:

• You need MCP servers in TypeScript/Node.js — use the standard MCP tools
• You need MCP servers in Kotlin — use the Kotlin MCP Expert agent
• You need general PHP development — use a PHP developer agent

Quick Start

Copy
# .claude/agents/php-mcp.yml
name: PHP MCP Expert Guru
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: PHP MCP server specialist for building type-safe tools, resources, and prompts with the official PHP SDK

Example invocation:

claude "Create a PHP MCP server that provides tools for managing a MySQL database — list tables, describe columns, and execute read-only queries with parameter binding"

Core Concepts

PHP MCP Server Structure

Copy
<?php
// server.php
require_once __DIR__ . '/vendor/autoload.php';

use ModelContextProtocol\Server\McpServer;
use ModelContextProtocol\Server\Tool;
use ModelContextProtocol\Transport\StdioTransport;

$server = new McpServer(
    name: 'my-php-mcp-server',
    version: '1.0.0'
);

// Register a tool
$server->addTool(
    new Tool(
        name: 'search_products',
        description: 'Search products by name or category',
        inputSchema: [
            'type' => 'object',
            'properties' => [
                'query' => [
                    'type' => 'string',
                    'description' => 'Search query'
                ],
                'category' => [
                    'type' => 'string',
                    'description' => 'Product category filter'
                ]
            ],
            'required' => ['query']
        ],
        handler: function (array $args): array {
            $results = searchProducts($args['query'], $args['category'] ?? null);
            return [['type' => 'text', 'text' => json_encode($results)]];
        }
    )
);

$transport = new StdioTransport();
$server->run($transport);

PHP MCP Components

Component	PHP Implementation	Purpose
Server	McpServer class	Main server instance
Tool	Tool class with handler closure	Callable actions
Resource	Resource class with URI pattern	Readable data
Transport	StdioTransport, SseTransport	Communication layer
Middleware	PSR-15 compatible middleware	Request/response pipeline

Configuration

Parameter	Description	Default
php_version	Minimum PHP version	8.2
framework	Framework integration (none, laravel, symfony)	none
transport	Transport type (stdio, sse)	stdio
type_safety	Type checking strictness (strict, loose)	strict
error_handling	Error reporting mode (exceptions, error-codes)	exceptions

Best Practices

1. Use PHP 8.2+ features for type safety. Leverage readonly properties, enums, intersection types, and named arguments. Strict typing catches parameter mismatches at development time rather than runtime, which is critical for MCP servers where invalid responses break the protocol.

2. Implement input validation using PHP's type system and custom validators. Don't rely solely on JSON Schema validation. Add PHP-level validation in tool handlers that checks business rules, value ranges, and data integrity before processing.

3. Use dependency injection for service integration. When your MCP server needs database connections, HTTP clients, or cache layers, inject them rather than creating global instances. This makes tools testable and keeps the server composable.

4. Handle errors with structured MCP error responses. Don't let PHP exceptions bubble up to raw stack traces. Catch exceptions in tool handlers and return MCP-formatted error responses with descriptive messages and error codes.

5. Test tools independently before integrating with the MCP server. Extract tool logic into service classes that can be unit-tested without the MCP transport layer. Test the handler input/output contract separately from the server protocol.

Common Issues

PHP process runs out of memory on long-running MCP server. PHP is designed for request-response, not long-running processes. Monitor memory usage with memory_get_usage(), unset large variables after use, and consider gc_collect_cycles() in tool handlers that process large datasets.

Composer autoloading conflicts with MCP SDK. If your project uses a framework (Laravel, Symfony), ensure the MCP SDK's autoloader doesn't conflict. Use Composer's autoload configuration to namespace MCP server classes separately from framework code.

stdio transport fails when PHP outputs warnings or notices. PHP warnings and notices print to stdout, corrupting the MCP protocol stream. Set error_reporting(E_ALL) with display_errors = 0 and log_errors = 1 to capture errors in a log file instead of stdout.