MCP PHP SDK

The MCP Client SDK provides a synchronous, framework-agnostic API for PHP applications to communicate with MCP servers. It manages connection lifecycles, request/response correlation, server-initiated requests (sampling), and real-time notifications.

Key features include:

• Connection management via Transports.
• Synchronous API for tools, resources, and prompts.
• Support for server-initiated communication (sampling and notifications).
• Progress notification support for long-running operations.

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

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

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

// Connect and use the server
$client->connect($transport);
$tools = $client->listTools();
$client->disconnect();

If you use PHP attributes like #[McpTool], #[McpResource], #[McpResourceTemplate], or #[McpPrompt] to define your server elements, you must configure discovery using setDiscovery() so the server knows where to scan for them.

Parameters:

• $basePath (string): The base directory for discovery (typically __DIR__).
• $scanDirs (array): Directories to recursively scan. Defaults to ['.', 'src'].
• $excludeDirs (array): Directory names to skip during the recursive scan.
• $cache (CacheInterface|null): An optional PSR-16 cache to store discovered elements. Highly recommended for production to avoid filesystem scanning on every startup.
• $namePatterns (array): File name patterns to match (e.g., ['*.php']).

// Production setup with caching
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', 'lib'],
        excludeDirs: ['vendor', 'tests', 'temp'],
        cache: $cache
    )
    ->build();

The SDK supports three ways to register capabilities (Tools, Resources, Prompts) on a server:

1. Attribute-Based Discovery: Use #[McpTool] and #[McpResource] attributes on class methods. Use setDiscovery(path, directories) on the builder to enable this.
2. Manual Registration: Use the builder methods addTool() and addResource() to register specific class methods programmatically.
3. Hybrid Approach: Combine attribute discovery with manual registration for specific external services.

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

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

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

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

The SDK dispatches four main protocol-level events that allow you to observe or modify server operations:

RequestEvent

Dispatched: When a request is received, before processing.

• getRequest(): Request: Get the incoming request.
• setRequest(Request $request): void: Modify the request before it reaches handlers.
• getMethod(): string: Get the request method.
• getSession(): SessionInterface: Get the current session.

ResponseEvent

Dispatched: When a successful response is ready, after handler execution.

• getResponse(): Response: Get the response being sent.
• setResponse(Response $response): void: Modify the response before sending.
• getMethod(): string: Get the request method.
• getSession(): SessionInterface: Get the current session.

ErrorEvent

Dispatched: When an error occurs during request processing.

• getError(): Error: Get the error being sent.
• setError(Error $error): void: Modify the error before sending.
• getThrowable(): ?\Throwable: Get the exception that caused the error.
• getRequest(): ?Request: Get the original request (null for parse errors).
• getSession(): SessionInterface: Get the current session.

NotificationEvent

Dispatched: When a notification is received, before processing.

• getNotification(): Notification: Get the incoming notification.
• setNotification(Notification $notification): void: Modify the notification before processing.
• getMethod(): string: Get the notification method.
• getSession(): SessionInterface: Get the current session.

Custom message handlers are a low-level escape hatch that allow you to intercept and process individual JSON-RPC messages before the SDK's built-in handlers.

Warning: Custom handlers bypass discovery and manual capability registration. Tools and resources registered via the builder will not be visible unless your custom handler manually loads them.

Request Handlers

Used for messages with an id that expect a response (e.g., tools/call).

• Interface: Mcp\Server\Handler\Request\RequestHandlerInterface
• Methods: supports(Request $request): bool and handle(Request $request, SessionInterface $session): Response|Error
• Requirement: Must return a Response or Error object.

Notification Handlers

Used for messages without an id (fire-and-forget) (e.g., notifications/initialized).

• Interface: Mcp\Server\Handler\Notification\NotificationHandlerInterface
• Methods: supports(Notification $notification): bool and handle(Notification $notification, SessionInterface $session): void
• Requirement: Must return void.

// Request Handler Example
use Mcp\Schema\JsonRpc\Response;
use Mcp\Schema\JsonRpc\Request;
use Mcp\Server\Handler\Request\RequestHandlerInterface;
use Mcp\Server\Session\SessionInterface;

class CustomListToolsHandler implements RequestHandlerInterface
{
    public function supports(Request $request): bool
    {
        return $request->getMethod() === 'tools/list';
    }

    public function handle(Request $request, SessionInterface $session): Response|Error
    {
        // Implementation logic
    }
}

// Attaching to the builder
$server = Server::builder()
    ->addRequestHandler(new CustomListToolsHandler())
    ->build();

The SDK automatically generates JSON schemas for tool parameters using a priority system. This allows you to define validation rules for your MCP tools using PHP attributes. The system follows a specific order of precedence:

1. #[Schema] attribute with definition: A complete schema override (highest priority).
2. Parameter-level #[Schema] attribute: Enhances specific parameters.
3. Method-level #[Schema] attribute: Configures the entire method.
4. PHP type hints + docblocks: Automatic inference (lowest priority).

Use automatic inference for simple types, parameter-level attributes for constraints like format or minimum, and method-level attributes for complex object structures.

use Mcp\
use Mcp\Capability\Attribute\Schema;

#[McpTool]
public function validateUser(
    #[Schema(format: 'email')]
    string $email,
    
    #[Schema(minimum: 18, maximum: 120)]
    int $age,
    
    #[Schema(
        pattern: '^[A-Z][a-z]+$',
        description: 'Capitalized first name'
    )]
    string $firstName
): bool
{
    // PHP types provide base validation
    // Schema attributes add constraints
}

Elicitation allows a server to request interactive user input during tool execution.

Requirements:

• The client must support elicitation (check via $context->getClientGateway()->supportsElicitation()).
• A session store (e.g., FileSessionStore) must be configured to persist the request.

Workflow:

1. Build an ElicitationSchema defining the required fields (string, number, boolean, enum).
2. Call $client->elicit() with a message and the schema.
3. Handle the result using $result->isAccepted(), $result->isDeclined(), or $result->isCancelled().

// 1. Check support
if (!$context->getClientGateway()->supportsElicitation()) {
    return ['status' => 'error', 'message' => 'Client does not support elicitation'];
}

// 2. Build schema
$schema = new ElicitationSchema(
    properties: [
        'party_size' => new NumberSchemaDefinition(
            title: 'Party Size',
            integerOnly: true,
            minimum: 1,
            maximum: 20
        ),
        'date' => new StringSchemaDefinition(
            title: 'Reservation Date',
            format: 'date'
        ),
        'dietary' => new EnumSchemaDefinition(
            title: 'Dietary Restrictions',
            enum: ['none', 'vegetarian', 'vegan'],
            enumNames: ['None', 'Vegetarian', 'Vegan']
        ),
    ],
    required: ['party_size', 'date']
);

// 3. Send request
$result = $client->elicit(
    message: 'Please provide your reservation details',
    requestedSchema: $schema
);

// 4. Handle response
if ($result->isAccepted()) {
    $data = $result->content; // User-provided data
} elseif ($result->isDeclined() || $result->isCancelled()) {
    // Handle decline/cancel
}