Laravel MCP Skill

Comprehensive assistance with Laravel MCP (Model Context Protocol) development. Laravel MCP provides a simple and elegant way for AI clients to interact with your Laravel application through the Model Context Protocol, enabling you to define servers, tools, resources, and prompts for AI-powered interactions.

When to Use This Skill

This skill should be triggered when:

• Building MCP servers for Laravel applications
• Creating AI tools that perform actions in Laravel
• Defining reusable prompts for AI interactions
• Exposing Laravel resources (data/content) to AI clients
• Implementing OAuth 2.1 or Sanctum authentication for MCP
• Registering and configuring MCP routes (web or local)
• Testing MCP servers and tools
• Working with Laravel JSON Schema builder for tool inputs
• Implementing streaming responses or progress notifications
• Building AI-powered Laravel features using MCP

Key Concepts

Core Components

MCP Server: The central communication point that exposes MCP capabilities. Each server has:

• name: Server identifier
• version: Server version
• instructions: Description of the server's purpose
• tools: Array of tool classes
• resources: Array of resource classes
• prompts: Array of prompt classes

Tools: Enable AI clients to perform actions. Tools can:

• Define input schemas using Laravel's JSON Schema builder
• Validate arguments with Laravel validation rules
• Support dependency injection
• Return single or multiple responses
• Stream responses using generators
• Use annotations like #[IsReadOnly] and #[IsIdempotent]

Prompts: Reusable prompt templates that provide a standardized way to structure common queries with argument definitions and validation.

Resources: Enable your server to expose data and content that AI clients can read, including text and blob responses with customizable MIME types and URIs.

Quick Reference

1. Basic MCP Server Definition

<?php
namespace App\Mcp\Servers;

use Laravel\Mcp\Server;

class WeatherServer extends Server
{
    protected string $name = 'Weather Server';
    protected string $version = '1.0.0';
    protected string $instructions = 'This server provides weather information and forecasts.';

    protected array $tools = [
        // CurrentWeatherTool::class,
    ];

    protected array $resources = [
        // WeatherGuidelinesResource::class,
    ];

    protected array $prompts = [
        // DescribeWeatherPrompt::class,
    ];
}

2. Tool with Input Schema

<?php
namespace App\Mcp\Tools;

use Illuminate\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Tool;

class CurrentWeatherTool extends Tool
{
    protected string $description = 'Fetches the current weather forecast for a specified location.';

    public function handle(Request $request): Response
    {
        $location = $request->get('location');
        // Get weather...
        return Response::text('The weather is...');
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'location' => $schema->string()
                ->description('The location to get the weather for.')
                ->required(),
        ];
    }
}

3. Tool with Validation

public function handle(Request $request): Response
{
    $validated = $request->validate([
        'location' => 'required|string|max:100',
        'units' => 'in:celsius,fahrenheit',
    ], [
        'location.required' => 'You must specify a location.',
        'units.in' => 'You must specify either "celsius" or "fahrenheit".',
    ]);
    // Fetch weather data...
}

4. Tool with Dependency Injection

<?php
namespace App\Mcp\Tools;

use App\Repositories\WeatherRepository;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Tool;

class CurrentWeatherTool extends Tool
{
    public function __construct(
        protected WeatherRepository $weather,
    ) {}

    public function handle(Request $request, WeatherRepository $weather): Response
    {
        $location = $request->get('location');
        $forecast = $weather->getForecastFor($location);
        // ...
    }
}

5. Tool with Annotations

<?php
namespace App\Mcp\Tools;

use Laravel\Mcp\Server\Tools\Annotations\IsIdempotent;
use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
use Laravel\Mcp\Server\Tool;

#[IsIdempotent]
#[IsReadOnly]
class CurrentWeatherTool extends Tool
{
    // ...
}

6. Streaming Tool Response

<?php
namespace App\Mcp\Tools;

use Generator;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Tool;

class CurrentWeatherTool extends Tool
{
    public function handle(Request $request): Generator
    {
        $locations = $request->array('locations');

        foreach ($locations as $index => $location) {
            yield Response::notification('processing/progress', [
                'curr

...