Use Laravel to create your own MCP server

Claude can already work with your Laravel app. Not by you hand-building a REST API, writing a client, and describing every endpoint to it, but by exposing a few tools over the Model Context Protocol (MCP) and letting the model call them directly. The official laravel/mcp package turns that into an afternoon's work.

This is the hands-on version. We'll build a small MCP server for an online shop: tools the model can call, a resource it can read, input validation, auth, and a test to keep it honest. The full write-up of how the protocol fits together lives on our site, Use Laravel to create your own MCP server. Here we're going to write the code.

First, the short version of what we're building. An MCP server exposes three things to a connected AI client: tools (actions the model can call, like searching orders), resources (read-only data it can pull in for context), and prompts (reusable templates). The client and server talk JSON-RPC, and laravel/mcp handles that wire format so you only write PHP.

Prerequisites

A recent Laravel application (12.x works well).
PHP 8.2 or newer.
Composer.
An MCP client to connect with later. Claude Desktop or Claude Code both work, and the bundled MCP Inspector covers testing.

Step 1: Install the package

Pull it in with Composer:

composer require laravel/mcp

Then publish the routes file your servers are registered in:

php artisan vendor:publish --tag=ai-routes

That gives you routes/ai.php. Treat it like routes/web.php: every server you expose gets a line in there.

Step 2: Create a server

A server is the thing a client connects to. It groups your tools, resources and prompts under one name. Generate one:

php artisan make:mcp-server OrdersServer

You get app/Mcp/Servers/OrdersServer.php. The class carries its identity in attributes and lists what it exposes in three arrays:

<?php

namespace App\Mcp\Servers;

use App\Mcp\Tools\SearchOrdersTool;
use Laravel\Mcp\Server;
use Laravel\Mcp\Server\Attributes\Instructions;
use Laravel\Mcp\Server\Attributes\Name;
use Laravel\Mcp\Server\Attributes\Version;

#[Name('Orders Server')]
#[Version('1.0.0')]
#[Instructions('Search orders, add internal notes, and cancel orders for the shop.')]
class OrdersServer extends Server
{
    protected array $tools = [
        SearchOrdersTool::class,
    ];

    protected array $resources = [
        //
    ];

    protected array $prompts = [
        //
    ];
}

Don't skip the Instructions attribute. It is sent to the client as context for what the server is for, so the model knows what it is looking at before it calls anything.

Step 3: Register the server

The server does nothing until it is registered in routes/ai.php. There are two kinds. A web server is reachable over HTTP for remote clients, and a local server runs as an Artisan command for agents on the same machine, like Claude Code.

use App\Mcp\Servers\OrdersServer;
use Laravel\Mcp\Facades\Mcp;

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

Mcp::local('orders', OrdersServer::class);

Web servers are ordinary routes, so the middleware you already use applies. We'll come back to the auth line in Step 8.

Step 4: Build a tool

This is the part that does real work. Generate a tool:

php artisan make:mcp-tool SearchOrdersTool

A tool has two methods. schema declares the arguments it accepts, and handle runs the work and returns a response. Here's a read-only search over orders:

<?php

namespace App\Mcp\Tools;

use App\Models\Order;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Tool;
use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;

#[IsReadOnly]
#[Description('Search recent orders, optionally filtered by status, and return their references and totals.')]
class SearchOrdersTool extends Tool
{
    public function handle(Request $request): Response
    {
        $validated = $request->validate([
            'status' => ['nullable', 'in:pending,shipped,delivered,cancelled'],
            'limit' => ['integer', 'between:1,50'],
        ]);

        $orders = Order::query()
            ->when($validated['status'] ?? null, fn ($query, $status) => $query->where('status', $status))
            ->latest()
            ->limit($validated['limit'] ?? 10)
            ->get();

        if ($orders->isEmpty()) {
            return Response::text('No orders matched that search.');
        }

        return Response::structured([
            'count' => $orders->count(),
            'orders' => $orders->map(fn ($order) => [
                'reference' => $order->reference,
                'status' => $order->status,
                'total' => $order->total,
                'placed_at' => $order->created_at->toIso8601String(),
            ])->all(),
        ]);
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'status' => $schema->string()
                ->enum(['pending', 'shipped', 'delivered', 'cancelled'])
                ->description('Only return orders with this status.'),

            'limit' => $schema->integer()
                ->description('Maximum number of orders to return.')
                ->default(10),
        ];
    }
}

It's already in the server's $tools from Step 2, so the client can call it now.

Two things are worth calling out. The schema is a typed contract for the model: status is one of four values, limit is an integer with a default. And the Description is how the model decides when to reach for the tool, so write it like you're briefing someone who has never seen your code. Response::structured() sends back parseable data while keeping a plain text version for clients that want one.

Step 5: Validate the input, and write errors the model will read

The schema sets the shape. Laravel's validator enforces the rules, exactly as in a controller:

$validated = $request->validate([
    'reference' => ['required', 'string', 'max:32'],
], [
    'reference.required' => 'Provide the order reference, for example "ORD-10423".',
]);

Here's the part people miss. The error message goes back to the model, and the model decides what to do next from what it says. "The reference field is required" tells it nothing. "Provide the order reference, for example ORD-10423" tells it how to retry. Write validation messages as instructions to a reader who is going to act on them.

Step 6: Tell the client how a tool behaves

