php-mcp/laravel

When a tool handler throws an exception, the Laravel MCP SDK automatically converts it into a valid JSON-RPC error response. This allows you to use standard PHP exceptions (like InvalidArgumentException or RuntimeException) to communicate errors to the MCP client.

#[McpTool(name: 'get_user')]
public function getUser(int $userId): array
{
    $user = User::find($userId);
    
    if (!$user) {
        throw new \InvalidArgumentException("User with ID {$userId} not found");
    }
    
    return $user->toArray();
}

MCP handlers are resolved via Laravel's service container. You can use standard constructor injection to provide services, gateways, or loggers to your tool methods.

class OrderService
{
    public function __construct(
        private PaymentGateway $gateway,
        private NotificationService $notifications,
        private LoggerInterface $logger
    ) {}

    #[McpTool(name: 'process_order')]
    public function processOrder(array $orderData): array
    {
        $this->logger->info('Processing order', $orderData);
        // ...
    }
}

The dedicated HTTP server supports two transport modes via the enable_json_response setting:

• JSON Mode ('enable_json_response' => true): Returns immediate JSON responses. Best for fast-executing tools.
• SSE Mode ('enable_json_response' => false): Uses SSE streaming (default). Ideal for long-running operations and provides enhanced resumability.

Since the dedicated HTTP server is a long-running process, it should be managed by a process manager like Supervisor in production.

[program:laravel-mcp]
process_name=%(program_name)s_%(process_num)02d
command=php /var/www/laravel/artisan mcp:serve --transport=http
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
user=www-data
numprocs=1
redirect_stderr=true
stdout_logfile=/var/log/laravel-mcp.log

Integrated HTTP transport serves MCP through your existing Laravel application routes. This is best for development or applications with existing web servers.

Default Routes:

• GET /mcp - Streamable connection endpoint
• POST /mcp - Message sending endpoint
• DELETE /mcp - Session termination endpoint

Legacy Mode Routes (if enabled):

• GET /mcp/sse - Server-Sent Events endpoint
• POST /mcp/message - Message sending endpoint

For production environments and high-traffic applications, use a dedicated ReactPHP-based HTTP server. This is the recommended approach for production.

# Start dedicated server
php artisan mcp:serve --transport=http

# With custom configuration
php artisan mcp:serve --transport=http \
    --host=0.0.0.0 \
    --port=8091 \
    --path-prefix=mcp_api

Install the package via Composer using the -W flag to ensure dependency compatibility. After installation, publish the configuration file and, if you plan to use database-backed session storage, publish and run the migrations.

# Install the package
composer require php-mcp/laravel:^3.0 -W

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

# Setup database sessions (optional)
php artisan vendor:publish --provider="PhpMcp\Laravel\McpServiceProvider" --tag="mcp-migrations"
php artisan migrate

Because MCP clients send requests to your Laravel application, you must exclude the MCP routes from CSRF protection.

// Laravel 11+
// bootstrap/app.php
->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(except: [
        'mcp',           // For streamable transport (default)
        'mcp/*',         // For legacy transport (if enabled)
    ]);
})

// Laravel 10 and below
// app/Http/Middleware/VerifyCsrfToken.php
protected $except = [
    'mcp',           // For streamable transport (default)
    'mcp/*',         // For legacy transport (if enabled)
];

Version 3.1 introduces several additive features with no breaking changes to existing v3.0 code:

• Closure Handlers: You can now use anonymous functions for tools and resources.
• Custom Input Schemas: Use the ->inputSchema(array $schema) method on blueprints to define complex JSON schemas for tool parameters.

Example of new v3.1 features:

// Closure-based tool
Mcp::tool(function(float $x, float $y): float {
    return $x * $y;
})->name('multiply');

// Custom input schema
Mcp::tool([CalculatorService::class, 'calculate'])
    ->inputSchema([
        'type' => 'object',
        'properties' => [
            'operation' => ['type' => 'string', 'enum' => ['add', 'subtract']]
        ],
        'required' => ['operation']
    ]);

Use STDIO transport for direct client execution, such as with the Cursor IDE or command-line tools.

Warning: When using STDIO, never write to STDOUT in your handlers. STDOUT is reserved for JSON-RPC communication. Use Laravel's logger or STDERR for debugging.

php artisan mcp:serve --transport=stdio

You can customize the integrated HTTP transport via the http_integrated configuration key.

'http_integrated' => [
    'enabled' => true,
    'route_prefix' => 'mcp',           // URL prefix
    'middleware' => ['api'],           // Applied middleware
    'domain' => 'api.example.com',     // Optional domain
    'legacy' => false,                 // Use legacy SSE transport
],