Laravel Boost

What is Laravel Boost?

Laravel Boost accelerates AI-assisted development by providing the essential guidelines and agent skills that help AI agents write high-quality Laravel applications. It includes a built-in MCP (Model Context Protocol) server that gives your AI coding agent access to your application's structure, database, routes, and all of Laravel's documentation.

Because Spin runs your Laravel application inside Docker containers, the MCP server needs to run inside the container where PHP and Artisan are available. This guide walks you through installing Boost and configuring the MCP server for your preferred AI coding tool.

Prerequisites

Before we install Laravel Boost, we'll want to prepare two things:

1. Configure a wait script to handle the MCP server startup
2. Set the .env file so Laravel Boost generates the correct MCP configuration files

Why a Wrapper Script is Needed

Laravel Boost's MCP server uses stdio (standard input/output) as its transport — not an HTTP port. This means your AI coding tool communicates with the MCP server by sending and receiving data directly through the process's stdin and stdout streams, much like a conversation over a pipe.

Since Spin runs PHP inside a Docker container, we need a way to bridge your host machine (where the IDE runs) to the container (where PHP and Artisan live). The spin run -T command does exactly this — it runs the Artisan command inside the container while keeping the stdio streams connected back to your workstation. The -T flag disables pseudo-TTY allocation, which is critical because TTY mode would interfere with the raw stdio data that the MCP protocol relies on.

There's one more complication: AI coding tools typically start their MCP servers as soon as the IDE opens. At that point, your Spin containers might not be running yet. If the MCP command fails because the container isn't ready, the IDE may not retry it automatically.

To handle both of these concerns, we use a lightweight wrapper script that:

1. Runs the MCP command inside the container using spin run -T
2. Retries every few seconds until the container is available

Creating the Wrapper Script

Create the scripts directory and the wrapper script — this keeps it alongside other Spin infrastructure files:

mkdir -p .infrastructure/scripts

Then create .infrastructure/scripts/mcp-wait.sh with the following contents:

#!/usr/bin/env bash
#
# Retry wrapper for commands that depend on Docker or other services.
# Filters stdout to pass only JSON-RPC messages, stripping startup noise
# (ANSI codes, container messages, emoji banners) that would corrupt the
# MCP stdio protocol. Retries on failure until the service is available.
#
# Usage: mcp-wait.sh COMMAND [ARGS...]

# If this isn't an MCP server invocation, skip the retry/filter logic entirely.
is_mcp=0
for arg in "$@"; do
    [ "$arg" = "boost:mcp" ] && is_mcp=1 && break
done

if [ "$is_mcp" -eq 0 ]; then
    exec "$@"
fi

MAX_RETRIES=60
SLEEP_SECONDS=5
attempt=0

while [ $attempt -lt $MAX_RETRIES ]; do
    # stdout: pass only JSON-RPC lines (strips ANSI codes, emoji banners)
    # stderr: suppress docker-compose container lifecycle messages
    "$@" 2>/dev/null | grep --line-buffered '^{'
    exit_code="${PIPESTATUS[0]}"

    # Exit if:
    # 1. Success (exit code 0)
    # 2. Signal termination (exit code > 128)
    [ "$exit_code" -eq 0 ] && exit 0
    [ "$exit_code" -gt 128 ] && exit "$exit_code"

    attempt=$((attempt + 1))
    echo "mcp-wait: attempt $attempt/$MAX_RETRIES failed (exit $exit_code), retrying in ${SLEEP_SECONDS}s..." >&2
    sleep "$SLEEP_SECONDS"
done

echo "mcp-wait: gave up after $MAX_RETRIES attempts: $*" >&2
exit 1

Make the script executable:

chmod +x .infrastructure/scripts/mcp-wait.sh

Preparing the .env file

When Laravel Boost generates MCP configurations, everything is centralized from what you set in your .env file. Add these values to your .env file:

BOOST_PHP_EXECUTABLE_PATH="./.infrastructure/scripts/mcp-wait.sh ./vendor/bin/spin run -T php php"
BOOST_COMPOSER_EXECUTABLE_PATH="./vendor/bin/spin run php composer"
BOOST_NPM_EXECUTABLE_PATH="./vendor/bin/spin run node npm"
BOOST_VENDOR_BIN_EXECUTABLE_PATH="./vendor/bin"

Installation

Now that everything is ready, we can install Laravel Boost.

spin run php composer require laravel/boost --dev

Next, install the MCP server and coding guidelines. When prompted, select the AI agents you plan to use (Cursor, Claude Code, etc.):

spin run php php artisan boost:install

The boost:install command generates the relevant guideline and skill files for the coding agents you selected. Feel free to add the generated configuration files to your .gitignore since they are automatically regenerated when running boost:install or boost:update.

Learn More

Laravel Boost offers much more than what's covered here, including custom AI guidelines, agent skills, and a powerful documentation API. For the full reference, visit the official Laravel Boost documentation.