By Indunil Peramuna (Senior Laravel Dev)
As a software engineer, I’ve spent the better part of the last few years talking to AI. We’ve all done it: copy-pasting stack traces, asking for refactor suggestions, and getting into philosophical debates about the best way to handle multi-tenancy. But today, I did something different. I gave the AI the keys to the house, and honestly? It felt like seeing the future for the first time.
I just finished setting up a Model Context Protocol (MCP) server on my Laravel 12 application. This isn't just another API; it’s a standard bridge that allows AI agents (like Cursor, Windsurf, or Antigravity) to browse my application’s logic, execute tools, and manage content programmatically—all while following the security and routing rules I’ve defined in PHP.
Building this was an absolute ride. Here is exactly how I navigated the setup, step-by-step, with all the senior-dev grit and enthusiasm included:
1. The Gateway: Registration
Everything starts in routes/ai.php. This is the new frontier in Laravel 12. Registering a server is as simple as:
Mcp::web('/mcp/blog', BlogContentServer::class)
->middleware(['auth:sanctum']);
Security is paramount. We aren't opening a backdoor; we’re opening a secure, authenticated shipping dock. Using Sanctum ensures that only authorized agents can interact with your logic. It felt incredibly satisfying to see the standard Laravel auth pipeline protecting an AI-centric route.
2. Defining Tools: The “Hands” of the AI
I created a series of Tools: CreateBlogPostTool, UpdateBlogPostTool, and a specialized GetBlogPostTool. Each tool defines its own JSON Schema. This is where my brain had to switch gears. You aren't just writing logic; you’re writing a description of that logic so the AI knows how to use it.
public function schema(JsonSchema $schema): array
{
return [
'id' => $schema->integer()->description('The ID of the post to audit.'),
'meta_description' => $schema->string()->description('The new SEO description.'),
];
}
It’s like writing documentation that the computer actually reads and obeys.
3. The Transport Layer: Stdio vs. HTTP Streaming
This was a major learning moment. When you're local, you use stdio. But when you go remote, you move to HTTP. In Laravel 12, this is a clever hybrid: while standard tool calls use JSON-RPC over HTTP, the protocol leverages SSE (Server-Sent Events) for real-time streaming and progress tracking. It’s not just a simple API; it’s a streamable bridge. Setting up the SSE transport in .vscode/mcp.json felt like configuring a specialized telemetry link.
4. Nginx Tuning for AI Patience
AI thinking takes time. Standard HTTP timeouts are too aggressive for an LLM that might need 30 seconds to analyze a complex piece of architecture. I had to dive into my Nginx config to ensure the bridge didn't collapse mid-thought:
proxy_read_timeout 600s;
proxy_buffering off;
proxy_request_buffering off;
Disabling buffering is key for SSE—it ensures the AI gets the data the moment Laravel sends it. It’s these "in the trenches" optimizations that make the final result so robust.
5. The First Handshake: Pure Magic
The first time I connected the inspector and saw my tools listed—create-blog-post-tool, get-blog-post-tool, delete-tool—I knew I was onto something big. I typed a command to my agent: "Check my last 3 drafts and suggest better slugs."
Watching the AI hit the /mcp/blog endpoint, authenticate via Sanctum, fetch the data, and successfully propose changes via the tools was the most “Aha!” moment I've had in years. It turned the AI from a ChatBot into a Digital Team Member.
The Thrill of Autonomy
Watching the AI “think” through a task is surreal. It fetched the content, analyzed the intent, generated the metadata, and saved it via the tools I wrote. Watching the console logs stream by as the AI executed SQL-bound tools securely across a remote connection was one of those rare moments in tech that feels genuinely magical.
A New Era for Laravel Developers
We are witnessing a shift in how applications are designed. We are no longer just building interfaces for humans. We are building Agentic Interfaces. Our jobs as developers are expanding from simply writing code to designing robust, safe, and efficient systems that AI agents can navigate as easily as we do.
If you haven't tried laravel/mcp yet, dive in. It’s more than just cool tech—it’s the roadmap for how we will build web applications for the next decade. I am genuinely excited to see where this goes.
Written with enthusiasm by Laravel Artisan.