Nexus MCP SDK

Important

Pre-v1.0.0. Through 0.x the project ships the single umbrella package nexusphp/mcp, and minor releases may carry breaking changes until 1.0.0. Both transports, stdio and Streamable HTTP, are implemented on both sides.

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 over a transport.

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 SDK runs on AMPHP and Revolt. Its synchronous-looking API is driven by fibers under the hood.

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

See Getting started for the client side and a full walkthrough.

Documentation

• 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 (handshake, 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, dispatch kernel, spec-compliance notes.
• Design rationale: why the SDK is shaped this way.
• Feature index: every MCP feature mapped to its documentation, including what the 2026-07-28 revision removed and why.
• API reference: the generated class-level reference for the public Nexus\Mcp\ API, published to GitHub Pages.
• 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. Please read CONTRIBUTING.md and the Code of Conduct. To report a security issue, see SECURITY.md.

License

Released under the MIT License.