php-mcp / server
PHP SDK for building Model Context Protocol (MCP) servers - Create MCP tools, resources, and prompts
Installs: 4 223
Dependents: 7
Suggesters: 0
Security: 0
Stars: 415
Watchers: 9
Forks: 25
Open Issues: 6
Requires
- php: >=8.1
- opis/json-schema: ^2.4
- php-mcp/schema: ^1.0
- phpdocumentor/reflection-docblock: ^5.6
- psr/clock: ^1.0
- psr/container: ^1.0 || ^2.0
- psr/log: ^1.0 || ^2.0 || ^3.0
- psr/simple-cache: ^1.0 || ^2.0 || ^3.0
- react/event-loop: ^1.5
- react/http: ^1.11
- react/promise: ^3.0
- react/stream: ^1.4
- symfony/finder: ^6.4 || ^7.2
Requires (Dev)
- friendsofphp/php-cs-fixer: ^3.75
- mockery/mockery: ^1.6
- pestphp/pest: ^2.36.0|^3.5.0
- react/async: ^4.0
- react/child-process: ^0.6.6
- symfony/var-dumper: ^6.4.11|^7.1.5
Suggests
- react/http: Required for using the ReactPHP HTTP transport handler (^1.11 recommended).
README
A comprehensive PHP SDK for building Model Context Protocol (MCP) servers. Create production-ready MCP servers in PHP with modern architecture, extensive testing, and flexible transport options.
This SDK enables you to expose your PHP application's functionality as standardized MCP Tools, Resources, and Prompts, allowing AI assistants (like Anthropic's Claude, Cursor IDE, OpenAI's ChatGPT, etc.) to interact with your backend using the MCP standard.
๐ Key Features
- ๐๏ธ Modern Architecture: Built with PHP 8.1+ features, PSR standards, and modular design
- ๐ก Multiple Transports: Supports
stdio
,http+sse
, and new streamable HTTP with resumability - ๐ฏ Attribute-Based Definition: Use PHP 8 Attributes (
#[McpTool]
,#[McpResource]
, etc.) for zero-config element registration - ๐ง Flexible Handlers: Support for closures, class methods, static methods, and invokable classes
- ๐ Smart Schema Generation: Automatic JSON schema generation from method signatures with optional
#[Schema]
attribute enhancements - โก Session Management: Advanced session handling with multiple storage backends
- ๐ Event-Driven: ReactPHP-based for high concurrency and non-blocking operations
- ๐ Batch Processing: Full support for JSON-RPC batch requests
- ๐พ Smart Caching: Intelligent caching of discovered elements with manual override precedence
- ๐งช Completion Providers: Built-in support for argument completion in tools and prompts
- ๐ Dependency Injection: Full PSR-11 container support with auto-wiring
- ๐ Comprehensive Testing: Extensive test suite with integration tests for all transports
This package supports the 2025-03-26 version of the Model Context Protocol with backward compatibility.
๐ Requirements
- PHP >= 8.1
- Composer
- For HTTP Transport: An event-driven PHP environment (CLI recommended)
- Extensions:
json
,mbstring
,pcre
(typically enabled by default)
๐ฆ Installation
composer require php-mcp/server
๐ก Laravel Users: Consider using
php-mcp/laravel
for enhanced framework integration, configuration management, and Artisan commands.
โก Quick Start: Stdio Server with Discovery
This example demonstrates the most common usage pattern - a stdio
server using attribute discovery.
1. Define Your MCP Elements
Create src/CalculatorElements.php
:
<?php namespace App; use PhpMcp\Server\Attributes\McpTool; use PhpMcp\Server\Attributes\Schema; class CalculatorElements { /** * Adds two numbers together. * * @param int $a The first number * @param int $b The second number * @return int The sum of the two numbers */ #[McpTool(name: 'add_numbers')] public function add(int $a, int $b): int { return $a + $b; } /** * Calculates power with validation. */ #[McpTool(name: 'calculate_power')] public function power( #[Schema(type: 'number', minimum: 0, maximum: 1000)] float $base, #[Schema(type: 'integer', minimum: 0, maximum: 10)] int $exponent ): float { return pow($base, $exponent); } }
2. Create the Server Script
Create mcp-server.php
:
#!/usr/bin/env php <?php declare(strict_types=1); require_once __DIR__ . '/vendor/autoload.php'; use PhpMcp\Server\Server; use PhpMcp\Server\Transports\StdioServerTransport; try { // Build server configuration $server = Server::make() ->withServerInfo('PHP Calculator Server', '1.0.0') ->build(); // Discover MCP elements via attributes $server->discover( basePath: __DIR__, scanDirs: ['src'] ); // Start listening via stdio transport $transport = new StdioServerTransport(); $server->listen($transport); } catch (\Throwable $e) { fwrite(STDERR, "[CRITICAL ERROR] " . $e->getMessage() . "\n"); exit(1); }
3. Configure Your MCP Client
Add to your client configuration (e.g., .cursor/mcp.json
):
{ "mcpServers": { "php-calculator": { "command": "php", "args": ["/absolute/path/to/your/mcp-server.php"] } } }
4. Test the Server
Your AI assistant can now call:
add_numbers
- Add two integerscalculate_power
- Calculate power with validation constraints
๐๏ธ Architecture Overview
The PHP MCP Server uses a modern, decoupled architecture:
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ MCP Client โโโโโบโ Transport โโโโโบโ Protocol โ
โ (Claude, etc.) โ โ (Stdio/HTTP/SSE) โ โ (JSON-RPC) โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโ
โ
โโโโโโโโโโโโโโโโโโโ โ
โ Session Manager โโโโโโโโโโโโโโโโโค
โ (Multi-backend) โ โ
โโโโโโโโโโโโโโโโโโโ โ
โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ โ
โ Dispatcher โโโโโโ Server Core โโโโโโโโโโโโโโโโค
โ (Method Router) โ โ Configuration โ โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ โ
โ โ
โผ โ
โโโโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโโโโ โ
โ Registry โ โ Elements โโโโโโโโโโโโโโโโ
โ (Element Store)โโโโโบโ (Tools/Resources โ
โโโโโโโโโโโโโโโโโโโ โ Prompts/etc.) โ
โโโโโโโโโโโโโโโโโโโโ
Core Components
ServerBuilder
: Fluent configuration interface (Server::make()->...->build()
)Server
: Central coordinator containing all configured componentsProtocol
: JSON-RPC 2.0 handler bridging transports and core logicSessionManager
: Multi-backend session storage (array, cache, custom)Dispatcher
: Method routing and request processingRegistry
: Element storage with smart caching and precedence rulesElements
: Registered MCP components (Tools, Resources, Prompts, Templates)
Transport Options
StdioServerTransport
: Standard I/O for direct client launchesHttpServerTransport
: HTTP + Server-Sent Events for web integrationStreamableHttpServerTransport
: Enhanced HTTP with resumability and event sourcing
โ๏ธ Server Configuration
Basic Configuration
use PhpMcp\Server\Server; use PhpMcp\Schema\ServerCapabilities; $server = Server::make() ->withServerInfo('My App Server', '2.1.0') ->withCapabilities(ServerCapabilities::make( resources: true, resourcesSubscribe: true, prompts: true, tools: true )) ->withPaginationLimit(100) ->build();
Advanced Configuration with Dependencies
use Psr\Log\Logger; use Psr\SimpleCache\CacheInterface; use Psr\Container\ContainerInterface; $server = Server::make() ->withServerInfo('Production Server', '1.0.0') ->withLogger($myPsrLogger) // PSR-3 Logger ->withCache($myPsrCache) // PSR-16 Cache ->withContainer($myPsrContainer) // PSR-11 Container ->withSession('cache', 7200) // Cache-backed sessions, 2hr TTL ->withPaginationLimit(50) // Limit list responses ->build();
Session Management Options
// In-memory sessions (default, not persistent) ->withSession('array', 3600) // Cache-backed sessions (persistent across restarts) ->withSession('cache', 7200) // Custom session handler (implement SessionHandlerInterface) ->withSessionHandler(new MyCustomSessionHandler(), 1800)
๐ฏ Defining MCP Elements
The server provides two powerful ways to define MCP elements: Attribute-Based Discovery (recommended) and Manual Registration. Both can be combined, with manual registrations taking precedence.
Element Types
- ๐ง Tools: Executable functions/actions (e.g.,
calculate
,send_email
,query_database
) - ๐ Resources: Static content/data (e.g.,
config://settings
,file://readme.txt
) - ๐ Resource Templates: Dynamic resources with URI patterns (e.g.,
user://{id}/profile
) - ๐ฌ Prompts: Conversation starters/templates (e.g.,
summarize
,translate
)
1. ๐ท๏ธ Attribute-Based Discovery (Recommended)
Use PHP 8 attributes to mark methods or invokable classes as MCP elements. The server will discover them via filesystem scanning.
use PhpMcp\Server\Attributes\{McpTool, McpResource, McpResourceTemplate, McpPrompt}; class UserManager { /** * Creates a new user account. */ #[McpTool(name: 'create_user')] public function createUser(string $email, string $password, string $role = 'user'): array { // Create user logic return ['id' => 123, 'email' => $email, 'role' => $role]; } /** * Get user configuration. */ #[McpResource( uri: 'config://user/settings', mimeType: 'application/json' )] public function getUserConfig(): array { return ['theme' => 'dark', 'notifications' => true]; } /** * Get user profile by ID. */ #[McpResourceTemplate( uriTemplate: 'user://{userId}/profile', mimeType: 'application/json' )] public function getUserProfile(string $userId): array { return ['id' => $userId, 'name' => 'John Doe']; } /** * Generate welcome message prompt. */ #[McpPrompt(name: 'welcome_user')] public function welcomeUserPrompt(string $username, string $role): array { return [ ['role' => 'user', 'content' => "Create a welcome message for {$username} with role {$role}"] ]; } }
Discovery Process:
// Build server first $server = Server::make() ->withServerInfo('My App Server', '1.0.0') ->build(); // Then discover elements $server->discover( basePath: __DIR__, scanDirs: ['src/Handlers', 'src/Services'], // Directories to scan excludeDirs: ['src/Tests'], // Directories to skip saveToCache: true // Cache results (default: true) );
Available Attributes:
#[McpTool]
: Executable actions#[McpResource]
: Static content accessible via URI#[McpResourceTemplate]
: Dynamic resources with URI templates#[McpPrompt]
: Conversation templates and prompt generators
2. ๐ง Manual Registration
Register elements programmatically using the ServerBuilder
before calling build()
. Useful for dynamic registration, closures, or when you prefer explicit control.
use App\Handlers\{EmailHandler, ConfigHandler, UserHandler, PromptHandler}; use PhpMcp\Schema\{ToolAnnotations, Annotations}; $server = Server::make() ->withServerInfo('Manual Registration Server', '1.0.0') // Register a tool with handler method ->withTool( [EmailHandler::class, 'sendEmail'], // Handler: [class, method] name: 'send_email', // Tool name (optional) description: 'Send email to user', // Description (optional) annotations: ToolAnnotations::make( // Annotations (optional) title: 'Send Email Tool' ) ) // Register invokable class as tool ->withTool(UserHandler::class) // Handler: Invokable class // Register a closure as tool ->withTool( function(int $a, int $b): int { // Handler: Closure return $a + $b; }, name: 'add_numbers', description: 'Add two numbers together' ) // Register a resource with closure ->withResource( function(): array { // Handler: Closure return ['timestamp' => time(), 'server' => 'php-mcp']; }, uri: 'config://runtime/status', // URI (required) mimeType: 'application/json' // MIME type (optional) ) // Register a resource template ->withResourceTemplate( [UserHandler::class, 'getUserProfile'], uriTemplate: 'user://{userId}/profile' // URI template (required) ) // Register a prompt with closure ->withPrompt( function(string $topic, string $tone = 'professional'): array { return [ ['role' => 'user', 'content' => "Write about {$topic} in a {$tone} tone"] ]; }, name: 'writing_prompt' // Prompt name (optional) ) ->build();
The server supports three flexible handler formats: [ClassName::class, 'methodName']
for class method handlers, InvokableClass::class
for invokable class handlers (classes with __invoke
method), and any PHP callable including closures, static methods like [SomeClass::class, 'staticMethod']
, or function names. Class-based handlers are resolved via the configured PSR-11 container for dependency injection. Manual registrations are never cached and take precedence over discovered elements with the same identifier.
Important
When using closures as handlers, the server generates minimal JSON schemas based only on PHP type hints since there are no docblocks or class context available. For more detailed schemas with validation constraints, descriptions, and formats, you have two options:
- Use the
#[Schema]
attribute for enhanced schema generation - Provide a custom
$inputSchema
parameter when registering tools with->withTool()
๐ Element Precedence & Discovery
Precedence Rules:
- Manual registrations always override discovered/cached elements with the same identifier
- Discovered elements are cached for performance (configurable)
- Cache is automatically invalidated on fresh discovery runs
Discovery Process:
$server->discover( basePath: __DIR__, scanDirs: ['src/Handlers', 'src/Services'], // Scan these directories excludeDirs: ['tests', 'vendor'], // Skip these directories force: false, // Force re-scan (default: false) saveToCache: true // Save to cache (default: true) );
Caching Behavior:
- Only discovered elements are cached (never manual registrations)
- Cache loaded automatically during
build()
if available - Fresh
discover()
calls clear and rebuild cache - Use
force: true
to bypass discovery-already-ran check
๐ Running the Server (Transports)
The server core is transport-agnostic. Choose a transport based on your deployment needs:
1. ๐ Stdio Transport
Best for: Direct client execution, command-line tools, simple deployments
use PhpMcp\Server\Transports\StdioServerTransport; $server = Server::make() ->withServerInfo('Stdio Server', '1.0.0') ->build(); $server->discover(__DIR__, ['src']); // Create stdio transport (uses STDIN/STDOUT by default) $transport = new StdioServerTransport(); // Start listening (blocking call) $server->listen($transport);
Client Configuration:
{ "mcpServers": { "my-php-server": { "command": "php", "args": ["/absolute/path/to/server.php"] } } }
โ ๏ธ Important: When using stdio transport, never write to
STDOUT
in your handlers (useSTDERR
for debugging).STDOUT
is reserved for JSON-RPC communication.
2. ๐ HTTP + Server-Sent Events Transport (Deprecated)
โ ๏ธ Note: This transport is deprecated in the latest MCP protocol version but remains available for backwards compatibility. For new projects, use the StreamableHttpServerTransport which provides enhanced features and better protocol compliance.
Best for: Legacy applications requiring backwards compatibility
use PhpMcp\Server\Transports\HttpServerTransport; $server = Server::make() ->withServerInfo('HTTP Server', '1.0.0') ->withLogger($logger) // Recommended for HTTP ->build(); $server->discover(__DIR__, ['src']); // Create HTTP transport $transport = new HttpServerTransport( host: '127.0.0.1', // MCP protocol prohibits 0.0.0.0 port: 8080, // Port number mcpPathPrefix: 'mcp' // URL prefix (/mcp/sse, /mcp/message) ); $server->listen($transport);
Client Configuration:
{ "mcpServers": { "my-http-server": { "url": "http://localhost:8080/mcp/sse" } } }
Endpoints:
- SSE Connection:
GET /mcp/sse
- Message Sending:
POST /mcp/message?clientId={clientId}
3. ๐ Streamable HTTP Transport (Recommended)
Best for: Production deployments, remote MCP servers, multiple clients, resumable connections
use PhpMcp\Server\Transports\StreamableHttpServerTransport; $server = Server::make() ->withServerInfo('Streamable Server', '1.0.0') ->withLogger($logger) ->withCache($cache) // Required for resumability ->build(); $server->discover(__DIR__, ['src']); // Create streamable transport with resumability $transport = new StreamableHttpServerTransport( host: '127.0.0.1', // MCP protocol prohibits 0.0.0.0 port: 8080, mcpPathPrefix: 'mcp', enableJsonResponse: false // Use SSE streaming (default) ); $server->listen($transport);
JSON Response Mode:
The enableJsonResponse
option controls how responses are delivered:
false
(default): Uses Server-Sent Events (SSE) streams for responses. Best for tools that may take time to process.true
: Returns immediate JSON responses without opening SSE streams. Use this when your tools execute quickly and don't need streaming.
// For fast-executing tools, enable JSON mode $transport = new StreamableHttpServerTransport( host: '127.0.0.1', port: 8080, enableJsonResponse: true // Immediate JSON responses );
Features:
- Resumable connections - clients can reconnect and replay missed events
- Event sourcing - all events are stored for replay
- JSON mode - optional JSON-only responses for fast tools
- Enhanced session management - persistent session state
- Multiple client support - designed for concurrent clients
๐ Schema Generation and Validation
The server automatically generates JSON schemas for tool parameters using a sophisticated priority system that combines PHP type hints, docblock information, and the optional #[Schema]
attribute. These generated schemas are used both for input validation and for providing schema information to MCP clients.
Schema Generation Priority
The server follows this order of precedence when generating schemas:
#[Schema]
attribute withdefinition
- Complete schema override (highest precedence)- Parameter-level
#[Schema]
attribute - Parameter-specific schema enhancements - Method-level
#[Schema]
attribute - Method-wide schema configuration - PHP type hints + docblocks - Automatic inference from code (lowest precedence)
When a definition
is provided in the Schema attribute, all automatic inference is bypassed and the complete definition is used as-is.
Parameter-Level Schema Attributes
use PhpMcp\Server\Attributes\{McpTool, Schema}; #[McpTool(name: 'validate_user')] public function validateUser( #[Schema(format: 'email')] // PHP already knows it's string string $email, #[Schema( pattern: '^[A-Z][a-z]+$', description: 'Capitalized name' )] string $name, #[Schema(minimum: 18, maximum: 120)] // PHP already knows it's integer int $age ): bool { return filter_var($email, FILTER_VALIDATE_EMAIL) !== false; }
Method-Level Schema
/** * Process user data with nested validation. */ #[McpTool(name: 'create_user')] #[Schema( properties: [ 'profile' => [ 'type' => 'object', 'properties' => [ 'name' => ['type' => 'string', 'minLength' => 2], 'age' => ['type' => 'integer', 'minimum' => 18], 'email' => ['type' => 'string', 'format' => 'email'] ], 'required' => ['name', 'email'] ] ], required: ['profile'] )] public function createUser(array $userData): array { // PHP type hint provides base 'array' type // Method-level Schema adds object structure validation return ['id' => 123, 'status' => 'created']; }
Complete Schema Override (Method-Level Only)
#[McpTool(name: 'process_api_request')] #[Schema(definition: [ 'type' => 'object', 'properties' => [ 'endpoint' => ['type' => 'string', 'format' => 'uri'], 'method' => ['type' => 'string', 'enum' => ['GET', 'POST', 'PUT', 'DELETE']], 'headers' => [ 'type' => 'object', 'patternProperties' => [ '^[A-Za-z0-9-]+$' => ['type' => 'string'] ] ] ], 'required' => ['endpoint', 'method'] ])] public function processApiRequest(string $endpoint, string $method, array $headers): array { // PHP type hints are completely ignored when definition is provided // The schema definition above takes full precedence return ['status' => 'processed', 'endpoint' => $endpoint]; }
โ ๏ธ Important: Complete schema definition override should rarely be used. It bypasses all automatic schema inference and requires you to define the entire JSON schema manually. Only use this if you're well-versed with JSON Schema specification and have complex validation requirements that cannot be achieved through the priority system. In most cases, parameter-level and method-level
#[Schema]
attributes provide sufficient flexibility.
๐จ Return Value Formatting
The server automatically formats return values from your handlers into appropriate MCP content types:
Automatic Formatting
// Simple values are auto-wrapped in TextContent public function getString(): string { return "Hello World"; } // โ TextContent public function getNumber(): int { return 42; } // โ TextContent public function getBool(): bool { return true; } // โ TextContent public function getArray(): array { return ['key' => 'value']; } // โ TextContent (JSON) // Null handling public function getNull(): ?string { return null; } // โ TextContent("(null)") public function returnVoid(): void { /* no return */ } // โ Empty content
Advanced Content Types
use PhpMcp\Schema\Content\{TextContent, ImageContent, AudioContent, ResourceContent}; public function getFormattedCode(): TextContent { return TextContent::code('<?php echo "Hello";', 'php'); } public function getMarkdown(): TextContent { return TextContent::make('# Title\n\nContent here'); } public function getImage(): ImageContent { return ImageContent::make( data: base64_encode(file_get_contents('image.png')), mimeType: 'image/png' ); } public function getAudio(): AudioContent { return AudioContent::make( data: base64_encode(file_get_contents('audio.mp3')), mimeType: 'audio/mpeg' ); }
File and Stream Handling
// File objects are automatically read and formatted public function getFileContent(): \SplFileInfo { return new \SplFileInfo('/path/to/file.txt'); // Auto-detects MIME type } // Stream resources are read completely public function getStreamContent() { $stream = fopen('/path/to/data.json', 'r'); return $stream; // Will be read and closed automatically } // Structured resource responses public function getStructuredResource(): array { return [ 'text' => 'File content here', 'mimeType' => 'text/plain' ]; // Or for binary data: // return [ // 'blob' => base64_encode($binaryData), // 'mimeType' => 'application/octet-stream' // ]; }
๐ Batch Processing
The server automatically handles JSON-RPC batch requests:
// Client can send multiple requests in a single HTTP call: [ {"jsonrpc": "2.0", "id": "1", "method": "tools/call", "params": {...}}, {"jsonrpc": "2.0", "method": "notifications/ping"}, // notification {"jsonrpc": "2.0", "id": "2", "method": "tools/call", "params": {...}} ] // Server returns batch response (excluding notifications): [ {"jsonrpc": "2.0", "id": "1", "result": {...}}, {"jsonrpc": "2.0", "id": "2", "result": {...}} ]
๐ง Advanced Features
Completion Providers
Completion providers enable MCP clients to offer auto-completion suggestions in their user interfaces. They are specifically designed for Resource Templates and Prompts to help users discover available options for dynamic parts like template variables or prompt arguments.
Note: Tools and resources can be discovered via standard MCP commands (
tools/list
,resources/list
), so completion providers are not needed for them. Completion providers are used only for resource templates (URI variables) and prompt arguments.
The #[CompletionProvider]
attribute supports three types of completion sources:
1. Custom Provider Classes
For complex completion logic, implement the CompletionProviderInterface
:
use PhpMcp\Server\Contracts\CompletionProviderInterface; use PhpMcp\Server\Contracts\SessionInterface; use PhpMcp\Server\Attributes\{McpResourceTemplate, CompletionProvider}; class UserIdCompletionProvider implements CompletionProviderInterface { public function __construct(private DatabaseService $db) {} public function getCompletions(string $currentValue, SessionInterface $session): array { // Dynamic completion from database return $this->db->searchUsers($currentValue); } } class UserService { #[McpResourceTemplate(uriTemplate: 'user://{userId}/profile')] public function getUserProfile( #[CompletionProvider(provider: UserIdCompletionProvider::class)] // Class string - resolved from container string $userId ): array { return ['id' => $userId, 'name' => 'John Doe']; } }
You can also pass pre-configured provider instances:
class DocumentService { #[McpPrompt(name: 'document_prompt')] public function generatePrompt( #[CompletionProvider(provider: new UserIdCompletionProvider($database))] // Pre-configured instance string $userId, #[CompletionProvider(provider: $this->categoryProvider)] // Instance from property string $category ): array { return [['role' => 'user', 'content' => "Generate document for user {$userId} in {$category}"]]; } }
2. Simple List Completions
For static completion lists, use the values
parameter:
use PhpMcp\Server\Attributes\{McpPrompt, CompletionProvider}; class ContentService { #[McpPrompt(name: 'content_generator')] public function generateContent( #[CompletionProvider(values: ['blog', 'article', 'tutorial', 'guide', 'documentation'])] string $contentType, #[CompletionProvider(values: ['beginner', 'intermediate', 'advanced', 'expert'])] string $difficulty ): array { return [['role' => 'user', 'content' => "Create a {$difficulty} level {$contentType}"]]; } }
3. Enum-Based Completions
For enum classes, use the enum
parameter:
enum Priority: string { case LOW = 'low'; case MEDIUM = 'medium'; case HIGH = 'high'; case CRITICAL = 'critical'; } enum Status // Unit enum (no backing values) { case DRAFT; case PUBLISHED; case ARCHIVED; } class TaskService { #[McpTool(name: 'create_task')] public function createTask( string $title, #[CompletionProvider(enum: Priority::class)] // String-backed enum uses values string $priority, #[CompletionProvider(enum: Status::class)] // Unit enum uses case names string $status ): array { return ['id' => 123, 'title' => $title, 'priority' => $priority, 'status' => $status]; } }
Manual Registration with Completion Providers
$server = Server::make() ->withServerInfo('Completion Demo', '1.0.0') // Using provider class (resolved from container) ->withPrompt( [DocumentHandler::class, 'generateReport'], name: 'document_report' // Completion providers are auto-discovered from method attributes ) // Using closure with inline completion providers ->withPrompt( function( #[CompletionProvider(values: ['json', 'xml', 'csv', 'yaml'])] string $format, #[CompletionProvider(enum: Priority::class)] string $priority ): array { return [['role' => 'user', 'content' => "Export data in {$format} format with {$priority} priority"]]; }, name: 'export_data' ) ->build();
Completion Provider Resolution
The server automatically handles provider resolution:
- Class strings (
MyProvider::class
) โ Resolved from PSR-11 container with dependency injection - Instances (
new MyProvider()
) โ Used directly as-is - Values arrays (
['a', 'b', 'c']
) โ Automatically wrapped inListCompletionProvider
- Enum classes (
MyEnum::class
) โ Automatically wrapped inEnumCompletionProvider
Important: Completion providers only offer suggestions to users in the MCP client interface. Users can still input any value, so always validate parameters in your handlers regardless of completion provider constraints.
Custom Dependency Injection
Your MCP element handlers can use constructor dependency injection to access services like databases, APIs, or other business logic. When handlers have constructor dependencies, you must provide a pre-configured PSR-11 container that contains those dependencies.
By default, the server uses a BasicContainer
- a simple implementation that attempts to auto-wire dependencies by instantiating classes with parameterless constructors. For dependencies that require configuration (like database connections), you can either manually add them to the BasicContainer or use a more advanced PSR-11 container like PHP-DI or Laravel's container.
use Psr\Container\ContainerInterface; class DatabaseService { public function __construct(private \PDO $pdo) {} #[McpTool(name: 'query_users')] public function queryUsers(): array { $stmt = $this->pdo->query('SELECT * FROM users'); return $stmt->fetchAll(); } } // Option 1: Use the basic container and manually add dependencies $basicContainer = new \PhpMcp\Server\Defaults\BasicContainer(); $basicContainer->set(\PDO::class, new \PDO('sqlite::memory:')); // Option 2: Use any PSR-11 compatible container (PHP-DI, Laravel, etc.) $container = new \DI\Container(); $container->set(\PDO::class, new \PDO('mysql:host=localhost;dbname=app', $user, $pass)); $server = Server::make() ->withContainer($basicContainer) // Handlers get dependencies auto-injected ->build();
Resource Subscriptions
use PhpMcp\Schema\ServerCapabilities; $server = Server::make() ->withCapabilities(ServerCapabilities::make( resourcesSubscribe: true, // Enable resource subscriptions prompts: true, tools: true )) ->build(); // In your resource handler, you can notify clients of changes: #[McpResource(uri: 'file://config.json')] public function getConfig(): array { // When config changes, notify subscribers $this->notifyResourceChange('file://config.json'); return ['setting' => 'value']; }
Resumability and Event Store
For production deployments using StreamableHttpServerTransport
, you can implement resumability with event sourcing by providing a custom event store:
use PhpMcp\Server\Contracts\EventStoreInterface; use PhpMcp\Server\Defaults\InMemoryEventStore; use PhpMcp\Server\Transports\StreamableHttpServerTransport; // Use the built-in in-memory event store (for development/testing) $eventStore = new InMemoryEventStore(); // Or implement your own persistent event store class DatabaseEventStore implements EventStoreInterface { public function storeEvent(string $streamId, string $message): string { // Store event in database and return unique event ID return $this->database->insert('events', [ 'stream_id' => $streamId, 'message' => $message, 'created_at' => now() ]); } public function replayEventsAfter(string $lastEventId, callable $sendCallback): void { // Replay events for resumability $events = $this->database->getEventsAfter($lastEventId); foreach ($events as $event) { $sendCallback($event['id'], $event['message']); } } } // Configure transport with event store $transport = new StreamableHttpServerTransport( host: '127.0.0.1', port: 8080, eventStore: new DatabaseEventStore() // Enable resumability );
Custom Session Handlers
Implement custom session storage by creating a class that implements SessionHandlerInterface
:
use PhpMcp\Server\Contracts\SessionHandlerInterface; class DatabaseSessionHandler implements SessionHandlerInterface { public function __construct(private \PDO $db) {} public function read(string $id): string|false { $stmt = $this->db->prepare('SELECT data FROM sessions WHERE id = ?'); $stmt->execute([$id]); $session = $stmt->fetch(\PDO::FETCH_ASSOC); return $session ? $session['data'] : false; } public function write(string $id, string $data): bool { $stmt = $this->db->prepare( 'INSERT OR REPLACE INTO sessions (id, data, updated_at) VALUES (?, ?, ?)' ); return $stmt->execute([$id, $data, time()]); } public function destroy(string $id): bool { $stmt = $this->db->prepare('DELETE FROM sessions WHERE id = ?'); return $stmt->execute([$id]); } public function gc(int $maxLifetime): array { $cutoff = time() - $maxLifetime; $stmt = $this->db->prepare('DELETE FROM sessions WHERE updated_at < ?'); $stmt->execute([$cutoff]); return []; // Return array of cleaned session IDs if needed } } // Use custom session handler $server = Server::make() ->withSessionHandler(new DatabaseSessionHandler(), 3600) ->build();
SSL Context Configuration
For HTTPS deployments of StreamableHttpServerTransport
, configure SSL context options:
$sslContext = [ 'ssl' => [ 'local_cert' => '/path/to/certificate.pem', 'local_pk' => '/path/to/private-key.pem', 'verify_peer' => false, 'allow_self_signed' => true, ] ]; $transport = new StreamableHttpServerTransport( host: '0.0.0.0', port: 8443, sslContext: $sslContext );
SSL Context Reference: For complete SSL context options, see the PHP SSL Context Options documentation.
๐ Error Handling & Debugging
The server provides comprehensive error handling and debugging capabilities:
Exception Handling
Tool handlers can throw any PHP exception when errors occur. The server automatically converts these exceptions into proper JSON-RPC error responses for MCP clients.
#[McpTool(name: 'divide_numbers')] public function divideNumbers(float $dividend, float $divisor): float { if ($divisor === 0.0) { // Any exception with descriptive message will be sent to client throw new \InvalidArgumentException('Division by zero is not allowed'); } return $dividend / $divisor; } #[McpTool(name: 'calculate_factorial')] public function calculateFactorial(int $number): int { if ($number < 0) { throw new \InvalidArgumentException('Factorial is not defined for negative numbers'); } if ($number > 20) { throw new \OverflowException('Number too large, factorial would cause overflow'); } // Implementation continues... return $this->factorial($number); }
The server will convert these exceptions into appropriate JSON-RPC error responses that MCP clients can understand and display to users.
Logging and Debugging
use Psr\Log\LoggerInterface; class DebugAwareHandler { public function __construct(private LoggerInterface $logger) {} #[McpTool(name: 'debug_tool')] public function debugTool(string $data): array { $this->logger->info('Processing debug tool', ['input' => $data]); // For stdio transport, use STDERR for debug output fwrite(STDERR, "Debug: Processing data length: " . strlen($data) . "\n"); return ['processed' => true]; } }
๐ Production Deployment
Since $server->listen()
runs a persistent process, you can deploy it using any strategy that suits your infrastructure needs. The server can be deployed on VPS, cloud instances, containers, or any environment that supports long-running processes.
Here are two popular deployment approaches to consider:
Option 1: VPS with Supervisor + Nginx (Recommended)
Best for: Most production deployments, cost-effective, full control
# 1. Install your application on VPS git clone https://github.com/yourorg/your-mcp-server.git /var/www/mcp-server cd /var/www/mcp-server composer install --no-dev --optimize-autoloader # 2. Install Supervisor sudo apt-get install supervisor # 3. Create Supervisor configuration sudo nano /etc/supervisor/conf.d/mcp-server.conf
Supervisor Configuration:
[program:mcp-server] process_name=%(program_name)s_%(process_num)02d command=php /var/www/mcp-server/server.php --transport=http --host=127.0.0.1 --port=8080 autostart=true autorestart=true stopasgroup=true killasgroup=true user=www-data numprocs=1 redirect_stderr=true stdout_logfile=/var/log/mcp-server.log stdout_logfile_maxbytes=10MB stdout_logfile_backups=3
Nginx Configuration with SSL:
# /etc/nginx/sites-available/mcp-server server { listen 443 ssl http2; listen [::]:443 ssl http2; server_name mcp.yourdomain.com; # SSL configuration ssl_certificate /etc/letsencrypt/live/mcp.yourdomain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/mcp.yourdomain.com/privkey.pem; # Security headers add_header X-Frame-Options "SAMEORIGIN" always; add_header X-Content-Type-Options "nosniff" always; add_header X-XSS-Protection "1; mode=block" always; # MCP Server proxy location / { proxy_http_version 1.1; proxy_set_header Host $http_host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; # Important for SSE connections proxy_buffering off; proxy_cache off; proxy_pass http://127.0.0.1:8080/; } } # Redirect HTTP to HTTPS server { listen 80; listen [::]:80; server_name mcp.yourdomain.com; return 301 https://$server_name$request_uri; }
Start Services:
# Enable and start supervisor sudo supervisorctl reread sudo supervisorctl update sudo supervisorctl start mcp-server:* # Enable and start nginx sudo systemctl enable nginx sudo systemctl restart nginx # Check status sudo supervisorctl status
Client Configuration:
{ "mcpServers": { "my-server": { "url": "https://mcp.yourdomain.com/mcp" } } }
Option 2: Docker Deployment
Best for: Containerized environments, Kubernetes, cloud platforms
Production Dockerfile:
FROM php:8.3-fpm-alpine # Install system dependencies RUN apk --no-cache add \ nginx \ supervisor \ && docker-php-ext-enable opcache # Install PHP extensions for MCP RUN docker-php-ext-install pdo_mysql pdo_sqlite opcache # Create application directory WORKDIR /var/www/mcp # Copy application code COPY . /var/www/mcp COPY docker/nginx.conf /etc/nginx/nginx.conf COPY docker/supervisord.conf /etc/supervisord.conf COPY docker/php.ini /usr/local/etc/php/conf.d/production.ini # Install Composer dependencies RUN composer install --no-dev --optimize-autoloader --no-interaction # Set permissions RUN chown -R www-data:www-data /var/www/mcp # Expose port EXPOSE 80 # Start supervisor CMD ["/usr/bin/supervisord", "-c", "/etc/supervisord.conf"]
docker-compose.yml:
services: mcp-server: build: . ports: - "8080:80" environment: - MCP_ENV=production - MCP_LOG_LEVEL=info volumes: - ./storage:/var/www/mcp/storage restart: unless-stopped healthcheck: test: ["CMD", "curl", "-f", "http://localhost/health"] interval: 30s timeout: 10s retries: 3 # Optional: Add database if needed database: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: secure_password MYSQL_DATABASE: mcp_server volumes: - mysql_data:/var/lib/mysql restart: unless-stopped volumes: mysql_data:
Security Best Practices
- Firewall Configuration:
# Only allow necessary ports sudo ufw allow ssh sudo ufw allow 80 sudo ufw allow 443 sudo ufw deny 8080 # MCP port should not be publicly accessible sudo ufw enable
- SSL/TLS Setup:
# Install Certbot for Let's Encrypt sudo apt install certbot python3-certbot-nginx # Generate SSL certificate sudo certbot --nginx -d mcp.yourdomain.com
๐ Examples & Use Cases
Explore comprehensive examples in the examples/
directory:
Available Examples
01-discovery-stdio-calculator/
- Basic stdio calculator with attribute discovery02-discovery-http-userprofile/
- HTTP server with user profile management03-manual-registration-stdio/
- Manual element registration patterns04-combined-registration-http/
- Combining manual and discovered elements05-stdio-env-variables/
- Environment variable handling06-custom-dependencies-stdio/
- Dependency injection with task management07-complex-tool-schema-http/
- Advanced schema validation examples08-schema-showcase-streamable/
- Comprehensive schema feature showcase
Running Examples
# Navigate to an example directory cd examples/01-discovery-stdio-calculator/ # Make the server executable chmod +x server.php # Run the server (or configure it in your MCP client) ./server.php
๐ง Migration from v2.x
If migrating from version 2.x, note these key changes:
Schema Updates
- Uses
php-mcp/schema
package for DTOs instead of internal classes - Content types moved to
PhpMcp\Schema\Content\*
namespace - Updated method signatures for better type safety
Session Management
- New session management with multiple backends
- Use
->withSession()
or->withSessionHandler()
for configuration - Sessions are now persistent across reconnections (with cache backend)
Transport Changes
- New
StreamableHttpServerTransport
with resumability - Enhanced error handling and event sourcing
- Better batch request processing
๐งช Testing
# Install development dependencies composer install --dev # Run the test suite composer test # Run tests with coverage (requires Xdebug) composer test:coverage # Run code style checks composer lint
๐ค Contributing
We welcome contributions! Please see CONTRIBUTING.md for guidelines.
๐ License
The MIT License (MIT). See LICENSE for details.
๐ Acknowledgments
- Built on the Model Context Protocol specification
- Powered by ReactPHP for async operations
- Uses PSR standards for maximum interoperability