php-sdk/docs/server-client-communication.md

Client Communication

MCP supports various ways a server can communicate back to a server on top of the main request-response flow.

Table of Contents

• ClientGateway
• Sampling
• Logging
• Notification
• Progress

ClientGateway

Every communication back to client is handled using the Mcp\Server\ClientGateway and its dedicated methods per operation. To use the ClientGateway in your code, you need to use method argument injection for RequestContext.

Every reference of a MCP element, that translates to an actual method call, can just add an type-hinted argument for the RequestContext and the SDK will take care to include the gateway in the arguments of the method call:

use Mcp\Capability\Attribute\McpTool;
use Mcp\Server\RequestContext;

class MyService
{
    #[McpTool(name: 'my_tool', description: 'My Tool Description')]
    public function myTool(RequestContext $context): string
    {
        $context->getClientGateway()->log(...);

Sampling

With sampling servers can request clients to execute "completions" or "generations" with a language model for them:

$result = $clientGateway->sample('Roses are red, violets are', 350, 90, ['temperature' => 0.5]);

The sample method accepts four arguments:

1. message, which is required and accepts a string, an instance of Content or an array of SamplingMessage instances.
2. maxTokens, which defaults to 1000
3. timeout in seconds, which defaults to 120
4. options which might include systemPrompt, preferences for model choice, includeContext, temperature, stopSequences, metadata, tools, and toolChoice

Only send includeContext when the client advertises sampling.context, and only send tools or toolChoice when it advertises sampling.tools. The context modes other than none are soft-deprecated by the current specification.

Find more details to sampling payload in the specification.

Logging

The Logging utility enables servers to send structured log messages as notification to clients:

use Mcp\Schema\Enum\LoggingLevel;

$clientGateway->log(LoggingLevel::Warning, 'The end is near.');

Progress

With a Progress notification a server can update a client while an operation is ongoing:

$clientGateway->progress(4.2, 10, 'Downloading needed images.');

Notification

Lastly, the server can push all kind of notifications, that implement the Mcp\Schema\JsonRpc\Notification interface to the client to:

$clientGateway->notify($yourNotification);