mcp-client

# Model Context Protocol client implementation for PHP [](https://packagist.org/packages/swisnl/mcp-client) [](https://packagist.org/packages/swisnl/mcp-client) [](LICENSE.md) [](https://plant.treeware.earth/swisnl/mcp-client) [](https://github.com/swisnl/mcp-client/actions/workflows/run-tests.yml) [](https://www.swis.nl) A PHP client library for interacting with Model Context Protocol (MCP) servers. ## Installation You can install the package via composer: ```bash composer require swisnl/mcp-client ``` ## Requirements - PHP 8.2 or higher - [ReactPHP](https://reactphp.org/) 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 ```php 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 ```php 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 ```php 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 ```bash composer require swisnl/agents-sdk ``` ```php 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: ```php 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`: ```php 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: ```php $client->sendRequest(new ListToolsRequest())->then(...); ``` ## Changelog Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. ## Contributing Please see [CONTRIBUTING](https://github.com/spatie/.github/blob/main/CONTRIBUTING.md) for details. ## Security Vulnerabilities Please review [our security policy](../../security/policy) on how to report security vulnerabilities. ## Credits - [Joris Meijer](https://github.com/jormeijer) - [All Contributors](../../contributors) ## License This package is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT). This package is [Treeware](https://treeware.earth). If you use it in production, then we ask that you [**buy the world a tree**](https://plant.treeware.earth/swisnl/mcp-client) 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](https://www.swis.nl) is a web agency from Leiden, the Netherlands. We love working with open source software.