README

Laravel-native client for Model Context Protocol (MCP) servers
Built and maintained by Redberry, a Diamond-tier official Laravel partner.

AI PoC Sprint

🚀 What is This?

This package provides a Laravel-native client for interacting with Model Context Protocol (MCP) servers — enabling your Laravel application to communicate with external tools, structured resources, and memory services in a standardized way.

It is framework-agnostic and can be used in any Laravel application. Agent frameworks like LarAgent use this package internally to enable tool use, memory management, and reasoning across distributed contexts.

Use it to:

Connect to any MCP-compliant server over HTTP or STDIO
Discover and call tools defined on MCP servers
Access structured memory and contextual resources
Extend your Laravel apps with AI-ready interfaces to external agents or toolchains

🚀 Looking to build an AI agent in Laravel? Talk to us about our 5-week PoC sprint — from idea to working prototype.

Installation

Note that while project is running with php artisan serve STDIO transporter doesn't work

You can install the package via composer:

composer require redberry/mcp-client-laravel

After installation, publish the configuration file:

php artisan vendor:publish --tag="mcp-client-config"

This will create a config/mcp-client.php file in your application.

Configuration

The published configuration file contains settings for your MCP servers. Here's an example configuration:

return [
    'servers' => [
        'github' => [
            'type' => \Redberry\MCPClient\Enums\Transporters::HTTP,
            'base_url' => 'https://api.githubcopilot.com/mcp',
            'timeout' => 30,
            'token' => env('GITHUB_API_TOKEN', null),
        ],
        'npx_mcp_server' => [
            'type' => \Redberry\MCPClient\Enums\Transporters::STDIO,
            'command' => [
                'npx',
                '-y',
                '@modelcontextprotocol/server-memory',
            ],
            'timeout' => 30,
            'cwd' => base_path(),
        ],
    ],
];

Configuration Options

HTTP Transporter

type: Set to Redberry\MCPClient\Enums\Transporters::HTTP for HTTP connections
base_url: The base URL of the MCP server
timeout: Request timeout in seconds
token: Authentication token (if required)

STDIO Transporter

type: Set to Redberry\MCPClient\Enums\Transporters::STDIO for STDIO connections
command: Array of command parts to execute the MCP server
timeout: Command timeout in seconds
cwd: Current working directory for the command

Usage

Basic Usage

use Redberry\MCPClient\Facades\MCPClient;

// Connect to a specific MCP server defined in your config
$client = MCPClient::connect('github');

// Get available tools from the MCP server
$tools = $client->tools();

// Get available resources from the MCP server
$resources = $client->resources();

Using Dependency Injection

use Redberry\MCPClient\MCPClient;

class MyService
{
    public function __construct(private MCPClient $mcpClient)
    {
    }

    public function getToolsFromGithub()
    {
        return $this->mcpClient->connect('github')->tools();
    }
}

Working with Collections

The tools() and resources() methods return a Collection object that provides helpful methods for working with the results:

// Get all tools as an array
$allTools = $client->tools()->all();

// Get only specific tools by name
$specificTools = $client->tools()->only('tool1', 'tool2');

// Exclude specific tools
$filteredTools = $client->tools()->except('tool3');

// Map over tools
$mappedTools = $client->tools()->map(function ($tool) {
    return $tool['name'];
});

Call tools

The callTool method is used to execute specific tool. Here is the signature:

public function callTool(string $toolName, mixed $params = []): mixed;

Example:

$result = $client->callTool('create_entities', [
    'entities' => [
        [
            'name' => 'John Doe',
            'entityType' => 'PERSON',
            'observations' => ['Test observation 1', 'Test observation 2'],
        ]
    ],
]);

Read Resources

The readResource method is used to retrieve the resource by the uri.

public function readResource(string $uri): mixed;

Example:

$result = $client->readResource("file:///project/src/main.rs");

Advanced Usage

Creating Custom Transporters

If you need to create a custom transporter, you can extend the Transporter interface and implement your own transport mechanism. Then register it in the TransporterFactory.

Testing

composer test

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

redberry / mcp-client-laravel

Maintainers

Details