README

Important

Pre-v1.0.0. Through 0.x the project ships the single umbrella package nexusphp/mcp-sdk, and minor releases may carry breaking changes until 1.0.0. The stdio transport is implemented. Streamable HTTP lands with the 2026-07-28 migration.

A PHP SDK for the Model Context Protocol (MCP), tracking spec revision 2025-11-25. 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 the path to the 2026-07-28 spec migration.

Requirements

PHP 8.4 or newer
Composer

Installation

composer require nexusphp/mcp-sdk

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([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 transport and the in-memory paired transport.
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.
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.

nexusphp / mcp-sdk

Maintainers

Package info

Statistics

Security