A PHP client for the Model Context Protocol (MCP). Connects to MCP servers over stdio or HTTP, letting you call tools, read resources, and use prompts from any PHP application.

Protocol version: 2025-11-25

• Two transports — stdio (subprocess) and HTTP (remote server)
• Full MCP support — tools, resources, resource templates, and prompts
• Capability negotiation — automatic handshake with protocol version verification
• Server-initiated messages — handle requests and notifications from the server
• Roots support — respond to roots/list server requests
• Request cancellation — manual and automatic cancellation on timeout
• Pagination — cursor-based pagination for list operations
• Logging — PSR-3 compatible, pass any logger implementation
• Timeouts — configurable per-request timeouts with sensible defaults

• PHP 7.4 or higher
• ext-json
• ext-curl (for HTTP transport)
• proc_open enabled (for stdio transport)

composer require automattic/php-mcp-client

Note: This package depends on wordpress/php-mcp-schema which is loaded from a VCS repository. Add the following to your project's composer.json if it is not already present:

"repositories": [
    {
        "type": "vcs",
        "url": "https://github.com/WordPress/php-mcp-schema"
    }
]

Connect to an MCP server running as a local subprocess:

<?php

use Automattic\PhpMcpClient\Client\ClientCapabilities;
use Automattic\PhpMcpClient\Client\McpClient;
use Automattic\PhpMcpClient\Transport\StdioTransport;

$transport    = new StdioTransport('npx', ['-y', '@modelcontextprotocol/server-filesystem', '/tmp']);
$capabilities = new ClientCapabilities();
$client       = new McpClient($transport, $capabilities);

$client->connect();

// List and call tools
$tools  = $client->listTools();
$result = $client->callTool('read_file', ['path' => '/tmp/example.txt']);

$client->disconnect();

Connect to a remote MCP server over HTTP:

<?php

use Automattic\PhpMcpClient\Client\ClientCapabilities;
use Automattic\PhpMcpClient\Client\McpClient;
use Automattic\PhpMcpClient\Transport\Http\HttpTransport;

$transport = new HttpTransport(
    'https://mcp.example.com/api',
    null,
    null,
    ['Authorization' => 'Bearer your-token']
);

$capabilities = new ClientCapabilities();
$client       = new McpClient($transport, $capabilities);

$client->connect();

$tools = $client->listTools();

$client->disconnect();

• Usage guide — connecting, listing tools/resources/prompts, calling tools, pagination
• Transports — stdio vs HTTP, configuration, custom HTTP clients
• Advanced usage — message handlers, roots, cancellation, error handling, logging

# Stdio transport with the filesystem server
php examples/example-stdio.php npx -y @modelcontextprotocol/server-filesystem /tmp

# HTTP transport
php examples/example-http.php http://localhost:8080/mcp
php examples/example-http.php https://api.example.com/mcp "your-bearer-token"

src/
├── Client/         # McpClient, capabilities, server info
├── Contracts/      # TransportInterface, MessageHandlerInterface, RootsHandlerInterface
├── Exception/      # McpException hierarchy
├── JsonRpc/        # JSON-RPC 2.0 message types
└── Transport/      # Stdio and HTTP transport implementations

The client communicates with MCP servers using JSON-RPC 2.0 messages sent through a transport layer. The transport is pluggable — implement TransportInterface to add custom transports.

composer install          # Install dependencies
composer test             # Run tests
composer phpstan          # Static analysis (level 9)
composer phpcs            # Code style checks

MIT