MCP Server Architecture

This page describes the Model Context Protocol (MCP) architecture as implemented in this package: specifically, how PhpStorm's GitHub Copilot plugin acts as the MCP client, how php artisan boost:mcp acts as the server subprocess, and how mcp.json bridges the two at runtime. It covers the conceptual protocol model and the runtime data flow.

For details on how the PhpStormCopilot agent class generates and writes mcp.json during installation, see MCP Configuration Generation. For platform-specific write paths and config file format examples, see MCP Configuration Format and Examples.

---

What MCP Is in This Context

MCP (Model Context Protocol) is a protocol that allows an AI assistant (here: the GitHub Copilot plugin inside PhpStorm) to call external tools and retrieve context from a running process. The protocol defines two roles:

Role	In this system
MCP Client	GitHub Copilot plugin running inside PhpStorm
MCP Server	php artisan boost:mcp subprocess, provided by laravel/boost

The client discovers available servers by reading mcp.json from a fixed, system-wide location on disk. On startup, the client spawns each configured server as a subprocess, then communicates over stdio using the MCP protocol.

The boost:mcp artisan command — registered by laravel/boost, not this package — is the actual MCP server process. This package's sole responsibility is to correctly write and maintain the mcp.json file that tells the Copilot plugin how to spawn that process.

Sources: README.md1-30 .github/copilot-instructions.md1-20

---

The Role of mcp.json

mcp.json is a system-wide configuration file that the GitHub Copilot plugin reads at startup to discover MCP servers. It is not per-project; it lives in a fixed OS-specific location.

OS	Path
macOS	~/.config/github-copilot/intellij/mcp.json
Linux	~/.config/github-copilot/intellij/mcp.json
Windows (native)	%LOCALAPPDATA%\github-copilot\intellij\mcp.json
WSL	Written to Windows path via PowerShell

The file structure under the servers key (the value returned by mcpConfigKey()) maps a server name to its command and args:

Because the paths are absolute, the file becomes stale the moment the developer switches to a different Laravel project. boost:install --mcp must be re-run per project.

The mcpConfigPath() method in PhpStormCopilot src/PhpStormCopilot.php104-114 returns the OS-appropriate path, and mcpConfigKey() src/PhpStormCopilot.php99-102 returns 'servers', matching the schema above.

Sources: src/PhpStormCopilot.php99-114 README.md122-124 .github/copilot-instructions.md101-116

---

Runtime Data Flow

The following sequence describes what happens after boost:install has been run and mcp.json is in place.

Diagram: Runtime sequence — from IDE startup to MCP tool response

Sources: README.md96-124 .github/copilot-instructions.md99-116

---

Component Relationships

The diagram below maps the conceptual MCP roles to the concrete code entities involved.

Diagram: Code entities mapped to MCP roles

Sources: src/PhpStormCopilot.php1-187 src/Concerns/WithWSL.php1-129

---

Installation vs. Runtime Separation

It is important to distinguish two phases:

Phase	When	What runs	What it does
Installation	php artisan boost:install --mcp	PhpStormCopilot::installFileMcp()	Writes mcp.json with absolute paths
Runtime	PhpStorm startup / Copilot use	GitHub Copilot plugin → php artisan boost:mcp	Serves MCP tools over stdio

This package is only involved in the installation phase. It has no code that runs when the MCP server itself is active. Once mcp.json is written, laravel/boost handles all MCP protocol communication.

The installFileMcp() method src/PhpStormCopilot.php119-132 is the entry point for the installation phase. It:

1. Guards against Testbench environments
2. Branches to installMcpViaWsl() src/Concerns/WithWSL.php16-76 when WSL_DISTRO_NAME is set
3. Otherwise calls transformSailCommand() src/PhpStormCopilot.php141-162 and delegates to parent::installFileMcp() from laravel/boost

Sources: src/PhpStormCopilot.php119-132 src/Concerns/WithWSL.php11-14

---

mcp.json Content by Environment

The content written to mcp.json varies by environment. The table below shows the command and args structure for each case.

Environment	command	args
macOS / Linux (standard)	/absolute/path/to/php	["/path/to/artisan", "boost:mcp"]
Windows (native)	C:\path\to\php.exe	["C:\\path\\to\\artisan", "boost:mcp"]
WSL (no Sail)	wsl.exe	["/path/to/php", "/path/to/artisan", "boost:mcp"]
WSL + Sail	wsl.exe	["--cd", "/project/path", "./vendor/bin/sail", "artisan", "boost:mcp"]
macOS/Linux + Sail	bash	["-c", "cd /project/path && ./vendor/bin/sail artisan boost:mcp"]

The WSL wrapping is handled by transformMcpCommandForWsl() src/Concerns/WithWSL.php85-128 The Sail wrapping on non-WSL platforms is handled by transformSailCommand() src/PhpStormCopilot.php141-162

The removeEmptyArrays() method src/PhpStormCopilot.php168-181 is applied before writing in all cases, because some MCP clients reject configs containing empty arrays (e.g., "headers": []).

Sources: .github/copilot-instructions.md120-170 src/PhpStormCopilot.php141-181 src/Concerns/WithWSL.php85-128

---

System-Wide vs. Per-Project Scope

Because mcp.json is stored in a system-wide location rather than inside the project directory, only one Laravel project's MCP server can be registered under the laravel-boost key at a time. When the developer switches projects, the absolute paths in mcp.json point to the old project.

The correct workflow is:

# When switching to a new project:
php artisan boost:install --guidelines --skills --mcp --no-interaction

boost:update explicitly does not update the MCP config file (this was changed in Boost 1.8). Only boost:install --mcp writes the file.

For deeper context on the project-switching workflow, see Multi-Project Workflow.

Sources: README.md113-120 .github/copilot-instructions.md176-180