Download the PHP package llm/mcp-server without Composer

PHP MCP Server SDK

A comprehensive PHP SDK for building Model Context Protocol (MCP) servers. Create production-ready MCP servers in PHP with modern architecture, flexible transport options, and comprehensive feature support.

Table of Contents

• Requirements
• Installation
  • Framework Integration
• Quick Start
• Core Concepts
• Transport Options
  • STDIO Transport
  • HTTP Transport with SSE
  • Streamable HTTP Transport
• Working with Tools
  • Basic Tool Registration
  • Advanced Tool with Multiple Content Types
  • Error Handling in Tools
• Working with Resources
• Working with Prompts
• HTTP Middleware
  • Built-in Middleware
    • CORS Middleware
    • Authentication Middleware
  • Custom Middleware
• Advanced Configuration
  • Complete Server Setup
  • Event Store for Resumability
• Common Patterns
  • Handler Factory Pattern
  • Decorator Pattern for Handlers
  • Class-Based Tool Handlers with Schema Mapping
• Ecosystem & Extensions
• Contributing
• License
• Acknowledgments

This SDK implements the MCP 2025-03-26 specification with full backward compatibility support.

Features

• Complete MCP Implementation: Full support for tools, resources, prompts, and logging
• Multiple Transport Options: STDIO, HTTP with SSE, and streamable HTTP transports
• Session Management: Built-in session handling with configurable storage backends
• Event-Driven Architecture: ReactPHP-powered asynchronous operations
• Middleware Support: PSR-15 compatible HTTP middleware system
• Type Safety: Full PHP 8.3+ type declarations and comprehensive error handling
• Extensible Design: Pluggable components with clear interfaces
• Production Ready: Comprehensive logging, error handling, and testing support

What's NOT Included

This SDK focuses on core MCP functionality and intentionally does not include:

• Resource Discovery: Automatic scanning and registration of resources from filesystem or annotations
• Schema Generation: Automatic generation of JSON schemas from PHP code or docblocks
• Request Validation: Built-in validation of incoming requests against defined schemas
• Framework Integration: Direct integration with web frameworks (Laravel, Symfony, etc.)

Why? These features are better implemented as separate packages or framework-specific bridges that can:

• Provide opinionated conventions for specific use cases
• Integrate deeply with framework ecosystems
• Offer different approaches to schema management
• Maintain focused, single-responsibility packages

Requirements

• PHP >= 8.3 (required for advanced type features and performance)
• Extensions: json, mbstring, pcre (typically bundled with PHP)

Installation

Framework Integration

For enhanced developer experience with automatic discovery and validation:

Spiral Framework: Use the spiral/mcp-server bridge

Other Frameworks: Framework-specific bridges are planned. Contributions welcome!

Quick Start

Here's a minimal working example that demonstrates core functionality:

Expected Output: The server will listen on STDIN/STDOUT and respond to MCP requests.

To Test: Save as server.php and run php server.php, then send MCP messages via STDIN.

Core Concepts

Architecture Overview

The SDK follows a layered architecture:

Key Components

• Server: Main orchestrator that binds protocol to transport
• Protocol: Handles MCP message parsing and session management
• Registry: Manages tools, resources, and prompts registration
• Transport: Communication layer (STDIO, HTTP, etc.)
• Session Manager: Handles client sessions and state persistence

Transport Options

STDIO Transport (Recommended for CLI)

Perfect for command-line tools and process-based communication:

Use Cases: CLI tools, subprocess communication, development/testing

HTTP Transport with SSE

For web-based applications with real-time communication:

Use Cases: Web applications, browser-based clients, dashboard integrations

Streamable HTTP Transport

Advanced HTTP transport with JSON response and resumability support:

Use Cases: High-performance applications, stateless deployments, fault-tolerant systems

Working with Tools

Tools are executable functions that AI assistants can call to perform actions.

Basic Tool Registration

Advanced Tool with Multiple Content Types

Error Handling in Tools

Working with Resources

Resources provide read-only access to data that AI assistants can reference.

Static Resources

Dynamic Resource Templates

Resource templates use URI patterns to handle multiple similar resources:

Resource with Completion Providers

Working with Prompts

Prompts provide templated text generation for AI assistants.

Basic Prompt

{$language}\n{$code}\n

Advanced Prompt with Multiple Message Types

Session Management

Custom Session Handlers

Implement the SessionHandlerInterface for custom storage:

Cache-Based Session Storage

HTTP Middleware

Built-in Middleware

CORS Middleware

Authentication Middleware

Custom Middleware

Advanced Configuration

Complete Server Setup

Event Store for Resumability

Performance Optimization

Caching Strategies

Memory Management

Handler Factory Pattern

Decorator Pattern for Handlers

Class-Based Tool Handlers with Schema Mapping

For more advanced use cases with automatic schema generation and request mapping, you can create handlers that work with DTO classes:

Schema Mapper Interface:

Implementation with Valinor and spiral/json-schema-generator:

Usage Example:

Contributing

We welcome contributions! Please follow these guidelines:

Development Setup

Code Style

We follow PSR-12 coding standards:

Testing

License

The MIT License (MIT). See LICENSE for details.

Ecosystem & Extensions

Framework Bridges

Spiral Framework: spiral/mcp-server

• Automatic resource discovery via annotations
• JSON schema generation from PHP classes
• Built-in request/response validation
• Dependency injection integration
• Configuration management

Planned Extensions

• Laravel Bridge: Integration with Laravel's service container and validation
• Symfony Bridge: Symfony bundle with automatic service discovery

Acknowledgments

• Built on the Model Context Protocol specification
• Powered by ReactPHP for async operations
• Uses PSR standards for maximum interoperability