How to Use Lerd with Laravel Boost (or Any Local Laravel MCP)?

[SantosVilanculos]

Laravel MCP supports local servers that run as Artisan commands. These are intended for local AI integrations such as Laravel Boost.

When your Laravel application runs with Lerd, the application and its services run inside Podman containers. Starting the MCP server directly with php artisan from your host can cause environment mismatches, especially when services such as MySQL, Redis, or PostgreSQL use container-only hostnames.

The Problem

A Laravel MCP local server might be registered like this:

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

Mcp::local('weather', WeatherServer::class);

Laravel MCP local servers are started as Artisan commands by the MCP client.

If the client starts the server using php, the command runs on the host:

{
  "mcpServers": {
    "weather": {
      "command": "php",
      "args": ["artisan", "mcp:start", "weather"]
    }
  }
}

That can require host-specific overrides for database hosts, ports, or other environment values.

Using Lerd Instead

Lerd can pass console commands through to the running application container. Replace php with lerd:

{
  "mcpServers": {
    "weather": {
      "command": "lerd",
      "args": ["artisan", "mcp:start", "weather"]
    }
  }
}

The MCP client still starts the Laravel MCP local server, but the Artisan command runs inside the Lerd application container.

As a result, the MCP server uses the same environment as the application:

• Database and service hostnames work as configured.
• Container network aliases such as mysql and redis are available.
• The server uses the same PHP runtime and extensions as the application.
• Host-side .env overrides are unnecessary.

This approach works with Laravel MCP local servers, including servers used by Laravel Boost or other local MCP clients.

The key change is simply:

php artisan mcp:start <server>

becomes:

lerd artisan mcp:start <server>

[geodro]

this is a good writeup, and it made us find a real bug, so thanks.

one thing worth knowing, you do not strictly need to swap php for lerd. the installer puts lerd's bin directory ahead of the system one on your PATH, and the php there already execs into the project's container, so a plain command php entry runs inside the container too. where naming lerd explicitly does matter is a client you launch from a desktop icon rather than a terminal, since it never inherits your login PATH and finds the system php instead. so both forms are right, they just cover different launch paths.

the bug is on our side. lerd was printing a few setup notices on stdout before the exec, the paused site header, the starting a service line, and the warning when a service fails to start. stdout on that path belongs to the child, so on a paused site, or with a service that had to come up first, one of those lines would have landed in the middle of the JSON-RPC stream and desynced the client. they go to stderr now, and the docs gained a section on running a framework's own MCP server through lerd. that is PR 1604, shipping in the next release.