Mcp Client Laravel Laravel Package

Getting Started

Start by installing the package and publishing its config:

composer require redberry/mcp-client-laravel:^1.1.1
php artisan vendor:publish --tag="mcp-client-config"

Review config/mcp-client.php — define your MCP servers using either HTTP or STDIO transports. The simplest first use case is calling a tool from an MCP-compliant server (e.g., GitHub Copilot MCP or memory server):

use Redberry\MCPClient\Facades\MCPClient;

$client = MCPClient::connect('github');
$result = $client->callTool('create_entities', [
    'entities' => [['name' => 'Alice', 'entityType' => 'PERSON']]
]);

Note: This release now supports Laravel 13 and PHP 8.5. Ensure your project's composer.json reflects these versions if upgrading.

Also check the Transporters enum and config schema in the config file — this sets the stage for discovery, tooling, and memory interaction.

Implementation Patterns

• Configuration-driven servers: Define each MCP server as a named entry in config/mcp-client.php. Use environment variables for tokens, timeouts, and credentials (e.g., GITHUB_API_TOKEN).

• Service injection: Prefer dependency injection over facades for testability:

  class ToolService
  {
      public function __construct(private MCPClient $client) {}
  
      public function runTools(array $names): array
      {
          return $this->client->connect('my-server')
                              ->tools()
                              ->only(...$names)
                              ->map(fn($tool) => $this->client->callTool($tool['name'], []));
      }
  }
  

• Resource + tool orchestration: Access structured data and actions in sequence:

  $client = MCPClient::connect('npx_mcp_server');
  $resources = $client->resources()->map(fn($r) => $r['uri']);
  $content   = $client->readResource('file:///project/config/app.php');
  

• Integration with agent frameworks: This package powers tool calling in agents (e.g., LarAgent). Use it to wrap MCP tools as Laravel LLM-compatible functions or tool definitions.

• Reusable tool presets: Create reusable “tool groups” by defining static helpers like MCP::github()->tools()->only('list_issues','create_issue').

Gotchas and Tips

• STDIO limitation in php artisan serve: The README explicitly warns STDIO transport doesn’t work with php artisan serve. Use php -S localhost:8000 or Docker during development if relying on STDIO.

• Timeout misconfig: Ensure timeout (seconds) is meaningful per use case. STDIO commands may require higher timeouts for large payloads or long-running servers.

• Tool param shape matters: MCP tools expect structured params matching their schema. Validate or hydrate inputs (e.g., using Laravel Form Requests or DTOs) before calling callTool().

• Collection utilities: Leverage Laravel Collections to filter, rename, or group tools/resources before use:

  $client->tools()
         ->where('description', 'like', '%issue%')
         ->pluck('name');
  

• Extensibility: To support custom transports (e.g., WebSockets, custom header auth), implement the Transporter interface and register in TransporterFactory. Add a corresponding config key ('type' => 'custom') to wire it up.

• Debugging: Log raw requests/responses during early integration. The package doesn’t emit events yet — consider wrapping callTool() in a logger or trait to capture tool inputs/outputs for auditing.

• Laravel version support: Now supports Laravel 13 alongside L10–L12. Use ^10.0||^11.0||^12.0||^13.0 in composer.json for illuminate/contracts. Confirm compatibility before upgrading Laravel.

• STDIO error handling: The StdioTransporter no longer duplicates startup failures in error_log(). Check the TransporterRequestException message for command, exit code, stderr, and stdout details.

• Testing: The package now supports Testbench v8.22–v11.0 and Pest v2–v4. Update your testing dependencies if needed.

• Future migration: For new projects, consider the v2.0 line, which includes Streamable HTTP, SSE event streaming, and session-loss recovery. See UPGRADE.md for v1.x → v2.x migration guidance.