Annotations describe a tool's behaviour without changing what it does. A client uses them to decide how to present a tool, for example asking the user to confirm before running anything that makes a change. They are attributes:

<?php

namespace App\Mcp\Tools;

use App\Models\Order;
use Illuminate\Contracts\JsonSchema\JsonSchema;
use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Tool;
use Laravel\Mcp\Server\Tools\Annotations\IsDestructive;
use Laravel\Mcp\Server\Tools\Annotations\IsIdempotent;

#[IsDestructive]
#[IsIdempotent]
#[Description('Cancel an order. An order that is already cancelled is left unchanged.')]
class CancelOrderTool extends Tool
{
    public function handle(Request $request): Response
    {
        $validated = $request->validate([
            'reference' => ['required', 'string', 'max:32'],
        ]);

        $order = Order::where('reference', $validated['reference'])->firstOrFail();

        if ($order->status !== 'cancelled') {
            $order->update(['status' => 'cancelled']);
        }

        return Response::text("Order {$order->reference} is cancelled.");
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'reference' => $schema->string()
                ->description('The reference of the order to cancel.')
                ->required(),
        ];
    }
}

There are four: #[IsReadOnly] (changes nothing), #[IsDestructive] (can make destructive changes), #[IsIdempotent] (running it again with the same arguments changes nothing further), and #[IsOpenWorld] (it touches systems outside your app). Cancelling an order is destructive but idempotent: cancel it twice and it is still just cancelled. Add CancelOrderTool::class to the server's $tools so it can be called.

Step 7: Add a resource and a prompt

Tools are actions. The other two primitives fill in the picture.

A resource is read-only context the model can pull in. No arguments, just a handle that returns content, like a returns policy:

<?php

namespace App\Mcp\Resources;

use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Resource;

#[Description('The shop returns and refunds policy.')]
class RefundPolicyResource extends Resource
{
    public function handle(Request $request): Response
    {
        return Response::text(file_get_contents(resource_path('policies/refunds.md')));
    }
}

A prompt is a reusable template the client can offer the user. It declares its arguments and returns the messages:

<?php

namespace App\Mcp\Prompts;

use Laravel\Mcp\Request;
use Laravel\Mcp\Response;
use Laravel\Mcp\Server\Attributes\Description;
use Laravel\Mcp\Server\Prompt;
use Laravel\Mcp\Server\Prompts\Argument;

#[Description('Draft a short status update to send to a customer about their order.')]
class OrderUpdatePrompt extends Prompt
{
    public function arguments(): array
    {
        return [
            new Argument(
                name: 'reference',
                description: 'The order the update is about.',
                required: true,
            ),
        ];
    }

    public function handle(Request $request): array
    {
        $reference = $request->string('reference');

        return [
            Response::text('You write friendly customer service messages.')->asAssistant(),
            Response::text("Draft a short update for the customer about order {$reference}."),
        ];
    }
}

Generate these with make:mcp-resource and make:mcp-prompt, then register them in the server's $resources and $prompts arrays.

Step 8: Secure the server

A web MCP server is a public endpoint that can read and change your data. Leaving it open is the same mistake as shipping an admin API with no auth. Because it is a normal route, you protect it with middleware.

The simple option is a token with Laravel Sanctum. The client sends it in the Authorization header:

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

For third-party clients, OAuth 2.1 through Laravel Passport is the stronger choice. Register the discovery routes and apply Passport's guard:

Mcp::oauthRoutes();

Mcp::web('/mcp/orders', OrdersServer::class)
    ->middleware('auth:api');

Once a user is authenticated, the request carries them into your tools, so $request->user() works as normal. You can even hide a tool per user with a shouldRegister method:

public function shouldRegister(Request $request): bool
{
    return $request->user()?->can('manage-orders') ?? false;
}

A tool whose shouldRegister returns false never shows up in the client's list and cannot be called. One server, different tools for different users.

Step 9: Inspect and test it

Two things check the server before a real client touches it.

The MCP Inspector connects to a server and lists its tools, resources and prompts so you can call them by hand. Point it at a registered server by name:

php artisan mcp:inspector orders

It prints the client settings to copy into your MCP client. If the server is behind auth, you add the header there too.

For automated coverage, write a normal test and call the primitive on the server that registers it. The response has assertion helpers:

<?php

use App\Mcp\Servers\OrdersServer;
use App\Mcp\Tools\CancelOrderTool;
use App\Models\Order;

it('cancels an order', function () {
    $order = Order::factory()->create([
        'reference' => 'ORD-10423',
        'status' => 'shipped',
    ]);

    $response = OrdersServer::tool(CancelOrderTool::class, [
        'reference' => 'ORD-10423',
    ]);

    $response
        ->assertOk()
        ->assertSee('ORD-10423 is cancelled');

    expect($order->fresh()->status)->toBe('cancelled');
});

There are matching assertions for errors and notifications, and an actingAs helper for testing tools that depend on the authenticated user.

Wrapping up

You have gone from an empty Laravel app to an MCP server with a read tool, a write tool, a resource, a prompt, authentication, and a test. The model now works against your application through one standard interface, and you never wrote a line of protocol code. The pattern from here is small: add a tool, give it a clear description and honest annotations, validate its input with messages worth reading, and put it behind the right middleware.

For the longer explanation of how MCP fits together, the full article is on our site: Use Laravel to create your own MCP server.

Have you wired an MCP server into something useful yet? Tell me what you connected it to in the comments.

推荐订阅源

DEV Community