Laravel MCP: A Complete Guide

Your AI coding agent writes better code when it has real context about your application. Laravel MCP is the framework's answer to that problem, and the foundation for exposing your app's capabilities to any AI client, from coding tools to ChatGPT to Claude.

Without it, your agent guesses column names, invents routes, and searches documentation that may not match your installed packages. With it, you give AI tools structured access to your app's schema, routes, data, and actions. The same server that helps you build faster becomes a new entry point for your users.

This guide covers how you can get started with laravel/mcp, the package you use to build an MCP server and expose your application's capabilities to external AI clients.

What MCP Does for Your Laravel App

MCP stands for Model Context Protocol. Anthropic introduced it as an open standard in November 2024 to define how AI agents communicate with external tools and data sources.

Before MCP, every AI tool that wanted to connect to your data built its own integration. MCP replaces all of those with a single standard. Any MCP-compatible client, such as Claude, Cursor, or GitHub Copilot, can connect to any MCP-compatible server, including one you build in Laravel.

The practical result is that your agent stops guessing and starts querying. By using the Laravel MCP to build an MCP server and connecting it to your app, your agent can tell you which columns exist in your orders table, run a database query to verify results before writing a migration, and look up the exact Filament version you have installed rather than guessing from a generic overview.

The Laravel MCP server exposes three types of capabilities:

• Tools: callable functions your agent can invoke, such as querying orders or creating invoices
• Resources: readable data exposed by URI, such as database records or config files
• Prompts: reusable conversation templates for consistent agent behavior

It also powers Laravel Boost, your AI sidekick for fast, reliable AI-assisted Laravel development.

When MCP Is the Right Call

If you are a developer working alone, you might wonder whether MCP is overkill. For pure context-gathering, sometimes it is. A gh CLI call or a quick curl to your own API can give an agent what it needs without the extra layer. If all you want is to pipe some JSON into a prompt, you do not need a protocol for that.

MCP starts earning its keep when the consumer of your app is not you. Non-technical users cannot reach for a CLI or compose an API request. They connect to an app, authenticate once, and start asking questions. That is the gap MCP fills. It turns your Laravel application into something any AI client can talk to without requiring the user to understand HTTP verbs or terminal commands.

It also matters at scale. A solo developer can wire up bespoke integrations for a handful of tools. A team of 50 cannot. When you have dozens of engineers, each using different AI clients, a single MCP server gives every client the same structured access to your application. That is why MCP is showing up fastest in enterprise environments: companies with real security requirements, centralized authentication, and too many seats to manage one-off integrations for each tool.

So the question is not "MCP or CLI" but "who is connecting, and how many of them?" If the answer is just you, start with the simplest thing that works. If the answer is your team or your users, MCP gives you a single surface to build and secure, rather than many.

Building an MCP Server: Installing Laravel MCP

Install the package and publish the routes file:

1composer require laravel/mcp
2php artisan vendor:publish --tag=ai-routes

This creates routes/ai.php. Register your server there using Mcp::web() for HTTP clients or Mcp::local() for Artisan-based local tools:

1// routes/ai.php
2use App\Mcp\Servers\OrderServer;
3use Laravel\Mcp\Facades\Mcp;
4 
5// remote ai clients connect via http post
6Mcp::web('/mcp/orders', OrderServer::class);
7 
8// local cli agents connect via stdio
9Mcp::local('orders', OrderServer::class);

Generate the server class:

1php artisan make:mcp-server OrderServer

A server class is a container for your tools, resources, and prompts. PHP attributes define its metadata:

 1// app/mcp/servers/order-server.php
 2use Laravel\Mcp\Server\Attributes\Instructions;
 3use Laravel\Mcp\Server\Attributes\Name;
 4use Laravel\Mcp\Server;
 5 
 6#[Name('Order Server')]
 7#[Instructions('This server manages customer orders.')]
 8class OrderServer extends Server
 9{
10    protected array $tools = [];
11    protected array $resources = [];
12    protected array $prompts = [];
13}

Defining Your First Tool

Tools are the primary capability you expose. A tool has two methods: schema() defines the input the agent must provide, and handle() runs the action and returns a response.

Generate a tool:

1php artisan make:mcp-tool GetOpenOrdersTool

 1// app/mcp/tools/get-open-orders-tool.php
 2use Illuminate\Contracts\JsonSchema\JsonSchema;
 3use Laravel\Mcp\Request;
 4use Laravel\Mcp\Response;
 5use Laravel\Mcp\Server\Attributes\Description;
 6use Laravel\Mcp\Server\Tool;
 7 
 8#[Description('Returns all open orders for a given customer ID.')]
 9class GetOpenOrdersTool extends Tool
10{
11    public function schema(JsonSchema $schema): array
12    {
13        return [
14            'customer_id' => $schema->integer()
15                ->description('The ID of the customer.')
16                ->required(),
17        ];
18    }
19 
20    public function handle(Request $request): Response
21    {
22        $validated = $request->validate([
23            'customer_id' => 'required|integer|exists:customers,id',
24        ]);
25 
26        $orders = Order::where('customer_id', $validated['customer_id'])
27            ->where('status', 'open')
28            ->get();
29 
30        return Response::structured($orders->toArray());
31    }
32}

Register it on your server:

1protected array $tools = [
2    GetOpenOrdersTool::class,
3];

If your tool needs a service from the container, add it to the handle method signature. Laravel resolves it automatically:

1public function handle(Request $request, OrderRepository $orders): Response
2{
3    $customerId = $request->get('customer_id');
4    return Response::structured($orders->getOpen($customerId));
5}

Authentication

For MCP servers you expose to remote clients, protect the route with middleware. The package supports OAuth 2.1 through Laravel Passport and token auth through Laravel Sanctum:

1Mcp::web('/mcp/orders', OrderServer::class)
2    ->middleware(['auth:sanctum']);

For OAuth 2.1, call Mcp::oauthRoutes() in routes/ai.php and publish the auth views:

1php artisan vendor:publish --tag=mcp-views

We wrote an in-depth post about MCP authentication and security best practices here.

Testing with the MCP Inspector

Before connecting a real client, use the built-in MCP inspector. It connects to your server, lets you call each tool, and shows the raw request and response for every interaction. It is the fastest way to confirm your schemas are correct and that your responses parse as expected.

Resources and Prompts

After tools, resources, and prompts are the natural next step. Resources expose readable data by URI, such as orders://reports/monthly. Prompts define reusable conversation templates for consistent agent behavior across clients.

Generate both with:

1php artisan make:mcp-resource MonthlyOrderReport
2php artisan make:mcp-prompt OrderSummaryPrompt

Make Your Laravel App an Active Participant in AI Workflows

Laravel MCP is how your application becomes an active participant in AI workflows rather than a passive codebase that agents guess about. The laravel/mcp package gives you the primitives to expose your application to any MCP-compatible client, with the fluent syntax you already know from the rest of the framework.

To see it in action, check out Locket, a demo app we built to show the Laravel MCP in a real product context. You can read the code or watch the demo.

When you’re ready to try it for yourself, start with a single tool that solves a real problem in your app. Connect it to Claude or Cursor. See how different the interaction is when the agent is querying your actual data rather than inventing it. Then read the laravel/mcp documentation to go further with resources, prompts, and OAuth.