README

A PHP implementation of the Model Context Protocol (MCP) specification. This SDK enables PHP applications to seamlessly integrate with LLM applications by providing contextual information, tools, and prompts through a standardized interface.

MCP PHP SDK

Overview

The Model Context Protocol allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction. This PHP SDK implements the full MCP specification (2025-03-26), making it easy to:

Diagram created with GitDiagram

Build MCP clients that can connect to any MCP server
Create MCP servers that expose resources, prompts, and tools
Use standard transports like stdio with proper message framing
Handle all MCP protocol messages and lifecycle events
Robust error handling with standardized JSON-RPC error responses
Advanced resource management with URI templates and dynamic content
Complete prompts system for reusable LLM interaction patterns
Production-ready features including error recovery, logging, and validation

Installation

composer require eduardocruz/mcp-php-sdk

Note: Requires PHP 8.1 or higher.

Quick Start

Let's create a simple MCP server that exposes a calculator tool and a dynamic resource:

<?php

require_once 'vendor/autoload.php';

use ModelContextProtocol\Server\McpServer;
use ModelContextProtocol\Transport\StdioTransport;
use ModelContextProtocol\Protocol\Resources\ResourceTemplate;

// Create an MCP server
$server = new McpServer('Demo', '1.0.0');

// Add an addition tool
$server->registerTool('add', [
    'properties' => [
        'a' => ['type' => 'number'],
        'b' => ['type' => 'number']
    ],
    'required' => ['a', 'b']
], function(array $params) {
    $a = $params['a'];
    $b = $params['b'];
    
    return [
        'content' => [
            [
                'type' => 'text',
                'text' => (string)($a + $b)
            ]
        ]
    ];
});

// Add a dynamic greeting resource
$template = new ResourceTemplate('greeting://{name}');
$server->registerResourceTemplate('personalized-greeting', $template, function($uri, $params) {
    return [
        'content' => [
            [
                'type' => 'text',
                'text' => "Hello, {$params['name']}!"
            ]
        ]
    ];
});

// Add a prompt for generating introductions
$server->registerPrompt('introduction', [
    'properties' => [
        'name' => ['type' => 'string'],
        'profession' => ['type' => 'string']
    ],
    'required' => ['name', 'profession']
], function(array $params) {
    return [
        'messages' => [
            [
                'role' => 'user',
                'content' => [
                    'type' => 'text',
                    'text' => "Please introduce {$params['name']}, who works as a {$params['profession']}."
                ]
            ]
        ]
    ];
});

// Start the server using stdio transport
$transport = new StdioTransport();
$server->connect($transport);

What is MCP?

The Model Context Protocol (MCP) lets you build servers that expose data and functionality to LLM applications in a secure, standardized way. Think of it like a web API, but specifically designed for LLM interactions. MCP servers can:

