Download the PHP package bramato/laravel-mcp-server without Composer

Laravel MCP Server (bramato/laravel-mcp-server)

A base Laravel package for building Model Context Protocol (MCP) servers.

This package provides the basic infrastructure to handle MCP requests over different transports (Stdio, HTTP, WebSocket via Reverb). It uses the excellent sajya/server library internally for robust JSON-RPC 2.0 request parsing and response formatting.

You need to implement your own ResourceInterface and ToolInterface classes (using the Bramato\\LaravelMcpServer\\Mcp\\Interfaces namespace) and register them in the configuration file to expose your application's data and functionalities according to the MCP specification.

Installation

You can install the package via composer:

Next, you should publish the configuration file using the vendor:publish Artisan command:

This will create a config/mcp.php file in your application's config directory, where you can customize the server's behavior.

Configuration

The config/mcp.php file allows you to configure:

• enabled_transports: Choose which transports (stdio, http, websocket) are active.
• transports: Configure details for each transport (e.g., the HTTP path in transports.http.path).
• authentication: Basic authentication setup (supports none or token via authentication.driver). For token authentication, specify the header name in authentication.options.header.
• resources: Register your MCP Resources. Provide an array of fully qualified class names that implement Bramato\\LaravelMcpServer\\Mcp\\Interfaces\\ResourceInterface.
• tools: Register your MCP Tools. Provide an array of fully qualified class names that implement Bramato\\LaravelMcpServer\\Mcp\\Interfaces\\ToolInterface. This acts as a whitelist for executable tools.
• logging: Configure the logging channel and level for package-specific logs.

Creating Resources and Tools

This package provides the interfaces, but you need to implement the actual logic.

Example: Creating a Resource

1. Create your Resource class (e.g., in app/Mcp/Resources/UserProfileResource.php):

2. Register it in config/mcp.php:

Example: Creating a Tool

1. Create your Tool class (e.g., in app/Mcp/Tools/SendNotificationTool.php):

2. Register it in config/mcp.php:

Usage

How to run the server depends on the enabled transport:

• Stdio: Run the Artisan command: php artisan mcp:server --transport=stdio.
• HTTP: Ensure your web server (e.g., php artisan serve or Nginx/Apache) is running. Send JSON-RPC POST requests to the path configured in mcp.transports.http.path (default: /mcp-rpc).
• WebSocket (Reverb):
  1. Install and configure Laravel Reverb in your main application: php artisan reverb:install.
  2. Ensure the websocket transport is listed in enabled_transports in config/mcp.php.
  3. Start the Reverb server: php artisan reverb:start.
  4. Connect your MCP WebSocket client to the Reverb server endpoint (check your Reverb configuration).

Testing

The package includes a basic test suite using PHPUnit and Orchestra Testbench.

Security Considerations

The MCP specification does not define authentication or authorization mechanisms between client and server. This package provides:

• Tool Whitelisting: Only tools explicitly listed in the tools array in config/mcp.php can be executed.
• Basic Token Authentication: You can enable token-based authentication via the authentication config section.

Important: It is your responsibility to implement fine-grained authorization logic within your ToolInterface::execute and ResourceInterface::getContents methods. Use Laravel's Gates and Policies or other authorization mechanisms to ensure that the requesting client has the necessary permissions to access specific resources or execute specific tools.

Contributing

Please see CONTRIBUTING.md for details (if available).

License

The MIT License (MIT). Please see the LICENSE.md file for more information.