MCP PHP SDK

HeaderAwareTransportInterface extends TransportInterface

A transport whose messages carry headers the protocol gets to fill in.

From 2026-07-28 an HTTP client mirrors parts of the body into request headers so intermediaries can route without parsing it (SEP-2243), and declares the revision it is speaking on every POST (SEP-2575). Deriving those needs the message, which the protocol has and the transport only sees encoded — hence a callback rather than a setter: the transport asks about the exact payload it is about to write, so the two can never drift apart.

Separate from TransportInterface because it is meaningless over stdio, and because an existing transport must keep working without it.

Tags
author

Christopher Hertel mail@christopher-hertel.de

Table of Contents

Constants

CONNECTION_LOST  : mixed = 'connectionLost'
Error data key marking an error the transport filed because the connection is gone.
REDIRECTED  : mixed = 'redirected'
Error data key marking an error the transport filed because the server answered with a redirect.
RESPONSE_TOO_LARGE  : mixed = 'responseTooLarge'
Error data key marking an error the transport filed because a response body is over its limit.

Methods

close()  : void
Close the transport and clean up resources.
connect()  : void
Connect to the MCP server and perform initialization handshake.
onClose()  : void
Register callback for when connection closes.
onError()  : void
Register callback for transport errors.
onHeaders()  : void
Register the source of per-message headers.
onInitialize()  : void
Register callback for initialization handshake.
onMessage()  : void
Register callback for incoming messages from server.
runRequest()  : Response<string|int, array<string, mixed>>|Error
Run a request fiber to completion.
send()  : void
Send a message to the server immediately.
setState()  : void
Set the client state for runtime state management.

Constants

CONNECTION_LOST

Error data key marking an error the transport filed because the connection is gone.

public mixed CONNECTION_LOST = 'connectionLost'

REDIRECTED

Error data key marking an error the transport filed because the server answered with a redirect.

public mixed REDIRECTED = 'redirected'

RESPONSE_TOO_LARGE

Error data key marking an error the transport filed because a response body is over its limit.

public mixed RESPONSE_TOO_LARGE = 'responseTooLarge'

Methods

connect()

Connect to the MCP server and perform initialization handshake.

public connect() : void

This method blocks until:

  • Initialization completes successfully
  • Connection fails (throws ConnectionException)
Tags
throws
ConnectionException

onClose()

Register callback for when connection closes.

public onClose(callable(string $reason): void $callback) : void
Parameters
$callback : callable(string $reason): void

onError()

Register callback for transport errors.

public onError(callable(Throwable $error): void $callback) : void
Parameters
$callback : callable(Throwable $error): void

onHeaders()

Register the source of per-message headers.

public onHeaders(callable(string $payload): array<string, string> $callback) : void
Parameters
$callback : callable(string $payload): array<string, string>

receives the encoded message

onInitialize()

Register callback for initialization handshake.

public onInitialize(callable(): mixed $callback) : void

The callback should return a Fiber that performs the initialization.

Parameters
$callback : callable(): mixed

onMessage()

Register callback for incoming messages from server.

public onMessage(callable(string $message): void $callback) : void
Parameters
$callback : callable(string $message): void

runRequest()

Run a request fiber to completion.

public runRequest(McpFiber $fiber[, callable(float $progress, Array $total, Array $message): void|null $onProgress = null ]) : Response<string|int, array<string, mixed>>|Error

The transport starts the fiber, runs its internal loop, and resumes the fiber when a response arrives or timeout occurs.

Parameters
$fiber : McpFiber

The fiber to execute

$onProgress : callable(float $progress, Array $total, Array $message): void|null = null

Unused: the protocol delivers progress as it is parsed

Return values
Response<string|int, array<string, mixed>>|Error —

The response or error

send()

Send a message to the server immediately.

public send(string $data) : void
Parameters
$data : string

JSON-encoded message

On this page

Search results