Ehsan Bagherzadegan
Back to articles
8 min read

Laravel's MCP Ecosystem Goes Production-Ready in October 2026

The official laravel/mcp package and three complementary packages (packstub/agents, filament-agents, heihallo/mcp-kit) now give Laravel developers a complete, production-grade stack for building MCP servers, AI agents, and governed tooling.

Laravel's MCP ecosystem took a decisive step forward in October 2026. The official laravel/mcp package reached v1.1.1, and a cluster of complementary packages appeared around it — each solving a different layer of the "AI talks to your app" problem. If you've been waiting for MCP tooling to feel native to Laravel, that moment has arrived.

What changed in October

Four packages landed or updated within days of each other:

Package Version Date Role
laravel/mcp 1.1.1 Oct 21 Official foundation: define MCP servers, tools, resources, prompts
packstub/agents 1.10.0 Oct 13 Agent engine + MCP server sharing one tool list
packstub/filament-agents 1.17.0 Oct 22 Filament v5 panel integration with in-panel chat and MCP
heihallo/mcp-kit 1.31.2 Oct 20 Staff-facing tooling: tokens, audits, preview/confirm, memory, playbooks

All target Laravel 12/13 and PHP 8.3/8.4. The pattern is consistent: laravel/mcp provides the protocol primitives; the others add runtime concerns — agents, UI, governance — that production apps actually need.

The foundation: laravel/mcp

The official package gives you a fluent API to expose your application over the Model Context Protocol. You get three server types:

  • Web servers — HTTP endpoints (typically /mcp/{name}) for remote clients like Claude Desktop or Cursor
  • Local servers — Artisan commands (php artisan mcp:start {name}) for local clients like Claude Code
  • OAuth/Sanctum authentication — built-in middleware support

Defining a server

// app/Mcp/Servers/WeatherServer.php
<?php

namespace App\Mcp\Servers;

use Laravel\Mcp\Server\Attributes\Instructions;
use Laravel\Mcp\Server\Attributes\Name;
use Laravel\Mcp\Server\Attributes\Version;
use Laravel\Mcp\Server;

#[Name('Weather Server')]
#[Version('1.0.0')]
#[Instructions('Provides weather forecasts and historical data.')]
class WeatherServer extends Server
{
    protected array $tools = [
        CurrentWeatherTool::class,
        ForecastTool::class,
    ];

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

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

Registering it

// routes/ai.php
use App\Mcp\Servers\WeatherServer;
use Laravel\Mcp\Facades\Mcp;

Mcp::web('/mcp/weather', WeatherServer::class)
    ->middleware(['throttle:mcp', 'auth:sanctum']);

// Or for local CLI clients:
Mcp::local('weather', WeatherServer::class);

Tools with schemas and DI

// app/Mcp/Tools/CurrentWeatherTool.php
<?php

namespace App\Mcp\Tools;

use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Tool;

#[Description('Fetches the current weather for a location.')]
class CurrentWeatherTool extends Tool
{
    public function __construct(
        protected WeatherRepository $weather,
    ) {}

    public function handle(Request $request): Response
    {
        $forecast = $this->weather->current($request->get('location'));
        
        return Response::structured([
            'temperature' => $forecast->temperature,
            'conditions' => $forecast->conditions,
            'humidity' => $forecast->humidity,
        ]);
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'location' => $schema->string()
                ->description('City or coordinates')
                ->required(),
            'units' => $schema->string()
                ->enum(['celsius', 'fahrenheit'])
                ->default('celsius'),
        ];
    }

    public function outputSchema(JsonSchema $schema): array
    {
        return [
            'temperature' => $schema->number()->required(),
            'conditions' => $schema->string()->required(),
            'humidity' => $schema->integer()->required(),
        ];
    }
}

Annotations like #[IsReadOnly] and #[IsIdempotent] tell clients whether a tool mutates state or can be safely retried — critical for approval flows.

Resources and prompts

Resources expose data (files, docs, database snapshots) at URIs like weather://resources/guidelines. Prompts are reusable prompt templates with typed arguments. Both follow the same fluent pattern.

Consuming external MCP servers

The package also includes a client:

use Laravel\Mcp\Facades\Mcp;

$client = Mcp::client('github'); // registered in a service provider
$issues = $client->callTool('list_issues', [
    'owner' => 'laravel',
    'repo' => 'framework',
]);

This symmetry — your app can be an MCP server and consume other MCP servers — is where things get interesting.

The agent runtime: packstub/agents

laravel/mcp handles the protocol. packstub/agents handles the agent — the LLM loop that decides which tools to call and in what order. Its key insight: the same tool list powers both your in-app agent and external MCP clients.

// app/Agents/Assistant.php
<?php

namespace App\Agents;

use Packstub\Agents\Agent;
use Packstub\Agents\Tools\AgentTool;

class Assistant extends Agent
{
    protected array $tools = [
        CreateOrderTool::class,
        LookupCustomerTool::class,
        SendNotificationTool::class,
    ];
}

Tools extend AgentTool, declare Laravel abilities for authorization, and implement run() + schema():

class CreateOrderTool extends AgentTool
{
    public function abilities(): array
    {
        return ['orders.create'];
    }

    public function run(array $arguments): mixed
    {
        // Your logic here
    }

