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
• _meta 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,
    headers: ['Authorization' => 'Bearer your-token']
);

// 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,
    headers: ['Authorization' => 'Bearer your-token']
);

// 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

Metadata

You can send metadata using the _meta parameter:

use Swis\McpClient\Requests\CallToolRequest

$request = new CallToolRequest('search');
$request->withMeta(['traceparent' => '0000-0000-00-00x']);

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(...);

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

• Joris Meijer
• All Contributors

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.

SWIS :heart: Open Source

SWIS is a web agency from Leiden, the Netherlands. We love working with open source software.