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:
laravel/mcpfor the protocol layerpackstub/agentsfor the agent runtimepackstub/filament-agentsfor the admin UIheihallo/mcp-kitfor token governance and audit
Gotchas and practical notes
- PHP 8.3+ required across the board;
packstub/agentsneeds 8.4+. Plan your runtime accordingly. - Sanctum 4 is the auth baseline for web MCP servers. If you're on Passport,
laravel/mcpsupports OAuth 2.1 viaMcp::oauthRoutes(). - PostgreSQL preferred for
mcp-kit(JSONB columns for memory). MySQL works but loses some query ergonomics. - Token scoping matters. Don't mint broad
writetokens. Use granular abilities (tool:orders.create,tenant:acme-corp) and letmcp-kit'sAgentAccesspage enforce it. - Approval flows add latency. For high-frequency read tools, mark
#[IsReadOnly]and#[IsIdempotent]so clients can skip approval. - Test your schemas. The
JsonSchemacontract validates inputs and outputs. A mismatch betweenoutputSchema()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
- Laravel MCP Documentation
- laravel/mcp on GitHub
- packstub/agents on GitHub
- packstub/filament-agents on GitHub
- heihallo/mcp-kit on Packagist
- Laravel News: Laravel MCP Ecosystem October 2026 (search results for October 2026 MCP packages)