Building a Laravel MCP Server: Auth, Permissions and Guardrails

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

Mcp::oauthRoutes();

Mcp::web('/mcp/shop', ShopServer::class)
    ->middleware(['auth:api', 'throttle:mcp']);

abstract class AuthorizedTool extends Tool
{
    final public function handle(Request $request): Response
    {
        $user = $request->user();

        if (! $user instanceof User) {
            return $this->audit($request, null, 'denied', Response::error('Sign in to use this tool.'));
        }

        try {
            $response = Container::getInstance()->call([$this, 'run'], ['request' => $request, 'user' => $user]);

            return $this->audit($request, $user, 'success', $response);
        } catch (AuthorizationException) {
            return $this->audit($request, $user, 'denied', Response::error('You are not allowed to do this.'));
        } catch (ValidationException $e) {
            return $this->audit($request, $user, 'denied', Response::error(collect($e->errors())->flatten()->first()));
        } catch (ModelNotFoundException) {
            return $this->audit($request, $user, 'denied', Response::error('Record not found.'));
        } catch (Throwable $e) {
            report($e);

            return $this->audit($request, $user, 'error', Response::error('Something went wrong while running this tool.'), $e->getMessage());
        }
    }

    private function audit(Request $request, ?User $user, string $status, Response $response, ?string $error = null): Response
    {
        DB::table('mcp_tool_calls')->insert([
            'user_id' => $user?->id,
            'tool' => $this->name(),
            'status' => $status,
            'arguments' => json_encode($request->all()),
            'error' => $error,
            'created_at' => now(),
            'updated_at' => now(),
        ]);

        return $response;
    }
}

#[Name('list-orders')]
#[Description('List orders the signed-in user can see, newest first. Support staff see all orders; customers see only their own.')]
#[IsReadOnly]
class ListMyOrdersTool extends AuthorizedTool
{
    public function run(Request $request, User $user): Response
    {
        $data = $request->validate([
            'status' => ['nullable', 'in:paid,refunded'],
            'limit' => ['nullable', 'integer', 'min:1', 'max:50'],
        ]);

        $orders = Order::query()
            ->when(! $user->is_support, fn ($q) => $q->where('user_id', $user->id)) // scope first, always
            ->when($data['status'] ?? null, fn ($q, $status) => $q->where('status', $status))
            ->latest('id')
            ->limit($data['limit'] ?? 20)
            ->get(['id', 'user_id', 'total', 'status', 'created_at']);

        return Response::json(['orders' => $orders]);
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'status' => $schema->string()->enum(['paid', 'refunded'])->description('Only orders with this status.'),
            'limit' => $schema->integer()->description('How many orders to return (1-50, default 20).'),
        ];
    }
}

#[Name('refund-order')]
#[Description('Refund a paid order in full. This moves real money and cannot be undone: always confirm the order id and amount with the user first.')]
#[IsDestructive]
class RefundOrderTool extends AuthorizedTool
{
    /** Hidden from users who can never refund, so the model doesn't even see it. */
    public function shouldRegister(Request $request): bool
    {
        return (bool) $request->user()?->is_support;
    }

    public function run(Request $request, User $user): Response
    {
        $data = $request->validate([
            'order_id' => ['required', 'integer'],
            'confirm_total' => ['required', 'integer'],
        ]);

        $order = Order::findOrFail($data['order_id']);

        Gate::forUser($user)->authorize('refund', $order); // the real check, same policy as the admin panel

        if ($data['confirm_total'] !== $order->total) {
            return Response::error("Order {$order->id} total is {$order->total}, not {$data['confirm_total']}. Confirm the amount with the user.");
        }

        $order->update(['status' => 'refunded']); // in a real app: call the payment service here

        return Response::json(['refunded' => true, 'order_id' => $order->id, 'total' => $order->total]);
    }

    public function schema(JsonSchema $schema): array
    {
        return [
            'order_id' => $schema->integer()->description('The order to refund.')->required(),
            'confirm_total' => $schema->integer()->description('The order total in minor units, as confirmed by the user.')->required(),
        ];
    }
}

#[Name('Shop')]
#[Version('1.0.0')]
#[Instructions('Operates the shop on behalf of the signed-in user, with exactly the permissions they have in the admin panel. Prefer read tools. refund-order moves real money: confirm the order and amount with the user before calling it.')]
class ShopServer extends Server
{
    protected array $tools = [
        ListMyOrdersTool::class,
        RefundOrderTool::class,
    ];
}

public function test_customers_only_see_their_own_orders(): void
{
    $alice = User::factory()->create();
    $bob = User::factory()->create();
    Order::create(['user_id' => $alice->id, 'total' => 1500]);
    Order::create(['user_id' => $bob->id, 'total' => 9900]);

    ShopServer::actingAs($alice)->tool(ListMyOrdersTool::class)
        ->assertOk()->assertSee('1500')->assertDontSee('9900');
}

public function test_support_must_confirm_the_amount(): void
{
    $support = User::factory()->create(['is_support' => true]);
    $order = Order::create(['user_id' => User::factory()->create()->id, 'total' => 1500]);

    ShopServer::actingAs($support)->tool(RefundOrderTool::class, ['order_id' => $order->id, 'confirm_total' => 15000])
        ->assertHasErrors(['total is 1500, not 15000']);
    $this->assertSame('paid', $order->fresh()->status);

    ShopServer::actingAs($support)->tool(RefundOrderTool::class, ['order_id' => $order->id, 'confirm_total' => 1500])
        ->assertOk()->assertSee('"refunded":true');
}

public function test_the_policy_still_applies_to_support(): void
{
    $support = User::factory()->create(['is_support' => true]);
    $order = Order::create(['user_id' => $support->id, 'total' => 1500, 'status' => 'refunded']);

    ShopServer::actingAs($support)->tool(RefundOrderTool::class, ['order_id' => $order->id, 'confirm_total' => 1500])
        ->assertHasErrors(['You are not allowed to do this.']);
}

// + a customer calling the hidden refund tool gets an error and nothing changes,
//   and every call (allowed or denied) lands in mcp_tool_calls.