Getting started
Connect the same app across local runtimes
The browser, coding client, and worker must point to the same application evidence. Similar paths on different machines are not the same files.
-
Web runtime
PHP captures the request in the Laravel app. -
Profile directory
The app stores the retained profile and background correlation data. -
MCP and workers
The other local processes need the intended app environment and access to that evidence.
Host PHP, Herd, and Valet
Use the PHP executable that is compatible with the app’s web runtime. Check the PHP and Laravel environment used by your terminal or client:
php -v
php /absolute/path/to/your-app/artisan env
Compare those facts with the runtime context captured by the web request. A per-site PHP selection in Herd or Valet can differ from the php found by a desktop application. Use an absolute executable path in the MCP configuration when needed.
Keep the Artisan path specific to the app. Two worktrees or two Laravel projects should not accidentally share the same manually configured MCP server command.
Docker and Sail
Start the MCP process inside the application container when that is where Laravel and its dependencies run. The following Docker Compose example is a configuration pattern: replace the Compose file and service name with your project’s values, then verify them before connecting.
{
"command": "docker",
"args": [
"compose",
"--file", "/absolute/path/to/your-app/compose.yaml",
"exec", "-T",
"laravel.test",
"php", "artisan", "mcp:start", "newdebugbar"
]
}
This assumes the service’s working directory contains artisan, as in a standard Sail application service. -T disables a pseudo-terminal so the MCP protocol can use standard input and output. The Docker executable must be available to the coding client.
Check the container itself before troubleshooting the client:
docker compose --file /absolute/path/to/your-app/compose.yaml exec -T laravel.test php -v
docker compose --file /absolute/path/to/your-app/compose.yaml exec -T laravel.test php artisan env
These commands are based on Laravel Sail and Docker Compose exec. A custom service, working directory, or filesystem mount needs the corresponding change.
Check the profile directory
By default, profiles live in storage/framework/newdebugbar inside the Laravel app. A browser process in a container and host-side PHP may use different storage, database addresses, and environment values even when both can read the same source tree.
Prefer running MCP in the intended application runtime. If you use a custom storage path, make it readable by the relevant processes and keep the profile and correlation data together. Confirm one fresh response ID can be read by the client.
Keep workers on the same setup
A queue worker needs the package enabled in an allowed environment, the intended queue connection, and access to the retained profiles. Restart long-lived workers after relevant code or configuration changes.
Compare the job’s connection, queue, and attempt facts with the origin profile. Use Queues when a dispatch remains pending or a retry creates several worker profiles.
Verify long-lived runtime boundaries
A recorded Octane, FrankenPHP, or RoadRunner runtime label identifies the process. It is not a promise of dedicated integration with every server option or child process.
Check at least two different requests and a failed request in your runtime. The selected profile must contain that request’s work rather than activity carried over from another request. Follow the runtime’s normal reload procedure after changing the package.
Use one end-to-end check
- Visit one known HTML or API route and copy its response profile ID.
- Read that exact ID through MCP and compare method, path, and a visible metric.
- If the flow dispatches a job, run the intended worker and open its correlated result.
- If any step fails, keep the exact command, runtime facts, and error for the relevant troubleshooting guide.