MCP PHP SDK: building Model Context Protocol servers and clients in PHP

What the MCP PHP SDK actually solves for PHP applications

Model Context Protocol defines how an assistant discovers and calls tools, reads resources, and uses prompts from a server. Until an SDK exists in your language, that means writing JSON-RPC framing, capability negotiation, session handling and transport plumbing by hand. This package removes that work for PHP: the README describes it as "a framework-agnostic API for implementing MCP servers and clients in PHP", covering tools, resources, prompts, STDIO and HTTP transports, sessions, authorization, and both protocol eras.

The audience is narrow and identifiable. It is PHP developers who want an existing application's behaviour reachable by an MCP client, and PHP developers who want to build a client that consumes other MCP servers. The README lists integrations from API Platform, Drupal, CakePHP, Kirby, Nette and Symfony, which tells you the intended shape: a framework or CMS exposes what it already knows, and the SDK handles the protocol conversation.

It is not a general-purpose RPC library and not a replacement for your application's own HTTP API. The protocol is the point. If your consumers are ordinary HTTP clients rather than MCP-capable assistants, this adds a layer you do not need.

Attributes, discovery and two protocol eras

The mechanism is attribute-driven discovery. You write an ordinary PHP class, mark methods with `#[McpTool]` or `#[McpResource]`, and the server builder scans a directory for them. The README's server example is exactly this: a `Calculator` class with an `add` method and a `settings` method, wired up with `setServerInfo`, `setDiscovery` and `run`.

That discovery step is the design decision worth noticing. Registration is by convention over a filesystem scan, with `excludeDirs: ['vendor']` in the example, so the scan does not walk your dependencies. Method parameters become the tool's input schema, and the return value becomes the result. The docblock above `add` supplies the description. Nothing here is a configuration file; the class is the configuration.

The second design decision is protocol era support. The README names two: the `initialize` handshake and the stateless `2026-07-28` revision. The conformance table tracks both `2026-07-28` and `2025-11-25` for server and client, and the README notes the `2026-07-28` scores run against the conformance framework's `alpha` releases, so those numbers move as upstream publishes new scenarios. Treat the badge as a moving measurement, not a fixed grade.

Transports are separate from all of this. `StdioTransport` runs a server over standard input and output; the README points to `docs/run/index.md` for HTTP transports, sessions and authorization, and to `docs/client/connecting.md` for client transports, timeouts and handlers that answer server-initiated requests. The handler side is where most real work lands, and it has its own documentation section.

Installing the SDK and running a first server

Installation is one Composer command. It pulls `mcp/sdk` from Packagist, and the current release line at the time of writing is v0.8.1, published on 2026-08-29.

composer require mcp/sdk

A minimal server is a class plus a builder call. The README's example defines a tool and a resource on the same class, then hands the builder a directory to scan:

use Mcp\Capability\Attribute\McpResource;
use Mcp\Capability\Attribute\McpTool;
use Mcp\Server;
use Mcp\Server\Transport\StdioTransport;

class Calculator
{
    #[McpTool]
    public function add(int $a, int $b): int
    {
        return $a + $b;
    }
}

exit(Server::builder()
    ->setServerInfo('Calculator', '1.0.0')
    ->setDiscovery(__DIR__, ['.'], excludeDirs: ['vendor'])
    ->build()
    ->run(new StdioTransport()));

Running that file over STDIO starts the server. It will sit waiting for messages on standard input rather than printing a banner, which is expected for a STDIO transport. The README points to `docs/get-started/first-server.md` for a walkthrough of each piece and to `docs/get-started/inspector.md` for seeing it run in the Inspector. Use the Inspector first; a server that appears to hang is usually just waiting for a client.

The client side mirrors it. The README connects to a server by spawning a PHP process and then lists and calls tools:

use Mcp\Client;
use Mcp\Client\Transport\StdioTransport;

$client = Client::builder()
    ->setClientInfo('My Application', '1.0.0')
    ->build();

$client->connect(new StdioTransport(command: 'php', args: ['/path/to/server.php']));

$tools = $client->listTools();
$result = $client->callTool('add', ['a' => 5, 'b' => 3]);

