laravel-mcp-server

Laravel MCP Framework: expose Laravel tools, resources, and business workflows to AI agents using a Laravel-native developer experience.

Turn any Laravel application into an AI-native application in minutes.

Features

• MCP runtime manager with discovery and execution APIs.
• HTTP transport with JSON and streaming endpoint support.
• Built-in Eloquent integration to expose models as MCP resources.
• Tool and resource abstractions with JSON schema generation.
• FormRequest and Validator integration for argument validation.
• Laravel authorization integration for per-tool and per-resource checks.
• Tenant context resolver for multi-tenant SaaS workloads.
• Queue-backed async tool execution.
• Security module with API keys, rate limiting, and execution audit logs.
• Artisan generators and operational diagnostics.
• Extension architecture for marketplace-ready MCP packages.

Documentation

• Architecture: docs/architecture.md
• API reference: docs/api-reference.md
• Tools guide: docs/tools.md
• Resources guide: docs/resources.md
• Security guide: docs/security.md
• Testing guide: docs/testing.md
• Use cases: docs/use-cases.md
• End-to-end use cases: docs/use-cases-e2e.md
• Product roadmap: docs/roadmap.md
• Contribution guide: docs/contributing.md

Product Positioning

laravel-mcp-server is positioned as the Laravel MCP Framework for teams that want to make existing Laravel applications AI-native without rewriting core domain logic.

It maps naturally to Laravel patterns:

• Laravel routes -> MCP endpoints
• Laravel controllers/services -> MCP tools
• Laravel resources/models -> MCP resources
• Laravel jobs -> async MCP execution

This lets teams keep business logic in familiar Laravel structures while exposing capabilities to AI agents through MCP.

Roadmap

Phase 1: Foundation

• MCP protocol implementation
• Tools
• Resources
• Authentication

Status:

• Implemented in current release.

Phase 2: Laravel-native Intelligence

• Eloquent auto discovery
• Policies integration
• Events

Status:

• Implemented baseline support (Eloquent helpers, policy hooks, runtime events).
• Additional auto-discovery depth can continue in minor releases.

Phase 3: Operational Platform

• Filament dashboard
• Agent monitoring
• Analytics

Status:

• Planned.

Phase 4: Publish-ready maturity

• Laravel 11/12/13 support
• Pest tests
• GitHub Actions
• PHPStan level 9
• Documentation website
• Demo application
• Docker environment
• Packagist release

Status:

• In progress.
• Current release includes Laravel 11/12 support, Pest tests, GitHub Actions, and Packagist publication path.
• Laravel 13, PHPStan level 9, documentation website, demo app, and Docker environment are planned upgrades.

Package Design Philosophy

This package follows Laravel package development guidance:

• clear service provider bootstrapping
• publishable config and migrations
• framework-aligned testing setup
• clean package structure with contracts and abstractions

Building it as a standalone package from the beginning ensures maintainability, upgrade safety, and reusable adoption across multiple Laravel applications.

Requirements

• PHP 8.2+
• Laravel 11.x or 12.x

Installation

composer require yoosuf/laravel-mcp-server

Publish config and migrations:

php artisan vendor:publish --tag=mcp-config
php artisan vendor:publish --tag=mcp-migrations
php artisan migrate

Quick Start

Register classes in a service provider:

use Yoosuf\LaravelMcpServer\Facades\MCP;

MCP::resource(\App\MCP\Resources\CustomerResource::class);
MCP::tool(\App\MCP\Tools\CreateInvoiceTool::class);
MCP::async(\App\MCP\Tools\GenerateReportTool::class);

MCP::tenantResolver(fn () => tenant());

Discover MCP metadata:

• GET /.well-known/mcp/discovery

Execute over HTTP:

• POST /.well-known/mcp/execute
• POST /.well-known/mcp/stream

Creating a Tool

php artisan make:mcp-tool CreateInvoiceTool

class CreateInvoiceTool extends MCPTool
{
    public function name(): string { return 'create_invoice'; }

    public function description(): string { return 'Creates customer invoice'; }

    public function schema(): array
    {
        return [
            'customer_id' => 'integer',
            'items' => 'array',
        ];
    }

    public function rules(): array
    {
        return [
            'customer_id' => ['required', 'integer'],
            'items' => ['required', 'array'],
        ];
    }

    public function authorize(McpContext $context, array $arguments): bool
    {
        return $context->user?->can('create', \App\Models\Invoice::class) ?? false;
    }

    public function execute(array $arguments, McpContext $context): mixed
    {
        // Implement domain operation
    }
}

Creating a Resource

php artisan make:mcp-resource CustomerResource

class CustomerResource extends MCPResource
{
    public function name(): string { return 'customers'; }

    public function schema(): array
    {
        return [
            'id' => 'integer',
            'name' => 'string',
            'email' => 'string',
        ];
    }

    public function actions(): array
    {
        return ['list', 'find'];
    }
}

Security

• Laravel guards (Sanctum, Passport-compatible architecture).
• API key auth via mcp_api_keys table and X-MCP-Key header.
• Rate limiting for MCP execution endpoints.
• Per-execution audit logs in mcp_executions and mcp_logs.

Multi Tenancy

Set a global tenant resolver:

MCP::tenantResolver(function () {
    return tenant();
});

Every execution context includes user_id, tenant_id, permissions, and roles.

Artisan Commands

• php artisan make:mcp-tool
• php artisan make:mcp-resource
• php artisan make:mcp-server
• php artisan mcp:list
• php artisan mcp:test
• php artisan mcp:cli
• php artisan mcp:stdio

Eloquent Integration

Use the built-in trait on your model:

use Yoosuf\LaravelMcpServer\Eloquent\Support\HasMcpExposure;

class Customer extends Model
{
    use HasMcpExposure;
}

Customer::mcp()->allow(['list', 'search', 'find']);

Use Cases

• CRM assistants that read customer data and trigger workflows.
• Invoice automation with async report generation.
• Tenant-safe SaaS operations for subscriptions and billing.
• Support desk actions with policy-controlled write operations.
• Internal compliance workflows with audit-friendly execution logs.

See detailed implementation patterns in docs/use-cases.md. For complete operational walkthroughs, see docs/use-cases-e2e.md.

Testing and Quality

composer lint
composer analyse
composer test
composer coverage

Versioning

This package follows semantic versioning. Current stable line: 1.x.

License

MIT