Content
# Model Context Protocol SDK for PHP
[](https://github.com/logiscape/mcp-sdk-php/actions/workflows/ci.yml)
[](https://github.com/logiscape/mcp-sdk-php/actions/workflows/conformance.yml)
This package provides a PHP implementation of the [Model Context Protocol](https://modelcontextprotocol.io). The primary goal of this project is to provide both an MCP server and an MCP client using pure PHP, making it easy to use in PHP/Apache/cPanel hosting environments with typical server configurations.
## Overview
This PHP SDK implements the full MCP specification, making it easy to:
* Build MCP clients that can connect to any MCP server
* Create MCP servers that expose resources, prompts and tools
* Use standard transports like stdio and HTTP
This SDK offers two major advantages for the MCP and PHP developer communities:
* This SDK features a 100% pass rate on the applicable required [MCP Conformance Tests](https://github.com/modelcontextprotocol/conformance) as of testing suite v0.1.16 and aims to maintain full conformance as the spec and tests evolve, not including tests still marked as experimental or optional extensions.
* The SDK can demonstrate both a functional MCP client and MCP server with a single Composer command. See the [Webclient Example](webclient/README.md).
## Installation
You can install the package via composer:
```bash
composer require logiscape/mcp-sdk-php
```
### Requirements
* PHP 8.1 or higher
* ext-curl
* ext-json
* ext-pcntl (optional, recommended for CLI environments)
* monolog/monolog (optional, used by example clients/servers for logging)
## Basic Usage
### Creating an MCP Server
For detailed documentation and examples of MCP servers, see the [Server Development Guide](docs/server-dev.md).
Here's a complete example of an MCP server that provides a simple tool:
```php
<?php
// An example server with a basic addition tool
require 'vendor/autoload.php';
use Mcp\Server\McpServer;
$server = new McpServer('example-mcp-server');
$server
// Define a tool
->tool('add-numbers', 'Adds two numbers together', function (float $a, float $b): string {
return 'Sum: ' . ($a + $b);
})
// Start the server
->run();
```
Save this as `example_server.php`
### Creating an MCP Client
For detailed documentation and examples of MCP clients, see the [Client Development Guide](docs/client-dev.md).
Here's how to create a client that connects to the example server and calls the addition tool:
```php
<?php
// A basic example client that connects to example_server.php and calls a tool
require 'vendor/autoload.php';
use Mcp\Client\Client;
$client = new Client();
try {
// Connect to the server over stdio
$session = $client->connect('php', ['example_server.php']);
// Call the add-numbers tool with two arguments
$result = $session->callTool('add-numbers', ['a' => 5, 'b' => 25]);
// Output the result
echo $result->content[0]->text . "\n";
} catch (\Exception $e) {
echo "Error: " . $e->getMessage() . "\n";
exit(1);
} finally {
$client->close();
}
```
Save this as `example_client.php` and run it:
```bash
php example_client.php
```
## Advanced Examples
The "examples" directory includes additional clients and servers for both the STDIO and HTTP transports. All examples are designed to run in the same directory where you installed the SDK.
Some examples use monolog for logging, which can be installed via composer:
```bash
composer require monolog/monolog
```
## MCP Web Client
The "webclient" directory includes a web-based application for testing MCP servers. It was designed to demonstrate an MCP client capable of running in a typical web hosting environment.
### Setting Up The Web Client
To setup the web client, upload the contents of "webclient" to a web directory, such as public_html on a cPanel server. Ensure that the MCP SDK for PHP is installed in that same directory by running the Composer command found in the Installation section of this README.
### Using The Web Client
Once the web client has been uploaded to a web directory, navigate to index.php to open the interface. To connect to the included MCP test server, enter `php` in the Command field and `test_server.php` in the Arguments field and click `Connect to Server`. The interface allows you to test Prompts, Tools, and Resources. There is also a Debug Panel allowing you to view the JSON-RPC messages being sent between the Client and Server.
### Web Client Notes And Limitations
This MCP Web Client is intended for developers to test MCP servers, and it is not recommended to be made publicly accessible as a web interface without additional testing for security, error handling, and resource management.
## OAuth Authorization
The HTTP server transport includes optional OAuth 2.1 support. For more details see the [OAuth Authentication Example](examples/server_auth/README.md).
## Documentation
For detailed information about the Model Context Protocol itself, visit the [official documentation](https://modelcontextprotocol.io).
Project-specific documentation lives in this repository:
| Document | Purpose |
| --- | --- |
| [Server Development Guide](docs/server-dev.md) | Building MCP servers with `McpServer`. |
| [Testing Guide](docs/testing.md) | Unit tests, PHPStan, conformance, MCP Inspector, Claude Code, OpenAI. |
| [Compatibility Guide](docs/compatibility.md) | cPanel / Apache / PHP-FPM notes and graceful-degradation rules. |
| [Dependency Policy](docs/dependency-policy.md) | How dependencies are declared, bumped, and retired. |
| [Label Scheme](docs/labels.md) | Issue labels aligned with the MCP SDK Working Group conventions. |
| [Conformance Testing](conformance/README.md) | How the conformance harness works and the no-shortcut rule. |
Project governance and process:
| Document | Purpose |
| --- | --- |
| [CONTRIBUTING](CONTRIBUTING.md) | Local development setup, test stack, coding standards, versioning policy. |
| [ROADMAP](ROADMAP.md) | Direction, tier self-assessment against SEP-1730, and what we're working on. |
| [CHANGELOG](CHANGELOG.md) | Structured release history. |
| [SECURITY](SECURITY.md) | How to report vulnerabilities. |
| [GOVERNANCE](GOVERNANCE.md) | How decisions are made and how to become a trusted contributor. |
| [SUPPORT](SUPPORT.md) | Where to ask questions. |
| [CODE_OF_CONDUCT](CODE_OF_CONDUCT.md) | Adopts Contributor Covenant 2.1 by reference; summarises the key sections. |
## Project Status
This SDK tracks the latest MCP specification revision (currently `2025-11-25`) and runs the full [official conformance suite](https://github.com/modelcontextprotocol/conformance) in CI. At the time of writing, 100% of the applicable required tests pass against suite `v0.1.16`; known failures are limited to optional MCP Extensions and are documented in [`conformance/conformance-baseline.yml`](conformance/conformance-baseline.yml).
This is a community-maintained SDK. See [ROADMAP.md](ROADMAP.md) for a candid self-assessment against the [SDK tier criteria](https://modelcontextprotocol.io/community/sdk-tiers) and [GOVERNANCE.md](GOVERNANCE.md) for how the project is maintained.
Release history is captured in [CHANGELOG.md](CHANGELOG.md); what is shipping next is tracked under its `[Unreleased]` heading.
## Credits
This PHP SDK was developed by:
- [Josh Abbott](https://joshabbott.com)
- Claude 3.5 Sonnet
- Claude Opus 4.5
Additional debugging and refactoring done by Josh Abbott using OpenAI ChatGPT o1 pro mode and OpenAI Codex.
Special acknowledgement to [Roman Pronskiy](https://github.com/pronskiy) for simplifying the server building process with his convenience wrapper project: [https://github.com/pronskiy/mcp](https://github.com/pronskiy/mcp)
- `Mcp\Server\McpServer` — adapted from `Pronskiy\Mcp\Server`
- `Mcp\Server\McpServerException` — adapted from `Pronskiy\Mcp\McpServerException`
## License
The MIT License (MIT). Please see [License File](LICENSE) for more information.