$client->disconnect();

If you want to run the project's own checks locally, the Makefile exposes targets for coding standards, static analysis and tests, including `make unit-tests`, `make integration-tests` and `make conformance-server`. The Makefile pins the conformance tool to `0.2.0-alpha.11` and notes it is pinned to the same version CI runs.

Where the SDK is the wrong choice

The README states the project is considered experimental until the first major release, and links to the Symfony experimental policy and to ROADMAP.md for planned next steps. That is the headline limitation, and it is a real one: the SDK adopts the Symfony Backward Compatibility Promise, but the experimental designation means the surface can still move before 1.0. If you are shipping something that must not break on a minor upgrade, this is a reason to wait or to pin hard.

There is a second limitation that is less about the project and more about the platform. STDIO transport means the server is a child process talking over standard input and output. Long-running background work, shared in-process state across requests, and anything that assumes a persistent worker do not map cleanly onto that model. The README points to HTTP transports as the alternative, and to `docs/run/index.md` for sessions and authorization, so the answer exists, but it is a different deployment shape with its own concerns.

Finally, the conformance picture has a caveat the README states directly: the `2026-07-28` scores run against the conformance framework's `alpha` releases. A score can change because upstream added scenarios, not because the SDK changed. Reading the badge as a stable quality number would be a mistake.

How this differs from the official TypeScript and Python SDKs

The Model Context Protocol project publishes SDKs in several languages, and the README links to the official MCP documentation and specification rather than positioning this one against the others. The difference in approach is mostly environmental. The TypeScript and Python SDKs sit in ecosystems where an MCP server is typically a standalone process or a small service; this one is built to be embedded in a PHP application that already has a request lifecycle, a DI container and a framework.

That shows up in the integration list. `symfony/mcp-bundle`, `drupal/mcp_server`, `api-platform/mcp` and `josbeir/cakephp-synapse` are not standalone servers; they are bridges that expose an existing application's configuration and entities as MCP elements. If your tooling lives in a PHP CMS or framework, no other SDK reaches it without a translation layer. If your tooling lives in Node or Python, this SDK offers nothing that those do not, and you would be adding a PHP runtime for no reason.

The other difference is governance. The README describes the project as a collaboration between the PHP Foundation and the Symfony project, and says it adopts Symfony's coding standards and backward compatibility promise. If you already follow Symfony's release discipline, the upgrade expectations will feel familiar.

Maintenance, licensing and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-08. Recent releases are close together: v0.7.1 on 2026-08-14, v0.8.0 on 2026-08-25, v0.8.1 on 2026-08-29. That cadence on a pre-1.0 package is the practical upgrade cost. Minor versions are where behaviour changes land, so pinning to a patch range and reading CHANGELOG.md before moving is the sensible posture.

The project ships the machinery to make upgrades checkable. CI runs coding standards, PHPStan with a baseline file, PHPUnit suites split into unit, integration and inspector, and a weekly conformance workflow. The Makefile wraps all of it, so you can reproduce the pipeline locally before upgrading rather than discovering a break in production. The conformance targets need Docker, since `conformance-server` starts a fixture with `docker compose` before running the suite.

On licensing, the repository's licence field is reported as NOASSERTION, meaning the machine-readable metadata does not resolve to a standard SPDX identifier. A `LICENSE` file exists at the repository root and Packagist renders a licence badge for the package. Read that file yourself before you depend on the terms; the metadata alone does not tell you what they are, and nothing here should be read as legal advice.

Editorial conclusion

Adopt it if you already run PHP and want your application's functions exposed to MCP clients without a second language in the stack, and accept the experimental label the README attaches until the first major release. Do not adopt it if you need a stable API surface today, or if your handlers are long-running jobs where PHP's execution model gets in the way. Verify two things before committing: which protocol revision your target clients negotiate (the initialize handshake or the stateless 2026-07-28 revision), and whether the capability you need is listed in ROADMAP.md as planned rather than shipped.

Frequently asked questions

Official sources

1. Issues
2. modelcontextprotocol/php-sdk on GitHub
3. Project website
4. README
5. Releases