Content
# 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.
- 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
```bash
composer require yoosuf/laravel-mcp-server
```
Publish config and migrations:
```bash
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:
```php
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
```bash
php artisan make:mcp-tool CreateInvoiceTool
```
```php
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
```bash
php artisan make:mcp-resource CustomerResource
```
```php
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:
```php
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:
```php
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
```bash
composer lint
composer analyse
composer test
composer coverage
```
## Versioning
This package follows semantic versioning. Current stable line: 1.x.
## License
MIT