Expose data through Resources (like GET endpoints; they provide information to the LLM's context)
Provide functionality through Tools (like POST endpoints; they execute code or produce side effects)
Define interaction patterns through Prompts (reusable templates for LLM interactions)

Core Concepts

Server

The McpServer is your core interface to the MCP protocol. It handles connection management, protocol compliance, and message routing:

$server = new ModelContextProtocol\Server\McpServer('My App', '1.0.0');

Resources

Resources are how you expose data to LLMs. They're similar to GET endpoints in a REST API - they provide data but shouldn't perform significant computation or have side effects:

// Static resource
$server->registerResource('greeting', 'greeting://hello', [
    [
        'type' => 'text',
        'text' => 'Hello, world!'
    ]
]);

// Dynamic resource with parameters
$template = new ModelContextProtocol\Protocol\Resources\ResourceTemplate('greeting://{name}');
$server->registerResourceTemplate('personalized-greeting', $template, function(string $uri, array $params) {
    return [
        'content' => [
            [
                'type' => 'text',
                'text' => "Hello, {$params['name']}!"
            ]
        ]
    ];
});

Tools

Tools let LLMs take actions through your server. Unlike resources, tools are expected to perform computation and have side effects:

// Simple tool with parameters
$server->registerTool(
    'calculate-bmi',
    [
        'properties' => [
            'weightKg' => ['type' => 'number'],
            'heightM' => ['type' => 'number']
        ],
        'required' => ['weightKg', 'heightM']
    ],
    function(array $params) {
        $weightKg = $params['weightKg'];
        $heightM = $params['heightM'];
        $bmi = $weightKg / ($heightM * $heightM);
        
        return [
            'content' => [
                [
                    'type' => 'text',
                    'text' => (string)$bmi
                ]
            ]
        ];
    }
);

Prompts

Prompts are reusable templates that help LLMs interact with your server effectively:

$server->registerPrompt(
    'introduction',
    [
        'properties' => [
            'name' => ['type' => 'string'],
            'profession' => ['type' => 'string']
        ],
        'required' => ['name', 'profession']
    ],
    function(array $params) {
        return [
            'messages' => [
                [
                    'role' => 'user',
                    'content' => [
                        'type' => 'text',
                        'text' => "Please introduce {$params['name']}, who works as a {$params['profession']}."
                    ]
                ]
            ]
        ];
    }
);

Running Your Server

MCP servers in PHP need to be connected to a transport to communicate with clients.

stdio Transport

For command-line tools and direct integrations:

use ModelContextProtocol\Server\McpServer;
use ModelContextProtocol\Transport\StdioTransport;

$server = new McpServer('example-server', '1.0.0');

// ... set up server resources, tools, and prompts ...

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

Recent Improvements

This SDK has been significantly enhanced with production-ready features:

✅ Standardized Error Handling (EDU-102)

ErrorResponseBuilder: Centralized error response creation with JSON-RPC 2.0 compliance
Error Recovery: Automatic retry mechanisms with exponential backoff and circuit breaker patterns
Enhanced Debugging: Structured error logging with context and stack traces
MCP-Specific Error Codes: Extended error codes (-32001 to -32010) for MCP-specific scenarios

✅ Complete Prompts System (EDU-101)

Full Implementation: Complete prompts registration, listing, and execution
Schema Validation: Parameter validation with detailed error reporting
Integration: Seamlessly integrated with McpServer for production use

✅ Advanced Resource Management (EDU-100)

Resource Templates: Dynamic URI pattern matching with parameter extraction
Static & Dynamic Resources: Support for both static content and computed resources
Full Integration: Complete resource listing, reading, and template support

✅ Enhanced Infrastructure (EDU-98, EDU-99)

Improved Message Handling: Better JSON-RPC message processing and validation
Transport Reliability: Enhanced stdio transport with proper error handling
Session Management: Robust connection and session lifecycle management

Documentation

For more detailed documentation, please refer to the docs folder, which includes:

API Reference: Comprehensive documentation of all classes and methods
Examples: Code examples for common use cases
Guides: Installation and getting started guides
Troubleshooting: Common issues and their solutions

Cursor Integration

This SDK includes a PHPStan MCP Server example that you can connect to Cursor for PHP code analysis. When connected, you can ask Claude to:

Analyze PHP code for errors using PHPStan
Check code quality issues like complexity
Scan for potential security vulnerabilities

Learn more about using the PHPStan MCP Server with Cursor

🚀 Support

If you found MCP PHP SDK helpful, believe in its potential, or simply want to support meaningful open-source contributions, please consider becoming a sponsor. Your support helps sustain continuous improvements, new features, and ongoing maintenance.

Whether you're actively using MCP PHP SDK, exploring its possibilities, or just excited by its mission—your contribution makes a significant difference.

👉 Become a Sponsor

Thank you for empowering open source!

Contributing

We welcome contributions! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

eduardocruz / mcp-php-sdk

Maintainers

Details