Model Context Protocol SDK for PHP

Note

This main branch contains the v2 beta of the logiscape/mcp-sdk-php SDK.

v2 adds day-one support for the MCP 2026-07-28 spec revision; upgrading from v1 is covered by the Migration Guide. For the stable v1 code and documentation, see the 1.x branch.

This package provides a PHP implementation of the Model Context Protocol. 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
• Interoperate with peers on any spec revision from 2024-11-05 through 2026-07-28 — version negotiation is built in

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 — the stable-track baseline is empty — and additionally runs the draft-track suite validating the 2026-07-28 release candidate. See Conformance Testing.

• The SDK can demonstrate both a functional MCP client and MCP server with a single Composer command. See the Webclient Example.

New in v2

v2 is built around two headline features — day-one support for the MCP 2026-07-28 "stateless core" spec revision, and full support for the MCP Apps extension — delivered without giving up compatibility with any earlier revision:

• 2026-07-28 stateless core — no initialize handshake, no session ids: every request is self-contained, which is exactly the model that fits typical PHP web hosting (a fresh process per request). Includes server/discover, caching hints, request-metadata headers, subscriptions/listen streams, and multi-round-trip input gathering.
• Dual-era negotiation — servers detect each request's era and clients probe-then-fall-back automatically, so one codebase serves both modern (2026-07-28) and legacy (2024-11-05 … 2025-11-25) peers concurrently.
• Tasks extension (SEP-2663) — long-running tool calls return a task handle that clients poll, cancel, and feed input to; backed by a file-based store that works on shared hosting. See the Tasks guide.
• MCP Apps extension (SEP-1865) — attach a host-rendered HTML UI to a tool with one ->ui(...) call. See the Apps guide.

The complete inventory — including OAuth 2.1 hardening, typed errors, and the feature-lifecycle deprecation registry — is in the CHANGELOG; API differences from v1 are covered in the Migration Guide.

Installation

You can install the v2 beta via composer:

composer require logiscape/mcp-sdk-php:2.0.0-beta3

(Plain composer require logiscape/mcp-sdk-php installs the stable v1 line until v2.0.0 is released.)

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.

Here's a complete example of an MCP server that provides a simple tool:

<?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.

Here's how to create a client that connects to the example server and calls the addition tool:

<?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:

php example_client.php

Examples

The examples/ directory contains a runnable example for every major SDK feature — stateless servers, dual-era client negotiation, Tasks, Apps, elicitation, HTTP clients, and OAuth — each designed to run from the directory where you installed the SDK. Its README doubles as a feature map of the SDK.

Some examples use monolog for logging, which can be installed via composer:

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.

Documentation

For detailed information about the Model Context Protocol itself, visit the official documentation.

Project-specific documentation lives in this repository (see the documentation index for the full annotated list):

Document	Purpose
Server Development Guide	Building MCP servers with McpServer.
Client Development Guide	Building MCP clients with Client / ClientSession.
Migration Guide	Upgrading a project from v1 to v2.
Tasks Extension Guide	Long-running tool calls (SEP-2663), server and client side.
Apps Extension Guide	Host-rendered tool UIs (SEP-1865).
Examples Index	A runnable example per major feature.
Testing Guide	Unit tests, PHPStan, conformance, MCP Inspector, Claude Code, OpenAI.
Compatibility Guide	cPanel / Apache / PHP-FPM notes and graceful-degradation rules.
Dependency Policy	How dependencies are declared, bumped, and retired.
Label Scheme	Issue labels aligned with the MCP SDK Working Group conventions.
Conformance Testing	How the dual-track conformance harness works and the no-shortcut rule.

Project governance and process:

Document	Purpose
CONTRIBUTING	Local development setup, test stack, coding standards, versioning policy.
ROADMAP	Direction, tier self-assessment against SEP-1730, and what we're working on.
CHANGELOG	Structured release history.
SECURITY	How to report vulnerabilities.
GOVERNANCE	How decisions are made and how to become a trusted contributor.
SUPPORT	Where to ask questions.
CODE_OF_CONDUCT	Adopts Contributor Covenant 2.1 by reference; summarises the key sections.

Project Status

This SDK supports the latest MCP specification revision (2026-07-28, the "stateless core") from day one, alongside every earlier revision back to 2024-11-05 — version negotiation and per-request era detection let one server or client interoperate across all of them.

Conformance runs on two tracks in CI: the stable track passes 100% of the applicable required tests with an empty baseline (conformance/conformance-baseline.yml), and the draft track validates the 2026-07-28 release candidate against the upstream RC-validation suite, with the few remaining entries in conformance/conformance-draft-baseline.yml documented as upstream-tool issues. See conformance/README.md for the dual-track rules.

v2 is in beta (latest pre-release: v2.0.0-beta2); the final v2.0.0 is gated on the 2026-07-28 spec's publication and a clean conformance run against the suite current at that date, per the v2 development plan.

This is a community-maintained SDK. See ROADMAP.md for a candid self-assessment against the SDK tier criteria and GOVERNANCE.md for how the project is maintained.

Release history is captured in CHANGELOG.md; what is shipping next is tracked under its [Unreleased] heading.

Credits

This PHP SDK was developed by:

• Josh Abbott
• Claude 3.5 Sonnet
• Claude Opus 4.5
• Claude Fable 5

Code reviews and refactoring done by Josh Abbott originally using OpenAI ChatGPT o1 pro mode, and later by OpenAI Codex using GPT-5.5.

Special acknowledgement to Roman Pronskiy for simplifying the server building process with his convenience wrapper project: 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 for more information.