php-mcp/server

The server automatically generates JSON schemas for tool parameters using a priority system. These schemas are used for both input validation and providing information to MCP clients. The priority order is:

1. #[Schema(definition: [...])] (Highest precedence - complete override)
2. Parameter-level #[Schema] (Enhancements to specific parameters)
3. Method-level #[Schema] (Configuration for the entire method)
4. PHP type hints + docblocks (Lowest precedence - automatic inference)

Use parameter-level attributes to add constraints like format, pattern, minimum, or maximum to existing PHP types.

use PhpMcp\​Server​Attributes\\{McpTool, Schema};

#[McpTool(name: 'validate_user')]
public function validateUser(
    #[Schema(format: 'email')]              // Enhances string type
    string $email,
    
    #[Schema(
        pattern: '^[A-Z][a-z]+$',
        description: 'Capitalized name'
    )]
    string $name,
    
    #[Schema(minimum: 18, maximum: 120)]    // Enhances integer type
    int $age
): bool {
    return filter_var($email, FILTER_VALIDATE_EMAIL) !== false;
}

The StreamableHttpServerTransport is the recommended transport for production, remote servers, and multiple clients. It supports resumable connections and enhanced session management.

Key Configuration Options:

• host: The server host (Note: 0.0.0.0 is prohibited by the MCP protocol; use a specific IP like 127.0.0.1).
• port: The port number.
• mcpPathPrefix: The URL prefix (e.g., mcp).
• enableJsonResponse: If true, returns immediate JSON responses instead of SSE streams. Use this for fast-executing tools.
• stateless: If true, enables stateless mode where each request is independent and session IDs are not exposed to clients.
• withCache($cache): Required for resumability features.

Client Configuration Example:

{
    "mcpServers": {
        "my-http-server": {
            "url": "http://localhost:8080/mcp/sse"
        }
    }
}

use PhpMcp\\Server\\Transports\\StreamableHttpServerTransport;

$server = Server::make()
    ->withServerInfo('Streamable Server', '1.0.0')
    ->withLogger($logger)
    ->withCache($cache) // Required for resumability
    ->build();

$server->discover(__DIR__, ['src']);

$transport = new StreamableHttpServerTransport(
    host: '127.0.0.1',
    port: 8080,
    mcpPathPrefix: 'mcp',
    enableJsonResponse: false, // Use SSE streaming
    stateless: false
);

$server->listen($transport);

For dynamic registration, closures, or explicit control, use the ServerBuilder methods before calling build(). Manual registrations take precedence over discovered elements with the same identifier.

Supported Handler Formats:

• [ClassName::class, 'methodName']: Class method handlers.
• InvokableClass::class: Classes with an __invoke method.
• callable: Closures, static methods, or function names.

Note on Closures: When using closures, the server generates minimal JSON schemas based only on PHP type hints. For detailed schemas, use the #[Schema] attribute or provide a custom $inputSchema in withTool().

use App\​Handlers\\EmailHandler;
use PhpMcp\\Schema\\ToolAnnotations;

$server = Server::make()
    ->withServerInfo('Manual Registration Server', '1.0.0')
    
    // Register a tool with a class method
    ->withTool(
        [EmailHandler::class, 'sendEmail'],
        name: 'send_email',
        description: 'Send email to user',
        annotations: ToolAnnotations::make(title: 'Send Email Tool')
    )
    
    // Register an invokable class
    ->withTool(UserHandler::class)
    
    // Register a closure
    ->withTool(
        function(int $a, int $b): int { return $a + $b; },
        name: 'add_numbers'
    )
    
    // Register a resource with a closure
    ->withResource(
        function(): array { return ['status' => 'ok']; },
        uri: 'config://runtime/status'
    )
    
    // Register a resource template
    ->withResourceTemplate(
        [UserHandler::class, 'getUserProfile'],
        uriTemplate: 'user://{userId}/profile'
    )
    
    // Register a prompt with a closure
    ->withPrompt(
        function(string $topic): array {
            return [['role' => 'user', 'content' => "Write about {$topic}"]];
        },
        name: 'writing_prompt'
    )
    ->build();

You can define MCP elements by marking methods or classes with PHP 8 attributes. The server will automatically discover these via filesystem scanning. This is the recommended approach for most use cases.

Supported element types:

• Tools (#[McpTool]): Executable functions/actions.
• Resources (#[McpResource]): Static content/data accessible via a URI.
• Resource Templates (#[McpResourceTemplate]): Dynamic resources with URI patterns (e.g., user://{id}/profile).
• Prompts (#[McpPrompt]): Conversation starters or templates.

use PhpMcp\​Server\Attributes\\{McpTool, McpResource, McpResourceTemplate, McpPrompt};

class UserManager
{
    #[McpTool(name: 'create_user')]
    public function createUser(string $email, string $password, string $role = 'user'): array
    {
        return ['id' => 123, 'email' => $email, 'role' => $role];
    }

    #[McpResource(uri: 'config://user/settings', mimeType: 'application/json')]
    public function getUserConfig(): array
    {
        return ['theme' => 'dark'];
    }

    #[McpResourceTemplate(uriTemplate: 'user://{userId}/profile', mimeType: 'application/json')]
    public function getUserProfile(string $userId): array
    {
        return ['id' => $userId, 'name' => 'John Doe'];
    }

    #[McpPrompt(name: 'welcome_user')]
    public function welcomeUserPrompt(string $username, string $role): array
    {
        return [
            ['role' => 'user', 'content' => "Create a welcome message for {$username} with role {$role"]
        ];
    }
}

MCP element handlers can use constructor dependency injection. To use it, you must provide a PSR-11 compatible container to the server via withContainer().

• BasicContainer: The default implementation. It attempts to auto-wire dependencies by instantiating classes with parameterless constructors. You can manually add dependencies using $container->set(ClassName::class, $instance).
• Advanced Containers: You can use any PSR-11 container like PHP-DI or Laravel's container for more complex dependency management.

use PhpMcp// ...

// Option 1: Use the basic container and manually add dependencies
$basicContainer = new \PhpMcp\Server\Defaults\BasicContainer();
$basicContainer->set(\PDO::class, new \PDO('sqlite::memory:'));

// Option 2: Use any PSR-11 compatible container
$container = new \DI\Container();
$container->set(\PDO::class, new \PDO('mysql:host=localhost;dbname=app', $user, $pass));

$server = Server::make()
    ->withContainer($container)
    ->build();