Download the PHP package php-mcp/laravel without Composer

Laravel MCP Server SDK

A comprehensive Laravel SDK for building Model Context Protocol (MCP) servers with enterprise-grade features and Laravel-native integrations.

This SDK provides a Laravel-optimized wrapper for the powerful php-mcp/server library, enabling you to expose your Laravel application's functionality as standardized MCP Tools, Resources, Prompts, and Resource Templates for AI assistants like Anthropic's Claude, Cursor IDE, OpenAI's ChatGPT, and others.

Key Features

• Laravel-Native Integration: Deep integration with Laravel's service container, configuration, caching, logging, sessions, and Artisan console
• Fluent Element Definition: Define MCP elements with an elegant, Laravel-style API using the Mcp facade
• Attribute-Based Discovery: Use PHP 8 attributes (#[McpTool], #[McpResource], etc.) with automatic discovery and caching
• Advanced Session Management: Laravel-native session handlers (file, database, cache, redis) with automatic garbage collection
• Flexible Transport Options:
  • Integrated HTTP: Serve through Laravel routes with middleware support
  • Dedicated HTTP Server: High-performance standalone ReactPHP server
  • STDIO: Command-line interface for direct client integration
• Streamable Transport: Enhanced HTTP transport with resumability and event sourcing
• Artisan Commands: Commands for serving, discovery, and element management
• Full Test Coverage: Comprehensive test suite ensuring reliability

This package supports the 2025-03-26 version of the Model Context Protocol.

Requirements

• PHP >= 8.1
• Laravel >= 10.0
• Extensions: json, mbstring, pcre (typically enabled by default)

Installation

Install the package via Composer:

Publish the configuration file:

For database session storage, publish the migration:

Configuration

All MCP server settings are managed through config/mcp.php, which contains comprehensive documentation for each option. The configuration covers server identity, capabilities, discovery settings, session management, transport options, caching, and logging. All settings support environment variables for easy deployment management.

Key configuration areas include:

• Server Info: Name, version, and basic identity
• Capabilities: Control which MCP features are enabled (tools, resources, prompts, etc.)
• Discovery: How elements are found and cached from your codebase
• Session Management: Multiple storage backends (file, database, cache, redis) with automatic garbage collection
• Transports: STDIO, integrated HTTP, and dedicated HTTP server options
• Performance: Caching strategies and pagination limits

Review the published config/mcp.php file for detailed documentation of all available options and their environment variable overrides.

Defining MCP Elements

Laravel MCP provides two powerful approaches for defining MCP elements: Manual Registration (using the fluent Mcp facade) and Attribute-Based Discovery (using PHP 8 attributes). 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 accessible via URI (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. Manual Registration

Define your MCP elements using the elegant Mcp facade in routes/mcp.php:

Available Fluent Methods:

For All Elements:

• name(string $name): Override the inferred name
• description(string $description): Set a custom description

For Resources:

• mimeType(string $mimeType): Specify content type
• size(int $size): Set content size in bytes
• annotations(array|Annotations $annotations): Add MCP annotations

Handler Formats:

• [ClassName::class, 'methodName'] - Class method
• InvokableClass::class - Invokable class with __invoke() method

2. Attribute-Based Discovery

Alternatively, you can use PHP 8 attributes to mark your methods or classes as MCP elements, in which case, you don't have to register them in them routes/mcp.php:

Discovery Process:

Elements marked with attributes are automatically discovered when:

• auto_discover is enabled in configuration (default: true)
• You run php artisan mcp:discover manually

Element Precedence

• Manual registrations always override discovered elements with the same identifier
• Discovered elements are cached for performance
• Cache is automatically invalidated on fresh discovery runs

Running the MCP Server

Laravel MCP offers three transport options, each optimized for different deployment scenarios:

1. STDIO Transport

Best for: Direct client execution, Cursor IDE, command-line tools

Client Configuration (Cursor IDE):

⚠️ Important: When using STDIO transport, never write to STDOUT in your handlers (use Laravel's logger or STDERR for debugging). STDOUT is reserved for JSON-RPC communication.

2. Integrated HTTP Transport

Best for: Development, applications with existing web servers, quick setup

The integrated transport serves MCP through your Laravel application's routes:

CSRF Protection Configuration:

Add the MCP routes to your CSRF exclusions:

Laravel 11+:

Laravel 10 and below:

Configuration Options:

Client Configuration:

Server Environment Considerations:

Standard synchronous servers struggle with persistent SSE connections, as each active connection ties up a worker process. This affects both development and production environments.

For Development:

• PHP's built-in server (php artisan serve) won't work - the SSE stream locks the single process
• Laravel Herd (recommended for local development)
• Properly configured Nginx with multiple PHP-FPM workers
• Laravel Octane with Swoole/RoadRunner for async handling
• Dedicated HTTP server (php artisan mcp:serve --transport=http)

For Production:

• Dedicated HTTP server (strongly recommended)
• Laravel Octane with Swoole/RoadRunner
• Properly configured Nginx with sufficient PHP-FPM workers

3. Dedicated HTTP Server (Recommended for Production)

Best for: Production environments, high-traffic applications, multiple concurrent clients

Launch a standalone ReactPHP-based HTTP server:

Configuration Options:

Transport Modes:

• Streamable Mode (legacy: false): Enhanced transport with resumability and event sourcing
• Legacy Mode (legacy: true): Deprecated HTTP+SSE transport.

JSON Response Mode:

• JSON Mode: Returns immediate responses, best for fast-executing tools
• SSE Mode: Streams responses, ideal for long-running operations

Production Deployment:

This creates a long-running process that should be managed with:

• Supervisor (recommended)
• systemd
• Docker containers
• Process managers

Example Supervisor configuration:

For comprehensive production deployment guides, see the php-mcp/server documentation.

Artisan Commands

Laravel MCP includes several Artisan commands for managing your MCP server:

Discovery Command

Discover and cache MCP elements from your codebase:

Output Example:

List Command

View registered MCP elements:

Output Example:

Serve Command

Start the MCP server with various transport options:

Command Options:

• --transport: Choose transport type (stdio or http)
• --host: Host address for HTTP transport
• --port: Port number for HTTP transport
• --path-prefix: URL path prefix for HTTP transport

Dynamic Updates & Events

Laravel MCP integrates with Laravel's event system to provide real-time updates to connected clients:

List Change Events

Notify clients when your available elements change:

Resource Update Events

Notify clients when specific resource content changes:

Advanced Features

Schema Validation

The server automatically generates JSON schemas for tool parameters from PHP type hints and docblocks. You can enhance this with the #[Schema] attribute for advanced validation:

Schema Features:

• Automatic inference from PHP type hints and docblocks
• Parameter-level validation using #[Schema] attributes
• Support for string constraints, numeric ranges, enums, arrays, and objects
• Works with both manual registration and attribute-based discovery

For comprehensive schema documentation and advanced features, see the php-mcp/server Schema documentation.

Completion Providers

Provide auto-completion suggestions for resource template variables and prompt arguments to help users discover available options:

Completion Features:

• Auto-completion for resource template variables and prompt arguments
• Laravel integration - use Eloquent models, collections, etc.
• Session-aware - completions can vary based on user session
• Real-time filtering based on user input

For detailed completion provider documentation, see the php-mcp/server Completion documentation.

Dependency Injection

Your MCP handlers automatically benefit from Laravel's service container:

Exception Handling

Tool handlers can throw exceptions that are automatically converted to proper JSON-RPC error responses:

Logging and Debugging

Configure comprehensive logging for your MCP server:

Create a dedicated log channel in config/logging.php:

Migration Guide

From v2.x to v3.x

Configuration Changes:

Session Configuration:

Transport Updates:

• Default transport changed from sse to streamable
• New CSRF exclusion pattern: mcp instead of mcp/*
• Enhanced session management with automatic garbage collection

Breaking Changes:

• Removed deprecated methods in favor of new registry API
• Updated element registration to use new schema format
• Changed configuration structure for better organization

Examples & Use Cases

E-commerce Integration

Content Management

API Integration

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

License

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

Acknowledgments

• Built on the Model Context Protocol specification
• Powered by php-mcp/server for core MCP functionality
• Leverages Laravel framework features for seamless integration
• Uses ReactPHP for high-performance async operations