MCP PHP SDK

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

Important

This SDK is currently in active development with ongoing refinement of its architecture and features. While functional, the API may experience changes as we work toward stabilization.

If you want to help us stabilize the SDK, please see the issue tracker.

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.

Roadmap

Features

• Stabilize server component with all needed handlers and functional tests
• Extend documentation, including integration guides for popular frameworks
• Implement Client component
• Support multiple schema versions

Installation

composer require mcp/sdk

Quick Start

This example demonstrates the most common usage pattern - a STDIO server using attribute discovery.

1. Define Your MCP Elements

Create a class with MCP capabilities using attributes:

<?php

namespace App;

use Mcp\Capability\Attribute\McpTool;
use Mcp\Capability\Attribute\McpResource;

class CalculatorElements
{
    /**
     * Adds two numbers together.
     * 
     * @param int $a The first number
     * @param int $b The second number
     * @return int The sum of the two numbers
     */
    #[McpTool]
    public function add(int $a, int $b): int
    {
        return $a + $b;
    }

    /**
     * Performs basic arithmetic operations.
     */
    #[McpTool(name: 'calculate')]
    public function calculate(float $a, float $b, string $operation): float|string
    {
        return match($operation) {
            'add' => $a + $b,
            'subtract' => $a - $b,
            'multiply' => $a * $b,
            'divide' => $b != 0 ? $a / $b : 'Error: Division by zero',
            default => 'Error: Unknown operation'
        };
    }

    #[McpResource(
        uri: 'config://calculator/settings',
        name: 'calculator_config',
        mimeType: 'application/json'
    )]
    public function getSettings(): array
    {
        return ['precision' => 2, 'allow_negative' => true];
    }
}

2. Create the Server Script

Create your MCP server:

#!/usr/bin/env php
<?php

declare(strict_types=1);

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

use Mcp\Server;
use Mcp\Server\Transport\StdioTransport;

$server = Server::builder()
    ->setServerInfo('Calculator Server', '1.0.0')
    ->setDiscovery(__DIR__, ['.'])
    ->build();

$transport = new StdioTransport();

$server->run($transport);

3. Configure Your MCP Client

Add to your client configuration (e.g., Claude Desktop's mcp.json):

{
    "mcpServers": {
        "php-calculator": {
            "command": "php",
            "args": ["/absolute/path/to/your/server.php"]
        }
    }
}

4. Test Your Server

# Test with MCP Inspector
npx @modelcontextprotocol/inspector php /path/to/server.php

# Your AI assistant can now call:
# - add: Add two integers
# - calculate: Perform arithmetic operations
# - Read config://calculator/settings resource

Key Features

Attribute-Based Discovery

Define MCP elements using PHP attributes with automatic discovery:

// Tool with automatic name and description from method
#[McpTool]
public function generateReport(): string { /* ... */ }

// Tool with custom name
#[McpTool(name: 'custom_name')]
public function myMethod(): string { /* ... */ }

// Resource with URI and metadata
#[McpResource(uri: 'config://app/settings', mimeType: 'application/json')]
public function getConfig(): array { /* ... */ }

Manual Registration

Register capabilities programmatically:

$server = Server::builder()
    ->addTool([MyClass::class, 'myMethod'], 'tool_name')
    ->addResource([MyClass::class, 'getData'], 'data://config')
    ->build();

Multiple Transport Options

STDIO Transport (Command-line integration):

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

HTTP Transport (Web-based communication):

$transport = new StreamableHttpTransport($request, $responseFactory, $streamFactory);
$response = $server->run($transport);
// Handle $response in your web application

Session Management

By default, the SDK uses in-memory sessions. You can configure different session stores:

use Mcp\Server\Session\FileSessionStore;
use Mcp\Server\Session\InMemorySessionStore;
use Mcp\Server\Session\Psr16SessionStore;
use Symfony\Component\Cache\Psr16Cache;
use Symfony\Component\Cache\Adapter\RedisAdapter;

// Use default in-memory sessions with custom TTL
$server = Server::builder()
    ->setSession(ttl: 7200) // 2 hours
    ->build();

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

// Override with in-memory storage and custom TTL
$server = Server::builder()
    ->setSession(new InMemorySessionStore(3600))
    ->build();

// Override with PSR-16 cache-based storage
// Requires psr/simple-cache and symfony/cache (or any other PSR-16 implementation)
// composer require psr/simple-cache symfony/cache
$redisAdapter = new RedisAdapter(
    RedisAdapter::createConnection('redis://localhost:6379'),
    'mcp_sessions'
);

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

Discovery Caching

Use any PSR-16 cache implementation to cache discovery results and avoid running discovery on every server start:

use Symfony\Component\Cache\Adapter\FilesystemAdapter;
use Symfony\Component\Cache\Psr16Cache;

$cache = new Psr16Cache(new FilesystemAdapter('mcp-discovery'));

$server = Server::builder()
    ->setDiscovery(
        basePath: __DIR__,
        scanDirs: ['.', 'src'],      // Default: ['.', 'src']
        excludeDirs: ['vendor'],     // Default: ['vendor', 'node_modules']
        cache: $cache
    )
    ->build();

Documentation

Core Concepts:

• Server Builder - Complete ServerBuilder reference and configuration
• Transports - STDIO and HTTP transport setup and usage
• MCP Elements - Creating tools, resources, and prompts
• Client Communication - Communicating back to the client from server-side
• Events - Hooking into server lifecycle with events

Learning:

• Examples - Comprehensive example walkthroughs

External Resources:

• Model Context Protocol documentation
• Model Context Protocol specification
• Officially supported servers

PHP Libraries Using the MCP SDK

• pronskiy/mcp - Additional DX 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.