README

The official PHP SDK for Model Context Protocol (MCP). It provides a framework-agnostic API for implementing MCP servers and clients in PHP.

This project represents a collaboration between the PHP Foundation and the Symfony project. It adopts development practices and standards from the Symfony project, including Coding Standards and the Backward Compatibility Promise.

Until the first major release, this SDK is considered experimental, please see the roadmap for planned next steps and features.

Installation
Overview
Server SDK
Client SDK
Documentation
External Resources
PHP Libraries Using the MCP SDK
Contributing
Credits
License

Installation

composer require mcp/sdk

Overview

The MCP PHP SDK provides both server and client implementations for the Model Context Protocol, enabling you to:

Build MCP Servers: Expose your PHP application's functionality (tools, resources, prompts) to AI agents
Build MCP Clients: Connect to and interact with MCP servers from your PHP applications

Server SDK

Build MCP servers to expose your PHP application's capabilities to AI agents like Claude, Codex, and others.

Quick Start

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

// Define capabilities using PHP attributes
class CalculatorCapabilities
{
    #[McpTool]
    public function add(int $a, int $b): int
    {
        return $a + $b;
    }

    #[McpResource(uri: 'config://calculator/settings')]
    public function getSettings(): array
    {
        return ['precision' => 2];
    }
}

// Build and run the server
$server = Server::builder()
    ->setServerInfo('Calculator Server', '1.0.0')
    ->setDiscovery(__DIR__, ['.'])  // Auto-discover attributes
    ->build();

$transport = new StdioTransport();
$server->run($transport);

Server Capabilities

Tools: Executable functions that AI agents can call
Resources: Data sources that can be read (files, configs, databases)
Resource Templates: Dynamic resources with URI parameters
Prompts: Pre-defined templates for AI interactions
Server-Initiated Communication: Elicitations, sampling, logging, progress notifications

Registration Methods

There are multiple ways to register your MCP capabilities—choose the approach that best fits your application's architecture:

1. Attribute-Based Discovery — Define capabilities using PHP attributes for automatic discovery:

#[McpTool]
public function generateReport(): string { /* ... */ }

#[McpResource(uri: 'config://app/settings')]
public function getConfig(): array { /* ... */ }

2. Manual Registration — Register capabilities programmatically without attributes:

$server = Server::builder()
    ->addTool([Calculator::class, 'add'], 'add_numbers')
    ->addResource([Config::class, 'get'], 'config://app')
    ->build();

3. Hybrid Approach — Combine both methods for maximum flexibility:

$server = Server::builder()
    ->setDiscovery(__DIR__, ['.'])
    ->addTool([ExternalService::class, 'process'], 'external')
    ->build();

Transports

Choose the transport that matches your deployment environment:

1. STDIO Transport — For command-line integration and local processes:

$transport = new StdioTransport();
$server->run($transport);

2. HTTP Transport — For web-based servers and distributed systems:

$transport = new StreamableHttpTransport($request, $responseFactory, $streamFactory);
$response = $server->run($transport);

Session Management

Configure session storage to maintain state between requests. Choose the backend that fits your infrastructure:

In-Memory (default, suitable for STDIO):

$server = Server::builder()
    ->setSession(ttl: 7200) // 2 hours
    ->build();

File-Based (suitable for single-server HTTP deployments):

$server = Server::builder()
    ->setSession(new FileSessionStore(__DIR__ . '/sessions'))
    ->build();

PSR-16 Cache (for example with Redis for scaled deployments):

$server = Server::builder()
    ->setSession(new Psr16SessionStore(
        cache: new Psr16Cache($redisAdapter),
        prefix: 'mcp-',
        ttl: 3600
    ))
    ->build();

→ Server Documentation

Client SDK

Connect to MCP servers from your PHP applications to access their tools, resources, and prompts.

Quick Start

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

// Build the client
$client = Client::builder()
    ->setClientInfo('My Application', '1.0.0')
    ->setInitTimeout(30)
    ->setRequestTimeout(120)
    ->build();

// Connect to a server
$transport = new StdioTransport(
    command: 'php',
    args: ['/path/to/server.php'],
);

$client->connect($transport);

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

$resources = $client->listResources();
$content = $client->readResource('config://calculator/settings');

$client->disconnect();

Client Capabilities

Tool Calling: List and execute tools from any MCP server
Resource Access: Read static and dynamic resources
Prompt Management: List and retrieve prompt templates
Completion Support: Request argument completion suggestions

Advanced Features

Progress Tracking: Real-time progress during long operations

$result = $client->callTool(
    name: 'process_data',
    arguments: ['dataset' => 'large_file.csv'],
    onProgress: function (float $progress, ?float $total, ?string $message) {
        echo "Progress: {$progress}/{$total} - {$message}\n";
    }
);

Sampling Support: Handle server LLM sampling requests

$samplingHandler = new SamplingRequestHandler($myCallback);
$client = Client::builder()
    ->setCapabilities(new ClientCapabilities(sampling: true))
    ->addRequestHandler($samplingHandler)
    ->build();

Logging Notifications: Receive server log messages

$loggingHandler = new LoggingNotificationHandler($myCallback);
$client = Client::builder()
    ->addNotificationHandler($loggingHandler)
    ->build();

Transports

Connect to MCP servers using the transport that matches your setup:

1. STDIO Transport — Connect to local server processes:

$transport = new StdioTransport(
    command: 'php',
    args: ['/path/to/server.php'],
);

$client->connect($transport);

2. HTTP Transport — Connect to remote or web-based servers:

$transport = new HttpTransport('http://localhost:8000');

$client->connect($transport);

→ Client Documentation

Documentation

Core Concepts

Server Builder — Complete ServerBuilder reference and configuration
Client — Client SDK for connecting to and communicating with MCP servers
Transports — STDIO and HTTP transport setup and usage
MCP Elements — Creating tools, resources, prompts, and templates
Server-Client Communication — Sampling, logging, progress, and notifications
Events — Hooking into server lifecycle with events

Learning & Examples

Examples — Comprehensive example walkthroughs for servers and clients
ROADMAP.md — Planned features and development roadmap

External Resources

Model Context Protocol Documentation — Official MCP documentation
Model Context Protocol Specification — Protocol specification
Officially Supported Servers — Reference server implementations

PHP Libraries Using the MCP SDK

pronskiy/mcp — Additional developer experience layer
symfony/mcp-bundle — Symfony integration bundle
josbeir/cakephp-synapse — CakePHP integration plugin

Contributing

We are passionate about supporting contributors of all levels of experience and would love to see you get involved in the project.

See the Contributing Guide to get started before you report issues and send pull requests.

Credits

The starting point for this SDK was the PHP-MCP project, initiated by Kyrian Obikwelu, and the Symfony AI initiative. We are grateful for the work done by both projects and their contributors, which created a solid foundation for this SDK.

License

This project is licensed under the Apache License, Version 2.0 for new contributions, with existing code under the MIT License — see the LICENSE file for details.

mcp / sdk

Maintainers

Package info

Statistics

Security

README

Table of Contents

Installation

Overview

Server SDK

Quick Start

Server Capabilities

Registration Methods

Transports

Session Management

Client SDK

Quick Start

Client Capabilities

Advanced Features

Transports

Documentation

Core Concepts

Learning & Examples

External Resources

PHP Libraries Using the MCP SDK

Contributing

Credits

License