MCP PHP SDK

HttpTransport extends BaseTransport implements HeaderAwareTransportInterface

HTTP-based client transport using PSR-18 HTTP client.

PSR-18 HTTP clients are auto-discovered if not provided.

Tags
phpstan-import-type

McpFiber from TransportInterface

author

Kyrian Obikwelu koshnawaza@gmail.com

Table of Contents

Interfaces

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

Constants

DEFAULT_MAX_SSE_BUFFER_BYTES  : mixed = 8 * 1024 * 1024
Default cap on the bytes buffered while waiting for a complete SSE event.

Properties

$closeCallback  : callable(string): void|null
$errorCallback  : callable(Throwable): void|null
$initializeCallback  : callable(): mixed|null
$logger  : LoggerInterface
$messageCallback  : callable(string): void|null
$state  : ClientStateInterface|null
$activeFiber  : McpFiber|null
$activeProgressCallback  : callable(float, Array, Array): void|null
$activeStream  : StreamInterface|null
$endpoint  : string
$headerCallback  : callable(string): array<string, string>|null
$headers  : array<string|int, mixed>
$httpClient  : ClientInterface
$maxSseBufferBytes  : int
$requestFactory  : RequestFactoryInterface
$sessionId  : string|null
$sseBuffer  : string
$streamFactory  : StreamFactoryInterface

Methods

__construct()  : mixed
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.
handleClose()  : void
Handle connection close.
handleError()  : void
Handle a transport error.
handleInitialize()  : mixed
Perform initialization via the registered callback.
handleMessage()  : void
Handle an incoming message from the server.
abortSseStream()  : void
Tear down the active SSE stream and fail any in-flight request.
extractSSEEvent()  : string|null
Take the next complete event off the buffer, or null if none is complete yet.
processFiber()  : void
processProgress()  : void
Process pending progress updates from session and execute callback.
processSSEEvent()  : void
Parse a single SSE event and handle the message.
processSSEStream()  : void
Read SSE data incrementally from active stream.
protocolHeaders()  : array<string, string>
tick()  : void

Constants

DEFAULT_MAX_SSE_BUFFER_BYTES

Default cap on the bytes buffered while waiting for a complete SSE event.

public mixed DEFAULT_MAX_SSE_BUFFER_BYTES = 8 * 1024 * 1024

Properties

$closeCallback

protected callable(string): void|null $closeCallback

$errorCallback

protected callable(Throwable): void|null $errorCallback

$initializeCallback

protected callable(): mixed|null $initializeCallback

$messageCallback

protected callable(string): void|null $messageCallback

$activeProgressCallback

private callable(float, Array, Array): void|null $activeProgressCallback

$activeStream

private StreamInterface|null $activeStream = null

Active SSE stream being read

$headerCallback

private callable(string): array<string, string>|null $headerCallback

$headers read-only

private array<string|int, mixed> $headers = []

$requestFactory

private RequestFactoryInterface $requestFactory

$sseBuffer

private string $sseBuffer = ''

Buffer for incomplete SSE data

$streamFactory

private StreamFactoryInterface $streamFactory

Methods

__construct()

public __construct(string $endpoint[, array<string, string> $headers = [] ][, ClientInterface|null $httpClient = null ][, RequestFactoryInterface|null $requestFactory = null ][, StreamFactoryInterface|null $streamFactory = null ][, LoggerInterface|null $logger = null ][, int $maxSseBufferBytes = self::DEFAULT_MAX_SSE_BUFFER_BYTES ]) : mixed
Parameters
$endpoint : string

The MCP server endpoint URL

$headers : array<string, string> = []

Additional headers to send

$httpClient : ClientInterface|null = null

PSR-18 HTTP client (auto-discovered if null)

$requestFactory : RequestFactoryInterface|null = null

PSR-17 request factory (auto-discovered if null)

$streamFactory : StreamFactoryInterface|null = null

PSR-17 stream factory (auto-discovered if null)

$logger : LoggerInterface|null = null
$maxSseBufferBytes : int = self::DEFAULT_MAX_SSE_BUFFER_BYTES

Maximum bytes buffered while waiting for a complete SSE event. A server that never sends the "\n\n" event delimiter would otherwise grow the buffer without bound and exhaust client memory; reaching the cap aborts the stream instead. Raise it for servers that legitimately emit single events larger than the default.

close()

Close the transport and clean up resources.

public close() : void

connect()

Connect to the MCP server and perform initialization handshake.

public connect() : void

This method blocks until:

  • Initialization completes successfully
  • Connection fails (throws ConnectionException)

onClose()

Register callback for when connection closes.

public onClose(callable $listener) : void
Parameters
$listener : callable

onError()

Register callback for transport errors.

public onError(callable $listener) : void
Parameters
$listener : callable

onHeaders()

Register the source of per-message headers.

public onHeaders(callable $callback) : void
Parameters
$callback : callable

receives the encoded message

onInitialize()

Register callback for initialization handshake.

public onInitialize(callable $listener) : void

The callback should return a Fiber that performs the initialization.

Parameters
$listener : callable

onMessage()

Register callback for incoming messages from server.

public onMessage(callable $listener) : void
Parameters
$listener : callable

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
Parameters
$fiber : McpFiber
$onProgress : callable(float $progress, Array $total, Array $message): void|null = null
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

handleClose()

Handle connection close.

protected handleClose(string $reason) : void
Parameters
$reason : string

handleError()

Handle a transport error.

protected handleError(Throwable $error) : void
Parameters
$error : Throwable

handleInitialize()

Perform initialization via the registered callback.

protected handleInitialize() : mixed
Tags
throws
RuntimeException

If no initialize listener is registered

Return values
mixed —

The result from the initialization callback

handleMessage()

Handle an incoming message from the server.

protected handleMessage(string $message) : void
Parameters
$message : string

abortSseStream()

Tear down the active SSE stream and fail any in-flight request.

private abortSseStream(string $reason) : void

The waiting fiber is resolved with an error immediately so the caller fails fast, rather than spinning until the request timeout elapses.

Parameters
$reason : string

extractSSEEvent()

Take the next complete event off the buffer, or null if none is complete yet.

private extractSSEEvent() : string|null

Per the SSE specification, lines are terminated by CRLF, LF or CR, so an event is delimited by any pair of those. Servers built on sse-starlette (the MCP Python SDK) use CRLF.

Return values
string|null

processProgress()

Process pending progress updates from session and execute callback.

private processProgress() : void

processSSEEvent()

Parse a single SSE event and handle the message.

private processSSEEvent(string $event) : void
Parameters
$event : string

processSSEStream()

Read SSE data incrementally from active stream.

private processSSEStream() : void

protocolHeaders()

private protocolHeaders(string $payload) : array<string, string>
Parameters
$payload : string
Return values
array<string, string>
On this page

Search results