README

A PHP SDK for the Model Context Protocol (MCP), tracking spec revision 2026-07-28. It provides both sides of an MCP session: a server for exposing tools, resources, and prompts, and a client for connecting to MCP servers, each over stdio or Streamable HTTP.

This SDK is architected independently of the official PHP MCP SDK. See ROADMAP.md for direction and what is queued next.

Requirements

PHP 8.3 or newer
Composer

Installation

composer require nexusphp/mcp

The umbrella package carries everything. Each layer is also its own package, cut from this repository as a read-only subtree mirror and tagged in lockstep, with 1.0.0 as the first tagged version on Packagist:

Package	Contents
`nexusphp/mcp-core`	Schema types, the JSON-RPC envelope, the transport contract, and the dispatch kernel
`nexusphp/mcp-server`	`ServerBuilder`, `Server`, both server transports, and the resource-server side of OAuth. Requires `mcp-core`
`nexusphp/mcp-client`	`ClientBuilder`, `Client`, both client transports, and the OAuth client. Requires `mcp-core`
`nexusphp/mcp-extensions`	Tasks, MCP Apps, and the OAuth extension grants, both halves of each. Requires `mcp-server` and `mcp-client`

Report issues and open pull requests here, never on a mirror.

The SDK runs on AMPHP and Revolt. Its synchronous-looking API is driven by fibers.

Quickstart

A minimal stdio server exposing one tool:

<?php

declare(strict_types=1);

require __DIR__.'/vendor/autoload.php';

use Nexus\Mcp\Core\Schema\ContentBlock\TextContent;
use Nexus\Mcp\Core\Schema\Result\CallToolResult;
use Nexus\Mcp\Core\Schema\Tool\Tool;
use Nexus\Mcp\Server\ServerBuilder;
use Nexus\Mcp\Server\ServerContext;
use Nexus\Mcp\Server\Transport\StdioServerTransport;

$server = (new ServerBuilder())
    ->setServerInfo(name: 'hello', version: '0.1.0')
    ->addTool(
        tool: new Tool(
            name: 'greet',
            inputSchema: [
                'type' => 'object',
                'properties' => ['name' => ['type' => 'string']],
                'required' => ['name'],
            ],
            description: 'Greets the named person.',
        ),
        executor: static function (?array $args, ServerContext $context): CallToolResult {
            $name = is_string($args['name'] ?? null) ? $args['name'] : 'stranger';

            return new CallToolResult(content: [new TextContent(text: sprintf('Hello, %s!', $name))]);
        },
    )
    ->build()
;

$server->run(new StdioServerTransport());

Run it through MCP Inspector:

npx @modelcontextprotocol/inspector php hello.php

The client ships in the same package. This spawns the server above and calls its tool:

<?php

declare(strict_types=1);

require __DIR__.'/vendor/autoload.php';

use Nexus\Mcp\Client\ClientBuilder;
use Nexus\Mcp\Client\Transport\StdioClientTransport;
use Nexus\Mcp\Core\Schema\ContentBlock\TextContent;
use Nexus\Mcp\Core\Schema\Result\CallToolResult;

$client = (new ClientBuilder())
    ->setClientInfo(name: 'hello-client', version: '0.1.0')
    ->build()
;

$client->connect(new StdioClientTransport(command: [PHP_BINARY, __DIR__.'/hello.php']));

try {
    $client->discover();

    $result = $client->callTool(name: 'greet', arguments: ['name' => 'Ada']);

    if ($result instanceof CallToolResult) {
        foreach ($result->content as $block) {
            if ($block instanceof TextContent) {
                echo $block->text, PHP_EOL;
            }
        }
    }
} finally {
    $client->disconnect();
}

See Getting started for the full walkthrough.

Documentation

The guides are published at https://nexusphp.github.io/mcp/, with the API reference under /api/. The docs index maps every page. The entry points:

Getting started: install plus a minimal server and client.
Server API: ServerBuilder reference (tools, prompts, resources, completions, handlers).
Attribute discovery: declare features with #[AsTool], #[AsServer], and friends, registered via ServerBuilder::register().
Client API: ClientBuilder and Client reference (server/discover, typed requests, streaming progress).
Transports: the stdio and Streamable HTTP transports, the PSR-15 middleware stack that secures the HTTP endpoint, and the in-memory paired transport.
Authorization: the OAuth 2.1 client and resource-server halves.
Error handling: the exception model and JSON-RPC error codes.
Best practices: conventions the SDK is shaped to reward.
Architecture: layering and the dispatch kernel.
Spec compliance: coverage against the targeted revision, and the deliberate omissions.
Design rationale: why the SDK is shaped this way.
API reference: the generated class-level reference for the public Nexus\Mcp\ API, published under /api/ of the docs site and tracking the 1.x development branch.
Examples: runnable demo server and client.

Development

composer update          # install dependencies
composer test:all        # full gate suite (style, static analysis, docs, tests, mutation)
composer test:unit       # unit tests only
composer cs:fix          # fix code style
composer phpstan:check   # static analysis (PHPStan level 10)

See CONTRIBUTING.md for the full workflow.

Contributing

Contributions are welcome. Read CONTRIBUTING.md and the Code of Conduct. To report a security issue, see SECURITY.md.

License

Released under the MIT License.

nexusphp / mcp

Package info

Security

Fund package maintenance!

Statistics