yoosuf/laravel-mcp-server

Laravel-native Model Context Protocol server framework for exposing tools, resources, and business operations to AI agents.

Maintainers

Package info

github.com/yoosuf/laravel-mcp-server

pkg:composer/yoosuf/laravel-mcp-server

Transparency log

Statistics

Installs: 0

Dependents: 0

Suggesters: 0

Stars: 0

Open Issues: 0

Security

Advisories: 0

Aikido package health analysis

v1.0.0 2026-07-16 16:43 UTC

Requires

Requires (Dev)

MIT 4c61bb84832b363b3fd2720e31b365c33190bc2a

  • Yoosuf

toolslaravelresourcesAgentaimcp

Published on Packagist.org on 2026-07-16 16:48 UTC

This package is auto-updated.

Last update: 2026-07-17 02:10:53 UTC

README

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.
  • Operational endpoints for dashboard, agent monitoring, and analytics.
  • 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 with auto-discovery service, policy-aware Eloquent authorization, and extended runtime events.
  • Additional auto-discovery depth can continue in minor releases.

Phase 3: Operational Platform

  • Filament dashboard
  • Agent monitoring
  • Analytics

Status:

  • Implemented baseline with MCP operational dashboard, execution monitoring, and analytics endpoints.
  • Optional Filament integration endpoint is included and activates when Filament is installed.

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