    public function schema(): array
    {
        return [/* JSON schema */];
    }
}

The agent server (AgentServer) registers these tools for MCP. A single tool definition serves:

  • Your Laravel agent (via laravel/ai)
  • Claude Code / Cursor / Claude Desktop (via MCP over HTTP)
  • Any other MCP-compatible client

Production concerns baked in

Feature What it solves
Queued turns Agent turns persist across requests; long runs don't time out
Approval-gated writes Write tools return proposals; a human must approve before execution
Audit trail Every tool call logged with args, result, approver, timestamp
Budgets Per-user/workspace token and turn limits
Tenancy Workspace-aware; tokens, databases, and provider keys scoped per tenant

This is the gap between "it works in dev" and "it runs in production."

The panel integration: packstub/filament-agents

If you use Filament v5, this package drops an AI assistant into your panel with almost no configuration:

// app/Providers/Filament/AdminPanelProvider.php
use Packstub\FilamentAgents\AgentsPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            AgentsPlugin::make()
                ->agent(Assistant::class)
                ->server(AgentServer::class),
        ]);
}

You get:

  • Slide-over chat (Ctrl/Cmd + J) on every page
  • Context-aware @ mentions — reference resources, tables, records
  • Live Filament tables and charts embedded in answers
  • Approve-in-chat writes — diff preview, one-click confirm
  • Operator pages for AI limits (budgets) and AI turns (audit log with charts)
  • Agent access page to mint scoped MCP tokens for external clients

Resources implement AgentResource + InteractsWithAgent to auto-expose their tables and filters to the agent.

The governance layer: heihallo/mcp-kit

mcp-kit focuses on the human side of MCP: who can do what, and how do you know what happened?

Ability catalogue

Centralize token abilities as strings ('shop:orders:read', 'billing:refunds:write'). Tools, tokens, tests, and the me resource all reference the same catalogue. Permissions are re-checked on every call.

Guarded servers by default

The package refuses to boot if unguarded MCP routes exist. Sanctum auth, per-token throttling, EnsureMcpAccess middleware, and AuditMcpCall activity logging are mandatory.

Preview/confirm for writes

public function run(array $args): mixed
{
    return $this->previewOrExecute(
        description: "Refund order {$args['order_id']} (€{$args['amount']})",
        preview: fn () => ['order_id' => $args['order_id'], 'amount' => $args['amount']],
        execute: fn () => $this->refundService->refund($args['order_id'], $args['amount']),
    );
}

The assistant shows the diff; the user confirms; the audit log records call_id, args, result, and approver.

The me resource and memory

Every assistant gets a me resource describing the current user: role, team, token abilities, work patterns, remembered facts. Users can teach the assistant via remember_about_me (stored in a JSONB column). A 3-question onboarding flow bootstraps this.

Usage learning and gap reports

working_on tracks why a task started and its outcome. {scheme}://usage shows actual tool usage patterns. report_gap lets users file missing capabilities (deduplicated); {scheme}://gaps lists open ones. This turns "the AI can't do X" into a backlog item.

Playbooks as MCP prompts

save_playbook stores reusable workflows exposed as MCP prompts (slash commands in Claude Code). Scoped or shared across the org.

How to choose

If you need… Start with
Pure MCP server for external clients laravel/mcp
In-app agent + external MCP sharing tools packstub/agents
Filament panel with in-panel chat packstub/filament-agents (includes agents)
Staff tooling: tokens, audits, governance heihallo/mcp-kit (composes with laravel/mcp)

They're not mutually exclusive. A typical stack might be:

  1. laravel/mcp for the protocol layer
  2. packstub/agents for the agent runtime
  3. packstub/filament-agents for the admin UI
  4. heihallo/mcp-kit for token governance and audit

Gotchas and practical notes

  • PHP 8.3+ required across the board; packstub/agents needs 8.4+. Plan your runtime accordingly.
  • Sanctum 4 is the auth baseline for web MCP servers. If you're on Passport, laravel/mcp supports OAuth 2.1 via Mcp::oauthRoutes().
  • PostgreSQL preferred for mcp-kit (JSONB columns for memory). MySQL works but loses some query ergonomics.
  • Token scoping matters. Don't mint broad write tokens. Use granular abilities (tool:orders.create, tenant:acme-corp) and let mcp-kit's AgentAccess page enforce it.
  • Approval flows add latency. For high-frequency read tools, mark #[IsReadOnly] and #[IsIdempotent] so clients can skip approval.
  • Test your schemas. The JsonSchema contract validates inputs and outputs. A mismatch between outputSchema() and actual return breaks structured parsing.
  • MCP Inspector (the official debugging tool) works against both web and local servers. Use it during development: npx @modelcontextprotocol/inspector.

The bigger picture

October 2026 marks the point where Laravel's MCP story shifted from "here's the protocol" to "here's the production stack." The official package handles the spec; the ecosystem handles the reality — agents that survive deployments, UIs that non-developers can use, governance that security teams accept.

If you've been prototyping AI integrations with ad-hoc HTTP endpoints or one-off Python scripts, this ecosystem lets you replace them with typed, tested, auditable Laravel code. The protocol is standardized; the tooling is finally Laravel-native.

Sources