Automatic Content Wrapping

// Primitive types → TextContent
public function getString(): string { return "Hello"; }           // TextContent
public function getNumber(): int { return 42; }                  // TextContent  
public function getBool(): bool { return true; }                 // TextContent
public function getArray(): array { return ['key' => 'value']; } // TextContent (JSON)

// Special cases
public function getNull(): ?string { return null; }              // TextContent("(null)")
public function returnVoid(): void { /* no return */ }           // Empty content

Explicit Content Types

For fine control over output formatting:

use Mcp\Schema\Content\{TextContent, ImageContent, AudioContent, EmbeddedResource};

public function getFormattedCode(): TextContent
{
    return TextContent::code('<?php echo "Hello";', 'php');
}

public function getMarkdown(): TextContent  
{
    return new TextContent('# Title\n\nMarkdown content');
}

public function getImage(): ImageContent
{
    return new ImageContent(
        data: base64_encode(file_get_contents('image.png')),
        mimeType: 'image/png'
    );
}

public function getAudio(): AudioContent
{
    return new AudioContent(
        data: base64_encode(file_get_contents('audio.mp3')),
        mimeType: 'audio/mpeg'
    );
}

public function getEmbeddedResource(): EmbeddedResource
{
    return new EmbeddedResource(
        type: 'resource',
        resource: ['uri' => 'file://data.json', 'text' => 'File content']
    );
}

Multiple Content Items

Return an array of content items:

public function getMultipleContent(): array
{
    return [
        new TextContent('Here is the analysis:'),
        TextContent::code($code, 'php'),
        new TextContent('And here is the summary.')
    ];
}

Error Handling

Tool handlers can throw any exception, but the type determines how it's handled:

• ToolCallException : Converted to JSON-RPC response with CallToolResult where isError: true , allowing the LLM to see the error message and self-correct
• Any other exception : Converted to JSON-RPC error response, but with a generic error message

use Mcp\Exception\ToolCallException;

#[McpTool]
public function divideNumbers(float $a, float $b): float
{
    if ($b === 0.0) {
        throw new ToolCallException('Division by zero is not allowed');
    }

    return $a / $b;
}

#[McpTool]
public function processFile(string $filename): string
{
    if (!file_exists($filename)) {
        throw new ToolCallException("File not found: {$filename}");
    }

    return file_get_contents($filename);
}

Recommendation : Use ToolCallException when you want to communicate specific errors to clients. Any other exception will still be converted to JSON-RPC compliant errors but with generic error messages.

Supported Return Types

// String content - converted to text resource
public function getTextFile(): string 
{
    return "File content here";
}

// Array content - converted to JSON
public function getConfig(): array 
{
    return ['debug' => true, 'version' => '1.0'];
}

// Stream resource - read and converted to blob
public function getImageStream(): resource
{
    return fopen('image.png', 'r');
}

// SplFileInfo - file content with MIME type detection
public function getFileInfo(): \SplFileInfo
{
    return new \SplFileInfo('document.pdf');
}

Explicit resource content types

use Mcp\Schema\Content\{TextResourceContents, BlobResourceContents};

public function getExplicitText(): TextResourceContents
{
    return new TextResourceContents(
        uri: 'config://app/settings',
        mimeType: 'application/json',
        text: json_encode(['setting' => 'value'])
    );
}

public function getExplicitBlob(): BlobResourceContents
{
    return new BlobResourceContents(
        uri: 'file://image.png',
        mimeType: 'image/png',
        blob: base64_encode(file_get_contents('image.png'))
    );
}

Special Array Formats

// Array with 'text' key - used as text content
public function getTextArray(): array
{
    return ['text' => 'Content here', 'mimeType' => 'text/plain'];
}

// Array with 'blob' key - used as blob content  
public function getBlobArray(): array
{
    return ['blob' => base64_encode($data), 'mimeType' => 'image/png'];
}

// Multiple resource contents
public function getMultipleResources(): array
{
    return [
        new TextResourceContents('file://readme.txt', 'text/plain', 'README content'),
        new TextResourceContents('file://config.json', 'application/json', '{"key": "value"}')
    ];
}

Error Handling

Resource handlers can throw any exception, but the type determines how it's handled:

• ResourceReadException : Converted to JSON-RPC error response with the actual exception message
• Any other exception : Converted to JSON-RPC error response, but with a generic error message

use Mcp\Exception\ResourceReadException;

#[McpResource(uri: 'file://{path}')]
public function getFile(string $path): string
{
    if (!file_exists($path)) {
        throw new ResourceReadException("File not found: {$path}");
    }

    if (!is_readable($path)) {
        throw new ResourceReadException("File not readable: {$path}");
    }

    return file_get_contents($path);
}

