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:

composer require php-mcp/laravel:^3.0 -W

Publish the configuration file:

php artisan vendor:publish --provider="PhpMcp\Laravel\McpServiceProvider" --tag="mcp-config"

For database session storage, publish the migration:

php artisan vendor:publish --provider="PhpMcp\Laravel\McpServiceProvider" --tag="mcp-migrations"
php artisan migrate

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:

<?php
use PhpMcp\Laravel\Facades\Mcp;

use App\Services\{CalculatorService, UserService, EmailService, PromptService};
// Register a simple tool

Mcp::tool([CalculatorService::class, 'add'])

    ->name('add_numbers')

    ->description('Add two numbers together');
// Register an invokable class as a tool

Mcp::tool(EmailService::class)

    ->description('Send emails to users');
// Register a closure as a tool with custom input schema

Mcp::tool(function(float $x, float $y): float {

    return $x  $y;

})

    ->name('multiply')

    ->description('Multiply two numbers')

    ->inputSchema([

        'type' => 'object',

        'properties' => [

            'x' => ['type' => 'number', 'description' => 'First number'],

            'y' => ['type' => 'number', 'description' => 'Second number'],

        ],

        'required' => ['x', 'y'],

    ]);

// Register a resource with metadata

Mcp::resource('config://app/settings', [UserService::class, 'getAppSettings'])

    ->name('app_settings')

    ->description('Application configuration settings')

    ->mimeType('application/json')

    ->size(1024);
// Register a closure as a resource

Mcp::resource('system://time', function(): string {

    return now()->toISOString();

})

    ->name('current_time')

    ->description('Get current server time')

    ->mimeType('text/plain');
// Register a resource template for dynamic content

Mcp::resourceTemplate('user://{userId}/profile', [UserService::class, 'getUserProfile'])

    ->name('user_profile')

    ->description('Get user profile by ID')

    ->mimeType('application/json');
// Register a closure as a resource template

Mcp::resourceTemplate('file://{path}', function(string $path): string {

    if (!file_exists($path) || !is_readable($path)) {

        throw new \InvalidArgumentException("File not found or not readable: {$path}");

    }

    return file_get_contents($path);

})

    ->name('file_reader')

    ->description('Read file contents by path')

    ->mimeType('text/plain');
// Register a prompt generator

Mcp::prompt([PromptService::class, 'generateWelcome'])

    ->name('welcome_user')

    ->description('Generate a personalized welcome message');
// Register a closure as a prompt

Mcp::prompt(function(string $topic, string $tone = 'professional'): array {

    return [

        [

            'role' => 'user',

            'content' => "Write a {$tone} summary about {$topic}. Make it informative and engaging."

        ]

    ];

})

    ->name('topic_summary')

    ->description('Generate topic summary prompts');

<?php
namespace App\Services;
use PhpMcp\Server\Attributes\{McpTool, McpResource, McpResourceTemplate, McpPrompt};
class UserService

{

    /

      Create 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,

            'created_at' => now()->toISOString(),

        ];

    }

/

      Get application configuration.

     /

    #[McpResource(

        uri: 'config://app/settings',

        mimeType: 'application/json'

    )]

    public function getAppSettings(): array

    {

        return [

            'theme' => config('app.theme', 'light'),

            'timezone' => config('app.timezone'),

            'features' => config('app.features', []),

        ];

    }

/

      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',

            'email' => 'john@example.com',

            'profile' => [

                'bio' => 'Software developer',

                'location' => 'New York',

            ],

        ];

    }

/

      Generate a welcome message prompt.

     */

    #[McpPrompt(name: 'welcome_user')]

    public function generateWelcome(string $username, string $role = 'user'): array

    {

        return [

            [

                'role' => 'user',

                'content' => "Create a personalized welcome message for {$username} with role {$role}. Be warm and professional."

            ]

        ];

    }

}

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

```bash