## Getting Started

### Minimal Setup
1. **Installation**:
   ```bash
   composer require laravel/mcp

Publish the MCP configuration and migration:

php artisan vendor:publish --provider="Laravel\MCP\MCPServiceProvider" --tag="mcp-config"
php artisan migrate

Configure MCP: Edit config/mcp.php to define your server's metadata (e.g., name, description, protocolVersion). Example:

'servers' => [
    'primary' => [
        'name' => 'My Laravel App',
        'description' => 'A Laravel-powered MCP server',
        'protocolVersion' => '2025-11-25',
        'icon' => 'https://example.com/icon.png',
    ],
],

Define a Resource: Create a resource using the McpResource macro or trait. Example:

use Laravel\MCP\Resources\Resource;
use Laravel\MCP\Resources\Annotations\Resource as ResourceAnnotation;

#[ResourceAnnotation(
    name: 'user',
    description: 'User profile resource',
    outputSchema: 'user-schema.json'
)]
class UserResource extends Resource
{
    public function toArray($request)
    {
        return [
            'id' => auth()->id(),
            'name' => auth()->user()->name,
        ];
    }
}

Register the Resource: Bind the resource in a service provider or boot method:
```
MCP::resource('users', UserResource::class);
```
Run the MCP Server: Start the MCP server with:
```
php artisan mcp:serve
```
Or integrate it into your existing Laravel routes:
```
MCP::routes();
```
First Use Case: Test the server using the mcp:inspect command:
```
php artisan mcp:inspect
```
This generates an OpenAPI/Swagger spec for your MCP server, which can be shared with AI clients.

Implementation Patterns

Core Workflows

1. Resource Development

Structured Resources: Use #[Resource] annotations to define metadata (name, description, output schema). Example:

#[Resource(
    name: 'invoice',
    description: 'Invoice details',
    outputSchema: 'invoice-schema.json',
    icon: 'https://example.com/invoice-icon.png'
)]
class InvoiceResource extends Resource { ... }

Dynamic Data: Fetch data dynamically in the toArray or toJson methods:

public function toArray($request)
{
    return Invoice::find($request->invoice_id)->toArray();
}

Templates: Use URI templates for dynamic paths (e.g., /invoices/{invoice_id}). Resolve variables in the resource:
```
public function resolve($request, $invoice_id)
{
    return Invoice::findOrFail($invoice_id);
}
```

2. Tool Integration

Define Tools: Register tools for AI clients to interact with your app. Example:

MCP::tool('send_email', function (ToolRequest $request) {
    Mail::to($request->to)->send(new Email($request->subject, $request->body));
    return response()->structured(['status' => 'sent']);
});

Input Validation: Use assertStructuredContent to validate tool inputs:

MCP::tool('update_user', function (ToolRequest $request) {
    MCP::assertStructuredContent($request, [
        'type' => 'object',
        'properties' => [
            'name' => ['type' => 'string'],
            'email' => ['type' => 'string', 'format' => 'email'],
        ],
        'required' => ['name', 'email'],
    ]);
    // Proceed with update logic
});

3. Authentication and Authorization

OAuth Registration: Configure OAuth client registration for AI clients:

MCP::oauthClientRegistration(function (OAuthRegisterRequest $request) {
    $client = Client::create([
        'name' => $request->name,
        'redirect' => $request->redirect_uri,
        'personal_access_client' => true,
    ]);
    return response()->json([
        'client_id' => $client->id,
        'client_secret' => $client->secret,
        'redirect_uri' => $client->redirect,
    ]);
});

Scopes: Define scopes for tools/resources:

MCP::scope('read:invoices', 'Read invoice data');
MCP::scope('write:invoices', 'Create/update invoices');

Role-Based Access: Use roles (e.g., Role::Assistant, Role::User) to gate resources/tools:

#[Resource(
    name: 'admin_dashboard',
    roles: [Role::User]
)]
class AdminDashboardResource extends Resource { ... }

4. Content Types

Structured Content: Return structured data with schemas:

public function toJson($request)
{
    return response()->structured([
        'type' => 'object',
        'properties' => [
            'id' => ['type' => 'string'],
            'name' => ['type' => 'string'],
        ],
    ]);
}

Media Content: Serve images/audio using Laravel Storage:

use Laravel\MCP\Resources\ContentTypes\Image;

#[Resource(
    name: 'profile_picture',
    contentType: Image::class
)]
class ProfilePictureResource extends Resource
{
    public function toResponse($request)
    {
        return response()->file(storage_path('app/public/profile.jpg'));
    }
}

5. Testing

Resource Testing: Use MCP::testResource to validate resources:

public function test_user_resource()
{
    MCP::testResource('users')
        ->assertName('user')
        ->assertOutputSchema('user-schema.json')
        ->assertSee('name');
}

Tool Testing: Test tools with mock requests:

public function test_send_email_tool()
{
    MCP::testTool('send_email')
        ->withInput(['to' => 'user@example.com', 'subject' => 'Test'])
        ->assertStatus(200)
        ->assertStructured(['status' => 'sent']);
}

6. Event Handling

Session Events: Listen for session events (e.g., SessionInitialized):

MCP::onSessionInitialized(function (SessionInitialized $event) {
    \Log::info('New MCP session started', ['session_id' => $event->sessionId]);
});

Tool Execution Events: Track tool usage:

MCP::onToolExecuted(function (ToolExecuted $event) {
    \Log::info('Tool executed', [
        'tool' => $event->tool,
        'input' => $event->input,
    ]);
});

Integration Tips

1. Laravel Ecosystem

Queues: Offload tool execution to queues for async processing:

MCP::tool('process_order', function (ToolRequest $request) {
    ProcessOrderJob::dispatch($request->order_id);
    return response()->structured(['status' => 'queued']);
});

Notifications: Trigger Laravel notifications from tools:

MCP::tool('notify_user', function (ToolRequest $request) {
    Notification::send($request->user, new UserNotification($request->message));
    return response()->structured(['status' => 'sent']);
});

Events: Dispatch Laravel events for tool/resource interactions:

public function toArray($request)
{
    event(new InvoiceRetrieved($this->invoice));
    return $this->invoice->toArray();
}

2. API Integration

REST API Coexistence: Share routes between MCP and REST APIs:

Route::middleware('api')->group(function () {
    MCP::routes(); // MCP routes
    Route::get('/api/v1/users', [UserController::class, 'index']); // REST route
});

Rate Limiting: Apply Laravel rate limiting to MCP tools/resources:

MCP::tool('rate_limited_tool', function (ToolRequest $request) {
    // Tool logic
})->middleware('throttle:10,1');

3. UI Integration

MCP UI App: Serve interactive HTML resources:

#[Resource(
    name: 'dashboard',
    contentType: 'text/html',
    uiApp: true
)]
class DashboardResource extends Resource
{
    public function toResponse($request)
    {
        return view('mcp.dashboard');
    }
}

**Blade Views

Mcp Laravel Package