README

A powerful Laravel package to build a Model Context Protocol Server seamlessly

Official Website

English | Português do Brasil | 한국어 | Русский | 简体中文 | 繁體中文 | Polski

Overview

Laravel MCP Server is a powerful package designed to streamline the implementation of Model Context Protocol (MCP) servers in Laravel applications. Unlike most Laravel MCP packages that use Standard Input/Output (stdio) transport, this package utilizes Server-Sent Events (SSE) transport, providing a more secure and controlled integration method.

Why SSE instead of STDIO?

While stdio is straightforward and widely used in MCP implementations, it has significant security implications for enterprise environments:

• Security Risk: STDIO transport potentially exposes internal system details and API specifications
• Data Protection: Organizations need to protect proprietary API endpoints and internal system architecture
• Control: SSE offers better control over the communication channel between LLM clients and your application

By implementing the MCP server with SSE transport, enterprises can:

• Expose only the necessary tools and resources while keeping proprietary API details private
• Maintain control over authentication and authorization processes

Key benefits:

• Seamless and rapid implementation of SSE in existing Laravel projects
• Support for the latest Laravel and PHP versions
• Efficient server communication and real-time data processing
• Enhanced security for enterprise environments

Key Features

• Real-time communication support through Server-Sent Events (SSE) integration
• Implementation of tools and resources compliant with Model Context Protocol specifications
• Adapter-based design architecture with Pub/Sub messaging pattern (starting with Redis, more adapters planned)
• Simple routing and middleware configuration

Requirements

• PHP >=8.2
• Laravel >=10.x

Installation

1. Install the package via Composer:

   composer require opgginc/laravel-mcp-server

2. Publish the configuration file:

   php artisan vendor:publish --provider="OPGG\LaravelMcpServer\LaravelMcpServerServiceProvider"

Basic Usage

Creating and Adding Custom Tools

The package provides convenient Artisan commands to generate new tools:

php artisan make:mcp-tool MyCustomTool

This command:

• Handles various input formats (spaces, hyphens, mixed case)
• Automatically converts the name to proper case format
• Creates a properly structured tool class in app/MCP/Tools
• Offers to automatically register the tool in your configuration

You can also manually create and register tools in config/mcp-server.php:

use OPGG\LaravelMcpServer\Services\ToolService\ToolInterface;

class MyCustomTool implements ToolInterface
{
    // Tool implementation
}

Testing MCP Tools

The package includes a special command for testing your MCP tools without needing a real MCP client:

# Test a specific tool interactively
php artisan mcp:test-tool MyCustomTool

# List all available tools
php artisan mcp:test-tool --list

# Test with specific JSON input
php artisan mcp:test-tool MyCustomTool --input='{"param":"value"}'

This helps you rapidly develop and debug tools by:

• Showing the tool's input schema and validating inputs
• Executing the tool with your provided input
• Displaying formatted results or detailed error information
• Supporting complex input types including objects and arrays

Visualizing MCP Tools with Inspector

You can also use the Model Context Protocol Inspector to visualize and test your MCP tools:

# Run the MCP Inspector without installation
npx @modelcontextprotocol/inspector node build/index.js

This will typically open a web interface at localhost:6274. To test your MCP server:

1. Warning: php artisan serve CANNOT be used with this package because it cannot handle multiple PHP connections simultaneously. Since MCP SSE requires processing multiple connections concurrently, you must use one of these alternatives:

   • Laravel Octane (Easiest option):

     # Install and set up Laravel Octane with FrankenPHP (recommended)
     composer require laravel/octane
     php artisan octane:install --server=frankenphp
     
     # Start the Octane server
     php artisan octane:start

     Important: When installing Laravel Octane, make sure to use FrankenPHP as the server. The package may not work properly with RoadRunner due to compatibility issues with SSE connections. If you can help fix this RoadRunner compatibility issue, please submit a Pull Request - your contribution would be greatly appreciated!

     For details, see the Laravel Octane documentation

   • Production-grade options:

     • Nginx + PHP-FPM
     • Apache + PHP-FPM
     • Custom Docker setup
     • Any web server that properly supports SSE streaming

2. In the Inspector interface, enter your Laravel server's MCP SSE URL (e.g., http://localhost:8000/mcp/sse)

3. Connect and explore available tools visually

The SSE URL follows the pattern: http://[your-laravel-server]/[default_path]/sse where default_path is defined in your config/mcp-server.php file.

Advanced Features

Pub/Sub Architecture with SSE Adapters

The package implements a publish/subscribe (pub/sub) messaging pattern through its adapter system:

1. Publisher (Server): When clients send requests to the /message endpoint, the server processes these requests and publishes responses through the configured adapter.

2. Message Broker (Adapter): The adapter (e.g., Redis) maintains message queues for each client, identified by unique client IDs. This provides a reliable asynchronous communication layer.

3. Subscriber (SSE Connection): Long-lived SSE connections subscribe to messages for their respective clients and deliver them in real-time.

This architecture enables:

• Scalable real-time communication
• Reliable message delivery even during temporary disconnections
• Efficient handling of multiple concurrent client connections
• Potential for distributed server deployments

Redis Adapter Configuration

The default Redis adapter can be configured as follows:

'sse_adapter' => 'redis',
'adapters' => [
    'redis' => [
        'prefix' => 'mcp_sse_',    // Prefix for Redis keys
        'connection' => 'default', // Redis connection from database.php
        'ttl' => 100,              // Message TTL in seconds
    ],
],

Environment Variables

The package supports the following environment variables to allow configuration without modifying the config files:

Example .env Configuration

# Disable MCP server in specific environments
MCP_SERVER_ENABLED=false

# Use a specific Redis connection for MCP
MCP_REDIS_CONNECTION=mcp

License

This project is distributed under the MIT license.