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

Talking back to the client

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

Protocol revision 2026-07-28. This page describes the handshake era, where a server sends its own JSON-RPC requests to the client. The modern lifecycle removed that: sampling, elicitation and roots are carried back inside the result instead, and ClientGateway::sample(), elicit() and listRoots() raise a LogicException there. Logging and progress still work as described below — they simply travel on the request's own response stream, and the client opts into each. See Asking for input.

ClientGateway

Every communication back to client is handled using the Mcp\Server\ClientGateway and its dedicated methods per operation. Reach it through method argument injection for RequestContext. (A ClientGateway-typed parameter is injected too, but unlike RequestContext it is not excluded from the generated input schema, so it would show up as an argument of your tool.)

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(...);

Request metadata

RequestContext also carries what the current request said about itself, which is useful when a feature is only available from a certain revision on:

use Mcp\Schema\Enum\ProtocolVersion;

if ($context->getProtocolVersion()->isAtLeast(ProtocolVersion::V2026_07_28)) {
    // e.g. a bare list is only valid as `structuredContent` from this revision on
}

Two more accessors read what the client declared, and both work in either protocol era — negotiated once during the handshake, or declared per request from 2026-07-28 on:

$context->getClientCapabilities();  // what this client declared, or null in the handshake era
$context->getTraceContext();        // traceparent / tracestate / baggage, verbatim

ClientGateway's capability probes — supportsElicitation(), supportsSampling(), supportsRoots() and the sub-capability variants — read the same declaration.

W3C trace context is passed through exactly as it arrived, and echoed onto every notification the request causes, so a span stays joined across the response stream. Reading it adds no OpenTelemetry dependency — the values are strings.

Sampling

Deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28. Sampling keeps working until then; new integrations should call an LLM provider's API directly instead.

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 Mcp\Schema\Content\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

Both tools/toolChoice and includeContext are gated on what the client advertised, so check before sending:

if ($clientGateway->supportsSamplingTools()) {
    $result = $clientGateway->sample($messages, options: ['tools' => $tools]);
}

A server must not send tools or toolChoice to a client that did not advertise sampling.tools. The includeContext values other than none are soft-deprecated and should only be sent when the client advertises sampling.context — supportsSamplingContext() reports that one.

Tool loops

When the model wants to call a tool, the result comes back with stopReason: 'toolUse' and one or more ToolUseContent blocks. Execute them, then send a follow-up request with the assistant's message and a user message carrying a matching ToolResultContent for every ToolUseContent:

$messages[] = new SamplingMessage(Role::Assistant, $result->content);
$messages[] = new SamplingMessage(Role::User, [new ToolResultContent($toolUse->id, [new TextContent($output)])]);

The specification is strict about the shape of that exchange: tool results may not be mixed with other content in a message, and every tool use must be answered before the conversation continues. sample() checks these rules before sending and throws an InvalidArgumentException rather than letting the client reject the request with -32602. Use $result->getContentBlocks() to iterate the response regardless of whether it holds one block or a list.

Find more details to sampling payload in the specification.

Logging

Deprecated since protocol revision 2026-07-28 (SEP-2577), earliest removal 2027-07-28. Logging keeps working until then; new integrations should log to stderr (stdio) or use OpenTelemetry instead.

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.');

Progress is opt-in by the client in both eras: it sends a progressToken with the request, and without one this call sends nothing.

Notification

Lastly, the server can push all kind of notifications, that extend the abstract Mcp\Schema\JsonRpc\Notification class to the client to:

$clientGateway->notify($yourNotification);