MCP Protocol Integration

This document describes how the laravel-boost-copilot-cli package implements the Model Context Protocol (MCP) to enable communication between GitHub Copilot CLI and Laravel Boost. It covers the protocol structure, server lifecycle, and the implementation of the SupportsMcp contract.

For information about the MCP configuration file structure and settings, see MCP Configuration File. For details about the CopilotCli agent class implementation, see CopilotCli Agent Class.

Model Context Protocol Overview

The Model Context Protocol is a communication standard that allows AI tools to interact with external systems through a server-client architecture. In this package, GitHub Copilot CLI acts as the MCP client, while Laravel Boost provides the MCP server functionality through the boost:mcp command.

The protocol operates through JSON-RPC 2.0 over stdio, where:

• The MCP client (GitHub Copilot CLI) spawns and manages the server process
• The MCP server (Laravel Boost) exposes tools and resources through a standardized interface
• Communication happens via standard input/output streams using JSON messages

Sources: README.md55-59 .github/copilot-instructions.md37-40

Configuration File Structure

The MCP protocol requires a configuration file that defines how to spawn and connect to MCP servers. This package generates .github/mcp-config.json with the mcpServers configuration block.

Configuration Schema

Sources: .github/mcp-config.json1-14 .github/copilot-instructions.md37-90

Standard Laravel Application Configuration

Field	Value	Purpose
type	"local"	Spawn process on local machine
command	"php"	Standard PHP binary
args	["artisan", "boost:mcp"]	Run Laravel artisan command
tools	["*"]	Enable all available MCP tools

Sources: .github/copilot-instructions.md41-53

Laravel Sail Configuration

Field	Value	Purpose
type	"local"	Spawn process on local machine
command	"./vendor/bin/sail"	Sail wrapper script
args	["artisan", "boost:mcp"]	Execute inside Docker container
tools	["*"]	Enable all available MCP tools

Sources: .github/copilot-instructions.md55-72

Orchestra Testbench Configuration

Field	Value	Purpose
type	"local"	Spawn process on local machine
command	"./vendor/bin/testbench"	Testbench binary
args	["boost:mcp"]	Note: no "artisan" argument
tools	["*"]	Enable all available MCP tools

Sources: .github/copilot-instructions.md74-90 .github/mcp-config.json1-14

MCP Communication Flow

Sources: README.md55-67 .ai/guidelines/copilot-cli.blade.php1-10

SupportsMcp Contract Implementation

The CopilotCli class implements the Laravel\Boost\Contracts\SupportsMcp interface, which requires implementation of MCP configuration generation methods.

mcpServerConfig Method

The mcpServerConfig() method is the core implementation that generates the MCP server configuration payload.

Sources: src/CopilotCli.php84-103

Method Signature and Return Structure

src/CopilotCli.php91-103

The method returns an associative array with the following structure:

Key	Type	Description
type	string	Always "local" for stdio-based spawning
command	string	Executable path (environment-specific)
args	array<int, string>	Command arguments (filtered based on environment)
env	array<string, string>	Environment variables to pass to process
tools	array<int, string>	Always ["*"] to enable all tools

Sources: src/CopilotCli.php86-103

Command Path Conversion Logic

The convertCommandToPhpPath() method handles environment-specific command path transformations to ensure the MCP server can be spawned correctly in different execution contexts.

Sources: src/CopilotCli.php105-122

Environment Detection Methods

Method	Purpose	Implementation
isRunningInTestbench()	Detects Orchestra Testbench environment	Checks if TESTBENCH_CORE constant is defined
isRunningInsideWsl()	Detects Windows Subsystem for Linux	Checks WSL_DISTRO_NAME or IS_WSL environment variables

Sources: src/CopilotCli.php124-140

Configuration Generation Process

Sources: src/CopilotCli.php79-103 README.md42-53

MCP Server Lifecycle

Server Spawn Process

When GitHub Copilot CLI spawns the MCP server:

1. Process Creation: CLI reads mcp-config.json and spawns the configured command
2. Laravel Bootstrap: The php artisan boost:mcp command initializes Laravel framework
3. Protocol Handshake: Server and client exchange protocol version and capabilities
4. Tool Registration: Laravel Boost registers all available MCP tools
5. Ready State: Server enters listening mode on stdio

