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 over 17,000 pieces of Laravel-specific documentation — all enhanced by semantic search.

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.

Installation

First, install the Laravel Boost package via Composer:

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.

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 exec -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 exec -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/boost-mcp.sh with the following contents:

#!/usr/bin/env bash

while true; do
    spin exec -T php php artisan boost:mcp 2>/dev/null
    exit_code=$?

    if [ $exit_code -eq 0 ]; then
        break
    fi

    sleep 3
done

Make the script executable:

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

Configuring Your AI Coding Tool

When you ran boost:install, it generated MCP configuration files for each AI agent you selected. These default configs point to php artisan boost:mcp — which assumes PHP is available on your host machine. Since Spin runs PHP inside Docker, you need to update these configs to use the wrapper script instead.

Every tool has its own configuration file and location — there is no universal standard. However, the concept is the same across all of them: change the MCP server command to run bash .infrastructure/scripts/boost-mcp.sh instead of php artisan boost:mcp.

Regardless of which tool you use, the important values are always the same:

Cursor

Cursor reads its MCP configuration from .cursor/mcp.json inside your project. The boost:install command should have already created this file. Update it so the laravel-boost server points to the wrapper script:

{
    "mcpServers": {
        "laravel-boost": {
            "command": "bash",
            "args": [".infrastructure/scripts/boost-mcp.sh"]
        }
    }
}

After saving this file, enable the MCP server in Cursor:

1. Open the command palette (Cmd+Shift+P on macOS or Ctrl+Shift+P on Windows/Linux)
2. Search for "Cursor Settings: Tools & MCP" and press Enter
3. Turn the toggle on for laravel-boost

Claude Code

Claude Code reads its project-level MCP configuration from .mcp.json in the project root (not inside .cursor/). The boost:install command should have already created this file. Update it so the laravel-boost server points to the wrapper script:

{
    "mcpServers": {
        "laravel-boost": {
            "command": "bash",
            "args": [".infrastructure/scripts/boost-mcp.sh"]
        }
    }
}

Alternatively, you can register the server using the CLI:

claude mcp add --transport stdio --scope local laravel-boost -- bash .infrastructure/scripts/boost-mcp.sh

Other AI Agents

Each tool has its own way of registering MCP servers and may use a different config file location. For Codex, Gemini CLI, GitHub Copilot, Junie, and others, refer to the official Laravel Boost documentation for their specific setup steps. The only difference with Spin is that you should update the command to point to the .infrastructure/scripts/boost-mcp.sh wrapper script instead of running php artisan boost:mcp directly.

Keeping Boost Updated

As you update Laravel packages in your project, you should periodically update your local Boost resources to keep the AI guidelines and skills current:

spin run php php artisan boost:update

You can also automate this by adding it to your Composer post-update-cmd scripts:

{
    "scripts": {
        "post-update-cmd": [
            "@php artisan boost:update --ansi"
        ]
    }
}

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.