Model Context Protocol client implementation for PHP

A PHP client library for interacting with Model Context Protocol (MCP) servers.

Installation

You can install the package via composer:

composer require swisnl/mcp-client

Requirements

• PHP 8.2 or higher
• ReactPHP packages

Features

• Multiple transport mechanisms:
  • SSE (Server-Sent Events)
  • Stdio (Standard input/output)
  • Process (External process communication)
  • StreamableHttp (HTTP with session management)
• Promise-based API with ReactPHP
• PSR-3 Logger interface support
• Most of MCP protocol support (2025-03-26)
• Tool annotation support

Basic Usage

SSE Transport

use Swis\McpClient\Client;

// Create client with SSE transporter
$endpoint = 'https://your-mcp-server.com/sse';
$client = Client::withSse($endpoint);

// Connect to the server
$client->connect(function($initResponse) {
    echo "Connected to server: " . json_encode($initResponse['serverInfo']) . "\n";
});

// List available tools
$tools = $client->listTools();
foreach ($tools->getTools() as $tool) {
    echo "- {$tool->getName()}: {$tool->getDescription()}\n";
    
    // Access tool annotations if available
    if ($annotations = $tool->getAnnotations()) {
        echo "  * Read-only: " . ($annotations->getReadOnlyHint() ? 'Yes' : 'No') . "\n";
        echo "  * Title: " . ($annotations->getTitle() ?? 'N/A') . "\n";
    }
}

// Call a tool
$result = $client->callTool('echo', ['message' => 'Hello World!']);
echo $result->getResult() . "\n";

Process Transport

use Swis\McpClient\Client;

// Create client with a process transporter
[$client, $process] = Client::withProcess('/path/to/mcp-server/binary');

// Connect to the server
$client->connect();

// Use the client...

// Disconnect when done
$client->disconnect();

StreamableHttp Transport

use Swis\McpClient\Client;

// Create client with StreamableHttp transporter
$endpoint = 'https://your-mcp-server.com/';
$client = Client::withStreamableHttp($endpoint);

// Connect to the server
$client->connect();

// The transporter will automatically manage session IDs from the Mcp-Session-Id header

// Use the client...

// Disconnect when done
$client->disconnect();

Use in combination with Agents SDK

First, install Agents SDK

composer require swisnl/agents-sdk

use Swis\Agents\Agent;
use Swis\Agents\Mcp\McpConnection;
use Swis\McpClient\Client;
use Swis\Agents\Orchestrator;

$agent = new Agent(
    name: 'Calculator Agent',
    description: 'This Agent can perform arithmetic operations.',
    mcpConnections: [
        new MathMcpConnection(),
    ]
);

$orchestrator = new Orchestrator($agent);
echo $orchestrator
        ->withUserInstruction('What\'s 5 + 5?')
        ->run($agent)

class MathMcpConnection extends McpConnection
{
    public function __construct()
    {
        [$client, $process] = Client::withProcess(
            command: 'node ' . realpath(__DIR__ . '/node_modules/math-mcp/build/index.js'),
        );

        parent::__construct(
            client: $client,
            name: 'Math MCP',
        );
    }
}

Advanced Usage

Custom Transporter

You can implement your own transporter by implementing the TransporterInterface:

use Swis\McpClient\TransporterInterface;
use Swis\McpClient\EventDispatcher;

class CustomTransporter implements TransporterInterface
{
    // Implement required methods
}

// Create a client with your custom transporter
$transporter = new CustomTransporter();
$eventDispatcher = new EventDispatcher();
$client = new Client($transporter, $eventDispatcher);

Async Operations

The client supports async operations using ReactPHP promises:

$client->sendRequest(new ListToolsRequest())->then(...);

License

This package is open-sourced software licensed under the MIT license.

This package is Treeware. If you use it in production, then we ask that you buy the world a tree to thank us for our work. By contributing to the Treeware forest you’ll be creating employment for local families and restoring wildlife habitats.