Sources: README.md61-62 .ai/guidelines/copilot-cli.blade.php4-9

Communication Channel

The MCP protocol uses standard input/output streams for all communication:

Stream	Direction	Purpose
stdin	Client → Server	JSON-RPC requests (tool calls, resource requests)
stdout	Server → Client	JSON-RPC responses (tool results, data)
stderr	Server → Debug	Error logging (not part of protocol)

Sources: .github/copilot-instructions.md1-90

Tool Execution Lifecycle

Sources: README.md55-59

Loading MCP Configuration

GitHub Copilot CLI requires explicit configuration loading through the --additional-mcp-config command-line option.

Command-Line Usage

The configuration file must be loaded with every Copilot CLI invocation:

The @ prefix indicates a file path reference that will be resolved relative to the current directory.

Sources: README.md55-59 README.md63-67

Verification

When the MCP configuration is successfully loaded, Copilot CLI displays a confirmation message:

Configured MCP servers: laravel-boost

If this message does not appear, the server failed to load or the configuration file path is incorrect.

Sources: README.md61-62 .ai/guidelines/copilot-cli.blade.php1-10

Environment-Specific Protocol Considerations

Standard Laravel Application

• Command: php binary from system PATH
• Args: ["artisan", "boost:mcp"] to invoke Laravel artisan
• Process Context: Runs in the application's root directory with full access to application resources

Sources: .github/copilot-instructions.md41-53

Laravel Sail (Docker)

• Command: ./vendor/bin/sail wrapper script
• Args: ["artisan", "boost:mcp"] forwarded to container
• Process Context: Executes inside Docker container, accesses containerized database and services
• Requirement: Sail must be running (./vendor/bin/sail up -d) before spawning MCP server

Sources: .github/copilot-instructions.md55-72 README.md27-29

Windows Subsystem for Linux (WSL)

• Command: Result of getPhpPath() method (WSL-compatible PHP path)
• Args: ["artisan", "boost:mcp"] standard artisan invocation
• Process Context: Bridges Windows and Linux filesystem paths
• Detection: Checks WSL_DISTRO_NAME or IS_WSL environment variables

Sources: src/CopilotCli.php108-116 src/CopilotCli.php124-131

Orchestra Testbench (Package Development)

• Command: ./vendor/bin/testbench binary
• Args: ["boost:mcp"] (note: "artisan" is omitted)
• Process Context: Limited Laravel environment without full application context
• Detection: Checks if TESTBENCH_CORE constant is defined
• Limitations: Some MCP tools may not function due to missing application resources

Sources: src/CopilotCli.php97-99 src/CopilotCli.php133-140 .github/mcp-config.json1-14 .ai/guidelines/copilot-cli.blade.php11-21

MCP Configuration Path

The mcpConfigPath() method defines where the MCP configuration file should be written:

src/CopilotCli.php79-82

The path .github/mcp-config.json is standard across all environments and follows GitHub's configuration convention of placing tool configurations in the .github/ directory.

Sources: src/CopilotCli.php79-82

Local Configuration Overrides

For sensitive credentials or local-only MCP servers, a separate .github/mcp-config.local.json file can be created and loaded alongside the primary configuration:

This file should be added to .gitignore to prevent credential exposure in version control.

Sources: README.md102-124

Integration with Laravel Boost Framework

The MCP protocol integration relies on Laravel Boost's core MCP server implementation. This package's role is to:

1. Detect Environment: Identify execution context (standard Laravel, Sail, WSL, Testbench)
2. Generate Configuration: Create appropriate mcp-config.json with correct command and arguments
3. Register Agent: Provide the CopilotCli agent to Laravel Boost via CopilotCliServiceProvider

Laravel Boost handles:

• MCP protocol implementation (JSON-RPC over stdio)
• Tool registration and execution
• Resource management
• Protocol handshake and lifecycle

Sources: src/CopilotCli.php1-151 .github/copilot-instructions.md23-35