Recommendation : Use ResourceReadException when you want to communicate specific errors to clients. Any other exception will still be converted to JSON-RPC compliant errors but with generic error messages.

Supported Return Formats

// Array of message objects with role and content
public function basicPrompt(): array
{
    return [
        ['role' => 'assistant', 'content' => 'You are a helpful assistant'],
        ['role' => 'user', 'content' => 'Hello, how are you?']
    ];
}

// Single message (automatically wrapped in array)
public function singleMessage(): array
{
    return [
        ['role' => 'user', 'content' => 'Write a poem about PHP']
    ];
}

// Associative array with user/assistant keys
public function userAssistantFormat(): array
{
    return [
        'user' => 'Explain how arrays work in PHP',
        'assistant' => 'Arrays in PHP are ordered maps...'
    ];
}

// Mixed content types in messages
use Mcp\Schema\Content\{TextContent, ImageContent};

public function mixedContent(): array
{
    return [
        [
            'role' => 'user', 
            'content' => [
                new TextContent('Analyze this image:'),
                new ImageContent(data: $imageData, mimeType: 'image/png')
            ]
        ]
    ];
}

// Using explicit PromptMessage objects
use Mcp\Schema\PromptMessage;
use Mcp\Schema\Enum\Role;

public function explicitMessages(): array
{
    return [
        new PromptMessage(Role::Assistant, [new TextContent('System instructions')]),
        new PromptMessage(Role::User, [new TextContent('User question')])
    ];
}

The SDK automatically validates that all messages have valid roles and converts the result into the appropriate MCP prompt message format.

Valid Message Roles

• user : User input or questions
• assistant : Assistant responses/system

Error Handling

Prompt handlers can throw any exception, but the type determines how it's handled:

• PromptGetException : Converted to JSON-RPC error response with the actual exception message
• Any other exception : Converted to JSON-RPC error response, but with a generic error message

use Mcp\Exception\PromptGetException;

#[McpPrompt]
public function generatePrompt(string $topic, string $style): array
{
    $validStyles = ['casual', 'formal', 'technical'];

    if (!in_array($style, $validStyles)) {
        throw new PromptGetException(
            "Invalid style '{$style}'. Must be one of: " . implode(', ', $validStyles)
        );
    }

    return [
        ['role' => 'user', 'content' => "Write about {$topic} in a {$style} style"]
    ];
}

Recommendation : Use PromptGetException when you want to communicate specific errors to clients. Any other exception will still be converted to JSON-RPC compliant errors but with generic error messages.

1. Value Lists

Provide a static list of possible values:

use Mcp\Capability\Attribute\CompletionProvider;

#[McpPrompt]
public function generateContent(
    #[CompletionProvider(values: ['blog', 'article', 'tutorial', 'guide'])]
    string $contentType,
    
    #[CompletionProvider(values: ['beginner', 'intermediate', 'advanced'])]
    string $difficulty
): array
{
    return [
        ['role' => 'user', 'content' => "Create a {$difficulty} level {$contentType}"]
    ];
}

2. Enum Classes

Use enum values for completion:

enum Priority: string
{
    case LOW = 'low';
    case MEDIUM = 'medium';
    case HIGH = 'high';
}

enum Status  // Unit enum
{
    case DRAFT;
    case PUBLISHED;
    case ARCHIVED;
}

#[McpResourceTemplate(uriTemplate: 'tasks/{taskId}')]
public function getTask(
    string $taskId,
    
    #[CompletionProvider(enum: Priority::class)]  // Uses backing values
    string $priority,
    
    #[CompletionProvider(enum: Status::class)]    // Uses case names
    string $status
): array
{
    // Implementation
}

3. Custom Provider Classes

For dynamic completion logic:

use Mcp\Capability\Prompt\Completion\ProviderInterface;

class UserIdCompletionProvider implements ProviderInterface
{
    public function __construct(private DatabaseService $db) {}

    public function getCompletions(string $currentValue): array
    {
        // Return dynamic completions based on current input
        return $this->db->searchUserIds($currentValue);
    }
}

#[McpResourceTemplate(uriTemplate: 'user://{userId}/profile')]
public function getUserProfile(
    #[CompletionProvider(provider: UserIdCompletionProvider::class)]
    string $userId
): array
{
    // Implementation
}

Provider Resolution:

• Class strings (Provider::class ) → Resolved from PSR-11 container
• Instances (new Provider() ) → Used directly
• Values (['a', 'b'] ) → Wrapped in ListCompletionProvider
• Enums (MyEnum::class ) → Wrapped in EnumCompletionProvider

Important

Completion providers only offer suggestions to users. Users can still input any value, so always validate parameters in your handlers. Providers don't enforce validation - they're purely for UX improvement.